How tanush-vashisht160/autofuzzllm works
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: response_classifier.py Analysis core · campaign.py Campaign core · app.py App entry · mutator.py Mutator core
Components 28
Fuzzing pipeline
Campaign orchestration, seed handling, mutations, execution, and oracle evaluation.
- Runner · Headless campaign execution entrypoint.
fuzz_runner.py - Campaign core · Campaign loop and adaptive campaign control.
fuzzing/campaign.py - Adaptive mode · Feedback-driven campaign variant.
fuzzing/adaptive_campaign.py - Seed pool · Seed selection, reuse, and campaign input source.
fuzzing/seed_pool/seed_pool.py - Seed prompts · Static prompt corpus used to bootstrap campaigns.
datasets/seed_prompts.json - Mutator core · Mutation entrypoint and strategy selection.
fuzzing/mutator.py - Strategies · Strategy selection for prompt mutation behavior.
fuzzing/mutation_strategies.py - Operators · Composable prompt transformation operators.
- AI/template mutators · Higher-level mutation paths beyond static transforms.
fuzzing/mutations/ai_mutator.py - Template mutator · Template-driven prompt mutation path.
fuzzing/mutations/template_mutator.py - Operator manager · Selects and composes prompt operators.
fuzzing/mutations/operators/operator_manager.py - Executor · Sends mutated prompts to target models and collects responses.
fuzzing/executor.py - Oracle · Determines whether a response exhibits a vulnerability or leak.
fuzzing/oracle/oracle.py
LLM backends
Provider routing and model-specific client adapters.
- LLM router · Routes requests to provider-specific model clients.
llm/llm_router.py - Provider clients · Gemini, Groq, Ollama, and OpenRouter adapters.
Analysis layer
Classification, scoring, risk mapping, and insight extraction.
- Analysis core · Classification, rules, risk scoring, OWASP mapping, and insights.
analysis/response_classifier.py - Rule engine · Rule-based response classification and evaluation.
analysis/rule_engine.py - Risk scoring · Risk scoring and severity aggregation.
analysis/risk_score.py - Insights · Human-readable findings and summaries from analysis.
analysis/insights.py - Scorer · Aggregates findings into campaign-level scores.
scorer.py
User interface
Streamlit-style entrypoints, tabs, and result views.
- App entry · Main interactive application bootstrap.
app.py - History page · Campaign history browsing view.
pages/1_Campaign_History.py - Live fuzzer · Interactive single-run campaign surface.
tabs/live_fuzzer.py - Batch campaign · Bulk campaign execution surface.
tabs/batch_campaign.py - Insights views · Charts, explanations, dynamic insights, and report rendering.
Storage and reports
Persistent state, database access, and exported report artifacts.
- Database · Local durable store for campaigns, runs, and results.
database/database.py - Core state · Shared in-process application and campaign state.
core_state.py - Reports · Report generator and PDF artifact output.
reports/report_generator.py
Connections 34
- 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.