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
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 |
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
Usesecurity 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 |