Skip to content

OpenAI's Codex Security CLI and TypeScript SDK for finding, validating, and fixing security vulnerabilities. npm: https://www.npmjs.com/package/@openai/codex-security

refactor(findings): share persisted finding normalization (#1574)

Michael D'Angelo5cb5915364e7
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 83335097d..50ac46466 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -15,6 +15,10 @@ packages and releases. Do not edit or commit files in that directory. See the
[SDK testing guide](sdk/typescript/TESTING.md) for the generation and validation
commands.
+`pnpm --dir sdk/typescript run generate:models` also copies shared finding
+normalization from the plugin source into the SDK. Edit the plugin helper, then
+regenerate its SDK copy. `pnpm --dir sdk/typescript run types` checks freshness.
+
Model-based evaluations live in [`evals/`](evals/README.md), outside the plugin
source. Deterministic triage checks and the MCP reducer IPC regression remain
part of normal CI.
diff --git a/plugins/codex-security/mcp-app/src/artifact-scan-draft.ts b/plugins/codex-security/mcp-app/src/artifact-scan-draft.ts
index 468b9a07e..8fde77fb2 100644
--- a/plugins/codex-security/mcp-app/src/artifact-scan-draft.ts
+++ b/plugins/codex-security/mcp-app/src/artifact-scan-draft.ts
@@ -1,5 +1,6 @@
+import { normalizePersistedFindingDetails } from "./finding-normalization.js";
import type { JsonObject } from "./types.js";
-import { isRecord as isObject, isNonEmptyString } from "./record.js";
+import { isRecord as isObject } from "./record.js";
import { createHash, randomUUID } from "node:crypto";
import { promises as fs } from "node:fs";
import { dirname, isAbsolute, join, posix, sep } from "node:path";
@@ -1942,7 +1943,7 @@ function parsePersistedDraft(
): ScanDraftInput {
if (Array.isArray(compatible.findings)) {
for (const finding of compatible.findings) {
- if (isObject(finding)) normalizePersistedFindingDetails(finding);
+ if (isObject(finding)) normalizePersistedFindingDetails(finding, "draft");
}
}
return parseSemanticScanDraft(compatible, schema);
@@ -1982,171 +1983,6 @@ function parsePersistedCheckpoint(
return parsePersistedDraft(compatible, schema);
}
-function normalizePersistedFindingDetails(finding: JsonObject): void {
- const canonicalEvidence = Array.isArray(finding.codeEvidence)
- ? finding.codeEvidence
- : [];
- const evidenceIds = new Set(
- canonicalEvidence.flatMap((evidence) => {
- if (!isObject(evidence)) return [];
- const id = evidence.id;
- return isNonEmptyString(id) ? [id] : [];
- }),
- );
- if (Array.isArray(finding.code_evidence)) {
- const compatibleEvidence: JsonObject[] = [];
- for (const evidence of finding.code_evidence) {
- if (!isObject(evidence)) continue;
- const id = evidence.id;
- const code = evidence.code;
- if (
- !isNonEmptyString(id) ||
- !isNonEmptyString(code) ||
- evidenceIds.has(id)
- ) {
- continue;
- }
- evidenceIds.add(id);
- compatibleEvidence.push(evidence);
- }
- finding.code_evidence = compatibleEvidence;
- } else if ("code_evidence" in finding) {
- delete finding.code_evidence;
- }
-
- for (const [sectionName, listFields] of [
- ["rootCause", ["evidenceRefs", "evidence_refs"]],
- ["root_cause", ["evidenceRefs", "evidence_refs"]],
- [
- "validation",
- [
- "assertions",
- "counterEvidence",
- "evidence",
- "evidenceRefs",
- "evidence_refs",
- "limitations",
- ],
- ],
- [
- "attackPath",
- [
- "assumptions",
- "blindspots",
- "controls",
- "evidenceRefs",
- "evidence_refs",
- "limitations",
- "preconditions",
- "steps",
- ],
- ],
- ] satisfies Array<[string, string[]]>) {
- const section = finding[sectionName];
- if (!isObject(section)) continue;
- normalizePersistedStringLists(section, listFields);
- }
-
- const rootCause = finding.rootCause;
- if (isObject(rootCause)) {
- if (!isNonEmptyString(rootCause.summary)) {
- delete finding.rootCause;
- } else {
- removeUnsupportedPersistedStrings(rootCause, ["code", "language"]);
- }
- }
- const legacyRootCause = finding.root_cause;
- if (isObject(legacyRootCause)) {
- removeUnsupportedPersistedStrings(legacyRootCause, [
- "summary",
- "code",
- "language",
- ]);
- } else if ("root_cause" in finding && !isNonEmptyString(legacyRootCause)) {
- delete finding.root_cause;
- }
-
- const validation = finding.validation;
- if (isObject(validation)) {
- removeUnsupportedPersistedStrings(validation, [
- "method",
- "status",
- "summary",
- "disposition",
- "result",
- ]);
- }
-
- const attackPath = finding.attackPath;
- if (!isObject(attackPath)) return;
- removeUnsupportedPersistedStrings(attackPath, ["summary"]);
- for (const field of ["dataFlow", "data_flow", "dataflow", "reachability"]) {
- const detail = attackPath[field];
- if (!isObject(detail)) {
- if (!isNonEmptyString(detail)) delete attackPath[field];
- continue;
- }
- removeUnsupportedPersistedStrings(detail, [
- "summary",
- "source",
- "sink",
- "outcome",
- ...(field === "reachability" ? ["attacker", "entrypoint"] : []),
- ]);
- normalizePersistedStringLists(detail, [
- "evidenceRefs",
- "evidence_refs",
- "transformations",
- ...(field === "reachability" ? ["preconditions"] : []),
- ]);
- }
- for (const field of ["impact", "likelihood"]) {
- const detail = attackPath[field];
- if (isObject(detail)) {
- removeUnsupportedPersistedStrings(detail, ["level", "rationale", "why"]);
- } else if (
- detail !== undefined &&
- detail !== null &&
- !isNonEmptyString(detail)
- ) {
- delete attackPath[field];
- }
- }
-
- function normalizePersistedStringLists(
- section: JsonObject,
- fields: string[],
- ): void {
- for (const field of fields) {
- if (!(field in section)) continue;
- const value = section[field];
- const normalized = isNonEmptyString(value)
- ? [value]
- : Array.isArray(value)
- ? value.filter(isNonEmptyString)
- : [];
- if (normalized.length > 0) section[field] = normalized;
- else delete section[field];
- }
- for (const field of ["evidenceRefs", "evidence_refs"]) {
- const refs = section[field];
- if (!Array.isArray(refs)) continue;
- section[field] = refs.filter((ref) => evidenceIds.has(ref));
- }
- }
-}
-
-function removeUnsupportedPersistedStrings(
- section: JsonObject,
- fields: string[],
-): void {
- for (const field of fields) {
- if (field in section && !isNonEmptyString(section[field])) {
- delete section[field];
- }
- }
-}
-
function requireBoundScan(
context: ArtifactContext,
input: CompletedScanInput,
diff --git a/plugins/codex-security/mcp-app/src/finding-normalization.ts b/plugins/codex-security/mcp-app/src/finding-normalization.ts
new file mode 100644
index 000000000..381a4b32d
--- /dev/null
+++ b/plugins/codex-security/mcp-app/src/finding-normalization.ts
@@ -0,0 +1,193 @@
+import { isRecord as isObject } from "./record.js";
+
+type JsonObject = Record<string, unknown>;
+
+export function normalizePersistedFindingDetails(
+ finding: JsonObject,
+ profile: "draft" | "canonical",
+): void {
+ const canonicalEvidence =
+ profile === "draft" && Array.isArray(finding["codeEvidence"])
+ ? finding["codeEvidence"]
+ : [];
+ const evidenceIds = new Set(
+ canonicalEvidence.flatMap((evidence) => {
+ if (!isObject(evidence)) return [];
+ const id = evidence["id"];
+ return isNonEmptyString(id) ? [id] : [];
+ }),
+ );
+ if (Array.isArray(finding["code_evidence"])) {
+ const compatibleEvidence: JsonObject[] = [];
+ for (const evidence of finding["code_evidence"]) {
+ if (!isObject(evidence)) continue;
+ const id = evidence["id"];
+ const code = evidence["code"];
+ if (
+ !isNonEmptyString(id) ||
+ !isNonEmptyString(code) ||
+ (profile === "draft" && evidenceIds.has(id))
+ ) {
+ continue;
+ }
+ if (profile === "draft") evidenceIds.add(id);
+ compatibleEvidence.push(evidence);
+ }
+ finding["code_evidence"] = compatibleEvidence;
+ } else if (profile === "draft" || finding["code_evidence"] !== null) {
+ delete finding["code_evidence"];
+ }
+
+ for (const [sectionName, listFields] of [
+ ["rootCause", ["evidenceRefs", "evidence_refs"]],
+ ["root_cause", ["evidenceRefs", "evidence_refs"]],
+ [
+ "validation",
+ [
+ "assertions",
+ "counterEvidence",
+ "evidence",
+ "evidenceRefs",
+ "evidence_refs",
+ "limitations",
+ ],
+ ],
+ [
+ "attackPath",
+ [
+ "assumptions",
+ "blindspots",
+ "controls",
+ "evidenceRefs",
+ "evidence_refs",
+ "limitations",
+ "preconditions",
+ "steps",
+ ],
+ ],
+ ] satisfies Array<[string, string[]]>) {
+ const section = finding[sectionName];
+ if (!isObject(section)) continue;
+ normalizePersistedStringLists(section, listFields);
+ }
+
+ const rootCause = finding["rootCause"];
+ if (profile === "draft" && isObject(rootCause)) {
+ if (!isNonEmptyString(rootCause["summary"])) {
+ delete finding["rootCause"];
+ } else {
+ removeUnsupportedPersistedStrings(rootCause, ["code", "language"]);
+ }
+ }
+ const legacyRootCause = finding["root_cause"];
+ if (isObject(legacyRootCause)) {
+ removeUnsupportedPersistedStrings(legacyRootCause, [
+ "summary",
+ "code",
+ "language",
+ ]);
+ } else if (
+ profile === "draft"
+ ? !isNonEmptyString(legacyRootCause)
+ : legacyRootCause !== null && typeof legacyRootCause !== "string"
+ ) {
+ delete finding["root_cause"];
+ }
+
+ const validation = finding["validation"];
+ if (isObject(validation)) {
+ removeUnsupportedPersistedStrings(
+ validation,
+ ["method", "status", "summary", "disposition", "result"].filter(
+ (field) =>
+ profile === "draft" ||
+ !["status", "disposition", "result"].includes(field) ||
+ validation[field] !== null,
+ ),
+ );
+ }
+
+ const attackPath = finding["attackPath"];
+ if (!isObject(attackPath)) return;
+ removeUnsupportedPersistedStrings(attackPath, ["summary"]);
+ for (const field of ["dataFlow", "data_flow", "dataflow", "reachability"]) {
+ const detail = attackPath[field];
+ if (!isObject(detail)) {
+ if (!isNonEmptyString(detail)) delete attackPath[field];
+ continue;
+ }
+ removeUnsupportedPersistedStrings(detail, [
+ "summary",
+ "source",
+ "sink",
+ "outcome",
+ ...(field === "reachability" ? ["attacker", "entrypoint"] : []),
+ ]);
+ normalizePersistedStringLists(detail, [
+ "evidenceRefs",
+ "evidence_refs",
+ "transformations",
+ ...(field === "reachability" ? ["preconditions"] : []),
+ ]);
+ }
+ for (const field of ["impact", "likelihood"]) {
+ const detail = attackPath[field];
+ if (isObject(detail)) {
+ removeUnsupportedPersistedStrings(detail, ["level", "rationale", "why"]);
+ } else if (
+ detail !== undefined &&
+ detail !== null &&
+ !isNonEmptyString(detail)
+ ) {
+ delete attackPath[field];
+ }
+ }
+
+ function normalizePersistedStringLists(
+ section: JsonObject,
+ fields: string[],
+ ): void {
+ for (const field of fields) {
+ const value = section[field];
+ if (
+ profile === "canonical" &&
+ field === "evidence" &&
+ isNonEmptyString(value)
+ )
+ continue;
+ const normalized = isNonEmptyString(value)
+ ? [value]
+ : Array.isArray(value)
+ ? value.filter(isNonEmptyString)
+ : undefined;
+ if (
+ normalized !== undefined &&
+ (profile === "canonical" || normalized.length > 0)
+ )
+ section[field] = normalized;
+ else delete section[field];
+ }
+ if (profile === "canonical") return;
+ for (const field of ["evidenceRefs", "evidence_refs"]) {
+ const refs = section[field];
+ if (!Array.isArray(refs)) continue;
+ section[field] = refs.filter((ref) => evidenceIds.has(ref));
+ }
+ }
+
+ function removeUnsupportedPersistedStrings(
+ section: JsonObject,
+ fields: string[],
+ ): void {
+ for (const field of fields) {
+ if (!isNonEmptyString(section[field])) delete section[field];
+ }
+ }
+
+ function isNonEmptyString(value: unknown): value is string {
+ return (
+ typeof value === "string" &&
+ (profile === "canonical" ? value.length > 0 : value.trim().length > 0)
+ );
+ }
+}
diff --git a/plugins/codex-security/mcp-app/tests/test_artifact_scan_draft_recovery.ts b/plugins/codex-security/mcp-app/tests/test_artifact_scan_draft_recovery.ts
index 064f386d1..c70919fe5 100644
--- a/plugins/codex-security/mcp-app/tests/test_artifact_scan_draft_recovery.ts
+++ b/plugins/codex-security/mcp-app/tests/test_artifact_scan_draft_recovery.ts
@@ -41,6 +41,67 @@ const findingFor = (candidateId: string) => ({
provenance: { source: "local_plugin", candidateId },
});
+test("persisted draft recovery preserves evidence while removing unsupported optional details", async (t) => {
+ const f = await fixture(t, "worker");
+ const evidence = {
+ id: "canonical-source",
+ label: "Synthetic evidence",
+ path: "src/example.py",
+ startLine: 1,
+ code: "example()",
+ explanation: "Synthetic recovery fixture.",
+ };
+ const legacyEvidence = { id: "legacy-source", code: "legacy_example()" };
+ const input = {
+ ...f.draft(),
+ findings: [
+ {
+ ...findingFor("candidate-1"),
+ codeEvidence: [evidence],
+ code_evidence: [
+ evidence,
+ legacyEvidence,
+ legacyEvidence,
+ { id: " ", code: " " },
+ null,
+ ],
+ rootCause: { summary: " " },
+ root_cause: null,
+ validation: {
+ evidence: "single proof",
+ counterEvidence: [],
+ status: null,
+ evidenceRefs: ["canonical-source", "legacy-source", "missing"],
+ },
+ attackPath: {
+ steps: [" ", "Check the entrypoint", null],
+ reachability: {
+ attacker: false,
+ preconditions: [],
+ evidence_refs: ["missing"],
+ },
+ },
+ },
+ ],
+ };
+ const original = structuredClone(input);
+ const recovered = draftApi.parsePersistedScanDraft(input).findings[0];
+
+ assert.deepEqual(recovered.codeEvidence, [evidence]);
+ assert.deepEqual(recovered.code_evidence, [legacyEvidence]);
+ assert.equal(recovered.rootCause, undefined);
+ assert.equal(recovered.root_cause, undefined);
+ assert.deepEqual(recovered.validation, {
+ evidence: ["single proof"],
+ evidenceRefs: ["canonical-source", "legacy-source"],
+ });
+ assert.deepEqual(recovered.attackPath, {
+ steps: ["Check the entrypoint"],
+ reachability: { evidence_refs: [] },
+ });
+ assert.deepEqual(input, original);
+});
+
test("worker checkpoints retain typed surface IDs", async (t) => {
const f = await fixture(t, "worker");
await f.write(
diff --git a/sdk/typescript/scripts/generate-models.cjs b/sdk/typescript/scripts/generate-models.cjs
index bcb23faf7..0411b4ff1 100644
--- a/sdk/typescript/scripts/generate-models.cjs
+++ b/sdk/typescript/scripts/generate-models.cjs
@@ -88,15 +88,26 @@ async function generate() {
}
generate().then((models) => {
- const output = join(packageRoot, "src", "models.ts");
- if (process.argv.includes("--check")) {
- if (readFileSync(output, "utf8").replaceAll("\r\n", "\n") !== models) {
- console.error(
- "src/models.ts is out of date. Run `pnpm generate:models`.",
- );
- process.exitCode = 1;
- }
- return;
+ const shared = ["finding-normalization"].map((name) => [
+ `${name}.ts`,
+ `/* Generated from plugin ${name}.ts. Run \`pnpm generate:models\`. */\n` +
+ readFileSync(
+ join(
+ packageRoot,
+ `../../plugins/codex-security/mcp-app/src/${name}.ts`,
+ ),
+ "utf8",
+ ),
+ ]);
+ for (const [name, content] of [["models.ts", models], ...shared]) {
+ const output = join(packageRoot, "src", name);
+ if (process.argv.includes("--check")) {
+ if (readFileSync(output, "utf8").replaceAll("\r\n", "\n") !== content) {
+ console.error(
+ `src/${name} is out of date. Run \`pnpm generate:models\`.`,
+ );
+ process.exitCode = 1;
+ }
+ } else writeFileSync(output, content);
}
- writeFileSync(output, models);
});
diff --git a/sdk/typescript/scripts/package-dist-files.mjs b/sdk/typescript/scripts/package-dist-files.mjs
index ec33e1c6d..251d12fa8 100644
--- a/sdk/typescript/scripts/package-dist-files.mjs
+++ b/sdk/typescript/scripts/package-dist-files.mjs
@@ -72,6 +72,7 @@ const distModules = [
"deduplication/retry",
"deduplication/deduplication",
"finding-retrieval",
+ "finding-normalization",
"finding-workflow",
"findings-client",
"findings-errors",
diff --git a/sdk/typescript/src/contract.ts b/sdk/typescript/src/contract.ts
index 3c40f830d..448d07c18 100644
--- a/sdk/typescript/src/contract.ts
+++ b/sdk/typescript/src/contract.ts
@@ -1,6 +1,6 @@
import { isDeepStrictEqual as sameArray } from "node:util";
import { createHash, hash } from "node:crypto";
-import { isNonEmptyString } from "./value.js";
+import { normalizePersistedFindingDetails } from "./finding-normalization.js";
import { constants, type BigIntStats, type Stats } from "node:fs";
import {
lstat,
@@ -15,7 +15,6 @@ import { regexes } from "zod";
import { ContractValidationError, abortReason } from "./errors.js";
import { isRecord } from "./record.js";
import type {
- ContractObject as JsonRecord,
CoverageDocument,
FindingsDocument,
ScanManifest,
@@ -192,146 +191,11 @@ export function normalizePersistedFindings(payload: unknown): unknown {
}
for (const finding of compatible["findings"]) {
if (!isRecord(finding)) continue;
- const legacyEvidence = finding["code_evidence"];
- if (Array.isArray(legacyEvidence)) {
- finding["code_evidence"] = legacyEvidence.filter(
- (evidence) =>
- isRecord(evidence) &&
- isNonEmptyString(evidence["id"]) &&
- isNonEmptyString(evidence["code"]),
- );
- } else if ("code_evidence" in finding && legacyEvidence !== null) {
- delete finding["code_evidence"];
- }
-
- for (const [sectionName, listFields] of [
- ["rootCause", ["evidenceRefs", "evidence_refs"]],
- ["root_cause", ["evidenceRefs", "evidence_refs"]],
- [
- "validation",
- [
- "assertions",
- "counterEvidence",
- "evidenceRefs",
- "evidence_refs",
- "limitations",
- ],
- ],
- [
- "attackPath",
- [
- "assumptions",
- "blindspots",
- "controls",
- "evidenceRefs",
- "evidence_refs",
- "limitations",
- "preconditions",
- "steps",
- ],
- ],
- ] satisfies Array<[string, string[]]>) {
- const section = finding[sectionName];
- if (!isRecord(section)) continue;
- normalizeLegacyStringLists(section, listFields);
- }
-
- const legacyRootCause = finding["root_cause"];
- if (isRecord(legacyRootCause)) {
- removeUnsupportedLegacyStrings(legacyRootCause, [
- "summary",
- "code",
- "language",
- ]);
- } else if (
- "root_cause" in finding &&
- legacyRootCause !== null &&
- typeof legacyRootCause !== "string"
- ) {
- delete finding["root_cause"];
- }
-
- const validation = finding["validation"];
- if (isRecord(validation)) {
- if (!isNonEmptyString(validation["evidence"])) {
- normalizeLegacyStringLists(validation, ["evidence"]);
- }
- removeUnsupportedLegacyStrings(validation, ["method", "summary"]);
- removeUnsupportedLegacyStrings(
- validation,
- ["status", "disposition", "result"].filter(
- (field) => validation[field] !== null,
- ),
- );
- }
-
- const attackPath = finding["attackPath"];
- if (!isRecord(attackPath)) continue;
- removeUnsupportedLegacyStrings(attackPath, ["summary"]);
- for (const field of ["dataFlow", "data_flow", "dataflow", "reachability"]) {
- const detail = attackPath[field];
- if (!isRecord(detail)) {
- if (!isNonEmptyString(detail)) delete attackPath[field];
- continue;
- }
- removeUnsupportedLegacyStrings(detail, [
- "summary",
- "source",
- "sink",
- "outcome",
- ...(field === "reachability" ? ["attacker", "entrypoint"] : []),
- ]);
- normalizeLegacyStringLists(detail, [
- "evidenceRefs",
- "evidence_refs",
- "transformations",
- ...(field === "reachability" ? ["preconditions"] : []),
- ]);
- }
- for (const field of ["impact", "likelihood"]) {
- const detail = attackPath[field];
- if (isRecord(detail)) {
- removeUnsupportedLegacyStrings(detail, ["level", "rationale", "why"]);
- } else if (
- detail !== undefined &&
- detail !== null &&
- !isNonEmptyString(detail)
- ) {
- delete attackPath[field];
- }
- }
+ normalizePersistedFindingDetails(finding, "canonical");
}
return compatible;
}
-function normalizeLegacyStringLists(
- section: JsonRecord,
- fields: string[],
-): void {
- for (const field of fields) {
- if (!(field in section)) continue;
- const value = section[field];
- if (Array.isArray(value)) {
- section[field] = value.filter(isNonEmptyString);
- } else if (isNonEmptyString(value)) {
- section[field] = [value];
- } else {
- delete section[field];
- }
- }
-}
-
-function removeUnsupportedLegacyStrings(
- section: JsonRecord,
- fields: string[],
-): void {
- for (const field of fields) {
- if (field in section && !isNonEmptyString(section[field])) {
- delete section[field];
- }
- }
-}
-
function validateCanonicalContract(
manifest: ScanManifest,
findings: FindingsDocument,
diff --git a/sdk/typescript/src/finding-normalization.ts b/sdk/typescript/src/finding-normalization.ts
new file mode 100644
index 000000000..6663124ea
--- /dev/null
+++ b/sdk/typescript/src/finding-normalization.ts
@@ -0,0 +1,194 @@
+/* Generated from plugin finding-normalization.ts. Run `pnpm generate:models`. */
+import { isRecord as isObject } from "./record.js";
+
+type JsonObject = Record<string, unknown>;
+
+export function normalizePersistedFindingDetails(
+ finding: JsonObject,
+ profile: "draft" | "canonical",
+): void {
+ const canonicalEvidence =
+ profile === "draft" && Array.isArray(finding["codeEvidence"])
+ ? finding["codeEvidence"]
+ : [];
+ const evidenceIds = new Set(
+ canonicalEvidence.flatMap((evidence) => {
+ if (!isObject(evidence)) return [];
+ const id = evidence["id"];
+ return isNonEmptyString(id) ? [id] : [];
+ }),
+ );
+ if (Array.isArray(finding["code_evidence"])) {
+ const compatibleEvidence: JsonObject[] = [];
+ for (const evidence of finding["code_evidence"]) {
+ if (!isObject(evidence)) continue;
+ const id = evidence["id"];
+ const code = evidence["code"];
+ if (
+ !isNonEmptyString(id) ||
+ !isNonEmptyString(code) ||
+ (profile === "draft" && evidenceIds.has(id))
+ ) {
+ continue;
+ }
+ if (profile === "draft") evidenceIds.add(id);
+ compatibleEvidence.push(evidence);
+ }
+ finding["code_evidence"] = compatibleEvidence;
+ } else if (profile === "draft" || finding["code_evidence"] !== null) {
+ delete finding["code_evidence"];
+ }
+
+ for (const [sectionName, listFields] of [
+ ["rootCause", ["evidenceRefs", "evidence_refs"]],
+ ["root_cause", ["evidenceRefs", "evidence_refs"]],
+ [
+ "validation",
+ [
+ "assertions",
+ "counterEvidence",
+ "evidence",
+ "evidenceRefs",
+ "evidence_refs",
+ "limitations",
+ ],
+ ],
+ [
+ "attackPath",
+ [
+ "assumptions",
+ "blindspots",
+ "controls",
+ "evidenceRefs",
+ "evidence_refs",
+ "limitations",
+ "preconditions",
+ "steps",
+ ],
+ ],
+ ] satisfies Array<[string, string[]]>) {
+ const section = finding[sectionName];
+ if (!isObject(section)) continue;
+ normalizePersistedStringLists(section, listFields);
+ }
+
+ const rootCause = finding["rootCause"];
+ if (profile === "draft" && isObject(rootCause)) {
+ if (!isNonEmptyString(rootCause["summary"])) {
+ delete finding["rootCause"];
+ } else {
+ removeUnsupportedPersistedStrings(rootCause, ["code", "language"]);
+ }
+ }
+ const legacyRootCause = finding["root_cause"];
+ if (isObject(legacyRootCause)) {
+ removeUnsupportedPersistedStrings(legacyRootCause, [
+ "summary",
+ "code",
+ "language",
+ ]);
+ } else if (
+ profile === "draft"
+ ? !isNonEmptyString(legacyRootCause)
+ : legacyRootCause !== null && typeof legacyRootCause !== "string"
+ ) {
+ delete finding["root_cause"];
+ }
+
+ const validation = finding["validation"];
+ if (isObject(validation)) {
+ removeUnsupportedPersistedStrings(
+ validation,
+ ["method", "status", "summary", "disposition", "result"].filter(
+ (field) =>
+ profile === "draft" ||
+ !["status", "disposition", "result"].includes(field) ||
+ validation[field] !== null,
+ ),
+ );
+ }
+
+ const attackPath = finding["attackPath"];
+ if (!isObject(attackPath)) return;
+ removeUnsupportedPersistedStrings(attackPath, ["summary"]);
+ for (const field of ["dataFlow", "data_flow", "dataflow", "reachability"]) {
+ const detail = attackPath[field];
+ if (!isObject(detail)) {
+ if (!isNonEmptyString(detail)) delete attackPath[field];
+ continue;
+ }
+ removeUnsupportedPersistedStrings(detail, [
+ "summary",
+ "source",
+ "sink",
+ "outcome",
+ ...(field === "reachability" ? ["attacker", "entrypoint"] : []),
+ ]);
+ normalizePersistedStringLists(detail, [
+ "evidenceRefs",
+ "evidence_refs",
+ "transformations",
+ ...(field === "reachability" ? ["preconditions"] : []),
+ ]);
+ }
+ for (const field of ["impact", "likelihood"]) {
+ const detail = attackPath[field];
+ if (isObject(detail)) {
+ removeUnsupportedPersistedStrings(detail, ["level", "rationale", "why"]);
+ } else if (
+ detail !== undefined &&
+ detail !== null &&
+ !isNonEmptyString(detail)
+ ) {
+ delete attackPath[field];
+ }
+ }
+
+ function normalizePersistedStringLists(
+ section: JsonObject,
+ fields: string[],
+ ): void {
+ for (const field of fields) {
+ const value = section[field];
+ if (
+ profile === "canonical" &&
+ field === "evidence" &&
+ isNonEmptyString(value)
+ )
+ continue;
+ const normalized = isNonEmptyString(value)
+ ? [value]
+ : Array.isArray(value)
+ ? value.filter(isNonEmptyString)
+ : undefined;
+ if (
+ normalized !== undefined &&
+ (profile === "canonical" || normalized.length > 0)
+ )
+ section[field] = normalized;
+ else delete section[field];
+ }
+ if (profile === "canonical") return;
+ for (const field of ["evidenceRefs", "evidence_refs"]) {
+ const refs = section[field];
+ if (!Array.isArray(refs)) continue;
+ section[field] = refs.filter((ref) => evidenceIds.has(ref));
+ }
+ }
+
+ function removeUnsupportedPersistedStrings(
+ section: JsonObject,
+ fields: string[],
+ ): void {
+ for (const field of fields) {
+ if (!isNonEmptyString(section[field])) delete section[field];
+ }
+ }
+
+ function isNonEmptyString(value: unknown): value is string {
+ return (
+ typeof value === "string" &&
+ (profile === "canonical" ? value.length > 0 : value.trim().length > 0)
+ );
+ }
+}