Policy Schema Reference

Complete reference for the HushSpec policy schema. Policies are YAML documents that configure the Chio kernel's guard pipeline, extensions, and governance metadata.

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 (path or identifier)
`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
`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

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

Extensions

Extensions add advanced capabilities beyond the core guard pipeline: stateful posture management, origin-aware policies, detection integrations, reputation scoring, and runtime attestation assurance.

posture

Defines a state machine for adaptive security postures. The kernel transitions between states based on agent behavior, enabling progressive trust escalation or de-escalation.

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 can specify match rules (provider, tenant_id, organization_id, space_id, space_type, visibility, external_participants, tags, groups, roles, sensitivity, actor_role), along with per-origin overrides for posture, tool_access, egress, data policy, budgets, and bridge configuration.

yaml

extensions:
  origins:
    default_behavior: deny
    profiles:
      - name: internal-prod
        match:
          provider: google-workspace
          tenant_id: acme-corp
          sensitivity: confidential
        overrides:
          tool_access:
            default: allow
          egress:
            default: block
            allow: [api.github.com]
      - name: external-partner
        match:
          external_participants: true
        overrides:
          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.

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: 0.6
      block_threshold: 0.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:
        min_tier: attested
        max_scope:
          operations: [read_file, write_file]
          ttl_seconds: 3600
      verified:
        min_tier: verified
        max_scope:
          operations: [read_file, write_file, shell_exec]
          ttl_seconds: 7200
    trusted_verifiers:
      nitro-enclave:
        issuer: did:web:aws.amazon.com
        accepted_measurements:
          - "sha384:0f3a...e91d"
      tpm-vendor-a:
        issuer: did:web:vendor-a.example.com
        accepted_measurements:
          - "sha256:a1b2...c3d4"

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

A comprehensive policy demonstrating most 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