# invicti-security/brainstorm architecture

> Architecture diagram of the GitHub repository invicti-security/brainstorm, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-17). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/invicti-security/brainstorm
- Repository: https://github.com/invicti-security/brainstorm

## Overview

##### Project type and purpose
- This is a command-line web-fuzzing tool (“brainstorm”) that orchestrates iterative discovery of hidden endpoints by combining:
- A local LLM (via Ollama) for intelligent path suggestion
- A traditional fuzzing engine (ffuf CLI) for probing those paths
- It also includes a benchmarking component to compare model performance.

##### Main components of the system
- CLI Entry Points (Python scripts)
- fuzzer.py – general path discovery
- fuzzer_shortname.py – 8.3-style short filenames
- benchmark.py – runs benchmarks and produces reports
- Prompt Loader
- Reads static files under prompts/ (files.txt, shortname.txt)
- AI Client Module
- Connects to the local Ollama REST API (default localhost:11434)
- Sends prompt + context and receives suggested paths
- Fuzzing Engine Wrapper
- Spawns ffuf subprocess calls with generated wordlists and URL templates
- Parses ffuf output (stdout or JSON) for “successful” HTTP codes
- Result Aggregator & Persistence
- Writes discovered links to all_links.txt and filenames to all_filenames.txt
- Updates in-memory state for next AI prompt
- Benchmarking & Reporting
- Runs multiple model+cycle configurations
- Aggregates stats and emits HTML/Markdown reports (benchmark_report.html, .md)

##### External Dependencies
- Ollama LLM service (local REST API)
- ffuf CLI tool in PATH
- Python runtime and third-party packages (requirements.txt)

##### Relationships and data flow
1. User invokes one of the Python scripts
2. Script reads initial prompts/files and loads any existing results
3. Loop (N cycles):
a. Send current discoveries + static prompt to Ollama → receive new path guesses
b. Call ffuf with these guesses → collect new successful endpoints
c. Merge new results into state and append to output files
4. End of loop → script exits (or benchmark module generates final report)

##### Important architectural patterns
- Pipeline/iteration with feedback loop between AI suggestions and traditional fuzzing
- Clear separation between “suggestion” (LLM) and “validation” (ffuf) stages
- Modular CLI scripts for different use cases
- File-based persistence for reproducibility and chaining

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% CLI Entry Points
    subgraph "CLI Entry Points"
        fuzzer["fuzzer.py"]:::cli
        fsn["fuzzer_shortname.py"]:::cli
        bench["benchmark.py"]:::cli
    end

    %% Core Modules
    subgraph "Core Modules"
        loader["Prompt Loader"]:::core
        ai["AI Client (Ollama)"]:::core
        wrapper["Fuzzer Wrapper (ffuf)"]:::core
        aggregator["Result Aggregator"]:::core
    end

    %% External Services
    subgraph "External Services"
        ollama["Ollama LLM Service"]:::ext
        ffuf["ffuf CLI Tool"]:::ext
    end

    %% File Stores
    subgraph "File Stores"
        promptsdir["prompts/"]:::store
        fileprompt["files.txt"]:::store
        sprompt["shortname.txt"]:::store
        links["links.txt"]:::store
        models["models.txt"]:::store
        reporthtml["benchmark_report.html"]:::store
        reportmd["benchmark_report.md"]:::store
        req["requirements.txt"]:::store
    end

    %% Data Flow
    fuzzer --> loader
    fsn --> loader
    loader --> promptsdir
    loader --> fileprompt
    loader --> sprompt
    loader --> ai
    ai --> ollama
    ai --> wrapper
    wrapper --> ffuf
    wrapper --> aggregator
    aggregator --> links
    aggregator --> ai
    bench --> models
    bench --> ai
    bench --> wrapper
    bench --> reporthtml
    bench --> reportmd
    bench --> req

    %% Click Events
    click fuzzer "https://github.com/invicti-security/brainstorm/blob/main/fuzzer.py"
    click fsn "https://github.com/invicti-security/brainstorm/blob/main/fuzzer_shortname.py"
    click bench "https://github.com/invicti-security/brainstorm/blob/main/benchmark.py"
    click promptsdir "https://github.com/invicti-security/brainstorm/tree/main/prompts/"
    click fileprompt "https://github.com/invicti-security/brainstorm/blob/main/prompts/files.txt"
    click sprompt "https://github.com/invicti-security/brainstorm/blob/main/prompts/shortname.txt"
    click links "https://github.com/invicti-security/brainstorm/blob/main/links.txt"
    click models "https://github.com/invicti-security/brainstorm/blob/main/models.txt"
    click reporthtml "https://github.com/invicti-security/brainstorm/blob/main/benchmark_report.html"
    click reportmd "https://github.com/invicti-security/brainstorm/blob/main/benchmark_report.md"
    click req "https://github.com/invicti-security/brainstorm/blob/main/requirements.txt"

    %% Styles
    classDef cli fill:#D0E6FF,stroke:#0066CC,color:#000;
    classDef core fill:#DFFFD0,stroke:#33AA00,color:#000;
    classDef ext fill:#FFE6B3,stroke:#CC8400,color:#000;
    classDef store fill:#E0E0E0,stroke:#888888,color:#000;
```
