claude-guardrails

Hardened security configuration for Claude Code — deny rules, hooks, and prompt injection defense out of the box.

Why This Exists

Claude Code can read your filesystem, run shell commands, and fetch URLs autonomously. A poisoned file in a cloned repo can hijack its behavior via prompt injection. A careless tool call can leak your SSH keys or .env secrets. These configs add defense-in-depth so you don't have to think about it on every session.

Full vs Lite

Quick Start

# Install jq if you don't have it
brew install jq          # macOS
# sudo apt install jq    # Debian/Ubuntu

# Lite (3 hooks, 15 deny rules — for trusted projects)
npx claude-guardrails install

# Full (5 hooks + prompt injection scanner — for untrusted codebases)
npx claude-guardrails install full

The script merges into your existing ~/.claude/settings.json (backing it up first) and is safe to run repeatedly.

git clone https://github.com/dwarvesf/claude-guardrails.git
cd claude-guardrails
./install.sh          # lite
./install.sh full     # full

If you prefer to install manually, see full/SETUP.md for step-by-step instructions. The key steps are:

1. Copy the variant's settings.json to ~/.claude/settings.json (or merge permissions.deny and hooks.PreToolUse arrays into your existing config)
2. Append the variant's CLAUDE-security-section.md to ~/.claude/CLAUDE.md
3. Copy scan-secrets.sh to ~/.claude/hooks/scan-secrets/ and add the UserPromptSubmit hook entry to settings
4. (Full only) Copy prompt-injection-defender.sh to ~/.claude/hooks/prompt-injection-defender/ and add the PostToolUse hook entry to settings

Uninstall

# Remove lite guardrails
npx claude-guardrails uninstall

# Remove full guardrails
npx claude-guardrails uninstall full

./uninstall.sh          # lite
./uninstall.sh full     # full

The uninstall uses a surgical remove approach — it reads the variant's config to identify exactly which deny rules and hooks were added, then subtracts only those entries from your ~/.claude/settings.json. Your own custom rules, hooks, and other settings are left untouched. It does not restore from a backup, which means it works correctly even if you modified your settings after install.

A pre-uninstall backup is saved to ~/.claude/settings.json.pre-uninstall in case you need to roll back.

How It Works

Six layers, each covering gaps the others miss:

1. Permission deny rules — Block Claude's Read/Edit tools from touching sensitive paths (SSH keys, .env, credentials). Limitation: bash cat bypasses these.
2. PreToolUse hooks — Block dangerous bash commands before execution (destructive deletes, direct pushes, pipe-to-shell). Limitation: pattern-based, obfuscation can bypass.
3. UserPromptSubmit secret scanner — scan-secrets.sh (bash + jq) blocks prompts containing live credentials (AWS keys, GitHub tokens, Anthropic keys, PEM blocks, BIP39 phrases). Prevents pasted secrets from being persisted to the session transcript on disk.
4. OS-level sandbox (/sandbox) — Filesystem and network isolation at the OS level. The only layer bash can't bypass. Must be enabled per-session.
5. PostToolUse prompt injection scanner (full only) — Scans Read/WebFetch/Bash outputs for injection patterns. Warns but doesn't block to avoid false positives.
6. CLAUDE.md security rules — Natural language instructions telling Claude to avoid hardcoded secrets, treat external content as untrusted, etc.

No single layer is sufficient. That's the point.

See full/SETUP.md for detailed explanations of each layer and their limitations.

Known Tradeoffs

These guardrails trade convenience for safety. Be aware of what you're signing up for:

False positives will interrupt your workflow. The glob patterns are intentionally broad. Read **/*.key blocks all .key files — including legitimate ones like translation.key or config.key. Read **/*secret* (full) blocks files like secret_santa.py. rm -rf hook triggers on cleaning build directories (rm -rf dist/). When this happens, you'll need to run the command manually or temporarily adjust the rule.

Deny rules only cover Claude's built-in tools, not bash. Read ~/.ssh/id_rsa is denied, but bash cat ~/.ssh/id_rsa is not. The hooks catch some bash patterns, but they can't catch everything. This is a fundamental limitation of pattern matching — the OS-level sandbox (/sandbox) is the only real enforcement layer.

Hooks add latency to every Bash call. Each PreToolUse hook spawns a subshell, pipes through jq, and runs grep. With 3 hooks (lite) that's 3 extra processes per Bash tool call. With 5 hooks + PostToolUse scanner (full), it's 6. Noticeable on slower machines or rapid-fire commands.

The prompt injection scanner is noisy. It pattern-matches strings like "ignore previous instructions" and "system prompt:" — which appear in legitimate security docs, CTF writeups, and this README. Expect warnings when reading security-related content. It warns but doesn't block, so the cost is distraction rather than breakage.

Full variant overrides some global settings. full/settings.json sets alwaysThinkingEnabled: true and cleanupPeriodDays: 90. The merge in install.sh uses jq's * operator, so these will overwrite your existing values for those keys. Review the diff after install if you have custom global settings.

No easy per-file exceptions. If you legitimately need Claude to read a .env.example or a test .pem file, there's no allowlist mechanism. You either remove the deny rule, use bash to read the file, or copy the file to a non-matching path. This is a gap in Claude Code's permission model, not something we can fix here.

Untrusted Repos

Before opening any cloned repo with Claude Code, check for hidden config:

find . -path "*/.claude/*" -o -name ".mcp.json" -o -name "CLAUDE.md" | head -20

A malicious repo can ship .claude/hooks/ with arbitrary shell scripts, .mcp.json with exfil-capable MCP servers, or CLAUDE.md with prompt injection. Inspect before you trust.

References

• Trail of Bits — claude-code-config
• Trail of Bits — claude-code-devcontainer
• Lasso Security — Claude hooks prompt injection defender
• Anthropic — Claude Code security docs
• Anthropic — Hooks reference
• Snyk — ToxicSkills study
• Check Point Research — CVE-2025-59536

Maintained by Dwarves Foundation.