# Penetration Test Guidelines

## Attack Surface

JustAPI exposes the following attack surface:

| Component | Description | Port |
| --------- | ----------- | ---- |
| HTTP/HTTPS server | Main application server | 8080 (configurable) |
| WebSocket endpoint | `/ws` upgrade path | Same as HTTP |
| SSE endpoint | `/events` streaming | Same as HTTP |
| Health endpoints | `/health`, `/live`, `/ready` | Same as HTTP |
| Metrics endpoint | `/metrics` (Prometheus) | Same as HTTP |
| Static file server | Configured `static/` directory | Same as HTTP |
| OpenAPI docs | `/docs`, `/redoc` (Phase 18) | Same as HTTP |
| Database | PostgreSQL/SQLite/MySQL | 5432/3306 (external) |
| Jaeger (dev) | Distributed tracing UI | 16686 (dev only) |

## Test Scenarios

### 1. Authentication & Authorization

- **JWT forgery**: Attempt requests with malformed, expired, algorithm-confusion, and `none`-algorithm tokens
- **Missing auth**: Access protected routes without any Authorization header
- **Token replay**: Capture a valid token and replay it from a different IP
- **CORS bypass**: Send cross-origin requests with `Origin:` headers not in the allow list

### 2. Input Validation

- **JSON injection**: Send malformed JSON, deeply nested JSON (>100 levels), duplicate keys, large payloads (>10MB)
- **SQL injection**: Inject SQL into query parameters, path parameters, and request body fields (`' OR 1=1 --`, UNION-based, time-based blind)
- **NoSQL injection**: If any NoSQL paths exist, test for operator injection (`$gt`, `$ne`, `$where`)
- **Path traversal**: Send `../` sequences in URL paths and static file requests; URL-encoded variants (`%2e%2e%2f`, `..%252f`)
- **Parameter pollution**: Duplicate query parameters (`?id=1&id=2`); different types (`?id[]=1`)

### 3. Session Management

- **JWT weak secrets**: Attempt to crack the signing key with common wordlists
- **JWT claims manipulation**: Modify `sub`, `iat`, `exp`, `admin` or role claims after decoding
- **Token lifetime**: Verify expired tokens are rejected; tokens issued far in the future

### 4. Rate Limiting & DoS

- **Global rate limit**: Flood the server from a single IP to verify `RateLimiter` kicks in (429 + `Retry-After`)
- **Per-IP rate limit**: Use `IpRateLimiter` test — verify 429 after exceeding per-IP burst
- **Bulkhead saturation**: Open many concurrent connections to verify the bulkhead returns 503
- **Slow loris**: Open many connections and send data slowly (low `bytes/sec`) — verify timeout middleware triggers 504
- **Resource exhaustion**: Send requests that trigger large allocations (deep JSON, large file requests)

### 5. TLS & Network

- **Downgrade attack**: Attempt to negotiate TLS 1.1 or 1.0 (should fail – rustls supports 1.2/1.3 only)
- **Weak cipher suites**: Attempt connection with `NULL` cipher, `EXPORT` cipher, or `RC4` (should fail)
- **Certificate validation**: Present a self-signed, expired, or wrong-domain certificate (should fail)
- **Host header injection**: Send requests with manipulated `Host:` headers

### 6. Information Disclosure

- **Stack traces**: Trigger unhandled errors and verify no stack trace is leaked in responses
- **Debug endpoints**: Verify `/metrics`, health endpoints don't leak sensitive data
- **Error messages**: Verify validation errors don't reveal internal schema or implementation details
- **Server header**: Verify `Server` header is not present or is generic
- **Timing attacks**: Measure response time differences for valid vs. invalid authentication tokens

### 7. Security Headers

Verify all responses include:

```
X-Content-Type-Options: nosniff
X-Frame-Options: DENY
Strict-Transport-Security: max-age=31536000; includeSubDomains (optional: preload)
Content-Security-Policy: default-src 'self' (configurable)
X-XSS-Protection: 0
```

### 8. Fuzz Testing

Run the cargo-fuzz targets from `fuzz/`:

```bash
# Install cargo-fuzz (nightly)
rustup toolchain install nightly
cargo install cargo-fuzz

# Run fuzz targets
cargo fuzz run fuzz_jwt    -- -max_total_time=300
cargo fuzz run fuzz_headers -- -max_total_time=300
cargo fuzz run fuzz_body    -- -max_total_time=300
cargo fuzz run fuzz_router  -- -max_total_time=300
cargo fuzz run fuzz_query_params -- -max_total_time=300
cargo fuzz run fuzz_file_paths   -- -max_total_time=300
```

### 9. Supply Chain

- Verify `cargo audit` passes with zero advisories
- Verify `cargo deny check` passes with zero violations
- Verify Dependabot is configured for weekly updates
- Review `deny.toml` for license allowlist accuracy
- Verify lockfile is committed and up-to-date

## Tools

| Tool | Purpose | Command |
| ---- | ------- | ------- |
| `cargo fuzz` | Rust fuzzing | `cargo fuzz run <target>` |
| `cargo audit` | Vulnerability scanning | `cargo audit` |
| `cargo deny` | License/advisory checks | `cargo deny check` |
| `curl` | Manual request testing | `curl -v http://localhost:8080/` |
| `oha` | Load testing | `oha -z 10s http://localhost:8080/` |
| `nmap` | Port/service discovery | `nmap -sV localhost` |
| `testssl.sh` | TLS configuration test | `testssl.sh https://localhost:8080/` |
| `jwt_tool` | JWT attack toolkit | `python3 jwt_tool.py <token>` |
| `sqlmap` | SQL injection detection | `sqlmap -u "http://localhost:8080/endpoint"` |
| `nikto` | Web server scanner | `nikto -h http://localhost:8080/` |

## Scoring

Use CVSS 3.1 for severity scoring. Report template:

```
# Vulnerability Report

**Title**: <brief description>
**Severity**: CVSS 3.1 <score> (<Critical/High/Medium/Low>)
**Endpoint**: <method> <path>
**Type**: <OWASP category>

## Description

## Steps to Reproduce

## Impact

## Recommended Fix

## References
```

---

_Last updated: 2026-07-05_