Guardrails

How the Guard Module intercepts and governs every LLM tool call before execution.

How it works

Every tool call passes through a single gate, the Admission Controller, before reaching the OS. There is no path around it.

LLM output
    |
    v
Spotlighting
    |
    v
Pre-filter classifier
    |
    v
Rate limiter
    |
    v
Admission Controller
    |
    +-- DENY -> denial trace emitted
    |           evidence_hash + policy_version_id + decision_trace_id
    |           has_forensic_payload: true
    |
    +-- ALLOW -> tool executes
                full audit telemetry recorded

If any component in the evaluation path raises an unhandled exception, the decision is DENY. The tool never executes. The failure produces a context-bound GUARD_INTERNAL_ERROR deny with evidence_hash and has_forensic_payload: true.

The seven invariants

INV-1 - Single execution gate

No direct path from LLM output to tool execution. The Admission Controller is the only dispatch path.

INV-2 - Dual gate requirement

Policy decides intent. Authorization decides capability. Execution requires both.

INV-3 - Per-step enforcement

The Admission Controller runs per tool call, per agent step, after planning and before execution.

INV-4 - Untrusted executor model

The LLM produces candidates. The control plane decides outcomes. LLM confidence is not a security property.

INV-5 - Spotlighting before policy

Content is trust-tagged before policy evaluation. Untrusted content cannot promote its own trust level.

INV-6 - Boolean execution condition

execute = (policy == ALLOW) AND (admission == PASS). A partial pass is a block.

INV-7 - Deterministic forensic trace

Every deny response surfaced to the caller carries evidence_hash, has_forensic_payload: true, policy_version_id, and decision_trace_id. CI enforces this across the deny surface.

Admission Controller checks

Each tool call passes sequential checks. Failure at any check returns DENY immediately.

Check	What it evaluates	Reason codes on failure
0. Rate limiter	Call rate per session before expensive evaluation	RATE_LIMIT_EXCEEDED
1. Tool registration	Tool must be registered	TOOL_NOT_REGISTERED
2. Lockdown and capability	Capability gate for the requested action	LOCKDOWN_RESTRICTED, CAPABILITY_MISSING
3. Object ownership (BOLA)	Caller must own the target object	BOLA_VIOLATION
4. Role authorization (BFLA)	Caller role must satisfy tool required_role	BFLA_VIOLATION
5. Semantic and request risk	Semantic threats, shell injection, SSRF, segmented-input safety, obfuscated payloads	SEMANTIC_THREAT_DETECTED, MCP_SHELL_INJECTION_BLOCKED, SENSITIVE_PATH_BLOCKED, EXTERNAL_DOMAIN_BLOCKED, PRIVATE_IP_BLOCKED, OBFUSCATED_SHELL_INJECTION, PARAM_INJECTION_DETECTED

Pre-filter

Before the full Admission Controller runs, a fast-path classifier routes requests:

Decision	Meaning	What happens
BLOCK	High-confidence malicious	deny immediately, AC skipped
PASS	High-confidence benign	allow immediately, AC skipped
REVIEW	Ambiguous	full AC evaluation

The pre-filter also decodes and reclassifies obfuscated inputs. Covered forms include zero-width insertion, character arrays, hex escapes, base64 blobs, and rot13.

Spotlighting

All content entering policy evaluation is tagged with a trust source before evaluation.

Source tag	Applied to
[UNTRUSTED_CONTEXT source="rag_retrieval"]	retrieved document chunks
[TOOL_OUTPUT: UNTRUSTED] and [UNTRUSTED_CONTEXT source="tool_output"]	results from previous tool calls
[FILE_UPLOAD: UNTRUSTED] and [UNTRUSTED_CONTEXT source="file_upload"]	uploaded file content

Untrusted content cannot promote its own trust level.

What gets blocked

Prompt injection, shell injection, SSRF, obfuscated payloads, PII and PHI exfiltration, data exfiltration, BOLA violations, BFLA violations, and rate-flood or reasoning-DoS patterns.

Forensic telemetry

Every blocked call produces a tamper-evident record.

{
  "decision": "DENY",
  "reason_code": "MCP_SHELL_INJECTION_BLOCKED",
  "evidence_hash": "bdbde1558fb883573b0f6e8630ccba1edaf6bed8cb035fa6a48912809149f287",
  "has_forensic_payload": true,
  "policy_version_id": "0dbca364d66447469637bafa2282e635124fcb99eecd6383038e3b652577ebc7",
  "decision_trace_id": "17e797c0-eb5c-4f97-b4a1-2d3e4f5a6b7c"
}

Field	Description
evidence_hash	SHA-256 of the blocked payload bound to call context
has_forensic_payload	true on blocked records and false on allow
policy_version_id	signed bundle hash proving which policy made the decision
decision_trace_id	UUID linking the denial to the admission trace

Compliance coverage

Pre-execution compliance is preventive, not detective. Data does not move before a policy decision is made.

Framework	Controls enforced at tool boundary
GDPR	PII detection, data minimization, Art. 5 and 17 audit trail
HIPAA	PHI patterns, minimum-necessary access, logging controls
PCI-DSS v4	PAN and CVV detection, CDE path blocking, Req. 10.2 and 6.3.2
ISO 27001	A.8.2, A.9.4, A.12.4, A.14.2
SOC 2 Type II	CC6.1, CC6.6, CC7.2, CC9.2