amass

# OWASP Amass

## Overview

OWASP Amass performs network mapping of attack surfaces and external asset discovery using open source information gathering and active reconnaissance techniques. It supports dozens of passive data sources (certificate transparency, DNS datasets, APIs) and active techniques (brute force, DNS zone transfers). Amass is the industry standard for comprehensive subdomain enumeration during penetration tests and red team engagements.

## Instructions

### Step 1: Install Amass

```bash
# Option 1: Download pre-built binary (recommended)
# Visit https://github.com/owasp-amass/amass/releases
wget https://github.com/owasp-amass/amass/releases/latest/download/amass_Linux_amd64.zip
unzip amass_Linux_amd64.zip
sudo mv amass_Linux_amd64/amass /usr/local/bin/

# Option 2: Go install
go install -v github.com/owasp-amass/amass/v4/...@master

# Option 3: Docker
docker pull caffix/amass
alias amass='docker run --rm -v ~/.config/amass:/root/.config/amass caffix/amass'

# Verify installation
amass -version
```

### Step 2: Passive enumeration (safe, no target contact)

```bash
# Basic passive subdomain enumeration
amass enum -passive -d example.com

# Multiple domains at once
amass enum -passive -d example.com -d example.org

# Save results to file
amass enum -passive -d example.com -o subdomains.txt

# JSON output for programmatic processing
amass enum -passive -d example.com -json amass_output.json

# Verbose mode to see which sources are returning data
amass enum -passive -d example.com -v
```

### Step 3: Active enumeration (comprehensive, touches target DNS)

```bash
# Active mode: passive + DNS brute force + zone transfer attempts
amass enum -active -d example.com -o active_subdomains.txt

# Use a custom wordlist for brute force
amass enum -active -d example.com -brute -w /usr/share/wordlists/subdomains.txt

# Specify DNS resolvers
amass enum -active -d example.com -r 8.8.8.8,1.1.1.1,9.9.9.9

# Limit to specific port for alterations
amass enum -active -d example.com -alts -o subs_with_alts.txt

# Full active scan with brute force and alterations
amass enum -active -d example.com -brute -alts -min-for-recursive 2 -o full_enum.txt
```

### Step 4: Intelligence gathering — org and ASN mapping

```bash
# Find ASNs and IP ranges for an organization name
amass intel -org "Example Corporation"

# Reverse lookup: find domains from a known IP or CIDR
amass intel -ip 203.0.113.1
amass intel -cidr 203.0.113.0/24

# Find ASN for a domain, then map the full ASN
amass intel -d example.com -asn
amass intel -asn 12345 -o asn_domains.txt

# Combine: find org → get ASN → enumerate all domains
amass intel -org "Example Corp" 2>/dev/null | grep ASN | awk '{print $1}' | \
  while read asn; do amass intel -asn $asn; done
```

### Step 5: Configure API keys for maximum coverage

```yaml
# ~/.config/amass/config.yaml
scope:
  domains:
    - example.com

# Data source API keys
data_sources:
  Shodan:
    credentials:
      key: YOUR_SHODAN_API_KEY
  VirusTotal:
    credentials:
      key: YOUR_VT_API_KEY
  SecurityTrails:
    credentials:
      key: YOUR_ST_API_KEY
  GitHub:
    credentials:
      key: YOUR_GITHUB_TOKEN
  Censys:
    credentials:
      api_id: YOUR_CENSYS_ID
      secret: YOUR_CENSYS_SECRET
  Hunter:
    credentials:
      key: YOUR_HUNTER_KEY
  URLScan:
    credentials:
      key: YOUR_URLSCAN_KEY
  WhoisXMLAPI:
    credentials:
      key: YOUR_WHOISXML_KEY
  BinaryEdge:
    credentials:
      key: YOUR_BINARYEDGE_KEY

# Rate limiting (be respectful of free tier limits)
resolvers:
  - 8.8.8.8
  - 8.8.4.4
  - 1.1.1.1
  - 1.0.0.1
```

### Step 6: Parse and process JSON output

```python
import json
import subprocess
from collections import defaultdict

def run_amass_passive(domain, output_file=None):
    """Run Amass passive enumeration and return parsed results."""
    json_file = output_file or f"amass_{domain.replace('.', '_')}.json"
    cmd = [
        "amass", "enum",
        "-passive",
        "-d", domain,
        "-json", json_file
    ]
    print(f"Running Amass passive scan for {domain}...")
    subprocess.run(cmd, timeout=600)
    return parse_amass_json(json_file)

def parse_amass_json(json_file):
    """Parse Amass JSON output (newline-delimited JSON)."""
    subdomains = []
    ip_map = defaultdict(list)

    with open(json_file) as f:
        for line in f:
            line = line.strip()
            if not line:
                continue
            try:
                record = json.loads(line)
                name = record.get("name", "")
                addresses = record.get("addresses", [])
                subdomains.append(name)
                for addr in addresses:
                    ip = addr.get("ip", "")
                    if ip:
                        ip_map[ip].append(name)
            except json.JSONDecodeError:
                continue

    return {
        "subdomains": sorted(set(subdomains)),
        "ip_to_hosts": dict(ip_map),
        "unique_ips": sorted(ip_map.keys()),
    }

def print_summary(results, domain):
    print(f"\n=== Amass Results: {domain} ===")
    print(f"Unique subdomains: {len(results['subdomains'])}")
    print(f"Unique IPs:        {len(results['unique_ips'])}")
    print("\nTop-level subdomains found:")
    for sub in results['subdomains'][:30]:
        print(f"  {sub}")
    print("\nIPs hosting multiple domains (potential shared hosting):")
    for ip, hosts in results['ip_to_hosts'].items():
        if len(hosts) > 1:
            print(f"  {ip}: {', '.join(hosts[:5])}")

results = run_amass_passive("example.com")
print_summary(results, "example.com")
```

### Step 7: Visualize with network graph (dot format)

```bash
# Generate a DOT graph of discovered network relationships
amass viz -d3 -d example.com -o network_graph.html

# Open in browser
# The HTML file contains an interactive D3.js visualization

# Export to Graphviz dot format
amass viz -dot -d example.com -o network.dot
dot -Tpng network.dot -o network.png

# I