title

Vulnerability Investigation Playbook

version

0.5.1

status

Pilot

maturity

exercising

exercise_scope

standard + planning; deep + planning; standard + remediation; deep + remediation

validation_summary

standard planning/remediation work well in recent bounded runs; more deep scenarios required

owner

Engineering

last_updated

2026-09-04

depends_on

../frameworks/investigation.md

../strategies/collaborative.md

../contracts/workflow_execution.md

../contracts/claims.md

../integrations/jira.md

../templates/work_record.md

../templates/implementation_plan.md

../templates/vulnerability_issue_run_prompt.md

Vulnerability Investigation

Turn a security finding into an evidence-backed reachability and risk decision, a minimal remediation plan, and a controlled implementation handoff.

This playbook extends the Engineering Work Framework with practices specific to security, dependency, static-analysis, secret-scanning, container, and infrastructure findings. The shared framework and execution contract define the common workflow, worker, evidence, approval, and handoff semantics.

Purpose

Determine whether a reported vulnerability is:

real;
present in the affected artifact or codebase;
reachable by attacker-controlled input or a relevant execution path;
exploitable in the actual environment;
relevant to the application or business; and
adequately addressed by an existing mitigation.

Then identify the smallest safe remediation supported by evidence.

When To Use

Use this playbook for:

Jira VULN-* tickets;
SAST findings;
SCA or dependency vulnerabilities;
secret-scanning findings;
container-image vulnerabilities;
infrastructure-as-code security findings;
reachability investigations; and
security regression investigations.

When Not To Use

Use another workflow when:

the work is unrelated to security;
an approved implementation plan already exists and only execution remains;
the task is a routine package upgrade with no security investigation; or
the issue is a broad active incident requiring incident-command procedures.

Required Inputs

normalized work item or ticket context;
affected repository, workspace, image, or infrastructure definition; and
scanner, advisory, dashboard, or report context when available.

Recommended Inputs

vulnerability dashboard and scanner report;
CVE, GHSA, advisory, or vendor identifier;
dependency tree, lockfiles, SBOM, or image manifest;
architecture and deployment documentation;
affected release, commit, image digest, or infrastructure revision;
existing investigation notes;
relevant tests or reproduction steps; and
related Jira tickets, pull requests, or releases.

Optional Supporting Artifacts

The workflow may consume exported scanner JSON, SARIF, SBOMs, lockfiles, dependency trees, screenshots, logs, stack traces, advisories, source maps, deployment metadata, and reproduction fixtures.

Treat every artifact as evidence with a source, timestamp, owner, repository or revision, and redaction status. Do not trust an attachment over current repository or runtime evidence without reconciliation. Missing information is recorded as Unknown, not assumed.

Evidence Source Precedence

Use evidence sources in this order:

the work-item URL and its directly linked details;
configured scanner, advisory, dashboard, repository, or optional Jira integrations;
current repository, dependency, artifact, deployment, and runtime evidence;
user-provided hints and local supporting artifacts.

The work item may identify the finding without containing every security detail. Follow linked sources when the configured integrations allow it, and reconcile their identifiers, severity, component, revision, and timestamps. Jira is required when it is the declared primary work-item source; otherwise it is optional enrichment and its absence does not invalidate scanner, advisory, repository, or runtime evidence. Treat user-provided context as supplemental and unverified until reconciliation is complete. If a source is unavailable, record the access gap and Unknown instead of asking the user to restate facts that cannot be verified.

Security Evidence Model

The evidence worker owns normalization of the reported finding. Downstream workers consume the normalized evidence artifact rather than repeating the same scanner or repository investigation unless they identify a specific discrepancy.

The normalized finding should record:

finding identifier and reporting source;
advisory, CVE, GHSA, rule, or scanner reference;
reported severity and affected package, path, image, or resource;
introduced and fixed versions when available;
scanner timestamp and report revision;
affected repository, artifact, release, commit, or image digest;
raw artifact references and redaction status; and
finding category, route, classification confidence, and excluded workers; and
unresolved questions and confidence.

