# atomiczsec/web-cache-deception-scanner-main architecture

> Architecture diagram of the GitHub repository atomiczsec/web-cache-deception-scanner-main, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-12). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/atomiczsec/web-cache-deception-scanner-main
- Repository: https://github.com/atomiczsec/web-cache-deception-scanner-main

## Overview

##### Project type and purpose
- This is a Java-based Burp Suite extension (plugin) named “Web Cache Deception Scanner” for the Burp Suite Community Edition.
- Its purpose is to hook into Burp’s UI, add a context-menu command, and automate a series of HTTP tests against target endpoints to detect web cache deception vulnerabilities.

##### File structure
- Top-level build files:
- build.gradle, settings.gradle, Gradle wrapper scripts under `gradle/`
- Source code under `src/main/java/burp/`:
- BurpExtender.java – the entry point that implements Burp’s IBurpExtender and IContextMenuFactory interfaces
- RequestSender.java – encapsulates all HTTP request/response logic (initial mapping, delimiter tests, path-normalization tests)
- WebCacheIssue.java – models and reports discovered cache deception issues back into Burp’s UI

##### Key insights from README
- The extension registers a right-click menu item in Burp’s Target and Proxy tabs.
- When invoked, it performs three main test phases (path-mapping, extension-delimiter, normalization).
- Built with Gradle, outputs a “-all.jar” plugin loaded into Burp.

##### Main components and relationships
a. Components
- Burp Suite Host (UI & core API)
- Extension JAR (web-cache-deception-scanner-all.jar)
- BurpExtender (entry point)
- RequestSender (HTTP logic module)
- WebCacheIssue (reporting/data model)
- Target Web Application (external HTTP service)
b. Interactions
1. At load time, Burp Suite invokes BurpExtender.registerExtenderCallbacks()
2. BurpExtender registers itself as a context-menu factory
3. User right-clicks a request → Burp invokes BurpExtender.createMenuItems()
4. User selects “Web Cache Deception Test” → extension calls RequestSender to run tests in sequence
5. RequestSender issues authenticated and unauthenticated HTTP requests to the Target Web Application
6. Responses come back and are compared for similarity
7. If a vulnerability is detected, WebCacheIssue instances are created and passed back via callbacks to display in Burp’s Scanner/Issue panel
c. Architectural patterns and principles
- Plugin architecture: Implements Burp’s extension API interfaces to decouple from Burp’s core
- Single Responsibility Classes:
- BurpExtender handles registration and menu wiring
- RequestSender handles all HTTP/test logic
- WebCacheIssue encapsulates data and reporting
d. Relevant technologies/frameworks
- Java 11+
- Burp Suite Extension API (IBurpExtender, IContextMenuFactory, IHttpRequestResponse, IScanIssue)
- Gradle build system

##### Detail
- Test phase as a sub-component or note in RequestSender (Initial Path Mapping, Delimiter+Extension Test, Path Normalization Test)
- Build artifact generation via Gradle (optional small side-note)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Burp Suite Host
    subgraph "Burp Suite Host"
        direction TB
        BSUI["Burp Suite UI"] 
        subgraph "Extension JAR: web-cache-deception-scanner-all.jar"
            direction TB
            BE["BurpExtender"]:::burp
            RS["RequestSender"]:::logic
            WC["WebCacheIssue"]:::model
        end
    end

    %% External Target Web Application
    TWA["Target Web Application"]:::external

    %% Build System
    subgraph "Gradle Build System"
        direction TB
        GRADLE_BUILD["build.gradle"]:::build
        SETTINGS["settings.gradle"]:::build
        GRADLEW["gradlew / gradlew.bat"]:::build
        WRAPPER["gradle/"]:::build
    end

    %% Documentation & Metadata
    subgraph "Docs & Metadata"
        direction TB
        README["README.md"]:::doc
        LICENSE["LICENSE"]:::doc
        RULES[".cursor/rules/*.mdc"]:::doc
        MANIFEST["BappManifest.bmf"]:::doc
        DESCRIPTION["BappDescription.html"]:::doc
    end

    %% Interactions
    BSUI -->|"load extension"| BE
    BE -->|"registerExtenderCallbacks()"| BE
    BSUI -->|"right-click request"| BE
    BE -->|"createMenuItems()"| BE
    BE -->|"invoke Web Cache Deception Test"| RS
    RS -->|"HTTP requests"| TWA
    TWA -->|"HTTP responses"| RS
    RS -->|"detect vulnerability"| WC
    WC -->|"report via callbacks"| BSUI

    %% Class Definitions
    classDef burp fill:#AED6F1,stroke:#21618C,color:#1B2631;
    classDef logic fill:#A9DFBF,stroke:#239B56,color:#1B2631;
    classDef model fill:#F5B041,stroke:#B9770E,color:#1B2631;
    classDef external fill:#D5D8DC,stroke:#7B7D7D,color:#1B2631;
    classDef build fill:#FAD7A0,stroke:#B9770E,color:#1B2631;
    classDef doc fill:#EBDEF0,stroke:#7D3C98,color:#1B2631;

    %% Click Events
    click BE "https://github.com/atomiczsec/web-cache-deception-scanner-main/blob/main/src/main/java/burp/BurpExtender.java"
    click RS "https://github.com/atomiczsec/web-cache-deception-scanner-main/blob/main/src/main/java/burp/RequestSender.java"
    click WC "https://github.com/atomiczsec/web-cache-deception-scanner-main/blob/main/src/main/java/burp/WebCacheIssue.java"
    click GRADLE_BUILD "https://github.com/atomiczsec/web-cache-deception-scanner-main/blob/main/build.gradle"
    click SETTINGS "https://github.com/atomiczsec/web-cache-deception-scanner-main/blob/main/settings.gradle"
    click GRADLEW "https://github.com/atomiczsec/web-cache-deception-scanner-main/tree/main/gradlew"
    click WRAPPER "https://github.com/atomiczsec/web-cache-deception-scanner-main/tree/main/gradle/"
    click MANIFEST "https://github.com/atomiczsec/web-cache-deception-scanner-main/blob/main/BappManifest.bmf"
    click DESCRIPTION "https://github.com/atomiczsec/web-cache-deception-scanner-main/blob/main/BappDescription.html"
    click RULES "https://github.com/atomiczsec/web-cache-deception-scanner-main/blob/main/.cursor/rules/*.mdc"
    click README "https://github.com/atomiczsec/web-cache-deception-scanner-main/blob/main/README.md"
    click LICENSE "https://github.com/atomiczsec/web-cache-deception-scanner-main/tree/main/LICENSE"
```
