Atlas ASM — Attack Surface Manager

Interactive Python CLI that orchestrates free recon tools and produces a self-contained HTML report.

Modules

• WHOIS lookup (python-whois)
• Subdomain discovery — assetfinder + subfinder + amass (passive) + crt.sh, run in parallel and deduped
• Resolve + HTTP liveness — dnsx + httpx
• Port scan — naabu (fast TCP sweep) → nmap -sV -sC (service detection on open ports)
• CVE scan — nuclei
• Email discovery — theHarvester + crt.sh cert extraction + optional holehe
• Breach credential check — ProxyNova free public API (no key, no signup)

Design constraints: free tools only, no paid APIs, graceful degradation when external tools are missing.

---

Requirements

• Python 3.10+
• Go 1.21+ (only needed to install the ProjectDiscovery and assetfinder tools)
• nmap, whois (system packages)
• Optional: pipx for installing theHarvester and holehe

Modules whose tools are missing are skipped at runtime — you don't have to install everything to use Atlas ASM.

---

Install — Linux (Debian/Ubuntu)

1. System packages

sudo apt update
sudo apt install -y python3 python3-pip python3-venv pipx nmap whois golang-go git

On Fedora/RHEL:

sudo dnf install -y python3 python3-pip pipx nmap whois golang git

Arch:

sudo pacman -S python python-pip python-pipx nmap whois go git

2. Ensure Go bin directory is on PATH

echo 'export PATH=$PATH:$(go env GOPATH)/bin' >> ~/.bashrc
source ~/.bashrc

3. Install the Go-based recon tools

go install github.com/tomnomnom/assetfinder@latest
go install -v github.com/projectdiscovery/subfinder/v2/cmd/subfinder@latest
go install -v github.com/projectdiscovery/dnsx/cmd/dnsx@latest
go install -v github.com/projectdiscovery/httpx/cmd/httpx@latest
go install -v github.com/projectdiscovery/naabu/v2/cmd/naabu@latest
go install -v github.com/projectdiscovery/nuclei/v3/cmd/nuclei@latest
go install -v github.com/owasp-amass/amass/v4/...@master

naabu requires libpcap. If the build fails: sudo apt install libpcap-dev.

4. Install Python-based recon tools

theHarvester trap: there is a squatted package on PyPI literally named theHarvester at version 0.0.1 with no code in it. pip install theHarvester installs that stub and nothing else — python -m theHarvester will say No module named theHarvester. Always install from the GitHub repo.

pip uninstall -y theHarvester 2>/dev/null || true   # in case the stub is already there
pipx install git+https://github.com/laramies/theHarvester.git
pipx install holehe          # optional
pipx ensurepath

5. Install Atlas ASM Python deps

cd /path/to/ASM
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

6. Nuclei templates (handled automatically)

