HushSpec

HushSpec is a portable, open specification for declaring security rules at the tool boundary of AI agent runtimes. It defines what an agent may do without prescribing how a runtime enforces those controls.

Why HushSpec?

AI agents interact with file systems, network APIs, shell commands, browsers, MCP servers, and remote desktop surfaces. HushSpec provides a shared rule language for declaring which of those interactions are allowed, blocked, or require confirmation.

  • Portable: the same policy can move between SDKs and engines
  • Declarative: the document describes policy intent, not engine internals
  • Fail-closed: unknown fields and invalid shapes are rejected
  • Composable: extends plus defined merge semantics support layered policies
  • Extensible: posture, origins, and detection thresholds stay optional

What Ships Today

  • Four SDKs: Rust, TypeScript, Python, and Go all implement parse, validate, merge, resolve, and evaluate
  • The h2h CLI: validate, test, init, lint, diff, fmt, audit, panic, sign, verify, and keygen
  • Seven built-in rulesets for common deployment profiles
  • Compliance and scenario policy packs for healthcare, finance, government, education, DevOps, and general hardening
  • A shared evaluator fixture corpus that CI runs across all four SDKs

A Minimal Example

yaml 
hushspec: "0.1.0"
name: my-policy

rules:
  forbidden_paths:
    patterns:
      - "**/.ssh/**"
      - "**/.aws/**"

  egress:
    allow:
      - "api.openai.com"
      - "*.anthropic.com"
    default: block

  tool_access:
    block:
      - shell_exec
      - run_command
    default: allow

Spec vs Engine

HushSpec defines the portable rule language. Engines like Clawdstrike implement that language and add engine-specific pieces such as detection algorithms, receipt signing, broker subsystems, or async guard pipelines.

Current Status

HushSpec v0.1.0 is still unstable. Breaking changes may occur between minor versions before the format stabilizes at v1.0. The Rust crate, TypeScript package, and Python package are published, and the Go SDK is consumed from the public module path github.com/backbay-labs/hush/packages/go.

Explore the Documentation

Core Spec
Document structure, validation rules, and the 10 core rule types.
Rules Reference
Detailed field documentation for all 10 rule types with examples.
Getting Started
Install the SDK in Rust, TypeScript, Python, or Go and parse your first document.
Your First Policy
Step-by-step guide to writing, validating, and testing a HushSpec policy.
Conformance
The four conformance levels and the shared fixture corpus behind them.
JSON Schema
Machine-readable schemas for policies, receipts, signatures, and evaluator fixtures.
CLI Reference
Install and use the h2h CLI for policy validation, testing, signing, and panic mode.
Next
HushSpec Core