Amass: A Complete Guide to OWASP's Attack Surface Mapping Framework
Amass: A Complete Guide to OWASP's Attack Surface Mapping Framework
Amass is an open-source, versatile attack surface intelligence framework maintained by OWASP. While it is most commonly associated with subdomain enumeration, Amass extends far beyond that — it is a comprehensive asset discovery platform that combines passive OSINT collection, active DNS resolution, network mapping, and persistent graph database storage to build a detailed picture of an organization's physical and digital footprint.
Where Subfinder excels at raw speed and simplicity, Amass prioritizes depth and completeness. It aggregates data from over 80 sources, maintains a persistent graph database of everything it discovers, and supports both passive reconnaissance and active enumeration in a single workflow.
⚠️ Legal and ethical notice: Amass is for authorized security testing, bug bounty programs within scope, CTFs, and systems you own. Active mode sends direct DNS queries to target infrastructure. Unauthorized scanning may violate laws and terms of service. Always obtain written authorization before testing any system.
Table of Contents
- Why Amass Exists: Depth Over Speed
- Installation
- Passive vs. Active Modes
- Basic Usage
- Command Reference
- The
enumSubcommand: Core Flags - The
intelSubcommand: Organization Intelligence - Output Formats & Graph Database
- Configuration & API Keys
- Visualization & Graph Analysis
- Real-World Workflow Examples
- Amass vs. Subfinder: When to Use Which
- Integration with Other Tools
- Performance Tuning
- Common Pitfalls & Troubleshooting
- Final Thoughts
1. Why Amass Exists: Depth Over Speed
Most subdomain enumeration tools follow a simple pattern: query a handful of APIs, merge the results, output a text file. Amass takes a fundamentally different approach. It treats subdomain enumeration as one component of a larger problem: mapping an organization's complete attack surface.
The framework is built around the Open Asset Model (OAM) , which models both physical and digital assets — domains, IP addresses, ASNs, CIDRs, certificates, and the relationships that connect them. Every enumeration run writes to a persistent graph database, meaning Amass can track changes over time, correlate assets across multiple scans, and answer questions that simple scanners cannot.
This depth comes at a cost: Amass is slower than tools like Subfinder. But for comprehensive reconnaissance — where missing a single subdomain could mean missing the entry point of a breach — that trade-off is often worth it. The recommended workflow is to use Subfinder for quick passive enumeration, then Amass for comprehensive coverage.
2. Installation
System Requirements
| Requirement | Details |
|---|---|
| Operating System | Linux, macOS, Windows |
| Runtime | Go 1.21+ (for source builds) |
| Disk Space | 100MB+ (graph database grows with use) |
| Internet | Required for passive sources |
Kali Linux / Debian (Recommended)
Amass is included in the Kali Linux package repository:
sudo apt updatesudo apt install amassamass -version
The Kali package tracker confirms version 4.2.0 is available.
Ubuntu (Snap)
Ubuntu's official repositories do not include Amass. The simplest installation method is via Snap:
sudo snap install amassamass -version
The Snap package is published by the Amass team and bundles all dependencies.
macOS (Homebrew)
brew install amass
Build from Source (Latest Version)
For the latest development version, install Go and build from source:
# Install Go if neededsudo apt install golang# Build Amass v5 (latest)CGO_ENABLED=0 go install -v github.com/owasp-amass/amass/v5/cmd/amass@main# Add Go bin to PATHexport PATH="$PATH:$(go env GOPATH)/bin"
For v4 (stable):
go install -v github.com/owasp-amass/amass/v4/...@master
The binary is placed in $GOPATH/bin (typically ~/go/bin/amass).
Docker
# Pull the official imagedocker pull owaspamass/amass:latest# Or use Docker Compose for a full instancegit clone https://github.com/owasp-amass/amass-docker-compose.gitcd amass-docker-composedocker compose run --rm enum -d owasp.org
Verify Installation
amass -version
3. Passive vs. Active Modes
Understanding the distinction between passive and active modes is essential to using Amass effectively. The mode you choose depends on your authorization level, stealth requirements, and thoroughness goals.
Passive Mode
In passive mode, Amass queries third-party data sources — APIs, certificate transparency logs, web archives, search engines — without sending any direct queries to the target's infrastructure. It does not resolve discovered subdomains, does not perform DNS validation, and does not attempt zone transfers. The result is a fast, quiet enumeration that leaves no trace on the target's systems.
Use passive mode when:
- You are conducting stealth reconnaissance
- You do not have authorization for active scanning
- You need quick results without network footprint
- You want to avoid triggering IDS/IPS alerts
amass enum -passive -d example.com
Active Mode
Active mode adds direct enumeration techniques: DNS resolution of discovered names, TLS certificate scraping, zone transfer attempts, and optionally DNS brute-forcing. This validates which subdomains are live and uncovers names that passive sources may have missed.
Use active mode when:
- You have explicit written authorization
- You need validated, live subdomains
- You want maximum coverage
- You can tolerate a network footprint
amass enum -active -d example.com
Comparison Table
| Aspect | Passive | Active |
|---|---|---|
| Target interaction | None | Direct DNS queries |
| Speed | Fast | Slower |
| Stealth | High | Low (noisy) |
| Coverage | Public sources only | Public + brute force + validation |
| False positives | May include stale subdomains | Validated, live results |
| Authorization | Minimal risk | Requires explicit permission |
Workflow tip: Run passive first to gather a broad candidate list, then feed those results into an active scan for validation and discovery.
4. Basic Usage
Basic Syntax
amass <subcommand> [options]
The three primary subcommands in Amass v4/v5 are:
| Subcommand | Purpose |
|---|---|
enum | Subdomain enumeration (main use case) |
intel | Gather intel on an organization (ASN, CIDRs, root domains) |
db | Interact with the local graph database |
Your First Passive Scan
amass enum -passive -d example.com
This queries all configured passive data sources and outputs discovered subdomains to the terminal. No direct queries are sent to example.com.
Save Results to a File
amass enum -passive -d example.com -o subdomains.txt
Show Data Sources
amass enum -passive -d example.com -src
The -src flag shows which data source provided each result, useful for understanding coverage gaps.
Multiple Domains from a File
amass enum -passive -dL domains.txt -o all_subdomains.txt
Active Enumeration with Brute Force
amass enum -active -d example.com -brute -o active_results.txt
The -brute flag enables DNS brute-forcing using a wordlist. This is significantly more aggressive and should only be used with explicit authorization.
5. Command Reference
Core Subcommands
| Subcommand | Description |
|---|---|
amass enum | Perform DNS enumeration and network mapping |
amass intel | Gather intel on an organization (ASN, CIDRs, root domains) |
amass db | Manage the graph database storing enumeration results |
Note: Older subcommands like track and viz were removed in Amass v4. Tracking differences is now achieved through the persistent graph database and amass db commands.
Global Flags
| Flag | Description |
|---|---|
-config <file> | Path to the INI/YAML configuration file |
-dir <path> | Output directory for all files |
-h | Show help |
-version | Show version |
enum Subcommand Flags
| Flag | Description |
|---|---|
-d <domain> | Target domain (repeat for multiple domains) |
-dL <file> | File containing list of domains |
-passive | Passive only — no direct DNS queries to target |
-active | Active mode — DNS queries, zone transfer, cert grabbing |
-brute | Enable DNS brute-forcing |
-w <wordlist> | Custom brute-force wordlist |
-r <resolvers> | Custom DNS resolvers file |
-o <file> | Plain text output file |
-oA <prefix> | All output formats (JSON, TXT, etc.) |
-json <file> | JSON output file |
-ip | Include IP addresses in output |
-src | Show data source for each result |
-timeout <n> | Minutes before timeout (default: 30) |
-max-depth <n> | Maximum DNS brute-force recursion depth |
-list | Show available data sources |
-config <file> | Configuration file path |
Source:
6. The enum Subcommand: Core Flags
The enum subcommand is the heart of Amass. Here are the most important flags explained in detail:
-passive / -active
These flags control the fundamental operating mode. By default, Amass 4.2.0 runs in passive mode if neither is specified.
# Passive — no target interactionamass enum -passive -d example.com# Active — direct DNS queriesamass enum -active -d example.com
-brute
Enables DNS brute-forcing with a wordlist. This is the most aggressive option and should only be used with explicit authorization. The default wordlist is included with Amass, but you can specify your own:
amass enum -active -d example.com -brute -w /path/to/wordlist.txt
-src
Shows which data source provided each subdomain. This is invaluable for understanding where results are coming from and identifying which API keys are actually being used:
amass enum -passive -d example.com -src
Output includes source annotations like [CertSpotter], [Shodan], etc..
-ip
Includes IP addresses in the output for each discovered subdomain:
amass enum -d example.com -ip -o subs_with_ips.txt
-timeout
Sets the timeout in minutes. The default is 30 minutes. For large domains or slow networks, increase this:
amass enum -d example.com -timeout 60
-max-depth
Controls the recursion depth for DNS brute-forcing. Default is typically 1; increasing it makes brute-forcing more thorough but exponentially slower:
amass enum -active -d example.com -brute -max-depth 3
7. The intel Subcommand: Organization Intelligence
The intel subcommand goes beyond a single domain. It is designed to discover an organization's complete external footprint — including ASNs, CIDR ranges, and root domains.
Find ASNs for an Organization
amass intel -org "Target Corp"
This queries WHOIS data and other sources to find ASNs associated with the organization name.
Enumerate from an ASN
amass intel -asn 12345 -ip
This discovers all IP addresses and domains announced by the given ASN.
Enumerate from a CIDR Range
amass intel -cidr 203.0.113.0/24
This discovers hosts and domains within a specific IP range.
WHOIS Lookup
amass intel -whois -d example.com
This performs a WHOIS lookup and returns associated domains and IP ranges.
Practical Use Case
For a bug bounty program where the scope includes "all assets owned by Example Corp," start with intel to discover the full asset landscape before running enum on each discovered domain:
# Step 1: Find the organization's ASNsamass intel -org "Example Corp" -o asns.txt# Step 2: Enumerate each ASN for IPs and domainsamass intel -asn 12345 -ip -o asn_assets.txt# Step 3: Feed discovered domains into enumamass enum -passive -dL asn_domains.txt -o subdomains.txt
8. Output Formats & Graph Database
Plain Text Output
The simplest output format — one subdomain per line:
amass enum -d example.com -o subdomains.txt
JSON Output
For programmatic processing and integration with other tools:
amass enum -d example.com -json amass-output.json
JSON output includes metadata such as the discovery source, IP addresses, and timestamps.
All Output Formats
The -oA flag writes results in all supported formats simultaneously:
amass enum -d example.com -oA results/amass
This creates a directory with text, JSON, and potentially other formats, depending on the version.
Graph Database
One of Amass's distinguishing features is its persistent graph database. Every enumeration run writes to this database, allowing you to:
- Track changes in the attack surface over time
- Query historical enumeration results
- Export results in multiple formats
# Export all results for a domain to JSONamass db -d example.com -json output.json# List all enumerations in the databaseamass db -list
The database is stored in ~/.config/amass/ by default.
9. Configuration & API Keys
Amass's real power is unlocked when you configure API keys for the many data sources it supports. Without API keys, you are limited to a subset of free sources.
Configuration File Location
- Linux/macOS:
~/.config/amass/config.yaml(orconfig.inifor older versions) - System-wide:
/etc/amass/config.ini
Setting Up API Keys (v4.2.0+)
Create ~/.config/amass/config.yaml:
options:datasources: "/home/<user>/.config/amass/datasources.yaml"
Create ~/.config/amass/datasources.yaml:
datasources:- name: Shodancreds:account:apikey: "YOUR_SHODAN_KEY"- name: SecurityTrailscreds:account:apikey: "YOUR_ST_KEY"- name: VirusTotalcreds:account:apikey: "YOUR_VT_KEY"- name: Censyscreds:account: "YOUR_API_ID"secret: "YOUR_API_SECRET"- name: PassiveTotalcreds:account:apikey: "YOUR_PT_KEY"secret: "YOUR_PT_SECRET"
Important: YAML files must use spaces for indentation, never tabs.
Legacy INI Format
Older versions of Amass use an INI-style configuration:
[data_sources.CertSpotter][data_sources.CertSpotter.Credentials]apikey = YOUR_KEY[data_sources.Shodan][data_sources.Shodan.Credentials]apikey = YOUR_KEY
Source:
Verifying Configuration
After setting up API keys, verify which sources are active:
amass enum -config ~/.config/amass/config.yaml -list
Sources with an asterisk (*) are still missing credentials.
Recommended API Keys to Configure
| Source | Free Tier | Key Fields |
|---|---|---|
| Shodan | Yes | apikey |
| SecurityTrails | Yes | apikey |
| VirusTotal | Yes | apikey |
| Censys | No | username (API ID), secret |
| PassiveTotal | Yes | apikey, secret |
| CertSpotter | Yes | apikey (optional) |
Source:
10. Visualization & Graph Analysis
While the viz subcommand was removed in Amass v4, visualization capabilities are still available through the graph database and external tools.
D3.js Visualization
amass viz -d3 -dir amass_out/ -d example.com
This generates an interactive D3.js graph in amass_out/vis/d3.html that you can open in a browser.
Graph Database Export
You can export the graph database in formats compatible with Gephi, Maltego, and other analysis tools. Check the amass db subcommand for available export options.
Why Visualization Matters
A text list of subdomains tells you what exists. A graph visualization tells you how assets relate to each other — which subdomains share IP addresses, which certificates cover multiple domains, and which ASNs host your infrastructure. This relational view often reveals attack paths that a flat list obscures.
11. Real-World Workflow Examples
Example 1: Stealth Passive Reconnaissance
amass enum -passive -d target.com -src -o passive_subs.txt
This is the safest starting point. No traffic touches the target's infrastructure. The -src flag shows which sources contributed results.
Example 2: Active Enumeration with Brute Force
amass enum -active -d target.com -brute -o active_subs.txt -timeout 60
This combines active DNS resolution with brute-forcing. The 60-minute timeout accommodates the additional processing time.
Example 3: Multiple Domains from a File
amass enum -passive -dL domains.txt -o all_subs.txt
Feed a list of in-scope domains and enumerate them all in a single run.
Example 4: Organization Intelligence
# Find all CIDRs and domains for an organizationamass intel -org "Target Corp" -o org_intel.txt# Enumerate from a specific ASNamass intel -asn 12345 -ip -o asn_assets.txt# Enumerate from a CIDRamass intel -cidr 203.0.113.0/24 -o cidr_assets.txt
Example 5: Full Workflow with Output Files
amass enum -d target.com -brute -o subs.txt -oA results/amass -json results/amass.json
This generates plain text, JSON, and all other supported formats in a single run.
Example 6: Complete Recon Pipeline
# Step 1: Passive enumerationamass enum -passive -d target.com -o passive.txt# Step 2: Active enumeration with brute forceamass enum -active -d target.com -brute -o active.txt# Step 3: Merge and deduplicatecat passive.txt active.txt | sort -u > all_subs.txt# Step 4: Validate live hostscat all_subs.txt | httpx -silent -o live_hosts.txt# Step 5: Port scan live hostsnmap -sV -iL live_hosts.txt -oA nmap_results
12. Amass vs. Subfinder: When to Use Which
| Feature | Amass | Subfinder |
|---|---|---|
| Speed | Slower | Faster |
| Data sources | 50+ APIs | 20+ APIs |
| Modes | Passive + Active | Passive only |
| Graph database | Yes | No |
| Brute forcing | Yes (-brute) | No |
| Visualization | Yes (graph export) | No |
| Best for | Comprehensive coverage | Quick enumeration |
Source:
The Ideal Workflow
The two tools are complementary, not competitive:
- Subfinder → Quick passive enumeration to get a baseline list of subdomains
- Amass → Comprehensive active + passive enumeration for full coverage and validation
- Merge → Combine results, deduplicate, and feed into httpx/nuclei
# Quick passive with Subfindersubfinder -d target.com -o subfinder_subs.txt# Comprehensive with Amassamass enum -active -d target.com -brute -o amass_subs.txt# Mergecat subfinder_subs.txt amass_subs.txt | sort -u > all_subs.txt
The interview-ready summary: "I use Subfinder for quick passive enum, then Amass for comprehensive coverage".
13. Integration with Other Tools
Amass + httpx
amass enum -passive -d example.com -o subs.txtcat subs.txt | httpx -silent -o live.txt
Amass + Nuclei
amass enum -passive -d example.com -o subs.txtcat subs.txt | httpx -silent | nuclei -t cves/ -o vulns.txt
Amass + Nmap
amass enum -passive -d example.com -o subs.txtcat subs.txt | httpx -silent | awk -F'//' '{print $2}' | sed 's/:.*//' | sort -u > hosts.txtnmap -sV -iL hosts.txt -oA nmap_scan
Amass + MassDNS
For high-speed brute-force validation:
amass enum -passive -d example.com -o candidates.txtcat candidates.txt | massdns -r resolvers.txt -t A -o S -w resolved.txt
Amass + anew (ProjectDiscovery)
amass enum -passive -d example.com | anew subs.txt
The anew tool appends only new lines, making it ideal for incremental scanning.
14. Performance Tuning
Timeout
The default timeout is 30 minutes. For large domains with many data sources, increase it:
amass enum -d example.com -timeout 120
Rate Limiting
Amass respects the rate limits of each API. If you are hitting rate limits, consider:
- Running during off-hours
- Reducing the number of active data sources
- Using a proxy (
-proxy) to distribute requests
Resolver Configuration
For active mode and brute-forcing, use a custom resolver list for better performance:
amass enum -active -d example.com -brute -r resolvers.txt
A good resolver list is critical for brute-force speed and accuracy. Public resolver lists are available from the ProjectDiscovery community.
Brute-Force Depth
The -max-depth flag controls recursion. Default is typically 1. Increasing it makes brute-forcing more thorough but exponentially slower:
amass enum -active -d example.com -brute -max-depth 2
Config File for Reproducibility
Use a configuration file to lock in settings across multiple runs:
amass enum -config ~/.config/amass/config.yaml -d example.com -o results.txt
15. Common Pitfalls & Troubleshooting
| Issue | Solution |
|---|---|
| No results in passive mode | Configure API keys. Without them, only a few free sources (CertSpotter, etc.) are available. |
| Rate limit errors | Reduce the number of concurrent sources, increase timeout, or use a proxy. |
| Config file not found | Run Amass once to generate the default config at ~/.config/amass/. |
| YAML indentation errors | Use spaces, never tabs. Verify indentation carefully. |
| "Too many open files" | Increase the ulimit (ulimit -n 65535) or reduce concurrency. |
| Active mode slow | Use a resolver file (-r) and reduce -max-depth. |
| Graph database growing too large | Periodically clean old entries or use a separate database per engagement. |
| `viz` command not found | The viz subcommand was removed in Amass v4. Use amass db for exports and visualization alternatives. |
| Brute force produces no results | Ensure a wordlist is specified (-w) or that the default wordlist exists. Check DNS resolver connectivity. |
| Results contain wildcard entries | Wildcard DNS records make every random subdomain appear valid. Use puredns or massdns with wildcard filtering for brute-force validation. |
16. Final Thoughts
Amass occupies a unique position in the security tooling ecosystem. It is not the fastest subdomain enumerator — Subfinder holds that title. It is not the simplest — that honor goes to Assetfinder. What Amass offers is depth: a comprehensive, persistent, relational view of an organization's attack surface that no other open-source tool matches.
Its strengths lie in three areas:
- Breadth of data sources — 50+ APIs, certificate transparency logs, search engines, and DNS databases, all aggregated in one tool.
- Dual-mode operation — Passive for stealth and speed, active for validation and brute-force discovery.
- Persistent graph database — Track changes over time, correlate assets, and export for visualization.
The recommended workflow is to use Subfinder for quick reconnaissance, then Amass when you need comprehensive coverage and validation. For bug bounty hunters, penetration testers, and security teams mapping their own external footprint, Amass is an indispensable tool.
Official Resources:
- Documentation: owasp-amass.github.io
- GitHub: github.com/owasp-amass/amass
- OWASP Project Page: owasp.org/www-project-amass
- Docker Compose: github.com/owasp-amass/amass-docker-compose
- Open Asset Model: owasp-amass.github.io/docs/open-asset-model
Remember: Active mode sends direct DNS queries to target infrastructure. Always obtain written authorization before running Amass in active mode against any system. Use passive mode for reconnaissance on systems where you lack explicit permission.
Author
Discussion · 0
No comments yet — start the discussion.
Sign in to join the discussion.