HushSpec Policy Format

Document version

Every HushSpec document begins with a version line:

hushspec: "0.1.0"

HUSHSPEC_VERSION is "0.1.0", and it is the only value HUSHSPEC_SUPPORTED_VERSIONS lists. Detection and support are separate steps. is_hushspec_format decides that a document is a HushSpec from the presence of the top-level hushspec key alone and never reads its value, so hushspec: "9.9.9" is still recognized as HushSpec. The version is checked later, in validate(), where version::is_supported() compares it against the supported list and fails validation rather than format detection.

Top-level fields

The root object uses deny_unknown_fields: any key outside the list below is a parse-time error. Exactly one field is required.

extends

extends takes a single reference string. The resolver in chio-policy::resolve loads the base, recurses on its own extends chain, and merges the children back over each parent. The composite loader supports two reference forms:

Built-in references accept either the bare name or a chio: or hushspec: prefix. The catalogue is BUILTIN_RULESETS, and it ships one embedded YAML document per name above, including the reserved panic ruleset.

Circular detection

The resolver tracks every loaded canonical source on a stack. If a descendant resolves back to a source already in the stack, it returns ResolveError::Cycle with the full chain (joined with -> ). Cycles cannot compile.

merge_strategy

The merge strategy controls how the child policy combines with the resolved parent. Values are rendered in snake_case:

The default is deep_merge, but its difference from merge is narrow. Both fold rule blocks by whole-block replacement. When the child declares a rule block it replaces the parent's block entirely, so a child forbidden_paths.patterns list replaces the parent's list rather than appending to it. When the child omits a block, the parent's carries forward. The two strategies diverge only on extensions: deep_merge merges each extension (posture, origins, detection, reputation, chio) field-by-field, so a child can override one posture state without redeclaring the rest, while merge replaces the whole extension block.

rules

The rules object holds per-guard configuration in 14 named blocks. It uses deny_unknown_fields, so an unknown block name is a parse-time error, and RULE_BLOCK_NAMES is the same inventory in constant form for validators and evaluators. Every block is optional, and every one of them is gated twice: an omitted block adds no guard, and a block whose enabled is false adds no guard either. The compiler reads enabled before it constructs anything.

Two blocks are not one-to-one. egress also installs an InternalNetworkGuard so that the allowlist catches unknown domains while the companion catches raw RFC 1918 and cloud-metadata addresses, and secret_patterns installs a pre-invocation guard for the write path and a post-invocation SanitizerHook for the read path from the same configuration. Policy Compilation owns the full compile surface, including the guards that come from extensions rather than from rules.

Every block, field by field

Each block struct also carries deny_unknown_fields. Field names and types below are the struct definitions; the default column gives what a missing key deserializes to.

Read the enabled defaults before anything else. path_allowlist, computer_use, remote_desktop_channels, input_injection, browser_automation and code_execution default it to false, so declaring one of those blocks without it configures a guard that never runs. The other 8 default it to true, so declaring the block turns the guard on. remote_desktop_channels.audio is the one side channel that defaults to permitted.

tool_access in a document

rules:
  tool_access:
    enabled: true
    default: block           # "allow" or "block"
    allow: [read_file]       # tools explicitly permitted
    block: [delete_file]     # tools explicitly denied (overrides allow)
    require_confirmation:    # tools that require human approval
      - write_file
    max_args_size: 4096      # compiles to Constraint::MaxArgsSize
    require_runtime_assurance_tier: attested   # none | basic | attested | verified
    prefer_runtime_assurance_tier: verified
    require_workload_identity:
      scheme: spiffe                           # the only scheme
      trust_domain: example.org
      path_prefixes: ["/agents/"]
      credential_kinds: [x509_svid]            # uri | x509_svid | jwt_svid

Three of those keys leave the guard pipeline entirely and land on the compiled capability grants instead: max_args_size becomes Constraint::MaxArgsSize, require_runtime_assurance_tier becomes Constraint::MinimumRuntimeAssurance, and require_confirmation forces Constraint::RequireApprovalAbove to a threshold of zero on the grants its pattern matches, the same constraint human_in_loop emits from approve_above. A selective confirmation that would have to be widened to a wildcard grant is not widened; it stays in the policy evaluator. Capabilities defines those constraints and Scope Matching says which of them a matcher can decide.

For worked examples and list semantics per rule, Write a Policy is the operator-facing companion to the schema above.

Conditional activation

Rule blocks can be gated on runtime context. Conditions are supplied as a map keyed by rule-block name; each value is a Condition from chio_policy::conditions. validate_condition_keys rejects any key that is not a known rule-block name, so a misspelled block fails closed rather than silently leaving the rule active.

Condition is a small, non-Turing-complete predicate type with these fields:

• time_window: an optional TimeWindowCondition (start, end, optional timezone and days-of-week) matched against the request time.
• context: an optional key/value map matched against the RuntimeContext maps (user, agent, session, request, deployment, custom). There are no dedicated tool-name or agent-id fields; those are just keys inside these generic maps.
• all_of, any_of, not: boolean composition over nested conditions (AND / OR / NOT), nested up to a depth of eight.

evaluate_condition(condition, context) is fail-closed: every field present on a condition must hold, a missing context field evaluates to false, and nesting past depth eight also returns false. A bare Condition with several fields set therefore ANDs them together; any_of is the only OR.

extensions

Extensions hold optional, domain-specific configuration. The shape is fixed: unknown sub-blocks are rejected by deny_unknown_fields.

Each extension has its own merge function in chio-policy::merge, so deep-merge respects the structure: posture states keyed by name, origin profiles keyed by id.

