Professional README: logo, badges, architecture diagram; scrub test fixture id

reesepj · reesepj · commit ce009fc87572 · 2026-06-18T00:41:22.000-05:00
diff --git a/.github/assets/logo.jpg b/.github/assets/logo.jpg
diff --git a/README.md b/README.md
@@ -1,110 +1,152 @@
-<p align="center">
-  <img src="public/assets/brand/agentwall-logo-primary.svg" alt="Agentwall" width="360" />
-</p>
-
-# Agentwall
-
-**Runtime control for agentic AI.**
-
-Agentwall sits between AI agents and real-world action surfaces: shell commands, tools, network egress, browser actions, communication channels, identity, and content delivery.
-
-It answers one question before an agent acts:
-
-> Should this action be allowed, denied, redacted, or routed to a human?
-
-## Why it exists
-
-Agent prompts are not a security boundary. Agentwall enforces policy at runtime, where the risk becomes real.
-
-Core principles:
-
-- Least privilege by default
-- Default-deny egress
-- Human approval for high-risk actions
-- Communication-channel containment
-- Static command preflight before shell execution
-- Tamper-evident audit trails for operator review
+<p align="center"><img src=".github/assets/logo.jpg" width="120" alt="Agentwall"></p>
 
-## What ships now
+<h1 align="center">Agentwall</h1>
 
-- Policy evaluation API
-- DLP scanning for secrets and PII
-- Approval queue and operator controls
-- Telegram/channel guardrails
-- Damage Control bash/command preflight
-- Local Security Command Center dashboard
-- Watchdog and runtime health signals
-- Structured audit events and decision evidence
+<p align="center">Runtime firewall and operator console for AI agents.</p>
 
-## Dashboard
-
-Agentwall runs a local operator dashboard:
+<p align="center">
+  <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-22d3ee?style=flat-square&labelColor=0b0f14" alt="License: MIT"></a>
+  <img src="https://img.shields.io/badge/TypeScript-5.x-22d3ee?style=flat-square&labelColor=0b0f14&logo=typescript&logoColor=22d3ee" alt="TypeScript">
+  <img src="https://img.shields.io/badge/Node-%E2%89%A520-22d3ee?style=flat-square&labelColor=0b0f14&logo=node.js&logoColor=22d3ee" alt="Node >= 20">
+  <img src="https://img.shields.io/badge/Fastify-5.x-22d3ee?style=flat-square&labelColor=0b0f14&logo=fastify&logoColor=22d3ee" alt="Fastify 5">
+  <img src="https://img.shields.io/badge/status-active-22d3ee?style=flat-square&labelColor=0b0f14" alt="Status: active">
+  <a href="CONTRIBUTING.md"><img src="https://img.shields.io/badge/PRs-welcome-22d3ee?style=flat-square&labelColor=0b0f14" alt="PRs welcome"></a>
+</p>
 