Vulnerability Topology

The reporting source is not necessarily the affected runtime or ownership boundary. Record these roles explicitly:

Topology field	Meaning
`reporting_source`	Scanner, dashboard, Jira, advisory, or other origin of the finding
`affected_repository`	Repository containing the vulnerable code or dependency declaration
`deployed_artifact`	Release, image, package, or infrastructure revision that may be affected
`vulnerable_component`	Package, module, image layer, secret, rule, or resource involved
`dependency_path`	Dependency chain from the artifact to the vulnerable component
`reachable_entrypoint`	Code path, service, endpoint, job, or resource that can invoke it
`runtime_environment`	Environment, tenant, privilege, or deployment context
`owner`	Team responsible for remediation or risk acceptance

The initial topology is a hypothesis. Reconcile it with scanner data, repository history, dependency resolution, deployment evidence, runtime configuration, and tests.

Finding Classification and Route

Classify the finding immediately after evidence normalization. Classification is an evidence-backed routing decision, not a user-provided requirement. Record the category, confidence, evidence references, and any excluded route in the work record.

Category	Primary focus	Minimum investigation
`dependency`	Vulnerable package, lockfile, image layer, or transitive dependency	Confirm presence and fixed version, resolve the dependency path, assess whether the vulnerable functionality matters, then validate the smallest update, removal, or replacement.
`code`	Vulnerable logic, deprecated API, data exposure, authorization, or unsafe behavior	Trace the source-to-sink path, inspect related package dependencies, define the focused code change, and add regression/security validation.
`injection`	Variable interpolation, shell injection, SQL/command/template injection, or unsafe deserialization	Trace input to sink, verify parameterization or escaping, identify the smallest safe boundary fix, and add adversarial regression coverage.
`infrastructure`	Infrastructure-as-code, deployment, image, configuration, secret, or runtime permission	Reconcile declared and rendered configuration, affected artifact and environment, ownership, rollout, and rollback.
`mixed` / `unknown`	More than one category or insufficient evidence to classify safely	Use the full route, preserve competing hypotheses, and resolve the classification before implementation readiness.

The route is selected after classification. deep means stronger, route-appropriate analysis; it does not mean activating every worker when a worker has no meaningful responsibility for the finding. The Orchestrator must record why a deep worker was activated, made conditional, or excluded.

For an obvious dependency finding, prioritize package and dependency evidence before broad runtime topology. For code, injection, and infrastructure findings, focus first on the relevant source/configuration path and expand only when evidence shows a cross-repository or deployment boundary.

Bounded Dependency Route

Use the bounded route when one or more findings share a known repository, package, resolved dependency path, lockfile, fixed range, owner, and candidate change. Normalize the findings together, keep ticket-specific reachability and risk dispositions, and design one remediation change set. Repository Integration is unnecessary when the affected files, runtime inclusion, owner, and validation entry points are already known. Planning Review is unnecessary unless the recommendation is disputed, high impact, mixed/unknown, or changes more than the bounded dependency files. Missing deployed or scanner reruns become implementation-plan validation steps; they do not activate workers by themselves.

Routine dependency updates, upgrades, patches, and lockfile refreshes remain standard when the remediation change set is bounded, even when exploitability is unclear or an adjacent artifact requires a scope check. An adjacent artifact does not justify deep unless evidence brings it into the remediation scope. Use a deeper setting for the affected worker when needed; do not change the run profile.

For standard + planning, this route uses three delegated workers:

dependency-investigation (current_state_investigator) combines finding normalization, dependency tracing, and bounded reachability checks;
remediation-design (solution_architect) selects the minimal change and validation plan; and
handoff (documenter) creates the two compact durable artifacts after fan-in.

The Coordinator performs initialization directly; do not activate a separate initialize worker. Do not split evidence and reachability into separate workers, activate Repository Integration, or activate Planning Review unless new in-scope evidence invalidates this route. Search only the declared component root and affected dependency files; do not inventory the repository root or excluded components.

