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

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
• AUDIT-001: Add query result limits to prevent enumeration

Long-term (Low)

• CRYPTO-001: Add certificate serial collision detection
• TIMING-001: Add constant-time database lookups for sensitive queries

---

Test Execution Commands

Setup Test Environment

# 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

# 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

# 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

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