shopdb-flask/.claude/plans/security-improvements.md

# ShopDB Security Improvements

## Priority 1: Enable GitHub Secret Scanning

**Status:** Currently disabled

**How to enable:**
1. Go to: https://github.com/ge-aero/shopdb-flask/settings/security_analysis
2. Enable "Secret scanning"
3. Enable "Push protection" (blocks pushes with secrets)

**What it catches:**
- GitHub tokens (ghp_, gho_, etc.)
- AWS keys
- API keys from 200+ services
- Private keys

**Why:** Would have caught the token pasted in Claude conversation.

---

## Priority 2: Install Pre-Commit Hook

**Current state:** `scripts/check-naming-and-style.sh` exists but not installed as git hook.

**Install:**
```bash
cd C:\Users\270015376\Documents\github\flask-shopdb
ln -s ../../scripts/check-naming-and-style.sh .git/hooks/pre-commit
chmod +x .git/hooks/pre-commit
```

**Or use pre-commit framework:**
```bash
pip install pre-commit
```

Create `.pre-commit-config.yaml`:
```yaml
repos:
  - repo: local
    hooks:
      - id: naming-and-style
        name: Check naming and style
        entry: scripts/check-naming-and-style.sh
        language: system
        pass_filenames: false
        
      - id: gitleaks
        name: Detect secrets
        entry: gitleaks
        args: ['protect', '--verbose', '--redact', '--staged']
        language: system
        pass_filenames: false
```

**Install:** `pre-commit install`

---

## Priority 3: Add gitleaks for Secret Detection

**Install:**
```bash
winget install gitleaks
```

**Configure:** `.gitleaks.toml`
```toml
title = "ShopDB gitleaks config"

[allowlist]
description = "Known safe patterns"
paths = [
    # Example tokens in docs
    '''docs/.*\.md''',
    '''README\.md''',
]

# Custom rules for ShopDB
[[rules]]
id = "shopdb-collector-token"
description = "ShopDB collector token"
regex = '''[0-9a-f]{64}'''
path = '''plugins/endpoints/'''

[[rules]]
id = "github-token"
description = "GitHub Personal Access Token"
regex = '''ghp_[0-9a-zA-Z]{36}'''

[[rules]]
id = "mysql-connection"
description = "MySQL connection string with password"
regex = '''mysql://[^:]+:([^@\s]+)@'''
```

**Run manually:** `gitleaks detect --verbose`
**Run on commit:** (via pre-commit hook above)

---

## Priority 4: Rotate Exposed Token

**Action:** The token `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` was exposed in Claude conversation.

**Steps:**
1. Revoke: https://github.com/settings/tokens
2. Generate new token with same scopes (repo, workflow, read:org)
3. Update environment variable: `setx GITHUB_PERSONAL_ACCESS_TOKEN "NEW_TOKEN"`
4. Restart Claude Code

---

## Priority 5: Add Security Policy

Create `SECURITY.md`:
```markdown
# Security Policy

## Reporting a Vulnerability

Contact: [internal security team email]

## What NOT to commit:

- `.env` files with real credentials
- Database dumps with real data
- API tokens, GitHub tokens, SSH keys
- Collector tokens (generate per-site)
- Site-specific hostnames, IPs (use settings)

## Pre-commit checklist:

1. Run `scripts/check-naming-and-style.sh`
2. Run `gitleaks detect`
3. Check no secrets in diff: `git diff --cached`
4. Verify .gitignore caught sensitive files

## GitHub scanning:

- Secret scanning: Enabled (blocks pushes with secrets)
- Darkwing: Runs on all PRs
- Dependency scanning: Enabled (Dependabot alerts)
```

---

## What's Already Good:

✅ Strong .gitignore (lines 64-86 cover most credential patterns)
✅ Darkwing scanning on PRs
✅ Air-gapped deployment (secrets never in GitHub)
✅ ADR-016: Device tokens instead of user credentials for kiosks
✅ Collector tokens are 64-char hashes, not readable passwords

---

## Implementation Order:

1. **Today:** Enable GitHub secret scanning + push protection (5 min)
2. **Today:** Rotate the exposed GitHub token (3 min)
3. **This week:** Install gitleaks and pre-commit hook (30 min)
4. **This week:** Add SECURITY.md (15 min)
5. **Next sprint:** Train team on new workflow

---

## Testing the Setup:

```bash
# Test 1: Try to commit a fake token
echo "ghp_FAKE1234567890123456789012345678" > test-secret.txt
git add test-secret.txt
git commit -m "test"
# Expected: Pre-commit hook blocks it

# Test 2: Try to push a secret (if pre-commit bypassed)
git push
# Expected: GitHub push protection blocks it

# Test 3: Scan existing history
gitleaks detect --verbose
# Expected: No secrets found (or only known safe ones)
```

---

## Monitoring:

- GitHub Security tab: https://github.com/ge-aero/shopdb-flask/security
- Secret scanning alerts: (once enabled)
- Darkwing findings: Security → Code scanning
- Dependabot alerts: Security → Dependabot