The pilot soft target is 10 minutes end to end: up to 7 minutes for investigation and design, 2 minutes for documentation, and 1 minute for final verification. After analytical fan-in, do not reopen discovery or search memory, history, or unrelated repositories unless a named discrepancy could change the plan. Crossing a target does not skip a required safety check; record the check and reason for continuing.

Default Execution

The default run uses:

Execution profile: standard;
Lifecycle: planning; and
Mode: investigation.

Planning collects evidence, establishes reachability, assesses risk, compares remediation options, and produces implementation_plan.md. It stops at ready_for_implementation and makes no source or external-system changes.

The remediation lifecycle continues through implementation, review, validation, stabilization, and handoff after explicit approval.

Use templates/vulnerability_issue_run_prompt.md as the canonical run-prompt format. The prompt selects scenario inputs, profile, and lifecycle; it does not redefine this playbook.

Execution Profiles and Lifecycle

The profile controls investigation depth and worker activation. The lifecycle controls how far the run may proceed.

Profile	Use when	Planning behavior
`standard`	Bounded finding, known repository, ordinary dependency or code-path uncertainty	Normalized evidence, reachability, risk, remediation design, and final documentation
`deep`	Cross-repository or artifact uncertainty, disputed reachability, high impact, complex dependency chain, secrets, container, or infrastructure risk	Route-appropriate investigation plus independent boundary analysis and review when the category, risk, or uncertainty justifies them

There is no separate triage profile. The requested profile is immutable for the run. A different profile requires a new explicit user request; uncertainty may increase one worker's effort without changing the run profile.

Lifecycle	Behavior
`planning`	Investigate, assess, design, and stop at `ready_for_implementation`; no source or external-system changes
`remediation`	Execute the approved plan, review, validate, stabilize, and hand off

Valid combinations are standard + planning, deep + planning, standard + remediation, and deep + remediation. A remediation lifecycle never bypasses approval, validation, fan-in, or external-write gates.

Continuation and Lifecycle Re-entry

The selected lifecycle is immutable for one run. Follow-up questions do not convert a planning run into remediation, and a planning conversation must not invoke a generic implementation workflow.

When implementation is requested after a planning handoff, the Orchestrator must perform an explicit remediation re-entry:

preserve the existing work record and implementation plan;
record explicit implementation approval;
start or record a new run with the same profile and lifecycle: remediation;
re-read this playbook, the work record, and the implementation plan;
record profile_status: requested for the remediation run;
perform initialization in the Coordinator and activate implement, review, and validate;
wait for every required result envelope and complete fan-in before closing the remediation stage; and
activate final handoff after delivery fan-in;
complete the shared worker-runtime closure barrier before closing the prior run or starting another lifecycle run; and
report the remediation run's lifecycle, worker activation, fan-in, and runtime-closure status.

If new evidence contradicts or expands the approved plan, reactivate the profile's required planning workers before implementation. If approval is missing, stop with state awaiting_input and reason approval_required. If remediation lifecycle or required worker activation is missing, stop with state blocked and reason remediation_not_activated.

Interrupted Profile and Fan-In Recovery

If a required worker stops, is unavailable, or its result envelope is missing, the run is incomplete. Continue with the canonical run prompt using Interrupted profile recovery:

preserve the same work record, profile, lifecycle, and completed artifacts;
record the completed and missing workers plus the recovery reason;
reuse completed scanner and repository evidence unless a specific discrepancy requires a rerun;
activate every incomplete required worker for the selected profile;
wait for all result envelopes and complete fan-in; and
report the recovered profile status and next gate.

The missing implementation approval blocks delivery workers only. It must not block the remaining planning workers required to complete diagnosis and fix design. If the required graph cannot start, stop as not_executed. If it starts but required activation or fan-in remains incomplete, stop as blocked; do not use a generic workflow or claim successful profile execution.

Worker Profiles

