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: improve SARIF exports for GitHub (#570)
ianw-oai83b5a74f285d
diff --git a/sdk/typescript/_bundled_plugin/references/sarif-adapter.md b/sdk/typescript/_bundled_plugin/references/sarif-adapter.mdindex 84bef3ad0..9df8c5e7c 100644--- a/sdk/typescript/_bundled_plugin/references/sarif-adapter.md+++ b/sdk/typescript/_bundled_plugin/references/sarif-adapter.md@@ -8,12 +8,14 @@ The adapter:- stores SARIF separately from the canonical seal- emits SARIF 2.1.0- uses stable `ruleId` values-- keeps rule descriptors stable across scans+- derives stable, readable rule names from `ruleId`+- includes categories, CWE tags, and canonical remediation in rule help and result messages- emits repository-relative POSIX paths- keeps the root-control location first for GitHub annotation when available and emits every distinct affected or code-evidence location in `locations`, so vulnerable sinks remain matchable- preserves the semantic fingerprint under `codexSecurity/v1`- emits GitHub's source-line `primaryLocationLineHash` when it can safely hash a bounded regular non-symlink source file inside the available source root- maps categorical severity to SARIF `level`+- sets GitHub's rule-level `security-severity` to the highest finding score. Unscored critical, high, medium, low, and informational findings use 9.5, 8.0, 5.0, 2.0, and 0.0. A rule with no positive score omits this field. These defaults are display values, not calculated CVSS scores.- preserves a deep scan's canonical `candidateId` under each child result's properties so consumers can group results without changing the original SARIF result presentationLifecycle, rich validation evidence, attack-path context, and coverage are lossy or omitted in SARIF. Preserve them in semantic JSON.diff --git a/sdk/typescript/_bundled_plugin/scripts/finalize_scan_contract.py b/sdk/typescript/_bundled_plugin/scripts/finalize_scan_contract.pyindex e84b0d7b9..198a101e1 100644--- a/sdk/typescript/_bundled_plugin/scripts/finalize_scan_contract.py+++ b/sdk/typescript/_bundled_plugin/scripts/finalize_scan_contract.py@@ -51,6 +51,13 @@ SARIF_LEVELS = {"low": "note","informational": "note",}+SARIF_SECURITY_SCORES = {+ "critical": 9.5,+ "high": 8.0,+ "medium": 5.0,+ "low": 2.0,+ "informational": 0.0,+}SLUG_RE = re.compile(r"^[a-z0-9][a-z0-9._/-]*$")RFC3339_RE = re.compile(r"^\d{4}-\d{2}-\d{2}[Tt]\d{2}:\d{2}:\d{2}(?:\.\d+)?(?:[Zz]|[+-]\d{2}:\d{2})$"@@ -1701,15 +1708,67 @@ def _validate_contract_refs(scan: dict[str, Any]) -> None:raise ContractError(f"manifest.scan.{field}: expected {expected!r}")-def _sarif_rule(rule_id: str) -> dict[str, Any]:+def _sarif_label(value: str) -> str:+ words = re.sub(r"[-_./]+", " ", value).split()+ acronyms = {"api", "csrf", "html", "http", "id", "rce", "sql", "ssrf", "url", "xml", "xss"}+ label = " ".join(word.upper() if word.lower() in acronyms else word for word in words)+ return label[:1].upper() + label[1:]+++def _sarif_rule(rule_id: str, findings: list[dict[str, Any]]) -> dict[str, Any]:+ name = ": ".join(_sarif_label(part) for part in rule_id.split("."))+ categories = sorted({finding["taxonomy"]["category"] for finding in findings})+ cwes = sorted({cwe for finding in findings for cwe in finding["taxonomy"]["cwe"]})+ tags = {"security", *categories}+ for cwe in cwes:+ match = re.fullmatch(r"CWE-([0-9]+)", cwe, re.IGNORECASE)+ if match and int(match[1]) > 0:+ tags.add(f"external/cwe/cwe-{int(match[1]):03d}")+ description = f"{name}. Categories: {', '.join(map(_sarif_label, categories))}."+ if cwes:+ description += f" Weaknesses: {', '.join(cwes)}."+ remediation = "\n\n".join(sorted({finding["remediation"] for finding in findings}))+ properties: dict[str, Any] = {"tags": sorted(tags)}+ # GitHub assigns security severity to the shared rule, not each result.+ score = max(+ finding["severity"].get("score", SARIF_SECURITY_SCORES[finding["severity"]["level"]])+ for finding in findings+ )+ if score > 0:+ properties["security-severity"] = str(score)return {"id": rule_id,- "name": rule_id,- "shortDescription": {"text": rule_id},- "properties": {"tags": ["security"]},+ "name": name,+ "shortDescription": {"text": name},+ "fullDescription": {"text": description},+ "help": {+ "text": f"{description}\n\nRemediation:\n\n{remediation}",+ "markdown": f"{description}\n\n## Remediation\n\n{remediation}",+ },+ "properties": properties,}+def _sarif_finding_message(finding: dict[str, Any]) -> str:+ taxonomy = finding["taxonomy"]+ details = [+ finding["title"],+ finding["summary"],+ f"Severity: {finding['severity']['level']}",+ f"Category: {_sarif_label(taxonomy['category'])}",+ ]+ if taxonomy["cwe"]:+ details.append(f"Weaknesses: {', '.join(taxonomy['cwe'])}")+ details.append(f"Remediation:\n{finding['remediation']}")+ for key, label in (+ ("remediationTests", "Remediation tests"),+ ("preventiveControls", "Preventive controls"),+ ):+ if finding.get(key):+ details.append(f"{label}:\n" + "\n".join(f"- {item}" for item in finding[key]))+ return "\n\n".join(details)++def _utf16_code_units(value: str) -> Iterator[int]:encoded = value.encode("utf-16-le")for index in range(0, len(encoded), 2):@@ -2013,7 +2072,7 @@ def _sarif_result("ruleId": finding["ruleId"],"ruleIndex": rule_index,"level": SARIF_LEVELS[finding["severity"]["level"]],- "message": {"text": finding["summary"]},+ "message": {"text": _sarif_finding_message(finding)},"locations": [_sarif_location(location) for location in _sarif_locations(finding)],"partialFingerprints": partial_fingerprints,"properties": properties,@@ -2038,7 +2097,9 @@ def build_sarif("driver": {"name": "Codex Security","version": scan["producer"]["version"],- "rules": [_sarif_rule(rule_id) for rule_id in ordered_rule_ids],+ "rules": [+ _sarif_rule(rule_id, findings_by_rule[rule_id]) for rule_id in ordered_rule_ids+ ],}},"automationDetails": {"id": scan["id"]},diff --git a/sdk/typescript/tests-ts/cli-export.test.ts b/sdk/typescript/tests-ts/cli-export.test.tsindex 3ea2f66af..37e7f6bec 100644--- a/sdk/typescript/tests-ts/cli-export.test.ts+++ b/sdk/typescript/tests-ts/cli-export.test.ts@@ -342,6 +342,13 @@ describe("CLI", () => {const directory = await mkdtemp(join(tmpdir(), "codex-security-export-"));try {const scan = await copyCompletedScan(directory);+ const paths = [+ "scan-manifest.json",+ "findings.json",+ "coverage.json",+ ].map((name) => join(scan, name));+ const before = await Promise.all(paths.map((path) => readFile(path)));+ const source = JSON.parse(before[1]!.toString()).findings[0];for (const [format, filename] of [["csv", "findings.csv"],["json", "findings.json"],@@ -365,13 +372,36 @@ describe("CLI", () => {documentType: "codex-security.findings",});} else {- expect(JSON.parse(contents)).toMatchObject({ version: "2.1.0" });+ const sarif = JSON.parse(contents);+ expect(sarif.version).toBe("2.1.0");+ const run = sarif.runs[0];+ expect(run.tool.driver.rules[0]).toMatchObject({+ id: source.ruleId,+ help: { markdown: expect.stringContaining(source.remediation) },+ properties: {+ "security-severity": "8.1",+ tags: expect.arrayContaining([+ "security",+ "external/cwe/cwe-022",+ ]),+ },+ });+ expect(run.results[0]).toMatchObject({+ ruleId: source.ruleId,+ message: { text: expect.stringContaining(source.remediation) },+ partialFingerprints: {+ "codexSecurity/v1": source.fingerprints.primary,+ },+ });}if (process.platform !== "win32")expect((await stat(output)).mode & 0o777).toBe(0o600);expect(stdout.text()).toBe("");expect(stderr.text()).toBe(`${format.toUpperCase()}: ${output}\n`);}+ expect(await Promise.all(paths.map((path) => readFile(path)))).toEqual(+ before,+ );} finally {await rm(directory, { recursive: true, force: true });}diff --git a/sdk/typescript/tests-ts/sarif.test.ts b/sdk/typescript/tests-ts/sarif.test.tsnew file mode 100644index 000000000..56c0d94a6--- /dev/null+++ b/sdk/typescript/tests-ts/sarif.test.ts@@ -0,0 +1,158 @@+import { spawnSync } from "node:child_process";+import { readFile } from "node:fs/promises";+import { join } from "node:path";+import { describe, expect, test } from "bun:test";+import type { Finding, FindingsDocument } from "../src/models.js";+import { PLUGIN_ROOT } from "./plugin-root.js";++const example = join(PLUGIN_ROOT, "examples", "completed-scan");+const manifest = JSON.parse(+ await readFile(join(example, "scan-manifest.json"), "utf8"),+);+const document = JSON.parse(+ await readFile(join(example, "findings.json"), "utf8"),+) as FindingsDocument;++function finding(overrides: Partial<Finding> = {}): Finding {+ return { ...document.findings[0]!, ...overrides };+}++function buildSarif(findings: Finding[]) {+ const python = Bun.which("python3") ?? Bun.which("python");+ expect(python).not.toBeNull();+ const result = spawnSync(+ python!,+ [+ "-I",+ "-B",+ "-c",+ [+ "import json, sys",+ "sys.path.insert(0, sys.argv[1])",+ "from finalize_scan_contract import build_sarif",+ "payload = json.load(sys.stdin)",+ "print(json.dumps(build_sarif(payload['manifest'], payload['findings'])['runs'][0]))",+ ].join("\n"),+ join(PLUGIN_ROOT, "scripts"),+ ],+ {+ encoding: "utf8",+ input: JSON.stringify({ manifest, findings: { ...document, findings } }),+ },+ );+ expect(result.status, result.stderr).toBe(0);+ return JSON.parse(result.stdout);+}++describe("SARIF presentation", () => {+ test("keeps rule names and alert identity independent of finding text", () => {+ const source = finding({+ extensions: { candidateId: "candidate-example" },+ });+ const run = buildSarif([source]);+ const rule = run.tool.driver.rules[0];+ const result = run.results[0];+ expect(rule.name).not.toBe(source.ruleId);+ expect(rule.shortDescription.text).toBe(rule.name);+ expect(rule.help.text).toContain(source.remediation);+ expect(result.properties).toMatchObject({+ findingId: source.findingId,+ occurrenceId: source.occurrenceId,+ candidateId: "candidate-example",+ });+ for (const text of [+ source.title,+ source.summary,+ ...source.remediationTests!,+ ...source.preventiveControls!,+ ]) {+ expect(result.message.text).toContain(text);+ }++ const changed = buildSarif([+ {+ ...source,+ title: "A new title",+ summary: "A changed summary",+ remediation: "A different fix.",+ },+ ]);+ expect(changed.tool.driver.rules[0].name).toBe(rule.name);+ for (const key of [+ "ruleId",+ "ruleIndex",+ "locations",+ "partialFingerprints",+ "properties",+ ]) {+ expect(changed.results[0][key]).toEqual(result[key]);+ }+ });++ test("merges shared rule metadata without mixing result remediation", () => {+ const first = finding({+ occurrenceId: `occ_${"1".repeat(24)}`,+ severity: { level: "low" },+ remediation: "Apply the first control.",+ });+ const second = finding({+ occurrenceId: `occ_${"2".repeat(24)}`,+ severity: { level: "critical", score: 9.7, scoringSystem: "CVSS:3.1" },+ taxonomy: {+ category: "archive-extraction",+ cwe: ["cwe-022", "CWE-23", "unknown"],+ },+ remediation: "Apply the second control.",+ });+ const run = buildSarif([first, second]);+ expect(buildSarif([second, first])).toEqual(run);+ expect(run.tool.driver.rules).toHaveLength(1);+ const rule = run.tool.driver.rules[0];+ expect(rule.properties).toEqual({+ "security-severity": "9.7",+ tags: [+ "archive-extraction",+ "external/cwe/cwe-022",+ "external/cwe/cwe-023",+ "path-traversal",+ "security",+ ],+ });+ expect(rule.help.markdown).toContain(first.remediation);+ expect(rule.help.markdown).toContain(second.remediation);+ for (const [index, own, other] of [+ [0, first, second],+ [1, second, first],+ ] as const) {+ const result = run.results[index];+ expect(result.ruleIndex).toBe(0);+ expect(result.message.text).toContain(own.remediation);+ expect(result.message.text).not.toContain(other.remediation);+ expect(result.properties.severity).toBe(own.severity.level);+ }+ expect(run.results[0].level).toBe("note");+ });++ test.each([+ ["critical", undefined, "9.5"],+ ["high", undefined, "8.0"],+ ["medium", undefined, "5.0"],+ ["low", undefined, "2.0"],+ ["informational", undefined, undefined],+ ["high", 0, undefined],+ ["high", 6.25, "6.25"],+ ["critical", 10, "10"],+ ] as const)("maps %s severity with score %s", (level, score, expected) => {+ const severity =+ score === undefined+ ? { level }+ : { level, score, scoringSystem: "CVSS:3.1" };+ const run = buildSarif([+ finding({ severity, taxonomy: { category: "sql-injection", cwe: [] } }),+ ]);+ expect(run.tool.driver.rules[0].properties).toEqual({+ tags: ["security", "sql-injection"],+ ...(expected === undefined ? {} : { "security-severity": expected }),+ });+ });+});