convez.ai
SkillSegurançaAvançado
krutarthshukla

Subdomain Recon

krutarthshukla/subdomain-recon

Mapeia attack surface completo: raízes, subdomínios e hosts ativos

Ver no GitHub
InicialPluginScore · de 0 a 100

Skill Claude para reconhecimento de subdomínios que mapeia o footprint externo completo de uma organização. A partir de um nome de org ou domínios, descobre raízes pertencentes à organização, enumera subdomínios e valida hosts ativos usando 27 fontes passivas e 25 técnicas avançadas (pivô de favicon, hashes TLS, source maps, ASN ranges, ML e brute-force).

Instalação

$npx convez-ai krutarthshukla/subdomain-recon

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
0
Forks
0
Acompanhando
0
Saúde
28%
Último commit
há 5 meses
Versão
—
Issues abertas
0
Contribuidores
1

Casos de uso

  • Reconhecimento de segurança e pentesting
  • Mapeamento de footprint externo de organizações
  • Identificação de ativos digitais não gerenciados
  • Validação de propriedade de domínios e detecção de takeover

Veredito

Ferramenta robusta e bem-arquitetada para reconnaissance ofensivo. Vai além de enumeradores padrão ao combinar múltiplas técnicas passivas e ativas; requer Python 3.9+ e setup inicial, mas válido para profissionais de segurança sérios.

README

A tradução para o português deste README ainda está na fila.

subdomain-recon

Give it an organisation name — or just a domain or two — and it maps out the whole external footprint: all the root domains the org owns, every subdomain it can find, and which of those are actually live. Hand it an org name and it discovers and validates the owned roots first; hand it domains directly and it goes straight to enumerating their subdomains. It pulls from passive sources first, then layers on the more aggressive techniques, and finishes by probing what's up and writing a report.

In practice it tends to surface noticeably more than running subfinder or amass on their own, mostly because it doesn't stop at certificate transparency — it also pivots on favicons, TLS certs, source maps, ASN ranges, and a few ML and brute-force passes.

How to use it

This is a Claude Code skill, so the easiest way to run it is to just ask, in plain English:

  • recon acme.com
  • find all subdomains of Acme
  • map the attack surface of acme.com, acme.io

Give it an org name and it discovers and validates the owned root domains first; give it one or more domains and it enumerates those directly. You don't choose a mode — it's detected from what you type. The first run on a new machine installs the toolchain automatically (a few minutes, one time), and every run drops a self-contained folder under ~/Desktop/.

Prefer the terminal? The same thing runs as a single command — see Quick start below.

What it does

  • Finds the root domains, not just subdomains. Starts from the org name and expands into acquisitions, brand domains, and ccTLD variants. It also keeps domains that only have NS records (no A record), which a naive sweep would throw away.
  • Checks ownership before enumerating. A domain resolving doesn't mean the org owns it — plenty are parked or squatted. This step sorts roots into owned / uncertain / rejected so you don't waste time enumerating someone else's parking page. Rejected domains are logged, not silently dropped.
  • 27 passive sources. Merklemap, crt.sh, Columbus, LeakIX, Netlas, host.io, C99.nl, uncover (which itself wraps 18 engines), asnmap + PTR, and more.
  • 25 advanced techniques. Favicon-hash pivoting, .well-known app-association files, source-map extraction, Azure tenant enumeration, SaaS-platform patterns, Postman workspace search, BBOT, the katana JS crawler, subwiz ML prediction, BadDNS takeover checks, and JARM/TLS-SAN pivoting.
  • Active enumeration. DNS brute-force (top-110k wordlist by default; n0kovo 3M optional), permutation enrichment with alterx, and TLS SAN-on-CIDR — run in parallel per domain with per-domain watchdogs.
  • Live probing and a report. Probes everything it found and writes a text report grouped by source domain.
  • Continuous monitoring (optional). Subscribe to CT logs and get alerted when new subdomains show up.

Requirements

  • Python 3.9 or newer
  • The tooling the installer sets up (full list below)
  • API keys are optional — free tiers are plenty. Worth getting: Merklemap, LeakIX, Netlas, Validin, host.io, C99.nl

install_tools.sh is idempotent and cross-platform (macOS + Linux), and run_all.sh calls it automatically if anything is missing — so you don't have to run it by hand. Tools already on your system are detected and never reinstalled.

Tools it installs / uses

GroupTools
Passive enumerationsubfinder, assetfinder, chaos, findomain, amass, theHarvester, uncover
DNS resolution / brutednsx, puredns, massdns, shuffledns, alterx
Cert / TLS / ASN pivotstlsx, asnmap, mapcidr, cdncheck, cero
Crawl / archivekatana, gau, waybackurls, sourcemapper
Probe / utilityhttpx, anew
CT monitoringgungnir
ML / takeover (Python)bbot, subwiz, baddns
Python libsrequests, mmh3, pyyaml
Wordlistn0kovo 3M subdomains

