Architecture¶

Overview¶

┌──────────────────────────────────────────────────┐
│                 AgentSniff CLI                   │
│         agentsniff scan | serve                  │
├──────────┬───────────────────────┬───────────────┤
│ REST API │    Scanner Engine     │  Web Dashboard│
│ (FastAPI)│                       │  (HTML/JS/CSS)│
├──────────┴───────────┬───────────┴───────────────┤
│              Signal Correlator                   │
│     Groups signals by host, calculates scores    │
├─────┬─────┬─────┬─────┬─────┬─────┬─────┬────────┤
│ DNS │Port │Agent│ MCP │ EP  │ TLS │Traf.│  SSE   │
│ Mon │Scan │Pin  │ Det │Probe│ FP  │Anlz │  Det   │
├─────┴─────┴─────┴─────┴─────┴─────┴─────┴────────┤
│         Integrations (optional)                  │
│      Zeek DataSource │ nmap Enricher             │
├──────────────────────┴───────────────────────────┤
│              Target Network                      │
└──────────────────────────────────────────────────┘

Scan Pipeline¶

1. Target resolution — CIDR expanded to host IPs, DNS resolution
2. Detector setup — Each detector initializes (e.g., traffic analyzer resolves LLM API IPs)
3. Concurrent detection — All detectors run in parallel via asyncio.create_task
4. Signal correlation — Signals grouped by host IP, agents enriched as signals arrive
5. Fusion rules — Cross-module rules applied (e.g., banner corroboration)
6. nmap enrichment (optional) — Post-scan service identification
7. Result assembly — Agents sorted by confidence, status assigned

Signal Correlation¶

Signals from all detectors are grouped by source host IP. Each host with at least one signal becomes a DetectedAgent.

Confidence Scoring¶

Confidence is calculated using noisy-OR probability fusion:

P = 1 - ∏(1 - p_i)

Where p_i is the confidence weight of each signal:

Example: A host with one HIGH signal (0.8) and one MEDIUM signal (0.5) gets:

P = 1 - (1 - 0.8) × (1 - 0.5) = 1 - 0.1 = 0.90

Status Assignment¶

Fusion Rules¶

Cross-module rules that adjust confidence based on signal combinations:

• Banner corroboration — Port scanner banner matches an agent framework → boost port scanner signal from LOW to MEDIUM
• nmap exclusion — Non-agent service identified → downgrade to INFO (only if port scanner is the sole signal)
• nmap boost — Agent-like service confirmed → add corroborating NMAP_ENRICHER signal

Integration Patterns¶

DataSource (Zeek)¶

Replaces "how we observe" without changing "what we look for":

ZeekDataSource → load_traffic() → TrafficRecord list → TrafficAnalyzer
ZeekDataSource → load_dns()     → DnsRecord list     → DnsMonitor
ZeekDataSource → load_tls()     → TlsRecord list     → TlsFingerprint

Enricher (nmap)¶

Post-processing step after detection and correlation:

Detectors → Signals → Correlation → Fusion → nmap Enricher → Final Result

Key Files¶

ThirdKey Trust Stack¶

AgentSniff complements the ThirdKey trust infrastructure:

• AgentPin — Cooperative agent discovery via cryptographic identity documents
• SchemaPin — Verified tools detected on MCP servers can be cross-checked against SchemaPin signatures
• Symbiont — AgentSniff can run as a Symbiont agent with policy-enforced scanning boundaries
• AgentNull — Detection evasion research feeds back into scanner improvements