How prompt-security/ps-fuzz works
Project Type and Purpose
• This is an open-source, Python-based command-line tool and library (“Prompt Fuzzer”) designed to dynamically test and harden system prompts for GenAI applications against a variety of simulated attacks.
• It exposes both a CLI interface and an interactive “playground” mode, uses multiple LLM providers via a pluggable chat-client abstraction, and supports extensibility through a registry of “attack” modules.
File Structure
Top-level artifacts and directories:
• .github/workflows – CI/CD and security scans (bandit, tests, release)
• build_package.sh, setup.py, MANIFEST.in – packaging and versioning
• ps_fuzz/ – core Python package
– __main__.py, cli.py, interactive_mode.py – entry points
– app_config.py, client_config.py, attack_config.py – config loaders
– chat_clients.py, langchain_integration.py – LLM provider adapters
– attack_loader.py, attack_registry.py, ps_logging.py – plugin/registry pattern and logging
– prompt_injection_fuzzer.py, work_progress_pool.py – orchestration and multi-threading
– attacks/ – individual attack implementations (each inherits a common interface)
– attack_data/ – CSV/Parquet files used by specific attacks
– results_table.py – result formatting & display
– util.py – shared utilities
• resources/, system_prompt.examples/ – static assets for demos
• tests/ – pytest unit tests
Insights from the README
• The system dynamically discovers attacks, dynamically selects LLM providers (OpenAI, Anthropic, etc.), and runs N attempts per attack in parallel threads.
• Output is a table of “Resilient” vs. “Broken” vs. “Errors.”
• Extensibility is a key design goal: new attacks and providers are added via registry modules.
Main Components and Their Interactions
a. CLI & Interactive Front End
• Parses command-line options (cli.py)
• In interactive mode (interactive_mode.py), launches a REPL-style prompt for iterative hardening
b. Configuration Layer
• app_config.py & attack_config.py read .env or env-vars
• client_config.py selects and configures the target LLM provider
c. Attack Registry & Loader
• attack_registry.py holds metadata for each attack (name, parameters)
• attack_loader.py dynamically imports attack implementations from ps_fuzz/attacks/
d. Core Fuzzer Engine (prompt_injection_fuzzer.py)
• Loads the system prompt and benchmark data
• For each registered attack:
– Generates attack prompts (using attack logic)
– Dispatches to the LLM via chat_clients.py adapter
– Collects responses and evaluates success/failure
e. Thread Pool & Orchestration (work_progress_pool.py)
• Manages a pool of worker threads, each running independent attack attempts
f. Result Aggregator & Display
• results_table.py formats results in a terminal table or CSV
g. LLM Provider Adapters (chat_clients.py & langchain_integration.py)
• Abstract base class defines send_prompt()
• Concrete subclasses implement OpenAI, Anthropic, etc.
h. Logging & Reporting (ps_logging.py)
• Centralized logging for debug levels, metrics, and error handling
Architectural Patterns and Design Principles
• Plugin/Registry Pattern for attacks and providers (loose coupling, discoverability)
• Strategy Pattern for chat client abstraction
• Separation of concerns: CLI vs. core engine vs. adapters vs. data
• Multi-threaded execution for parallel testing
Elements
• CLI / Interactive Mode
• Config Layer
• Attack Registry & Loader
• Fuzzer Engine
• Thread Pool / Workers
• Chat Client Adapters
• External LLM Services
• Result Aggregator / Display
• CLI → Engine
• Engine ↔ Config Layer
• Engine → Registry → Attack Modules
• Engine → Thread Pool → Workers → Chat Clients → External LLM APIs
• Engine → Result Aggregator → Display
• Blue for core components (Engine, Registry, Thread Pool)
• Green for extensibility points (Attack Modules, Chat Clients)
• Orange for external dependencies (LLM Providers, file-system data)