Deploy, scan and interpret with confidence

Chapter 1

Architecture and scope

Spyderz Sense is an AWS EC2 inventory and vulnerability scanner delivered as an AMI. The scanner is launched into your account, uses your IAM controls, reaches targets through AWS Systems Manager, and stores operational data in PostgreSQL on the scanner instance.

What it does

• Discovers EC2 instances and attached security groups across enabled regions.
• Checks whether targets are registered and online in AWS Systems Manager.
• Collects Linux and Windows inventory with non-interactive SSM Run Command jobs.
• Matches operating systems and installed software against CVE and vendor patch data.
• Correlates listening ports with public security-group ingress.
• Stores assets, scans, evidence, users, settings and notifications in local PostgreSQL.
• Exports completed scan evidence as Excel workbooks.

What it does not do

• No exploit execution, credential attack, malware simulation or full file-system scan.
• No central Snakez control plane receives your inventory, findings or reports.
• No SSH, RDP or WinRM login to every target is required.
• No claim that a zero-CVE result proves an asset has no vulnerabilities.

Chapter 2

Subscribe and launch the AMI

Choose the Standard, Advanced or Enterprise offer in AWS Marketplace. The selected tier is part of the delivered AMI and cannot be changed from the web console.

Launch checklist

1. Subscribe to the required Spyderz Sense tier in AWS Marketplace and accept the offer terms.
2. Launch the AMI in the AWS Region that will own the Standard or Advanced license registry.
3. Keep the default gp3 root volume of at least 33 GiB, or increase it for larger scan history.
4. Select an instance size suitable for the fleet. Persistent yellow or red CPU and memory indicators mean the scanner needs more capacity or smaller batches.
5. Attach the scanner instance profile described in the next chapter.
6. Place the scanner in a private subnet when your administration path and outbound design allow it.
7. Allow console access on TCP 443 only from a VPN, bastion path or approved administrator CIDR.
8. Allow TCP 22 only when SSH administration is required, and restrict it to an administrator CIDR.
9. Keep PostgreSQL TCP 5432 closed. It is designed to listen only on localhost.

Chapter 3

IAM permissions and why they are needed

The scanner uses an EC2 instance profile and temporary role credentials. Do not place long-lived AWS access keys in files, environment variables or the database.

Functional baseline for the scanner instance

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "DiscoverAwsInventory",
      "Effect": "Allow",
      "Action": [
        "ec2:DescribeInstances",
        "ec2:DescribeRegions",
        "ec2:DescribeSecurityGroups"
      ],
      "Resource": "*"
    },
    {
      "Sid": "InspectAndScanSsmManagedNodes",
      "Effect": "Allow",
      "Action": [
        "ssm:DescribeInstanceInformation",
        "ssm:SendCommand",
        "ssm:GetCommandInvocation"
      ],
      "Resource": "*"
    },
    {
      "Sid": "ReadAndUpdateLicenseRegistry",
      "Effect": "Allow",
      "Action": [
        "ssm:GetParameter",
        "ssm:PutParameter"
      ],
      "Resource": "arn:aws:ssm:*:*:parameter/scanner/*"
    },
    {
      "Sid": "OptionalRdsSecurityGroupCorrelation",
      "Effect": "Allow",
      "Action": "rds:DescribeDBInstances",
      "Resource": "*"
    }
  ]
}

Permission-by-permission explanation

Why some resources use *

Several AWS Describe and list operations do not support resource-level ARNs, so IAM requires Resource: "*" even though the action is read-only. That does not grant write access. ssm:SendCommand is different: it can be restricted by target tags and SSM document ARNs and should be tightened once the initial deployment works.

Recommended Run Command restrictions

• Allow ssm:SendCommand only to instances tagged Spyderz=Sense.
• Limit allowed documents to the collection documents used by the scanner, such as AWS-RunShellScript and AWS-RunPowerShellScript, or customer-approved restrictive documents when supported.
• Use an IAM permission boundary or AWS Organizations SCP to prevent unrelated write actions.
• Do not grant people permission to assume the scanner role.
• Review CloudTrail records for unexpected Run Command activity.

AWS references: EC2 instance roles and temporary credentials, restricting Run Command by target tags, and Run Command privilege guidance.

Chapter 4

Prepare target instances

Targets do not give Spyderz a username, password, SSH key, domain account or local administrator credential. They participate through SSM Agent and their own target instance role.

Target requirements

