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:

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:

pip install pre-commit

Create .pre-commit-config.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:

winget install gitleaks

Configure: .gitleaks.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:

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

# 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