FEAT: Add ScenarioPreset

[hannahwestra25]

Description

First PR of the composite scan work. Design doc: Composite Scans in PyRIT.

Depends on #2956 — merge that first.

A scenario preset is a named, reusable, target-agnostic answer to what to test: a scenario plus its configuration. It excludes everything environment-specific — target, concurrency, retries, labels — which belongs to a launch, so one preset runs unchanged against dev, staging, and prod.

This PR covers the full vertical slice. It originally shipped the persistence layer alone; the API and UI were folded in so the storage contract is reviewed against something that exercises it.

Layer	Component	Responsibility
Model	ScenarioPreset	The model
	StoredPreset	A preset paired with the version of the document it came from
Storage	ScenarioPresetStorage	JSON persistence with optimistic concurrency
	FileDocumentStorage	Shared local-dir + Blob base: I/O, naming, versions, conditional writes
API	/api/scenario-presets	CRUD plus POST /{name}/resolve
	ScenarioPresetService	Validation against the live registry; preset → run request merge
UI	ScenarioPresetLibrary	Lists presets, surfaces issues, launches, deletes
	ScenarioPresetEditor	Creates and edits the scenario-owned fields
	LaunchPresetDialog	Restates what the preset pins, collects the launch-owned fields, starts the run

No built-in presets: RegisteredScenario already ships defaults for five of the seven preset fields, so a built-in would mostly restate them. Deferred to the PR that needs one.

Screenshots

Worth reviewing

• Fields are tri-state. None means "use the scenario default", distinct from an explicit equal value. Unknown fields are rejected, not dropped, so a misspelled key fails loudly.
• An unset field survives an unrelated edit. A scenario-owned field is emitted only if the preset already pinned it or the operator moved it off the scenario default, so fixing a typo in a description doesn't freeze every default the preset was tracking.
• Presets are held to the request limits a run is held to. ScenarioPreset reuses the annotated types from RunScenarioRequest, so an oversized preset fails at save rather than at launch.
• The version describes the document, not the preset. It hashes the bytes on disk, so hand-edits are caught. expected_version is separate: None creates, a token updates, and a client-supplied version never reaches storage.
• Name validation sits at the FileDocumentStorage base, so no document API can address a path outside its source. Listing applies the rule before reading and skips what it can't decode, so one bad file can't hide the rest.
• Atomicity and conditional writes solve different problems, so both are enforced. os.replace from a sibling temp file stops a reader seeing a half-written document; it does nothing to stop a second writer discarding the first's edit. Each backend keeps that comparison and the write inseparable: Blob creates use overwrite=False and updates send If-Match on the ETag just read; local writes hold an OS advisory lock across the whole read-compare-replace. A hand-edit outside the class is caught by the content hash instead.
• FileDocumentStorage is extracted, not duplicated. CustomInitializerStorage becomes a small subclass with an unchanged public API, so its existing tests are the regression check. Preset storage's separate sidecar lock was folded into the same base, leaving scenario_preset_storage.py a thin adapter.
• Unresolvable references are advisory, not fatal. A preset from another deployment stores and lists fine, shows what's missing, and has Launch disabled, rather than being rejected at save.
• Resolve happens server-side. POST /{name}/resolve merges the preset with the launch-owned fields into an ordinary RunScenarioRequest, so unset-vs-set-to-the-default has one implementation.
• Technique tokens have one grammar. pyrit/scenario/core/_technique_tokens.py backs both launch resolution and preset validation, so a converter-qualified token can't be valid at launch and unknown in the library.
• Scenario-owned configuration is shared, not duplicated. scenarioConfigForm, ScenarioTechniqueSelector, and ScenarioDatasetFields come out of ScenarioDetail, so the launch form and the preset editor build the same config from one place.
• Mutations require an admin; reads are open. Presets are data, not executable code like custom initializers, so there is no allow_ switch.

Tests and Documentation

• Backend storage — model, preset storage on both backends, and the shared base's listing, decode, and durability contracts through CustomInitializerStorage: tri-state round-trips, version conflicts, lost-update races on both backends, advisory-lock acquisition and reclamation, lock files never surfacing as documents, out-of-band edits and deletes, illegal names, unknown fields, malformed-file skipping, and the previous document surviving a failed write.
• Backend API — route authorization, 404/409/503 handling, advisory issue reporting, the resolve-time version precondition, and the preset → RunScenarioRequest merge.
• Frontend — library issue badges and a disabled Launch naming the missing reference, create vs. update, version-conflict and permission errors, the tri-state form round-trip, techniques with no checkbox surviving an unrelated edit, the launch dialog's default-vs-pinned summary, and route ranking that keeps /scanner/presets/new from shadowing a preset named new.

