secret-warn

secret-warn — real-time edit-time security guardrails

Catches secrets and unsafe patterns the moment a Claude Code agent writes them, not after the fact. Public substrate version (MIT). Free to install, free to extend.

What it does

Trigger	Severity	Action
API key in file (Stripe, AWS, GCP, OpenAI, Anthropic, GitHub, Slack)	block (exit 2)	Edit rejected
PEM-encoded private key block	block	Edit rejected
High-entropy assignment to a key-named variable	warn (exit 1)	Advisory, edit proceeds
Python dynamic-codegen on a user-input-suggesting name	warn	Advisory
Subprocess with shell-mode + variable expansion	warn	Advisory
Curl/wget pipe-to-shell from a non-allowlisted host	block	Edit rejected

All patterns are stored base64-encoded in hooks/pattern_registry.json so the registry file itself doesn't trip pattern-matching tools that scan the repo. This is intentional — see Design note: self-trigger safety below.

Install

bash skills/secret-warn/install.sh

The installer:

• Copies hooks/secret_warn.py to ~/.claude/secret-warn/
• Copies hooks/pattern_registry.json to the same location
• Merges PreToolUse + PostToolUse + Bash hook entries into ~/.claude/settings.json (non-destructive, additive)
• Logs every catch to ~/.claude/secret-warn/audit.log

Idempotent. Safe to re-run.

Uninstall

Edit ~/.claude/settings.json and remove any hook entry whose description starts with secret-warn:. Delete ~/.claude/secret-warn/ if you want the audit log gone too.

Bypass

For an emergency one-off where you genuinely need to bypass a catch (test fixture in a controlled environment, allowlisted-but-not-yet-configured host):

SECRET_WARN_BYPASS=1 <your-command>

The bypass is logged. Use sparingly.

Allowlist

hooks/pattern_registry.json ships with a default allowlist of placeholder values:

• your-key-here
• REPLACE_ME
• EXAMPLE
• FIXTURE
• TODO
• xxx
• ***

Any match that contains one of these markers is suppressed as a false positive. This covers AWS docs canonical samples (AKIAIOSFODNN7EXAMPLE), Stripe test fixtures with the FIXTURE marker, and similar.

To add your own placeholders, edit ~/.claude/secret-warn/pattern_registry.json after install or supply your own override via SECRET_WARN_ALLOWLIST_PATH=....

Design note: self-trigger safety

The pattern registry stores every regex as a base64-encoded string. This is because the registry will be scanned by the very tools it configures — including this hook itself, plus any other secret-detection tools running on the host. A naive registry with raw regex strings trips its own detection.

This is a real-world deployment lesson. Any production-grade secret-detection tool must solve this problem. Two common approaches: path-based exemption (the tool exempts its own config files), or encoding-at-rest (the regex catalog stores patterns in a form the tool's own detection can't match). This pack uses encoding-at-rest because it's portable across tools that don't share an exemption list.

What this skill is NOT

• Not a full security audit. It catches a curated set of common patterns at edit time.
• Not a replacement for gitleaks, semgrep, bandit, or your existing CI security stack. Layer them all.
• Not a static-analysis tool. It runs only when Claude Code makes a tool call. CI is still the right place for repo-wide scans.
• Not DLP. Doesn't watch Slack, email, or other surfaces.

Going further

This is the public substrate version. For production deployments with quarterly audit reports, per-client allowlist tuning, MCP-install audit, GitHub Actions CI integration, and ongoing retainer support, see Mycelium AI.

The public version ships the same pattern shape and the same hook architecture — Mycelium adds the operational layer: per-engagement tuning, compliance-grade reports, multi-tier install configs, and the curated rule set across nine reference tools.

Files

skills/secret-warn/
  SKILL.md                          this file
  install.sh                        one-shot installer
  hooks/
    secret_warn.py                  the actual hook
    pattern_registry.json           base64-encoded regex catalog
    hooks.json                      hook registration shape
  scripts/
    quick_test.sh                   smoke-test the install

License

MIT. Copyright (c) 2026. See LICENSE in the repo root.

Pattern shapes informed by: OWASP Top 10 (public guidelines), gitleaks (MIT, regex shape only — no code copied), bandit (Apache-2.0, study only), eslint-plugin-security (MIT, study only), Anthropic's published security-guidance plugin shape (Commercial Terms, study only). No regex or code was copied from any source. All implementation is original.