HushSpec

About

What is HushSpec?

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

It separates policy (what you declare) from enforcement (how an engine applies it). Engines like Clawdstrike implement the spec and add engine-specific features like detection algorithms and receipt signing.

Fail-closed - invalid input is rejected Stateless - pure declarations Engine-neutral - no runtime coupling Extensible - optional modules

Shared core, language-specific helpers

All SDKs implement: parse, validate, merge, resolve, evaluate. Receipts, sinks, and detection helpers are also available across the SDKs. Higher-level integrations vary by language: TypeScript adds adapters and hot reload, Python adds adapters and observers, and Rust adds signing.

evaluate.ts

import { parseOrThrow, evaluate } from '@hushspec/core';

const spec = parseOrThrow(policyYaml);
const result = evaluate(spec, {
  type: 'egress',
  target: 'api.openai.com'
});
// result.decision === 'allow' | 'warn' | 'deny'
// result.matched_rule === 'egress'

Core Specification

10 Rules, One Language

Every HushSpec document uses the same 10 rule types. Each rule is a pure declaration - no runtime state, no detection algorithms, no plugin systems.

01

forbidden_paths

Block access to sensitive filesystem paths using glob patterns

02

path_allowlist

Allowlist-based read, write, and patch access control

03

egress

Network egress control by domain with allow/block lists

04

secret_patterns

Detect secrets in file content before they are written or transmitted

05

patch_integrity

Validate diff safety with size limits and forbidden patterns

06

shell_commands

Block dangerous shell commands before execution

07

tool_access

Control tool and MCP invocations with allow/block/confirm

08

computer_use

Control computer use agent actions with observe/guardrail modes

09

remote_desktop_channels

Control clipboard, file transfer, and drive mapping side channels

10

input_injection

Control keyboard, mouse, and touch input injection capabilities

SDKs

Four Languages, Shared Core

Every SDK implements the full evaluator pipeline: parse, validate, merge, resolve, evaluate. Runtime integrations differ by language, but the core decision model is shared across all four.

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/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.

Tooling

The `h2h` CLI

h2h ("hush to hush") - 11 subcommands for policy management: validate, test, init, lint, diff, fmt, audit, panic, sign, verify, and keygen.

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

Ready to Use

Built-in Rulesets

7 ready-to-use security rulesets covering common deployment scenarios. Extend them with extends: to customize for your use case.

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

Beyond Core

Extension Modules

Three optional extensions add state machines, origin-aware profiles, and detection thresholds without bloating the core.

Posture

Declarative state machine for capabilities and budgets. Transition between security postures on violations, timeouts, or approvals.

Origins

Origin-aware policy projection. Apply different security profiles based on whether work comes from Slack, GitHub, email, or other sources.

Detection

Threshold configuration for prompt injection, jailbreak, and threat intelligence screening. Policy without algorithms.

Open Source

Apache-2.0

HushSpec is an open specification. The normative spec, JSON Schema definitions, all four SDKs, the CLI, conformance test fixtures, and built-in rulesets are available on GitHub under the Apache-2.0 license.

View on GitHub