Documentation

Rule Engine

Warden ships with hundreds of compiled patterns organized into categories:

Category	Examples
Safety	Block `rm -rf`, `sudo`, `chmod 777`, force pushes, credential file writes
Substitution	Redirect `grep` → `rg`, `find` → `fd`, `curl` → `xh`, `cat` → `bat`
Hallucination	Detect invented CLI flags, non-existent subcommands, wrong argument patterns
Path protection	Prevent writes to `.env`, credentials, system files, lock files
Git policy	Block mutating git commands (push, merge, rebase) unless explicitly allowed
Advisory	Suggest better approaches, warn about large file reads, flag verification debt

Rules are compiled into the binary — no runtime parsing, no config files to maintain. New rules ship with every release. Run warden describe --all to see the exact count and details.

How Rules Work

All patterns are evaluated simultaneously using a compiled regex set. The evaluation cost doesn’t grow linearly with the number of rules — a single pass checks everything.

Rules are available the instant Warden loads. They can’t go missing, get corrupted, or fail to download. When you update Warden, you get the exact rule set tested against that version.

You can extend the built-in rules with TOML overrides (see Configuration), but the compiled floor is always present.

Rule Categories in Detail

Safety — universally dangerous operations that are always blocked:

rm -rf on broad paths (~, /, ., *)
Privilege escalation (sudo, su -, doas, runas)
Dangerous permissions (chmod 777, chmod -R 777, chmod a+w)
System damage (mkfs, dd if=, format C:, diskpart)
Process killing (kill -9 1, killall, pkill -9)
Environment destruction (export PATH=, unset PATH)

Substitution — redirects legacy tools to modern alternatives:

grep to rg (ripgrep) — 10-50x faster regex search
find to fd — faster file discovery with sane defaults
curl to xh — friendlier HTTP client with colored output
cat to bat — syntax highlighting and line numbers
du to dust — visual disk usage tree
tar/zip/unzip/gzip to ouch — auto-detecting archive tool
sort | uniq to huniq — faster, preserves insertion order
sd blocked on Windows — mangles newlines, use the Edit tool instead

Hallucination — catches commands the agent fabricated:

URL-encoded path traversal (%2e%2e/)
Null byte injection (\x00, %00)
Reverse shell patterns (/dev/tcp/, socat EXEC:, ncat -e)
Credential exfiltration (piping .ssh/id_rsa or .env to curl/wget)
Command hijacking (alias sudo=..., eval $(curl ...))
Base64-decoded command execution

Path protection — prevents writes to sensitive locations:

SSH keys and config (~/.ssh/)
GPG keys (~/.gnupg/)
Cloud credentials (~/.aws/credentials, ~/.azure/, ~/.kube/config, ~/.gcloud/)
Docker credentials (~/.docker/config.json)
System directories (/etc/, /usr/, C:\Windows, C:\Program Files)
Certificate and key files (.pem, .key, .p12, .pfx)
Terraform state (~/.terraform/)

Git policy — enforces read-only git by default:

Blocks git push, git merge, git rebase, git reset
Blocks git checkout, git restore, git cherry-pick
Blocks git stash (save), git branch -d/-D, git tag
Allows read-only commands: log, status, diff, show, branch (list), blame

Advisory — non-blocking hints for better practices:

Docker CLI usage when MCP tools are available
rg for symbol lookups when aidex is available
rg for structural patterns when ast-grep is available
npm install, cargo add, pip install warnings about environment modification
git clone warnings about disk space and time

Shadow Mode

Rules can be set to shadow mode, where they log what they would have done without actually blocking. This is useful for testing new rules before deploying them:

# In ~/.warden/rules.toml
[safety]
patterns = [
  { match = "some-new-pattern", msg = "Testing this rule", shadow = true }
]

Shadow-mode entries show up in warden stats and warden export data, so you can evaluate their accuracy before making them live.

Rule IDs

Every rule has a stable ID for configuration and debugging:

ID	Rule
`safety.0`	Block `rm -rf` on broad paths
`safety.3`	Block `sudo`
`substitution.0`	Redirect `grep` to `rg`
`substitution.1`	Redirect `find` to `fd`
`hallucination.4`	Block reverse shell patterns
`sensitive_deny.0`	Block writes to `.ssh/`

Rule IDs are used for:

Disabling rules in config: disabled = ["substitution.0"]
Explaining rules: warden explain safety.3
Filtering stats: seeing how often a specific rule fires

Viewing All Rules

warden describe --all

This prints every active rule with its ID, category, severity (HardDeny, SoftDeny, or Advisory), pattern, and message. Safety rules marked as HardDeny cannot be disabled — they’re the immutable floor of protection.