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(publish): explain findings before scan details (#689)
ianw-oai067281b9f572
diff --git a/plugins/codex-security/references/final-report.md b/plugins/codex-security/references/final-report.mdindex 5886eff61..8fa17bd1e 100644--- a/plugins/codex-security/references/final-report.md+++ b/plugins/codex-security/references/final-report.md@@ -118,7 +118,7 @@ Affected lines must include the root broken control or dangerous sink line whenThen render these subsections under each finding:- `#### Summary`- - Explain why the issue matters, what the vulnerable path is, and why the current controls are insufficient.+ - Start with how to reproduce the issue and what happens in the product, then explain why the code causes that behavior.- Wrap code identifiers, RPC names, functions, types, fields, parameters, configuration keys, and literal values in single backticks.- `#### Root Cause`- State the violated security invariant and explain exactly how the implementation breaks it.diff --git a/plugins/codex-security/references/finding-detail-fields.md b/plugins/codex-security/references/finding-detail-fields.mdindex da6979888..df5d5fa82 100644--- a/plugins/codex-security/references/finding-detail-fields.md+++ b/plugins/codex-security/references/finding-detail-fields.md@@ -4,6 +4,9 @@ For every reportable finding in `findings.json`, preserve the validated reasonin## Writing Rules+- Lead the title and `summary` with the user action and product impact.+- Use `attackPath.summary` to briefly explain how to reproduce the issue.+- Explain how the code causes that product behavior in `rootCause.summary`. Use plain language and avoid repetition.- Wrap RPC names, functions, types, fields, parameters, configuration keys, literal identifiers, and short expressions in single backticks. For example: `environment/add`, `environmentId`, `execServerUrl`, and `EnvironmentManager::upsert_environment()`.- Keep code out of prose. Put source snippets in `codeEvidence[].code`, then reference them from the section that explains why the snippet matters. The workspace consolidates those referenced snippets under **Root cause** so the violated invariant and its source proof stay together.- Root cause must be a source-backed walkthrough, not a verdict paragraph. Start with the code where user-controlled data is declared, decoded, or read; follow each meaningful call, transformation, or state transition; then show the missing control, dangerous operation, and later consumer when it affects impact.@@ -106,11 +109,7 @@ The following shape shows how to encode the `environment/add` reserved-environme"validation": {"method": "static source trace","summary": "The source trace confirms that an `environment/add` caller controls both inputs, the RPC forwards them unchanged, and runtime insertion accepts `local`.",- "evidenceRefs": [- "rpc-input",- "rpc-forward",- "runtime-upsert"- ],+ "evidenceRefs": ["rpc-input", "rpc-forward", "runtime-upsert"],"assertions": ["The runtime path lacks the reserved-ID check present during startup.","Inserting `local` replaces the existing `HashMap` entry."@@ -139,11 +138,7 @@ The following shape shows how to encode the `environment/add` reserved-environme"entrypoint": "experimental `environment/add` RPC","outcome": "future operations selected for `local` are routed to the remote executor"},- "evidenceRefs": [- "rpc-forward",- "runtime-upsert",- "default-lookup"- ],+ "evidenceRefs": ["rpc-forward", "runtime-upsert", "default-lookup"],"impact": {"level": "medium","why": "Later commands and filesystem requests selected for `local` can be routed to the attacker-controlled remote executor."diff --git a/plugins/codex-security/skills/track-findings/SKILL.md b/plugins/codex-security/skills/track-findings/SKILL.mdindex 93608afa0..e546e2c16 100644--- a/plugins/codex-security/skills/track-findings/SKILL.md+++ b/plugins/codex-security/skills/track-findings/SKILL.md@@ -132,6 +132,8 @@ Treat failed requests, incomplete exact-identifier searches, unread plausible ma### 4. Preview The Exact Writes+Follow the Writing Rules in `../../references/finding-detail-fields.md`. Explain the problem, how to reproduce it, the cause, the proposed fix, and validation. Put source locations and scan identifiers last.+Present a compact review before any mutation. For every finding show:- finding id and fingerprintdiff --git a/sdk/typescript/src/publication.ts b/sdk/typescript/src/publication.tsindex dfa3bef36..03f8a6719 100644--- a/sdk/typescript/src/publication.ts+++ b/sdk/typescript/src/publication.ts@@ -112,7 +112,50 @@ function renderFindingDescription(): string {const { coverage } = contract;const { scan } = contract.manifest;- const lines = [+ const lines = ["## Summary", "", finding.summary];++ if (finding.attackPath?.summary !== undefined) {+ lines.push("", "## Reproduction summary", "", finding.attackPath.summary);+ }++ const rootCause = finding.rootCause;+ if (typeof rootCause === "string") {+ lines.push("", "## Root cause", "", rootCause);+ } else if (rootCause !== undefined) {+ lines.push("", "## Root cause", "", rootCause.summary);+ if (rootCause.code !== undefined) {+ lines.push("", fencedCode(rootCause.code, rootCause.language));+ }+ }++ lines.push("", "## Remediation", "", finding.remediation);++ const validation = finding.validation;+ const limits = [+ ...new Set([+ ...(validation?.limitations ?? []),+ ...(validation?.counterEvidence ?? []),+ ...(finding.attackPath?.limitations ?? []),+ ]),+ ];+ if (validation?.summary || validation?.method || limits.length > 0) {+ lines.push("", "## Validation", "");+ if (validation?.summary) lines.push(validation.summary, "");+ if (validation?.method) lines.push(`**Method:** ${validation.method}`, "");+ lines.push(...limits.map((limit) => `- ${limit}`));+ }++ if (finding.codeEvidence !== undefined && finding.codeEvidence.length > 0) {+ lines.push("", "## Source-code evidence");+ for (const evidence of finding.codeEvidence) {+ lines.push("", ...renderCodeEvidence(scan.target, evidence));+ }+ }++ lines.push(+ "",+ "---",+ "","## Codex Security finding","",`**Scan ID:** ${scan.id}`,@@ -148,30 +191,7 @@ function renderFindingDescription(...finding.locations.map((location) =>renderLocation(scan.target, location),),- "",- "## Summary",- "",- finding.summary,- ];-- const rootCause = finding.rootCause;- if (typeof rootCause === "string") {- lines.push("", "## Root cause", "", rootCause);- } else if (rootCause !== undefined) {- lines.push("", "## Root cause", "", rootCause.summary);- if (rootCause.code !== undefined) {- lines.push("", fencedCode(rootCause.code, rootCause.language));- }- }-- if (finding.codeEvidence !== undefined && finding.codeEvidence.length > 0) {- lines.push("", "## Source-code evidence");- for (const evidence of finding.codeEvidence) {- lines.push("", ...renderCodeEvidence(scan.target, evidence));- }- }-- lines.push("", "## Remediation", "", finding.remediation);+ );return `${lines.join("\n")}\n`;}diff --git a/sdk/typescript/tests-ts/publication.test.ts b/sdk/typescript/tests-ts/publication.test.tsindex 5581d118e..ac969d4e5 100644--- a/sdk/typescript/tests-ts/publication.test.ts+++ b/sdk/typescript/tests-ts/publication.test.ts@@ -150,9 +150,58 @@ describe("scan publication preparation", () => {expect(issue.description).toContain("**Uploaded:** 2026-06-01T10:30:00Z");expect(issue.description).toContain("without containment validation");expect(issue.description).toContain("Normalize destinations");+ expect(+ issue.description.indexOf("without containment validation"),+ ).toBeLessThan(issue.description.indexOf("**Scan ID:**"));+ expect(issue.description.indexOf("Normalize destinations")).toBeLessThan(+ issue.description.indexOf("**Scan ID:**"),+ );expect(issue.description).not.toContain("/blob/deadbeef/");});+ test("keeps the reproduction and validation limits ahead of scan metadata", async () => {+ const scanDirectory = await copyExample();+ const findingsPath = join(scanDirectory, "findings.json");+ const findings = await readJson<FindingsDocument>(findingsPath);+ const finding = findings.findings[0]!;+ const reproduction =+ "Import an archive containing ../escape.txt. The importer should reject it; source review shows it writing outside the selected directory. This was not run.";+ const unrun = "No runtime reproduction was run.";+ const attackPath = {+ summary: reproduction,+ limitations: [unrun, "Files must be writable by the importing process."],+ };+ const validation = {+ method: "Source review",+ summary: "The importer passes the entry name to the filesystem write.",+ limitations: [unrun],+ counterEvidence: ["The user must first choose to import the archive."],+ };+ finding.attackPath = attackPath;+ finding.validation = validation;+ await writeJson(findingsPath, findings);+ await reseal(scanDirectory);++ const { description } = (+ await prepareScanPublication(scanDirectory, DESTINATION)+ ).issues[0]!;++ const metadata = description.indexOf("**Scan ID:**");+ for (const text of [+ finding.summary,+ reproduction,+ validation.summary,+ validation.method,+ ...validation.limitations,+ ...validation.counterEvidence,+ ...attackPath.limitations,+ ]) {+ expect(description).toContain(text);+ expect(description.indexOf(text)).toBeLessThan(metadata);+ }+ expect(description.split(unrun)).toHaveLength(2);+ });+test("uses the canonical scan directory beneath an aliased parent", async () => {const root = await mkdtemp(join(tmpdir(), "codex-security-publication-alias-"),