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

# Policy Engine

> Define and enforce security policies for agent sandboxes

# Policy Engine (Cage Rules)

The Policy Engine lets you define rules that govern what agents can and cannot do inside sandboxes. Policies are enforced at the MCP tool layer, LLM proxy, file system, network, and command execution levels.

## How It Works

1. You define **policies** with **rules** — each rule targets a scope (tool, file, command, network, llm) and specifies an action (allow, deny, audit, pause)
2. When an agent attempts an operation, the engine evaluates all active policies
3. The first `deny` or `pause` rule that matches blocks the operation immediately
4. `audit` rules log a cage\_break event but don't block

## Policy Inheritance

Policies support a three-level hierarchy:

```
org → team → project
```

* **Org-level** policies apply to all sandboxes in the account
* **Team-level** policies apply to a specific team
* **Project-level** policies apply to a specific project

Child policies inherit parent rules. A child can **override** a parent rule by declaring the same rule ID with a different action.

## Built-in Templates

Apply production-ready templates with a single command:

| Template      | Description                                                                             |
| ------------- | --------------------------------------------------------------------------------------- |
| `soc2`        | PII redaction, injection blocking, secret file protection, destructive command blocking |
| `hipaa`       | Strict PHI blocking, restricted tools, git-push requires approval                       |
| `dev-only`    | Permissive — audit everything, block only fork bombs & rm -rf /                         |
| `restrictive` | Read-only filesystem, no network, full PII blocking                                     |
| `permissive`  | Uncaged mode — audit only, nothing blocked                                              |

## YAML Configuration

Add policies to your `.caged.yaml`:

```yaml theme={null}
policy:
  template: soc2
  denied_tools:
    - "dangerous_tool"
  denied_commands:
    - "rm -rf"
    - "curl"
  denied_files:
    - ".env"
    - "*.pem"
  scan_pii: true
  scan_injection: true
  require_approval:
    - "write_file"
    - "execute_command"
```

## API

```bash theme={null}
# List policies
curl -H "Authorization: Bearer $TOKEN" https://api.caged.dev/v1/policies

# Apply template
curl -X POST -H "Authorization: Bearer $TOKEN" \
  https://api.caged.dev/v1/policies/templates/soc2/apply

# Create custom policy
curl -X POST -H "Authorization: Bearer $TOKEN" \
  -d '{"name":"no-secrets","level":"org","rules":[...]}' \
  https://api.caged.dev/v1/policies
```

## CLI

```bash theme={null}
# List policies
caged policy list

# View available templates
caged policy templates

# Apply a template
caged policy apply soc2

# Delete a policy
caged policy delete <id>
```

## Content Scanning

The engine includes built-in content scanners for LLM traffic:

### PII Detection

Detects: email addresses, SSNs, credit card numbers, phone numbers, IP addresses, API keys, AWS secrets, private keys.

### Prompt Injection Detection

12 heuristic signals with weighted scoring. Blocks content scoring above 0.7 threshold.

## Dashboard

Manage policies from the web dashboard at `/dashboard/policies`:

* View all active policies with level, priority, and rule counts
* Apply templates with one click
* Enable/disable policies