The chio block is the one carried rather than interpreted. Its doc comment says the kernel does not read it, and its five fields (market_hours, signing, k8s_namespaces, rollback, human_in_loop) travel with the document for bridge consumers. One path inside it is an exception: the policy compiler reads extensions.chio.human_in_loop.approvers and, when it is present, refuses to compile through the plain compile_policy entry point at all. Threshold approval needs an authenticated approver directory, and Policy Compilation owns the four refusals it raises without one.

metadata

metadata carries governance fields. None are enforced by the runtime; they exist for audit pipelines and deployment review.

Compile model

Compilation runs in three stages:

1. Parse. HushSpec::parse reads the YAML, applies pre-checks against malformed scalars, and deserializes with deny_unknown_fields.
2. Resolve and merge. resolve_with_loader walks the extends chain, detecting cycles, then folds children over parents per merge_strategy.
3. Compile. compile_policy turns the resolved HushSpec into a CompiledPolicy: a guard pipeline plus initial capability grants. A separate control-plane path, build_guard_pipeline / build_post_invocation_pipeline (re-exported from chio_control_plane::policy), extends this with cloud-guardrail and threat-intel adapters from a separate external-guard policy, not from the HushSpec document.

The compiled output drives the kernel's evaluation pipeline. See Kernel Architecture for the runtime flow, and Policy Compilation for which guards each block materializes, the limits on extends resolution, and the bounded static analysis that runs alongside it.

Validation rules

The following are enforced by the parser, resolver, or compiler. They are exercised in the test suites at crates/guards/chio-policy/src/models/tests.rs, crates/guards/chio-policy/src/compiler/tests.rs, and crates/guards/chio-policy/src/evaluate/tests.rs.

• Unknown fields are rejected. deny_unknown_fields applies to HushSpec, Rules, every rule struct, and every extension. Typos like forbidden_path (singular) instead of forbidden_paths are parse-time errors.
• YAML must be a mapping. A document that begins with a plain scalar, a sequence, or a URL fails before libyml runs. This is a defense against accidentally-pasted text.
• Quoted scalar overflow is rejected. Long whitespace runs inside quoted scalars (over MAX_QUOTED_SCALAR_WHITESPACE_RUN) fail before reaching libyml so the underlying parser is not forced through an exponential path.
• Cycles in extends are rejected. The resolver returns ResolveError::Cycle with the chain.
• HTTP references are rejected. The composite loader returns ResolveError::Http for http:// and https:// references.
• Regex patterns are validated. shell_commands.forbidden_patterns,patch_integrity.forbidden_patterns, and secret_patterns.patterns[].pattern go through chio_policy::regex_safety and reject pathological patterns.
• Default actions are enums. tool_access.default and egress.default accept only allow or block. Other strings fail to deserialize.
• Posture references are validated. validate_posture checks that posture.initial and every posture.transitions[].from/to name a state defined in posture.states, and that no transition targets "*". There is no duplicate-guard-name rejection and no cross-reference validation tying extensions.origins to posture states. The compiler records guard names in a parallel list with no uniqueness check. Required-field checks on external-guard providers (a non-empty api_key or endpoint) live on the separate control-plane external-guard compile path, not in HushSpec validation.

Worked example

A team policy that extends the built-in chio:default ruleset, tightens forbidden paths, locks down tools to a project allowlist, adds a velocity cap, and records governance metadata.

hushspec: "0.1.0"
name: team-data-pipeline
description: Read-only data extraction agent with strict path and tool gates.
extends: "chio:default"
merge_strategy: deep_merge

rules:
  tool_access:
    enabled: true
    default: block
    allow:
      - read_file
      - list_directory
      - search_files
      - run_query
    block:
      - execute_command
    require_confirmation:
      - export_to_csv
    max_args_size: 8192

  forbidden_paths:
    enabled: true
    patterns:
      - "**/.env*"
      - "**/secrets/**"
      - "**/.aws/credentials"
      - "**/id_rsa*"
    exceptions:
      - "/var/lib/agent/.env.testing"

  path_allowlist:
    enabled: true
    read:
      - "/var/lib/agent/data/**"
      - "/var/lib/agent/config/*.yaml"
    write: []
    patch: []

  egress:
    enabled: true
    default: block
    allow:
      - "warehouse.internal"
      - "*.metrics.example.com"

  secret_patterns:
    enabled: true
    patterns:
      - name: aws_access_key
        pattern: "AKIA[0-9A-Z]{16}"
        severity: critical
      - name: bearer_token
        pattern: "Bearer\\s+[A-Za-z0-9._~+/-]+=*"
        severity: error

  velocity:
    enabled: true
    max_invocations_per_window: 200
    window_secs: 60
    burst_factor: 1.5

  human_in_loop:
    enabled: true
    require_confirmation:
      - "export_*"
    timeout_seconds: 300
    on_timeout: deny

extensions:
  chio:
    market_hours:
      tz: "America/New_York"
      open: "09:30"
      close: "16:00"
      days: [Mon, Tue, Wed, Thu, Fri]

metadata:
  author: "platform-security"
  approved_by: "secops-lead"
  classification: confidential
  lifecycle_state: deployed
  policy_version: 7
  effective_date: "2026-04-01"

Next steps

• Write a Policy · field-by-field tables for every rule with worked examples
• Inherit & Merge Policies · base policies, overlay patterns, and multi-environment inheritance
• chio.yaml Configuration · the runtime config that loads a compiled policy and registers guards
• External Guards · the separate control-plane external-guard configuration (cloud_guardrails and threat_intel), separate from HushSpec rules