Policy Schema Reference

Top-Level Fields

Field	Type	Required	Description
`hushspec`	string	yes	Schema version. Currently `"0.1.0"`
`name`	string	no	Human-readable policy name
`description`	string	no	Human-readable description of the policy's purpose
`extends`	string	no	Base policy to inherit from: a filesystem path, or a `chio:<name>` built-in ruleset identifier (see below)
`merge_strategy`	enum	no	How to merge with the base policy: `replace`, `merge`, or `deep_merge` (default: `deep_merge`)
`rules`	object	no	Guard rule configuration (see below)
`extensions`	object	no	Extension configuration: posture, origins, detection, reputation, runtime_assurance, and the Chio passthrough slot
`metadata`	object	no	Governance metadata (author, approval, classification, lifecycle)

minimal-policy.yaml

hushspec: "0.1.0"
name: my-policy
description: A minimal example policy

rules:
  tool_access:
    enabled: true
    default: block
    allow:
      - read_file

Built-in Rulesets

Seven rulesets ship embedded in chio-policy at compile time. Reference one from extends with the chio:<name> form; the merge_strategy field then controls how your document composes with the base.

Identifier	Purpose
`chio:default`	Default security rules for AI agent execution
`chio:strict`	Strict rules with minimal permissions
`chio:permissive`	Permissive rules for development (use with caution)
`chio:ai-agent`	Rules optimized for AI coding assistants
`chio:cicd`	Rules for CI/CD pipelines
`chio:remote-desktop`	Rules for remote desktop and computer-use agent sessions
`chio:panic`	Emergency deny-all policy, activated by panic mode

yaml

hushspec: "0.1.0"
name: hardened-agent
extends: "chio:strict"
merge_strategy: deep_merge

rules:
  egress:
    allow:
      - api.github.com

Rules

The rules block configures each guard in the kernel's guard pipeline. All rules are optional. Guards whose rule is omitted are disabled and return allow by default.

forbidden_paths

Blocks access to file paths matching glob patterns. Matched paths are denied regardless of other rules.

Field	Type	Default	Description
`enabled`	bool	`true`	Whether this guard is active
`patterns`	string[]	`[]`	Glob patterns to block (e.g. `/.env`, `/*.pem`)
`exceptions`	string[]	`[]`	Glob patterns exempted from blocking

yaml

rules:
  forbidden_paths:
    enabled: true
    patterns:
      - "**/.env"
      - "**/*.pem"
      - "**/credentials*"
    exceptions:
      - "**/credentials.example.json"

path_allowlist

Restricts file access to explicitly declared directory roots with read/write/patch granularity.

Field	Type	Default	Description
`enabled`	bool	`false`	Whether this guard is active
`read`	string[]	`[]`	Glob patterns for read-allowed paths
`write`	string[]	`[]`	Glob patterns for write-allowed paths
`patch`	string[]	`[]`	Glob patterns for patch-allowed paths

yaml

