Vallum

The wall between AI coding agents and your shell.

Vallum is a single Rust CLI that sits between an AI coding agent and your terminal. It stops dangerous commands before they run, redacts secrets and neutralizes prompt-injection in command output before it reaches the model, and audits everything — for Claude Code, Cursor, Codex, Gemini CLI, or any agent that runs shell commands.

What it does

Measured, not claimed. Over a committed, labeled corpus: injection recall 0.858 · precision 1.000 · benign false-positive rate 0.000; known-format secret recall 1.000. Numbers are evidence, not a guarantee — full report.

Quick start

# 1. Install (macOS + Linux)
curl --proto '=https' --tlsv1.2 -LsSf https://github.com/kahramanemir/Vallum/releases/latest/download/vallum-installer.sh | sh

# 2. Try it on any command
vallum run cargo test

# 3. Gate your agent — pick Claude Code, Cursor, Gemini CLI, or Codex CLI
vallum install-hook

After installing the hook, dangerous commands are gated inside your agent's own approval flow. Check the install anytime with vallum doctor.

Install

Prebuilt binaries for macOS (Intel + ARM) and Linux (x86_64 + aarch64) — with SHA-256 checksums and build-provenance attestations — are attached to every GitHub Release. Attestation verification, source builds, and the exact-BPE token-count feature: CLI reference → Install.

Works with your agent

vallum run works with any agent that runs shell commands. The pre-exec guardrail also hooks natively into Claude Code, Cursor, Gemini CLI, and Codex CLI — one vallum install-hook and dangerous commands are gated inside the agent's own approval flow. Output sanitization and token optimization run on Claude Code (and any explicit vallum run); on the other three agents Vallum gates commands without rewriting their output. Full matrix, per-agent behavior, and honest limitations: Agent integrations.

Everyday commands

vallum run <command> [args...]   # run any command through the security pipeline
vallum install-hook              # hook your agent(s) — interactive picker
vallum policy test "<command>"   # what would the guardrail say? (exit 0/10/20)
vallum mcp scan                  # scan MCP server configs for risks
vallum skills scan               # scan skills + agent context files for poisoning
vallum stats                     # cumulative token savings
vallum doctor                    # health self-check
vallum update                    # check for a newer release

Every command, JSON output, and exit codes: CLI reference.

How it works

Command output is untrusted input: it can leak secrets into the model's context, carry adversarial "ignore previous instructions" text, and bury the signal in noise. Vallum puts a controlled boundary in between — before a command runs it is checked against the guardrail policy, and after it runs the output is scrubbed, wrapped in untrusted-data markers, and audited. Pipeline stages, the security model, and the module map: Architecture.

Scope of the guarantees. Secret redaction and injection neutralization are best-effort, pattern-based defenses — they raise the cost of an attack, they don't replace treating terminal output as untrusted. The full threat model, mechanism by mechanism, is in SECURITY.md.

Fewer asks over time

Repeated approvals stop being asked: an approved Ask is remembered (exact command + directory, narrow rule set, 14-day TTL, HMAC-signed) and [[policy.allow]] lets you carve a scoped exception for one rule without disabling it. Every downgrade is audit-logged. See docs/guardrail.md.

CI & automation

One command gates a repo: vallum scan . (exit 0 clean / 10 warnings / 20 high / 125 error). GitHub code scanning:

- uses: kahramanemir/Vallum@v0.9.0   # pin to a release tag
  with:
    paths: "."
    fail-on: high

pre-commit:

- repo: https://github.com/kahramanemir/Vallum
  rev: v0.9.0
  hooks:
    - id: vallum-scan   # requires an installed vallum

Optional session-start scanning for Claude Code: vallum install-hook --agent claude --session-scan injects a one-line warning into new sessions when a scan finds issues (never blocks startup).

Commit policy with your repo

Drop a .vallum.toml at the repo root and PR-review it like code — every hooked agent and vallum scan . in CI enforce it:

[[policy.rules]]
pattern = 'terraform\s+destroy'
action = "deny"
reason = "prod guard"

Project config is tighten-only: it can add ask/deny rules and nothing else. It cannot disable rules, add allow exceptions, touch logging, or change any setting — a cloned repo can never weaken your guardrail. A file that tries is ignored with a warning (vallum doctor shows why). Scaffold one with vallum config init --project; opt out per shell with VALLUM_NO_PROJECT_CONFIG=1.

Documentation

Name

Vallum — Latin for the defensive embankment along Roman frontier fortifications. The thing that stands between what's inside and what's outside.

License

Licensed under either of

• Apache License, Version 2.0, (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
• MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT)

at your option.

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in this work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.