How cyberark/fuzzyai works
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: fuzzer.py Fuzzing orchestrator · handler.py Concrete attacks · chain.py LLM chain · base.py Response classifiers
Components 19
Entry points
- FuzzyAI CLI · Provides fuzz and experimental webui commands.
src/fuzzyai/cli.py - Web UI
src/fuzzyai/webui.py
Campaign engine
- Fuzzing orchestrator · Coordinates targets, attacks, classification, and result production.
src/fuzzyai/fuzzer.py - Async batch executor
src/fuzzyai/handlers/async_batch.py - Prompt model
src/fuzzyai/models/prompt.py - Fuzzer result model
src/fuzzyai/models/fuzzer_result.py
Attack and evaluation
- Attack contracts
src/fuzzyai/handlers/attacks/base.py - Attack manager
- Concrete attacks · Genetic, GPT Fuzzer, Crescendo, and other extensible jailbreak strategies.
src/fuzzyai/handlers/attacks/genetic/handler.py - Prompt mutators · Reusable rephrasing and retokenization transformations.
src/fuzzyai/handlers/mutators/base.py - Response refinement
src/fuzzyai/handlers/response_refinement_handler.py - Response classifiers · LLM judges, safety services, and local heuristics evaluate outputs.
src/fuzzyai/handlers/classifiers/base.py
LLM boundary
- LLM chain
src/fuzzyai/llm/chain.py - Provider contract
src/fuzzyai/llm/providers/base.py - Provider adapters · OpenAI, Bedrock, REST, and other hosted or local model targets.
src/fuzzyai/llm/providers/openai/openai.py - Target and auxiliary LLMs · Runtime-configured vendor APIs, REST endpoints, or local models.
Data and persistence
- Bundled corpora and templates · Adversarial prompts, benchmarks, and attack inputs.
src/fuzzyai/resources/adv_prompts.txt - Report and prompt persistence
src/fuzzyai/handlers/db/fuzzer_report.py - MongoDB · Stores campaign reports and adversarial data.
src/fuzzyai/db/mongodb.py
Connections 22
- 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