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

# Policy Schema Reference

> Developer-facing policy.yaml schema for middleware and gateway enforcement.

`policy.yaml` is the main file a developer authors to tell Sec0 what is allowed, what must be denied, and how telemetry and side effects should be handled. This page keeps the parts of the schema that are typically written as part of an SDK integration.

## Minimal example

```yaml theme={null}
tenant: my-app
security_level: middleware
default_retention: 30d

signing:
  enabled: true
  key_ref: file://./.sec0/keys/ed25519.key

observability:
  otlp_endpoint: https://otlp.example.com
  sample:
    success: 1
    error: 1

tools:
  allowlist:
    - mcp://orders/lookupOrder@1.0
  deny_if_unpinned_version: true

privacy:
  redact_outputs: false
  store_raw_payloads: false

side_effects:
  require_idempotency_key: true
  max_retries: 1

enforcement:
  deny_on:
    - tool_not_in_allowlist
    - missing_idempotency_for_side_effect
  circuit_breakers:
    error_rate_pct: 25
    p95_latency_ms: 2000

agent_guard:
  enabled: true
  block_on_severity: high

security:
  egress_allowlist:
    - "*.internal.example.com"
  side_effects:
    require_idempotency_key: true
```

## Top-level

| Key                 | Type                          | Required | Description                                  |
| ------------------- | ----------------------------- | -------- | -------------------------------------------- |
| `tenant`            | string                        | Yes      | Workspace or tenant slug                     |
| `security_level`    | `"gateway"` or `"middleware"` | No       | Policy tier hint                             |
| `default_retention` | `"30d"`, `"90d"`, or `"180d"` | Yes      | Default retention class                      |
| `signing`           | object                        | Yes      | Audit signing configuration                  |
| `observability`     | object                        | Yes      | OTLP endpoint and sampling                   |
| `tools`             | object                        | Yes      | Tool allowlist and version pinning rules     |
| `skills`            | object                        | No       | Skill allowlist and change-scan controls     |
| `privacy`           | object                        | Yes      | Output redaction and raw payload retention   |
| `side_effects`      | object                        | Yes      | Idempotency and retry controls               |
| `enforcement`       | object                        | Yes      | Deny, escalate, and circuit-breaker controls |
| `agent_guard`       | object                        | No       | Prompt and output guard thresholds           |
| `security`          | object                        | No       | Gateway-style runtime guardrails             |

Compliance pack authoring and export settings are intentionally not part of the main developer reference. Use the dedicated compliance and operations docs for those flows.

## signing

| Key               | Type    | Required | Description                                             |
| ----------------- | ------- | -------- | ------------------------------------------------------- |
| `signing.enabled` | boolean | Yes      | Enable audit envelope signing                           |
| `signing.key_ref` | string  | Yes      | Key reference such as `file://./.sec0/keys/ed25519.key` |

## observability

| Key                               | Type    | Required | Description                   |
| --------------------------------- | ------- | -------- | ----------------------------- |
| `observability.otlp_endpoint`     | string  | Yes      | OTLP collector endpoint       |
| `observability.sample`            | object  | Yes      | Sampling ratios               |
| `observability.enabled`           | boolean | No       | Enable tracing                |
| `observability.redact_identities` | boolean | No       | Redact identity data in spans |

### `observability.sample`

| Key                            | Type         | Required | Description            |
| ------------------------------ | ------------ | -------- | ---------------------- |
| `observability.sample.success` | number (0-1) | Yes      | Success sampling ratio |
| `observability.sample.error`   | number (0-1) | Yes      | Error sampling ratio   |

## tools

| Key                              | Type      | Required | Description                                                          |
| -------------------------------- | --------- | -------- | -------------------------------------------------------------------- |
| `tools.allowlist`                | string\[] | Yes      | Allowed tool patterns such as `"*"` or `"mcp://server/tool@version"` |
| `tools.deny_if_unpinned_version` | boolean   | Yes      | Block unpinned tool versions                                         |

## skills

| Key                               | Type                                   | Required     | Description                              |
| --------------------------------- | -------------------------------------- | ------------ | ---------------------------------------- |
| `skills.allowlist`                | string\[]                              | Yes (if set) | Allowed skill refs                       |
| `skills.deny_if_unpinned_version` | boolean                                | Yes (if set) | Block unpinned skill versions            |
| `skills.scan_on_change_only`      | boolean                                | No           | Scan only when version or digest changes |
| `skills.block_on_change`          | boolean                                | No           | Block while a new result is pending      |
| `skills.block_on_severity`        | `low`, `medium`, `high`, or `critical` | No           | Deny threshold                           |

## privacy

| Key                          | Type    | Required | Description                       |
| ---------------------------- | ------- | -------- | --------------------------------- |
| `privacy.redact_outputs`     | boolean | Yes      | Redact tool outputs in audit logs |
| `privacy.store_raw_payloads` | boolean | Yes      | Persist raw payload datasets      |

## side\_effects

| Key                                    | Type          | Required | Description                               |
| -------------------------------------- | ------------- | -------- | ----------------------------------------- |
| `side_effects.require_idempotency_key` | boolean       | Yes      | Require idempotency keys for side effects |
| `side_effects.max_retries`             | number (0-10) | Yes      | Max retry count                           |

