Concepts Overview

Govrix Scout enforces compliance and policy on every token that flows through the proxy. The five core concepts below form the foundation of how it works.

All features listed here are implemented and active in the OSS Scout build. No feature is SaaS-only or a stub.

Feature summary

Concept	What it does	Status
Session Forensics	Attaches session ID, timestamp, SHA-256 Merkle lineage hash, and compliance tag to every event for immutable audit trails	Active
PII Detection	Detects 5 PII types (email, phone, SSN, credit card, IP address) in request and response payloads in under 1ms	Active
Kill Switch	Blocks any agent instantly at the proxy hot path — no redeploy required — returning HTTP 403	Active
Budget Enforcement	Enforces per-agent and global daily token/cost caps; persisted in `budget_daily` table; returns HTTP 429 when exceeded	Active
YAML Policy Engine	Evaluates declarative YAML rules (6 operators, 5 fields, 3 actions) against every request/response	Active

How the pieces fit together

Every request that enters the proxy on port 4000 goes through the following sequence:

Kill switch check — interceptor.rs queries the agent registry; blocked agents are rejected immediately with HTTP 403.
Budget check — in-memory counters (loaded from budget_daily at startup) are compared against per-agent and global caps.
Policy evaluation — the YAML policy engine evaluates all matching rules against the request fields.
PII scan — request payload is scanned for the 5 PII types; the pii_detected flag is set on the event.
Upstream forward — the request is forwarded to the LLM provider; the response is streamed back to the caller.
Event write — an AgentEvent is emitted fire-and-forget to the bounded channel; the background batch writer persists it to PostgreSQL within 100ms.
Session record — SessionRecorder appends the event to the session trace.

The critical constraint is that steps 1 and 2 are the only ones that can return an error to the caller. Steps 6 and 7 are never awaited on the hot path.