1. The EC2 instance is running.
2. SSM Agent is installed and running.
3. The target is registered as an SSM managed node and reports PingStatus=Online.
4. The target instance profile includes AmazonSSMManagedInstanceCore or equivalent permissions.
5. The target can reach regional SSM service endpoints.
6. Standard and Advanced targets carry the exact case-sensitive tag Spyderz=Sense.
7. Linux targets provide python3, ss and their normal package-manager tools.
8. Windows targets support PowerShell and the required CIM and network cmdlets.

Why this is safer than logging in to every asset

This is a safer default for many AWS fleets when IAM and networking are configured correctly. It is not an absolute guarantee: a compromised scanner role with broad SendCommand scope can still issue privileged commands.

Chapter 5

Network isolation and private operation

Targets do not need inbound access from the scanner. SSM Agent initiates outbound TLS connections, so SSH, RDP and WinRM can remain closed unless another business workflow requires them.

Recommended network layout

• Place targets in private subnets.
• Use interface VPC endpoints for ssm, ssmmessages and, where applicable, ec2messages.
• Permit endpoint security-group TCP 443 from the managed-node subnets.
• Use the AWS-managed S3 access required by SSM Agent when your configuration needs it.
• Keep the Spyderz web console private behind VPN, private connectivity, a bastion path or tightly restricted administrator CIDRs.
• Keep PostgreSQL on 127.0.0.1:5432 and never publish it.

Required outbound traffic

The scanner calls AWS EC2, SSM and optional RDS APIs. It also needs HTTPS access to vulnerability and patch sources such as NVD, Microsoft, Ubuntu, Debian, Red Hat, CISA KEV, GitHub and Exploit-DB. VPC endpoints can keep supported AWS API traffic on the Amazon network, but current vulnerability enrichment is not a fully air-gapped workflow.

Do not expose these ports

AWS reference: Systems Manager VPC endpoints and no-inbound operation.

Chapter 6

First login and initial configuration

1. Open https://SCANNER_PRIVATE_IP/ through the approved administration path.
2. Expect a browser warning until the AMI self-signed certificate is replaced.
3. Sign in with case-sensitive fresh AMI credentials Admin / Admin.
4. Accept the Spyderz EULA.
5. Select timezone and 12-hour or 24-hour display.
6. Set a unique administrator password immediately.
7. Replace the self-signed certificate with a trusted certificate for the intended internal name.
8. Open Settings > NVD key and add a dedicated NVD API key.
9. Review minimum severity, minimum CVE year and Region exclusions.

Chapter 7

Inventory, tagging and scan eligibility

Standard and Advanced use the case-sensitive EC2 tag below. Enterprise can optionally override the tagging policy.

Key: Spyderz
Value: Sense

Refresh inventory

1. Open Assets.
2. Select Refresh inventory.
3. Review every Region card for OK, SG-only, Empty or No Access.
4. Resolve SSM Offline, missing tag, license capacity or IAM failures before scanning.

Inventory refresh discovers regions, EC2 instances, security groups and SSM readiness. It can reuse or collect inventory snapshots, but it is not a vulnerability scan.

License slots

• Slots track target instance IDs, not concurrent scan threads.
• A registered target can be rescanned without consuming another slot.
• Removing the tag, stopping or terminating an instance does not automatically release its slot.
• Do not edit the registry JSON manually; its HMAC protects integrity.
• Do not use a force-reset utility on an existing registry unless instructed, because it can overwrite registrations and release history.

Chapter 8

Run a vulnerability scan

Recommended first scan

1. Confirm the scanner and target roles.
2. Confirm the target is running, correctly tagged and SSM Online.
3. Select one test target in Assets.
4. Choose Scan Selected.
5. Watch the live transcript for collection, package matching, vendor checks and database writes.
6. Wait for the stored run to show completed.
7. Review Vulnerabilities, Security Groups, Dashboard and Reports.
8. Expand to the remaining licensed fleet after the first result is credible.

Scan controls

Watch resource pressure

• Green: scanner CPU or memory below 65%.
• Yellow: 65% through 84.9%.
• Red: 85% or higher.

Persistent red indicators justify a larger scanner instance or a smaller target batch. Repeatedly selecting Stop does not make an already-dispatched SSM command return faster.

Chapter 9

Read and validate the results

Dashboard is a posture overview. Vulnerabilities and Reports contain the asset, package, version, patch and source evidence required for decisions.

Finding states

Tabs and evidence

• All: every grouped CVE in the current database view.
• Critical: critical CVEs with open evidence.
• Cleared: CVEs containing cleared evidence.
• Actionable: open evidence with a scanner risk score of at least 60.

A CVE can appear in both Cleared and Actionable when one asset is patched and another remains open. Always expand evidence to review the affected asset, package, installed version, package manager, risk, CVSS, patch state and fixed-version information.

