Reorganize repository structure and clean up documentation

Clean up and organize the flask-shopdb repository for better maintainability and discoverability: ## Changes - Update .gitignore for build artifacts (publish/, data/, 122M total) - Reorganize .claude/ into 6 subdirectories with README navigation - Consolidate overlapping MCP setup guides into MCP-QUICK-START.md - Move deployment docs from root to docs/deployment/ - Archive dated status reports to .claude/archived/ - Delete temporary files (logs, backups, empty reports, ~50K) ## New Structure .claude/ organized into: - setup/ - MCP, VM, Hyper-V, GitHub setup guides + scripts (17 files) - plans/ - Feature plans and protocols (5 files) - maintenance/ - Deployment checklists and reports (4 files) - archived/ - Historical documentation (9 files) - skills/ - Claude Code automation (5 files) - workflows/ - Security audit workflow (1 file) docs/deployment/ created with 6 deployment guides: - LOCAL-DEV-SETUP.md, DOCKER-SETUP.md, DOCKER-PREBUILT-APPROACH.md - PRODUCTION-READINESS.md, DEPLOY-TO-VM.md, README.md Root directory cleaned to essential docs only: - CLAUDE.md, README.md, CONTRIBUTING.md, CHANGELOG.md Benefits: - Clear navigation via README.md in each subdirectory - No duplicate/overlapping documentation - Large artifacts properly gitignored (won't bloat repository) - Historical context preserved in archived/ See .claude/CLEANUP-SUMMARY.md for complete details. Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
2026-09-11 15:45:05 -04:00
parent 0b252db7d2
commit bd48814021
57 changed files with 11978 additions and 29 deletions
--- a/.claude/plans/security-improvements.md
+++ b/.claude/plans/security-improvements.md
@@ -0,0 +1,194 @@
+# 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