Add synchronous fast-path blocklist enforcer (EPP) and update README

Implement a synchronous blocklist evaluator in the processor hot loop that
blocks known-bad IPs, CIDRs, domains, process names, file paths, and chain
patterns in sub-millisecond time — skipping both graph writes and LLM analysis.

README updates: new EPP section, Usage Guide (response modes, recommended
workflow, API examples), updated architecture diagram, pipeline flow, security
framework (9 defense-in-depth layers), Prometheus metrics, project structure,
test count (~550), and corrected default mode (passive). Retake three
screenshots with live agent data showing fast-path blocking in action.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: System Administrator

README.md

@@ -19,11 +19,11 @@ Built from scratch as a single-developer project. Combines real-time telemetry c
 │                                                                              │
 │  ┌─────────────┐   ┌──────────────┐   ┌──────────────┐   ┌──────────────┐  │
 │  │  Collectors  │──▶│  Normalizer  │──▶│  Processor   │──▶│  Graph DB    │  │
-│  │  (per-OS)   │   │  (OCSF)      │   │  (entities)  │   │  (Kuzu)      │  │
-│  └─────────────┘   └──────────────┘   └──────────────┘   └──────┬───────┘  │
-│        │                                                         │          │
-│        ▼                                                         ▼          │
-│  ┌─────────────┐   ┌──────────────────────────────────────────────────────┐ │
+│  │  (per-OS)   │   │  (OCSF)      │   │  (entities + │   │  (Kuzu)      │  │
+│  └─────────────┘   └──────────────┘   │   fast-path)  │   └──────┬───────┘  │
+│        │                               └──────┬───────┘          │          │
+│        ▼                                      │ (blocked)        ▼          │
+│  ┌─────────────┐   ┌──────────────────────────┼───────────────────────────┐ │
 │  │  SQLite     │   │                 LLM Analyzer                         │ │
 │  │  Queue      │   │  ┌──────────┐  ┌───────────┐  ┌──────────────────┐  │ │
 │  │  + Findings │   │  │ Preflight│─▶│ Tool-Use  │─▶│ Finding Builder  │  │ │
@@ -39,7 +39,7 @@ Built from scratch as a single-developer project. Combines real-time telemetry c
 │                                          │                                  │
 │                                          ▼                                  │
 │  ┌───────────────────────────────────────────────────────────────────────┐  │
-│  │                      Response Engine                                  │  │
+│  │                      Response Engine  ◀── fast-path (skip LLM)        │  │
 │  │  Severity ──▶ Baseline/Allow/Block ──▶ Approval ──▶ Execute ──▶ Audit │  │
 │  │                                                                       │  │
 │  │  Actions: Suspend │ Terminate │ Isolate Network │ Block IP            │  │
@@ -57,7 +57,7 @@ Built from scratch as a single-developer project. Combines real-time telemetry c
 
 1. **Collect** — Platform-native collectors gather process, network, file, DNS, and registry events
 2. **Normalize** — Raw events are standardized to OCSF (Open Cybersecurity Schema Framework)
-3. **Extract & Graph** — Entities (processes, IPs, domains, files) and relationships are written to a Kuzu property graph
+3. **Extract & Enforce** — Entities are extracted and checked against the synchronous fast-path blocklist. Matches are blocked instantly. Non-blocked entities are written to the Kuzu property graph
 4. **Analyze** — An LLM with tool-use capabilities investigates novel behaviors using graph context, threat intel, and external APIs
 5. **Respond** — A policy engine maps severity to actions, checks baselines/allowlists, requests approval, executes, and audits everything
 
@@ -163,6 +163,21 @@ A three-mode response engine that maps LLM severity verdicts to automated or sup
 
 **Protected process list** prevents the agent from terminating system-critical processes (`launchd`, `csrss.exe`, `systemd`, `sshd`, etc.) regardless of severity.
 