-```text
-http://127.0.0.1:3015/dashboard
+---
+
+Agentwall sits between AI agents and the surfaces where their actions become real — shell commands, tools, network egress, browser actions, communication channels, identity, and content delivery. Before an agent acts, it answers one question: **should this action be allowed, redacted, routed to a human, or denied?** Prompts are not a security boundary; Agentwall enforces policy at runtime, where the risk is, and leaves a tamper-evident record an operator can review.
+
+## Features
+
+- **Deterministic policy engine** — every request is scored across six action planes (`network`, `tool`, `content`, `browser`, `identity`, `governance`) into one of four decisions (`allow` / `redact` / `approve` / `deny`). The highest-severity matching rule wins, and every decision returns the matched rule IDs, human reasons, risk level, and MITRE ATT&CK-mapped detections.
+- **Provenance- and flow-aware** — trust labels (`trusted` / `untrusted` / `derived`) and flow labels (`secret_material`, `pii`, `credential_access`, `destructive_action`, `payment`, `private_network_target`, …) drive high-risk detection, so untrusted content can't quietly escalate into privileged egress.
+- **DLP secret & PII scanning** — built-in detectors for AWS keys, GitHub PATs/OAuth tokens, OpenAI keys, Slack tokens, private keys, and JWTs, plus SSNs, credit cards, emails, and phone numbers — with inline redaction.
+- **Egress / SSRF firewall** — default-deny egress with scheme/port/host allowlists; blocks private, loopback, and link-local ranges and cloud metadata endpoints (`169.254.169.254`, `metadata.google.internal`).
+- **Human approval gate** — `auto` / `always` / `never` modes, a persistent approval queue, operator and channel notifications, and HMAC-signed, TTL-bound **capability tickets** minted on allow.
+- **Damage Control command preflight** — static analysis of shell/bash commands before execution, combined with the policy decision so risky commands escalate to a human.
+- **Communication-channel containment** — scoped guardrails for agent bots in shared Telegram/Slack/Discord chats: deny filesystem mutation and secret egress, redact PII in outbound replies.
+- **Runtime FloodGuard** — per-session and per-actor rate limits, pending-approval caps, cost budgets, one-command shield mode, and temporary session boosts.
+- **Tamper-evident audit** — SHA-256 hash-chained audit events plus OpenTelemetry (OTLP/HTTP) decision traces for downstream observability.
+- **Operator console & org control plane** — a local Fastify dashboard with live SSE updates, session containment (pause / resume / terminate), and a single-pane federation summary across multiple Agentwall instances via authenticated peer polling.
+- **Manifest integrity** — detects drift in tool/agent manifests against approved fingerprints.
+
+## Architecture
+
+The request → policy → decision → audit flow for a single agent action:
+
+```mermaid
+flowchart TD
+    A["Agent action request"] -->|"POST /evaluate"| B["Fastify server"]
+    B --> C{"FloodGuard<br/>rate &amp; cost limits"}
+    C -->|throttled| Z["Blocked &amp; audited"]
+    C -->|ok| D{"Session paused<br/>or terminated?"}
+    D -->|contained| Z
+    D -->|active| E["Policy engine"]
+
+    subgraph INPUTS["Evaluation inputs"]
+      direction LR
+      F["DLP scan<br/>secrets &amp; PII"]
+      G["Egress / SSRF<br/>inspector"]
+      H["Provenance &amp;<br/>flow labels"]
+      I["Built-in &amp; YAML<br/>policy rules"]
+    end
+    INPUTS --> E
+
+    E --> J{"Decision"}
+    J -->|allow| K["Issue capability ticket<br/>HMAC + TTL"]
+    J -->|redact| L["Return redacted content"]
+    J -->|approve| M["Approval queue"]
+    J -->|deny| N["Block action"]
+
+    M --> O["Operator console<br/>&amp; channel notifier"]
+    O -->|"approve / deny"| J
+
+    K --> P["Emit audit event"]
+    L --> P
+    N --> P
+    P --> Q["SHA-256 hash chain"]
+    P --> R["OTLP decision trace"]
+    P --> S["Runtime state<br/>dashboard &amp; org summary"]
 ```
 
-The dashboard is built around three surfaces:
-
-1. **Local Runtime**: service health, default-deny posture, approval mode, flood controls
-2. **Communication Guardrails**: scoped channel policies for agent bots in shared conversations
-3. **Bash Firewall**: preflight checks for risky shell commands before execution
-
-Advanced mode exposes policy, audit, federation, sessions, and diagnostic views.
+## Getting started
 
-## Quickstart
+Requires Node.js ≥ 20.
 
 ```bash
 git clone https://github.com/reesepj/agentwall.git
 cd agentwall
 npm install
 npm run build
+
+# scaffold config + policy, then start
 node dist/cli.js init --mode guarded --allow-hosts api.openai.com
 node dist/cli.js doctor
 node dist/cli.js start
 ```
 
-Run tests:
+The operator console is served at `/dashboard` on the configured host/port (default `http://127.0.0.1:3000/dashboard`).
 
 ```bash
-npm test
+npm run dev    # ts-node, no build step
+npm test       # Jest test suite
+npm run lint   # tsc --noEmit typecheck
 ```
 