If a tool can't be installed on a given host, that technique is skipped and the rest of the run continues.

Installation

You don't have to run this — run_all.sh auto-installs anything missing. But to set up (or refresh) the toolchain by hand:

bash scripts/install_tools.sh
source ~/.recon-tools/activate.sh

# Optional, but recommended — add free API keys
nano ~/.config/subdomain-recon/api_keys.yaml

If you only add a few keys, these give the most back for the least effort:

KeyCostWhy it's worth it
MerklemapFree tier100B+ CT rows, near-instant
LeakIXFree (register)Independent crawler, not just CT
Netlas50 req/day freeDeep nesting, regex search
ValidinFree communityThe best free RiskIQ replacement
C99.nl~$5/moCheapest commercial subdomain API
host.io1000/mo freeReverse IP / NS / MX lookups

Merklemap, Validin, LeakIX, and Netlas together cost under $100/mo and cover more than SecurityTrails alone.

Quick start

One command runs the whole thing. Give it either an org name or one or more domains — the mode is auto-detected:

# Org name → discover every owned root, then enumerate all of them
bash scripts/run_all.sh "Acme Corp"

# A single domain → enumerate just that domain's subdomains
bash scripts/run_all.sh "acme.com"

# Several domains → enumerate exactly those (no root discovery)
bash scripts/run_all.sh "acme.com,acquired-co.com,product.io"

