SurfaceCartographer

SurfaceCartographer is a lightweight OSINT orchestrator for authorized external attack surface mapping.

It helps security teams inventory public-facing domains, FQDNs, IP addresses, HTTP services, cloud/CDN/SaaS endpoints, and high-priority diagnostic candidates such as VPN portals, admin panels, APIs, SSO surfaces, staging environments, CI/CD systems, and monitoring consoles.

The tool is designed for Kali Linux workflows, but the Python core is intentionally simple and portable.

Safety Model

SurfaceCartographer is built for authorized asset discovery and scoping. It does not perform exploitation, authentication attempts, password guessing, directory brute forcing, or broad high-speed port scanning.

Use it only against assets you own, operate, or have explicit written authorization to assess. Operators are responsible for complying with applicable laws, customer rules of engagement, third-party platform terms, and cloud/SaaS provider policies.

Default behavior favors:

Principle	Meaning
Passive-first	Use passive sources such as subfinder, amass -passive, and Certificate Transparency logs first.
Low impact	Use rate-limited HTTP probing when enabled.
Evidence-based	Keep source labels and timestamps for discovered assets.
Scope-aware	Treat CDN, cloud, SaaS, and shared infrastructure differently from owned infrastructure.

What It Does

Stage	Tooling
Subdomain discovery	subfinder, amass -passive, crt.sh
DNS resolution	Python resolver, optional dnsx record capture
HTTP/HTTPS probing	Optional httpx with rate limiting
Risk triage	Keyword and status-based classification
Reporting	CSV inventory, CSV candidate list, CSV summary, HTML report

Requirements

• Python 3.10+
• Kali Linux recommended
• Optional external tools:
  • subfinder
  • amass
  • dnsx
  • httpx

If an optional tool is not installed, SurfaceCartographer skips that stage and continues.

Quick Start

Single domain:

python3 surfacecartographer.py -d example.com -o runs/example

Multiple domains:

python3 surfacecartographer.py -f domains.sample.txt -o runs/example

Passive collection only:

python3 surfacecartographer.py -f domains.sample.txt -o runs/example-passive --passive-only

Lower HTTP request rate:

python3 surfacecartographer.py -d example.com -o runs/example --rate-limit 10

Output Layout

runs/example/
  input/
    root_domains.txt
  raw/
    *.stdout.txt
    *.stderr.txt
    crtsh_*.json
    httpx_web.jsonl
  work/
    fqdn_candidates.txt
  output/
    asset_inventory.csv
    diagnosis_candidates.csv
    summary.csv
    report.html

Key Reports

File	Purpose
asset_inventory.csv	Full external asset inventory candidate table.
diagnosis_candidates.csv	Prioritized assets for validation or security testing scope review.
summary.csv	Counts for discovered FQDNs, resolved FQDNs, IPs, web services, and risk buckets.
report.html	Browser-friendly report focused on higher-priority assets.

Risk Triage

Risk	Typical Indicators
High	HTTP-reachable VPN, admin, SSO/auth, API, non-production, CI/CD, or monitoring indicators.
Medium	DNS-resolved sensitive indicators, or restricted/unstable HTTP states such as 401, 403, or 5xx.
Low	Reachable public web services with normal 2xx or 3xx responses.
Info	Passive-only or unresolved records. Passive sensitive indicators are marked as Maybe candidates until reachability is confirmed.

Important Notes

• CDN and SaaS IPs are usually not owned by the target organization.
• A discovered FQDN is not automatically in scope for testing.
• Third-party platforms may require separate written authorization.
• Passive data may be stale; use last_seen, source labels, and live DNS/HTTP checks to separate historical data from active exposure.
• Do not use this project to target third-party systems without authorization.
• Do not use this project to collect personal information, perform credential attacks, bypass access controls, or deliver payloads.

Responsible Use

This project is intended for defensive security, asset inventory, audit preparation, and authorized attack surface management. If you believe the project is being misused or you have a concern about the content, please see SECURITY.md.

Example

python3 surfacecartographer.py \
  -d example.com \
  --company "Example Corp" \
  --rate-limit 25 \
  -o runs/example-corp

Then open:

runs/example-corp/output/report.html