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

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.mts
index 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.md
index 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 Recovery
To 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.json
index 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.py
index 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_dir
scan = _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.py
index 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 annotations
import copy
import json
+import os
import shutil
import uuid
from 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.py
index 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.py
index 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 copy
import hashlib
import json
import os
+import shutil
import sqlite3
import subprocess
import 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) == 1
assert 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} == before
assert get_scan(state_dir, scan_id)["scan"]["warnings"] == warnings
assert scan_command(state_dir, "complete-scan", scan_id)["scan"]["warnings"] == warnings
[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) -> N
assert completed["findingCount"] == 1
assert len(completed["warnings"]) == 1
assert 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 finding
diff --git a/plugins/codex-security/tests/test_workbench_standard_deep_results.py b/plugins/codex-security/tests/test_workbench_standard_deep_results.py
index 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 warnings
assert 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.ts
index 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.ts
index 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"],