feat(bpf): add runtime XDP/TC health checks before each scan

Long-lived processes (e.g. limpet-timing) create Engine once at startup
and reuse it for days. If XDP/TC detach after init (interface bounce,
admin removal, another XDP program), the BPF map silently returns None
for everything and all ports become "Filtered". This adds ~5ms pre-scan
verification via `ip link show` + `tc filter show` to fail hard instead
of producing silently wrong results.

- Add `BpfTimingCollector::verify_attached()` wrapping existing verify fns
- Add pre-scan health check in `ScanEngine::discover_bpf()`
- Add pre-timing health check in `collect_timing_samples_raw()`
- Fix README: remove stale userspace fallback references

Author: Simon Morley

README.md

@@ -21,7 +21,7 @@ What does TRS stand for? Temporal Resonance Scanner. You heard it here first.
 ## Features
 
 - **SYN scanner** — raw socket sender, no connection established
-- **XDP/BPF timing** — per-packet timestamps from the kernel bypass path; falls back to userspace `gettimeofday` when XDP is unavailable
+- **XDP/BPF timing** — per-packet timestamps from the kernel bypass path; requires Linux with BPF capabilities
 - **Stealth pacing** — configurable inter-packet delay to avoid triggering rate limits
 - **ML-ready output** — timing samples (not just a single RTT), mean/p50/p90 stats, and 64-dim embedding vectors for each port
 - **JSON output** — machine-readable results for pipelines
@@ -34,13 +34,13 @@ What does TRS stand for? Temporal Resonance Scanner. You heard it here first.
 
 | Requirement | Notes |
 |-------------|-------|
-| Linux kernel ≥ 5.11 | For BPF ring buffers; XDP timing degrades gracefully to userspace on older kernels |
+| Linux kernel ≥ 5.11 | For BPF ring buffers; fails hard if BPF unavailable |
 | `NET_RAW` + `NET_ADMIN` capabilities | Required for raw socket SYN scanning |
-| `CAP_BPF` + `CAP_SYS_ADMIN` | Required for XDP/BPF timing (not needed for userspace fallback) |
-| Bare-metal or KVM VM | AF_XDP requires a real NIC driver; Docker Desktop (macOS/Windows) will fall back to userspace timing |
+| `CAP_BPF` + `CAP_SYS_ADMIN` | Required for XDP/BPF timing (no unprivileged fallback) |
+| Bare-metal or KVM VM | AF_XDP requires a real NIC driver; cannot load BPF — limpet will not run |
 | Root or `sudo` | Easiest path; or grant caps with `setcap` |
 
-**Does not work on:** macOS, Windows, Docker Desktop (for BPF features — CLI builds but timing falls back to userspace).
+**Does not work on:** macOS, Windows, Docker Desktop (BPF programs cannot load — scanning unavailable).
 
 ---
 
@@ -259,9 +259,9 @@ curl -X POST http://localhost:8888/v1/timing \
 ## Limitations
 
 **Platform**
-- Linux only. The BPF/XDP path requires kernel ≥ 5.11 for ring buffers. Older kernels fall back to userspace timing automatically.
+- Linux only. The BPF/XDP path requires kernel ≥ 5.11 for ring buffers. Older kernels fail at BPF program load — no fallback.
 - AF_XDP requires a NIC driver with XDP support. Virtio-net (KVM/QEMU) works. VMware vmxnet3 and some cloud hypervisor NICs do not.
-- Docker Desktop on macOS/Windows: the CLI builds and runs but the BPF programs cannot load — timing falls back to userspace.
+- Docker Desktop on macOS/Windows: the CLI builds but the BPF programs cannot load — limpet will exit with an error.
 
 **Scanning**
 - **No service detection** — limpet identifies open ports and collects RTT samples. The `banner` field contains raw bytes from the server's first response packet, but there is no protocol parsing.
@@ -272,7 +272,7 @@ curl -X POST http://localhost:8888/v1/timing \
 
 **Timing precision**
 - XDP timestamps are recorded at NIC receive time, not in application code. This gives you real wire latency including NIC driver overhead, not software scheduling jitter.
-- Userspace fallback (`precision_class: "userspace"`) has ±50–200µs jitter under load — accurate enough for coarse fingerprinting, not for sub-millisecond jitter analysis.
+- No userspace timing fallback — all timing uses XDP kernel timestamps.
 - RTT samples include the full TCP handshake (SYN → SYN-ACK). This is intentional: handshake latency is the fingerprinting signal.
 
 **Permissions**
@@ -304,7 +304,7 @@ limpet/
 │   │   └── mod.rs
 │   └── timing/
 │       ├── xdp.rs          # BpfTimingCollector — XDP kernel-bypass timing
-│       ├── userspace.rs    # Fallback: connect(2) + gettimeofday timing
+│       ├── userspace.rs    # Raw SYN probe timing collection (BPF-backed)
 │       ├── embeddings.rs   # 64-dim feature vector extraction
 │       ├── stats.rs        # Mean / std / percentile helpers
 │       └── mod.rs

src/engine.rs

@@ -282,6 +282,25 @@ impl ScanEngine {
         ports: &[u16],
         start: Instant,
     ) -> ScanResult {
+        // Pre-scan BPF health check: verify XDP + TC are still attached.
+        // Catches detachment between engine creation and scan execution —
+        // the critical gap for long-lived processes (e.g. limpet-timing).
+        {
+            let bpf_guard = self.collector.lock().await;
+            if let Err(e) = bpf_guard.verify_attached() {
+                return ScanResult {
+                    request_id: request.request_id,
+                    target_ip,
+                    target_hostname,
+                    ports: vec![],
+                    duration_ms: start.elapsed().as_millis() as u64,
+                    backend: self.backend.as_str().to_string(),
+                    scanned_at: Utc::now(),
+                    error: Some(format!("BPF health check failed: {e}")),
+                };
+            }
+        }
+
         let batch_size = request.pacing.batch_size();
         let timeout_ms = request.timeout_ms;
         let timeout = Duration::from_millis(timeout_ms as u64);

src/timing/userspace.rs

@@ -89,6 +89,17 @@ pub async fn collect_timing_samples_raw(
     bpf: Arc<Mutex<BpfTimingCollector>>,
     scanner: Arc<Mutex<SynScanner>>,
 ) -> TimingResult {
+    // Pre-timing BPF health check: verify XDP + TC are still attached.
+    {
+        let bpf_ref = bpf.lock().await;
+        if let Err(e) = bpf_ref.verify_attached() {
+            return TimingResult::error(
+                request,
+                format!("BPF health check failed: {e}"),
+            );
+        }
+    }
+
     let addr = match resolve_address(&request.target_host, request.target_port) {
         Ok(addr) => addr,
         Err(e) => return TimingResult::error(request, format!("DNS resolution failed: {}", e)),

src/timing/xdp.rs

@@ -351,6 +351,19 @@ impl BpfTimingCollector {
     }
 }
 
+impl BpfTimingCollector {
+    /// Verify both XDP ingress and TC egress are still attached.
+    ///
+    /// Runs `ip link show` + `tc filter show` (~5ms overhead). Use this as a
+    /// pre-scan health check for long-lived processes where BPF programs may
+    /// detach after initial setup (interface bounce, admin removal, etc.).
+    pub fn verify_attached(&self) -> Result<(), BpfTimingError> {
+        verify_xdp_attached(&self.interface)?;
+        verify_tc_attached(&self.interface)?;
+        Ok(())
+    }
+}
+
 impl Drop for BpfTimingCollector {
     fn drop(&mut self) {
         // TC hooks persist after userspace exits, so we must explicitly detach