backbay-labs/hush

Give your agents boundaries you can read. Get decisions you can verify.

What  ·   Quickstart  ·   How it works  ·   SDKs  ·   CLI  ·   Policies  ·   Docs  ·   Spec

What is HushSpec?

HushSpec is an open specification for the security controls an AI agent operates under. Write a policy in YAML, evaluate it in Rust, TypeScript, Python, or Go, and produce receipts that tie each decision to the policy behind it.

It covers the things agents actually touch: files, networks, shells, tools, browsers, and code execution. The spec defines the rules and their meaning; your runtime enforces the boundary through HushGuard or its own integration.

Spec 1.0.0 is stable. The document format, evaluation semantics, canonical form, and wire formats are frozen for the 1.x series. See the versioning policy and SDK conformance matrix for the contracts and their test coverage.

The 1.0 SDK release is not yet published. See the delivery status for implementation, qualification, and release evidence.

The experimental external conformance controller tests a captured executable against the L0-L3 corpus and retains its inputs, outputs and identity. The Go adapter is first-party bring-up, not independent engine or runtime-boundary qualification.

The experimental trusted invocation coordinator checks a host-qualified MCP tool and its effects against one authenticated policy snapshot, records a durable permit, then dispatches. Its isolated coding pilot tests real edits, blocked operations and crash evidence. This is a scoped first-party demonstration, not external adoption or general MCP containment.

Quickstart

Build the h2h CLI from this checkout:

cargo install --path crates/hushspec-cli --locked

Save this as policy.yaml. It protects credentials, restricts network access, and asks for confirmation before a tool can write a file or push code.

hushspec: "1.0.0"
name: production-agent

rules:
  forbidden_paths:
    patterns: ["**/.ssh/**", "**/.aws/**", "/etc/shadow"]

  egress:
    allow: ["api.openai.com", "*.anthropic.com", "api.github.com"]
    default: block

  tool_access:
    allow: [file_read, search]
    block: [shell_exec, run_command]
    require_confirmation: [file_write, git_push]
    default: block

Validate it, then try three decisions:

h2h validate policy.yaml

h2h eval policy.yaml --type egress --target api.openai.com
# allow

h2h eval policy.yaml --type tool_call --target shell_exec
# deny

h2h eval policy.yaml --type tool_call --target file_write
# warn: confirmation required

These commands evaluate actions; they do not execute them. eval exits with 0 for allow, 1 for deny, and 4 for warn. A runtime must handle the decision before dispatching the action. Wire it into your agent →

From policy to proof

Put the check before the action

HushGuard loads the policy and brings evaluation, enforcement modes, confirmation, receipt sinks, and observers together. Call enforce before dispatching a tool:

import { HushGuard } from '@hushspec/core';

const guard = HushGuard.fromFile('./policy.yaml');

guard.enforce({ type: 'tool_call', target: 'shell_exec' });
// Throws HushSpecDenied under the quickstart policy.

A policy that fails required signature verification produces a refused guard: every action is denied with __hushspec_policy_unverified__. A failed hot reload keeps the last valid policy in force. Unknown fields and invalid documents are rejected explicitly.

The enforcement boundary is the runtime's responsibility. HushSpec supplies the portable policy contract and SDK primitives to build it. Runtime integration guide →

Keep the evidence with the decision

Audited evaluation takes a resolved policy and returns a receipt containing its canonical content_hash, the decision, actor context, rule and detection traces, and enforcement disposition. Action content is represented by its hash and byte size, without embedding the raw content.

# Inspect the receipt for one evaluated action.
h2h eval policy.yaml --type egress --target api.openai.com --format receipt

The evidence can travel beyond the runtime:

Ed25519 signatures cover the resolved policy's content hash, so reformatting a file preserves its signature while changing an inherited rule invalidates it. Signing, receipt verification, and bundle verification are available across all four SDKs; Rust requires the signing feature and Python the signing extra.

SDKs and integrations

One policy language across four SDKs. The shared corpus checks evaluation, canonical bytes, policy hashes, and receipt formats across implementations.

Until 1.0 is published, use this source checkout. The registry commands below are for the upcoming release, not currently available 1.0 packages.

The Go SDK release will use the nested packages/go/v1.0.0 tag. For signing, use hushspec = { version = "1.0", features = ["signing"] } in Rust or pip install "hushspec[signing]" in Python.

use hushspec::HushSpec;

let yaml_str = "hushspec: \"1.0.0\"\nname: example\n";
let spec = HushSpec::parse(yaml_str)?;
let result = hushspec::validate(&spec);
assert!(result.is_valid());

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

const yamlString = 'hushspec: "1.0.0"\nname: example\n';
const spec = parseOrThrow(yamlString);
const result = validate(spec);
console.log(result.valid); // true

from hushspec import parse_or_raise, validate

yaml_string = 'hushspec: "1.0.0"\nname: example\n'
spec = parse_or_raise(yaml_string)
result = validate(spec)
assert result.is_valid

import (
    "fmt"

    "github.com/backbay-labs/hush/packages/go/hushspec"
)

yamlString := "hushspec: \"1.0.0\"\nname: example\n"
spec, err := hushspec.Parse(yamlString)
if err != nil {
    panic(err)
}
result := hushspec.Validate(spec)
fmt.Println(result.IsValid())

Framework adapters

Adapters translate tool calls into HushSpec actions without importing the framework they adapt. Use the same policy across agent stacks.

Rust applications can start from the guarded_agent example. Adapter entry points →

The existing adapters evaluate actions; they do not own dispatch or contain tool servers. For an opt-in TypeScript dispatch boundary, see the trusted invocation pilot.

Policy tooling

The h2h CLI covers the policy lifecycle in 22 commands.

# Show the rules behind a decision.
h2h explain policy.yaml --type egress --target api.example.com

# Fail CI when a policy change can relax a denial.
h2h diff main.yaml pr.yaml --fail-on relaxed

# Check your policy's control mappings.
h2h audit policy.yaml --controls --strict

# Verify a hash-linked receipt log.
h2h log verify receipts.jsonl

The CLI reference covers flags, JSON/SARIF/JUnit output, and exit codes. Editor setup adds schema validation and completions while you write.

- uses: backbay-labs/[email protected]
  with:
    command: validate
    paths: policies/**/*.yaml

Policy library

Start with a built-in policy and extend it for your environment. Rulesets and library policies are embedded in all four SDKs.

hushspec: "1.0.0"
name: clinical-agent
extends: "builtin:library/healthcare/hipaa-base"

Library templates include structured control mappings and control-tagged evaluation suites. They are starting points for your environment, not compliance certifications.

HushSpec policies also load natively in Clawdstrike.

Specification

The specification is the contract. The SDKs, schemas, and fixtures make it executable.

Contributing

The contributor guide covers setup, checks, and the fixture-first workflow for SDK changes. Specification changes follow the governance process; vulnerabilities go through security reporting.

spec/        Normative specifications and registries
schemas/     JSON Schema definitions
crates/      Rust SDK, h2h CLI, and conformance testkit
packages/    TypeScript, Python, and Go SDKs
rulesets/    Built-in security policies
library/     Control-mapped policy templates
fixtures/    Shared conformance and evaluation vectors
docs/        Guides, references, and mdBook sources
generated/   Shared SDK contract artifacts
scripts/     Code generation and CI checks

HushSpec
_{Declare the boundary. Carry the evidence.}

Apache-2.0  ·   Changelog  ·   Governance  ·   Security