-## Example policy posture
-
-```yaml
-policy:
-  defaultDecision: "deny"
-egress:
-  enabled: true
-  defaultDeny: true
-  allowPrivateRanges: false
-  allowedSchemes: ["https"]
-  allowedPorts: [443]
+Ask for a decision over HTTP:
+
+```bash
+curl -s http://127.0.0.1:3000/evaluate \
+  -H 'content-type: application/json' \
+  -d '{"agentId":"demo","plane":"network","action":"http_get",
+       "payload":{"url":"http://169.254.169.254/latest/meta-data/"},
+       "flow":{"direction":"egress"}}'
+# -> { "decision": "deny", "riskLevel": "critical", "matchedRules": ["net:block-ssrf-private","net:block-metadata-endpoint"], ... }
 ```
 
-## Main endpoints
+Core API surface:
 
 ```text
-POST /evaluate
-POST /inspect/content
-POST /integrations/communication-channel/guardrail
-POST /integrations/damage-control/command-preflight
-GET  /api/dashboard/state
+POST /evaluate                                          # policy decision (+ capability ticket)
+POST /inspect/content                                   # DLP secret/PII scan + redaction
+POST /inspect/network                                   # egress / SSRF inspection
+POST /inspect/manifest                                  # manifest drift detection
+POST /approval/request    GET /approval/pending         # approval queue
+POST /approval/:id/respond
+POST /integrations/communication-channel/guardrail      # channel containment
+POST /integrations/damage-control/command-preflight     # bash command firewall
+GET  /detections          GET /rules                    # decision catalog & active rules
+GET  /api/dashboard/state GET /api/dashboard/events     # operator console (state + SSE)
+GET  /api/org/summary                                   # federation single-pane summary
 ```
 
-## Docs
+## Tech stack
+
+| Layer | Choice |
+| --- | --- |
+| Language | TypeScript 5 (strict), Node.js ≥ 20 |
+| HTTP server | Fastify 5 |
+| Schema validation | Zod |
+| Logging | pino |
+| Config & policy | YAML (`js-yaml`) |
+| Crypto | Node `crypto` — HMAC capability tickets, SHA-256 audit chain |
+| Telemetry | OpenTelemetry OTLP/HTTP decision traces |
+| Tests | Jest + ts-jest |
+| Tooling | bundled `agentwall` CLI |
+
+## How it works
 
-- `docs/README.md`
-- `docs/architecture.md`
-- `docs/product-thesis.md`
-- `docs/threat-model.md`
-- `docs/tutorials/`
+A few load-bearing design decisions:
 
-## Boundary
+- **Enforce at the action surface, not in the model.** Agentwall is independent of the agent framework; it gates the moment an action would touch a real resource.
+- **Default-deny.** Unmatched actions and outbound egress are denied unless explicitly allowed, and a watchdog kill-switch fails closed (`deny_all`) when heartbeats go stale.
+- **Explainable decisions.** Results carry matched rule IDs, reasons, and ATT&CK-mapped detections — no opaque scores — so operators and audit logs agree on *why*.
+- **Tamper-evident by construction.** Audit events are hash-chained and capability tickets are signed, so allow decisions are verifiable after the fact.
+- **Operator-first.** Live dashboard, approval queue, FloodGuard shield, and per-session pause/resume/terminate give a human real-time containment controls.
 
-This repo is the local/open-source runtime control plane. Managed service operations, enterprise connectors, proprietary policy intelligence, and incident automation workflows belong outside the OSS core.
+Policy ships as a built-in rule pack plus hot-reloadable YAML, so posture can be tightened without a redeploy. See `examples/policy.yaml` and the `docs/` directory for threat model, architecture, and tutorials.
 
 ## License
 
-MIT
+MIT — see [LICENSE](LICENSE).
diff --git a/tests/org-control-plane.test.ts b/tests/org-control-plane.test.ts
@@ -62,7 +62,7 @@ describe("organization control plane", () => {
           lastAction: "credential_lookup",
           riskLevel: "critical",
           sessionIds: ["session-soc"],
-          userIds: ["telegram:8723371505"],
+          userIds: ["telegram:123456789"],
           roleIds: ["operator"],
         },
       ],