rules:
  path_allowlist:
    enabled: true
    read:
      - ./workspace/**
      - ./docs/**
    write:
      - ./workspace/output/**
    patch:
      - ./workspace/src/**

egress

Controls outbound network access by domain. The default action applies to domains not in either list.

Field	Type	Default	Description
`enabled`	bool	`true`	Whether this guard is active
`allow`	string[]	`[]`	Domains to allow (e.g. `api.example.com`)
`block`	string[]	`[]`	Domains to block
`default`	enum	`block`	Default action for unlisted domains: `allow` or `block`

yaml

rules:
  egress:
    enabled: true
    default: block
    allow:
      - api.github.com
      - registry.npmjs.org
    block:
      - evil.example.com

secret_patterns

Scans tool arguments and results for secrets using regex patterns. Matches trigger a deny with the matching pattern's severity level.

Field	Type	Default	Description
`enabled`	bool	`true`	Whether this guard is active
`patterns`	SecretPattern[]	`[]`	Array of secret pattern definitions
`skip_paths`	string[]	`[]`	File paths to skip during scanning

Each SecretPattern has the following fields:

Field	Type	Required	Description
`name`	string	yes	Identifier for this pattern
`pattern`	string (regex)	yes	Regular expression to match
`severity`	enum	yes	`critical`, `error`, or `warn`
`description`	string	no	Human-readable description of what this pattern detects

yaml

rules:
  secret_patterns:
    enabled: true
    patterns:
      - name: aws_key
        pattern: "AKIA[0-9A-Z]{16}"
        severity: critical
        description: AWS access key ID
      - name: github_token
        pattern: "ghp_[a-zA-Z0-9]{36}"
        severity: critical
    skip_paths:
      - "**/test/fixtures/**"

patch_integrity

Validates that file patches (diffs) stay within configured size and balance bounds.

Field	Type	Default	Description
`enabled`	bool	`true`	Whether this guard is active
`max_additions`	integer	`1000`	Maximum number of added lines per patch
`max_deletions`	integer	`500`	Maximum number of deleted lines per patch
`forbidden_patterns`	string[]	`[]`	Regex patterns forbidden in patch content
`require_balance`	bool	`false`	Require additions and deletions to be roughly balanced
`max_imbalance_ratio`	float	`10.0`	Maximum ratio of additions to deletions (or vice versa) when balance is required

yaml

rules:
  patch_integrity:
    enabled: true
    max_additions: 500
    max_deletions: 200
    require_balance: true
    max_imbalance_ratio: 5.0
    forbidden_patterns:
      - "eval\\("
      - "exec\\("

shell_commands

Controls which shell command patterns are allowed or blocked.

Field	Type	Default	Description
`enabled`	bool	`true`	Whether this guard is active
`forbidden_patterns`	string[]	`[]`	Regex patterns that trigger a deny when matched

yaml

rules:
  shell_commands:
    enabled: true
    forbidden_patterns:
      - "rm\\s+-rf"
      - "curl.*\\|.*sh"
      - "chmod\\s+777"

tool_access

Controls which tools can be invoked and optionally requires confirmation or specific runtime assurance tiers.

Field	Type	Default	Description
`enabled`	bool	`true`	Whether this guard is active
`allow`	string[]	`[]`	Tool names to allow
`block`	string[]	`[]`	Tool names to block
`require_confirmation`	string[]	`[]`	Tool names that require explicit confirmation
`default`	enum	`allow`	Default action for unlisted tools: `allow` or `block`
`max_args_size`	integer	none	Maximum byte size of tool arguments
`require_runtime_assurance_tier`	enum	none	Hard requirement: `none`, `basic`, `attested`, `verified`
`prefer_runtime_assurance_tier`	enum	none	Soft preference for runtime assurance tier
`require_workload_identity`	WorkloadIdentityMatch	none	Hard requirement for workload identity matching
`prefer_workload_identity`	WorkloadIdentityMatch	none	Soft preference for workload identity matching

WorkloadIdentityMatch

The require_workload_identity and prefer_workload_identity fields accept an object with: scheme (spiffe), trust_domain (string), path_prefixes (string[]), and credential_kinds (uri, x509_svid, jwt_svid). See Workload Identity for the normalized shape and Bind Workload Identity for the operational recipe.

yaml

rules:
  tool_access:
    enabled: true
    default: block
    allow:
      - read_file
      - list_directory
      - search_files
    block:
      - delete_file
    require_confirmation:
      - write_file
    max_args_size: 65536
    require_runtime_assurance_tier: attested

computer_use

Controls computer-use actions such as mouse clicks, keyboard input, and screen capture.

Field	Type	Default	Description
`enabled`	bool	`false`	Whether this guard is active
`mode`	enum	`guardrail`	`observe` (log only), `guardrail` (enforce with fallback), or `fail_closed` (strict deny)
`allowed_actions`	string[]	`[]`	Specific computer-use actions to allow

remote_desktop_channels

Controls which RDP/VNC side-channels are permitted during remote desktop sessions.

Field	Type	Default	Description
`enabled`	bool	`false`	Whether this guard is active
`clipboard`	bool	`false`	Allow clipboard sharing
`file_transfer`	bool	`false`	Allow file transfer
`audio`	bool	`true`	Allow audio channel
`drive_mapping`	bool	`false`	Allow drive mapping

input_injection

Controls synthetic input injection during computer-use sessions.

Field	Type	Default	Description
`enabled`	bool	`false`	Whether this guard is active
`allowed_types`	string[]	`[]`	Input types to allow (e.g. `keyboard`, `mouse`)
`require_postcondition_probe`	bool	`false`	Require a postcondition verification probe after injection

browser_automation

Constrains browser-automation actions by domain and verb, and detects credentials in automation payloads.

Field	Type	Default	Description
`enabled`	bool	`false`	Whether this guard is active
`allowed_domains`	string[]	`[]`	Domains the browser may navigate to
`blocked_domains`	string[]	`[]`	Domains the browser may not navigate to
`allowed_verbs`	string[]	`[]`	Automation verbs permitted (e.g. click, type, navigate)
`credential_detection`	bool	`true`	Detect credentials embedded in automation payloads
`extra_credential_patterns`	string[]	`[]`	Additional regex patterns treated as credentials

code_execution

Sandboxed-interpreter restrictions: language allowlist, dangerous-module denylist, network gating, and execution-time bounds.

Field	Type	Default	Description
`enabled`	bool	`false`	Whether this guard is active
`language_allowlist`	string[]	`[]`	Interpreter languages permitted for execution
`module_denylist`	string[]	`[]`	Modules that must not be imported
`network_access`	bool	`false`	Whether executed code may reach the network
`max_execution_time_ms`	integer	none	Wall-clock ceiling per execution in milliseconds
`max_scan_bytes`	integer	none	Maximum byte length of code scanned for denylisted modules

velocity

Token-bucket rate and spend limiting. Compiles to the grant-scoped VelocityGuard plus the identity-scoped AgentVelocityGuard.

Field	Type	Default	Description
`enabled`	bool	`true`	Whether this guard is active
`max_invocations_per_window`	integer	none	Maximum invocations per rolling window
`max_spend_per_window`	integer	none	Maximum spend per window, in minor currency units
`max_requests_per_agent`	integer	none	Cross-capability request ceiling per agent identity
`max_requests_per_session`	integer	none	Request ceiling per agent/capability session
`window_secs`	integer	`60`	Rolling window length in seconds
`burst_factor`	float	`1.0`	Token-bucket burst multiplier over the steady-state rate

human_in_loop

Human-in-the-loop approval gating. Compiles to RequireApprovalAbove constraints on tool grants.

Field	Type	Default	Description
`enabled`	bool	`true`	Whether this guard is active
`require_confirmation`	string[]	`[]`	Tool-name globs that always need approval (compiles to a zero threshold)
`approve_above`	integer	none	Approval threshold in minor currency units
`approve_above_currency`	string	none	ISO 4217 currency for `approve_above`
`timeout_seconds`	integer	none	How long to wait for an approval before applying `on_timeout`
`on_timeout`	enum	`deny`	Action on approval timeout: `deny` or `defer`

yaml

rules:
  velocity:
    enabled: true
    max_requests_per_agent: 600
    window_secs: 60
    burst_factor: 1.5

  human_in_loop:
    enabled: true
    require_confirmation:
      - "transfer_*"
    approve_above: 50000
    approve_above_currency: USD
    timeout_seconds: 300
    on_timeout: deny

Extensions

Extensions configure stateful policy states, origin-aware policies, detection integrations, reputation scoring, runtime-attestation assurance, and a Chio-specific passthrough slot.

posture

Defines a state machine for adaptive security states. The kernel transitions between states based on agent behavior to adjust trust.

Field	Type	Description
`initial`	string	Name of the starting state
`states`	map<string, PostureState>	Named states with capabilities and budgets
`transitions`	PostureTransition[]	Rules for moving between states

Transition triggers: user_approval, user_denial, critical_violation, any_violation, timeout, budget_exhausted, pattern_match.

yaml

extensions:
  posture:
    initial: restricted
    states:
      restricted:
        description: Limited tool access
        capabilities: [read_file]
        budgets:
          tool_calls: 50
      standard:
        description: Normal operating mode
        capabilities: [read_file, write_file, search_files]
        budgets:
          tool_calls: 500
    transitions:
      - from: restricted
        to: standard
        on: user_approval
      - from: standard
        to: restricted
        on: critical_violation

origins

Origin-aware policy profiles that match requests based on provider, tenant, organization, space, and other contextual attributes.

Field	Type	Default	Description
`default_behavior`	enum	`deny`	`deny` or `minimal_profile` for unmatched origins
`profiles`	OriginProfile[]	`[]`	Array of origin profile definitions

Each profile carries a required id, optional match rules (provider, tenant_id, organization_id, space_id, space_type, visibility, external_participants, tags, groups, roles, sensitivity, actor_role), and per-origin posture, tool_access, egress, data, budgets, and bridge settings as direct fields (there is no overrides wrapper).

yaml

extensions:
  origins:
    default_behavior: deny
    profiles:
      - id: internal-prod
        match:
          provider: google-workspace
          tenant_id: acme-corp
          sensitivity: confidential
        tool_access:
          default: allow
        egress:
          default: block
          allow: [api.github.com]
      - id: external-partner
        match:
          external_participants: true
        tool_access:
          default: block
          allow: [read_file]

detection

Integrates with detection engines for prompt injection, jailbreak attempts, and threat intelligence.

Sub-field	Options	Description
`prompt_injection`	`enabled`, `warn_at_or_above`, `block_at_or_above`, `max_scan_bytes`	Prompt injection detection with configurable severity thresholds
`jailbreak`	`enabled`, `block_threshold`, `warn_threshold`, `max_input_bytes`	Jailbreak attempt detection
`threat_intel`	`enabled`, `pattern_db`, `similarity_threshold`, `top_k`	Threat intelligence pattern matching

Detection levels for prompt injection: safe, suspicious, high, critical.

The jailbreak warn_threshold and block_threshold are integer percentages in the range 0–100, not fractional scores. When omitted they default to 50 and 80; a value above 100 is rejected at validation, and block_threshold should be greater than or equal to warn_threshold.

Only block_threshold is wired into the compiled guard: it maps to the jailbreak guard's threshold in the [0.0, 1.0] range (the percentage divided by 100). warn_threshold is accepted and validated for schema compatibility, but the compiler discards it after validation. The jailbreak guard has no dedicated warn-threshold field; it emits its own advisory and warn signals from detector-level statistical thresholds, unrelated to this value. Setting warn_threshold alone does not change runtime behavior.

yaml

extensions:
  detection:
    prompt_injection:
      enabled: true
      warn_at_or_above: suspicious
      block_at_or_above: high
      max_scan_bytes: 65536
    jailbreak:
      enabled: true
      warn_threshold: 50
      block_threshold: 85
      max_input_bytes: 32768
    threat_intel:
      enabled: true
      pattern_db: ./data/threat-intel.json
      similarity_threshold: 0.82
      top_k: 5

reputation

Configures the reputation scoring system with weighted metrics, temporal decay, and tiered access control.

yaml

extensions:
  reputation:
    scoring:
      weights:
        boundary_pressure: 0.15
        resource_stewardship: 0.15
        least_privilege: 0.15
        history_depth: 0.10
        tool_diversity: 0.10
        delegation_hygiene: 0.10
        reliability: 0.15
        incident_correlation: 0.10
      temporal_decay_half_life_days: 30
      probationary_receipt_count: 100
      probationary_score_ceiling: 0.6
      probationary_min_days: 7
    tiers:
      observer:
        score_range: [0.0, 0.4]
        max_scope:
          operations: [read_file]
          max_invocations: 100
          ttl_seconds: 3600
      standard:
        score_range: [0.4, 0.8]
        max_scope:
          operations: [read_file, write_file, search_files]
          max_invocations: 1000
          ttl_seconds: 86400
        promotion:
          target: trusted
          min_score: 0.75
          min_receipts: 500
          min_days: 30
        demotion:
          target: observer
          triggers:
            - type: score_drop
              threshold: 0.35

runtime_assurance

Configures runtime attestation verification tiers and trusted verifiers.

Field	Type	Description
`tiers`	map<string, RuntimeAssuranceTierRule>	Named tier rules with minimum attestation tier and scope constraints
`trusted_verifiers`	map<string, RuntimeAssuranceVerifierRule>	Named verifier rules defining accepted attestation sources

yaml

extensions:
  runtime_assurance:
    tiers:
      attested:
        minimum_attestation_tier: attested
        max_scope:
          operations: [read_file, write_file]
          ttl_seconds: 3600
      verified:
        minimum_attestation_tier: verified
        max_scope:
          operations: [read_file, write_file, shell_exec]
          ttl_seconds: 7200
    trusted_verifiers:
      nitro-enclave:
        schema: "chio.runtime-attestation.aws-nitro.v1"
        verifier: aws-nitro-enclave
        effective_tier: attested
        allowed_attestation_types: [nitro-enclave-attestation-doc]
      tpm-vendor-a:
        schema: "chio.runtime-attestation.tpm.v1"
        verifier: tpm-vendor-a
        effective_tier: verified
        max_evidence_age_seconds: 3600

Each tier rule requires minimum_attestation_tier (none, basic, attested, or verified) and a max_scope. Each verifier rule requires schema, verifier, and effective_tier, with optional verifier_family, max_evidence_age_seconds, allowed_attestation_types, and required_assertions. Every nested extension struct rejects unknown fields.

Chio

A Chio-specific passthrough slot. The kernel does not interpret this block; it is carried verbatim for chio-bridge consumers, which apply the contained policy to bridged deployments.

Field	Type	Description
`market_hours`	`ChioMarketHours`	Trading-hours window applied by bridge consumers
`signing`	`ChioSigning`	Signing configuration for bridge records
`k8s_namespaces`	`ChioK8sNamespaces`	Kubernetes namespace scoping for the bridge
`rollback`	`ChioRollback`	Rollback policy for bridged deployments
`human_in_loop`	`ChioHumanInLoopAdvanced`	Advanced approver configuration, including approver sets

Governance Metadata

Optional metadata for policy governance, audit trails, and lifecycle management.

Field	Type	Description
`author`	string	Policy author
`approved_by`	string	Approver name or ID
`approval_date`	string	Date of approval
`classification`	enum	`public`, `internal`, `confidential`, or `restricted`
`change_ticket`	string	Change management ticket reference
`lifecycle_state`	enum	`draft`, `review`, `approved`, `deployed`, `deprecated`, or `archived`
`policy_version`	integer	Monotonically increasing version number
`effective_date`	string	Date when the policy takes effect
`expiry_date`	string	Date when the policy expires

yaml

metadata:
  author: security-team
  approved_by: ciso@company.com
  approval_date: "2026-04-01"
  classification: internal
  change_ticket: SEC-1234
  lifecycle_state: deployed
  policy_version: 3
  effective_date: "2026-04-01"
  expiry_date: "2026-10-01"

Complete Example

An example policy that uses many available options:

production-policy.yaml

hushspec: "0.1.0"
name: production-workspace
description: Production policy for governed code agent

rules:
  forbidden_paths:
    enabled: true
    patterns:
      - "**/.env"
      - "**/*.pem"
      - "**/*.key"
      - "**/credentials*"
    exceptions:
      - "**/credentials.example.json"

  path_allowlist:
    enabled: true
    read:
      - ./workspace/**
      - ./docs/**
    write:
      - ./workspace/output/**
    patch:
      - ./workspace/src/**

  egress:
    enabled: true
    default: block
    allow:
      - api.github.com
      - registry.npmjs.org

  secret_patterns:
    enabled: true
    patterns:
      - name: aws_key
        pattern: "AKIA[0-9A-Z]{16}"
        severity: critical
      - name: github_token
        pattern: "ghp_[a-zA-Z0-9]{36}"
        severity: critical

  patch_integrity:
    enabled: true
    max_additions: 500
    max_deletions: 200
    require_balance: true
    max_imbalance_ratio: 5.0

  shell_commands:
    enabled: true
    forbidden_patterns:
      - "rm\\s+-rf"

  tool_access:
    enabled: true
    default: block
    allow:
      - read_file
      - list_directory
      - search_files
    require_confirmation:
      - write_file

extensions:
  posture:
    initial: restricted
    states:
      restricted:
        capabilities: [read_file, list_directory]
        budgets:
          tool_calls: 50
      standard:
        capabilities: [read_file, list_directory, search_files, write_file]
        budgets:
          tool_calls: 500
    transitions:
      - from: restricted
        to: standard
        on: user_approval
      - from: standard
        to: restricted
        on: critical_violation

metadata:
  author: security-team
  classification: internal
  lifecycle_state: deployed
  policy_version: 1

PreviousCLI NextReceipt Format