Crate vallum 

Vallum

A security boundary between AI coding agents (Claude Code, and any agent via vallum run) and your shell. When an agent runs a command, Vallum redacts secrets, neutralizes prompt-injection attempts, wraps the result as untrusted data, preserves the child exit code, and audits everything — so what reaches the model is exactly what you intend it to see. As a side benefit it strips ANSI noise and compresses long output, which also saves tokens.

This crate is a CLI

Vallum is primarily the vallum command-line tool. Install it with cargo install vallum (or via shell installer, Homebrew, or npm — see the README) and run, for example, vallum run -- cargo test. The full pipeline, configuration, security model, and Claude Code integration are documented in the README and the threat model in SECURITY.md.

Library surface

The modules below are published so the crate’s integration tests can drive the pipeline internals. They are not a stable public API: semver applies to the CLI’s behavior, not to these items, which may change between releases. Build on the vallum binary, not on this crate.

Modules

ansi

Strip ANSI escape sequences (color and cursor-control) from captured output.

approval

Machine-local approval secret and per-command HMAC tokens. The Claude hook mints a token when it re-wraps an approved command through vallum run; run verifies it before skipping the guardrail. A forged or injected --approval-token cannot match without the secret, so it is re-gated.

audit

Append-only writer for the raw and sanitized audit logs under ~/.vallum/logs.

breaker

Blast-radius circuit breaker: counts guardrail Ask/Deny verdicts in a sliding window (state file under flock); past the threshold, every command is denied until the cooldown expires or vallum unlock.

cli

Command-line argument parsing (clap) for the vallum subcommands.

config

Configuration: loading, defaults, and validation of ~/.vallum/config.toml.

doctor

vallum doctor — install/health self-checks (config, hook, PATH, log dir).

executor

Run the child command with concurrent capture, a byte cap, a timeout, inherited stdin, and an optional live tee.

fsutil

Private (0600) append-file helper shared by the audit and stats writers.

hook

Pre-exec guardrail hooks: shared Allow/Ask/Deny decision core plus per-agent stdin/stdout protocol codecs.

install_hook

Install/uninstall Vallum’s pre-exec hook in agent config files. Shared JSON-merge machinery lives here; each agent has a module with its config path, entry shape, and add/remove logic.

logchain

Hash-chained append + verification for the policy audit log (policy.log). Each entry carries Chain: sha256(prev_hash ++ body); vallum log verify recomputes the chain from genesis. See SECURITY.md for the honest limits (tail truncation needs an external head anchor).

mcp

Static MCP configuration scanner: discover config files and flag embedded secrets, risky launch commands, and injection in embedded descriptions. Read-only — connects to nothing, launches nothing, modifies nothing.

metrics

Token estimation and the per-command JSONL stats writer (~/.vallum/stats.jsonl).

optimizer

Per-command output optimizers: the CommandOptimizer trait and dispatch registry.

policy

Pre-exec command policy: evaluate a command line against dangerous-command rules and return Allow / Ask / Deny. Plain-text regex matching over one joined command line — no shell parsing (same posture as the scrubber).

scrubber

The scrub pipeline: secret redaction, prompt-injection neutralization, input normalization, and untrusted-output wrapping.

stats

Aggregate and render the vallum stats token-savings report.

tokenizer

Pluggable TokenEstimator with a dependency-free heuristic default.

truncator

Context-preserving head/tail truncation that keeps error lines in place.

update

vallum update: report whether a newer release exists and how to get it.

welcome

The bare-vallum welcome screen: a branded status + quick-start banner.

whitespace

Collapse runs of blank lines and strip trailing whitespace.