timmy-home/README.md

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:

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

# 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)

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:

# 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:

# 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

# 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 for contribution guidelines.

License

This project is part of the Timmy Foundation.