Atlas ASM auto-fetches the official nuclei-templates on first run, so you don't need to do anything. If you'd like to populate the templates dir up front (e.g., on an air-gapped box you'll later go offline on):

nuclei -update-templates

The CLI offers a one-keystroke refresh option each run.

---

Install — Windows

1. System packages

The easiest path is Chocolatey (run an elevated PowerShell):

choco install -y python golang nmap git

whois on Windows — pick one:

choco install -y sysinternals      # provides Sysinternals whois.exe on PATH
# or
choco install -y whois              # alternate community port

If you'd rather not use Chocolatey, install each manually:

• Python 3.10+: https://www.python.org/downloads/ (check "Add to PATH")
• Go: https://go.dev/dl/
• Nmap: https://nmap.org/download.html (the installer adds it to PATH)
• Git: https://git-scm.com/download/win
• Sysinternals whois: https://learn.microsoft.com/sysinternals/downloads/whois

2. Ensure Go bin directory is on PATH

Go's installer usually sets this, but verify in PowerShell:

go env GOPATH

The bin subfolder of whatever that prints needs to be on your PATH. If it isn't:

$gobin = (go env GOPATH) + "\bin"
[Environment]::SetEnvironmentVariable("Path", $env:Path + ";$gobin", "User")
# restart your shell after this

3. Install the Go-based recon tools

go install github.com/tomnomnom/assetfinder@latest
go install -v github.com/projectdiscovery/subfinder/v2/cmd/subfinder@latest
go install -v github.com/projectdiscovery/dnsx/cmd/dnsx@latest
go install -v github.com/projectdiscovery/httpx/cmd/httpx@latest
go install -v github.com/projectdiscovery/naabu/v2/cmd/naabu@latest
go install -v github.com/projectdiscovery/nuclei/v3/cmd/nuclei@latest
go install -v github.com/owasp-amass/amass/v4/...@master

naabu on Windows requires Npcap (install with WinPcap-compatible mode enabled): https://npcap.com/#download. Without Npcap, naabu falls back to a slower CONNECT scan but still works.

4. Install Python-based recon tools

theHarvester trap: there is a squatted package on PyPI literally named theHarvester at version 0.0.1 with no code in it. pip install theHarvester installs that stub and nothing else — python -m theHarvester will say No module named theHarvester. Always install from the GitHub repo.

python -m pip install --user pipx
python -m pipx ensurepath
# Restart your shell so pipx is on PATH.
pip uninstall -y theHarvester      # if you already grabbed the broken stub
pipx install git+https://github.com/laramies/theHarvester.git
pipx install holehe                # optional

5. Install Atlas ASM Python deps

cd C:\Users\Armadin\Documents\Tools\ASM
python -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install -r requirements.txt

If Activate.ps1 is blocked by execution policy: Set-ExecutionPolicy -Scope CurrentUser RemoteSigned.

6. Nuclei templates (handled automatically)

Atlas ASM auto-fetches the official nuclei-templates on first run. The CLI offers a one-keystroke refresh option each run. To pre-populate manually:

nuclei -update-templates

---

Usage

From the project root, with the venv active:

python atlas-asm.py

You'll be prompted for:

1. Company name — used in the report title and filename slug.
2. Known domains — comma-separated apex domains (acme.com, acme.io).
3. Output directory — defaults to ./output.
4. Y/N per module — pick which steps to run.
5. Y/N holehe — only if email discovery is selected.

The tool then:

• Audits which external tools are installed and warns about anything missing (you can continue — missing tools just skip their module).
• Runs the pipeline, showing live progress.
• Writes output/<company-slug>-<YYYY-MM-DD-HHMMSS>.html.

Example session

$ python atlas-asm.py
Atlas ASM — Attack Surface Manager

Company name: Acme Corp
Known domains: acme.com, acme.io
Output directory [./output]:

Select modules to run:
  WHOIS lookup [Y/n]: y
  Subdomain discovery [Y/n]: y
  Resolve + HTTP liveness [Y/n]: y
  Port scan (naabu + nmap) [Y/n]: y
  Nuclei CVE scan [Y/n]: y
  Email discovery [Y/n]: y
    └ Also run holehe? [y/N]: n
  Breach credential check (ProxyNova) [Y/n]: y

[tool audit ...]
── WHOIS ───────────────
  acme.com: registrar=MarkMonitor, expires=2030-01-15
── Subdomain discovery ─
  acme.com: 412 unique
    assetfinder: 88
    subfinder: 247
    amass: 134
    crt.sh: 318
...
── Done ────────────────
Report: /home/.../output/acme-corp-2026-05-26-141233.html

Open the report

# Linux
xdg-open output/acme-corp-*.html
# macOS
open output/acme-corp-*.html
# Windows
start .\output\acme-corp-*.html

The report has collapsible sections, sortable tables, and severity coloring. It's a single self-contained HTML file — safe to email or attach to engagement reports.

---

Notes

Privileges

• nmap -sS (SYN scan) requires root/Administrator. Atlas ASM uses nmap -sV -sC which works as an unprivileged user but uses TCP connect under the hood — slightly noisier and slower. Run as root/admin if you need stealth.
• naabu SYN mode also needs raw socket access. CONNECT mode (default fallback) works unprivileged.

Rate limits & OPSEC

• ProxyNova throttles aggressively. Atlas ASM sleeps 0.5s between queries by default. Scanning hundreds of emails will take a while.
• ProxyNova logs queries server-side. If pre-engagement opsec matters, query from a VPN/dedicated infra, not your engagement box.
• crt.sh is queried directly without rate-limiting — be considerate, don't loop.

Module dependencies

Module	Required tools	Behavior if missing
WHOIS	python-whois (pip)	Module errors out, others continue
Subdomain discovery	assetfinder / subfinder / amass (any subset)	Each source independently degrades; crt.sh always runs
Resolve + liveness	dnsx, httpx	Live host list will be empty; downstream still runs
Port scan	naabu, nmap	If naabu missing: skipped. If only nmap missing: naabu results shown without service detection.
Nuclei	nuclei	Skipped with error
Email discovery	theHarvester (optional holehe)	Falls back to crt.sh cert email extraction only
Breach creds	(network only)	Always works if internet is reachable

Updating nuclei templates

Atlas ASM auto-fetches the official ProjectDiscovery template set on first run (when the templates directory doesn't exist yet) and offers a Y/N refresh prompt every run after that. To refresh out-of-band:

nuclei -update-templates

Breach lookup modes

When the breach module is enabled, you're prompted to pick:

1. Per discovered email — needs the email module to have run; most precise but slow.
2. Per whole domain — queries @<domain> against ProxyNova. Finds creds for employee emails you never discovered. ProxyNova caps response size server-side, so for large domains (e.g., google.com) you'll get a sample, not the full dump.
3. Both (default) — runs domain-wide first, then per-email, so the report has precise per-employee context plus the broad-net findings.