Skip to article frontmatterSkip to article content
Site not loading correctly?

This may be due to an incorrect BASE_URL configuration. See the MyST Documentation for reference.

Framework

Learn how to use PyRIT’s components to build red teaming workflows.


The cards above link to a guide for each component. The rest of this page is the contributor guide: the principles every change follows and what each part of PyRIT owns. It is a north star for the architecture we are building toward. Some code doesn’t match yet, and Framework Plans list the main gaps. Follow this page rather than copying an exception.

Update this page rarely. Change it only when maintainers agree to change a principle or a component’s responsibility, or when a Framework Plan is done. Don’t add a feature’s details, examples, or edge cases; they belong in that component’s guide.

Principles

These decisions apply to every change. The style guide, notebook guide, and unit test guide cover the details.

Code

Security

Docs

Tests

Pull requests

Architecture

PyRIT's architecture. Surfaces (Python and notebooks, or the CLI and GUI through the backend REST API) run scenarios and attacks and keep domain logic in the library. A scenario packages the complete run: dataset objectives, the objective target, and scorers are run inputs, while each attack technique packages an attack with its converters, attack prompts, and adversarial or helper targets. In the shared library, the registry instantiates components and memory stores conversations, scores, and results.

Surfaces run the core components, and the shared library supports both. The orchestration layers nest from broadest to narrowest, and each owns less than the one above it:

Converters, targets, and scorers are the bricks that attacks use. The registry builds components, and memory holds the shared record of conversations, scores, and results.

Core Components

Core components are pluggable bricks. Each one can be swapped, combined, or replaced with a no-op, such as a converter that doesn’t convert or a target that only prints. Most contributions belong in one of them. If yours doesn’t fit, open an issue so we can discuss the architecture, and tell us what you want, or don’t want, under Framework Plans.

Datasets

Responsibility: Define, load, and store seeds: the objectives, prompts, and conversations that attacks use.

Framework Plans:

Contributing (difficulty easy): Add seed dataset providers, prompts, and jailbreak templates for what you’re testing.

Scenarios

Responsibility: Run PyRIT against something. A scenario turns user input into datasets paired with attack techniques, and runs them against an objective target with its scorers.

Framework Plans:

Contributing (difficulty medium): Is there a scanner that does something PyRIT doesn’t? Add it as a scenario. Expect more churn here than in other components.

Attack Techniques

Responsibility: Package a named, reusable attack: an attack class plus its configuration (converters, attack prompts, and helper targets). The technique is the recipe; the attack is the engine.

Framework Plans:

Contributing (difficulty easy): Add an AttackTechniqueFactory to extra.py, or to a source module like airt.py if one source owns it. Keep a technique that only one scenario can use with that scenario, and promote it to the catalog when others could reuse it. Reserve core for the curated set, and never tag a catalog technique default.

Executors and Attacks

Responsibility: An executor is an algorithm for interacting with an objective target: an objective and configuration go in, and a result comes out. Attacks are the most common executors; workflows, benchmarks, and prompt generators are the others.

Framework Plans:

Contributing (difficulty high): Most new attacks should be techniques. If you hit a limitation, open an issue.

Converters

Responsibility: Transform a prompt into something else: rephrase, encode, translate, or change its modality (for example, text to audio, an image, or a document). Converters can be stacked.

Framework Plans:

Contributing (difficulty low): The pattern is well-defined. Add conversions that help attacks.

Targets

Responsibility: Send a prepared Message and return the response. A target is usually an LLM, but it can be any endpoint: an HTTP API, an agent, or a storage account for cross-domain prompt injection. Attacks, converters, and scorers all use targets.

Framework Plans:

Contributing (difficulty low): The pattern is well-defined. Before adding a target, check whether an existing one already reaches your model, for example through an OpenAI-compatible endpoint.

Scorers

Responsibility: Tell the attack what happened. Was this blocked? Was the objective achieved? Was this tool called? Was this file written?

Framework Plans:

Contributing (difficulty low): The pattern is well-defined. Make probabilistic scorers more accurate, or add scorers for evidence you want to decide on.

Shared Library

These modules support every component.

Memory

Responsibility: Persist and retrieve everything that flows between components: seeds, prompts, responses, conversations, scores, and results. Memory is the shared record that lets components stay swappable while sharing context.

Models

Responsibility: Define the core types that PyRIT shares (messages, seeds, scores, results, and identifiers) once, and use them everywhere, including the REST API, so representations don’t drift.

Registry

Responsibility: Build and store components.

Normalizers

Responsibility: Move messages between attacks and targets in the right shape.

Exceptions

Responsibility: Define PyRIT’s exception hierarchy and the retry behavior built on it.

Setup

Responsibility: Bootstrap a PyRIT session: memory, defaults, and registered components.

Output

Responsibility: Render results (attack and scenario results, conversations, scores, and findings) in any format to any destination.

Contributing (difficulty low): Adding a format or sink is well-defined. Give every new domain printer a matching convenience function in helpers.py.

Analytics

Responsibility: Answer questions across stored results. Which technique works best? How often did an objective succeed? Which responses match known content?

Auth

Responsibility: Authenticate to the external services PyRIT calls, behind a common Authenticator. Components get credentials through these helpers instead of handling tokens themselves.

Code Execution (Experimental)

Responsibility: Run programs through caller-configured execution backends and return typed results. The API (pyrit._code_execution) is private and may change without deprecation.

Application Surfaces

Surfaces put PyRIT in front of people. Keep them thin: they expose and present the library and own no domain logic.

Backend

Responsibility: Expose the library through a FastAPI REST API for the GUI and CLI.

The backend is an adapter, not a second library. It owns HTTP and process concerns: routes, request validation and limits, authentication, error mapping, background runs, and runtime lifecycle. Everything else belongs in the library.

Framework Plans:

Frontend

Responsibility: Provide CoPyRIT, the graphical interface for human-led red teaming, on top of the backend REST API. It’s built with TypeScript, React, Vite, and Fluent UI.

Framework Plans:

CLI

Responsibility: Provide command-line entry points. pyrit_scan and pyrit_shell are thin REST clients over the backend.

Conventions

These patterns cut across components. Use them instead of inventing a local variant.