Each run is self-contained under ~/Desktop/<Org>_<timestamp>/: the report (<Org>_domains.txt, with live hosts under a # LIVE HOSTS section), the full run.log, per-phase intermediates in work/, and (org mode) rejected_domains.txt.

How it works

There are eight stages. Each one feeds the next, and you can run any of them on their own if you only need part of the pipeline.

        org name + seed domains
                  │
   ┌──────────────▼───────────────┐
   │ Phase 1   Domain Discovery    │  expand org → acquisitions/brands/ccTLDs
   │                               │  + NS-existence sweep
   └──────────────┬───────────────┘
                  │ confirmed roots
   ┌──────────────▼───────────────┐
   │ Phase 1.5 Ownership Validation│  owned / uncertain / rejected (parked)
   │                               │  rejected logged, never silently dropped
   └──────────────┬───────────────┘
                  │ owned roots
   ┌──────────────▼───────────────┐
   │ Phase 2   Passive Enumeration │  27 CT/API sources, no target contact
   │                               │
   └──────────────┬───────────────┘
                  │ passive subdomains
   ┌──────────────▼───────────────┐
   │ Phase 3   Advanced Techniques │  25 asset-pivot techniques
   │                               │  (favicon/JARM/sourcemap/BBOT/ML…)
   └──────────────┬───────────────┘
                  │ advanced subdomains
   ┌──────────────▼───────────────┐
   │ Phase 4   Active Enumeration  │  brute (top-110k, parallel+watchdog),
   │                               │  permutation, TLS SAN-on-CIDR
   └──────────────┬───────────────┘
                  │ brute / permuted subdomains
   ┌──────────────▼───────────────┐
   │ Phase 5   Merge + Dedupe      │  union all sources, normalise, cache
   │                               │
   └──────────────┬───────────────┘
                  │ merged subdomains
   ┌──────────────▼───────────────┐
   │ Phase 6   Live Probe          │  concurrent HTTP probe + tech detect
   │                               │
   └──────────────┬───────────────┘
                  │ live hosts
   ┌──────────────▼───────────────┐
   │ Phase 7   Report              │  grouped report → ~/Desktop
   │                               │
   └───────────────────────────────┘
PhaseTakesProducesWhat happens
1 — Domain Discoveryorg name, acquisitions, abbreviationsconfirmed root domainsTurns the org into a list of candidate roots — brands, ccTLD variants, acquisitions — and holds onto anything with live NS records even if it has no A record, since those are easy to miss.
1.5 — Ownership Validationconfirmed rootsowned roots, rejected rootsDecides whether each root really belongs to the org. Owned (trusted or with a clear ownership signal) and uncertain (no signal, but kept just in case) both move on; parked or for-sale domains get set aside and logged.
2 — Passive Enumerationowned rootspassive subdomainsQueries 27 passive sources (Merklemap, crt.sh, Columbus, LeakIX, Netlas, host.io, C99.nl, uncover's 18 engines, asnmap + PTR, and so on). Never touches the target directly.
3 — Advanced Techniquesroots + passive resultsadvanced subdomainsRuns 25 pivoting techniques: favicon hashes, .well-known app-association, source maps, Azure tenants, 17 SaaS patterns, Postman search, BBOT, katana JS crawling, subwiz ML prediction, BadDNS takeover checks, and JARM/TLS-SAN pivots.
4 — Active Enumerationowned roots + passive resultsbrute / permuted subdomainsDNS brute-force (top-110k by default; n0kovo 3M optional), permutation enrichment, and TLS SAN-on-CIDR — run in parallel per domain with per-domain watchdogs. Wildcards are tested first so you don't drown in false positives.
5 — Merge + Dedupeeverything abovemerged subdomain setCombines all the sources, normalises case, removes duplicates, and updates the per-org cache.
6 — Live Probemerged subdomainslive hostsProbes everything over HTTP/HTTPS (300 threads) and records status, title, and detected tech.
7 — Reportmerged subdomains + rejected roots~/Desktop/<Org>_domains.txtWrites the final report grouped by source domain, with live hosts at the end.

If you want ongoing coverage, you can also subscribe to CT logs and diff against the last run to catch new subdomains as they appear — see Continuous monitoring.

Running a single phase

# Phase 1 — root domain discovery
python3 scripts/domain_discovery.py \
  --org "Acme Corp" \
  --acquisitions "SubsidiaryA,SubsidiaryB,SubsidiaryC" \
  --abbreviations "acme,acmex" \
  --output /tmp/confirmed_domains.txt

# Phase 1.5 — ownership validation
python3 scripts/validate_ownership.py \
  --input /tmp/confirmed_domains.txt \
  --trusted acme.com \
  --slugs "acme,acmex" \
  --output /tmp/owned_domains.txt \
  --rejected /tmp/rejected_domains.txt

# Phase 2 — passive enumeration
python3 scripts/passive_enum.py \
  --domains "acme.com,acquired-co.com" \
  --output /tmp/passive.txt \
  --keys ~/.config/subdomain-recon/api_keys.yaml

# Phase 3 — advanced techniques (one domain at a time)
python3 scripts/advanced_techniques.py \
  --domain acme.com --org "Acme Corp" \
  --known-subs /tmp/passive.txt \
  --output /tmp/advanced.txt

# Phase 6 — live probe
python3 scripts/probe_live.py \
  --input /tmp/all.txt --output /tmp/live.txt --threads 300 --timeout 5

# Phase 7 — report
python3 scripts/write_report.py \
  --org "Acme Corp" \
  --domain-map "acme.com:Primary,acquired-co.com:Acquisition 2023" \
  --subdomain-files /tmp/all.txt \
  --rejected-file /tmp/rejected_domains.txt \
  --output ~/Desktop/Acme_domains.txt

Options reference

FlagRequiredDescription
--orgyesOrganisation name
--acquisitionsnoComma-separated subsidiary/brand names
--abbreviationsnoComma-separated short labels to expand
--outputyesOutput file of confirmed root domains
FlagRequiredDescription
--inputyesFile of confirmed root domains
--trustednoComma-separated roots treated as definitely owned
--slugsnoBrand labels for ownership signals (defaults to trusted roots' labels)
--outputyesOwned + uncertain roots
--rejectednoFile for parked/for-sale rejects (logged, not deleted)
--timeoutnoPer-request timeout (default 10s)
FlagRequiredDescription
--domainsyesComma-separated domains
--outputyesOutput file
--keysnoPath to api_keys.yaml
FlagRequiredDescription
--domainyesTarget domain
--orgnoOrganisation name
--outputyesOutput file
--probe-ipsnoKnown IPs for TLS pivot
--known-subsnoKnown subdomains file for subwiz ML

probe_live.py: --input --output --threads (300) --timeout (5) write_report.py: --org --domain-map --subdomain-files --rejected-file --output

Continuous monitoring

# Watch CT logs and get told about new subdomains
gungnir -d acme.com -o /tmp/ct_stream.txt &

# See what's new since the last scan
comm -13 <(sort /tmp/previous.txt) <(sort /tmp/all.txt) > /tmp/new_subdomains.txt

Things to know

  • The n0kovo 3M wordlist is slow over a home connection. Run it with --wildcard-batch 1000000.
  • JARM makes real TLS connections (10 hellos per host), so mind the rate limits.
  • Postman workspace scraping returns less than it used to since mid-2025, but it still finds things.
  • Merklemap doesn't cover Sunlight CT (the 2025 split). If that matters to you, add certstream-server-rust.
  • Cloud IP takeover signals (like EC2) are usually low impact — worth flagging, not worth chasing.

A note on scope

Only run this against assets you own or have explicit permission to test. Scanning systems you're not authorised to touch can be illegal where you live.

Author

Krutarth Shukla

Ver o original no GitHub

Bom para

Relacionados