+### Synchronous Fast-Path Blocklist (EPP)
+
+The fast-path enforcer evaluates blocklist rules **synchronously in the processor pipeline**, immediately after entity extraction — before the event reaches the graph database or LLM analyzer.
+
+**How it works:**
+
+- Blocklist rules are compiled into O(1) in-memory structures: IP hash sets, domain hash sets, CIDR prefix lists, and glob pattern lists
+- On every event, entities are checked in evaluation order: **IPs → CIDRs → domains → process names → file paths → chain patterns**
+- On match: a CRITICAL finding is generated and the response engine is triggered immediately, **skipping both the graph write and LLM analysis**
+- The compiled rule set is thread-safe with periodic SQLite refresh (5s default) and instant invalidation when rules are added or removed via the dashboard
+
+**Why it matters:** Known-bad indicators (C2 IPs, malicious domains, prohibited process chains) are blocked in sub-millisecond time — no waiting for the LLM analysis cycle. This turns the EDR from a detect-and-alert system into a real-time enforcement point for known threats.
+
+The dashboard shows a **fast-blocked event counter** on the Overview tab when events have been blocked by this path.
+
 ### User Identity Enrichment
 
 Every process in the graph is linked to the user who spawned it. The agent resolves the owning user for each process via OS-level APIs (`stat /proc/<pid>` on Linux, `ps -o user=` on macOS, token query on Windows) and writes `(:User)-[:SPAWNED]->(:Process)` edges into the graph.
@@ -283,6 +298,7 @@ edr_llm_call_latency_seconds
 edr_llm_verdicts_total{severity}
 edr_dga_detections_total
 edr_persistence_detections_total{type}
+edr_events_fast_blocked_total
 edr_response_actions_total{action, result}
 edr_tamper_detections_total{event_type}
 edr_agent_uptime_seconds
@@ -311,19 +327,26 @@ macOS system tray icon provides live status, native notifications for HIGH/CRITI
 │  IOC matching │    │  Severity verdict + findings     │    │  Approval gate   │
 │  Code signing │    │                                  │    │  Action executor │
 └──────────────┘    └──────────────────────────────────┘    │  Audit trail     │
-                                                            └──────────────────┘
+                                                            └────────▲─────────┘
+                                                                     │
+┌───────────────────────────────────────────────────────────────┐    │
+│  Fast-Path Blocklist Enforcer (in Processor)                  │────┘
+│  IPs → CIDRs → domains → process names → file paths → chains │
+│  O(1) compiled in-memory structures, sub-ms evaluation        │
+└───────────────────────────────────────────────────────────────┘
 ```
 
 **Defense-in-depth layers:**
 
 1. **Collection** — Native OS APIs for high-fidelity telemetry (ETW, auditd, FSEvents, Unified Log)
 2. **Normalization** — OCSF standardization ensures consistent analysis regardless of platform
 3. **Graph Correlation** — Entity relationships reveal multi-step attack patterns invisible in flat logs
-4. **Real-Time Detection** — DGA, persistence, and IOC detectors catch known patterns immediately
-5. **AI Reasoning** — LLM analyzes novel behaviors with graph context and external intelligence
-6. **Response Orchestration** — Graduated actions (log → alert → suspend → terminate → isolate) with approval gates
-7. **Behavioral Baseline** — Learning mode builds a profile of normal behavior; active mode only responds to deviations
-8. **Self-Protection** — Tamper detection, protected process list, heartbeat monitoring
+4. **Real-Time Detection** — DGA, persistence, IOC, and fast-path blocklist detectors catch known patterns immediately
+5. **Fast-Path Enforcement** — Synchronous blocklist evaluates IPs, domains, CIDRs, process names, file paths, and chain patterns in the processor hot loop — blocking known threats instantly without LLM analysis
+6. **AI Reasoning** — LLM analyzes novel behaviors with graph context and external intelligence
+7. **Response Orchestration** — Graduated actions (log → alert → suspend → terminate → isolate) with approval gates
+8. **Behavioral Baseline** — Learning mode builds a profile of normal behavior; active mode only responds to deviations
+9. **Self-Protection** — Tamper detection, protected process list, heartbeat monitoring
 
 ---
 
@@ -341,7 +364,7 @@ macOS system tray icon provides live status, native notifications for HIGH/CRITI
 | Process Info | psutil |
 | macOS Tray | rumps |
 | Logging | structlog (JSON/text) |
-| Testing | pytest (~500 tests) |
+| Testing | pytest (~550 tests) |
 
 ---
 
@@ -360,7 +383,72 @@ export DEEPINFRA_API_KEY="your-key-here"
 sudo .venv/bin/python3 -m agent.main --config config.yaml --log-level INFO
 ```
 
