OWASP Amass Attack Surface Mapping on AWS User Guide

Overview

This image runs OWASP Amass, the OWASP Foundation's open source, Apache-2.0 licensed tool for attack-surface mapping and external asset discovery. Point Amass at a domain you own, or one you are explicitly authorised to test, and it discovers the subdomains, DNS records, TLS certificates, netblocks and autonomous systems that make up your external attack surface, drawing on open-source intelligence from certificate-transparency logs, passive DNS, WHOIS/RDAP and dozens of data sources.

This is a headless command-line image. There is no web interface, no service to log into and no credentials: Amass is driven with the amass command over SSH using your own key. cloudimg ships it as a ready-to-run asset-inventory appliance: the pinned, checksum-verified scanner, a system configuration, an OSINT data-source template, a persistent OWASP Open Asset Model (OAM) asset database, a daily passive enumeration schedule and CI/SIEM-friendly reports are all in place the moment you SSH in.

Nothing a customer logs into listens on the network. SSH with your launch key is the only open port, and the embedded collection-engine port (tcp/4000) is firewalled to loopback. The image ships no default credential of any kind and no baked API keys, and the operating system is fully patched at capture with unattended security upgrades enabled.

Authorised use only

Amass is a defensive asset-inventory and attack-surface-mapping tool. Use it only against domains you own or are explicitly permitted to assess. Enumerating third-party infrastructure you are not authorised to test may be illegal in your jurisdiction. This image ships with no targets configured, and the default enumeration mode is passive open-source-intelligence collection, which sends no packets to your targets. You add only the domains you are authorised to enumerate. The examples in this guide use owasp.org, the OWASP Foundation's own project domain, which is the tool's standard demonstration target.

Prerequisites

Before you deploy this image you need:

• An Amazon Web Services account where you can launch EC2 instances
• IAM permissions to launch instances, create security groups, and subscribe to AWS Marketplace products
• An EC2 key pair in the target Region for SSH access to the instance
• A VPC and subnet in the target Region, with a security group allowing inbound port 22 from your management network
• Outbound internet access from the instance so Amass can reach OSINT data sources
• The AWS CLI (version 2) installed locally if you plan to deploy from the command line

Connecting to Your Instance

This listing may offer more than one operating system variant. Connect over SSH on port 22 as the default login user for the variant you launched:

Use your EC2 key pair, for example:

ssh -i /path/to/your-key.pem ubuntu@<vm-ip>

Step 1: Launch the Instance from the AWS Marketplace

Sign in to the AWS Management Console, open the EC2 service, and select Launch instance. Under Application and OS Images choose AWS Marketplace AMIs and search for OWASP Amass. Select the cloudimg listing and choose Select, then Continue on the subscription summary.

Pick an instance type of m5.large or another size that suits your workload. Choose your EC2 key pair under Key pair (login). Under Network settings select your VPC and subnet, and either create or select a security group that opens port 22 from your management network. Leave the root volume at the default size or larger.

Select Launch instance. First boot initialisation takes a minute or two after the instance state becomes Running and the status checks pass.

Step 2: Launch the Instance from the AWS CLI

The following block launches an instance from the cloudimg OWASP Amass Marketplace AMI into an existing subnet and security group. Replace <ami-id> with the AMI ID shown on the Marketplace listing, <key-name> with your EC2 key pair name, <subnet-id> with your subnet ID, and <security-group-id> with a security group that opens port 22 from your management network.

aws ec2 run-instances \
  --image-id <ami-id> \
  --instance-type m5.large \
  --key-name <key-name> \
  --subnet-id <subnet-id> \
  --security-group-ids <security-group-id> \
  --associate-public-ip-address \
  --metadata-options "HttpTokens=required" \
  --tag-specifications 'ResourceType=instance,Tags=[{Key=Name,Value=owasp-amass}]'

Step 3: Confirm the Scanner and the Armed Schedule

SSH in and confirm the pinned scanner, the appliance configuration, the loopback-only collection engine and the SSH-only listener set:

Check the installed version:

amass -version

Confirm the scheduled enumeration timer and the collection-engine firewall guard are armed and running:

systemctl is-active amass-enum.timer amass-firewall.service

See when the daily enumeration will next run:

systemctl list-timers amass-enum.timer --all --no-pager

Both units report active on a fresh instance: amass-enum.timer is armed and waiting, and amass-firewall.service keeps the embedded collection engine reachable from loopback only.