## enforcement

| Key                            | Type      | Required | Description                           |
| ------------------------------ | --------- | -------- | ------------------------------------- |
| `enforcement.deny_on`          | string\[] | Yes      | Reasons that trigger a deny           |
| `enforcement.escalate_on`      | string\[] | No       | Reasons that trigger human escalation |
| `enforcement.circuit_breakers` | object    | Yes      | Circuit-breaker thresholds            |

### `enforcement.deny_on` and `enforcement.escalate_on` values

| Value                                 | Meaning                                                |
| ------------------------------------- | ------------------------------------------------------ |
| `missing_audit_signature`             | Audit signature missing or invalid                     |
| `tool_not_in_allowlist`               | Tool not permitted by `tools.allowlist`                |
| `version_unpinned`                    | Tool version missing when pinning is required          |
| `missing_idempotency_for_side_effect` | Side-effecting call missing idempotency key            |
| `egress_violation`                    | Egress target is outside the allowed boundary          |
| `fs_violation`                        | Filesystem target is outside the allowed boundary      |
| `payload_too_large`                   | Payload exceeded configured size limits                |
| `duration_too_long`                   | Execution exceeded configured duration limits          |
| `registry_mutation`                   | Tool registry changed after middleware freeze          |
| `handler_swap`                        | Tool handler changed after registration                |
| `server_code_changed`                 | Server code hash changed since baseline                |
| `tool_code_changed`                   | Tool handler code hash changed since baseline          |
| `skill_version_changed`               | Skill version changed since baseline                   |
| `skill_code_changed`                  | Skill digest changed since baseline                    |
| `skill_scan_pending`                  | Skill scan is still pending                            |
| `skill_scan_failed`                   | Skill scan failed or exceeded threshold                |
| `sast_pending`                        | SAST scan is still pending                             |
| `sast_failed`                         | SAST scan failed or exceeded threshold                 |
| `dast_pending`                        | DAST scan is still pending                             |
| `dast_failed`                         | DAST scan failed or exceeded threshold                 |
| `agent_guard_failed`                  | Agent Guard findings exceeded the configured threshold |

### `enforcement.circuit_breakers`

| Key                                           | Type           | Required | Description           |
| --------------------------------------------- | -------------- | -------- | --------------------- |
| `enforcement.circuit_breakers.error_rate_pct` | number (0-100) | Yes      | Error-rate threshold  |
| `enforcement.circuit_breakers.p95_latency_ms` | number (>=0)   | Yes      | P95 latency threshold |

## `agent_guard`

This is the preferred place for guard thresholds.

| Key                             | Type                                   | Required | Description          |
| ------------------------------- | -------------------------------------- | -------- | -------------------- |
| `agent_guard.enabled`           | boolean                                | No       | Enable Agent Guard   |
| `agent_guard.block_on_severity` | `low`, `medium`, `high`, or `critical` | No       | Deny threshold       |
| `agent_guard.block_on_count`    | number (>=1)                           | No       | Deny count threshold |

## security

Use `security` when the same policy document should also drive gateway-style runtime guardrails.

| Key                         | Type      | Required | Description                     |
| --------------------------- | --------- | -------- | ------------------------------- |
| `security.allow_versions`   | object    | No       | Server-to-version allowlist map |
| `security.egress_allowlist` | string\[] | No       | Allowed egress patterns         |
| `security.fs_allowlist`     | string\[] | No       | Allowed filesystem patterns     |
| `security.limits`           | object    | No       | Payload and duration limits     |
| `security.side_effects`     | object    | No       | Side-effect guardrails          |

### `security.limits`

| Key                               | Type   | Required | Description      |
| --------------------------------- | ------ | -------- | ---------------- |
| `security.limits.max_payload_kb`  | number | No       | Max payload size |
| `security.limits.max_duration_ms` | number | No       | Max duration     |

### `security.side_effects`

| Key                                             | Type    | Required | Description                         |
| ----------------------------------------------- | ------- | -------- | ----------------------------------- |
| `security.side_effects.require_idempotency_key` | boolean | No       | Require idempotency                 |
| `security.side_effects.approve_high_risk`       | boolean | No       | Enable escalation creation          |
| `security.side_effects.human_escalation`        | object  | No       | Snake-case approval strategy config |
| `security.side_effects.humanEscalation`         | object  | No       | Camel-case approval strategy config |

### `security.side_effects.human_escalation / humanEscalation`

| Key                 | Type                                               | Required | Description                              |
| ------------------- | -------------------------------------------------- | -------- | ---------------------------------------- |
| `approval_strategy` | `auto_allow`, `single_approver`, or `human_quorum` | No       | Escalation approval strategy             |
| `timeout_action`    | `auto_approve` or `auto_reject`                    | No       | Action when escalation expires           |
| `min_approvals`     | number (>=1)                                       | No       | Approval quorum                          |
| `min_rejections`    | number (>=1)                                       | No       | Rejection quorum                         |
| `required_roles`    | string\[]                                          | No       | Roles that must appear on approval votes |
| `veto_roles`        | string\[]                                          | No       | Roles that can force rejection           |
| `approval_set_id`   | string                                             | No       | Explicit reviewer-set override           |