pyrit.cli.pyrit_scan

PyRIT CLI - Command-line interface for running security scenarios.

This module provides the main entry point for the pyrit_scan command. It is a thin REST client that talks to the PyRIT backend server over HTTP. No heavy pyrit imports — all operations go through the REST API.

Functions¶

build_parameters_from_api¶

build_parameters_from_api(api_params: list[Parameter]) → list[Parameter] | None

Return a scenario catalog’s supported_parameters as coercion-ready Parameter objects.

The REST client deserializes catalog payloads directly into Parameter, which reconstructs each parameter’s live param_type from its serialized display fields (type_name / choices / is_list). The parameters are therefore already coercion-ready, so the shell parser can apply per-element coercion and treat list parameters as multi_value without further mapping.

Returns:

• list[Parameter] | None — list[Parameter] | None: Parameter list when api_params is non-empty, else None.

collapse_dataset_filters¶

collapse_dataset_filters(tokens: list[tuple[str, str]]) → dict[str, list[str]]

Fold parsed KEY=VALUE dataset-filter tokens into list-valued filters, rejecting duplicates.

Repeating a key (e.g. harm_categories=cyber harm_categories=violence) would otherwise be silently collapsed by dict(...) to the last value, dropping earlier constraints. Since list-valued filters accept comma-separated values, a repeated key is almost certainly a mistake, so this fails loud instead. Each value is coerced into a list of tokens (comma splitting is CLI input parsing); the server-side request model validates the keys.

Returns:

• dict[str, list[str]] — dict[str, list[str]]: The collapsed, list-valued filter mapping.

Raises:

• ValueError — If any key appears more than once.

main¶

main(args: list[str] | None = None) → int

Start the PyRIT scanner CLI.

Returns:

• int — Exit code (0 for success, 1 for error).

parse_args¶

parse_args(args: list[str] | None = None) → Namespace

Parse command-line arguments (pass 1 — tolerant of scenario-declared flags).

Pass 1 uses parse_known_args so scenario-specific flags (e.g. --max-turns 7) don’t cause an error before we’ve had a chance to fetch the scenario’s declared parameters from the server. The unknown leftovers are stashed on the returned Namespace as _unknown_args so _reparse_with_scenario_params can detect truly unknown flags when no scenario was specified.

Returns:

• Namespace — Parsed command-line arguments.

parse_dataset_filter¶

parse_dataset_filter(arg: str) → tuple[str, str]

Parse a single KEY=VALUE dataset-filter token from the CLI.

Note: The arg parameter is positional (not keyword-only) so it can be used directly as an argparse type= callable and an _ArgSpec parser. This mirrors _parse_initializer_arg and is an intentional exception to the keyword-only style rule for argparse compatibility.

Returns:

• tuple[str, str] — tuple[str, str]: The (key, value) pair. The value keeps its raw string form so the server can coerce and validate it.

Raises:

• ValueError — If the token is not in KEY=VALUE form or the key is empty. Argparse converts this into a clean CLI error; the shell catches it directly.

validate_log_level_argparse¶

validate_log_level_argparse(value: Any) → int

Argparse-compatible wrapper around validate_log_level.

Adapts the keyword-only validator to argparse’s positional type= calling convention and converts ValueError to argparse.ArgumentTypeError.

Returns:

• int — Validated log level as a logging module constant.

Raises:

• argparse.ArgumentTypeError — If value is not a valid log level.

Parameter¶

Bases: BaseModel

Describes a parameter that a PyRIT component accepts.

This is the single JSON-serializable parameter descriptor reused across the registry, scenarios, the backend API, and the CLI. param_type carries the value’s live Python type and its allowed set (a Literal[...] or Enum is the allowed set) and drives coerce_value / validate; it is not serialized. Serialization instead projects the type into the display fields type_name, choices, and is_list (plus required from the REQUIRED_VALUE sentinel), so a consumer can rebuild a usable contract from the registry without the live type travelling on the wire.

reference, when set, marks the parameter as a registry reference: its value is supplied by name and resolved to a registered instance by the registry layer (Parameter itself never resolves references). It is also excluded from serialization.

coerce_value and validate are the only public behaviors; all coercion branching lives behind them so callers never touch a free function.

Methods:

coerce_value¶

coerce_value(raw_value: Any) → Any

Coerce raw_value to this parameter’s declared type.

An opaque or reference parameter passes its value through unchanged (by identity — the registry layer resolves a reference by name; an opaque value is a live object owned by the caller). Otherwise it branches by shape: None passes through (deep-copied), a list coerces per element, and a scalar form (including Literal/Enum) coerces and validates membership. Arbitrary defaulted types pass through unchanged.

Returns:

• Any — The coerced value (the raw value unchanged for opaque/reference/ arbitrary types, a deep copy for the None passthrough, a coerced list for list types, or a coerced scalar for scalar types).

Raises:

• ValueError — If the value cannot be coerced to a constrained scalar or list element type.

is_reference_to¶

is_reference_to(component_type: ComponentType) → bool

Whether this parameter is a registry reference to the given component family.

A reference parameter is supplied by name and resolved to a registered instance by the registry layer. This is the single source of truth for “does this parameter point at a TARGET / CONVERTER / SCORER”, so callers never re-derive it from reference internals.

Returns:

• bool — True when this parameter is a reference to component_type.

validate¶

validate() → None

Reject a declaration with an unsupported param_type.

Supported forms are a plain scalar, a constrained scalar (Literal/Enum), a list of any of those, a registry reference, an opaque passthrough, or None. An otherwise-unsupported type is tolerated only when the parameter declares a default (the builder simply does not supply it, and the value passes through unchanged).

Raises:

• ValueError — If param_type is unsupported and no default is declared.

RegisteredScenario¶

Bases: BaseModel

Summary of a registered scenario.

RunScenarioRequest¶

Bases: BaseModel

Request body for starting a scenario run.

ScenarioRunSummary¶

Bases: BaseModel

Response for a scenario run (status + result details).