diff --git a/doc/code/framework.md b/doc/code/framework.md index 1a27fe453c..bb3882240d 100644 --- a/doc/code/framework.md +++ b/doc/code/framework.md @@ -55,7 +55,7 @@ These decisions apply to every change. The [style guide](../contributing/3_style - **Give each responsibility one owner.** Put new code in the component that owns the responsibility, as described below. If nothing fits, raise it with the maintainers instead of stretching a component. - **Keep logic in the library.** The backend, CLI, and frontend only expose and present library behavior. Implement new behavior in the owning library package, with any shared types in `pyrit.models`, then use it from the surfaces. -- **Reuse and compose before adding.** Express new capability as a configuration of existing pieces: an attack technique instead of a new attack, a composite of scorers instead of a new scorer type, an existing model instead of a near-copy. Add a class only when composition can't express it. +- **Reuse and compose before adding.** Express new capability as a configuration of existing pieces: an attack technique instead of a new attack, a composite of scorers instead of a new scorer type, an existing model instead of a near-copy. Add a new kind of class only when composition can't express it. This limits new mechanisms, not the catalog: more converters and attack techniques mean a better user experience and more for operators and automation to select from, so a new named one is welcome even when existing ones could be stacked or configured to match it. The same holds, to a lesser degree, for scenarios and scorers. Build each on the closest existing piece instead of reimplementing its logic. - **Port the logic, not the structure.** When a feature comes from other work, such as an algorithm from a paper like Crescendo or a scenario from Garak, keep its logic, but break it into PyRIT's components and follow PyRIT's rules. A hard-coded judge, for example, becomes a scorer. If a part doesn't fit, that's a sign the owning component should generalize, not a reason to work around it. Cite sources in `doc/references.bib`. - **Be consistent, but do what's best.** Match the patterns in the code you change, so PyRIT reads as one codebase. Consistency never outranks doing what's best: when a better way exists, take it, and move existing uses to it in their own PR, not inside an unrelated change. - **Don't over-engineer.** Build what the change needs now, as simply as possible. Don't add options, layers, abstractions, or branches for hypothetical needs. Handle the cases that occur in practice, and reject the rest with a clear error. @@ -66,7 +66,7 @@ These decisions apply to every change. The [style guide](../contributing/3_style ## Security - **Trust operators with the data.** PyRIT is a red teaming tool, not a consumer app. Operators need everything a test produces: prompts, responses (including harmful content), errors, and scorer rationales. Don't redact, mask, or truncate what operators need; needless redaction breaks tests and causes bugs. A shortened preview is fine when the full value stays available. -- **Secure the real boundaries.** Never expose PyRIT's own credentials, such as API keys and tokens, in logs, errors, identifiers, or results; secrets that appear in target output are test evidence. In shared deployments, authenticate users, and keep server-level powers, such as changing configuration, reading the server's files, or running code on the server, behind explicit administrator or configuration control. Treat target output as data: escape it when rendering, and never run it as code outside a sandbox. +- **Secure the real boundaries.** Keep each boundary clear and enforce it the same way everywhere, so nothing fails by accident because checks are inconsistent. Never expose PyRIT's own credentials, such as API keys and tokens, in logs, errors, identifiers, or results; secrets that appear in target output are test evidence. In shared deployments, authenticate and trust all users: anyone may create shared targets, converters, and scorers that connect with the server's credentials, such as the team's managed identity. Reserve running code on the server for administrators as a soft boundary to keep the deployment working, not a defense against users. As a rule of thumb, prioritize keeping PyRIT usable for testing unusual situations over restricting what users can do. Treat target output as data: escape it when rendering, and never run it as code outside a sandbox. ## Docs @@ -192,7 +192,7 @@ Core components are pluggable bricks. Each one can be swapped, combined, or repl - Refactor the converter pipeline so partial and conditional conversion are more dynamic. Some of this works today, but it's limited. -**Contributing (difficulty low)**: The pattern is well-defined. Add conversions that help attacks. +**Contributing (difficulty low)**: The pattern is well-defined. Add conversions that help attacks. A named converter is welcome even when a stack of existing ones produces the same output; subclass or wrap them rather than copying their logic. ## [Targets](./targets/0_prompt_targets)