[!IMPORTANT] Authorized, defensive use only. Point this server only at assets you own or are explicitly authorized to assess. It performs passive, non-intrusive reconnaissance — it reads public records (Certificate Transparency logs, DNS, RDAP/WHOIS) and each target's own published surface (one TLS handshake and one HTTP GET per host). It does not port-scan, exploit, brute-force, fuzz, or probe for vulnerabilities; that capability is excluded from the surface by design, not gated behind a flag. Output is descriptive — what exists and what the security posture is — never an exploitation plan. Every outbound connection passes an SSRF guard that refuses private, loopback, link-local, and cloud-metadata targets.

Tools

Eight tools organized around the recon workflow — attacksurface_map_domain orchestrates the full flow end to end, the per-aspect tools back it for targeted follow-up, and attacksurface_recon_guidance synthesizes findings into a defensive review plan. Seven are keyless; one (attacksurface_lookup_host) needs a Shodan key and degrades gracefully without it.

attacksurface_map_domain

The spine of most engagements — one call maps a domain end to end.

• depth control: quick = subdomains + liveness only; standard = + DNS records, TLS, and HTTP posture; thorough = + Shodan enrichment (when a key is present, otherwise skipped with a note)
• includeRegistration adds an RDAP/WHOIS lookup for the apex at standard+ depth
• All per-host fan-out uses Promise.allSettled — one failed source or unreachable host degrades to a note, never tanks the call
• Subdomain resolution is capped (ATTACKSURFACE_MAX_SUBDOMAINS, default 200) with the cap disclosed when hit
• The assessment block synthesizes only observable facts — expiring certs, missing HSTS/CSP, weak TLS versions, failed chain validation — never an exploitation path

attacksurface_enumerate_subdomains

Passive subdomain discovery from public Certificate Transparency logs.

• Three sources with a fallback chain: crt.sh (primary), Certspotter (fallback — crt.sh is frequently overloaded), and the apex's own TLS certificate SAN list (always available)
• Every discovered name carries its source provenance
• DNS resolution marks which names are live; includeUnresolved: false returns only live hosts
• Reads public logs — it does not brute-force or probe the target's resolvers

attacksurface_resolve_dns

Multi-resolver DNS enumeration with propagation visibility.

• Queries A, AAAA, CNAME, MX, NS, TXT, and CAA across multiple public resolvers (default 8.8.8.8, 1.1.1.1, 9.9.9.9)
• Reports per-resolver answers so propagation gaps and split-horizon DNS are visible
• Optional reverse DNS (PTR) on resolved addresses
• Each host passes the SSRF guard; private/loopback resolver IPs are rejected; one failing host degrades to a per-host error

attacksurface_inspect_tls

Read-only TLS posture inspection — surfacing problems is the point.

• A real handshake per host reports negotiated protocol and cipher, the full certificate chain, SANs, validity window, days-to-expiry, issuer, and chain-validation status
• Invalid, expired, and self-signed certificates are inspected and reported rather than throwing
• Posture findings flag short expiry windows, deprecated protocols, and self-signed chains
• One handshake per host; no application data is sent; SSRF-guarded

attacksurface_probe_http

A single passive HTTP(S) GET with a security read-out.

• Follows redirects and reports the final status plus the full redirect chain
• Security-header audit: HSTS, CSP, X-Frame-Options, X-Content-Type-Options, Referrer-Policy, Permissions-Policy, cookie Secure/HttpOnly/SameSite flags, and CORS origin-reflection
• Evidence-bound technology fingerprint (server, framework, CDN, WAF, CMS) — every detection names the header or body marker that triggered it
• Strictly one request per host — no path traversal, parameter injection, or multi-method probing; every redirect hop is re-checked against the SSRF guard

attacksurface_lookup_registration

Registration and ownership from public registries.

• RDAP first (structured JSON, manual 302-follow with a fresh 5s timeout covering SSRF validation and the request for each hop, plus a five-redirect cap), WHOIS port-43 fallback for TLDs without RDAP or when a hop is unresponsive
• Domain lookups return registrar, EPP status codes, registration/expiry/updated events, nameservers, and DNSSEC
• IP/CIDR lookups return the netblock name, allocation CIDRs, origin ASN, and country
• Registry data is frequently redacted or sparse — absent fields are reported as unknown, never inferred

attacksurface_lookup_host

Shodan infrastructure intelligence — the one optional-key path.

• mode: "host" (default) — a free single-IP lookup: open ports, service banners, software versions, hostnames, ASN, geo
• mode: "search" — a faceted internet-wide query that consumes paid Shodan query credits
• Requires SHODAN_API_KEY; without it the tool returns a typed source_unavailable error and every other tool keeps working
• Shodan data reflects Shodan's last scan, not a live port state — the server itself never scans ports

attacksurface_recon_guidance

State-aware synthesis — no network calls, just reasoning over what you've found.