The worker graph reuses the framework's generic roles. Provider adapters select the concrete model, effort, tools, and runtime. The Coordinator performs initialization directly; never activate or delegate an initialize worker. Activate one final Documenter after analytical fan-in.

Worker	Role	Mode	Activation / dependency
`evidence`	`current_state_investigator`	investigation	Required; after Coordinator initialization
`reachability`	`dependency_analyst`	investigation	Required; after `evidence`
`repository-integration`	`repository_integrator`	investigation	Conditional after `evidence`; required when repository, artifact, deployment, ownership, or cross-repository uncertainty remains
`remediation-design`	`solution_architect`	investigation	After `reachability` and any required integration analysis
`planning-review`	`reviewer`	review	Conditional after design; required for high impact, mixed/unknown classification, disputed recommendation, or material residual risk
`implement`	`implementer`	delivery	Approval plus `remediation-design`
`review`	`reviewer`	review	After `implement`
`validate`	`tester`	review	After `review`
`handoff`	`documenter`	stabilization	Required once after applicable fan-in

For non-bounded standard + planning, the normal analytical set is evidence, reachability, remediation-design, and final handoff. Repository Integrator and Planning Reviewer are conditional.

The pilot soft target for other standard + planning routes is 15 minutes. Crossing it does not skip evidence, workers, or gates; record the elapsed time, active critical-path worker, remaining decision or check, and reason for continuing.

For deep + planning, the Orchestrator first classifies the finding and declares the route. Repository Integrator and Planning Reviewer are required when their activation criteria are met; they are not automatic for a clearly bounded package finding. The Orchestrator waits for every worker required by the declared route, collects terminal result envelopes, and completes fan-in before closing diagnosis or design.

For remediation, use the delivery sequence:

implement ↔ review → validate → handoff

For a bounded dependency remediation, initialization is Coordinator work, not a delegated worker. The pilot target is 6-8 minutes end to end: 1 minute for preflight, 1 minute for implementation, 1 minute for review, 3-4 minutes for validation, and 1 minute for the compact remediation handoff. Do not add investigation or initialization workers unless new evidence invalidates the approved plan.

This sequence is valid only inside an explicitly activated remediation run. The presence of an existing implementation_plan.md is not evidence that the remediation workers ran in the current run.

Do not start additional discovery workers after approval unless new evidence contradicts the finding, expands the affected boundary, or invalidates the approved plan.

Worker Results and Synchronization

Every worker returns the shared result envelope defined in the execution contract. Vulnerability-specific requirements are:

on the bounded dependency route, dependency-investigation owns both normalized evidence and bounded reachability;
evidence owns raw scanner, advisory, dashboard, or work-item evidence;
reachability owns dependency-chain and execution-path analysis;
repository-integration owns repository, artifact, release, deployment, and ownership-boundary reconciliation;
remediation-design owns security-risk interpretation and option selection;
downstream workers consume normalized artifacts instead of duplicating work;
the Documenter records every worker result, blocker, synchronization state, model, effort, usage, credits, and next consumer; and
active workers keep the workflow in_progress until their result envelopes are collected.

Copy CVE, advisory, scanner rule, and fingerprint identifiers exactly from their authoritative input. Verify exact identifier equality during fan-in; a shortened or reformatted identifier is a control failure.

When repository-integration is required, start it in parallel with reachability after evidence. Both consume the normalized evidence artifact and repeat scanner or repository discovery only for a recorded discrepancy.

The final handoff must distinguish requested, activated, and executed profile, profile_status, required-worker activation, fan-in status, and runtime-closure status.

Worker Effort Escalation

Escalate the affected worker to the provider adapter's deep setting when:

multiple repositories, images, services, or deployment environments are involved;
dependency resolution is indirect or disputed;
attacker-controlled reachability is unclear;
secrets, data exposure, privilege escalation, or high business impact is possible;
the finding affects a public contract or persistence behavior; or
rollback, compensating controls, or validation are non-trivial.

