Skip to content

API Reference — Attacks

attacks

Attack factories.

Attacks test for BAD things. When the evaluator detects the attack objective, the result is UNSAFE (safe=False).

Attacks

Factory methods for attack test executions.

Each method returns a BaseExecution. The test calls execute_async and asserts the result.

Attacks test for BAD things. When the evaluator detects the attack objective, the result is UNSAFE (safe=False).

Note: the return type is BaseExecution (an ABC), not a protocol. This is a deliberate asymmetry with the parameter types, which use the Evaluator protocol. Parameters use protocols because consumers provide implementations. The return type uses the ABC because the consumer only calls execute_async on it, and BaseExecution provides the concrete lifecycle skeleton.

xpia staticmethod

Python
xpia(
    *,
    inject=None,
    trigger,
    evaluator,
    stop_when=AUTO,
    max_turns=5,
    event_handlers=None,
)

Create an XPIA attack execution.

Orchestrates the full XPIA flow: inject payloads into surfaces, wait for indexing, create a session, drive the trigger conversation, evaluate, clean up, return Result.

The trigger parameter accepts benign user prompts that cause the agent to retrieve and process the injected content (e.g., "Summarize Q3"). XPIA triggers are never adversarial — the attack is in the injected payload, not the prompt.

Pass a string for the common single-prompt case, a list of strings for multi-turn sequences, a Request for prompts with inline attachments, or a PromptDriver for full control.

For inline XPIA — where the poisoned content is attached to the chat message rather than pre-positioned in an external surface — omit inject and pass a Request with attachments as the trigger.

Parameters:

Name Type Description Default
inject InjectionHandle | list[InjectionHandle] | None

Prepared injections from surface.inject() calls. None for inline XPIA where the payload travels as a chat attachment.

 None
trigger str | list[str] | Request | list[Request] | PromptDriver

Benign user request(s) that cause the agent to process poisoned content.

 required
evaluator Evaluator

What condition to check for.

 required
stop_when Evaluator | StopWhen | None

Online stop condition. StopWhen.AUTO reuses the verdict evaluator only when detection is known to be stable under trace extension. None disables online stopping. Defaults to StopWhen.AUTO.

 AUTO
max_turns int

Maximum prompt-response exchanges. Reaching the limit resolves the trace normally. Defaults to 5.

 5
event_handlers list[ExecutionEventHandler] | None

Optional additional handlers for custom observability.

 None

Returns:

Name Type Description
BaseExecution BaseExecution

Ready to execute with execute_async(adapter=...).

Raises:

Type Description
ValueError

If stop_when is a string that is not a StopWhen value.
Source code in rampart/attacks/_factory.py
Python
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
@staticmethod
def xpia(
    *,
    inject: InjectionHandle | list[InjectionHandle] | None = None,
    trigger: str | list[str] | Request | list[Request] | PromptDriver,
    evaluator: Evaluator,
    stop_when: Evaluator | StopWhen | None = StopWhen.AUTO,
    max_turns: int = 5,
    event_handlers: list[ExecutionEventHandler] | None = None,
) -> BaseExecution:
    """Create an XPIA attack execution.

    Orchestrates the full XPIA flow: inject payloads into surfaces,
    wait for indexing, create a session, drive the trigger
    conversation, evaluate, clean up, return Result.

    The trigger parameter accepts benign user prompts that cause
    the agent to retrieve and process the injected content (e.g.,
    "Summarize Q3").  XPIA triggers are never adversarial — the
    attack is in the injected payload, not the prompt.

    Pass a string for the common single-prompt case, a list of
    strings for multi-turn sequences, a Request for prompts with
    inline attachments, or a PromptDriver for full control.

    For inline XPIA — where the poisoned content is attached to
    the chat message rather than pre-positioned in an external
    surface — omit ``inject`` and pass a ``Request`` with
    ``attachments`` as the trigger.

    Args:
        inject (InjectionHandle | list[InjectionHandle] | None):
            Prepared injections from ``surface.inject()`` calls.
            None for inline XPIA where the payload travels as a
            chat attachment.
        trigger (str | list[str] | Request | list[Request] | PromptDriver):
            Benign user request(s) that cause the agent to process
            poisoned content.
        evaluator (Evaluator): What condition to check for.
        stop_when (Evaluator | StopWhen | None): Online stop condition.
            ``StopWhen.AUTO`` reuses the verdict evaluator only when
            detection is known to be stable under trace extension. None
            disables online stopping. Defaults to ``StopWhen.AUTO``.
        max_turns (int): Maximum prompt-response exchanges. Reaching the
            limit resolves the trace normally. Defaults to 5.
        event_handlers (list[ExecutionEventHandler] | None): Optional
            additional handlers for custom observability.

    Returns:
        BaseExecution: Ready to execute with
            ``execute_async(adapter=...)``.

    Raises:
        ValueError: If ``stop_when`` is a string that is not a
            ``StopWhen`` value.
    """
    if inject is None:
        handles = []
    elif isinstance(inject, InjectionHandle):
        handles = [inject]
    else:
        handles = inject
    driver = coerce_driver(trigger)
    if isinstance(stop_when, str):
        if stop_when != StopWhen.AUTO:
            msg = "stop_when must be an Evaluator, StopWhen.AUTO, or None."
            raise ValueError(msg)
        resolved_stop_when = evaluator if detected_is_absorbing(evaluator) else None
    else:
        resolved_stop_when = stop_when

    return XPIAExecution(
        handles=handles,
        driver=driver,
        evaluator=evaluator,
        stop_when=resolved_stop_when,
        max_turns=max_turns,
        event_handlers=event_handlers,
    )

