hushspec 0.1.1

Portable specification for AI agent security rules

hushspec

Portable specification types for AI agent security rules.

hushspec is the Python SDK for the HushSpec open policy format. Parse, validate, evaluate, and enforce security rules for AI agent runtimes.

Installation

pip install hushspec

Requires Python 3.10+.

Quick Start

from hushspec import parse_or_raise, validate, evaluate

policy = parse_or_raise("""
hushspec: "0.1.0"
name: my-policy
rules:
  egress:
    allow: ["api.github.com"]
    block: []
    default: block
""")

# Validate
result = validate(policy)
assert result.is_valid

# Evaluate an action
decision = evaluate(policy, {"type": "egress", "target": "api.github.com"})
assert decision.decision == "allow"

HushGuard Middleware

HushGuard wraps policy loading and evaluation behind a simple interface.

from hushspec import HushGuard

guard = HushGuard.from_file("./policy.yaml")

# Check without raising
result = guard.check({"type": "tool_call", "target": "bash"})
if result.decision == "deny":
    print(f"Blocked: {result.reason}")

# Or enforce (raises HushSpecDenied on deny)
guard.enforce({"type": "egress", "target": "api.openai.com"})

Features

Evaluation

from hushspec import parse_or_raise, evaluate

spec = parse_or_raise(policy_yaml)
result = evaluate(spec, {"type": "egress", "target": "evil.example.com"})
# result.decision: "allow" | "warn" | "deny"
# result.matched_rule: "rules.egress.default"

Audit Trail

from hushspec import parse_or_raise, evaluate_audited

receipt = evaluate_audited(spec, action, {
    "enabled": True,
    "include_rule_trace": True,
    "redact_content": False,
})
# receipt.decision, receipt.rule_evaluations, receipt.policy_summary

Detection Pipeline

Plug prompt injection, jailbreak, and exfiltration checks into the evaluation flow.

from hushspec import evaluate_with_detection, DetectorRegistry

registry = DetectorRegistry.with_defaults()
result = evaluate_with_detection(spec, action, registry, {
    "enabled": True,
    "prompt_injection_threshold": 0.5,
})

Receipt Sinks

Route decision receipts to files, stderr, or custom callbacks.

from hushspec import FileReceiptSink, FilteredSink, MultiSink

sink = MultiSink([
    FileReceiptSink("/var/log/hushspec-receipts.jsonl"),
    FilteredSink(stderr_sink, lambda r: r.decision == "deny"),
])

Panic Mode

from hushspec import activate_panic, deactivate_panic, is_panic_active

activate_panic()
# All evaluate() calls now return deny
deactivate_panic()

CLI

The h2h CLI tool provides validate, lint, test, diff, format, sign, and more:

cargo install hushspec-cli
h2h validate policy.yaml
h2h lint policy.yaml

License

Apache-2.0