Architecture

How AgentWard Works

AgentWard sits between your agent and its tools as a transparent proxy, enforcing declarative policies at the code level — completely outside the LLM context window.

The key principle: Policies are enforced in middleware, in code, before the tool call reaches the underlying server. The LLM never sees the policy rules and cannot override them — even under prompt injection or agent reasoning errors.

Two Modes

Compile-time analysis. Runtime enforcement.

Both use the same agentward.yaml policy file. They serve different purposes and run at different times.

Compile-Time · Static Analysis

Before your agent runs

Scans skill definitions, MCP configs, and tool declarations. Generates permission maps, smart-default policies, and compliance delta reports.

agentward scan Discover and risk-rate all tools
agentward configure Generate policy YAML from scan
agentward comply Evaluate against HIPAA / SOX / GDPR / PCI-DSS
Runtime · Live Enforcement

While your agent runs

MCP or HTTP proxy intercepts every tool call in real time. Evaluates against policies: ALLOW, BLOCK, REDACT, APPROVE, LOG. Generates structured audit trail.

agentward inspect Start the enforcement proxy
agentward status Live stats from running proxy
agentward audit View structured decision logs
Architecture

Three universal interception points.

The same policy YAML works across all three. AgentWard is framework-agnostic — it intercepts at the protocol level, not the application level.

AGENT HOSTS Claude Desktop Claude Code Cursor Windsurf VS Code OpenClaw UI API Clients JSON-RPC 2.0 (stdio) POST /tools-invoke (HTTP) AGENTWARD — PERMISSION ENFORCEMENT LAYER Stdio Proxy MCP JSON-RPC 2.0 · subprocess mgmt tools/call · tools/list · resources/read HTTP Reverse Proxy Gateway interception + WebSocket POST /tools-invoke policy check agentward.yaml Declarative policy rules ALLOW · BLOCK · REDACT · APPROVE · LOG Policy Engine ALLOW BLOCK REDACT APPROVE LOG Data Classifier SSN · CC · API keys · PHI Audit Logger Structured JSON Lines log MCP SERVERS & TOOLS filesystem shell-executor email-manager web-browser github postgres Python SDK tools OpenAI · LangChain · CrewAI Function middleware coming soon
Four Stages

The full pipeline, step by step.

Each stage can be run independently, or run agentward init to go through all four interactively.

1
agentward scan LIVE

Scan — Build a permission map

Auto-discovers all tool sources: MCP configs (Claude Desktop, Cursor, Windsurf, VS Code), Python source files (OpenAI, LangChain, CrewAI, Anthropic SDKs), and OpenClaw/ClawdBot skills. Enumerates tools from live MCP servers via subprocess + JSON-RPC handshake. Produces a risk-rated permission map with use-case-aware recommendations.

  • Per-tool: data access types, external connections, stored credentials, interaction triggers, risk rating (LOW / MEDIUM / HIGH / CRITICAL)
  • Dangerous skill chain detection — lateral data movement paths: email + browser, shell + network, finance + outbound — 9 built-in patterns
  • Use-case recommendations: "This email skill has write access — set read-only if you only need triage"
  • Outputs: rich CLI table, shareable HTML report, SARIF for GitHub Security tab, JSON for CI pipelines
2
agentward configure LIVE

Configure — Generate smart-default policies

Generates an agentward.yaml based on scan results and detected use-case patterns. Tailors defaults to what you actually have installed.

  • Email + Calendar → read-only email, no cross-skill chaining to browser (blocks lateral movement to browsing tools), require approval for send
  • Dev tools (GitHub, shell) → allow code ops, block files outside project dirs, log all shell commands
  • Finance tools → block all outbound network, restrict reads to finance dirs, no skill chaining (full lateral movement isolation)
  • Research/browsing → allow web, block email/files/credentials
3
agentward inspect LIVE

Inspect — Runtime enforcement proxy

Starts the MCP stdio proxy or HTTP reverse proxy with full policy enforcement. Every tool call is intercepted before it reaches the underlying server.

  • Policy enforcement: ALLOW / BLOCK / REDACT / APPROVE (human-in-the-loop) / LOG per tool call
  • Data classification: Tier 1 regex (SSN, credit cards, CVV, API keys) always on; Tier 2 distilled transformer (~50ms) optional
  • Skill chaining enforcement — controls lateral data movement between agent-accessible tools: CONTENT mode (detects data flowing between skills) + BLANKET mode (blocks all cross-skill triggers)
  • Human-in-the-loop gates: macOS dialog + Telegram remote approval with session caching
  • Structured JSON Lines audit log with every decision, timestamp, and tool arguments
  • LLM API proxy mode: intercepts Anthropic/OpenAI tool_use calls before the agent acts
4
agentward comply LIVE

Comply — Regulatory compliance evaluation

Evaluates your current agentward.yaml against regulatory frameworks and generates a compliance delta report with specific gaps and auto-fix suggestions.

  • HIPAA Security Rule: 8 controls — Access Control §164.312(a)(1), Data Boundary, Audit Controls, Integrity, Authentication, Transmission Security, Information Access Management, Zero-Trust Default
  • SOX Section 404: 8 controls — Access Control, Data Boundary, Audit Trail, Integrity, Authorization, Network Segregation, Segregation of Duties, Zero-Trust Default
  • GDPR Key Articles: 8 controls — Data Minimisation (Art. 5), Protection by Design (Art. 25), Records of Processing (Art. 30), Integrity (Art. 32), Confidentiality (Art. 32), Transmission Security (Art. 32), Processor Obligations (Art. 28), Accountability (Art. 5)
  • PCI-DSS v4.0: 8 controls — Restrict Access (Req. 7), CDE Boundary (Req. 7), Log & Monitor (Req. 10), Protect Stored Data (Req. 3), Authentication (Req. 8), Network Segmentation (Req. 1), Least Privilege (Req. 7), Secure Default (Req. 6)
  • --fix flag: auto-generates a corrected policy YAML with all required changes applied
Proxy Modes

Two interception transports.

Both modes use the same policy YAML. Choose based on how your agent connects to its tools.

MCP STDIO

Stdio Proxy

Sits between the agent host and MCP server subprocess. The agent thinks it's talking directly to the MCP server; the server thinks it's talking to the agent. Every tools/call is intercepted and evaluated.

Works with: Claude Desktop, Claude Code, Cursor, Windsurf, VS Code, OpenClaw

HTTP GATEWAY

HTTP Reverse Proxy

Swaps the ClawdBot gateway port so AgentWard listens on the original port and forwards to the gateway on a new port. Intercepts POST /tools-invoke. All other traffic including WebSocket (for the ClawdBot UI) passes through transparently.