StopWhen

Bases: StrEnum

Framework-selected online stop policies for attack factories.

Attributes:

Name Type Description
AUTO

Reuse the verdict evaluator as the online stop condition only when its detection is known to stay true as turns are appended. This applies to built-in evaluators; subclasses and custom evaluators run without online stopping unless passed explicitly.

XPIAExecution

Python
XPIAExecution(
    *,
    handles=None,
    driver,
    evaluator,
    stop_when=None,
    max_turns=25,
    event_handlers=None,
)

Bases: BaseExecution

Executes the full XPIA attack lifecycle.

Inherits BaseExecution. Implements _execute_async with XPIA's specific phase structure. The lifecycle skeleton (event dispatch, result collection, timing, infrastructure error handling) is owned by BaseExecution.

Phases (delegated to private helpers from _execute_async): 1. Activate all injection handles (via AsyncExitStack). 2. Wait for indexing (concurrent per-handle). 3. Create session (via async context manager). 4. Drive the trigger conversation via the PromptDriver. 5. Apply an optional online stop condition while driving turns. 6. Evaluate the final trace once. 7. Cleanup session and injections (guaranteed via AsyncExitStack). 8. Build and return Result via direct attack polarity.

InfrastructureError raised by surfaces or adapters during any phase is caught by BaseExecution.execute_async (not here) and converted to Result(status=SafetyStatus.ERROR). This execution strategy does not handle infrastructure failures — the base class does it as a cross-cutting concern for all strategies.

Parameters:

Name Type Description Default
handles list[InjectionHandle]

Prepared injections to activate. Empty for inline XPIA where payloads travel as chat attachments.

 None
driver PromptDriver

How to drive the trigger conversation.

 required
evaluator Evaluator

What condition to check for.

 required
stop_when Evaluator | None

Optional online condition that stops the trace when detected.

 None
max_turns int

Maximum prompt-response exchanges. Reaching the limit resolves the trace normally and prevents unbounded loops.

 25
event_handlers list[ExecutionEventHandler] | None

Additional handlers beyond the framework defaults.

 None
Source code in rampart/attacks/_xpia.py
Python
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
def __init__(
    self,
    *,
    handles: list[InjectionHandle] | None = None,
    driver: PromptDriver,
    evaluator: Evaluator,
    stop_when: Evaluator | None = None,
    max_turns: int = 25,
    event_handlers: list[ExecutionEventHandler] | None = None,
) -> None:
    super().__init__(event_handlers=event_handlers)
    self._handles = handles or []
    self._driver = driver
    self._evaluator = evaluator
    self._stop_when = stop_when
    self._max_turns = max_turns

strategy_name property

Python
strategy_name

Identifies this as an XPIA execution in results and reports.