@openai/codex-security 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (178) hide show
  1. package/LICENSE +201 -0
  2. package/README.md +306 -0
  3. package/_bundled_plugin/.app.json +20 -0
  4. package/_bundled_plugin/.codex-plugin/plugin.json +41 -0
  5. package/_bundled_plugin/.mcp.json +20 -0
  6. package/_bundled_plugin/assets/logo.png +0 -0
  7. package/_bundled_plugin/examples/completed-scan/coverage.json +22 -0
  8. package/_bundled_plugin/examples/completed-scan/findings.json +51 -0
  9. package/_bundled_plugin/examples/completed-scan/scan-manifest.json +43 -0
  10. package/_bundled_plugin/mcp/mcp-app.html.br +0 -0
  11. package/_bundled_plugin/mcp/server.mjs +24 -0
  12. package/_bundled_plugin/mcp/server.mjs.br.part-000 +0 -0
  13. package/_bundled_plugin/mcp/server.mjs.br.part-001 +0 -0
  14. package/_bundled_plugin/preflight/capability-profiles.toml +179 -0
  15. package/_bundled_plugin/references/config-preflight.md +115 -0
  16. package/_bundled_plugin/references/final-report.md +205 -0
  17. package/_bundled_plugin/references/finding-detail-fields.md +162 -0
  18. package/_bundled_plugin/references/sarif-adapter.md +26 -0
  19. package/_bundled_plugin/references/scan-artifacts.md +116 -0
  20. package/_bundled_plugin/references/scan-contract.md +164 -0
  21. package/_bundled_plugin/references/security-guidance.md +15 -0
  22. package/_bundled_plugin/references/shared-hard-rules.md +15 -0
  23. package/_bundled_plugin/references/static-finding-assessment.md +75 -0
  24. package/_bundled_plugin/schemas/coverage.schema.json +228 -0
  25. package/_bundled_plugin/schemas/findings.schema.json +359 -0
  26. package/_bundled_plugin/schemas/scan-manifest.schema.json +332 -0
  27. package/_bundled_plugin/scripts/config_preflight.py +901 -0
  28. package/_bundled_plugin/scripts/deep_scan_config.py +108 -0
  29. package/_bundled_plugin/scripts/deep_scan_workbench.py +1547 -0
  30. package/_bundled_plugin/scripts/filesystem_identity.py +30 -0
  31. package/_bundled_plugin/scripts/finalize_scan_contract.py +2208 -0
  32. package/_bundled_plugin/scripts/finding_preview.py +270 -0
  33. package/_bundled_plugin/scripts/generate_rank_input.py +1013 -0
  34. package/_bundled_plugin/scripts/normalize_candidates.py +320 -0
  35. package/_bundled_plugin/scripts/rank_preview.py +968 -0
  36. package/_bundled_plugin/scripts/report_projection.py +844 -0
  37. package/_bundled_plugin/scripts/resolve_security_md.py +158 -0
  38. package/_bundled_plugin/scripts/snapshot_sqlite.py +26 -0
  39. package/_bundled_plugin/scripts/validate_report_format.py +138 -0
  40. package/_bundled_plugin/scripts/validate_scan_contract.py +108 -0
  41. package/_bundled_plugin/scripts/validate_tracking_source.py +92 -0
  42. package/_bundled_plugin/scripts/windows_scan_local_files.py +612 -0
  43. package/_bundled_plugin/scripts/workbench/__init__.py +1 -0
  44. package/_bundled_plugin/scripts/workbench/handoff.py +238 -0
  45. package/_bundled_plugin/scripts/workbench_cli.py +325 -0
  46. package/_bundled_plugin/scripts/workbench_constants.py +81 -0
  47. package/_bundled_plugin/scripts/workbench_db.py +3728 -0
  48. package/_bundled_plugin/scripts/workbench_native_indexes.py +242 -0
  49. package/_bundled_plugin/scripts/workbench_progress.py +226 -0
  50. package/_bundled_plugin/scripts/workbench_remediation.py +125 -0
  51. package/_bundled_plugin/scripts/workbench_scan_history.py +829 -0
  52. package/_bundled_plugin/scripts/workbench_scan_start.py +149 -0
  53. package/_bundled_plugin/scripts/workbench_schema.py +714 -0
  54. package/_bundled_plugin/scripts/workbench_source_excerpt.py +99 -0
  55. package/_bundled_plugin/scripts/workbench_target.py +469 -0
  56. package/_bundled_plugin/scripts/workbench_target_state.py +63 -0
  57. package/_bundled_plugin/scripts/workbench_validation.py +294 -0
  58. package/_bundled_plugin/skills/attack-path-analysis/SKILL.md +117 -0
  59. package/_bundled_plugin/skills/attack-path-analysis/agents/openai.yaml +4 -0
  60. package/_bundled_plugin/skills/attack-path-analysis/references/attack-path-facts.md +76 -0
  61. package/_bundled_plugin/skills/attack-path-analysis/references/severity-policy.md +153 -0
  62. package/_bundled_plugin/skills/deep-security-scan/SKILL.md +166 -0
  63. package/_bundled_plugin/skills/deep-security-scan/agents/openai.yaml +4 -0
  64. package/_bundled_plugin/skills/define-security-policy/SKILL.md +93 -0
  65. package/_bundled_plugin/skills/define-security-policy/agents/openai.yaml +4 -0
  66. package/_bundled_plugin/skills/finding-discovery/SKILL.md +155 -0
  67. package/_bundled_plugin/skills/finding-discovery/agents/openai.yaml +4 -0
  68. package/_bundled_plugin/skills/fix-finding/SKILL.md +112 -0
  69. package/_bundled_plugin/skills/fix-finding/agents/openai.yaml +4 -0
  70. package/_bundled_plugin/skills/propose-security-hardening/SKILL.md +240 -0
  71. package/_bundled_plugin/skills/propose-security-hardening/agents/openai.yaml +4 -0
  72. package/_bundled_plugin/skills/propose-security-hardening/references/proposal-format.md +424 -0
  73. package/_bundled_plugin/skills/security-diff-scan/SKILL.md +167 -0
  74. package/_bundled_plugin/skills/security-diff-scan/agents/openai.yaml +4 -0
  75. package/_bundled_plugin/skills/security-scan/SKILL.md +42 -0
  76. package/_bundled_plugin/skills/security-scan/agents/openai.yaml +4 -0
  77. package/_bundled_plugin/skills/security-scan/references/repository-wide-scan.md +48 -0
  78. package/_bundled_plugin/skills/security-scan/references/scan-artifacts-and-ledger.md +85 -0
  79. package/_bundled_plugin/skills/threat-model/SKILL.md +59 -0
  80. package/_bundled_plugin/skills/threat-model/agents/openai.yaml +4 -0
  81. package/_bundled_plugin/skills/threat-model/references/threat-model-guidance.md +48 -0
  82. package/_bundled_plugin/skills/track-findings/SKILL.md +222 -0
  83. package/_bundled_plugin/skills/track-findings/agents/openai.yaml +6 -0
  84. package/_bundled_plugin/skills/track-findings/references/github-security-advisories.md +54 -0
  85. package/_bundled_plugin/skills/track-findings/references/jira.md +77 -0
  86. package/_bundled_plugin/skills/triage-finding/SKILL.md +342 -0
  87. package/_bundled_plugin/skills/triage-finding/agents/openai.yaml +4 -0
  88. package/_bundled_plugin/skills/triage-finding/references/github-rest-intake.md +168 -0
  89. package/_bundled_plugin/skills/triage-finding/references/ticket-intake.md +62 -0
  90. package/_bundled_plugin/skills/triage-finding/references/triage-result-contract.md +108 -0
  91. package/_bundled_plugin/skills/validation/SKILL.md +110 -0
  92. package/_bundled_plugin/skills/validation/agents/openai.yaml +4 -0
  93. package/_bundled_plugin/skills/validation/references/validation-guidance.md +122 -0
  94. package/_bundled_plugin/skills/vulnerability-writeup/SKILL.md +263 -0
  95. package/_bundled_plugin/skills/vulnerability-writeup/agents/openai.yaml +4 -0
  96. package/_bundled_plugin/skills/vulnerability-writeup/references/report-format.md +104 -0
  97. package/bin/codex-security.mjs +26 -0
  98. package/dist/api.d.ts +112 -0
  99. package/dist/api.d.ts.map +1 -0
  100. package/dist/api.js +1051 -0
  101. package/dist/api.js.map +1 -0
  102. package/dist/auth.d.ts +29 -0
  103. package/dist/auth.d.ts.map +1 -0
  104. package/dist/auth.js +246 -0
  105. package/dist/auth.js.map +1 -0
  106. package/dist/bulk-scan-discovery.d.ts +35 -0
  107. package/dist/bulk-scan-discovery.d.ts.map +1 -0
  108. package/dist/bulk-scan-discovery.js +217 -0
  109. package/dist/bulk-scan-discovery.js.map +1 -0
  110. package/dist/cli.d.ts +67 -0
  111. package/dist/cli.d.ts.map +1 -0
  112. package/dist/cli.js +2128 -0
  113. package/dist/cli.js.map +1 -0
  114. package/dist/config.d.ts +19 -0
  115. package/dist/config.d.ts.map +1 -0
  116. package/dist/config.js +199 -0
  117. package/dist/config.js.map +1 -0
  118. package/dist/contract.d.ts +21 -0
  119. package/dist/contract.d.ts.map +1 -0
  120. package/dist/contract.js +848 -0
  121. package/dist/contract.js.map +1 -0
  122. package/dist/cost.d.ts +30 -0
  123. package/dist/cost.d.ts.map +1 -0
  124. package/dist/cost.js +280 -0
  125. package/dist/cost.js.map +1 -0
  126. package/dist/errors.d.ts +38 -0
  127. package/dist/errors.d.ts.map +1 -0
  128. package/dist/errors.js +52 -0
  129. package/dist/errors.js.map +1 -0
  130. package/dist/index.d.ts +22 -0
  131. package/dist/index.d.ts.map +1 -0
  132. package/dist/index.js +11 -0
  133. package/dist/index.js.map +1 -0
  134. package/dist/knowledge-base.d.ts +7 -0
  135. package/dist/knowledge-base.d.ts.map +1 -0
  136. package/dist/knowledge-base.js +181 -0
  137. package/dist/knowledge-base.js.map +1 -0
  138. package/dist/models.d.ts +231 -0
  139. package/dist/models.d.ts.map +1 -0
  140. package/dist/models.js +3 -0
  141. package/dist/models.js.map +1 -0
  142. package/dist/multiscan.d.ts +30 -0
  143. package/dist/multiscan.d.ts.map +1 -0
  144. package/dist/multiscan.js +397 -0
  145. package/dist/multiscan.js.map +1 -0
  146. package/dist/result.d.ts +39 -0
  147. package/dist/result.d.ts.map +1 -0
  148. package/dist/result.js +71 -0
  149. package/dist/result.js.map +1 -0
  150. package/dist/runtime.d.ts +69 -0
  151. package/dist/runtime.d.ts.map +1 -0
  152. package/dist/runtime.js +997 -0
  153. package/dist/runtime.js.map +1 -0
  154. package/dist/scan-comparison.d.ts +42 -0
  155. package/dist/scan-comparison.d.ts.map +1 -0
  156. package/dist/scan-comparison.js +153 -0
  157. package/dist/scan-comparison.js.map +1 -0
  158. package/dist/scan-history-renderer.d.ts +13 -0
  159. package/dist/scan-history-renderer.d.ts.map +1 -0
  160. package/dist/scan-history-renderer.js +297 -0
  161. package/dist/scan-history-renderer.js.map +1 -0
  162. package/dist/targets.d.ts +39 -0
  163. package/dist/targets.d.ts.map +1 -0
  164. package/dist/targets.js +295 -0
  165. package/dist/targets.js.map +1 -0
  166. package/dist/trusted-executable.d.ts +6 -0
  167. package/dist/trusted-executable.d.ts.map +1 -0
  168. package/dist/trusted-executable.js +77 -0
  169. package/dist/trusted-executable.js.map +1 -0
  170. package/dist/version.d.ts +6 -0
  171. package/dist/version.d.ts.map +1 -0
  172. package/dist/version.js +42 -0
  173. package/dist/version.js.map +1 -0
  174. package/dist/worker-progress.d.ts +13 -0
  175. package/dist/worker-progress.d.ts.map +1 -0
  176. package/dist/worker-progress.js +113 -0
  177. package/dist/worker-progress.js.map +1 -0
  178. package/package.json +74 -0
