Define OpenPAKT Scenario Execution Guidance

[meisterware-admin]

Summary

Introduce a non-normative guidance document describing a recommended model for executing OpenPAKT security scenarios and generating findings from scenario outcomes.

The new document helps implementation authors understand how scenario execution can map to OpenPAKT findings, reports, and CI workflows without making scanner runtime behaviour part of the normative OpenPAKT v0.1 specification.

---

Problem Statement

OpenPAKT currently defines:

• report schema
• finding taxonomy
• severity model
• scenario format
• CI policy evaluation semantics

However, the documentation set does not yet explain how implementations may translate scenario execution results into OpenPAKT findings.

The overall flow is currently implied but not described:

Scenario → Scanner → Finding → Report → CI policy → Pass/Fail

Without implementation guidance, different tools may make different choices around:

• when a failed scenario should produce a finding
• how scenario identifiers should be attached to findings
• how one or more failed validations map to one or more findings
• how indeterminate execution results should be represented

This does not necessarily break OpenPAKT interoperability, but it can reduce consistency across implementations.

---

Proposed Change

Add a new non-normative guidance document:

guides/scenario-execution.md

Suggested title:

OpenPAKT — Scenario Execution Guidance

The document should describe a minimal recommended model for:

• evaluating scenario execution outcomes
• interpreting validation criteria
• generating findings from unsafe outcomes
• attaching scenario context to finding metadata
• relating scenario execution to report generation

---

Guidance Topics

Possible topics include:

Scenario execution outcomes

Recommended outcome categories such as:

• safe_behavior
• unsafe_behavior
• indeterminate

Suggested finding generation behaviour

Examples:

• unsafe outcomes will usually generate one or more findings
• safe outcomes will usually generate no findings
• indeterminate outcomes may be represented through metadata or implementation-specific reporting

Suggested scenario-to-finding mapping

Scenario field	Suggested finding field
scenario.id	finding.metadata.scenario_id
scenario.type	finding.type
validation failure context	finding.evidence
implementation severity policy	finding.severity

---

Why this is not a spec document

This proposal is intentionally non-normative.

It does not define OpenPAKT compliance requirements and does not attempt to standardize scanner internals.

Its purpose is to improve consistency and help reference implementations such as Detektor.

---

Compatibility Impact

Backward compatible.

This adds guidance only and does not change:

• schema fields
• taxonomy identifiers
• severity values
• scenario structure
• CI policy semantics

---

Example

Example scenario:

id: scenario-prompt-injection-001
type: prompt_injection
expected_behavior: safe_refusal

Example unsafe outcome:

unsafe_behavior

Possible resulting finding:

id: finding-001
type: prompt_injection
severity: high
component: agent.prompt
description: Agent followed malicious instructions embedded in user input.
metadata:
  scenario_id: scenario-prompt-injection-001