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