Validation: npm run lint and npx tsc --noEmit pass. jest src/components/Scenarios src/components/ScenarioPresets is green across 12 suites, pytest tests/unit/registry tests/unit/models is green, and the backend preset and lifecycle tests are green. The branch is merged current with main; full-suite coverage is left to CI.

No docs or notebook changes: the preset surface is reached from the scanner UI rather than a notebook, so JupyText was not run.

[Richard Lundeen (richlundeen)]

My biggest hesitation is that it is difficult to validate the design without seeing the complete preset workflow working together.

I like the overall design, but I would prefer to review the persistence contract alongside the CRUD, launch integration, and UI that consume it. Otherwise, we risk committing to storage and versioning decisions before we can validate them through a real user flow.

Could we combine the first three planned PRs into one PR, or keep them as a stacked set that lands together? The individual diffs can remain small, but we would be able to review and merge them as one complete, usable feature.

I'm flexible here, but I think it's a good approach. WDYT?

[Richard Lundeen (richlundeen)]

Can we separate persistence from this PR and address it as a shared framework capability? Scenario presets need it, but so do targets and other named registry configurations. I would prefer one design for what gets persisted, how references and credentials are handled, and how updates are versioned, rather than establishing a separate storage path for each component.

For this PR, could we keep the ScenarioPreset model and non-persistent runtime use—for example, presets supplied through code or initializers—and defer durable storage and the API/UI behavior that depends on it? That lets us settle the preset contract without also committing to a persistence architecture.

[hannahwestra25]

Can we separate persistence from this PR and address it as a shared framework capability? Scenario presets need it, but so do targets and other named registry configurations. I would prefer one design for what gets persisted, how references and credentials are handled, and how updates are versioned, rather than establishing a separate storage path for each component.

For this PR, could we keep the ScenarioPreset model and non-persistent runtime use—for example, presets supplied through code or initializers—and defer durable storage and the API/UI behavior that depends on

hmm agreed that targets and other instance-backed configs need a persistence design, and this PR shouldn't try to settle it. But I was treating presets as closer to initializers and the environment/config files, and followed that pattern deliberately: a preset is a configuration, not an object in its own right the way a target or converter is.

That split seems to be where the existing persistence boundary already falls. .pyrit_conf, .env files, and custom initializer scripts all persist today, each a named document carrying its own copy of the same sha256-version + expected_version + local-or-blob logic. Custom initializers are the closest analogue — created in the UI, written to disk or blob, admin-gated, reloaded at boot. Presets do the same thing with a strictly smaller blast radius: inert JSON validated against a model with extra="forbid", versus arbitrary Python that gets imported and executed at startup.

Targets and converters live in DefaultInstanceRegistry — in-memory, lost on restart. Persisting those means storing a construction recipe plus credentials, which is genuinely unsolved. Presets are target-agnostic, so they hold no secrets and contribute nothing to that design either way.

The resolving registry references that can go stale when a scenario or technique is renamed is a new concept. but that's more of a side effect of the storage decision

[Richard Lundeen (richlundeen)]

After considering the configuration-versus-runtime-instance distinction, I would revise my earlier suggestion to postpone preset persistence entirely.

General recommendation

Consolidate the document-storage mechanics, not the runtime objects. Preset documents, initializer scripts, configuration files, and future target construction recipes can share storage operations without sharing their models or loading behavior.

The shared layer should own local/Blob I/O, missing-document handling, opaque versions, and conditional updates with explicit concurrency guarantees. Typed adapters should own serialization and validation. Reference resolution, component construction, credentials, and API authorization should remain outside that layer. Environment-file protections and read-only source rules must remain intact when those services adopt shared storage.

An instance registry addresses named runtime registration and lookup; it does not itself solve persistence. I would not require presets to implement a component identity contract or introduce a second in-memory copy just to reuse an instance registry.

Recommendation for this PR

Keep preset persistence rather than make the feature live-instance-only. The existing FileDocumentStorage extraction, shared with custom initializers, is a useful starting point.

• Keep ScenarioPresetStorage as a thin preset-specific serialization/validation adapter.
• Put reusable version/conflict mechanics in the shared storage layer. Enforce the update guarantee: checking a hash and then writing unconditionally can still lose concurrent edits; atomic replacement only prevents partial documents.
• Defer migration of the other configuration services, target construction-recipe persistence, credential resolution, and broader registry changes to separate work.

The scope should be reliable configuration-document persistence now, with broader component persistence later. It should not require solving target reconstruction before presets can be saved.