security: add pre-commit hook for secret leak detection (#384)

2026-04-05 00:27:00 +00:00
parent d5c357df76
commit 5ace1e69ce
4 changed files with 603 additions and 0 deletions
--- a/README.md
+++ b/README.md
@@ -0,0 +1,132 @@
+# Timmy Home
+
+Timmy Foundation's home repository for development operations and configurations.
+
+## Security
+
+### Pre-commit Hook for Secret Detection
+
+This repository includes a pre-commit hook that automatically scans for secrets (API keys, tokens, passwords) before allowing commits.
+
+#### Setup
+
+Install pre-commit hooks:
+
+```bash
+pip install pre-commit
+pre-commit install
+```
+
+#### What Gets Scanned
+
+The hook detects:
+- **API Keys**: OpenAI (`sk-*`), Anthropic (`sk-ant-*`), AWS, Stripe
+- **Private Keys**: RSA, DSA, EC, OpenSSH private keys
+- **Tokens**: GitHub (`ghp_*`), Gitea, Slack, Telegram, JWT, Bearer tokens
+- **Database URLs**: Connection strings with embedded credentials
+- **Passwords**: Hardcoded passwords in configuration files
+
+#### How It Works
+
+Before each commit, the hook:
+1. Scans all staged text files
+2. Checks against patterns for common secret formats
+3. Reports any potential secrets found
+4. Blocks the commit if secrets are detected
+
+#### Handling False Positives
+
+If the hook flags something that is not actually a secret (e.g., test fixtures, placeholder values), you can:
+
+**Option 1: Add an exclusion marker to the line**
+
+```python
+# Add one of these markers to the end of the line:
+api_key = "sk-test123"  # pragma: allowlist secret
+api_key = "sk-test123"  # noqa: secret
+api_key = "sk-test123"  # secret-detection:ignore
+```
+
+**Option 2: Use placeholder values (auto-excluded)**
+
+These patterns are automatically excluded:
+- `changeme`, `password`, `123456`, `admin` (common defaults)
+- Values containing `fake_`, `test_`, `dummy_`, `example_`, `placeholder_`
+- URLs with `localhost` or `127.0.0.1`
+
+**Option 3: Skip the hook (emergency only)**
+
+```bash
+git commit --no-verify  # Bypasses all pre-commit hooks
+```
+
+⚠️ **Warning**: Only use `--no-verify` if you are certain no real secrets are being committed.
+
+#### CI/CD Integration
+
+The secret detection script can also be run in CI/CD:
+
+```bash
+# Scan specific files
+python3 scripts/detect_secrets.py file1.py file2.yaml
+
+# Scan with verbose output
+python3 scripts/detect_secrets.py --verbose src/
+
+# Run tests
+python3 tests/test_secret_detection.py
+```
+
+#### Excluded Files
+
+The following are automatically excluded from scanning:
+- Markdown files (`.md`)
+- Lock files (`package-lock.json`, `poetry.lock`, `yarn.lock`)
+- Image and font files
+- `node_modules/`, `__pycache__/`, `.git/`
+
+#### Testing the Detection
+
+To verify the detection works:
+
+```bash
+# Run the test suite
+python3 tests/test_secret_detection.py
+
+# Test with a specific file
+echo "API_KEY=sk-test123456789" > /tmp/test_secret.py
+python3 scripts/detect_secrets.py /tmp/test_secret.py
+# Should report: OpenAI API key detected
+```
+
+## Development
+
+### Running Tests
+
+```bash
+# Run secret detection tests
+python3 tests/test_secret_detection.py
+
+# Run all tests
+pytest tests/
+```
+
+### Project Structure
+
+```
+.
+├── .pre-commit-hooks.yaml    # Pre-commit configuration
+├── scripts/
+│   └── detect_secrets.py     # Secret detection script
+├── tests/
+│   └── test_secret_detection.py  # Test cases
+└── README.md                 # This file
+```
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for contribution guidelines.
+
+## License
+
+This project is part of the Timmy Foundation.