flaskpaste/PENTEST_PLAN.md

# 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

**MIME Detection Abuse (Priority Target):**
- Magic byte spoofing (embed malicious payload after valid magic bytes)
- Polyglot files (valid in multiple formats simultaneously)
- Truncated magic bytes (test boundary conditions)
- Content-Type vs magic byte mismatch exploitation
- MIME type injection via crafted binary patterns
- Test if MIME type affects server-side processing/execution
- Attempt to trigger unsafe file operations via MIME confusion
- Chain MIME detection with other features (burn-after-read, encryption)

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

- [x] **PROXY-001**: Add startup warning/failure when TRUSTED_PROXY_SECRET empty in production
- [x] **PROXY-002**: Document required proxy configuration in deployment guide
- [x] **PROXY-003**: Add security test for header spoofing without proxy secret

### Short-term (High)

- [x] **BURN-001**: Track HEAD requests as paste access for burn-after-read
- [x] **BURN-002**: Add test for HEAD-then-GET race condition
- [x] **RATE-001**: Add maximum entries limit to rate limit storage
- [x] **RATE-002**: Add automatic cleanup trigger when threshold exceeded
- [x] **CLI-001**: Validate clipboard tool paths against allow-list

### Medium-term (Medium)

- [x] **HASH-001**: Add locking to content hash deduplication
- [x] **FLOOD-001**: Add memory limit to anti-flood request list
- [x] **ENUM-001**: Add rate limiting to paste metadata endpoints
- [x] **CLI-002**: Verify SSL certificate hostname matching
- [x] **CLI-003**: Add config file permission validation on startup
- [x] **AUDIT-001**: Add query result limits to prevent enumeration

### Long-term (Low)

- [x] **CRYPTO-001**: Add certificate serial collision detection
- [x] **TIMING-001**: Add constant-time database lookups for sensitive queries

---

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