HushSpec Core Specification

HushSpec is a portable, engine-neutral specification for declaring security rules at the tool boundary of AI agent runtimes. A HushSpec document declares security intent — what actions are allowed, blocked, or require confirmation — without prescribing how those rules are enforced.

The specification defines a YAML-based document format that any conformant engine can parse, validate, merge, and evaluate. HushSpec documents are designed to be authored by security teams, shared across organizations, and enforced by heterogeneous runtimes including CLI tools, SDKs, proxies, and long-running services.

The full normative specification is at spec/hushspec-core.md. A machine-readable JSON Schema is also available for automated validation.

Design Principles

Fail-closed. Ambiguity or error in a HushSpec document MUST result in denial, not allowance.
Engine-neutral. The specification declares intent. Enforcement mechanics are engine-specific.
Portable. A valid HushSpec document MUST produce identical semantic decisions across conformant engines.
Composable. Documents support single inheritance via extends with well-defined merge semantics.

Document Structure

A HushSpec document is a YAML 1.2 file. The following table lists every permitted top-level field.

Field	Type	Required	Default	Description
`hushspec`	string	Yes	—	Spec version. MUST match `^0\.\d+\.\d+$` for v0.x documents (e.g., `"0.1.0"`).
`name`	string	No	—	Human-readable policy name for display and logging.
`description`	string	No	—	Longer policy description. May include authorship or purpose notes.
`extends`	string	No	—	Reference to a base policy document. Resolution strategy (path, URL, registry ID, built-in name) is engine-specific. Circular inheritance MUST be detected and rejected.
`merge_strategy`	string	No	`"deep_merge"`	One of `"replace"`, `"merge"`, or `"deep_merge"`. Controls how the child document is overlaid onto the base when `extends` is present. See Merge Semantics.
`rules`	object	No	—	Contains up to 10 named rule blocks, each controlling a specific security domain. See Rules Reference.
`extensions`	object	No	—	Extension modules providing optional capabilities beyond the core rule set. Permitted keys: `posture`, `origins`, `detection`. Unknown extension keys MUST be rejected.
`metadata`	object	No	—	Optional governance metadata. Known fields such as `author`, `approved_by`, `classification`, `lifecycle_state`, `policy_version`, and review dates are schema-validated. These fields do not affect evaluation, but tools such as `h2h audit` may emit advisory lifecycle warnings.

Minimal Valid Document

The only required field is hushspec. The smallest valid document is:

yaml

hushspec: "0.1.0"

Full Example

yaml

hushspec: "0.1.0"
name: "production-agent-policy"
description: "Security policy for production AI agent deployments"
extends: "default"
merge_strategy: "deep_merge"

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

  egress:
    enabled: true
    allow:
      - "api.openai.com"
      - "**.googleapis.com"
    default: "block"

  secret_patterns:
    enabled: true
    patterns:
      - name: "aws_access_key"
        pattern: "AKIA[0-9A-Z]{16}"
        severity: "critical"
        description: "AWS access key ID"

  tool_access:
    enabled: true
    block:
      - "dangerous_tool"
    require_confirmation:
      - "deploy"
      - "database_write"
    default: "allow"

Decision Types and Precedence

Every rule evaluation produces one of three decision outcomes:

Decision	Semantics
`deny`	The action is blocked. Execution MUST NOT proceed.
`warn`	The action is permitted pending confirmation. If confirmation is not obtainable, engines SHOULD treat `warn` as `deny`.
`allow`	The action is permitted. Execution may proceed.

When multiple rule blocks apply to a single action, decisions are aggregated by strict precedence:

deny takes absolute precedence. If any rule block denies, the action is denied.
warn is next. If no rule block denies but at least one warns, the action requires confirmation.
allow applies only when all applicable rule blocks allow.

This means the most restrictive decision always wins. A single deny from any rule overrides any number of allow or warn results from other rules.

The 10 Core Rules

The rules object contains up to ten named rule blocks. Each rule block controls a specific security domain. All rule blocks share a common enabled field; when enabled is false, the rule block is inert and MUST NOT influence decisions.

If rules is absent or empty, no rules are active. Engines MUST NOT inject implicit rules beyond what the document (and its resolved extends chain) declares.

#	Rule Block	Security Domain	Default Enabled
1	`forbidden_paths`	Block access to sensitive filesystem paths via glob deny-list	`true`
2	`path_allowlist`	Allowlist-based path access control (read/write/patch)	`false`
3	`egress`	Network egress control by domain (allow/block/default)	`true`
4	`secret_patterns`	Detect secrets in content via named regex patterns	`true`
5	`patch_integrity`	Validate patch/diff safety (line limits, forbidden patterns, balance)	`true`
6	`shell_commands`	Block dangerous shell commands via regex patterns	`true`
7	`tool_access`	Control tool and MCP invocations (allow/block/confirm)	`true`
8	`computer_use`	Control computer use agent actions (observe/guardrail/fail-closed)	`false`
9	`remote_desktop_channels`	Control remote desktop side channels (clipboard, file transfer, etc.)	`false`
10	`input_injection`	Control input injection in CUA environments (keyboard, mouse, touch)	`false`

