Protocol specificationv0.1.0Apache-2.0

Portable security rules for AI agents.

HushSpec is an open specification for declaring what an agent may access, invoke, and send at the tool boundary: one rule language across runtimes, frameworks, and languages.

Read the spec Get started

policy.yamlhushspec 0.1.0

hushspec: "0.1.0"
name: agent-boundary

rules:
  egress:
    allow: ["api.anthropic.com"]
    default: block
  forbidden_paths:
    patterns: ["**/.ssh/**", "**/.aws/**"]
  tool_access:
    confirm: [deploy_service]

evaluate

egress→api.anthropic.comallow

read→~/.ssh/id_ed25519deny

tool→deploy_servicewarn

01 The boundary

policy ≠ enforcement

Declare what, never how.

AI agents interact with tools: file systems, network APIs, shell commands, MCP servers. HushSpec is a standard way to declare which of those interactions are allowed, blocked, or require confirmation.

The separation

Policy is what you declare. Enforcement is how an engine applies it. HushSpec only ever specifies the first.

Engines like Clawdstrike implement the spec and add engine-specific features: detection algorithms, receipt signing, broker subsystems, async guard pipelines. The policy document stays portable between them.

fail-closed

Invalid input is rejected. Unknown fields and malformed shapes never pass silently.

stateless

Rules are pure declarations. No runtime state, no side effects, no hidden context.

engine-neutral

No coupling to any runtime. The same document moves between SDKs and engines.

extensible

Posture, origins, and detection thresholds ship as optional modules outside the core.

02 The rule language

10 rule types · 3 decisions

Ten rules, one language.

Every HushSpec document uses the same ten rule types. Each rule is a pure declaration: no runtime state, no detection algorithms, no plugin systems. Every evaluation resolves to allow, warn, or deny.

forbidden_paths

Block access to sensitive filesystem paths using glob patterns

path_allowlist

Allowlist-based read, write, and patch access control

egress

Network egress control by domain with allow/block lists

secret_patterns

Detect secrets in file content before they are written or transmitted

patch_integrity

Validate diff safety with size limits and forbidden patterns

shell_commands

Block dangerous shell commands before execution

tool_access

Control tool and MCP invocations with allow/block/confirm

computer_use

Control computer use agent actions with observe/guardrail modes

remote_desktop_channels

Control clipboard, file transfer, and drive mapping side channels

input_injection

Control keyboard, mouse, and touch input injection capabilities

Field-level documentation for every rule lives in the rules reference.

03 The SDKs

rust · typescript · python · go

Four languages, a shared core.

Every SDK implements the full evaluator pipeline. Receipts, sinks, and detection helpers are available across all four. Runtime integrations differ by language, but the decision model never does.

parse→validate→merge→resolve→evaluate

SDK	Level	Parse	Validate	Merge	Resolve	Evaluate	Audit	Detection
Rust	Level 3	yes	yes	yes	yes	yes	yes	yes
TypeScript	Level 3	yes	yes	yes	yes	yes	yes	yes
Python	Level 3	yes	yes	yes	yes	yes	yes	yes
Go	Level 3	yes	yes	yes	yes	yes	yes	yes

TypeScript adds Anthropic, OpenAI, and MCP adapters plus watcher and poller support. Python adds adapters and an observer layer. Rust is the reference implementation and currently the only SDK with Ed25519 signing. Full detail in the SDK conformance matrix.

04 Tooling

11 subcommands

The h2h command line.

h2h, hush to hush: one binary for the whole policy lifecycle. Validate, test, lint, and diff policies in CI; sign and verify them for distribution; flip the panic switch when something goes wrong.

h2h validate policy.yaml

Validate against the HushSpec schema

h2h test --policy policy.yaml --fixtures ./tests/

Run evaluation test suites

h2h init --preset default

Scaffold a new policy project

h2h lint policy.yaml

Static analysis and best-practice checks

h2h diff old.yaml new.yaml

Compare policies, show decision changes

h2h fmt policy.yaml

Format policy files canonically

h2h audit policy.yaml

Display governance metadata and advisory checks

h2h panic activate --sentinel /tmp/hushspec.panic

Emergency deny-all kill switch

h2h sign policy.yaml --key h2h.key

Sign a policy with Ed25519

h2h verify policy.yaml --key h2h.pub

Verify a policy file's detached signature

h2h keygen --output-dir ./keys

Generate a new Ed25519 keypair

Install and usage documentation in the CLI reference.

05 Ready to use

7 built-in profiles

Rulesets, ready to extend.

Seven built-in rulesets cover common deployment scenarios. Reference them with extends: and layer your own rules on top; the merge semantics are part of the spec.

default

Balanced security for AI agent execution

strict

Maximum security, minimal permissions

permissive

Development-friendly, relaxed limits

ai-agent

Optimized for AI coding assistants

cicd

CI/CD pipeline security

remote-desktop

Computer use agent sessions

panic

Deny-all emergency override

06 Beyond core

3 optional modules

Extensions, kept outside.

Three optional modules add state machines, origin-aware profiles, and detection thresholds without bloating the core. A conforming engine may implement none of them.

x-posturePostureA declarative state machine for capabilities and budgets. Transition between security postures on violations, timeouts, or approvals.Read the extension x-originsOriginsOrigin-aware policy projection. Apply different security profiles based on whether work arrives from Slack, GitHub, email, or other sources.Read the extension x-detectionDetectionThreshold configuration for prompt injection, jailbreak, and threat intelligence screening. Policy without algorithms.Read the extension

Declare the boundary once. Any engine can enforce it.

Get started

Open specification · The normative spec, JSON Schemas, four SDKs,
the CLI, conformance fixtures, and built-in rulesets, all Apache-2.0.