111 lines
3.7 KiB
Markdown
111 lines
3.7 KiB
Markdown
---
|
|
name: ck-privacy-guard
|
|
description: Blocks access to sensitive files and ignored directories. HARD-GATE on .env files, credentials, secrets, API keys. Also enforces .ckignore directory exclusions. Activates automatically on every file read and directory access attempt.
|
|
---
|
|
|
|
# ck-privacy-guard
|
|
|
|
Automatic guard that blocks access to sensitive files and ignored directories. Runs on every file read and bash command — never invoked manually.
|
|
|
|
## When Active
|
|
|
|
- **Privacy Block**: Fires before any file read (`Read` tool equivalent)
|
|
- **Scout Block**: Fires before any file read or directory access command
|
|
|
|
## Don't Use When
|
|
|
|
- This is a background guard — never invoke manually
|
|
- To intentionally access a sensitive file, follow the approval flow below
|
|
|
|
---
|
|
|
|
## HARD-GATE: Sensitive File Access
|
|
|
|
**Blocked file patterns** (privacy-sensitive):
|
|
- `.env`, `.env.*`, `.env.local`, `.env.production`, etc.
|
|
- `*.pem`, `*.key`, `*.p12`, `*.pfx` (certificates and private keys)
|
|
- `*credentials*`, `*secrets*`, `*token*` (credential files)
|
|
- `.npmrc`, `.pypirc` (package registry auth files)
|
|
- `id_rsa`, `id_ed25519`, `*.ssh/*` (SSH keys)
|
|
- `*.credentials.json`, `service-account*.json` (cloud credentials)
|
|
|
|
**When a sensitive file is accessed without approval:**
|
|
1. The read is BLOCKED immediately (exit code 2)
|
|
2. A structured privacy prompt is output containing JSON between `@@PRIVACY_PROMPT_START@@` and `@@PRIVACY_PROMPT_END@@`
|
|
3. The AI must parse this JSON and present an approval question to the user
|
|
|
|
**Approval flow:**
|
|
```
|
|
AI reads ".env" → BLOCKED
|
|
↓
|
|
AI asks user via interactive question:
|
|
"I need to read '.env' which may contain sensitive data. Do you approve?"
|
|
Options: [Yes, approve access] [No, skip this file]
|
|
↓
|
|
User selects "Yes, approve access"
|
|
↓
|
|
AI retries: reads the file using bash (cat ".env") — bash is auto-approved
|
|
↓
|
|
Access granted with notice logged
|
|
```
|
|
|
|
**If user selects "No, skip this file":** Continue without the file.
|
|
|
|
**Suspicious paths:** If an approved path is outside the project directory, a warning is logged but access is still allowed.
|
|
|
|
---
|
|
|
|
## Scout Block: Directory Exclusions
|
|
|
|
Blocks access to directories listed in `.claude/.ckignore`.
|
|
|
|
**Default blocked patterns** (gitignore-spec):
|
|
- `node_modules/`
|
|
- `.git/`
|
|
- `dist/`, `build/`, `.next/`
|
|
- `*.cache/`
|
|
- Any pattern listed in `.ckignore`
|
|
|
|
**Blocking rules:**
|
|
- File paths: blocks any path containing a blocked directory segment
|
|
- Bash commands: blocks directory access commands (`cd`, `ls`, `cat`) for blocked dirs
|
|
|
|
**Allowed despite blocking:**
|
|
- Build commands are always allowed: `npm build`, `go build`, `cargo build`, `make`, `mvn`, `gradle`, `docker build`, `kubectl`, `terraform`
|
|
- Python venv executables are always allowed
|
|
- Negation patterns in `.ckignore` (prefix `!`) re-allow specific paths
|
|
|
|
**Broad pattern protection:** If a pattern would block too broad a set of paths (e.g., `**` or `/`), a warning is shown with suggestions to use more specific patterns.
|
|
|
|
---
|
|
|
|
## Configuration
|
|
|
|
```json
|
|
// $HOME/.claude/.ck.json
|
|
{
|
|
"hooks": {
|
|
"privacy-block": true,
|
|
"scout-block": true
|
|
}
|
|
}
|
|
```
|
|
|
|
```
|
|
# .claude/.ckignore — one pattern per line, # for comments
|
|
node_modules/
|
|
dist/
|
|
.next/
|
|
# Allow a specific nested path despite parent being blocked
|
|
!node_modules/.bin/
|
|
```
|
|
|
|
---
|
|
|
|
## Security Properties
|
|
|
|
- **Fail-open**: Invalid JSON input or unexpected errors allow the operation to continue (never silently breaks workflow)
|
|
- **Bash bypass intentional**: Bash commands are warned but not blocked for sensitive files — this enables the "Yes → bash cat" approval flow
|
|
- **No secret logging**: Blocked file contents are never logged or included in error messages
|
|
- **Approval is session-scoped**: Approval prefix (`APPROVED:`) must be supplied explicitly each time — no persistent approval state
|