# tanush-vashisht160/autofuzzllm architecture

> Architecture diagram of the GitHub repository tanush-vashisht160/autofuzzllm, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-07-06). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/tanush-vashisht160/autofuzzllm
- Repository: https://github.com/tanush-vashisht160/autofuzzllm

## Overview

AutoFuzzLLM is an LLM fuzzing and prompt-attack analysis system with two main surfaces: an interactive UI for running campaigns and a backend pipeline for generating, executing, scoring, and persisting fuzzing results.

1. **Top-level structure**
   - `app.py` and `pages/` suggest a Streamlit-style multipage application.
   - `fuzz_runner.py` is the likely non-UI execution entrypoint for running campaigns headlessly.
   - `campaign_report.pdf` and `reports/` indicate the system can generate offline summaries of fuzzing runs.

2. **End-to-end workflow**
   - A campaign starts from seed prompts in `datasets/seed_prompts.json` and/or the `fuzzing/seed_pool`.
   - Seeds are mutated into attack variants, executed against an LLM target, classified by the oracle/analysis layer, and stored in the database.
   - Results feed UI views, insights, and report generation.

3. **Fuzzing engine**
   - `fuzzing/campaign.py`, `fuzzing/adaptive_campaign.py`, and `fuzzing/executor.py` form the core run loop.
   - `fuzzing/mutator.py`, `fuzzing/mutation_strategies.py`, and `fuzzing/mutations/` implement prompt transformation logic.
   - This layer is responsible for producing adversarial variants, scheduling runs, and coordinating execution.

4. **Mutation system and attack operators**
   - `fuzzing/mutations/operators/` contains a plug-in style operator set for specific prompt transformations such as base64, rot13, unicode, translation, roleplay, persona, prompt leakage, XML/JSON wrapping, typoglycemia, and context switching.
   - `operator_manager.py` likely selects and composes operators.
   - `ai_mutator.py` and `template_mutator.py` provide higher-level mutation paths beyond static string transforms.
   - `fuzzing/attacks/base_attacks.py` appears to define attack templates or shared attack behavior.

5. **Seed management**
   - `fuzzing/seed_pool/seed.py` and `seed_pool.py` manage the source prompts that drive campaigns.
   - This layer likely tracks seed quality, reuse, and selection for adaptive fuzzing.
   - The seed pool is the bridge between static datasets and generated adversarial campaigns.

6. **LLM provider abstraction**
   - `llm/llm_router.py` routes requests to provider-specific clients.
   - Provider adapters exist for `gemini`, `groq`, `ollama`, and `openrouter`.
   - This keeps the fuzzing engine model-agnostic: campaigns can target different backends without changing the mutation logic.

7. **Oracle, scoring, and analysis**
   - `fuzzing/oracle/oracle.py` is the response evaluation boundary: it determines whether a model output shows a vulnerability, refusal, leakage, or other behavior of interest.
   - `analysis/response_classifier.py`, `analysis/rule_engine.py`, `analysis/risk_score.py`, `analysis/owasp_mapper.py`, and `analysis/insights.py` turn raw responses into structured findings and scores.
   - `scorer.py` likely aggregates those findings into campaign-level metrics.

8. **Persistence and state**
   - `database/database.py` and `autofuzz.db` indicate local durable storage, likely SQLite-backed.
   - `core_state.py` suggests shared runtime state used across UI and backend components.
   - This storage layer is the repository for campaign history, run metadata, prompt/response pairs, and computed results.

9. **UI and operator dashboard**
   - `tabs/live_fuzzer.py` and `tabs/batch_campaign.py` suggest separate interactive modes for real-time and batch execution.
   - `ui/insights.py`, `ui/dynamic_insights.py`, `ui/charts.py`, `ui/report_view.py`, and `ui/explanations.py` provide visualization and interpretation of results.
   - `ui/assets/` contains loader assets for the interface.
   - `pages/1_Campaign_History.py` provides historical browsing of past runs.

10. **Reporting**
   - `reports/report_generator.py` produces exportable reports, likely from stored campaign data and analysis outputs.
   - The presence of `campaign_report.pdf` shows reports are a first-class artifact, not just an on-screen view.

11. **Configuration and environment**
   - `config/settings.py` centralizes runtime configuration such as model/provider settings, database paths, and campaign parameters.
   - This is the main boundary for adapting the app to different environments or target models.

12. **Testing and verification**
   - The `test_*.py` files cover campaign logic, mutators, the oracle, seed pool, database, and provider integrations.
   - The test layout mirrors the main subsystems, which reinforces the modular architecture: generation, execution, evaluation, and persistence are independently testable.