Do not choose high effort merely because the task involves code. Uncertainty, risk, and model capability determine the appropriate setting. Worker effort escalation does not activate the deep graph or change requested, activated, or executed profile.

Work Record and Implementation Plan

Initialize or recover the work record:

<execution-repository>/.thoughts/<WORK-ITEM-ID>/work_record.md

Do not create implementation_plan.md during initialization. Create it from templates/implementation_plan.md. Create it only after all planning workers required by the declared route have returned terminal result envelopes, fan-in is complete, and the workflow is ready for implementation. The plan is a design artifact, not authorization to change source code. The work record must link to it before the workflow reaches ready_for_implementation.

For the bounded dependency route, keep work_record.md and implementation_plan.md to the required evidence, decisions, change, validation, ownership, and explicit evaluation metrics; omit empty examples and sections that are not applicable. Reference evidence instead of duplicating it. Normal runs have no byte-count field or hard size gate.

If a plan cannot be created, the handoff must not use a vague next action. It must state implementation_plan: not_created, the blocking gate, the missing worker or evidence, the reason, and the exact recovery or user decision needed.

The plan must contain:

scope, affected artifact, revision, topology, and exclusions;
finding validation, root cause, reachability, and behavior/security contract;
actual risk, recommended severity, and residual uncertainty;
exact source, dependency, configuration, image, or infrastructure changes;
regression, security, dependency, image, CI, and operational validation;
ranked remediation options and rejected alternatives;
ordered implementation, review, validation, rollout, and rollback steps;
monitoring, risk acceptance, ownership, and completion criteria; and
explicit skipped, unavailable, and inconclusive checks.

Security-Specific Investigation

Validate Scanner Findings

Do not assume scanner output is correct. Determine what is reported, why it is reported, which component is affected, whether the finding is reproducible, and whether the report matches the current artifact or revision.

Analyze Reachability

A reported vulnerability is not necessarily exploitable. Determine:

whether the vulnerable package, rule, image layer, secret, or resource is actually present;
whether the vulnerable functionality is invoked;
whether attacker-controlled input can reach it;
whether required privilege or authentication conditions exist; and
whether existing mitigations block the relevant path.

Reachability must be demonstrated with repository, dependency, runtime, or test evidence.

Assess Actual Risk

Separate scanner severity from actual business risk. Consider exploit prerequisites, privileges, authentication, mitigations, data sensitivity, blast radius, operational impact, and affected environments. Recommended severity must reflect actual exposure, not only scanner severity.

Evaluate Remediation Options

Consider multiple approaches before recommending implementation:

No action, with justification.
Existing mitigation.
Configuration change.
Lockfile or dependency-resolution refresh.
Minimal dependency upgrade.
Parent dependency upgrade.
Library or component replacement.
Larger redesign.

Prefer the smallest safe remediation that adequately reduces risk.

When the final remediation is not clear, present at least two concrete options with tradeoffs and recommend one. When evidence supports one obvious minimal dependency action, do not invent artificial alternatives; record the primary action and the most relevant rejected alternative or no-action disposition.

Criterion	Description
Security improvement	Expected reduction in risk
Engineering effort	Implementation complexity
Regression risk	Potential impact on existing functionality
Blast radius	Scope of affected systems
Validation required	Testing and verification effort
Recommendation	Preferred / Acceptable / Not Recommended

Document why non-selected options were rejected.

Multiple Tickets

Maintain one work record and finding disposition per vulnerability ticket. Finding consolidation still requires the same root cause, dependency chain, vulnerable component, code path, and remediation.

Remediation consolidation is separate. Assign a shared change_set_id and create one implementation plan when tickets have the same affected files, intended changes, validation commands, owner, rollout, and rollback. Cross-link that plan from every ticket record even when their CVEs, rules, vulnerable functions, reachability, or risk dispositions differ. Create separate plans only when those remediation fields differ, and record the difference.

When consolidating, document tickets fully resolved, partially resolved, and remaining work.