How the Rules Relate

The 10 rules are organized into three functional groups that cover the full surface area of AI agent actions:

Filesystem Rules (1-2)

forbidden_paths and path_allowlist provide complementary file access control. forbidden_paths is a deny-list: any path matching its patterns is blocked unless excepted. path_allowlist is an allow-list: when enabled, only paths explicitly listed are permitted. Both rules apply to file_read, file_write, and patch_apply actions. If both are active, a path must satisfy both — it must not be forbidden AND it must be on the allowlist.

Content and Network Rules (3-6)

egress controls outbound network access by domain. secret_patterns scans content for sensitive data before writes or transmissions. patch_integrity validates the size and content of patches and diffs. shell_commands blocks dangerous command strings. These rules often work together — for example, a file_write action is checked by both the filesystem rules and secret_patterns, so a write to an allowed path can still be denied if the content contains a detected secret.

Tool and CUA Rules (7-10)

tool_access provides allow/block/confirm control over tool and MCP invocations. computer_use, remote_desktop_channels, and input_injection form a layered security model for computer use agents (CUA): computer_use controls the top-level CUA mode, remote_desktop_channels manages side-channel capabilities, and input_injection restricts which input types can be injected. All three are disabled by default since they only apply to CUA-capable runtimes.

See the Rules Reference for complete field documentation for each rule block, and Action Types for the mapping between actions and rules.

Validation Requirements

Conformant parsers and validators MUST enforce the following rules. The overriding principle is fail-closed: if a document is ambiguous, malformed, or contains unrecognized content, it is rejected rather than partially applied.

#	Requirement	Description
1	Unknown field rejection	Documents containing fields not defined in this specification at any nesting level MUST be rejected. This extends recursively into `rules`, individual rule objects, and `extensions`.
2	Version field presence	The `hushspec` field MUST be present, MUST be a string, and MUST match `^0\.\d+\.\d+$` for v0.x documents.
3	Type correctness	All fields MUST conform to their declared types. A string where a boolean is expected (or vice versa) MUST cause rejection.
4	Enum constraints	Fields with enumerated values MUST contain one of the specified values: `severity`: `"critical"`, `"error"`, `"warn"` `mode` (computer_use): `"observe"`, `"guardrail"`, `"fail_closed"` `default` (egress): `"allow"`, `"block"` `default` (tool_access): `"allow"`, `"block"` `merge_strategy`: `"replace"`, `"merge"`, `"deep_merge"`
5	Uniqueness constraints	The `name` field within each element of `secret_patterns.patterns` MUST be unique across the array. Duplicate names MUST cause rejection.
6	Regex validity	All fields designated as regex patterns (`secret_patterns[].pattern`, `patch_integrity.forbidden_patterns[]`, `shell_commands.forbidden_patterns[]`) MUST be syntactically valid regular expressions. Invalid regexes MUST cause document rejection.
7	Numeric constraints	`max_additions` and `max_deletions` MUST be non-negative integers. `max_imbalance_ratio` MUST be a positive number (> 0). `max_args_size` MUST be a positive integer if present.
8	Boolean fields	Boolean fields MUST be YAML booleans (`true`/`false`), not strings or integers. `"true"` and `1` are not valid boolean values.

Extensions

Extension modules are declared under the extensions top-level field and provide optional capabilities beyond the core rule set.

Extension	Purpose
`posture`	Stateful capability and budget management. Defines budgets, capability state machines, and degradation policies.
`origins`	Origin-aware policy profiles. Allows policies to vary based on request source context (Slack channel, GitHub repo, API client identity).
`detection`	Detection engine thresholds. Configures prompt injection detection, jailbreak detection, threat intelligence screening, and content analysis.

Core parsers MUST accept known extension keys without rejecting the document but MAY ignore their contents. Unknown keys under extensions MUST be rejected.

In HushSpec v0.1.0, extension modules do not declare independent version fields. The companion extension specifications are versioned alongside the core HushSpec release.

Versioning

HushSpec uses semantic versioning (SemVer 2.0.0). The current version is 0.1.0.

v0.x (current): Unstable development series. Breaking changes between minor versions are permitted. Patch versions contain only clarifications and errata.
v1.0+: Stable series. Minor versions are additive only — new optional fields and rule blocks may be introduced, but existing documents remain valid. Major versions may introduce breaking changes.

HushSpec versioning is independent of any engine, SDK, or implementation. See Versioning for the full versioning policy.