claude-code-security-starter

English | 繁體中文 | 简体中文

A security starter pack for Claude Code beginners. CLAUDE.md rules and pre-built hooks stop credential leaks before they happen.

Watch this first

A recommended walkthrough, in Chinese:

Why

Claude Code sends file contents to Anthropic servers whenever it reads a file. By default, nothing stops it from reading your .env, your .clasprc.json, or any file with "secret" in the name if you or Claude ask for it by accident.

This pack closes those gaps with rules and five hooks:

Layer	What it stops
CLAUDE.md rules	Tells Claude what not to touch
block_sensitive_read	Read, Grep and Glob on credential files
bash_security_gate	cat .env and other shell reads, plus a confirmation before rm -rf, git reset --hard and force push
block_sensitive_write	Claude creating or editing credential files
block_sensitive_prompt	Sending a message that contains a real API key
pre_push_safety	Secrets, credential files and your real name or computer name in a git push

Quick Start

You need macOS or Linux with python3. Windows hasn't been tested.

This repo ships with a CLAUDE.md that tells Claude Code how to install everything. The easiest way:

git clone https://github.com/yyu0310/claude-code-security-starter
cd claude-code-security-starter
claude  # open Claude Code in this directory

Then say "install this" or "幫我安裝". Claude copies the hooks, configures your forbidden directories, and merges the settings for you.

Update an older install

Run git pull in this folder, open Claude Code here, and say "install this" again. Your FORBIDDEN_DIRS list is kept. Earlier versions only guarded the Read tool, so cat .env wasn't blocked.

Manual install

# 1. Copy hooks
mkdir -p ~/.claude/hooks
cp hooks/*.sh ~/.claude/hooks/
chmod +x ~/.claude/hooks/*.sh

# 2. Edit your forbidden directories
nano ~/.claude/hooks/block_sensitive_read.sh   # fill in FORBIDDEN_DIRS

# 3. Merge settings.example.json into ~/.claude/settings.json

# 4. Copy and adapt the CLAUDE.md template to your project
cp CLAUDE.md.template /path/to/your/project/CLAUDE.md
# Replace all <PLACEHOLDER> values

Restart Claude Code after installing. To check the hooks, run python3 tests/run_tests.py. It uses fake keys only.

Files

File	Purpose
CLAUDE.md.template	Security rules to paste into your project's CLAUDE.md
hooks/block_sensitive_read.sh	Blocks Read, Grep and Glob on .env, credentials and your forbidden paths
hooks/bash_security_gate.sh	Blocks shell reads of credential files and asks before destructive commands
hooks/block_sensitive_write.sh	Blocks Write and Edit on credential files
hooks/block_sensitive_prompt.sh	Blocks prompts that contain a real API key
hooks/pre_push_safety.sh	Scans git push for 25+ API key and token patterns, and for your identity
settings.example.json	Claude Code hook wiring, to merge into settings.json
tests/run_tests.py	Tests every hook with fake keys

What Gets Blocked

block_sensitive_read.sh

• Any path you add to FORBIDDEN_DIRS, such as your ~/secrets/ folder
• Any filename you add to FORBIDDEN_FILES
• .env and .env.*
• .clasprc* (Google clasp OAuth tokens)
• credentials.json, service-account.json
• Any filename containing secret, credential, token or key

bash_security_gate.sh

• Any command that mentions .env, .clasprc, credentials.json, service-account.json or a FORBIDDEN_DIRS path, unless every program in it is on a short safe list such as ls, stat and git add. Upper and lower case count as the same name
• Asks you before rm -rf, git reset --hard and force push

block_sensitive_write.sh

• .env, .env.*, .clasprc*, credentials.json, service-account.json and FORBIDDEN_DIRS paths
• .env.example, .env.sample and .env.template are allowed

Once Claude has written a file, Claude Code tracks it. If you later paste a real key into that file and save, the change can be reported back into the conversation. Create credential files yourself.

block_sensitive_prompt.sh

Anthropic and OpenAI keys, GitHub tokens, AWS keys, Slack tokens, Google API keys and private keys. Talking about a prefix such as sk- is fine, because each pattern also needs a real key's length.

pre_push_safety.sh

Regex patterns for: AWS, Google API, Anthropic, OpenAI, GitHub, GitLab, Stripe, SendGrid, Twilio, Slack, HuggingFace, Perplexity, Replicate, npm, Telegram Bot, HashiCorp Vault, PEM private keys, database connection strings (MongoDB, PostgreSQL, MySQL), and generic api_key = "..." patterns.

It also blocks commits whose author contains your computer name. Add your real name to IDENTITY_PATTERN to block that too.

What This Can't Do

These hooks match patterns, and they aren't a sandbox. Keep your secrets outside your projects as well.

• A recursive search from a parent folder can still reach a credential file
• Paths built from variables, wildcards such as cat cred*.json, split names such as cred''entials.json, and shell redirects such as echo x > .env aren't caught
• A push hidden inside bash -c '...' isn't scanned
• Prompt injection isn't stopped. A file you open can still try to give Claude instructions. The hooks can block some of what it asks for, such as reading a key
• Without python3, the hooks let everything through. Run the tests after installing to check

Because the match is on text, a harmless command that only mentions a credential filename, such as grep -n credentials.json README.md, gets blocked too.

How Hooks Work

Claude Code hooks are shell scripts that run at defined lifecycle events. A hook that exits with code 2 blocks the action and feeds stderr back to Claude as context.

PreToolUse → hook runs → exit 2 → tool call cancelled
                       → exit 0 → tool call proceeds normally

More on hooks: https://code.claude.com/docs/hooks

License

MIT