feat(asm): attack-surface management — external discovery, continuous monitoring, engagement

[ehartford]

Ports the discovery/continuity/engagement ideas from Sn1per into Clearwing — reimagined agentically and feeding Clearwing's existing deep scanning/verification, without copying Sn1per's shallow version-only detection (the false-positive firehose Clearwing exists to avoid).

Why

Clearwing is deep on a known target but had no way to discover what's out there, track what changes over time, or organize a surface across runs. scanner_tools only scans a host you already supply. This adds the missing front half.

What (new clearwing/asm/ subsystem + clearwing asm command)

Layer	Module	Notes
Asset inventory	assets.py / scope.py	Scope-keyed SQLite store modeled on HistoricalFindingsDB; record_observations returns only the new assets (delta detection).
Discovery	discovery.py + agent/tools/recon/discovery_tools.py	Passive-first, host-safe @tools: crt.sh cert transparency, Wayback, optional GitHub/Shodan/Censys, DNS resolution, HTTP liveness + tech fingerprint, screenshot gallery. Projected into the knowledge graph.
Continuous monitor	monitor.py	Poll loop (modeled on CommitMonitor): discover → delta → ASSET_DISCOVERED → scan new hosts. Never exploits or triggers approval-gated actions automatically.
Notifications	notify.py	Outbound Slack/webhook (the missing outbound half), subscribing to ASSET_DISCOVERED/FINDING_RECORDED, best-effort.
Threat intel	threatintel.py	CISA KEV + EPSS enrichment; findings sort KEV-first.
Mass sweep	sweep.py	Parallel port/service/vuln scan across a discovered surface.
Modes	modes.py	Named playbooks: recon, stealth, web-assessment, external-sweep.
Reporting	report.py	Per-scope aggregate markdown/json.

Wiring (additive, with baselines updated): an asm config section; EventType.ASSET_DISCOVERED + payload; knowledge-graph entity/relationship types (domain/subdomain/url/technology); the discovery tool category in get_all_tools(); the asm CLI subcommand (scan/monitor/sweep/report/list); read-only web endpoints + a WebSocket event.

Design choices

• Passive-first / host-safe. Discovery queries public archives (crt.sh, Wayback, KEV, EPSS) exactly like the existing NVD/CVE lookups; light active steps (DNS, HTTP liveness) match proxy_request/scan_ports. Heavy active enum is left to the Kali container. ASM never auto-exploits.
• Delta store vs. graph. The SQLite AssetStore is authoritative for "what's new since last run"; the knowledge graph is a queryable/visualizable projection.
• No new scheduler. asm monitor is a poll loop (daemon or --once for cron / clearwing schedule) — the repo has no scheduler library.

Tests / docs

48 focused ASM tests (store delta, discovery, monitor, notifier, threat-intel, sweep, modes, report, CLI) — all green, plus shared-file regressions (events, tool registry, knowledge, config, webui, scanner, reporting) pass; ruff clean; two baseline tests updated for the new event + 6 new tools. Docs: docs/asm.md, a docs/cli.md section, README, mkdocs nav.

Note

This is a large single PR (~2.8k lines) by request — organized so each layer is an independent module with its own tests. Happy to split if the team prefers.