Architecture¶

Overview¶

┌──────────────────────────────────────────────────┐
│                 AgentSniff CLI                   │
│      scan │ serve │ init-config │ update-sigs    │
├──────────┬───────────────────────┬───────────────┤
│ REST API │    Scanner Engine     │  Web Dashboard│
│ FastAPI/ │                       │  (HTML/JS/CSS)│
│ Axum     │                       │  embedded     │
├──────────┴───────────┬───────────┴───────────────┤
│              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 │ eBPF (v2)     │
├──────────────────────┴───────────────────────────┤
│              Target Network                      │
└──────────────────────────────────────────────────┘

v1 uses FastAPI + asyncio; v2 uses Axum + tokio. The dashboard HTML, signal/agent/scan-result JSON schemas, and on-disk SQLite schema are identical between the two so configuration, alert payloads, SARIF exports, and database history are interchangeable.

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: asyncio.create_task on v1, tokio::spawn via a JoinSet on v2
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

Storage Backends¶

v1 stores scan history in a single SQLite database at ~/.agentsniff/agentsniff.db. v2 keeps SQLite as the default and adds two extra backends behind the same StorageBackend trait:

Key Files¶

v1 (Python)¶

v2 (Rust)¶

ThirdKey Trust Stack¶

AgentSniff complements the ThirdKey trust infrastructure:

• AgentPin — Domain-anchored cryptographic identity for AI agents
• 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