Recon — Pipeline (tools/recon/)

Canonical recon implementation. tools/recon_pipeline.py is a deprecated shim re-exporting these modules. ReconConfig.from_config is the sole config entry point. See the family overview for enrichers, OSINT, diff, fast preset, socket fallback, and privilege handling.

Architecture

ReconPipeline.recon_host(target)            # pipeline.py:36
  → preflight probe (opt-in)                # probe_reachable; False+large sample = skip, None/small = proceed
  → PrimaryReconScanner.scan_host(target)   # scanner.py:160
      nmap → rustscan+nmap → masscan+nmap → python socket_scan
  → SecondaryEnumerator.enumerate_host(result)  # enumerator.py:33 (only if open_ports and parallel_secondary)
      per-service-family coroutines, semaphore-bounded, mutate result in place
  → get_attack_surface_summary(result)      # pipeline.py:113 (find_modules top-10)

Standalone additive path: ReconPipeline.recon_udp → PrimaryReconScanner.recon_udp → _run_nmap_udp (UDP only, no TCP scan, no secondary enumerators).

Package map

ReconPipeline (pipeline.py:23)

def __init__(self, config: ReconConfig | None = None) -> None
async def recon_host(self, target: str) -> HostReconResult
async def recon_hosts(self, targets: list[str]) -> list[HostReconResult]
async def recon_udp(self, target: str, top_ports: int | None = None) -> HostReconResult
def get_attack_surface_summary(self, result: HostReconResult) -> dict[str, Any]

Lifecycle of recon_host:

1. Optional preflight (preflight_probe): bare TCP probe_reachable on preflight_ports before the expensive scan. False (all refused) skips the full scan only when the probe set is at least COMMON_PORTS-sized; small-sample refused and None (timeout/filtered ambiguity) fall through to the normal scan. A skipped host returns an empty HostReconResult with an error note.
2. Primary: self._primary.scan_host(target). Empty open_ports returns early (no secondary enumeration).
3. Secondary: self._secondary.enumerate_host(result) when parallel_secondary is true.
4. scan_duration clamped to a minimum of 0.0001s.

recon_hosts runs recon_host per target under asyncio.gather with return_exceptions=True. recon_udp defaults top_ports to udp_top_ports and delegates to the primary scanner. get_attack_surface_summary groups services by name and emits services_by_name, high_value_targets (ssh/rdp/smb), credential_targets, web_targets (http/https with headers/dirs/vulns from svc.scripts), lateral_movement_targets (smb/ldap), privilege_escalation_hints (docker ports 2375/2376/10250), and recommended_attack_modules (top 10 from find_modules).

PrimaryReconScanner (scanner.py:154)

def __init__(self, config: ReconConfig) -> None
async def scan_host(self, target: str) -> HostReconResult
async def recon_udp(self, target: str, top_ports: int = 100) -> HostReconResult
async def _run_nmap(self, target: str) -> HostReconResult | None
async def _run_nmap_udp(self, target: str, top_ports: int = 100) -> HostReconResult | None
async def _run_rustscan(self, target: str) -> HostReconResult | None
async def _run_masscan(self, target: str) -> HostReconResult | None

Command runner:

async def run_command(cmd: list[str], *, timeout: int = 300, max_retries: int = 2,
                      retry_delay: float = 5.0, cwd: Path | None = None,
                      env: dict[str, str] | None = None,
                      capture_output: bool = True) -> tuple[bool, str, str, float]

Retries with exponential backoff (retry_delay *= 1.5) but short-circuits privilege errors (is_privilege_error) and _NON_RETRYABLE_EXIT_CODES (127, 126, 9009, 3221225477/86/76). Timeout kills the whole process group via _kill_process. Returns (success, stdout, stderr, elapsed).

SecondaryEnumerator (enumerator.py:27)

def __init__(self, config: ReconConfig) -> None
async def enumerate_host(self, primary_result: HostReconResult) -> HostReconResult

enumerate_host builds one coroutine per detected service family, wraps each in a semaphore gate (max_concurrent_secondary), and gathers with return_exceptions=True. Coroutines mutate the shared result in place (no merge step); exceptions become result.errors entries. Families:

Additive extended_enumerators block (production default on via from_config; dataclass default off):

Depth flags (each opt-in, writes result.extended[key], never raises): _enumerate_subdomains (crt.sh → extended["subdomains"]), _enumerate_vhosts (Host rotation → extended["vhosts"]), _enumerate_waf (header heuristics → extended["waf"]), _enumerate_asn_whois (RDAP → extended["asn"]), _enumerate_cloud_metadata (operator-box IMDS probe → extended["cloud_metadata"]), _enumerate_snmp (snmpwalk public → extended["snmp"]), _enumerate_dns_zone_transfer (dig AXFR → extended["dns_zone"]). HTTP ones take injectable fetch_fn, subprocess ones run_fn, so tests need no live network. Implementation note: per-service fan-out comments in the source describe serial-to-parallel refactors; exact concurrency bounds follow the shared semaphore above.

ReconConfig keys (config.py:199)

@classmethod
def from_config(cls, config: dict | None, **overrides: Any) -> "ReconConfig"

from_config reads the nmap section (path/sudo/priv_fallback) and the recon section (everything else); explicit kwargs win. _concurrency_from_config resolves recon.max_concurrent_secondary, else recon.fast.service_concurrency, default 3, minimum 1.

Data structures: ServiceInfo (port, protocol, service, version, banner, cpe[], scripts{}, ssl_info, smtp_info, db_info, os_guess, confidence, technologies[], to_dict/from_dict tolerant of missing keys); HostReconResult (target_ip, hostname, os_name/family/accuracy, ttl, mac/vendor, services[], open/filtered/udp_ports[], scan_duration/tool/raw_output — raw_output dropped on from_dict round-trip for resume — evidence_refs, errors/warnings, spider_results[], osint{}, ipv6_addresses[], extended{}, plus get_services_by_name/port, has_service/port); ToolAvailability.check(tool_name) (shutil.which cache) / reset().

Examples

from tools.recon.config import ReconConfig
from tools.recon.pipeline import ReconPipeline

pipeline = ReconPipeline(ReconConfig.from_config(config, aggression_level="normal"))
result = await pipeline.recon_host("10.0.0.50")
udp = await pipeline.recon_udp("10.0.0.50")          # additive UDP pass only
summary = pipeline.get_attack_surface_summary(result) # high-value/web/cred targets + top-10 modules

multi = await ReconPipeline().recon_hosts(["10.0.0.50", "10.0.0.51"])

from tools.recon.config import ReconConfig

cfg = ReconConfig.from_config(
    {"nmap": {"sudo": True}, "recon": {"extended_enumerators": False}},
    aggression_level="stealth",
)

Related documentation

• Recon overview
• Kernel gates
• Kernel overview
• MCP tools
• Architecture

Source map

• tools/recon/pipeline.py
• tools/recon/scanner.py
• tools/recon/enumerator.py
• tools/recon/config.py
• tools/recon_pipeline.py
• tools/recon_enrichers.py
• tools/recon_osint.py
• tools/socket_scan.py
• tools/nmap_priv.py