Common Investigation Pitfalls

Avoid:

treating scanner output as ground truth;
equating package presence with exploitability;
expanding scope without evidence;
recommending upgrades before understanding reachability;
ignoring existing mitigations;
selecting the largest remediation instead of the smallest safe one; and
mixing facts, assumptions, hypotheses, and unknowns.

Execution Flow

Stage 0 — Initialize

The Orchestrator records the requested profile and lifecycle, creates or recovers the work record, and declares dependencies. It records profile_status: requested before spawning evidence workers. This is Coordinator work for every route and is not a delegated worker instance.

Use the prompt's declared Execution repository as the durable-artifact root. It must be the in-scope repository that owns the affected dependency artifact unless the user explicitly selects a separate record repository. The framework checkout is not the execution repository merely because it contains this playbook. Additional repositories must not receive the work record or worker artifacts.

First resolve that logical repository to the active execution checkout. When the runtime starts in a managed worktree of the declared repository, use the worktree for revision, branch, scope, source commands, and component paths. Keep durable artifacts under the prompt's declared execution-repository path; do not place them in the managed worktree. Do not change source operations back to the original checkout. Stop as blocked if Git identity cannot establish that the worktree and declared path are the same repository.

Stage 1 — Normalize Security Evidence

The evidence worker collects scanner, advisory, dashboard, work-item, and repository facts. It produces one normalized evidence artifact with source, timestamp, revision, redaction status, affected component, initial topology, finding category, classification confidence, and unknowns.

The worker must consume every supplied report, rule reference, payload, attachment, and repository artifact before requesting clarification. Record each input as consumed, unavailable, conflicting, or out of scope, and retain the original path when the normalized artifact does not preserve all details.

Stage 2 — Establish Reachability and Boundaries

The reachability worker traces dependency and execution paths, checks attacker-controlled inputs and mitigations, and records competing hypotheses. Activate repository-integration when the declared route or evidence requires artifact, repository, deployment, or ownership-boundary reconciliation.

Before returning needs_input or blocked, apply the shared Evidence-to-Hypothesis Gate. The result must identify the strongest supported security hypothesis, the smallest reachability or reproduction check it actually executed, and its result in checks_performed. Record unavailable checks in checks_remaining, and request them only when necessary for a safe conclusion. A scanner rule, dependency graph, source check, or repository test that can run locally must run before external clarification is requested.

Stage 3 — Assess Risk and Choose Remediation

The remediation-design worker consumes normalized evidence and reachability results. It separates scanner severity from actual risk, compares options, and produces the complete implementation-plan content. A required or conditional Planning Reviewer challenges the risk, scope, and recommendation.

The remediation-design result must preserve the consumed finding context and return confirmed facts, risk and reachability hypotheses, evidence references, confidence, checks_performed, checks_remaining, remediation options, recommendation, and a plain-language next action. Do not use clarification_required as a substitute for bounded package, code, rule, reachability, or configuration analysis.

Apply the shared planning-readiness rule. Remaining dependency, configuration, test, environment, operational, rollout, or validation work belongs in the plan when a feasible sequence exists; it is not a planning blocker by itself.

Stage 4 — Re-enter Remediation and Implement

This stage is entered only after the lifecycle re-entry rules and approval gate pass. This stage is valid only inside an explicitly activated remediation run. Execute only the approved implementation_plan.md. Do not change source, dependencies, configuration, images, infrastructure, or external ticket state during planning.

Stage 5 — Code Review and Validate

In-scope review findings return to implement and are re-reviewed before validation. Reopen planning only when evidence invalidates the risk conclusion or approved remediation boundary.

Before validation, the Tester records an environment preflight:

scanner and version available;
originating rule or scanner configuration available;
target revision and scan scope identified;
repository test runner and required dependencies available; and
required local services, fixtures, or credentials available when applicable.

The Coordinator passes resolved tool paths and versions as typed worker inputs. Downstream workers use those exact values; they must not retry a command with a known-missing default executable first.

