Skip to content

DOC: Document XPIAManualProcessingWorkflow on the Workflows page #4499

Open

Description

@romanlutz

The Workflows page documents XPIAWorkflow and XPIATestWorkflow for cross-domain prompt injection (XPIA) testing. A third variant, XPIAManualProcessingWorkflow, is exported from pyrit.executor.workflow but is not mentioned anywhere in the docs.

It is the variant for when the system that processes the injected content cannot be driven from code: the workflow plants the attack, pauses, asks the operator to trigger the processing step by hand (for example by opening the document in the application under test), and then takes the output pasted into the console and scores it.

What to change

Add a section to doc/code/executor/5_workflow.py that covers:

  • When to choose it over XPIAWorkflow and XPIATestWorkflow.
  • What the operator sees and has to do at the pause.
  • A code example showing how to construct and run it (attack_setup_target and scorer are required).

The workflow waits for console input, so it cannot run when the notebook is executed. Show the example as a fenced code block inside a markdown cell, not as an executed cell.

Done when

  • The page describes all three XPIA workflow variants and when to use each.
  • The example matches the constructor's current signature.
  • The .py and .ipynb files match, and pre-commit passes.

Implementation notes

  • Doc pages under doc/code/ are jupytext pairs: a .py file and a matching .ipynb. Change both. doc/contributing/7_notebooks.md and .github/instructions/docs.instructions.md explain how.
  • Read the class and its unit tests first, and describe only what the code does today.
  • Keep the text short and concrete. Lead with when someone would use the class, then show the smallest example that works.
  • pre-commit runs the doc validation hooks; they must pass.

How to contribute

  • Claim it first. Before you start, comment on this issue to say you are taking it.
  • First comment wins. If yours is the first claim comment, go ahead and open a PR; you do not need to wait for a reply. If someone has already commented, this issue is taken, so please pick a different one.
  • Link this issue in your PR description.

Activity

  1. galiliya commented on Nov 21, 2026

    @galiliya

    I'll take this one. Since #4499 has no comments yet, I'll claim it here and open a PR.

    Quick plan: add a short section to doc/code/executor/5_workflow.py after the existing XPIA content, framing it as when-to-use (auto-driven target vs. test target vs. human-in-the-loop), with the manual example in a fenced code block inside a markdown cell so the notebook doesn't block on input(). Then regenerate the matching .ipynb via jupytext and run pre-commit so both stay in sync. I'll read xpia.py and its unit tests first and only describe current behavior, and link this issue in the PR.

    One thing to confirm: is pasting the operator output back into the console still the supported path for XPIAManualProcessingWorkflow, or should the docs steer people to a non-interactive scoring hook if one exists?

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    documentationImprovements or additions to documentationgood first issueGood for newcomershelp wantedExtra attention is needed

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions