Overview, Scope & Deployment
Positioning & Boundaries
Claude Code Antileak Hooks is a two-layer leakage-prevention guardrail combining offline PreToolUse shell wrappers with mandatory Git hooks, both delegating to a single Python policy engine (policy/check.py):
- In scope: Offline pre-execution blocking of writes (
Write/Edit/NotebookEdit), sensitive file reads (Read/GrepandBash), bypass flags (--no-verify,--no-gpg-sign,core.hooksPathedits), and agent branch pushes (claude/...,codex/..., etc.); plus online (--net) Git verification atpre-commit,pre-merge-commit,commit-msg, andpre-pushcovering private repository names (R1), model/session markers (R2), non-provider authorship andCo-authored-by:trailers (R3), private regexes (R4), agent branch push blocking (R5), non-generic SSH commit signatures (R6), and masked secret regexes (R7). - Out of scope: Does not enforce protected branch or force-push rules (delegated to hosting platform rulesets); does not hook
Glob(which returns paths rather than file contents); advisory shell checks cannot stop a privileged local user who bypasses hooks, so the Git pre-push gate and remote branch protections remain the strong enforcement boundary. - Product hooks vs. repo maintenance guard:
hooks/,hooks/git/, andpolicy/form the installable product package, whereastools/repo_maintenance_guard.pyandtools/repo_maintenance_hooks/are offline maintenance hooks solely for committing to this repository clone. - Interactive API & Component Reference: Inspect per-hook parameters,
check.pyexit codes, and CLI examples in API & Component Reference.
Prerequisites
| Requirement | Purpose | Failure Behavior |
|---|---|---|
python3 | Runs check.py, refresh-private.py, resolve-private.py, and installers | bootstrap.sh exits 1 |
git | Extracts staged + lines, runs ls-remote, inspects commit objects | bootstrap.sh exits 1 |
curl, unzip / tar | Fetches and unpacks zip/tgz release archive | bootstrap.sh exits 1 |
openssh-client (ssh-keygen) | Computes signing key fingerprints and runs ssh-keygen -Y check-novalidate for R6 | bootstrap.sh attempts apt-get; missing binary triggers fail-closed denial |
All entry wrappers export PYTHONUTF8=1 and Python scripts explicitly open files and streams with UTF-8 to avoid silent fallbacks on Chinese Windows / GBK locales.
Deployment Modes
Source files intentionally contain template paths (/root/.claude/...) and cannot be wired directly from a git clone without path rewriting via policy/bootstrap.sh.
Mode A: Local CLI Install & Idempotent Upgrade
# 1. Install or upgrade into $GUARD (default $HOME/.claude/guardrails) while preserving seeds/caches
HOOK_PACKAGE_URL=file:///path/to/guardrails-package.zip bash policy/bootstrap.sh
# 2. Place local-only private seed & history sanitize map (never shipped in packages)
cp private-seed.json sanitize-map.json "$HOME/.claude/guardrails/"
chmod 600 "$HOME/.claude/guardrails/private-seed.json" "$HOME/.claude/guardrails/sanitize-map.json"
# 3. Refresh dynamic private repo cache and run read-only diagnostics
python3 "$HOME/.claude/guardrails/hooks/refresh-private.py"
python3 "$HOME/.claude/guardrails/policy/doctor.py"What bootstrap.sh executes in order:
- Backs up existing
private-seed.json,sanitize-map.json,private-repos.json, and.resolve.jsonbefore replacinghooks/andpolicy/, then restores them. - Uses
sedto rewrite template/root/.claude/...paths acrosspolicy/*,hooks/*.sh,hooks/*.py, andhooks/git/*to$GUARD/...and$HOME/.claude/settings.json. - Sets global
git config --global core.hooksPath "$GUARD/hooks/git". - Calls
policy/install-settings.pyto idempotently merge 6PreToolUsehooks, 1SessionStarthook, andattribution.sessionUrl=falseinto<repo>/.claude/settings.json(plus colon-separatedGUARD_REPOS, adding untracked files to.git/info/excludevia--exclude-untracked) and~/.claude/settings.json.
Mode B: Cloud / Container Environment Setup Script
- Paste
policy/bootstrap.shinto your cloud Setup Script and replacePKG_URL_DEFAULTwith your release archive URL. - Configure environment variables:
GUARD_SEED_B64(orGUARD_SEED_JSON), the primary hosting platform read-only token (matchingpolicy/policy.json), and optionalGH_TOKEN_1..N(if private repositories also reside on GitHub). Allowlist the package CDN domain, primary hosting API, andapi.github.com. - Cloud sessions read repository-level
.claude/settings.jsonrather than~/.claude/settings.json. Note that if a cloud Git proxy only permits pushing toclaude/...branches, R5 intentionally blocks all cloud pushes by design.
Mode C: token-helper Local Credential Wrapper (Optional)
To avoid plaintext token files on disk, fill token slots in a private copy of policy/token-helper.cpp, inject GUARD_PKG_URL during build (never hardcode release URLs into tracked files), generate XOR-obfuscated C++ via policy/build-secure-token.py, and compile an executable readable only by the user (chmod 700). Note that XOR stream obfuscation mitigates automated text scraping and does not replace OS keyrings or HSMs.
Mode D: This Repository's Maintenance Guard (Contributors Only)
python tools/repo_maintenance_guard.py install
python tools/repo_maintenance_guard.py statusSets local .git/config core.hooksPath to tools/repo_maintenance_hooks and commit.template to .gitmessage.txt (requires Python 3.10+).
Read-Only Health Check (doctor.py)
python3 "$HOME/.claude/guardrails/policy/doctor.py"Checks policy.json integrity, Claude hooks (no permissionDecision: allow), global/local core.hooksPath, --net isolation, cache freshness (6h TTL), private seed presence, and SSH signing config. Exits 0 (Overall: PASS) only when zero [FAIL] checks occur; otherwise exits 1 (Overall: DEGRADED). Next: Config Matrix, Seeds & Troubleshooting FAQ.