Skip to content

Commit 9093c1f

Browse files
atomiczsecatomiczsec
authored
Merge pull request #19 from atomiczsec/claude/add-claude-documentation-pjbCc
2 parents 0397ea6 + a1ae43b commit 9093c1f

1 file changed

Lines changed: 224 additions & 0 deletions

File tree

‎CLAUDE.md‎

Lines changed: 224 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,224 @@
1+
# CLAUDE.md — Web Cache Deception Scanner
2+
3+
A guide for AI assistants working in this repository.
4+
5+
## Project Overview
6+
7+
This is a **Burp Suite extension** (BApp) that automatically detects Web Cache Deception vulnerabilities. It integrates with Burp Suite's scanning pipeline, adds a right-click context menu, and reports findings as standard Burp `IScanIssue` entries.
8+
9+
Language: **Java 11+**. Build system: **Gradle**. No test framework — validation is done manually inside Burp Suite.
10+
11+
---
12+
13+
## Repository Structure
14+
15+
```
16+
Web-Cache-Scanner/
17+
├── src/main/java/burp/
18+
│ ├── BurpExtender.java # Extension entry point + orchestration (~750 lines)
19+
│ ├── RequestSender.java # Core testing engine + response analysis (~1579 lines)
20+
│ ├── WebCacheIssue.java # IScanIssue implementation for reporting (~120 lines)
21+
│ └── PerformanceConfig.java # Adaptive performance tuning system (~310 lines)
22+
├── .github/workflows/
23+
│ └── build.yml # CI: builds JAR, versions, creates GitHub releases
24+
├── build.gradle # Gradle build + fatJar configuration
25+
├── settings.gradle
26+
├── BappManifest.bmf # Burp extension metadata (UUID, version, entry point)
27+
├── BappDescription.html # Marketplace description
28+
├── README.md # Installation and usage guide
29+
└── gradle/wrapper/ # Gradle wrapper (do not modify)
30+
```
31+
32+
---
33+
34+
## Core Modules
35+
36+
### `BurpExtender.java`
37+
The main extension class. Implements `IBurpExtender`, `IContextMenuFactory`, and `IExtensionStateListener`.
38+
39+
Key responsibilities:
40+
- Registers the extension with Burp callbacks on `registerExtenderCallbacks()`
41+
- Creates a thread pool sized by `PerformanceConfig`
42+
- Adds a context menu item ("Web Cache Deception Test") for manual scans
43+
- Runs scanning in `ScannerThread` (inner class) with a **prioritized test sequence**:
44+
1. **Prerequisite check** — confirms the endpoint requires auth and accepts path manipulation
45+
2. **High-priority tests** (run first; skip remaining tests if high-severity found):
46+
- Self-referential normalization
47+
- Reverse traversal
48+
- Hash-based traversal
49+
3. **Medium-priority tests** (skipped if high-severity already found):
50+
- Delimiter + extension caching
51+
- Header-based cache key manipulation
52+
- HTTP Parameter Pollution (HPP)
53+
- Case sensitivity attacks
54+
- Unicode normalization
55+
4. **Low-priority tests**:
56+
- Path normalization caching
57+
- Relative normalization
58+
- Prefix normalization
59+
- Logging helpers: `logDebug`, `logInfo`, `logWarning`, `logError`, `logTiming` — all write to Burp's Output tab
60+
61+
### `RequestSender.java`
62+
The vulnerability testing engine. All individual test methods live here.
63+
64+
Key capabilities:
65+
- **Response caching**: Caffeine cache with configurable TTL to avoid redundant requests
66+
- **Rate limiting**: Per-host token bucket limiting
67+
- **Circuit breaker**: Per-host failure tracking; stops hammering broken hosts
68+
- **Retry logic**: Up to 3 retries with exponential backoff
69+
- **Response similarity**: Uses both Jaro-Winkler (threshold 0.75) and Levenshtein (threshold 300) to compare responses
70+
- **Dynamic content filtering**: Strips timestamps, CSRF tokens, session IDs, and UUIDs before comparison
71+
72+
Test methods:
73+
- `testDelimiterExtension()` — path delimiters (`;`, `/`, `?`, `%23`, `@`, `~`, `|`) + static extensions
74+
- `testNormalizationCaching()` — path normalization exploits
75+
- `testHashPathTraversal()` — hash fragment (`#`) traversal
76+
- `testSelfReferentialNormalization()` — self-referential path segments
77+
- `testReverseTraversal()` — reverse path traversal to cacheable resources
78+
- `testHeaderBasedCacheKey()` — `X-Forwarded-Host` / `X-Original-URL` header injection
79+
- `testHPPCacheKey()` — HTTP Parameter Pollution
80+
- `testCaseSensitivityAttack()` — case variation in cache keys
81+
- `testUnicodeNormalization()` — Unicode encoding tricks
82+
83+
### `WebCacheIssue.java`
84+
Implements Burp's `IScanIssue` interface. Always reports severity **High**, confidence **Tentative**. Includes exploitation instructions, example `curl` commands, and HTML-formatted remediation guidance.
85+
86+
### `PerformanceConfig.java`
87+
Detects system resources at startup and selects a performance profile:
88+
- **HIGH**: RAM > 4 GB AND CPU cores > 4 → 4× thread multiplier
89+
- **MEDIUM**: RAM > 2 GB AND CPU cores > 2 → 2× thread multiplier
90+
- **LOW** (default): 1× thread multiplier
91+
92+
Override via system properties or environment variables:
93+
```
94+
WEBCACHE_PROFILE=HIGH
95+
WEBCACHE_THREAD_MULTIPLIER=4
96+
WEBCACHE_CACHE_SIZE=50000 # entries (range: 2000–50000)
97+
WEBCACHE_RATE_LIMIT=100 # requests/second (range: 20–100)
98+
WEBCACHE_CACHE_TTL=20 # minutes (range: 10–30)
99+
```
100+
101+
---
102+
103+
## Build System
104+
105+
### Build commands
106+
107+
```bash
108+
# Build the fat JAR (includes all dependencies)
109+
./gradlew fatJar
110+
111+
# Clean + build
112+
./gradlew clean build
113+
114+
# Windows
115+
gradlew.bat fatJar
116+
```
117+
118+
Output: `build/libs/web-cache-deception-scanner-all.jar`
119+
120+
### Dependencies (build.gradle)
121+
122+
| Artifact | Version | Purpose |
123+
|---|---|---|
124+
| `net.portswigger.burp.extender:burp-extender-api` | 2.3 | Burp Suite extension API |
125+
| `org.apache.commons:commons-lang3` | 3.12.0 | String utilities |
126+
| `org.apache.commons:commons-text` | 1.10.0 | Jaro-Winkler similarity |
127+
| `com.github.ben-manes.caffeine:caffeine` | 3.1.8 | High-performance cache |
128+
129+
Java source/target compatibility: **11**.
130+
131+
The `fatJar` Gradle task bundles everything into a single self-contained JAR for loading into Burp.
132+
133+
---
134+
135+
## CI/CD Pipeline (`.github/workflows/build.yml`)
136+
137+
Triggers on:
138+
- Push to `main` or `master`
139+
- Pull request creation
140+
- Manual workflow dispatch
141+
142+
Steps:
143+
1. Checkout + set up JDK 11 (Temurin)
144+
2. Build with `./gradlew fatJar`
145+
3. Auto-increment minor version (e.g., `v2.0` → `v2.1`) on pushes to main
146+
4. Create a GitHub Release with the JAR attached
147+
5. Retain build artifacts for 30 days
148+
149+
When modifying the build pipeline, keep the `BuildCommand` in `BappManifest.bmf` in sync with `build.gradle`.
150+
151+
---
152+
153+
## Code Conventions
154+
155+
### General style
156+
- Standard Java conventions (camelCase methods, PascalCase classes)
157+
- Comprehensive null-checks before processing HTTP messages
158+
- All shared mutable state uses `ConcurrentHashMap`, `AtomicInteger`, or `AtomicLong`
159+
- Compiler warnings are enabled (`-Xlint:unchecked`, `-Xlint:deprecation`) — fix any new warnings introduced
160+
161+
### Logging
162+
Use the logging helpers in `BurpExtender`, not `System.out`:
163+
```java
164+
logDebug(tag, message);
165+
logInfo(tag, message);
166+
logWarning(tag, message);
167+
logError(tag, message);
168+
logTiming(tag, elapsedMs);
169+
```
170+
All output appears in Burp Suite's Output tab with timestamps and severity level.
171+
172+
### Similarity comparison
173+
When determining whether two responses are "equivalent" (i.e., the caching attack didn't change the response):
174+
- Apply `filterDynamicContent()` first to strip volatile fields
175+
- Use **both** Jaro-Winkler (≥ 0.75 = similar) **and** Levenshtein (≤ 300 = similar)
176+
- A response is considered "different" (potential cache hit) only when **both** metrics indicate divergence
177+
178+
### Thread safety
179+
- `BurpExtender` uses a `ThreadPoolExecutor` — never block the Burp EDT
180+
- `RequestSender` rate limiters and circuit breakers are keyed per host using `ConcurrentHashMap`
181+
- New shared state must use concurrent collections or explicit synchronization
182+
183+
### Adding new test vectors
184+
1. Add the test method to `RequestSender.java` following the pattern of existing methods
185+
2. Classify it HIGH / MEDIUM / LOW priority
186+
3. Wire it into `ScannerThread.run()` in `BurpExtender.java` at the appropriate priority level
187+
4. Update `WebCacheIssue.java` if the new vector requires distinct reporting language
188+
5. Document the vector in `README.md`
189+
190+
---
191+
192+
## Testing
193+
194+
There is no automated test suite. To validate changes:
195+
1. Build the fat JAR: `./gradlew fatJar`
196+
2. Load into Burp Suite: Extender → Add → select the JAR
197+
3. Right-click a request in Proxy history → "Web Cache Deception Test"
198+
4. Inspect the Output tab for log output and the Issues tab for findings
199+
200+
Test against a local instance of a vulnerable application (e.g., a deliberately misconfigured Nginx + app stack) to avoid unintended testing of production systems.
201+
202+
---
203+
204+
## Extension Metadata
205+
206+
`BappManifest.bmf` must stay consistent with the build:
207+
208+
| Field | Value |
209+
|---|---|
210+
| UUID | `7c1ca94a61474d9e897d307c858d52f0` |
211+
| Name | Web Cache Deception Scanner |
212+
| EntryPoint | `build/libs/web-cache-deception-scanner-all.jar` |
213+
| BuildCommand | `gradle fatJar` |
214+
215+
Do not change the UUID — it identifies the extension in the Burp BApp store.
216+
217+
---
218+
219+
## Security Considerations
220+
221+
- This tool sends **crafted HTTP requests** to target servers. Only run it against systems you are authorized to test.
222+
- The extension does not exfiltrate data; it only reads response metadata to infer caching behavior.
223+
- Rate limiting and circuit breakers are built in to avoid overwhelming targets.
224+
- Never commit credentials, session tokens, or real target URLs into the repository.

0 commit comments

Comments
 (0)