@@ -0,0 +1,62 @@
1
+ # Jira and Linear Ticket Intake
2
+
3
+ Use this reference whenever `$triage-finding` imports Jira or Linear issues. Retrieve the requested ticket content before normalization. Never infer inaccessible ticket content from an identifier, title fragment, or repository code.
4
+
5
+ ## Source Retrieval
6
+
7
+ For Jira, use the Atlassian Rovo connector when it is available:
8
+
9
+ - Prefer structured JQL for repeatable imported collections, ordered by a stable field such as key or created date. Use natural-language search only to discover the cloud/site, project, issue family, or first matching key from a vague phrase. After discovery, switch to JQL or exact issue fetches.
10
+ - Jira text search tokenizes punctuation. If a hyphenated marker such as `KAN-PROMPTFOO-SYNTH` returns no rows, broaden to a stable token such as `PROMPTFOO`, then filter returned summaries for the exact family before triage.
11
+ - Fetch exact issue URLs or keys directly when the connector supports it. For a project family or saved query, use JQL and preserve the JQL string as source provenance.
12
+
13
+ For Linear, fetch exact issue URLs or identifiers directly. When the user supplies a team, project, or search phrase, use search results only to identify the intended issue set, then fetch every selected issue before normalization.
14
+
15
+ ## Linear Parent and Sub-Issue Selection
16
+
17
+ For an exact Linear issue, fetch the parent issue first. Then list its direct children with the connector's parent filter. Exhaust all pages of the direct-child listing before deciding whether children exist.
18
+
19
+ When the parent has direct children:
20
+
21
+ 1. Show the number of direct children and each child's identifier and title. This listing is selection metadata, not imported finding content.
22
+ 2. Ask whether to include that level before fetching any child's full content.
23
+ 3. If the user declines, do not fetch or normalize those children.
24
+ 4. If the user approves, check that the selected finding count remains within the result limit, then fetch the full content of every approved child.
25
+ 5. List direct children for each approved issue, exhausting pagination and grouping the next-level identifiers and titles by parent. If another level exists, repeat the confirmation at the next depth before fetching its full content.
26
+
27
+ Do not interpret approval for one level as approval for deeper descendants. If no children exist at a level, continue without another sub-issue question.
28
+
29
+ Classify the originally supplied parent separately from its children:
30
+
31
+ - Include the parent as a triage item when its title and body contain a clear independent vulnerability claim.
32
+ - Exclude it when it only organizes or summarizes the child findings.
33
+ - If the parent mixes collection context with a possible standalone claim and the classification is ambiguous, explain the ambiguity and ask whether to include the parent before normalization.
34
+
35
+ Preserve one result per selected issue. Use deterministic breadth-first tree order: include the parent first when selected, then each approved depth ordered by creation time with the issue identifier as the tie-breaker. Preserve source identifiers and parent relationships in references.
36
+
37
+ The `triage-finding/v0` result accepts at most 250 findings. Before fetching full content for an approved level, count the parent when selected plus all previously imported and newly approved issues. If the total would exceed 250, stop and report the count. Ask the user to narrow by depth, status, label, or a smaller parent. Do not truncate the issue set or split it into multiple result payloads automatically.
38
+
39
+ ## Connector Failure Handling
40
+
41
+ Classify a failed Jira or Linear read before deciding what to do:
42
+
43
+ - **Missing connector or authentication:** The connector tool is unavailable, the source is not connected, or authentication is missing or expired. Do not retry. State which source could not be accessed and ask the user to connect or reauthorize it. Also offer to continue if the user pastes the complete finding content.
44
+ - **Insufficient permission:** The connector is authenticated but reports forbidden, access denied, or an equivalent authorization error. Do not retry. Preserve the connector's safe error detail, ask the user to request access or use an account with access, and offer the paste-the-finding alternative.
45
+ - **Issue not found or inaccessible:** An exact identifier or URL returns no matching issue, or the connector cannot distinguish missing from hidden. Do not claim that the issue does not exist. Ask the user to verify the identifier and source workspace or provide the ticket content directly.
46
+ - **Transient connector failure:** A timeout, rate limit, temporary service error, or transport failure may recover without a configuration change. Retry the identical read once. Do not broaden the query or switch sources during the retry. If the identical retry fails, stop and report both the original and retry errors when they are safe to show.
47
+
48
+ After any unresolved retrieval failure, stop the intake workflow. Do not inspect the repository, normalize a finding, assign a verdict, or emit the `triage-finding/v0` contract. Give the recovery step that matches the failure class rather than a generic success-shaped response.
49
+
50
+ ## Normalization and Provenance
51
+
52
+ Normalize Jira and Linear vulnerability tickets as `source_type: "scanner_ticket"` unless the ticket body clearly represents `bug_bounty`, `advisory`, `cve`, or `codex_security_finding` input.
53
+
54
+ Preserve the issue key or identifier, URL, project, status, labels, components, priority, assignee, reporter, timestamps, issue type, and import query in `input_id`, `normalized_input.references`, and evidence or proof-gap text.
55
+
56
+ ## Read-Only Default
57
+
58
+ Default to read-only import and triage. Do not add comments, transition issues, close issues, assign owners, or change labels unless the user explicitly asks for writeback.
59
+
60
+ When writeback is requested, finish the static verdicts first. Summarize the planned issue mutations and keep mutation separate from evidence analysis.
61
+
62
+ For imported collections, the final summary must state the number of issues imported, the query or issue set, where the full result was rendered or saved, and whether the source system changed. The default status is: no Jira or Linear changes made.
@@ -0,0 +1,108 @@
1
+ # Triage Result Contract
2
+
3
+ Use this contract for `$triage-finding` first-pass output. The skill performs static, inline triage of supplied findings. It does not use a queue or deep triage mode.
4
+
5
+ ## Schema Fit
6
+
7
+ `../../../schemas/findings.schema.json` is not the normalization shape for triage inputs.
8
+
9
+ That schema is for completed Codex Security scan artifacts. It requires scan metadata, generated finding ids, occurrence ids, fingerprints, severity,
10
+ remediation, provenance, and locations. Triage inputs often arrive as incomplete claims from SARIF snippets, CVEs, advisories, scanner tickets, bug bounty reports, or pasted text. The normalization step should preserve those claims without inventing completed-scan fields.
11
+
12
+ If the user supplies a valid `codex-security.findings` artifact, use it as an input source and map its fields into this triage contract. Preserve `findingId`, `occurrenceId`, and `ruleId` as source identifiers; do not require new triage inputs to conform to the completed-scan schema.
13
+
14
+ ## Top-Level JSON
15
+
16
+ ```json
17
+ {
18
+ "schema_version": "triage-finding/v0",
19
+ "repository": {
20
+ "path": "/path/to/repo",
21
+ "revision": "optional git sha"
22
+ },
23
+ "findings": []
24
+ }
25
+ ```
26
+
27
+ ## Per-Finding JSON
28
+
29
+ Each entry in `findings` must use this shape:
30
+
31
+ ```json
32
+ {
33
+ "triage_item_id": "triage-001",
34
+ "input_id": "scanner-or-user-id",
35
+ "source_type": "sarif",
36
+ "title": "finding title",
37
+ "normalized_input": {
38
+ "vulnerable_component": "package, file, API, route, function, service, or unknown",
39
+ "claimed_source": "attacker-controlled input or unknown",
40
+ "claimed_sink": "sink or broken control or unknown",
41
+ "claimed_control": "missing or bypassed guard, sanitizer, auth check, or unknown",
42
+ "affected_version_or_path": "affected version, path, config, or unknown",
43
+ "preconditions": ["required condition"],
44
+ "impact": "claimed impact or unknown",
45
+ "references": ["source-provided reference"]
46
+ },
47
+ "verdict": "confirmed",
48
+ "confidence": "high",
49
+ "affected_locations": [
50
+ {
51
+ "label": "entrypoint",
52
+ "path": "relative/path",
53
+ "lines": "12-18",
54
+ "detail": "why this location matters"
55
+ }
56
+ ],
57
+ "reachable_path": ["step 1", "step 2"],
58
+ "boundary_assessment": {
59
+ "product_surface": "hosted service, CLI, library API, local developer UI, MCP/tooling, example/demo, test/fixture, docs, generated, vendored, or unknown",
60
+ "source_trust": "untrusted, trusted_operator, trusted_developer_config, local_only, or unknown",
61
+ "boundary_crossed": true,
62
+ "policy_basis": "SECURITY.md, package/deploy evidence, product docs, code comments, or unknown"
63
+ },
64
+ "exploitability_stack_rank": {
65
+ "rank_queue": "confirmed",
66
+ "rank": 1,
67
+ "rationale": "why this finding is more or less exploitable than other findings with the same verdict",
68
+ "drivers": ["attacker reachability", "privilege required", "preconditions", "source-to-sink control", "guard strength"]
69
+ },
70
+ "evidence": ["static evidence observed"],
71
+ "counterevidence": ["static evidence that weakens or defeats the claim"],
72
+ "proof_gaps": ["missing evidence or reason for human review"],
73
+ "recommended_next_step": "fix-finding",
74
+ "fix_finding_handoff": "prompt-ready summary for confirmed findings"
75
+ }
76
+ ```
77
+
78
+ Required source type values:
79
+
80
+ - `sarif`
81
+ - `cve`
82
+ - `advisory`
83
+ - `scanner_ticket`
84
+ - `bug_bounty`
85
+ - `codex_security_finding`
86
+ - `freeform`
87
+ - `unknown`
88
+
89
+ Allowed verdicts:
90
+
91
+ - `confirmed`
92
+ - `not_actionable`
93
+ - `needs_review`
94
+
95
+ Allowed confidence values:
96
+
97
+ - `high`
98
+ - `medium`
99
+ - `low`
100
+
101
+ `boundary_assessment` records whether the source crosses a supported product security boundary, not just whether dataflow reaches a sink. Use `unknown`
102
+ strings and `null` for `boundary_crossed` when the surface or policy is unclear;
103
+ prefer `needs_review` for unclear boundary cases.
104
+
105
+ `exploitability_stack_rank` records priority within the result set. Use separate queues for `confirmed` and `needs_review`. Assign unique positive integer ranks contiguously from `1` inside each queue. Rank `1` is the most exploitable finding in its queue; use `rank_queue` rather than the number alone to identify the queue. For `not_actionable`, set `rank_queue` and `rank` to `null`, use an empty `drivers`
106
+ array, and set `rationale` to a short explanation such as `not actionable`.
107
+
108
+ Use empty arrays for unavailable optional evidence lists. Use `null` for `fix_finding_handoff` unless the verdict is `confirmed`.
@@ -0,0 +1,110 @@
1
+ ---
2
+ name: validation
3
+ description: Use when Codex is already in the validation phase of a security scan or the user explicitly asks to determine whether one or more candidate security findings are valid. Do not use as the primary trigger for full PR, commit, branch, patch, or repository scans.
4
+ ---
5
+
6
+ # Security Validation
7
+
8
+ ## Objective
9
+
10
+ Take candidate findings from discovery and produce the strongest evidence-backed validation assessment you can. Prefer targeted, non-interactive reproduction or falsification when it is feasible and proportionate, but use focused code tracing when dynamic execution is blocked by missing services, unavailable infrastructure, or excessive setup relative to the candidate and scan scope.
11
+
12
+ ## Artifact Resolution
13
+
14
+ The path references in this skill are the default locations for this phase.
15
+ If the user explicitly provides a different path for a required input or output, use the user-provided path instead of the corresponding default path referenced in this skill.
16
+ If a required input is still missing, stop and ask the user for it before continuing.
17
+ Use the shared scan artifact path conventions in `../../references/scan-artifacts.md`.
18
+
19
+ ### Compact Standard-Scan Mode
20
+
21
+ When `$security-scan` explicitly invokes this skill in compact standard-scan mode, use `<discovery_dir>/candidate_ledger.jsonl` as both the candidate input and the phase-closure artifact. Apply the validation method and evidence rules in this skill to the full candidate set in one invocation. Add one nested `validation` record to every row, using the compact record shape in `../../references/scan-artifacts.md`, while preserving every discovery field and row order.
22
+
23
+ In this mode, the nested record replaces the per-finding validation report, receipt, and closure table. Rewrite the ledger atomically. Do not feed the enriched ledger back through the discovery normalizer. Create `<discovery_dir>/validation_artifacts/<candidate_id>/` only when validation produces an actual PoC, crafted input, or log, and reference it from the nested record. All validation reasoning, instance-preservation, evidence, and confidence requirements still apply; only the artifact packaging changes.
24
+
25
+ ## Workflow
26
+
27
+ 1. Before starting, create a detailed validation rubric with up to five criteria for the candidate.
28
+ 2. For each candidate finding, identify the claimed attacker input, vulnerable sink, and preconditions.
29
+ 3. Choose the validation path using the strongest realistic method available:
30
+ - crash: for crash, memory-corruption, parser-confusion, or denial-of-service candidates, attempt to compile a debug variant and produce a crashing PoC when the project can be built with bounded effort.
31
+ - valgrind or ASan: if a memory-safety or crash candidate does not immediately reproduce and the build supports it, attempt valgrind and/or ASan.
32
+ - debugger: if runtime execution is available but the chain is unclear, attempt a non-interactive debugger trace with gdb/lldb that shows the source-to-sink path.
33
+ - unit or integration test: if the vulnerable path is covered by an existing test harness, add or adapt the smallest focused test that exercises the vulnerable code and asserts the vulnerable behavior.
34
+ - realistic interface reproduction: if the code exposes a real user-reachable interface such as HTTP, CLI, file parser, RPC, message queue, plugin hook, or package API, attempt a minimal end-to-end reproduction through that interface using crafted input that reaches the suspected sink.
35
+ - code understanding: if dynamic reproduction is not feasible or proportionate after bounded attempts, follow the static finding assessment reference in `../../references/static-finding-assessment.md` to trace source, control, sink, reachability, boundary evidence, counterevidence, and proof gaps.
36
+ - large internal repository mode: for repository-wide or scoped-path scans where runtime reproduction requires unavailable internal services, secrets, cloud accounts, service meshes, or local production data, use the static finding assessment reference plus existing tests and deploy/config evidence once the candidate has a complete source/control/sink/impact tuple. Missing internal runtime setup is not suppression evidence.
37
+ 4. For non-compiled stacks, attempt to generate PoCs or targeted commands that exercise the vulnerable path and trigger the vulnerability.
38
+ 5. For compiled stacks, prefer dynamic validation when it is feasible with bounded setup: build a debug variant or targeted test harness when available, reproduce the vulnerable behavior with a small PoC, then use valgrind, ASan, or a non-interactive debugger trace when those tools materially improve confidence.
39
+ 6. Save any PoC files, inputs, or logs under the validation artifacts path for the active mode from `../../references/scan-artifacts.md`.
40
+ 7. If validation is not feasible, document what was tried, what remains uncertain, and the exact proof gap.
41
+ 8. Return a clear validation assessment per finding grounded in the evidence, proof gaps, and remaining uncertainty.
42
+ 9. In compact standard-scan mode, add the nested `validation` record to every candidate row and atomically replace the ledger.
43
+ 10. Outside compact standard-scan mode, save that finding's visible validation report and append one validation receipt per candidate id at the default paths from `../../references/scan-artifacts.md`. The receipt must record the validation method, evidence or exact proof gap, disposition, and validation artifact/report reference for that candidate finding.
44
+
45
+ ## Usage Guidance
46
+
47
+ - Prefer short, bounded commands (git, grep -nI within changed dirs, build/test runners, minimal PoCs).
48
+ - Avoid interactive editors (vi), long-running repo-wide scans, and network access unless essential.
49
+ - If you need to use debuggers, invoke them non-interactively (gdb: "-q -batch -ex run -ex bt -ex quit"; lldb: "-b -o run -o bt -o quit").
50
+ - When creating PoCs to validate the vulnerability, you should attempt to trigger them against the actual application/library directly. Ideally this shows how an attacker would trigger the bug.
51
+
52
+ ## Validation Guidance
53
+
54
+ Follow the instance-preserving validation rules, validation checklist, and confidence guidance in `references/validation-guidance.md`.
55
+ When validation falls back to static code understanding, or when static evidence is proportionate for large internal repositories, use the shared source/control/sink, boundary, counterevidence, and proof-gap guidance in `../../references/static-finding-assessment.md`.
56
+
57
+ ## Output Contract
58
+
59
+ In compact standard-scan mode, use the nested record defined in `../../references/scan-artifacts.md`. Every input row must receive exactly one validation disposition. The record is the closure table for this mode; do not also create a narrative report or receipt.
60
+
61
+ Outside compact standard-scan mode, use the following report contract.
62
+
63
+ For each candidate finding, include:
64
+
65
+ - finding title
66
+ - candidate id, instance key, and ledger row id when provided
67
+ - root-control file:line and affected-location labels from discovery when provided
68
+ - advisory/source reference and seed anchor file:line when provided, especially when distinct from the root-control line
69
+ - confidence level
70
+ - validation method used or recommended
71
+ - rubric checklist with `- [x]` or `- [ ]` items
72
+ - evidence observed
73
+ - concise notes on what was tested
74
+ - remaining uncertainty
75
+ - minimal next step if more proof is needed
76
+ - artifact paths when validation files or logs were created
77
+ - enough detail that a later reader can tell whether the finding survived validation without relying on a separate status label
78
+
79
+ For repository-wide and scoped-path scans, also include a validation closure table with columns:
80
+
81
+ - ledger row id
82
+ - instance key
83
+ - advisory/source reference when available
84
+ - seed anchor file:line when distinct from the root-control
85
+ - root-control file:line
86
+ - entrypoint/source
87
+ - sink/control
88
+ - disposition: `reportable`, `suppressed`, `not_applicable`, or `deferred`
89
+ - counterevidence or proof gap
90
+ - survives: `yes`, `no`, or `uncertain`
91
+
92
+ ## Hard Rules
93
+
94
+ - Do not imply validation happened when it did not.
95
+ - Do not leave candidate coverage implicit. In compact standard-scan mode, every candidate must receive a nested `validation` record. In other modes, every candidate that enters validation must leave a validation receipt in its candidate-ledger path from `../../references/scan-artifacts.md`, even when the result is suppressed, uncertain, or deferred.
96
+ - Prefer realistic local reproduction paths over contrived setups.
97
+ - If a finding depends on missing product assumptions, state the question clearly instead of fabricating the answer.
98
+ - Keep commands short, bounded, and non-interactive.
99
+ - Use stronger validation methods such as crashing PoCs, valgrind, ASan, debugger traces, focused tests, or realistic interface reproduction before falling back to code understanding when the stack and scan scope make that feasible.
100
+ - Calibrate confidence from the validation method and evidence, not from how dangerous the bug class sounds.
101
+ - Keep validation artifacts and phase output in the paths for the active mode from `../../references/scan-artifacts.md` so the full scan bundle lives together. Compact standard scans do not create per-finding validation reports.
102
+ - Make a serious, bounded effort to get runtime validation working when it would materially change reportability, confidence, or severity. Consult repository guidance such as `AGENTS.md`, `README.md`, setup docs, test docs, build files, and package-manager metadata to identify the required dependencies, generated files, services, and setup steps.
103
+ - For scans that should not modify the target tree, use a disposable copy or generated-artifact directory under the validation artifacts path for the active mode for builds, generated clients, patched test harnesses, and PoC files. A no-edit target rule does not forbid output-only build copies when they are needed to validate the original code.
104
+ - For repository-wide and scoped-path scans outside compact standard-scan mode, update each affected finding's validation report and closure table as each reportable, suppressed, not_applicable, or deferred row is decided. In compact standard-scan mode, atomically update the shared ledger after deciding all rows. Do not leave validated rows only in transient notes, terminal logs, or validation artifacts; later phases must be able to reconstruct every disposition from the durable phase output.
105
+ - For large repository-wide scans, keep setup/build/debug effort proportionate to the candidate and the remaining high-impact coverage ledger. Do not spend the review budget trying to fully reproduce one internal service when static trace, existing tests, and deploy/config evidence are enough to validate or suppress the candidate.
106
+ - In repository-wide and scoped-path validation, once one candidate in a repeated high-impact pattern has a strong proof tuple, switch to sibling candidates from the coverage ledger and validate each by checking the same source, closest control, sink, and impact. Only continue deeper runtime work when it would materially change reportability, severity, or confidence.
107
+ - If a repository-wide shard has a promoted same-family finding plus unresolved seeded or root-control rows, close those sibling rows next as reportable, suppressed, or deferred before replacing the review with a more dramatic neighboring finding. Representative proof improves confidence, but it does not close sibling root controls without exact counterevidence.
108
+ - If the project or code does not compile/build, diagnose the failure enough to know whether a targeted build, existing test, package API harness, or disposable validation copy can still exercise the original code. Prefer validating the original target over a separate reimplementation.
109
+ - Do not treat setup errors, compilation errors, or missing dependencies as immediate counterevidence. Record what blocked runtime proof, then use static trace plus existing tests/config/deploy evidence when setup becomes disproportionate.
110
+ - Do not abandon a build, test, or validation command just because it takes time when there is output, resource usage, generated artifacts, or other evidence of progress and no hard evidence of failure. If a long-running command appears inconclusive, check process status, recent logs, output file timestamps, resource usage, or test runner status before stopping or weakening validation.
@@ -0,0 +1,4 @@
1
+ interface:
2
+ display_name: "Validation"
3
+ short_description: "Validate a security finding"
4
+ default_prompt: "Use $validation to determine whether a given security finding is valid."
@@ -0,0 +1,122 @@
1
+ # Validation Guidance
2
+
3
+ Use this guidance when validating candidate security findings.
4
+
5
+ ## Instance-Preserving Validation
6
+
7
+ Validation does not choose whether the scan is diff-scoped or repository-wide. Use the scope and candidate set provided by the user, discovery report, or top-level security scan workflow. When validation is invoked directly for one named bug, validate that bug only unless the user explicitly provides multiple instances or asks for sibling expansion.
8
+
9
+ When validation is part of a top-level repository-wide security scan, treat discovery notes, coverage ledgers, and repeated source/sink/control patterns as validation input even if they are not yet numbered as final findings. The ledger is a coverage artifact: preserve rows that are not_applicable, suppressed, deferred, or reportable, and continue bounded high-impact sibling checks needed to complete that provided ledger. This is preserving repository-wide scan scope, not independently expanding a standalone validation request.
10
+
11
+ For large repository-wide scans, validation should preserve coverage as well as proof depth. Once a candidate has a complete source, closest control, sink, and impact tuple, prefer static trace plus existing tests and deploy/config evidence over lengthy environment bring-up when runtime reproduction needs unavailable internal services, secrets, service meshes, cloud accounts, or production data. Missing runtime setup is a proof-gap note, not counterevidence and not a suppression reason.
12
+
13
+ If discovery, user scope, or an advisory/tag seed names a specific package, class family, or root-control family, validation must close that exact row. A same-family finding in a neighboring route, parser, deserializer, or auth flow can be used as supporting evidence, but it is not counterevidence for the seeded row. If the seeded row survives, preserve its exact root-control file:line into attack-path analysis and final-report inputs.
14
+
15
+ Advisory-derived candidate files, functions, or hunks are not findings by themselves, but they are validation obligations for advisory-led repository-wide scans. Validate them against the checked-out local code, then close each exact seed row as `reportable`, `suppressed`, `not_applicable`, or `deferred` with local evidence. If the seed file was opened only during search, still give it an explicit closure row rather than leaving it only in logs.
16
+
17
+ When the checked-out code still contains a seeded construct, keep that seed row alive until validation decides its local proof tuple. Mark it `reportable` only when local repository evidence independently supports the same source, broken control, sink or security impact, and realistic preconditions; otherwise mark it `deferred` or `suppressed` with the exact missing proof or counterevidence. A stricter deployment assumption, missing downstream application configuration, or a neighboring stronger finding is a precondition or proof gap to state, not counterevidence by itself.
18
+
19
+ When a high-impact candidate is blocked only by a missing downstream consumer, workflow caller, policy exception, or artifact provenance fact, run one bounded adjacency pass over the most likely evidence sources before suppressing it: generated clients/specs, workflow callers, deploy/policy config, storage or ACL definitions, and package importers. If that pass still leaves the proof gap, keep the row `deferred` rather than treating the gap as counterevidence.
20
+
21
+ When the input contains multiple candidate instances, preserve that instance inventory:
22
+
23
+ - validate each candidate instance independently enough to decide whether that exact file/line should survive
24
+ - do not collapse multiple candidate instances into one validated finding solely because they share a vulnerability family
25
+ - for repeated instances provided by discovery or the security scan workflow, validate a representative exploit path once when feasible, then analytically validate each sibling instance by checking the same proof tuple: attacker-controlled source, missing or incomplete closest control, dangerous sink, and impact
26
+ - for repeated vulnerable templates, query builders, parser operations, auth/object endpoints, or shared-helper callers, preserve each independently vulnerable file and sink/control line as a surviving instance when the proof tuple applies. Grouping is acceptable for readability only after every affected instance has its own surviving finding entry or explicit suppressed/deferred row.
27
+ - if discovery hands validation a broad family candidate with multiple concrete sink, parser, helper, API-mode, or protected-action lines, expand it into child closure rows before deciding survival. One representative PoC may support the family, but each child still needs its own file/line, source or protected boundary, closest control, sink or action, disposition, and counterevidence.
28
+ - when one route or helper exposes multiple same-family operations such as `execute`/`executemany`/`executescript`, `pickle.load`/`pickle.loads`/`yaml.load`/`yaml.load_all`, separate path/file helpers, insert/select/delete/update query builders, or unauthenticated create/delete/reset/admin/job actions, validate or suppress each independently triggerable operation rather than carrying only one representative row.
29
+ - treat shared or generated wrappers as reachability evidence during validation. Do not let a proved wrapper path replace the child sink/control/protected-action rows that determine whether each concrete instance survives.
30
+ - after a repeated high-impact pattern has one strong proof tuple, stop deepening that one proof unless extra runtime work would materially change reportability, severity, or confidence. Spend the next validation effort on sibling ledger rows and suppress only with exact per-instance counterevidence.
31
+ - when a sibling is safe, suppress that exact instance with the specific control that makes it safe
32
+ - keep a table of `candidate id`, `file:line`, `family`, `validation method`, `closest control`, `survives`, and `confidence`
33
+ - prefer exact source/sink line evidence over broad prose, because downstream validation, attack-path analysis, and final report assembly depend on precise affected locations
34
+ - for wrapper-to-shared-sink findings, validate reachability through the wrapper while preserving the underlying parser, deserializer, path/archive, expression, or auth/authz sink/control line as an affected location when that line implements the broken security behavior
35
+ - for parser, deserializer, and object-construction findings, validate the concrete codec, converter, deserializer, resolver, or container handler that performs recursive parsing, type resolution, conversion, class filtering, or object construction. A broad parser/config proof does not close a concrete registered handler unless the handler's own root-control line is included or exactly suppressed.
36
+ - for file-format object-model helper rows, first decide whether malformed or adversarial input plausibly reaches the helper and whether the missing type, size, shape, recursion, numeric, or conversion guard creates crash, denial-of-service, parser-confusion, authorization-bypass, or other concrete security impact. If those pieces are absent, suppress or defer the row with exact evidence; if present, preserve the helper line as the root control even when an edge parser/filter finding also survives.
37
+ - when equivalent class filters, allowlists, denylists, blacklists, whitelists, or resolver controls are duplicated across runtime packages, validate or suppress the runtime/exported implementation separately. A transport callsite or nested helper proves reachability, but the reusable resolver line remains affected when it implements the broken security behavior.
38
+ - if validation shows one route or helper has multiple distinct high-impact proof tuples, keep them separately addressable instead of replacing one with another. A proved command-injection path does not validate away a separate SSRF, XML parser, path/file, XSS/template, or authz/state-change path in the same flow.
39
+ - when suppressing XML/parser/deserializer candidates, name the exact complete control that defeats that parser path. Partial hardening or a safe sibling parser does not suppress a different default factory, converter, validator, transformer, unmarshal, or parse call.
40
+ - for XML parser/converter candidates, verify hardening fails closed on the exact parser instance. `FEATURE_SECURE_PROCESSING` by itself, swallowed/logged `setFeature` failures, caller-supplied parser factories/readers, or missing entity/DTD resolver controls leave the row alive unless exact runtime evidence proves external entities and DTDs cannot be processed.
41
+ - for command/action runner candidates, validate each argument type and execution mode independently. Treat API/webhook-supplied values as attacker-controlled even when the frontend widget would normally constrain them, and do not suppress shell injection until the exact typecheck/escape path for that argument type is proven safe before template rendering and shell wrapping.
42
+ - for SSRF/download/webhook/callback candidates, validate the exact destination source, URL parser, allow/deny/filter config, redirect behavior, and network client sink. Do not suppress because the outbound request is a documented feature, because operators can configure filters, because filters are empty by default, or because validation happens before redirects; those facts are preconditions or partial controls unless the final requested destination is constrained on the exact path.
43
+ - for resource-serving/path traversal candidates, validate the exact allowlist, path matcher, URL decoding, canonicalization, and resource-selection control used by that handler. A newer safe resource handler or resolver does not suppress a legacy/deprecated/exported handler with a different control line. For restore/import/export/admin-looking routes, also validate the exact global middleware and decorator semantics before assuming the path is authenticated; optional or conditional login wrappers are not enough when the route is reachable without auth in default or no-password deployments.
44
+ - for restore/import/export, backup/restore, archive extraction, file copy/move, download/open, and key/config fetch candidates, validate the exact destination-selection, canonicalization, branch-local transform, and filesystem effect for that operation. A nearby auth bypass, secret leak, or configuration flaw is a separate row, not suppression or replacement for the path/file row.
45
+ - for archive extraction and restore/import candidates, suppression requires exact proof that each untrusted member path is normalized and contained before the extraction or write occurs. Do not suppress with a generic claim that a library helper is safe, or with later top-level file filtering, UUID/manifest gates, copytree/import allowlists, recursive promotion into an approved root, or post-extraction scanning after attacker-controlled paths have already been materialized. Reason explicitly about symlink, hardlink, metadata, and imported-subtree behavior whenever extracted content is later copied or promoted. Do not require the write to escape the overall app/datastore root; writes into trusted config, peer-object directories, shared roots, or imported subtrees inside that root still count as arbitrary file impact.
46
+ - for archive-member traversal, static evidence can be enough to survive when uploaded package/archive bytes reach a member-name decode/filter/join/write sequence and no exact containment check runs before the write. Missing optional parser libraries or lack of a full archive harness should lower confidence or become an explicit deferred proof gap, not silently suppress or replace the row with an adjacent same-family file traversal.
47
+ - deprecation, opt-in registration, or documentation warning that an API can be dangerous is a precondition, not counterevidence, for framework/library runtime code when the instance has a plausible cross-boundary source and runtime/deployment path. Suppress only if repository evidence proves the intended restricted/control mode defeats the exact attack; do not suppress a bypass of the restricted mode because an unrestricted mode is documented as dangerous.
48
+ - when suppressing auth/authz candidates, name the exact permission, authentication, tenant/object, or state-transition check on that endpoint. A credential-helper issue elsewhere does not replace a public webhook/status/API endpoint that reads protected data or triggers protected work.
49
+ - for stateful authentication protocols, validate the transition from pre-authentication or pre-upgrade state to credentialed identity: principal/credential/token installation, rebind or reauthentication call, issuer/callback assignment, and validated object versus consumed object. Missing rebinding or incomplete state checks remain reportable when attacker-controlled protocol state can authenticate or bind the wrong identity.
50
+ - for self-service update candidates, compare the attacker-controlled request object and persisted object field by field for security-sensitive identity, trust-state, tenant, role/group, MFA, and account-recovery properties. Do not suppress because one alias is checked, such as primary email, when a related scalar or collection alias can still be changed.
51
+ - when the provided candidate set is repository-wide, validate high-impact candidates first and spend validation effort in this order: command/code execution, unsafe deserialization, SSTI/template execution, SQL/NoSQL/query injection, SSRF/callback/file/network impact, path traversal/arbitrary file read or write, unsafe upload, and authz/tenant/object bypass with privilege or protected-object impact
52
+ - do not let low-severity data/config findings consume validation budget before the high-impact queue is exhausted
53
+ - do not let one difficult build or service setup consume the budget needed to validate sibling high-impact candidates from the coverage ledger. If setup becomes disproportionate, switch to code trace plus existing tests/config evidence for that candidate and continue the ledger.
54
+ - suppressions must close the specific row they suppress. A missing downstream caller, deployment fact, import path, or artifact-provenance fact is a reason to run the bounded adjacency pass or mark the row `deferred`, not proof that the candidate is safe.
55
+
56
+ Use class-specific proof tuples:
57
+
58
+ - authz/tenant/object/state change: attacker path + missing/wrong guard + protected object/comparison/state transition
59
+ - injection/path traversal/file upload/header/open redirect: attacker-controlled bytes + sanitizer/canonicalization/allowlist result + dangerous sink/context
60
+ - XSS/template/SSTI: attacker-controlled value + escaping/template context + browser/server-side template execution sink
61
+ - recursive placeholder/template injection: request, tenant/client metadata, stored configuration, or error value + placeholder/template helper that recursively expands, re-parses, or evaluates resolved values + missing escape/non-recursive guard + XSS, expression execution, credential exfiltration, or code execution impact
62
+ - deserialization/code execution: attacker-controlled serialized/code/template bytes + unsafe loader/evaluator + execution or object-construction effect
63
+ - deserializer wrapper denylist/allowlist control: attacker-controlled, stored, plugin, remoting, import, or persisted-state serialized input + shared wrapper that accepts type tags or default object construction + missing/misordered deny entry, allowlist gap, converter-priority gap, or unsafe class-loader/default-converter behavior + object construction, crash, code execution, or privilege-boundary impact
64
+ - concrete deserializer/codec control: attacker-controlled serialized or structured input + registered codec/converter/deserializer/container handler that recursively parses, resolves types, filters classes, converts values, or constructs objects + missing validation, unsafe fallback, fail-open filter, or unbounded traversal + code execution, object construction, parser confusion, denial of service, or privilege-boundary impact
65
+ - SSRF/callback: attacker-controlled destination + destination control bypass + network/read/side-effect impact
66
+ - SSRF optional-filter/redirect control: attacker-controlled download/webhook/callback URL + optional, empty-by-default, regex-only, pre-request-only, or redirect-following destination control + internal/LAN/cloud metadata/file-backed fetch or server-side callback side effect
67
+ - auth/token/assertion/protocol control: attacker-controlled token, assertion, protocol metadata, or version value + exact validator/control semantics + mismatch between validated value and trusted value, incomplete canonicalization/equality, unchecked parsing, or missing binding + authentication, authorization, or protocol-security impact
68
+ - stateful auth protocol transition: attacker-controlled credentials, principal, token, issuer, assertion, server response, or protocol metadata + state transition after TLS upgrade, bind, redirect, callback, assertion validation, or identity-provider response + missing rebind/reauthentication, stale identity reuse, incomplete issuer/callback binding, or validated-vs-consumed mismatch + authentication bypass or identity confusion impact
69
+ - SAML/XML assertion binding: attacker-controlled response or assertion set + protocol/signature validation of one object + later use, clone, serialization, or storage of a different assertion/document node + authentication/session/token impact. Multi-object preconditions should be stated, but suppression needs exact evidence that the same object is cryptographically and semantically bound to the consumed object.
70
+ - SSO/SAML response validator: attacker-controlled SSO response containing one or more assertions + response/assertion validator code that selects, indexes, clones, serializes, or returns an assertion + mismatch between the signed/validated assertion and the assertion later consumed by the session/token path, or missing recipient/audience/destination/ACS binding + authentication or authorization bypass impact. A generic claims-authorizer or service-method authorization finding does not validate or suppress this row.
71
+ - found-valid selection mismatch: attacker-controlled list or set of tokens/assertions/identities + validator loop or `foundValid*` flag proves one element while later fixed-index, first/last, clone, serialization, or lookup consumes another element + authentication, authorization, or protocol-state impact. Suppression needs evidence that the consumed object is the same object already validated.
72
+ - XML parser/converter hardening: attacker-controlled XML/SVG/XSLT/SAX/DOM/StAX input + parser factory, converter, transformer, or resolver setup + fail-open feature configuration, missing entity/DTD controls, caller-supplied parser path, or secure-processing-only hardening + XXE, SSRF, file read, parser injection, or denial-of-service impact
73
+ - query/parser injection: attacker-controlled bytes + query/selector/parser API that receives syntax or operators rather than bound values + semantic change, parser error, row-set change, write amplification, or bypassable post-query guard + read, write, authz, integrity, or availability impact. A later business check limits confidence or impact only after proving it checks the same trusted object and defeats syntax control for that exact instance.
74
+ - resource handler path control: attacker-controlled URL/path/resource name + allowlist/path-matcher/decoder/canonicalizer/resource-selection control + mismatch, pre-decode/post-decode gap, legacy handler behavior, or unsafe resolver fallback + arbitrary file read/write, path traversal, or unauthorized resource access impact
75
+ - shared deserialization control: attacker-controlled or privilege-bearing serialized/config/import/plugin/remoting input + shared loader or converter/allowlist/denylist behavior + unsafe object construction or incomplete control + affected callsites or unresolved cross-boundary reuse
76
+ - protocol/version parser: attacker-controlled protocol metadata + missing complete format enforcement before split/parse/compare + parse exception, wrong ordering, or feature-gate bypass + protocol-security impact
77
+ - protocol/version regression seed: CVE/advisory/security-test context points at protocol compatibility, version comparison, negotiation, or feature gating + checked-out utility/comparator parses attacker-controlled protocol metadata with `split`, numeric conversion, regex partial validation, or unchecked component access + malformed or adversarial metadata can crash negotiation, bypass a protocol gate, select the wrong feature path, or downgrade/disable a security-relevant behavior. Missing runtime harness is a confidence limit when the local parser/control/impact tuple is visible.
78
+ - file-format object model DoS/corruption: untrusted document/archive/message parsed into first-party object model + low-level array/dictionary/node/helper method that performs unchecked element conversion, recursion, numeric parsing, or unbounded iteration without validating attacker-controlled structure + crash, denial of service, parser confusion, or security-control bypass impact
79
+ - file-format primitive helper: untrusted PDF/XML/YAML/archive/message/image/font/protocol structure + helper such as `to*Array`, `toList`, `getObject`, numeric conversion, parser/iterator, size-based allocation, unchecked cast, collection-to-array conversion, or loop over attacker-controlled nodes + missing type/size/shape validation + crash, denial of service, parser confusion, or security-control bypass impact. Central object-model helpers should be validated even when an edge parser/filter finding already survives.
80
+ - advisory-seeded parser/file-format DoS: advisory, release note, fix hunk, or security test identifies a malformed-input crash or resource-exhaustion regression + checked-out source shows untrusted file/message parsing reaches the exact helper + the helper performs unchecked cast, size-based allocation, recursive traversal, numeric conversion, or loop over attacker-controlled structure. A runtime harness improves confidence, but checked-out code plus existing tests or deterministic code reasoning can be enough to mark the row `reportable` when no exact countercontrol exists.
81
+ - deterministic parser/helper availability: untrusted remote, protocol, document, archive, or package input + missing helper guard produces a deterministic exception, unchecked cast, unchecked numeric parse, recursion, allocation, or loop failure + repeated trigger can abort request processing, parser execution, security negotiation, or service availability. Treat as security-relevant unless exact recovery or equivalent prevalidation defeats this instance.
82
+ - branch-specific operation control: request-selected operation or fallback branch + branch-local split/filter/canonicalize/type-resolution/object-binding line transforms attacker-controlled path/value differently from the shared path + shared evaluator, binder, or security-sensitive mutation sink. Validate the branch line, not only the common helper.
83
+ - self-service object/profile update authz: authenticated or externally controlled identity + update guard over protected profile/account/tenant fields + missing immutable-field, collection-alias, or subject/object binding check + account takeover, identity confusion, privilege escalation, or protected-object mutation impact
84
+ - secret/data exposure/session config: secret or sensitive source + exposure/storage/log/client boundary + missing protection; validate after high-impact classes unless this directly enables code execution, injection, privilege escalation, auth bypass, or sensitive cross-boundary impact
85
+ - agent/MCP: untrusted instruction/data source + privileged tool/action boundary + action, code execution, or exfiltration effect
86
+
87
+ ## Validation Checklist
88
+
89
+ Use this checklist to keep validation close to the prompt contract:
90
+
91
+ - Build the rubric before validating, using up to five concrete criteria grounded in the candidate and the surrounding code.
92
+ - Include a realistic-interface criterion when the code exposes an HTTP, CLI, message, file, or other user-reachable interface.
93
+ - Prefer precise, bounded steps over broad scans.
94
+ - For non-compiled stacks, prefer minimal targeted code understanding and only the smallest set of files needed.
95
+ - For compiled stacks, prefer stronger evidence in this order when feasible:
96
+ - crash
97
+ - valgrind or ASan
98
+ - debugger trace
99
+ - focused unit or integration test
100
+ - realistic interface reproduction
101
+ - code understanding
102
+ - If the code exposes a realistic interface, attempt validation through that interface before concluding when feasible.
103
+ - Keep commands short, non-interactive, and scoped to the touched files or the minimum referenced paths.
104
+ - If validation fails, record what was attempted, why it was inconclusive, and what proof gap remains.
105
+ - Save any PoCs, logs, or crafted inputs under that finding's validation artifacts path from `../../../references/scan-artifacts.md`.
106
+ - When multiple instances are provided, keep each candidate individually marked as survived, suppressed, or uncertain; do not silently omit candidates from the final validation report.
107
+ - For a single standalone validation request, do not infer repository-wide or sibling scope unless the user explicitly asks for expansion or provides a multi-instance candidate list.
108
+ - For a top-level repository-wide security scan, do not narrow validation to one representative finding when discovery supplied a coverage ledger or repeated pattern family.
109
+ - For repository-wide candidate sets, do not drop low-severity but real instances solely because they are low severity, but validate and report them only after the high-impact queue unless they directly amplify a serious issue.
110
+ - Use nearby safe paths as negative controls when feasible, but do not let the existence of a safe sibling suppress vulnerable siblings.
111
+ - Along with the PoC and artifacts, include a small readme explaining how to rebuild or use the PoC to test against the real target.
112
+ - If ASan, valgrind, debugger, or other logs prove the vulnerability with high certainty, include them as validation artifacts.
113
+
114
+ ## Confidence Guidance
115
+
116
+ Calibrate confidence from the strongest evidence actually obtained, not the scariness of the bug class.
117
+
118
+ - `1.0` for a reproduced crashing PoC with a successful validation result
119
+ - `0.9+` for valgrind or ASan reproduction with a successful validation result
120
+ - `0.8+` for a debugger trace that successfully demonstrates the vulnerability path
121
+ - `0.3+` for code understanding with a defensible success or failure conclusion
122
+ - `0.0` when counterevidence clearly defeats the suspected vulnerability