Step 4: Prove Enumeration End to End with the Self-Test

The image ships a bounded self-test so you can confirm the scanner, configuration and data sources work end to end before you point Amass at your own domains. It runs a short passive enumeration of owasp.org, exercises the collection engine and persists the OWASP Open Asset Model asset database:

$ amass-selftest owasp.org
Running a bounded passive enumeration of owasp.org (<= 1 min)...
Session Scope
FQDN:
owasp.org
----
OAM asset database present: /var/lib/amass/asset.db
discovered 0 name(s) for owasp.org (enum exit 0)

A short passive keyless run establishes the session scope and writes the asset database but typically discovers few or no additional names: meaningful passive discovery is unlocked by adding OSINT data-source API keys (Step 6) or by using active mode (Step 9). The load-bearing proof here is that the enumeration engine ran a real session end to end and persisted the asset database, which you then query at any time.

Step 5: Configure the Domains You Are Authorised to Enumerate

The scheduled enumeration reads its targets from /etc/amass/scan.conf, which ships empty. View it:

cat /etc/amass/scan.conf

Add only the domains you own or are explicitly authorised to assess to AMASS_TARGETS (space separated), then apply. Edit the file:

sudo nano /etc/amass/scan.conf

Set, for example, AMASS_TARGETS="example.com example.net" and AMASS_MODE="passive", then restart the timer so it picks up the change:

sudo systemctl restart amass-enum.timer

Step 6: Add OSINT Data-Source API Keys (Optional, Unlocks Full Discovery)

Certificate-transparency and a few sources work with no keys, but Amass reaches its full potential with API keys for the OSINT data sources. The template at /etc/amass/datasources.yaml ships as an all-commented template with dozens of source stanzas ready for your keys - the image bakes in no keys of its own. Add your keys:

sudo nano /etc/amass/datasources.yaml

Uncomment the sources you have accounts for and paste your keys, then re-run an enumeration. Keys you add here stay on your instance.

Step 7: The Scheduled Enumeration and Reports

A systemd timer runs a daily passive enumeration of your configured domains. Each run writes a dated text report under /var/lib/amass/reports/ and updates a stable latest-<domain>.txt symlink your CI or SIEM can always read:

You can trigger the scheduled runner on demand for a domain you are authorised to enumerate:

sudo amass-enum-run <your-domain>

The runner writes /var/lib/amass/reports/latest-<your-domain>.txt for downstream pickup.

Step 8: Query the OWASP Open Asset Model Asset Database

Every enumeration persists its findings into the OAM asset database at /var/lib/amass, so results accumulate over time. Query the discovered names for a domain at any time:

amass subs -d <your-domain> -dir /var/lib/amass -names

You can also generate graph visualisations of the asset relationships:

amass viz -d <your-domain> -dir /var/lib/amass

Step 9: Passive Versus Active Mode

The default mode is passive: Amass collects from open-source-intelligence data sources only and sends no packets to your targets. For assets you own, you can switch to active mode, which additionally resolves names and performs light active reconnaissance such as zone-transfer attempts and certificate name grabs. Set AMASS_MODE="active" in /etc/amass/scan.conf, or run an active enumeration directly:

amass enum -active -d <your-domain> -config /etc/amass/config.yaml -dir /var/lib/amass

Only use active mode against infrastructure you own or are explicitly authorised to test.

Security and Credentials

This image ships no credentials. Amass has no web interface, no API listener a customer logs into and no admin account, so there is nothing to log in to and nothing to rotate. The only way in is SSH with the key you chose at launch. Confirm the instance note, which documents the layout and contains no secrets:

cat /etc/amass/credentials

The embedded collection engine is firewalled to loopback, SSH with your key is the only open port, and unattended security upgrades keep the operating system patched. The data-source template ships with no keys, and any keys you add stay on your instance.

Support

cloudimg provides 24/7 technical support for this product by email and live chat.

Contact: support@cloudimg.co.uk

Support covers configuring authorised enumeration targets, adding and troubleshooting OSINT data-source API keys, interpreting the asset database and reports, wiring the schedule and reports into a CI or SIEM pipeline, and switching between passive and active modes. Critical issues receive a one-hour average response.

Only enumerate domains you own or are authorised to assess. All product and company names are trademarks or registered trademarks of their respective holders; use of them does not imply any affiliation with or endorsement by them, including the OWASP Foundation.