> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sector8.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 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.

```text theme={null}
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.

```json theme={null}
{
  "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                                    |