Windows posture is not the same as CVEs

Windows output reports posture findings and CVE matches separately. Open RDP or SMB, disabled protection, broad local administration or risky services can be important security findings without being CVEs.

Security Group Radar

A public security-group rule means the network policy allows a port. A listening port means a process is listening locally. Public overlap means both were observed and is higher-confidence exposure. A zero overlap still needs review when inventory is missing, stale or blocked by SSM.

Chapter 10

Reports, users and ongoing operations

Reports

• Target asset workbook: one target from its latest or selected completed run.
• Full scan run workbook: all persisted results linked to one completed run.
• Actionable Items: a reduced remediation queue using the scanner classification.

Report files can contain instance identifiers, software versions, users, groups, ports, services, CVEs and exposure evidence. Treat them as confidential security records and store them only in approved locations.

Roles

Back up before destructive actions

1. Finish or stop active scans.
2. Create an EBS snapshot of the scanner root volume.
3. Use pg_dump for a database-level backup when PostgreSQL is healthy.
4. Store backups outside the scanner instance with restricted access.
5. Test restoration on a separate instance.

Chapter 11

Data boundary and what Snakez receives

Spyderz has no Snakez-hosted telemetry, inventory or findings service. The scanner database and report files are stored on the customer-owned scanner instance.

What Snakez does not receive from the running scanner

• EC2 inventory, private IP addresses or security-group rules.
• SSM command output, operating-system inventory or software lists.
• User, group, port, service or local-administrator findings.
• CVE evidence, dashboards, scan history or report workbooks.
• A recurring license heartbeat or usage telemetry.

Chapter 12

Closed licensing without a license server

Spyderz uses a closed, baked-license model because the product processes sensitive infrastructure evidence. The selected tier is compiled into the AMI. The running scanner does not contact a Snakez license server to identify the customer, count scans or upload usage.

How licensing works

• Standard and Advanced keep a signed target registry in the customer's AWS Systems Manager Parameter Store at /scanner/license/registry.
• The registry tracks licensed target instance IDs and lifetime normal-release state.
• An HMAC protects registry integrity; manual JSON editing is unsupported.
• Enterprise does not use target-slot enforcement.
• License operations remain inside the customer AWS account and do not require a Snakez-hosted validation endpoint.

What AWS Marketplace can disclose to the seller

AWS Marketplace seller reports can include agreement and subscriber metadata such as company name, AWS account ID or encrypted account ID, email domain, country or state, offer identifiers and agreement dates. That information comes from the Marketplace transaction, not from the Spyderz scanner.

Snakez does not receive scanner telemetry simply because a customer subscribes. Marketplace metadata must not be confused with customer inventory, scan evidence or report content.

AWS references: Marketplace agreements and subscriber fields and agreement details reports.

Chapter 13

Hardening, what to avoid and troubleshooting

Hardening checklist

1. Change the default Admin password immediately.
2. Restrict scanner TCP 443 and optional TCP 22 to trusted administration paths.
3. Keep TCP 5432 closed and PostgreSQL on localhost.
4. Replace the self-signed TLS certificate.
5. Use EC2 instance profiles and temporary credentials, never long-lived access keys.
6. Restrict ssm:SendCommand to intended tags, targets and documents.
7. Use VPC endpoints for supported AWS APIs and controlled egress for vulnerability sources.
8. Patch the scanner AMI and target SSM Agent.
9. Take EBS and database backups before upgrades or reset actions.
10. Review users regularly and deactivate unused accounts.

Avoid these configurations

• Do not expose the scanner console, SSH or database to 0.0.0.0/0 or ::/0.
• Do not open SSH, RDP or WinRM on targets for Spyderz; SSM does not require inbound target access.
• Do not store AWS keys, target passwords or private keys in the scanner.
• Do not place secrets in plaintext SSM command parameters; AWS warns that API activity and command parameters can be logged.
• Do not publish report workbooks to public object storage or unrestricted collaboration links.
• Do not interpret a cleared or zero-CVE view without reviewing evidence and data freshness.
• Do not manually repair the signed license registry.

Basic health check

sudo systemctl status postgresql spyderz-api nginx --no-pager
curl -fsS http://127.0.0.1:8000/api/health
sudo journalctl -u spyderz-api -n 200 --no-pager
sudo ss -ltnp
cat /opt/spyderz/BUILD_INFO

Expected listeners

127.0.0.1:5432  PostgreSQL
127.0.0.1:8000  Spyderz API
0.0.0.0:443     Nginx HTTPS

Fast fault isolation

AWS reference: Run Command security guidance.