OpenAI's Codex Security CLI and TypeScript SDK for finding, validating, and fixing security vulnerabilities. npm: https://www.npmjs.com/package/@openai/codex-security
TypeScript ai-securityapplication-securityclicode-scanningcodexcodex-securitycybersecuritydevsecopsnodejsnpmopenaisdksecuritytypescriptvulnerability-scanning
fix(reports): persist run warnings in SARIF exports (#1893)
Michael D'Angelo9cb8020754df
diff --git a/plugins/codex-security/mcp-app/scripts/canonical-schemas.mts b/plugins/codex-security/mcp-app/scripts/canonical-schemas.mtsindex 0094f93e9..51c53d2a3 100644--- a/plugins/codex-security/mcp-app/scripts/canonical-schemas.mts+++ b/plugins/codex-security/mcp-app/scripts/canonical-schemas.mts@@ -192,6 +192,7 @@ const scanManifest = z.looseObject({id: text,producer: z.looseObject({ name: text, version: text }),status: z.enum(["completed", "failed", "canceled", "interrupted"]),+ warnings: textList.optional(),startedAt: timestamp,completedAt: timestamp,sealedAt: timestamp,diff --git a/plugins/codex-security/references/scan-contract.md b/plugins/codex-security/references/scan-contract.mdindex 2a2242a75..ebb1bd692 100644--- a/plugins/codex-security/references/scan-contract.md+++ b/plugins/codex-security/references/scan-contract.md@@ -39,6 +39,8 @@ Producers should use UTC ISO 8601 timestamps in the native SDK or plugin format.Only `completed` supports a completed-scan conclusion. For every stopped outcome, consumers must preserve retained findings and coverage while treating absence of findings as inconclusive.+Optional `scan.warnings` records run-level diagnostics available when the bundle is first sealed. SARIF exports include these messages alongside deferred-task reasons in `toolExecutionNotifications`; warnings do not change `executionSuccessful`, which follows `scan.status`. Missing or empty warnings add no notifications. Existing sealed bundles remain unchanged, and export or publication warnings discovered afterward remain separate operation diagnostics.+### Stopped Result RecoveryTo validate and republish retained checkpoints for a failed, non-canceled workbench scan, run:diff --git a/plugins/codex-security/schemas/scan-manifest.schema.json b/plugins/codex-security/schemas/scan-manifest.schema.jsonindex 5ca16a25a..c8c9d0a39 100644--- a/plugins/codex-security/schemas/scan-manifest.schema.json+++ b/plugins/codex-security/schemas/scan-manifest.schema.json@@ -21,6 +21,7 @@"status": {"enum": ["completed", "failed", "canceled", "interrupted"]},+ "warnings": { "$ref": "#/$defs/stringList" },"startedAt": { "type": "string", "format": "date-time" },"completedAt": { "type": "string", "format": "date-time" },"sealedAt": { "type": "string", "format": "date-time" },diff --git a/plugins/codex-security/scripts/finalize_scan_contract.py b/plugins/codex-security/scripts/finalize_scan_contract.pyindex abcb82736..02f027328 100644--- a/plugins/codex-security/scripts/finalize_scan_contract.py+++ b/plugins/codex-security/scripts/finalize_scan_contract.py@@ -2831,14 +2831,17 @@ def build_sarif_projection(manifest, findings, coverage, _ = _read_sealed_scan(scan_dir, schema_dir, "SARIF projection")sarif = build_sarif(manifest, findings, source_root)execution_successful = manifest["scan"]["status"] == "completed"- if not execution_successful or coverage["deferred"]:+ messages = [item["reason"] for item in coverage["deferred"]]+ for warning in manifest["scan"].get("warnings", []):+ if warning not in messages:+ messages.append(warning)+ if not execution_successful or messages:run = sarif["runs"][0]run["invocations"] = [{"executionSuccessful": execution_successful,"toolExecutionNotifications": [- {"level": "warning", "message": {"text": item["reason"]}}- for item in coverage["deferred"]+ {"level": "warning", "message": {"text": message}} for message in messages],}]@@ -3239,6 +3242,24 @@ def _write_prepared_scan_finalization(scan_dir = prepared.scan_dirscan = _require_dict(prepared.manifest, "scan", "manifest")if not prepared.was_sealed:+ # Capture warnings before the first seal; later operation diagnostics must+ # not change an existing scan's portable results.+ # Escape surrogate-escaped filesystem bytes for the Unicode JSON contract.+ warnings = list(+ dict.fromkeys(+ warning.encode("utf-8", errors="backslashreplace").decode("utf-8")+ for warning in [+ *scan.get("warnings", []),+ *(projection_warnings or []),+ *prepared.warnings,+ ]+ )+ )+ if warnings:+ scan["warnings"] = warnings+ validate_against_schema(+ prepared.manifest, prepared.schema_dir / "scan-manifest.schema.json"+ )_write_scan_local_json(scan_dir, "findings.json", prepared.findings)_write_scan_local_json(scan_dir, "coverage.json", prepared.coverage)write_scan_local_bytes(scan_dir, "report.md", prepared.report_markdown_bytes)diff --git a/plugins/codex-security/tests/test_deep_scan_successful_publication.py b/plugins/codex-security/tests/test_deep_scan_successful_publication.pyindex 63fe19e42..74d9a95fb 100644--- a/plugins/codex-security/tests/test_deep_scan_successful_publication.py+++ b/plugins/codex-security/tests/test_deep_scan_successful_publication.py@@ -2,6 +2,7 @@ from __future__ import annotationsimport copyimport json+import osimport shutilimport uuidfrom argparse import Namespace@@ -350,6 +351,75 @@ def test_deep_prepare_and_complete_preserve_the_same_aggregate(assert_published_aggregate(scan)[email protected]("mode", ["standard", "deep"])[email protected]("after_sealing", [False, True])+def test_completion_captures_target_warnings_before_first_seal(+ workbench_api, workbench_db, publication_scan, monkeypatch, tmp_path, mode, after_sealing+):+ scan = publication_scan(mode=mode)+ source = tmp_path / "target" / "subdir" / "extract.py"+ completion_globals = workbench_api["complete_scan_locked"].__globals__+ prepare = completion_globals["_prepare_scan_finalization"]++ def prepare_then_change_target(*args, **kwargs):+ prepared = prepare(*args, **kwargs)+ if not after_sealing:+ source.write_text("# Changed during finalization\n")+ return prepared++ with monkeypatch.context() as patch:+ patch.setitem(completion_globals, "_prepare_scan_finalization", prepare_then_change_target)+ complete(workbench_api, workbench_db, scan, prepare_only=True)+ manifest_path = scan.scan_dir / "scan-manifest.json"+ sealed_bytes = manifest_path.read_bytes()+ if after_sealing:+ source.write_text("# Changed after preparation sealed the scan\n")++ completed = complete(workbench_api, workbench_db, scan)++ assert completed["progress"]["status"] == "complete"+ assert len(completed["warnings"]) == 1+ assert manifest_path.read_bytes() == sealed_bytes+ manifest = json.loads(sealed_bytes)+ assert manifest["scan"].get("warnings", []) == ([] if after_sealing else completed["warnings"])+ sarif = json.loads((scan.scan_dir / "exports/results.sarif").read_text())+ if after_sealing:+ assert "invocations" not in sarif["runs"][0]+ else:+ invocation = sarif["runs"][0]["invocations"][0]+ assert invocation["executionSuccessful"] is True+ assert invocation["toolExecutionNotifications"] == [+ {"level": "warning", "message": {"text": completed["warnings"][0]}}+ ]++[email protected](os.name == "nt", reason="Unix filenames can contain non-UTF-8 bytes")[email protected]("mode", ["standard", "deep"])+def test_completion_preserves_non_utf8_filename_warning(+ workbench_api, workbench_db, publication_scan, tmp_path, mode+):+ scan = publication_scan(mode=mode)+ os.mkfifo(os.fsencode(tmp_path / "target") + b"/new-pipe-\xff")++ completed = complete(workbench_api, workbench_db, scan)++ assert completed["progress"]["status"] == "complete"+ warning = completed["warnings"][0]+ assert "new-pipe-\udcff" in warning+ portable_warning = warning.replace("\udcff", "\\udcff")+ manifest_path = scan.scan_dir / "scan-manifest.json"+ sealed_bytes = manifest_path.read_bytes()+ assert json.loads(sealed_bytes)["scan"]["warnings"] == [portable_warning]+ sarif = json.loads((scan.scan_dir / "exports/results.sarif").read_text())+ invocation = sarif["runs"][0]["invocations"][0]+ assert invocation["executionSuccessful"] is True+ assert invocation["toolExecutionNotifications"] == [+ {"level": "warning", "message": {"text": portable_warning}}+ ]+ complete(workbench_api, workbench_db, scan)+ assert manifest_path.read_bytes() == sealed_bytes++@pytest.mark.cross_platform@pytest.mark.parametrize("scope", [".", "subdir"])@pytest.mark.parametrize("missing_parent", [False, True])diff --git a/plugins/codex-security/tests/test_sarif_projection.py b/plugins/codex-security/tests/test_sarif_projection.pyindex d37723d99..c3a15934e 100644--- a/plugins/codex-security/tests/test_sarif_projection.py+++ b/plugins/codex-security/tests/test_sarif_projection.py@@ -146,6 +146,85 @@ class SarifProjectionTest(unittest.TestCase):self.assertIn(f"Weaknesses: {', '.join(cwes)}", run["results"][0]["message"]["text"])self.assertEqual(self.finding["taxonomy"]["cwe"], cwes)+ def test_sarif_projection_reports_run_warnings_without_changing_status_or_seal(self) -> None:+ warning = "Optional writeup unavailable: notes/review.md\nThe finding was retained."+ for status in ("completed", "failed", "interrupted", "canceled"):+ for warnings in (None, [], [warning]):+ with (+ self.subTest(status=status, warnings=warnings),+ tempfile.TemporaryDirectory() as directory,+ ):+ scan_dir = Path(directory) / "scan"+ shutil.copytree(EXAMPLE_DIR, scan_dir)+ manifest = copy.deepcopy(self.manifest)+ manifest["scan"]["status"] = status+ if warnings is not None:+ manifest["scan"]["warnings"] = warnings+ (scan_dir / "scan-manifest.json").write_text(json.dumps(manifest) + "\n")+ before = {+ name: (scan_dir / name).read_bytes()+ for name in ("scan-manifest.json", "findings.json", "coverage.json")+ }++ contents = FINALIZER.build_findings_export(scan_dir, "sarif")+ run = json.loads(contents)["runs"][0]+ if status == "completed" and not warnings:+ self.assertNotIn("invocations", run)+ else:+ self.assertEqual(+ run["invocations"],+ [+ {+ "executionSuccessful": status == "completed",+ "toolExecutionNotifications": [+ {"level": "warning", "message": {"text": message}}+ for message in warnings or []+ ],+ }+ ],+ )+ FINALIZER.write_sarif_projection(scan_dir)+ self.assertEqual((scan_dir / "exports/results.sarif").read_bytes(), contents)+ self.assertEqual(+ before, {name: (scan_dir / name).read_bytes() for name in before}+ )++ def test_sarif_projection_appends_unique_run_warnings_after_deferred_reasons(self) -> None:+ deferred_reason = "Review of a deferred surface is incomplete."+ warning = "Optional writeup unavailable."+ for warnings, messages in (+ (None, [deferred_reason, deferred_reason]),+ ([], [deferred_reason, deferred_reason]),+ (+ [warning, deferred_reason, warning, warning + " "],+ [deferred_reason, deferred_reason, warning, warning + " "],+ ),+ ):+ with self.subTest(warnings=warnings), tempfile.TemporaryDirectory() as directory:+ scan_dir = Path(directory) / "scan"+ shutil.copytree(EXAMPLE_DIR, scan_dir)+ manifest = copy.deepcopy(self.manifest)+ if warnings is not None:+ manifest["scan"]["warnings"] = warnings+ coverage_path = scan_dir / "coverage.json"+ coverage = json.loads(coverage_path.read_bytes())+ coverage["deferred"] = [+ {"id": f"deferred-{index}", "reason": deferred_reason} for index in range(2)+ ]+ coverage_path.write_text(json.dumps(coverage) + "\n")+ for artifact in manifest["scan"]["artifacts"]:+ if artifact["path"] == "coverage.json":+ artifact["sha256"] = hashlib.sha256(coverage_path.read_bytes()).hexdigest()+ (scan_dir / "scan-manifest.json").write_text(json.dumps(manifest) + "\n")++ invocation = FINALIZER.build_sarif_projection(scan_dir)["runs"][0]["invocations"][0]++ self.assertTrue(invocation["executionSuccessful"])+ self.assertEqual(+ invocation["toolExecutionNotifications"],+ [{"level": "warning", "message": {"text": message}} for message in messages],+ )+def test_sarif_projection_preserves_inventoried_exports(self) -> None:relative_path = "exports/results.sarif"error = "SARIF output path cannot overwrite a sealed scan artifact"diff --git a/plugins/codex-security/tests/test_workbench_completion_binding.py b/plugins/codex-security/tests/test_workbench_completion_binding.pyindex 5e885f6a1..60322e3dd 100644--- a/plugins/codex-security/tests/test_workbench_completion_binding.py+++ b/plugins/codex-security/tests/test_workbench_completion_binding.py@@ -4,6 +4,7 @@ import copyimport hashlibimport jsonimport os+import shutilimport sqlite3import subprocessimport sys@@ -19,6 +20,7 @@ from workbench_test_support import (fail_scan,get_scan,initialize_git_repository,+ load_script,mark_deep_coordinator_succeeded,resume_deep_scan,run_workbench,@@ -1119,12 +1121,51 @@ def test_completion_persists_optional_model_projection_warnings(assert len(warnings) == 1assert warnings[0].startswith("Automatic threat model save failed:")assert json.loads(manifest_path.read_text())["scan"]["threatModel"] == model+ assert "warnings" not in json.loads(manifest_path.read_text())["scan"]if already_completed:assert {name: (scan_dir / name).read_bytes() for name in before} == beforeassert get_scan(state_dir, scan_id)["scan"]["warnings"] == warningsassert scan_command(state_dir, "complete-scan", scan_id)["scan"]["warnings"] == warnings[email protected]_platform[email protected]("mode", ["standard", "deep"])[email protected]("prepare_first", [False, True])+def test_completion_exports_warning_without_workbench_state(+ tmp_path: Path, mode: str, prepare_first: bool+) -> None:+ start = (+ _start_deep_scan_with_draft_findings if mode == "deep" else _start_scan_with_draft_findings+ )+ state_dir, scan_id, scan_dir = start(tmp_path)+ path = scan_dir / "findings.json"+ findings = json.loads(path.read_text())+ findings["findings"][0]["writeup"] = {"reportPath": "findings/missing/missing.md"}+ path.write_text(json.dumps(findings))+ if prepare_first:+ prepared = scan_command(state_dir, "prepare-scan-completion", scan_id)["scan"]+ assert prepared["warnings"]+ completed = scan_command(state_dir, "complete-scan", scan_id)["scan"]+ warnings = completed["warnings"]+ assert len(warnings) == 1+ assert warnings[0].startswith("Skipped missing writeup for finding 1:")+ assert json.loads((scan_dir / "scan-manifest.json").read_text())["scan"]["warnings"] == warnings+ assert json.loads((scan_dir / "coverage.json").read_text())["deferred"] == []++ portable = tmp_path / "portable"+ shutil.copytree(scan_dir, portable)+ finalizer = load_script("finalize_scan_contract", module_name="warnings_finalizer")+ sarif = finalizer.build_sarif_projection(portable)+ assert sarif["runs"][0]["invocations"] == [+ {+ "executionSuccessful": True,+ "toolExecutionNotifications": [+ {"level": "warning", "message": {"text": warning}} for warning in warnings+ ],+ }+ ]++@pytest.mark.parametrize("field", ["ruleId", "anchor", "instance"])def test_completion_rejects_malformed_finding_identity(tmp_path: Path, field: str) -> None:state_dir, scan_id, scan_dir = _start_scan_with_draft_findings(tmp_path)@@ -1202,6 +1243,12 @@ def test_completion_rejects_bad_findings_and_failed_scan_preserves_valid_rows(assert (scan_dir / "report.md").is_file()sarif = json.loads((scan_dir / "exports/results.sarif").read_text())assert sarif["runs"][0]["invocations"][0]["executionSuccessful"] is False+ warnings = json.loads((scan_dir / "scan-manifest.json").read_text())["scan"]["warnings"]+ assert warnings+ notifications = sarif["runs"][0]["invocations"][0]["toolExecutionNotifications"]+ assert all(+ {"level": "warning", "message": {"text": warning}} in notifications for warning in warnings+ )def test_completion_rejects_unknown_optional_root_cause_evidence_reference(@@ -1386,8 +1433,12 @@ def test_stopped_recovery_preserves_findings_with_invalid_or_duplicate_writeups(@pytest.mark.cross_platform-def test_completion_retry_preserves_missing_writeup_warning(tmp_path: Path) -> None:- state_dir, scan_id, scan_dir = _start_scan_with_draft_findings(tmp_path)[email protected]("mode", ["standard", "deep"])+def test_completion_retry_preserves_missing_writeup_warning(tmp_path: Path, mode: str) -> None:+ start = (+ _start_deep_scan_with_draft_findings if mode == "deep" else _start_scan_with_draft_findings+ )+ state_dir, scan_id, scan_dir = start(tmp_path)path = scan_dir / "findings.json"document = json.loads(path.read_text())document["findings"][0]["writeup"] = {"reportPath": "findings/missing/missing.md"}@@ -1420,6 +1471,10 @@ def test_completion_retry_preserves_missing_writeup_warning(tmp_path: Path) -> Nassert completed["findingCount"] == 1assert len(completed["warnings"]) == 1assert completed["warnings"][0].startswith("Skipped missing writeup for finding 1:")+ assert (+ json.loads((scan_dir / "scan-manifest.json").read_text())["scan"]["warnings"]+ == completed["warnings"]+ )finding = json.loads(path.read_text())["findings"][0]assert finding["summary"] == document["findings"][0]["summary"]assert "writeup" not in findingdiff --git a/plugins/codex-security/tests/test_workbench_standard_deep_results.py b/plugins/codex-security/tests/test_workbench_standard_deep_results.pyindex 45016127b..1df180120 100644--- a/plugins/codex-security/tests/test_workbench_standard_deep_results.py+++ b/plugins/codex-security/tests/test_workbench_standard_deep_results.py@@ -830,6 +830,15 @@ def test_canceled_scan_retries_failed_publication_from_frozen_sources(assert not any("result publication needs follow-up" in warning for warning in warnings)assert "Recovered finding 1: normalized severity change conditions." in warningsassert preserved["warnings"] == warnings+ assert json.loads((scan_dir / "scan-manifest.json").read_text())["scan"]["warnings"] == warnings+ sarif = json.loads((scan_dir / "exports/results.sarif").read_text())+ invocation = sarif["runs"][0]["invocations"][0]+ assert invocation["executionSuccessful"] is False+ assert all(+ {"level": "warning", "message": {"text": warning}}+ in invocation["toolExecutionNotifications"]+ for warning in warnings+ )@pytest.mark.parametrize("deep_status", ["failed", "interrupted"])diff --git a/sdk/typescript/src/models.ts b/sdk/typescript/src/models.tsindex 0f8f0c44d..17118f99f 100644--- a/sdk/typescript/src/models.ts+++ b/sdk/typescript/src/models.ts@@ -11,6 +11,7 @@ export interface ScanManifest {[k: string]: unknown;};status: "completed" | "failed" | "canceled" | "interrupted";+ warnings?: string[];startedAt: string;completedAt: string;sealedAt: string;diff --git a/sdk/typescript/tests-ts/artifact-export.test.ts b/sdk/typescript/tests-ts/artifact-export.test.tsindex cd3f44a6b..bffb9f091 100644--- a/sdk/typescript/tests-ts/artifact-export.test.ts+++ b/sdk/typescript/tests-ts/artifact-export.test.ts@@ -38,6 +38,66 @@ const caseInsensitiveVolume = await stat(join(caseProbe, "REPORTS")).then(await rm(caseProbe, { recursive: true, force: true });describe("offline artifact export", () => {+ test.each([+ { warnings: undefined },+ { warnings: [] },+ { warnings: ["Synthetic run warning."] },+ ])(+ "exports persisted run warnings %j without changing sealed documents",+ async ({ warnings }) => {+ const root = await mkdtemp(+ join(tmpdir(), "codex-security-sarif-warning-"),+ );+ const scanDir = join(root, "scan");+ const output = join(root, "results.sarif");+ try {+ await cp(join(PLUGIN_ROOT, "examples", "completed-scan"), scanDir, {+ recursive: true,+ });+ const manifestPath = join(scanDir, "scan-manifest.json");+ if (warnings !== undefined) {+ const manifest = JSON.parse(await readFile(manifestPath, "utf8"));+ manifest.scan.warnings = warnings;+ await writeFile(manifestPath, JSON.stringify(manifest));+ }+ const canonicalPaths = [+ manifestPath,+ join(scanDir, "findings.json"),+ join(scanDir, "coverage.json"),+ ];+ const before = await Promise.all(+ canonicalPaths.map((path) => readFile(path)),+ );+ const result = await exportArtifact({+ source: { directory: scanDir },+ format: "sarif",+ output,+ pythonPath: PYTHON,+ });+ expect(result.path).toBe(output);+ const run = JSON.parse(await readFile(output, "utf8")).runs[0];+ if (warnings?.length) {+ expect(run.invocations).toEqual([+ {+ executionSuccessful: true,+ toolExecutionNotifications: warnings.map((text) => ({+ level: "warning",+ message: { text },+ })),+ },+ ]);+ } else {+ expect(run.invocations).toBeUndefined();+ }+ expect(+ await Promise.all(canonicalPaths.map((path) => readFile(path))),+ ).toEqual(before);+ } finally {+ await rm(root, { recursive: true, force: true });+ }+ },+ );+test.skipIf(process.platform === "win32").each([["artifact helper", "PATH"],["artifact helper", "PYTHON"],