13. **Main architectural boundaries**
   - **Input boundary:** seed prompts and campaign configuration.
   - **Transformation boundary:** mutation operators and AI/template mutators.
   - **Execution boundary:** provider router and LLM clients.
   - **Evaluation boundary:** oracle plus analysis/scoring.
   - **Persistence boundary:** database and report artifacts.
   - **Presentation boundary:** Streamlit-like UI and reporting views.

14. **Overall shape**
   - The repository is a pipeline-oriented fuzzing platform: it takes prompts, mutates them into attack candidates, sends them to external LLM services, interprets responses with rule/scoring logic, stores results locally, and surfaces them through an interactive dashboard and generated reports.

Main entry points: [`analysis/response_classifier.py`](https://github.com/tanush-vashisht160/autofuzzllm/blob/main/analysis/response_classifier.py) (Analysis core), [`fuzzing/campaign.py`](https://github.com/tanush-vashisht160/autofuzzllm/blob/main/fuzzing/campaign.py) (Campaign core), [`app.py`](https://github.com/tanush-vashisht160/autofuzzllm/blob/main/app.py) (App entry), [`fuzzing/mutator.py`](https://github.com/tanush-vashisht160/autofuzzllm/blob/main/fuzzing/mutator.py) (Mutator core)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_group_fuzz["Fuzzing pipeline"]
  node_fuzz_runner["Runner<br/>cli entrypoint<br/>[fuzz_runner.py]"]
  node_campaign_core["Campaign core<br/>fuzzing orchestration<br/>[campaign.py]"]
  node_adaptive_campaign["Adaptive mode<br/>fuzzing strategy"]
  node_seed_pool[("Seed pool<br/>seed management<br/>[seed_pool.py]")]
  node_seed_prompts["Seed prompts<br/>dataset<br/>[seed_prompts.json]"]
  node_mutator_core["Mutator core<br/>mutation orchestration<br/>[mutator.py]"]
  node_mutation_strategies["Strategies<br/>mutation policy"]
  node_mutation_ops["Operators"]
  node_ai_template_mutator["AI/template mutators<br/>mutation engines<br/>[ai_mutator.py]"]
  node_template_mutator["Template mutator<br/>mutation engine"]
  node_operator_manager["Operator manager<br/>operator selection"]
  node_executor["Executor<br/>run coordinator<br/>[executor.py]"]
  node_oracle["Oracle<br/>response evaluation<br/>[oracle.py]"]
end

subgraph group_group_llm["LLM backends"]
  node_llm_router["LLM router<br/>provider router<br/>[llm_router.py]"]
  node_provider_clients["Provider clients<br/>model adapters"]
end

subgraph group_group_analysis["Analysis layer"]
  node_analysis_core["Analysis core<br/>analysis pipeline"]
  node_rule_engine["Rule engine<br/>analysis rules<br/>[rule_engine.py]"]
  node_risk_score(("Risk scoring<br/>analysis scoring<br/>[risk_score.py]"))
  node_insights["Insights<br/>[insights.py]"]
  node_scorer["Scorer<br/>metrics aggregation<br/>[scorer.py]"]
end

subgraph group_group_ui["User interface"]
  node_app_py["App entry<br/>ui entrypoint<br/>[app.py]"]
  node_pages_history["History page<br/>ui page"]
  node_tabs_live["Live fuzzer<br/>ui tab<br/>[live_fuzzer.py]"]
  node_tabs_batch["Batch campaign<br/>ui tab<br/>[batch_campaign.py]"]
  node_ui_views["Insights views<br/>ui views"]
end

subgraph group_group_storage["Storage and reports"]
  node_database[("Database<br/>persistence<br/>[database.py]")]
  node_core_state(("Core state<br/>runtime state<br/>[core_state.py]"))
  node_reports["Reports<br/>export generation"]
end

node_app_py -->|"launches"| node_tabs_live
node_app_py -->|"launches"| node_tabs_batch
node_app_py -->|"renders"| node_ui_views
node_app_py -->|"uses"| node_core_state
node_pages_history -->|"reads"| node_database
node_fuzz_runner -->|"starts"| node_campaign_core
node_campaign_core -->|"selects"| node_adaptive_campaign
node_campaign_core -->|"draws"| node_seed_pool
node_seed_pool -->|"loads"| node_seed_prompts
node_seed_pool -->|"feeds"| node_mutator_core
node_mutator_core -->|"chooses"| node_mutation_strategies
node_mutator_core -->|"applies"| node_mutation_ops
node_mutator_core -->|"routes"| node_ai_template_mutator
node_ai_template_mutator -->|"uses"| node_template_mutator
node_ai_template_mutator -->|"coordinates"| node_operator_manager
node_operator_manager -->|"selects"| node_mutation_ops
node_campaign_core -->|"dispatches"| node_executor
node_executor -->|"requests"| node_llm_router
node_llm_router -->|"delegates"| node_provider_clients
node_executor -->|"evaluates"| node_oracle
node_oracle -->|"classifies"| node_analysis_core
node_analysis_core -->|"uses"| node_rule_engine
node_analysis_core -->|"derives"| node_risk_score
node_analysis_core -->|"summarizes"| node_insights
node_analysis_core -->|"scores"| node_scorer
node_analysis_core -->|"persists"| node_database
node_scorer -->|"stores"| node_database
node_ui_views -->|"visualizes"| node_analysis_core
node_ui_views -->|"exports"| node_reports
node_reports -->|"reads"| node_database
node_reports -->|"references"| node_core_state
node_campaign_core -->|"updates"| node_core_state
node_tabs_live -->|"controls"| node_campaign_core
node_tabs_batch -->|"can invoke"| node_fuzz_runner

click node_app_py "https://github.com/tanush-vashisht160/autofuzzllm/blob/main/app.py"
click node_pages_history "https://github.com/tanush-vashisht160/autofuzzllm/blob/main/pages/1_Campaign_History.py"
click node_tabs_live "https://github.com/tanush-vashisht160/autofuzzllm/blob/main/tabs/live_fuzzer.py"
click node_tabs_batch "https://github.com/tanush-vashisht160/autofuzzllm/blob/main/tabs/batch_campaign.py"
click node_fuzz_runner "https://github.com/tanush-vashisht160/autofuzzllm/blob/main/fuzz_runner.py"
click node_campaign_core "https://github.com/tanush-vashisht160/autofuzzllm/blob/main/fuzzing/campaign.py"
click node_adaptive_campaign "https://github.com/tanush-vashisht160/autofuzzllm/blob/main/fuzzing/adaptive_campaign.py"
click node_seed_pool "https://github.com/tanush-vashisht160/autofuzzllm/blob/main/fuzzing/seed_pool/seed_pool.py"
click node_seed_prompts "https://github.com/tanush-vashisht160/autofuzzllm/blob/main/datasets/seed_prompts.json"
click node_mutator_core "https://github.com/tanush-vashisht160/autofuzzllm/blob/main/fuzzing/mutator.py"
click node_mutation_strategies "https://github.com/tanush-vashisht160/autofuzzllm/blob/main/fuzzing/mutation_strategies.py"
click node_ai_template_mutator "https://github.com/tanush-vashisht160/autofuzzllm/blob/main/fuzzing/mutations/ai_mutator.py"
click node_template_mutator "https://github.com/tanush-vashisht160/autofuzzllm/blob/main/fuzzing/mutations/template_mutator.py"
click node_operator_manager "https://github.com/tanush-vashisht160/autofuzzllm/blob/main/fuzzing/mutations/operators/operator_manager.py"
click node_executor "https://github.com/tanush-vashisht160/autofuzzllm/blob/main/fuzzing/executor.py"
click node_oracle "https://github.com/tanush-vashisht160/autofuzzllm/blob/main/fuzzing/oracle/oracle.py"
click node_llm_router "https://github.com/tanush-vashisht160/autofuzzllm/blob/main/llm/llm_router.py"
click node_analysis_core "https://github.com/tanush-vashisht160/autofuzzllm/blob/main/analysis/response_classifier.py"
click node_rule_engine "https://github.com/tanush-vashisht160/autofuzzllm/blob/main/analysis/rule_engine.py"
click node_risk_score "https://github.com/tanush-vashisht160/autofuzzllm/blob/main/analysis/risk_score.py"
click node_insights "https://github.com/tanush-vashisht160/autofuzzllm/blob/main/analysis/insights.py"
click node_scorer "https://github.com/tanush-vashisht160/autofuzzllm/blob/main/scorer.py"
click node_database "https://github.com/tanush-vashisht160/autofuzzllm/blob/main/database/database.py"
click node_core_state "https://github.com/tanush-vashisht160/autofuzzllm/blob/main/core_state.py"
click node_reports "https://github.com/tanush-vashisht160/autofuzzllm/blob/main/reports/report_generator.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_fuzz_runner,node_campaign_core,node_adaptive_campaign,node_seed_pool,node_seed_prompts,node_mutator_core,node_mutation_strategies,node_mutation_ops,node_ai_template_mutator,node_template_mutator,node_operator_manager,node_executor,node_oracle toneBlue
class node_llm_router,node_provider_clients toneAmber
class node_analysis_core,node_rule_engine,node_risk_score,node_insights,node_scorer toneMint
class node_app_py,node_pages_history,node_tabs_live,node_tabs_batch,node_ui_views toneRose
class node_database,node_core_state,node_reports toneIndigo
```

## Components

### Fuzzing pipeline

Campaign orchestration, seed handling, mutations, execution, and oracle evaluation.

- [Runner](https://github.com/tanush-vashisht160/autofuzzllm/blob/main/fuzz_runner.py): cli entrypoint · Headless campaign execution entrypoint. · `fuzz_runner.py`
- [Campaign core](https://github.com/tanush-vashisht160/autofuzzllm/blob/main/fuzzing/campaign.py): fuzzing orchestration · Campaign loop and adaptive campaign control. · `fuzzing/campaign.py`
- [Adaptive mode](https://github.com/tanush-vashisht160/autofuzzllm/blob/main/fuzzing/adaptive_campaign.py): fuzzing strategy · Feedback-driven campaign variant. · `fuzzing/adaptive_campaign.py`
- [Seed pool](https://github.com/tanush-vashisht160/autofuzzllm/blob/main/fuzzing/seed_pool/seed_pool.py): seed management · Seed selection, reuse, and campaign input source. · `fuzzing/seed_pool/seed_pool.py`
- [Seed prompts](https://github.com/tanush-vashisht160/autofuzzllm/blob/main/datasets/seed_prompts.json): dataset · Static prompt corpus used to bootstrap campaigns. · `datasets/seed_prompts.json`
- [Mutator core](https://github.com/tanush-vashisht160/autofuzzllm/blob/main/fuzzing/mutator.py): mutation orchestration · Mutation entrypoint and strategy selection. · `fuzzing/mutator.py`
- [Strategies](https://github.com/tanush-vashisht160/autofuzzllm/blob/main/fuzzing/mutation_strategies.py): mutation policy · Strategy selection for prompt mutation behavior. · `fuzzing/mutation_strategies.py`
- **Operators**: prompt operators · Composable prompt transformation operators.
- [AI/template mutators](https://github.com/tanush-vashisht160/autofuzzllm/blob/main/fuzzing/mutations/ai_mutator.py): mutation engines · Higher-level mutation paths beyond static transforms. · `fuzzing/mutations/ai_mutator.py`
- [Template mutator](https://github.com/tanush-vashisht160/autofuzzllm/blob/main/fuzzing/mutations/template_mutator.py): mutation engine · Template-driven prompt mutation path. · `fuzzing/mutations/template_mutator.py`
- [Operator manager](https://github.com/tanush-vashisht160/autofuzzllm/blob/main/fuzzing/mutations/operators/operator_manager.py): operator selection · Selects and composes prompt operators. · `fuzzing/mutations/operators/operator_manager.py`
- [Executor](https://github.com/tanush-vashisht160/autofuzzllm/blob/main/fuzzing/executor.py): run coordinator · Sends mutated prompts to target models and collects responses. · `fuzzing/executor.py`
- [Oracle](https://github.com/tanush-vashisht160/autofuzzllm/blob/main/fuzzing/oracle/oracle.py): response evaluation · Determines whether a response exhibits a vulnerability or leak. · `fuzzing/oracle/oracle.py`

### LLM backends

Provider routing and model-specific client adapters.

- [LLM router](https://github.com/tanush-vashisht160/autofuzzllm/blob/main/llm/llm_router.py): provider router · Routes requests to provider-specific model clients. · `llm/llm_router.py`
- **Provider clients**: model adapters · Gemini, Groq, Ollama, and OpenRouter adapters.

### Analysis layer

Classification, scoring, risk mapping, and insight extraction.

- [Analysis core](https://github.com/tanush-vashisht160/autofuzzllm/blob/main/analysis/response_classifier.py): analysis pipeline · Classification, rules, risk scoring, OWASP mapping, and insights. · `analysis/response_classifier.py`
- [Rule engine](https://github.com/tanush-vashisht160/autofuzzllm/blob/main/analysis/rule_engine.py): analysis rules · Rule-based response classification and evaluation. · `analysis/rule_engine.py`
- [Risk scoring](https://github.com/tanush-vashisht160/autofuzzllm/blob/main/analysis/risk_score.py): analysis scoring · Risk scoring and severity aggregation. · `analysis/risk_score.py`
- [Insights](https://github.com/tanush-vashisht160/autofuzzllm/blob/main/analysis/insights.py): analysis insights · Human-readable findings and summaries from analysis. · `analysis/insights.py`
- [Scorer](https://github.com/tanush-vashisht160/autofuzzllm/blob/main/scorer.py): metrics aggregation · Aggregates findings into campaign-level scores. · `scorer.py`

### User interface

Streamlit-style entrypoints, tabs, and result views.

- [App entry](https://github.com/tanush-vashisht160/autofuzzllm/blob/main/app.py): ui entrypoint · Main interactive application bootstrap. · `app.py`
- [History page](https://github.com/tanush-vashisht160/autofuzzllm/blob/main/pages/1_Campaign_History.py): ui page · Campaign history browsing view. · `pages/1_Campaign_History.py`
- [Live fuzzer](https://github.com/tanush-vashisht160/autofuzzllm/blob/main/tabs/live_fuzzer.py): ui tab · Interactive single-run campaign surface. · `tabs/live_fuzzer.py`
- [Batch campaign](https://github.com/tanush-vashisht160/autofuzzllm/blob/main/tabs/batch_campaign.py): ui tab · Bulk campaign execution surface. · `tabs/batch_campaign.py`
- **Insights views**: ui views · Charts, explanations, dynamic insights, and report rendering.

### Storage and reports

Persistent state, database access, and exported report artifacts.

- [Database](https://github.com/tanush-vashisht160/autofuzzllm/blob/main/database/database.py): persistence · Local durable store for campaigns, runs, and results. · `database/database.py`
- [Core state](https://github.com/tanush-vashisht160/autofuzzllm/blob/main/core_state.py): runtime state · Shared in-process application and campaign state. · `core_state.py`
- [Reports](https://github.com/tanush-vashisht160/autofuzzllm/blob/main/reports/report_generator.py): export generation · Report generator and PDF artifact output. · `reports/report_generator.py`

## Connections

- App entry → Live fuzzer: launches · Main app exposes the live campaign surface.
- App entry → Batch campaign: launches · Main app exposes batch execution.
- App entry → Insights views: renders · App UI composes insights and reporting views.
- App entry → Core state: uses · UI shares runtime state for campaign context.
- History page → Database: reads · History page pulls persisted campaign records.
- Runner → Campaign core: starts · Headless runner invokes campaign execution.
- Campaign core → Adaptive mode: selects · Campaign core can switch into adaptive behavior.
- Campaign core → Seed pool: draws · Campaigns consume seeds from the seed pool.
- Seed pool → Seed prompts: loads · Static prompts bootstrap the seed pool.
- Seed pool → Mutator core: feeds · Selected seeds are handed into mutation.
- Mutator core → Strategies: chooses · Core mutation logic applies strategy selection.
- Mutator core → Operators: applies · Operator manager composes prompt transformations.
- Mutator core → AI/template mutators: routes · Mutation core can delegate to AI paths.
- AI/template mutators → Template mutator: uses · Higher-level mutators may invoke template-based mutation.
- AI/template mutators → Operator manager: coordinates · AI/template mutation can call into operator composition.
- Operator manager → Operators: selects · Operator manager selects concrete prompt operators.
- Campaign core → Executor: dispatches · Mutated prompts are sent for execution.
- Executor → LLM router: requests · Executor uses the provider router for target calls.
- LLM router → Provider clients: delegates · Router forwards to specific model adapters.
- Executor → Oracle: evaluates · Responses are passed to the oracle boundary.
- Oracle → Analysis core: classifies · Oracle and analysis turn responses into structured findings.
- Analysis core → Rule engine: uses · Structured classification is rule-driven.
- Analysis core → Risk scoring: derives · Analysis computes severity and risk signals.
- Analysis core → Insights: summarizes · Analysis emits narrative insights for the UI.
- Analysis core → Scorer: scores · Analysis outputs are aggregated into metrics.
- Analysis core → Database: persists · Structured findings and run data are stored locally.
- Scorer → Database: stores · Campaign scores are persisted with run history.
- Insights views → Analysis core: visualizes · UI surfaces insights derived from analysis.
- Insights views → Reports: exports · Views can render or generate report artifacts.
- Reports → Database: reads · Report generation consumes stored campaign data.
- Reports → Core state: references · Report/UI flows share campaign context.
- Campaign core → Core state: updates · Execution updates shared runtime state.
- Live fuzzer → Campaign core: controls · Live UI starts and monitors campaigns.
- Batch campaign → Runner: can invoke · Batch UI may trigger headless-style runs.
