add comprehensive penetration testing plan

Define 8 specialized subagents for security testing: - AuthBypass, InputFuzz, CryptoAudit, RaceCondition - DoSResilience, InfoLeak, CLISecurity, DependencyAudit Document critical vulnerabilities and remediation priorities.
2025-12-24 21:32:19 +01:00
parent 4e06a3befb
commit bebc6e0354
1 changed files with 398 additions and 0 deletions
--- a/PENTEST_PLAN.md
+++ b/PENTEST_PLAN.md
@@ -0,0 +1,398 @@
+# FlaskPaste Penetration Testing Plan
+
+Comprehensive security assessment for the FlaskPaste web application and fpaste CLI tool.
+
+---
+
+## Executive Summary
+
+This plan defines a structured penetration testing methodology targeting:
+- **FlaskPaste API** - 22 REST endpoints with authentication, PKI, and abuse prevention
+- **fpaste CLI** - Standalone client with encryption, mTLS, and certificate management
+
+Testing uses specialized Claude subagents for different security domains, with findings tracked incrementally for remediation.
+
+---
+
+## Attack Surface Overview
+
+```
+┌─────────────────────────────────────────────────────────────────────────────┐
+│ FLASKPASTE ATTACK SURFACE
+├─────────────────────────────────────────────────────────────────────────────┤
+│ Web Application (app/api/routes.py)
+│   ├─ Public endpoints (10): /, /health, /challenge, POST /, /<id>, etc.
+│   ├─ Authenticated endpoints (6): /pastes, PUT/DELETE /<id>, /pki/*
+│   ├─ PKI endpoints (4): /pki, /pki/ca, /pki/issue, /pki/revoke
+│   └─ Admin endpoints (2): /pastes?all=1, /audit
+│
+│ CLI Tool (fpaste)
+│   ├─ Network operations: HTTP requests, mTLS, SSL context
+│   ├─ Cryptography: AES-256-GCM encryption, key derivation
+│   ├─ File operations: Config files, certificate storage
+│   ├─ Subprocess calls: Clipboard integration
+│   └─ Certificate generation: RSA/EC key generation
+│
+│ Supporting Systems
+│   ├─ SQLite database (pastes, certificates, audit logs)
+│   ├─ Reverse proxy integration (header-based auth)
+│   └─ External dependencies (Flask, cryptography, etc.)
+└─────────────────────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## Specialized Subagents
+
+### 1. AuthBypass Agent
+**Purpose:** Test authentication and authorization vulnerabilities
+**Scope:**
+- X-SSL-Client-SHA1 header spoofing
+- X-Proxy-Secret bypass when unconfigured
+- X-Forwarded-For chain manipulation
+- Certificate fingerprint forgery
+- Trust level escalation (anon → untrusted → trusted → admin)
+- Session/token replay attacks
+
+### 2. InputFuzz Agent
+**Purpose:** Fuzz all input vectors for injection and validation bypass
+**Scope:**
+- Paste ID format bypass (regex evasion)
+- MIME type confusion attacks
+- Content-Type header injection
+- JSON payload malformation
+- Header value overflow/truncation
+- Unicode normalization attacks
+- Path traversal attempts
+
+### 3. CryptoAudit Agent
+**Purpose:** Analyze cryptographic implementations
+**Scope:**
+- PoW algorithm weakness analysis
+- Token signature verification timing
+- PBKDF2 parameter validation
+- AES-GCM nonce reuse detection
+- Key derivation entropy analysis
+- PKI certificate chain validation
+- Private key protection assessment
+
+### 4. RaceCondition Agent
+**Purpose:** Identify and exploit race conditions
+**Scope:**
+- Burn-after-read concurrent access
+- Content hash deduplication races
+- Rate limit window manipulation
+- Anti-flood difficulty calculation races
+- Certificate issuance/revocation timing
+
+### 5. DoSResilience Agent
+**Purpose:** Test denial-of-service resistance
+**Scope:**
+- Memory exhaustion via rate limit storage
+- Anti-flood memory growth
+- Large paste upload handling
+- PoW difficulty manipulation
+- Cleanup function starvation
+- Connection pool exhaustion
+
+### 6. InfoLeak Agent
+**Purpose:** Discover information disclosure vulnerabilities
+**Scope:**
+- Error message verbosity
+- Paste existence enumeration
+- Timing attacks on lookups
+- Debug information exposure
+- Version/endpoint disclosure
+- Audit log data leakage
+
+### 7. CLISecurity Agent
+**Purpose:** Audit the fpaste CLI tool
+**Scope:**
+- Command injection via clipboard tools
+- Config file permission issues
+- Certificate/key file exposure
+- SSL context validation bypass
+- URL parsing vulnerabilities
+- Subprocess execution safety
+
+### 8. DependencyAudit Agent
+**Purpose:** Analyze third-party dependencies
+**Scope:**
+- Known CVE scanning
+- Outdated package detection
+- Transitive dependency risks
+- Optional dependency failures
+- Import error handling
+
+---
+
+## Testing Phases
+
+### Phase 1: Reconnaissance & Configuration
+
+| # | Task | Agent | Priority |
+|---|------|-------|----------|
+| 1.1 | Map all API endpoints and parameters | InfoLeak | High |
+| 1.2 | Identify authentication requirements per endpoint | AuthBypass | High |
+| 1.3 | Document default configuration weaknesses | InfoLeak | High |
+| 1.4 | Enumerate error message patterns | InfoLeak | Medium |
+| 1.5 | Profile response timing baselines | RaceCondition | Medium |
+
+### Phase 2: Authentication & Authorization
+
+| # | Task | Agent | Priority |
+|---|------|-------|----------|
+| 2.1 | Test X-SSL-Client-SHA1 spoofing without proxy secret | AuthBypass | Critical |
+| 2.2 | Verify X-Proxy-Secret HMAC timing resistance | CryptoAudit | High |
+| 2.3 | Attempt trust level escalation | AuthBypass | High |
+| 2.4 | Test admin endpoint access controls | AuthBypass | High |
+| 2.5 | Verify certificate revocation enforcement | AuthBypass | Medium |
+| 2.6 | Test X-Forwarded-For chain bypass | AuthBypass | Medium |
+
+### Phase 3: Input Validation
+
+| # | Task | Agent | Priority |
+|---|------|-------|----------|
+| 3.1 | Fuzz paste ID format validation | InputFuzz | High |
+| 3.2 | Test MIME type detection bypass | InputFuzz | Medium |
+| 3.3 | Attempt entropy check evasion | InputFuzz | Medium |
+| 3.4 | Test Content-Type header injection | InputFuzz | Medium |
+| 3.5 | Verify size limit enforcement | InputFuzz | Low |
+| 3.6 | Test JSON payload edge cases | InputFuzz | Low |
+
+### Phase 4: Cryptographic Security
+
+| # | Task | Agent | Priority |
+|---|------|-------|----------|
+| 4.1 | Analyze PoW token structure and replay potential | CryptoAudit | High |
+| 4.2 | Verify PBKDF2 iteration count (600k) | CryptoAudit | Low |
+| 4.3 | Test password hash timing attacks | CryptoAudit | Medium |
+| 4.4 | Audit AES-GCM implementation in CLI | CryptoAudit | Medium |
+| 4.5 | Verify PKI private key encryption | CryptoAudit | High |
+| 4.6 | Test certificate serial collision | CryptoAudit | Low |
+
+### Phase 5: Race Conditions & Logic Flaws
+
+| # | Task | Agent | Priority |
+|---|------|-------|----------|
+| 5.1 | Exploit burn-after-read via HEAD then GET | RaceCondition | High |
+| 5.2 | Race content hash deduplication counter | RaceCondition | Medium |
+| 5.3 | Manipulate rate limit sliding window | RaceCondition | Medium |
+| 5.4 | Test anti-flood difficulty race | RaceCondition | Low |
+| 5.5 | Concurrent paste update/delete | RaceCondition | Low |
+
+### Phase 6: Denial of Service
+
+| # | Task | Agent | Priority |
+|---|------|-------|----------|
+| 6.1 | Memory exhaustion via unique IP rate limits | DoSResilience | High |
+| 6.2 | Anti-flood list growth under load | DoSResilience | Medium |
+| 6.3 | PoW difficulty prediction for timed attacks | DoSResilience | Medium |
+| 6.4 | Cleanup function starvation | DoSResilience | Low |
+| 6.5 | Large paste memory consumption | DoSResilience | Low |
+
+### Phase 7: CLI Tool Security
+
+| # | Task | Agent | Priority |
+|---|------|-------|----------|
+| 7.1 | Test clipboard command injection | CLISecurity | High |
+| 7.2 | Verify config file permissions | CLISecurity | Medium |
+| 7.3 | Test certificate file exposure | CLISecurity | Medium |
+| 7.4 | Audit SSL context configuration | CLISecurity | Medium |
+| 7.5 | Test URL parsing edge cases | CLISecurity | Low |
+| 7.6 | Verify subprocess safety | CLISecurity | Medium |
+
+### Phase 8: Dependency & Supply Chain
+
+| # | Task | Agent | Priority |
+|---|------|-------|----------|
+| 8.1 | Run pip-audit for known CVEs | DependencyAudit | High |
+| 8.2 | Check for outdated packages | DependencyAudit | Medium |
+| 8.3 | Audit optional dependency handling | DependencyAudit | Low |
+| 8.4 | Review Containerfile for supply chain risks | DependencyAudit | Medium |
+
+---
+
+## Critical Vulnerabilities Identified
+
+```
+┌───┬─────────────────────────────────────┬──────────┬───────────────────────┐
+│ # │ Vulnerability                       │ Severity │ Remediation
+├───┼─────────────────────────────────────┼──────────┼───────────────────────┤
+│ 1 │ Missing TRUSTED_PROXY_SECRET        │ Critical │ Require in production
+│   │ allows auth header spoofing         │          │ or fail closed
+│ 2 │ HEAD request bypasses burn-after-   │ Medium   │ Track HEAD as access
+│   │ read deletion                       │          │ or disable for burn
+│ 3 │ Rate limit memory unbounded         │ Medium   │ Add max entries limit
+│ 4 │ Content hash race condition         │ Low      │ Add locking
+│ 5 │ Clipboard command injection         │ Medium   │ Sanitize tool paths
+│   │ potential in CLI                    │          │
+└───┴─────────────────────────────────────┴──────────┴───────────────────────┘
+```
+
+---
+
+## Remediation Task List
+
+### Immediate (Critical)
+
+- [ ] **PROXY-001**: Add startup warning/failure when TRUSTED_PROXY_SECRET empty in production
+- [ ] **PROXY-002**: Document required proxy configuration in deployment guide
+- [ ] **PROXY-003**: Add security test for header spoofing without proxy secret
+
+### Short-term (High)
+
+- [ ] **BURN-001**: Track HEAD requests as paste access for burn-after-read
+- [ ] **BURN-002**: Add test for HEAD-then-GET race condition
+- [ ] **RATE-001**: Add maximum entries limit to rate limit storage
+- [ ] **RATE-002**: Add automatic cleanup trigger when threshold exceeded
+- [ ] **CLI-001**: Validate clipboard tool paths against allow-list
+
+### Medium-term (Medium)
+
+- [ ] **HASH-001**: Add locking to content hash deduplication
+- [ ] **FLOOD-001**: Add memory limit to anti-flood request list
+- [ ] **ENUM-001**: Add rate limiting to paste metadata endpoints
+- [ ] **CLI-002**: Verify SSL certificate hostname matching
+- [ ] **CLI-003**: Add config file permission validation on startup
+
+### Long-term (Low)
+
+- [ ] **CRYPTO-001**: Add certificate serial collision detection
+- [ ] **TIMING-001**: Add constant-time database lookups for sensitive queries
+- [ ] **AUDIT-001**: Add query result limits to prevent enumeration
+
+---
+
+## Test Execution Commands
+
+### Setup Test Environment
+
+```bash
+# Create isolated test environment
+python3 -m venv pentest-venv
+source pentest-venv/bin/activate
+pip install -r requirements.txt
+pip install pytest pytest-cov httpx hypothesis
+
+# Start test server
+FLASK_ENV=testing python run.py &
+```
+
+### Run Security Tests
+
+```bash
+# Authentication bypass tests
+./venv/bin/pytest tests/test_security.py -v -k "proxy"
+
+# Rate limiting tests
+./venv/bin/pytest tests/test_rate_limiting.py -v
+
+# PoW tests
+./venv/bin/pytest tests/test_pow.py -v
+
+# Full security suite
+./venv/bin/pytest tests/ -v --tb=short -x
+```
+
+### Manual Testing
+
+```bash
+# Test header spoofing without proxy secret
+curl -H "X-SSL-Client-SHA1: $(printf '0%.0s' {1..40})" \
+     http://localhost:5000/pastes
+
+# Test burn-after-read via HEAD
+paste_id=$(echo "secret" | curl -sS -X POST -d @- http://localhost:5000/ \
+           -H "X-Burn-After-Read: true" | jq -r .id)
+curl -I http://localhost:5000/$paste_id/raw  # HEAD request
+curl http://localhost:5000/$paste_id/raw     # Should still exist?
+
+# Test rate limit memory growth
+for i in {1..10000}; do
+  curl -H "X-Forwarded-For: 192.168.$((i/256)).$((i%256))" \
+       -X POST -d "test" http://localhost:5000/ 2>/dev/null &
+done
+```
+
+---
+
+## Test File Structure
+
+```
+tests/
+├── security/
+│   ├── test_auth_bypass.py      # AuthBypass agent tests
+│   ├── test_input_fuzz.py       # InputFuzz agent tests
+│   ├── test_crypto_audit.py     # CryptoAudit agent tests
+│   ├── test_race_conditions.py  # RaceCondition agent tests
+│   ├── test_dos_resilience.py   # DoSResilience agent tests
+│   ├── test_info_leak.py        # InfoLeak agent tests
+│   └── test_cli_security.py     # CLISecurity agent tests
+├── conftest.py                  # Shared fixtures
+└── test_abuse_prevention.py     # Existing abuse tests
+```
+
+---
+
+## Reporting
+
+### Finding Template
+
+```markdown
+## [SEVERITY] Finding Title
+
+**ID:** CATEGORY-NNN
+**Severity:** Critical | High | Medium | Low | Info
+**CVSS:** X.X (if applicable)
+**CWE:** CWE-XXX
+
+### Description
+[Detailed description of the vulnerability]
+
+### Reproduction Steps
+1. Step one
+2. Step two
+3. ...
+
+### Impact
+[Business and technical impact]
+
+### Remediation
+[Specific fix recommendations]
+
+### References
+- [Link to relevant documentation]
+```
+
+### Summary Report Sections
+
+1. Executive Summary
+2. Scope and Methodology
+3. Findings by Severity
+4. Risk Assessment Matrix
+5. Remediation Roadmap
+6. Appendix: Raw Test Results
+
+---
+
+## Schedule
+
+```
+Week 1: Phases 1-2 (Recon, Auth)
+Week 2: Phases 3-4 (Input, Crypto)
+Week 3: Phases 5-6 (Race, DoS)
+Week 4: Phases 7-8 (CLI, Deps)
+Week 5: Reporting and Remediation
+```
+
+---
+
+## Success Criteria
+
+- [ ] All Critical findings remediated
+- [ ] All High findings remediated or risk-accepted
+- [ ] Medium findings tracked in issue tracker
+- [ ] Security test coverage > 80%
+- [ ] CI pipeline includes security regression tests
+- [ ] Documentation updated with security guidance