# cyberark/fuzzyai architecture

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

- Interactive diagram: https://gitdiagram.com/cyberark/fuzzyai
- Repository: https://github.com/cyberark/fuzzyai

## Overview

#### Purpose and entry points
FuzzyAI is a Python LLM-security fuzzer: it generates or transforms adversarial prompts, sends them to target LLMs/APIs, evaluates responses, and reports/persists findings. The packaged CLI is centered on `fuzzyai fuzz` and experimental `fuzzyai webui`; likely entry wiring is in `src/fuzzyai/cli.py`, with orchestration in `src/fuzzyai/fuzzer.py` and UI support in `src/fuzzyai/webui.py`.

#### Fuzzing orchestration
`src/fuzzyai/fuzzer.py` is the primary control plane. It receives CLI/configured targets, prompts, attacks, classifiers, models, and execution options; coordinates the campaign; and produces result records. Shared domain structures for prompts and outputs live in `src/fuzzyai/models/prompt.py` and `src/fuzzyai/models/fuzzer_result.py`. Batch/concurrent work is separated into `src/fuzzyai/handlers/async_batch.py`.

#### Attack strategy layer
Attack handlers implement prompt-generation and iterative jailbreak strategies behind shared attack abstractions and type definitions:
- `src/fuzzyai/handlers/attacks/base.py`
- `src/fuzzyai/handlers/attacks/attack_manager.py`
- `src/fuzzyai/handlers/attacks/models.py`

Concrete strategies are isolated by directory, enabling extension without changing provider code; examples include `src/fuzzyai/handlers/attacks/genetic/handler.py`, `src/fuzzyai/handlers/attacks/gpt_fuzzer/handler.py`, and `src/fuzzyai/handlers/attacks/crescendo/handler.py`. Some attacks require auxiliary LLM calls, iteration, prompt templates, or resource-backed datasets.

#### Target-model abstraction and providers
A common LLM chain/provider boundary shields campaigns and attacks from vendor SDK/API differences:
- `src/fuzzyai/llm/chain.py`
- `src/fuzzyai/llm/providers/base.py`
- `src/fuzzyai/llm/models.py`

Provider adapters cover OpenAI, Anthropic, Azure, AWS Bedrock, Gemini, AI21, DeepSeek, Ollama/local models, and generic REST targets. Representative implementations are `src/fuzzyai/llm/providers/openai/openai.py`, `src/fuzzyai/llm/providers/bedrock/handler.py`, and `src/fuzzyai/llm/providers/rest/handler.py`. This is the principal external-service boundary; API credentials and endpoint/model-specific settings are supplied at runtime.

#### Response classification and refinement
After a target returns output, classifiers decide whether an attack succeeded or score/detect content. The shared classifier contract is `src/fuzzyai/handlers/classifiers/base.py`; classifier selection/types are under `src/fuzzyai/handlers/classifiers/enums.py`. Implementations range from LLM judges to provider safety services and local heuristics, e.g. `src/fuzzyai/handlers/classifiers/generic_llm/handler.py`, `src/fuzzyai/handlers/classifiers/openai_moderation/handler.py`, and `src/fuzzyai/handlers/classifiers/aws_guardrails/handler.py`. `src/fuzzyai/handlers/response_refinement_handler.py` supports iterative attack workflows that feed evaluation back into subsequent generation.

#### Mutation, text, and token boundaries
Reusable transformations are a separate layer from named attacks, with a base contract in `src/fuzzyai/handlers/mutators/base.py` and implementations such as `src/fuzzyai/handlers/mutators/rephrase/handler.py` and `src/fuzzyai/handlers/mutators/retokenize/handler.py`. Text/similarity analysis is centralized in `src/fuzzyai/handlers/text_analyzer.py` and `src/fuzzyai/handlers/sentence_similarity_analyzer.py`; tokenization is isolated in `src/fuzzyai/handlers/tokenizers/handler.py`. These components support candidate generation, deduplication/scoring, and attack-specific transformations.