-Dashboard opens at `http://localhost:9200`. The agent starts in **learning mode** by default — switch to **active** mode via the Settings tab when ready to enforce response actions.
+Dashboard opens at `http://localhost:9200`. The agent starts in **passive** mode by default — switch to **learning** to build a behavioral baseline, then **active** to enforce.
+
+---
+
+## Usage Guide
+
+### Response Modes
+
+The agent operates in one of three modes, switchable at runtime via the dashboard **Settings** tab or the API:
+
+| Mode | What happens on a threat | When to use |
+|------|-------------------------|-------------|
+| **Learning** | Records all observed behaviors to a baseline. No alerts, no enforcement. | First deployment — build a profile of normal activity before enabling detection. |
+| **Passive** | Generates findings and alerts (dashboard + tray notifications). No enforcement actions. | Day-to-day monitoring when you want visibility without automated response. |
+| **Active** | Evaluates findings against blocklist → allowlist → baseline → policy, then executes response actions (suspend, terminate, isolate, etc.) with approval gates. | Production enforcement — the agent actively responds to threats. |
+
+### Recommended Workflow
+
+1. **Start in Learning mode** — Let the agent observe normal behavior and build a baseline.
+   - **Development machines**: 24 hours is usually sufficient
+   - **Servers / production hosts**: 1–7 days to capture periodic jobs, maintenance windows, and varied workloads
+2. **Switch to Passive mode** — Review findings in the dashboard. Add allowlist rules for known-good behaviors that generate false positives. Add blocklist rules for known-bad indicators you want blocked immediately.
+3. **Switch to Active mode** — The agent now enforces. Baselined behaviors are silently passed, allowlisted behaviors are skipped, blocklisted behaviors are blocked instantly (via the fast-path enforcer), and novel threats go through the LLM → policy → approval → action pipeline.
+
+### Switching Modes
+
+**Dashboard:** Settings tab → Response Mode dropdown → select mode.
+
+**API:**
+```bash
+curl -X POST http://localhost:9200/api/response/mode \
+  -H 'Content-Type: application/json' \
+  -d '{"mode": "active"}'
+```
+
+### Adding Blocklist / Allowlist Rules
+
+**Dashboard:** Settings tab → scroll to Blocklist or Allowlist section → fill in rule type, pattern, and optional chain filter → Add.
+
+**API:**
+```bash
+# Block a specific IP
+curl -X POST http://localhost:9200/api/response/blocklist \
+  -H 'Content-Type: application/json' \
+  -d '{"rule_type": "dst_ip", "pattern": "203.0.113.50", "description": "Known C2 server"}'
+
+# Block a process chain pattern
+curl -X POST http://localhost:9200/api/response/blocklist \
+  -H 'Content-Type: application/json' \
+  -d '{"rule_type": "chain_pattern", "pattern": "** > curl > sh", "description": "Pipe curl to shell"}'
+
+# Allowlist a known-good connection with chain scope
+curl -X POST http://localhost:9200/api/response/allowlist \
+  -H 'Content-Type: application/json' \
+  -d '{"rule_type": "dst_ip", "pattern": "18.97.36.79", "chain_filter": "launchd > Claude", "description": "Claude → Anthropic API"}'
+```
+
+Rule types: `dst_ip`, `dst_cidr`, `domain`, `process_name`, `file_path`, `chain_pattern`. See [Chain-Aware Allow/Block Rules](#chain-aware-allowblock-rules) for the full chain pattern syntax.
+
+### What Happens When a Threat Is Detected
+
+| Stage | Learning | Passive | Active |
+|-------|----------|---------|--------|
+| Fast-path blocklist match | Skipped | Alert only | **Block immediately** — CRITICAL finding + response action |
+| LLM severity verdict | Recorded to baseline | Finding + alert | Finding → blocklist → allowlist → baseline → policy → approval → action |
+| Response action execution | Never | Never | Executes (with approval gate for destructive actions unless `auto_respond` is enabled) |
 
 ---
 
@@ -374,7 +462,7 @@ edr-graph/
 │   ├── collectors/             # 10+ platform-native event sources
 │   ├── normalizer/             # OCSF normalization (6 event types)
 │   ├── schema/                 # Kuzu DDL, SQLite DDL, OCSF types
-│   ├── processor/              # Entity extraction → graph writes
+│   ├── processor/              # Entity extraction, fast-path enforcement → graph writes
 │   ├── graph/                  # Attack chain queries
 │   ├── analyzer/               # LLM tool-use analyzer + preflight
 │   ├── analysis/               # Lightweight detectors (DGA, persistence)
@@ -384,7 +472,7 @@ edr-graph/
 │   ├── dashboard/              # FastAPI server + SPA frontend
 │   ├── platform/               # Tamper detection, Windows service
 │   └── tray/                   # macOS menu bar integration
-├── tests/                      # 40 test modules, ~500 tests
+├── tests/                      # 42 test modules, ~550 tests
 ├── config.yaml                 # Runtime configuration
 └── README.md
 ```

agent/dashboard/server.py

@@ -107,6 +107,12 @@ async def get_status():
             if sample.name == "edr_events_dropped_total":
                 events_dropped += int(sample.value)
 
+    events_fast_blocked = 0
+    for metric in metrics.events_fast_blocked.collect():
+        for sample in metric.samples:
+            if sample.name == "edr_events_fast_blocked_total":
+                events_fast_blocked += int(sample.value)
+
     return {
         "agent_status": "paused" if _state["paused"] else "running",
         "uptime_seconds": round(uptime, 1),
@@ -115,6 +121,7 @@ async def get_status():
         "events_dropped": events_dropped,
         "events_per_second": round(events_processed / max(uptime, 1), 1),
         "queue_depth": queue.count_unprocessed(),
+        "events_fast_blocked": events_fast_blocked,
     }
 
 
@@ -882,6 +889,10 @@ async def add_blocklist_rule(body: dict):
     except Exception:
         logger.exception("Failed to add blocklist rule")
         raise HTTPException(500, "Failed to add blocklist rule") from None
+    # Invalidate fast-path blocklist enforcer cache
+    fb = _state.get("fast_blocklist")
+    if fb:
+        fb.invalidate()
     return {"status": "ok", "rule_id": rule_id}
 
 
@@ -893,6 +904,10 @@ async def delete_blocklist_rule(rule_id: int):
         raise HTTPException(503, "Blocklist not initialized")
     if not blocklist.remove_rule(rule_id):
         raise HTTPException(404, "Rule not found")
+    # Invalidate fast-path blocklist enforcer cache
+    fb = _state.get("fast_blocklist")
+    if fb:
+        fb.invalidate()
     return {"status": "ok"}
 
 

agent/dashboard/static/index.html

@@ -890,14 +890,15 @@
 
 // ── Settings ───────────────────────────────────────────────────
 async function refreshSettings() {
-  const [data, iocStats, modeData, baselineStats, allowlistData, blocklistData, netStatus] = await Promise.all([
+  const [data, iocStats, modeData, baselineStats, allowlistData, blocklistData, netStatus, statusData] = await Promise.all([
     api('/api/settings'),
     api('/api/intel/ioc-stats'),
     api('/api/response/mode'),
     api('/api/response/baseline/stats'),
     api('/api/response/allowlist'),
     api('/api/response/blocklist'),
     api('/api/response/network-status'),
+    api('/api/status'),
   ]);
   if (!data || Object.keys(data).length === 0) { document.getElementById('settings-content').innerHTML = '<div class="empty-state">Settings not available</div>'; return; }
   const groups = {
@@ -940,6 +941,9 @@
   if (allowlistData && allowlistData.rules) {
     html += '<div style="color:var(--dim);font-size:13px;margin-top:4px">Allowlist: <strong style="color:var(--text)">' + allowlistData.rules.length + '</strong> rules</div>';
   }
+  if (statusData && statusData.events_fast_blocked > 0) {
+    html += '<div style="color:var(--dim);font-size:13px;margin-top:4px">Fast-blocked: <strong style="color:var(--critical)">' + fmtNum(statusData.events_fast_blocked) + '</strong> events</div>';
+  }
   html += '<div style="margin-top:8px"><button class="btn btn-danger" style="font-size:11px" onclick="clearBaseline()">Clear Baseline</button></div>';
   html += '</div></div>';