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¶

add_results_arguments¶

add_results_arguments(parser: argparse.ArgumentParser) → None

Add the shared scenario-results selection flags to parser.

Registers --view, --attack-result-ids, and --limit in a scenario results group so that pyrit_scan (its scenario-results sub-parser) and pyrit_shell (build_scenario_results_parser) expose an identical results interface. Both surfaces take the scenario-result id as a positional, added by the caller.

--view defaults to None (not OVERVIEW) so callers can tell an explicit --view apart from an omitted one; resolve it with pyrit.cli._results.resolve_view.

build_dataset_request_fields¶

build_dataset_request_fields(args: dict[str, Any]) → dict[str, Any]

Build the same edit-only dataset request for scanner and shell.

Returns:

• dict[str, Any] — dict[str, Any]: Either the new request or legacy dataset fields.

Raises:

• ValueError — If new and deprecated flags are mixed.

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.

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).

The raw argv is first run through _translate_legacy_argv (the back-compat shim). Pass 1 then uses parse_known_args so scenario-specific flags (e.g. --max-turns 7) don’t error before we’ve fetched the scenario’s declared parameters. Unknown leftovers are stashed on the Namespace as _unknown_args, and the translated argv as _translated_args, for the run reparse.

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.

parse_dataset_limit¶

parse_dataset_limit(value: str) → int | Literal['all', 'default']

Parse a positive total limit, default, or all.

Returns:

• int | Literal['all', 'default'] — int | Literal[“all”, “default”]: The requested total limit.

Raises:

• ValueError — If the value is not a supported dataset limit.

parse_dataset_source¶

parse_dataset_source(value: str) → Any

Parse a named source with an optional source cap.

Returns:

• Any — Validated named source.

Raises:

• ValueError — If the token is malformed.

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, is_list, sensitive, multiline, and identity_conflicting (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). The live reference is excluded from serialization; reference_type exposes its component family, while type_name and is_list expose whether clients supply one name or a list of names.

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.

for_external_catalog¶

for_external_catalog() → Parameter

Describe this parameter in the form external callers send it.

A flat Collection or Sequence is described as a list, and a union as its first alternative in declaration order that external callers can send, so font_size: int | tuple[int, int] is described as int; Path | str keeps its own form. Other alternatives are still accepted and coercion is unchanged; only the catalog description changes, and registry metadata keeps the full annotation. A default the described form cannot hold is left out, so callers omit the value and the constructor default applies.

Returns:

• Parameter — This parameter, or a copy whose param_type is the external form.

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.

RunScenarioRequest¶

Bases: _DatasetRequestModel

Request body for starting a scenario run.

ScenarioRunSummary¶

Bases: BaseModel

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