#### Persistence and bundled inputs
MongoDB is the explicit persistence runtime, accessed through `src/fuzzyai/db/mongodb.py`; campaign/report and adversarial-data handlers are grouped in `src/fuzzyai/handlers/db/fuzzer_report.py` and `src/fuzzyai/handlers/db/adv_prompts.py`. `run_mongo.sh` supports local infrastructure. Bundled prompt corpora, benchmark data, and templates reside in `src/fuzzyai/resources/`, notably `src/fuzzyai/resources/adv_prompts.txt` and `src/fuzzyai/resources/harmful_behaviors.csv`. Ollama is optional local model infrastructure, supported by `run_ollama.sh`.

Main entry points: [`src/fuzzyai/fuzzer.py`](https://github.com/cyberark/fuzzyai/blob/main/src/fuzzyai/fuzzer.py) (Fuzzing orchestrator), [`src/fuzzyai/handlers/attacks/genetic/handler.py`](https://github.com/cyberark/fuzzyai/blob/main/src/fuzzyai/handlers/attacks/genetic/handler.py) (Concrete attacks), [`src/fuzzyai/llm/chain.py`](https://github.com/cyberark/fuzzyai/blob/main/src/fuzzyai/llm/chain.py) (LLM chain), [`src/fuzzyai/handlers/classifiers/base.py`](https://github.com/cyberark/fuzzyai/blob/main/src/fuzzyai/handlers/classifiers/base.py) (Response classifiers)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Entry points"]
  node_cli["FuzzyAI CLI<br/>[cli.py]"]
  node_webui["Web UI<br/>[webui.py]"]
end

subgraph group_campaign["Campaign engine"]
  node_fuzzer{{"Fuzzing orchestrator<br/>control plane<br/>[fuzzer.py]"}}
  node_async_batch["Async batch executor<br/>concurrency<br/>[async_batch.py]"]
  node_prompt["Prompt model<br/>domain model<br/>[prompt.py]"]
  node_result["Fuzzer result model<br/>domain model<br/>[fuzzer_result.py]"]
end

subgraph group_strategies["Attack and evaluation"]
  node_attack_contract["Attack contracts<br/>strategy API<br/>[base.py]"]
  node_attack_manager["Attack manager<br/>strategy selection"]
  node_attack_strategies["Concrete attacks<br/>attack strategies<br/>[handler.py]"]
  node_mutators["Prompt mutators<br/>transformation API<br/>[base.py]"]
  node_refinement["Response refinement<br/>iteration feedback"]
  node_classifiers["Response classifiers<br/>classifier API<br/>[base.py]"]
end

subgraph group_llm["LLM boundary"]
  node_llm_chain{{"LLM chain<br/>provider facade<br/>[chain.py]"}}
  node_provider_base["Provider contract<br/>provider API<br/>[base.py]"]
  node_providers["Provider adapters<br/>vendor adapters<br/>[openai.py]"]
  node_external_llms(("Target and auxiliary LLMs<br/>external services"))
end

subgraph group_data["Data and persistence"]
  node_resources["Bundled corpora and templates<br/>resource data<br/>[adv_prompts.txt]"]
  node_mongo_handlers["Report and prompt persistence<br/>persistence handlers<br/>[fuzzer_report.py]"]
  node_mongodb[("MongoDB<br/>database<br/>[mongodb.py]")]
end

node_cli -->|"starts campaign"| node_fuzzer
node_cli -->|"launches"| node_webui
node_webui -->|"configures and starts"| node_fuzzer
node_fuzzer -->|"dispatches work"| node_async_batch
node_fuzzer -->|"selects attacks"| node_attack_manager
node_fuzzer -->|"sends target prompts"| node_llm_chain
node_fuzzer -->|"evaluates responses"| node_classifiers
node_fuzzer -->|"persists findings"| node_mongo_handlers
node_fuzzer -->|"produces"| node_result
node_attack_manager -->|"uses"| node_attack_contract
node_attack_manager -->|"instantiates"| node_attack_strategies
node_attack_strategies -->|"transforms candidates"| node_mutators
node_attack_strategies -->|"loads inputs"| node_resources
node_attack_strategies -->|"iterates with feedback"| node_refinement
node_refinement -->|"uses evaluations"| node_classifiers
node_attack_strategies -.->|"makes auxiliary calls"| node_llm_chain
node_classifiers -.->|"uses LLM or safety providers"| node_llm_chain
node_llm_chain -->|"delegates through"| node_provider_base
node_provider_base -->|"implemented by"| node_providers
node_providers -->|"calls"| node_external_llms
node_mongo_handlers -->|"stores reports and prompts"| node_mongodb
node_resources -->|"supplies seed prompts"| node_prompt

click node_cli "https://github.com/cyberark/fuzzyai/blob/main/src/fuzzyai/cli.py"
click node_webui "https://github.com/cyberark/fuzzyai/blob/main/src/fuzzyai/webui.py"
click node_fuzzer "https://github.com/cyberark/fuzzyai/blob/main/src/fuzzyai/fuzzer.py"
click node_async_batch "https://github.com/cyberark/fuzzyai/blob/main/src/fuzzyai/handlers/async_batch.py"
click node_prompt "https://github.com/cyberark/fuzzyai/blob/main/src/fuzzyai/models/prompt.py"
click node_result "https://github.com/cyberark/fuzzyai/blob/main/src/fuzzyai/models/fuzzer_result.py"
click node_attack_contract "https://github.com/cyberark/fuzzyai/blob/main/src/fuzzyai/handlers/attacks/base.py"
click node_attack_strategies "https://github.com/cyberark/fuzzyai/blob/main/src/fuzzyai/handlers/attacks/genetic/handler.py"
click node_mutators "https://github.com/cyberark/fuzzyai/blob/main/src/fuzzyai/handlers/mutators/base.py"
click node_refinement "https://github.com/cyberark/fuzzyai/blob/main/src/fuzzyai/handlers/response_refinement_handler.py"
click node_classifiers "https://github.com/cyberark/fuzzyai/blob/main/src/fuzzyai/handlers/classifiers/base.py"
click node_llm_chain "https://github.com/cyberark/fuzzyai/blob/main/src/fuzzyai/llm/chain.py"
click node_provider_base "https://github.com/cyberark/fuzzyai/blob/main/src/fuzzyai/llm/providers/base.py"
click node_providers "https://github.com/cyberark/fuzzyai/blob/main/src/fuzzyai/llm/providers/openai/openai.py"
click node_resources "https://github.com/cyberark/fuzzyai/blob/main/src/fuzzyai/resources/adv_prompts.txt"
click node_mongo_handlers "https://github.com/cyberark/fuzzyai/blob/main/src/fuzzyai/handlers/db/fuzzer_report.py"
click node_mongodb "https://github.com/cyberark/fuzzyai/blob/main/src/fuzzyai/db/mongodb.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_cli,node_webui toneBlue
class node_fuzzer,node_async_batch,node_prompt,node_result toneAmber
class node_attack_contract,node_attack_manager,node_attack_strategies,node_mutators,node_refinement,node_classifiers toneMint
class node_llm_chain,node_provider_base,node_providers,node_external_llms toneRose
class node_resources,node_mongo_handlers,node_mongodb toneIndigo
```

## Components

### Entry points

- [FuzzyAI CLI](https://github.com/cyberark/fuzzyai/blob/main/src/fuzzyai/cli.py): CLI · Provides fuzz and experimental webui commands. · `src/fuzzyai/cli.py`
- [Web UI](https://github.com/cyberark/fuzzyai/blob/main/src/fuzzyai/webui.py): UI · `src/fuzzyai/webui.py`

### Campaign engine

- [Fuzzing orchestrator](https://github.com/cyberark/fuzzyai/blob/main/src/fuzzyai/fuzzer.py): control plane · Coordinates targets, attacks, classification, and result production. · `src/fuzzyai/fuzzer.py`
- [Async batch executor](https://github.com/cyberark/fuzzyai/blob/main/src/fuzzyai/handlers/async_batch.py): concurrency · `src/fuzzyai/handlers/async_batch.py`
- [Prompt model](https://github.com/cyberark/fuzzyai/blob/main/src/fuzzyai/models/prompt.py): domain model · `src/fuzzyai/models/prompt.py`
- [Fuzzer result model](https://github.com/cyberark/fuzzyai/blob/main/src/fuzzyai/models/fuzzer_result.py): domain model · `src/fuzzyai/models/fuzzer_result.py`

### Attack and evaluation

- [Attack contracts](https://github.com/cyberark/fuzzyai/blob/main/src/fuzzyai/handlers/attacks/base.py): strategy API · `src/fuzzyai/handlers/attacks/base.py`
- **Attack manager**: strategy selection
- [Concrete attacks](https://github.com/cyberark/fuzzyai/blob/main/src/fuzzyai/handlers/attacks/genetic/handler.py): attack strategies · Genetic, GPT Fuzzer, Crescendo, and other extensible jailbreak strategies. · `src/fuzzyai/handlers/attacks/genetic/handler.py`
- [Prompt mutators](https://github.com/cyberark/fuzzyai/blob/main/src/fuzzyai/handlers/mutators/base.py): transformation API · Reusable rephrasing and retokenization transformations. · `src/fuzzyai/handlers/mutators/base.py`
- [Response refinement](https://github.com/cyberark/fuzzyai/blob/main/src/fuzzyai/handlers/response_refinement_handler.py): iteration feedback · `src/fuzzyai/handlers/response_refinement_handler.py`
- [Response classifiers](https://github.com/cyberark/fuzzyai/blob/main/src/fuzzyai/handlers/classifiers/base.py): classifier API · LLM judges, safety services, and local heuristics evaluate outputs. · `src/fuzzyai/handlers/classifiers/base.py`

### LLM boundary

- [LLM chain](https://github.com/cyberark/fuzzyai/blob/main/src/fuzzyai/llm/chain.py): provider facade · `src/fuzzyai/llm/chain.py`
- [Provider contract](https://github.com/cyberark/fuzzyai/blob/main/src/fuzzyai/llm/providers/base.py): provider API · `src/fuzzyai/llm/providers/base.py`
- [Provider adapters](https://github.com/cyberark/fuzzyai/blob/main/src/fuzzyai/llm/providers/openai/openai.py): vendor adapters · OpenAI, Bedrock, REST, and other hosted or local model targets. · `src/fuzzyai/llm/providers/openai/openai.py`
- **Target and auxiliary LLMs**: external services · Runtime-configured vendor APIs, REST endpoints, or local models.

### Data and persistence

- [Bundled corpora and templates](https://github.com/cyberark/fuzzyai/blob/main/src/fuzzyai/resources/adv_prompts.txt): resource data · Adversarial prompts, benchmarks, and attack inputs. · `src/fuzzyai/resources/adv_prompts.txt`
- [Report and prompt persistence](https://github.com/cyberark/fuzzyai/blob/main/src/fuzzyai/handlers/db/fuzzer_report.py): persistence handlers · `src/fuzzyai/handlers/db/fuzzer_report.py`
- [MongoDB](https://github.com/cyberark/fuzzyai/blob/main/src/fuzzyai/db/mongodb.py): database · Stores campaign reports and adversarial data. · `src/fuzzyai/db/mongodb.py`

## Connections

- FuzzyAI CLI → Fuzzing orchestrator: starts campaign
- FuzzyAI CLI → Web UI: launches
- Web UI → Fuzzing orchestrator: configures and starts
- Fuzzing orchestrator → Async batch executor: dispatches work
- Fuzzing orchestrator → Attack manager: selects attacks
- Fuzzing orchestrator → LLM chain: sends target prompts
- Fuzzing orchestrator → Response classifiers: evaluates responses
- Fuzzing orchestrator → Report and prompt persistence: persists findings
- Fuzzing orchestrator → Fuzzer result model: produces
- Attack manager → Attack contracts: uses
- Attack manager → Concrete attacks: instantiates
- Concrete attacks → Prompt mutators: transforms candidates
- Concrete attacks → Bundled corpora and templates: loads inputs
- Concrete attacks → Response refinement: iterates with feedback
- Response refinement → Response classifiers: uses evaluations
- Concrete attacks → LLM chain: makes auxiliary calls
- Response classifiers → LLM chain: uses LLM or safety providers
- LLM chain → Provider contract: delegates through
- Provider contract → Provider adapters: implemented by
- Provider adapters → Target and auxiliary LLMs: calls
- Report and prompt persistence → MongoDB: stores reports and prompts
- Bundled corpora and templates → Prompt model: supplies seed prompts