The final security check must re-run the originating rule or equivalent scanner configuration against the candidate revision. For a Semgrep finding, preserve the exact rule ID, configuration, Semgrep version, revision, scope, command or integration used, finding count, result artifact, and timestamp. A broad scan must not silently replace the originating rule check.

Use the lowest validation level that can prove the claim, escalating when risk or the repository requires it:

Finding, advisory, and dependency-resolution confirmation.
Reachability, focused mitigation, or regression test.
Broader repository, integration, contract, image, or infrastructure test.
Originating-rule or equivalent security scan.
CI, deployment, or post-release verification.

For a bounded lockfile remediation, classify checks before running them:

required local proof: complete resolver diff, exact target version, frozen lock/tree/sync, and focused affected tests;
conditional local proof: image build or broader tests only when the affected package ships in that artifact or the approved plan requires them;
external closure proof: originating scanner reruns, deployed-artifact mapping, and runtime verification; and
informational: unrelated repository-wide lint, formatting, or type-check debt, which must not determine the bounded change result unless the diff affects those checks.

Do not call a failure pre-existing, legacy, or unrelated without baseline evidence. Without an unchanged-baseline comparison or cited verified evidence, say only that the failure appears unrelated to the bounded diff and that baseline comparison was not performed.

Record each level as pass, fail, skipped, unavailable, or inconclusive. unavailable and inconclusive are not passes.

If the originating scanner or rule cannot run, record the reason and any substitute evidence separately. Do not claim the vulnerability is resolved from unit-test success alone.

Stage 6 — Stabilize and Hand Off

Complete rollout, rollback, monitoring, ownership, risk acceptance, and follow-up requirements. Updating vulnerability status in Jira, dashboards, or scanner systems is a separate human-approved external action.

Gates

Gate	Required condition
Investigation ready	Finding, affected artifact, and source evidence are identified
Reachability ready	Dependency and execution-path conclusion is supported or explicitly blocked
Risk ready	Actual exposure, severity, mitigations, and residual risk are explicit
Implementation ready	Shared semantic readiness threshold and planning fan-in passed; plan exists
Validation ready	Review findings are resolved or accepted and checks are recorded
Handoff ready	Ownership, monitoring, follow-up, and next action are explicit

Success Criteria

The workflow succeeds when:

scanner or advisory evidence is recorded with provenance and redaction;
affected repository, artifact, revision, and ownership are reconciled;
reachability and exploitability are evidence-backed or explicitly blocked;
actual business risk and recommended severity are justified;
remediation options and rejected alternatives are documented;
finding category and route are recorded with evidence and confidence;
implementation_plan.md exists and is linked from work_record.md;
validation results are objective and preserved;
every worker has a summarized terminal result and synchronization status;
requested, activated, and executed profiles, including profile_status, are explicit;
residual risk, risk acceptance, blockers, and ownership are explicit; and
the work record identifies the next owner and action.

Required Handoff Output

The final handoff is ordered as follows:

Shared outcome summary: finding status, affected scope, reachability, actual risk, recommendation, implementation-plan path/status, validation, and next action. The next action must name the owner, location, and completion condition in plain language.
Profile, gate, and synchronization status: requested, activated, and executed profile, profile status, required-worker activation, fan-in status, and runtime-closure status.
Remaining risks, blockers, risk acceptance, ownership, and follow-up.

Use the shared canonical Human-Readable Handoff template. Detailed worker results remain in the work record.

The handoff must not imply that remediation or validation completed when the workflow stopped at an approval, unavailable-environment, or planning gate.

Terminal Outcomes

In addition to common contract outcomes, this playbook may close as:

real_vulnerability;
not_reachable;
false_positive;
mitigated_existing_control;
fixed_pending_release;
insufficient_evidence; or
deferred_to_incident_workflow.

Each outcome requires supporting evidence and a reason.

FilesExpand file tree

vulnerability_investigation.md

Latest commit

History