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(logs): stream large saved scan JSON output (#932)

mldangelo-oai480b8a341488
diff --git a/sdk/typescript/scripts/check-package.mjs b/sdk/typescript/scripts/check-package.mjs
index f78271374..04d8c56e2 100644
--- a/sdk/typescript/scripts/check-package.mjs
+++ b/sdk/typescript/scripts/check-package.mjs
@@ -170,6 +170,7 @@ const distFiles = new Set(
"auth",
"bulk-scan-discovery",
"cli",
+ "cli-scan-logs-json",
"classify-severity",
"classify-scan-severity",
"severity-store",
diff --git a/sdk/typescript/src/cli-scan-logs-json.ts b/sdk/typescript/src/cli-scan-logs-json.ts
new file mode 100644
index 000000000..8bceaacc5
--- /dev/null
+++ b/sdk/typescript/src/cli-scan-logs-json.ts
@@ -0,0 +1,31 @@
+import { Formatter } from "incur";
+import type { readSavedScanLogs } from "./scan-logs.js";
+
+// Format records separately: a saved log document can exceed the runtime's
+// maximum string length even though each session and event fits comfortably.
+export async function* scanLogsJson(
+ logs: Awaited<ReturnType<typeof readSavedScanLogs>>,
+ cta?: unknown,
+): AsyncGenerator<Uint8Array> {
+ yield Buffer.from(
+ `{\n "scanId": ${JSON.stringify(logs.scanId)},\n "threadId": ${JSON.stringify(logs.threadId)}`,
+ );
+ for (const key of ["sessions", "events"] as const) {
+ yield Buffer.from(`,\n "${key}": [`);
+ let first = true;
+ for (const record of logs[key]) {
+ const formatted = Formatter.format(record, "json").replaceAll(
+ "\n",
+ "\n ",
+ );
+ yield Buffer.from(`${first ? "\n" : ",\n"} ${formatted}`);
+ first = false;
+ }
+ yield Buffer.from(first ? "]" : "\n ]");
+ }
+ if (cta !== undefined) {
+ const formatted = Formatter.format(cta, "json").replaceAll("\n", "\n ");
+ yield Buffer.from(`,\n "cta": ${formatted}`);
+ }
+ yield Buffer.from("\n}\n");
+}
diff --git a/sdk/typescript/src/cli.ts b/sdk/typescript/src/cli.ts
index e5bccc3bf..d369b3ead 100644
--- a/sdk/typescript/src/cli.ts
+++ b/sdk/typescript/src/cli.ts
@@ -45,6 +45,7 @@ import { pipeline } from "node:stream/promises";
import { fileURLToPath, pathToFileURL } from "node:url";
import { promisify, stripVTControlCharacters } from "node:util";
import { Cli, z } from "incur";
+import { scanLogsJson } from "./cli-scan-logs-json.js";
import { parse as parseToml } from "smol-toml";
import {
classifyConnectionFailure,
@@ -1777,6 +1778,7 @@ export async function main(
let exitCode = 0;
let frameworkExit: number | undefined;
let frameworkOutput = "";
+ let streamedLogs: Awaited<ReturnType<typeof readSavedScanLogs>> | undefined;
let renderedHistory: string | undefined;
let renderedPublication: string | undefined;
let renderedPolicy: string | undefined;
@@ -2124,18 +2126,33 @@ export async function main(
.describe("Scan identifier or unique prefix (default: latest)."),
}),
output: z.record(z.string(), z.unknown()).optional(),
- async run({ args }) {
+ async run({ args, format }) {
const scanId =
args.scanId ?? (await latestScans(1, "any"))?.[0]?.scanId;
if (scanId === undefined) return;
- return await history(
+ const result = await history(
["get-scan", "--scan-id", scanId],
- async (value) =>
- (await readSavedScanLogs(
+ async (value) => {
+ const logs = await readSavedScanLogs(
value["scan"] as ScanLogSource,
codexSecurityCredentialHome(dependencies.environment),
- )) as unknown as JsonObject,
+ );
+ // Incur owns filtering, envelopes and token controls. Keep those
+ // requests on its formatter; plain JSON needs no aggregate string.
+ if (
+ format === "json" &&
+ !argv.some((argument) =>
+ /^--(?:filter-output|full-output|token-count|token-limit|token-offset)(?:=|$)/u.test(
+ argument,
+ ),
+ )
+ ) {
+ streamedLogs = logs;
+ }
+ return logs as unknown as JsonObject;
+ },
);
+ return streamedLogs === undefined ? result : undefined;
},
})
.command("resume", {
@@ -5686,11 +5703,21 @@ export async function main(
return 2;
}
}
- if (frameworkOutput.length === 0) return exitCode;
+ if (frameworkOutput.length === 0 && streamedLogs === undefined)
+ return exitCode;
try {
+ // Incur can add a stale-skills CTA after the logs handler returns.
+ const logOutput =
+ streamedLogs === undefined
+ ? undefined
+ : scanLogsJson(
+ streamedLogs,
+ frameworkOutput ? JSON.parse(frameworkOutput).cta : undefined,
+ );
await writeCliOutput(
output,
- renderedPolicy ??
+ logOutput ??
+ renderedPolicy ??
renderedPatch ??
renderedPublication ??
renderedHistory ??
diff --git a/sdk/typescript/tests-ts/cli-scan-logs.test.ts b/sdk/typescript/tests-ts/cli-scan-logs.test.ts
new file mode 100644
index 000000000..04f31c44d
--- /dev/null
+++ b/sdk/typescript/tests-ts/cli-scan-logs.test.ts
@@ -0,0 +1,319 @@
+import { execFile } from "node:child_process";
+import { mkdir, mkdtemp, realpath, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { Writable } from "node:stream";
+import { promisify } from "node:util";
+import { pathToFileURL } from "node:url";
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { Cli, Formatter, z } from "incur";
+import { main } from "../src/cli.js";
+import { scanLogsJson } from "../src/cli-scan-logs-json.js";
+import { readSavedScanLogs } from "../src/scan-logs.js";
+import { VERSION } from "../src/version.js";
+import { capture, dependencies } from "./cli-fixtures.js";
+
+async function fixture() {
+ const state = await realpath(await mkdtemp(join(tmpdir(), "saved-logs-")));
+ const home = join(state, "codex-home");
+ await mkdir(join(home, "sessions"), { recursive: true });
+ const events = [
+ { type: "session_meta", payload: { id: "thread-1" } },
+ {
+ type: "event_msg",
+ payload: {
+ message: 'full values: \" \\ \n \u0000 😀',
+ nested: [null, false, 2],
+ },
+ },
+ ];
+ await writeFile(
+ join(home, "sessions", "rollout.jsonl"),
+ events.map((event) => JSON.stringify(event)).join("\n"),
+ );
+ const scan = { scanId: "scan-1", continuationThreadId: "thread-1" };
+ const logs = await readSavedScanLogs(scan, home);
+ const deps = dependencies({
+ environment: { CODEX_SECURITY_STATE_DIR: state },
+ onWorkbench: () => ({ scan }),
+ });
+ deps.createSecurity = () => {
+ throw new Error("Reading logs must not start Codex");
+ };
+ return { state, logs, deps };
+}
+
+async function referenceOutput(args: string[], logs: unknown) {
+ let text = "";
+ await Cli.create("codex-security", { version: VERSION, update: false })
+ .command(
+ Cli.create("scans").command("logs", {
+ args: z.object({ scanId: z.string() }),
+ run: () => logs,
+ }),
+ )
+ .serve(["scans", "logs", "scan-1", ...args], {
+ stdout: (value) => {
+ text += value;
+ },
+ });
+ return text;
+}
+
+function withoutDuration(text: string) {
+ const value = JSON.parse(text);
+ value.meta.duration = "duration";
+ return value;
+}
+
+describe("saved logs JSON output", () => {
+ let dataHome: string;
+ let previousDataHome: string | undefined;
+
+ beforeEach(async () => {
+ previousDataHome = process.env["XDG_DATA_HOME"];
+ dataHome = await mkdtemp(join(tmpdir(), "saved-logs-data-"));
+ process.env["XDG_DATA_HOME"] = dataHome;
+ });
+
+ afterEach(async () => {
+ if (previousDataHome === undefined) delete process.env["XDG_DATA_HOME"];
+ else process.env["XDG_DATA_HOME"] = previousDataHome;
+ await rm(dataHome, { recursive: true, force: true });
+ });
+
+ test("preserves the stale installed-skills CTA after saved logs", async () => {
+ const f = await fixture();
+ try {
+ const skillPath = join(f.state, "skills", "codex-security-scans");
+ await mkdir(join(dataHome, "incur"), { recursive: true });
+ await mkdir(skillPath, { recursive: true });
+ await writeFile(
+ join(skillPath, "SKILL.md"),
+ "Previously installed skill.",
+ );
+ await writeFile(
+ join(dataHome, "incur", "codex-security.json"),
+ JSON.stringify({
+ hash: "previous-command-hash",
+ skills: ["codex-security-scans"],
+ paths: [skillPath],
+ }),
+ );
+ for (const args of [
+ ["--json"],
+ ["--format", "json"],
+ ["--format=json"],
+ ]) {
+ const stdout = capture();
+ const stderr = capture();
+ expect(
+ await main(
+ ["scans", "logs", "scan-1", ...args],
+ stdout.stream,
+ stderr.stream,
+ f.deps,
+ ),
+ ).toBe(0);
+ const expected = await referenceOutput(["--json"], f.logs);
+ expect(Object.keys(JSON.parse(expected))).toEqual([
+ "scanId",
+ "threadId",
+ "sessions",
+ "events",
+ "cta",
+ ]);
+ expect(stdout.text()).toBe(expected);
+ expect(stderr.text()).toBe("");
+ }
+ } finally {
+ await rm(f.state, { recursive: true, force: true });
+ }
+ });
+
+ test.each(
+ [
+ [],
+ ["--json"],
+ ["--format", "json"],
+ ["--format=json"],
+ ["--format", "toon"],
+ ["--format", "jsonl"],
+ ["--format", "yaml"],
+ ["--format", "md"],
+ ["--json", "--format", "toon"],
+ ["--format", "toon", "--json"],
+ ["--json", "--filter-output", "scanId"],
+ ["--json", "--filter-output", "events[0,1]"],
+ ["--json", "--filter-output", "missing"],
+ ["--json", "--filter-output", "scanId,threadId"],
+ ["--json", "--token-count"],
+ ["--json", "--token-limit", "4"],
+ ["--json", "--token-offset", "1", "--token-limit", "4"],
+ ["--json", "--token-offset", "999999"],
+ ["--json", "--token-limit", "999999"],
+ ["--json", "--full-output"],
+ ["--json", "--full-output", "--filter-output", "scanId"],
+ ["--json", "--full-output", "--token-limit", "4"],
+ ["--json", "--full-output", "--token-count"],
+ ].map((args) => [args]),
+ )("preserves Incur output for %j", async (args) => {
+ const f = await fixture();
+ try {
+ const stdout = capture();
+ const stderr = capture();
+ expect(
+ await main(
+ ["scans", "logs", "scan-1", ...args],
+ stdout.stream,
+ stderr.stream,
+ f.deps,
+ ),
+ ).toBe(0);
+ const expected = await referenceOutput(
+ args.flatMap((arg) =>
+ arg === "--format=json" ? ["--format", "json"] : [arg],
+ ),
+ f.logs,
+ );
+ if (args.includes("--full-output") && !args.includes("--token-count")) {
+ expect(withoutDuration(stdout.text())).toEqual(
+ withoutDuration(expected),
+ );
+ } else {
+ expect(stdout.text()).toBe(expected);
+ }
+ expect(stderr.text()).toBe("");
+ } finally {
+ await rm(f.state, { recursive: true, force: true });
+ }
+ });
+
+ test.each(
+ [
+ ["--format", "invalid"],
+ ["--format=invalid"],
+ ["--json", "--token-limit", "invalid"],
+ ["--json", "--token-offset", "invalid"],
+ ["--json", "--filter-output"],
+ ].map((args) => [args]),
+ )("preserves invalid-option failure for %j", async (args) => {
+ const stdout = capture();
+ const stderr = capture();
+ expect(
+ await main(
+ ["scans", "logs", "scan-1", ...args],
+ stdout.stream,
+ stderr.stream,
+ dependencies(),
+ ),
+ ).toBe(2);
+ expect(stdout.text()).toBe("");
+ expect(stderr.text()).not.toBe("");
+ });
+
+ test("formats empty session and event lists", async () => {
+ const logs = {
+ scanId: "scan-1",
+ threadId: "thread-1",
+ sessions: [],
+ events: [],
+ };
+ const chunks = [];
+ for await (const chunk of scanLogsJson(logs)) chunks.push(chunk);
+ expect(Buffer.concat(chunks).toString()).toBe(
+ `${Formatter.format(logs, "json")}\n`,
+ );
+ });
+
+ test("waits for output backpressure and leaves the stream open", async () => {
+ const f = await fixture();
+ try {
+ const chunks: Buffer[] = [];
+ const output = new Writable({
+ highWaterMark: 1,
+ write(chunk, _encoding, callback) {
+ setImmediate(() => {
+ chunks.push(Buffer.from(chunk));
+ callback();
+ });
+ },
+ });
+ expect(
+ await main(
+ ["scans", "logs", "scan-1", "--json"],
+ output,
+ capture().stream,
+ f.deps,
+ ),
+ ).toBe(0);
+ expect(Buffer.concat(chunks).toString()).toBe(
+ `${Formatter.format(f.logs, "json")}\n`,
+ );
+ expect(output.writableEnded).toBe(false);
+ expect(output.listenerCount("error")).toBe(0);
+ } finally {
+ await rm(f.state, { recursive: true, force: true });
+ }
+ });
+
+ test("reports a failed output write", async () => {
+ const f = await fixture();
+ try {
+ const stderr = capture();
+ const output = new Writable({
+ write(_chunk, _encoding, callback) {
+ callback(new Error("synthetic write failure"));
+ },
+ });
+ expect(
+ await main(
+ ["scans", "logs", "scan-1", "--json"],
+ output,
+ stderr.stream,
+ f.deps,
+ ),
+ ).toBe(2);
+ expect(stderr.text()).toContain("synthetic write failure");
+ } finally {
+ await rm(f.state, { recursive: true, force: true });
+ }
+ });
+
+ test("writes a complete document larger than Node's maximum string", async () => {
+ // Keep the bundle beneath the SDK so external dependencies resolve normally.
+ const bundle = await mkdtemp(
+ join(import.meta.dir, "..", ".logs-boundary-"),
+ );
+ const state = await mkdtemp(join(tmpdir(), "large-saved-logs-"));
+ try {
+ const built = await Bun.build({
+ entrypoints: [join(import.meta.dir, "support", "cli-logs-large.mts")],
+ outdir: bundle,
+ target: "node",
+ packages: "external",
+ });
+ expect(built.success).toBe(true);
+ const result = await promisify(execFile)(
+ "node",
+ [
+ "--input-type=module",
+ "--eval",
+ `await import(${JSON.stringify(pathToFileURL(built.outputs[0]!.path).href)})`,
+ "synthetic-launcher",
+ state,
+ ],
+ { encoding: "utf8" },
+ );
+ const proof = JSON.parse(result.stdout);
+ expect(proof.exitCode).toBe(0);
+ expect(proof.bytes).toBeGreaterThan(proof.maximumStringLength);
+ expect(proof.bytes).toBe(proof.expectedBytes);
+ expect(proof.sha256).toBe(proof.expectedSha256);
+ expect(result.stderr).toBe("");
+ } finally {
+ await rm(bundle, { recursive: true, force: true });
+ await rm(state, { recursive: true, force: true });
+ }
+ });
+});
diff --git a/sdk/typescript/tests-ts/support/cli-logs-large.mts b/sdk/typescript/tests-ts/support/cli-logs-large.mts
new file mode 100644
index 000000000..2ac765fbd
--- /dev/null
+++ b/sdk/typescript/tests-ts/support/cli-logs-large.mts
@@ -0,0 +1,92 @@
+import { constants } from "node:buffer";
+import { createHash } from "node:crypto";
+import { mkdir, open, realpath } from "node:fs/promises";
+import { join } from "node:path";
+import { Writable } from "node:stream";
+import { main } from "../../src/cli.js";
+import { dependencies } from "../cli-fixtures.js";
+
+const state = await realpath(process.argv[2]!);
+const sessions = join(state, "codex-home", "sessions");
+await mkdir(sessions, { recursive: true });
+const path = join(sessions, "rollout.jsonl");
+const metadata = { type: "session_meta", payload: { id: "thread-1" } };
+let payload: unknown = Array(4096).fill(0);
+// Pretty indentation expands a small input into a large document economically.
+for (let i = 0; i < 32; i++) payload = { nested: payload };
+const event = (sequence: number) => ({ type: "event_msg", sequence, payload });
+const header = {
+ scanId: "scan-1",
+ threadId: "thread-1",
+ sessions: [{ threadId: "thread-1", parentThreadId: null, path }],
+ events: [{ threadId: "thread-1", event: metadata }],
+};
+const first = JSON.stringify(header, null, 2);
+const prefix = first.slice(0, first.lastIndexOf("\n ]"));
+const suffix = "\n ]\n}\n";
+const record = (sequence: number) =>
+ JSON.stringify(
+ { events: [{ threadId: "thread-1", event: event(sequence) }] },
+ null,
+ 2,
+ ).slice('{\n "events": [\n'.length, -"\n ]\n}".length);
+const count = Math.ceil(constants.MAX_STRING_LENGTH / record(0).length) + 1;
+const expected = createHash("sha256");
+let expectedBytes = 0;
+function expectChunk(text: string) {
+ expected.update(text);
+ expectedBytes += Buffer.byteLength(text);
+}
+expectChunk(prefix);
+const file = await open(path, "wx");
+try {
+ await file.write(`${JSON.stringify(metadata)}\n`);
+ for (let i = 0; i < count; i++) {
+ await file.write(`${JSON.stringify(event(i))}\n`);
+ expectChunk(`,\n${record(i)}`);
+ }
+} finally {
+ await file.close();
+}
+expectChunk(suffix);
+let bytes = 0;
+const actual = createHash("sha256");
+const output = new Writable({
+ write(chunk, _encoding, callback) {
+ bytes += chunk.length;
+ actual.update(chunk);
+ callback();
+ },
+});
+const deps = dependencies({
+ environment: { CODEX_SECURITY_STATE_DIR: state },
+ onWorkbench: () => ({
+ scan: { scanId: "scan-1", continuationThreadId: "thread-1" },
+ }),
+});
+deps.createSecurity = () => {
+ throw new Error("Reading logs must not start Codex");
+};
+try {
+ const exitCode = await main(
+ ["scans", "logs", "scan-1", "--json"],
+ output,
+ process.stderr,
+ deps,
+ );
+ console.log(
+ JSON.stringify({
+ exitCode,
+ bytes,
+ sha256: actual.digest("hex"),
+ expectedBytes,
+ expectedSha256: expected.digest("hex"),
+ maximumStringLength: constants.MAX_STRING_LENGTH,
+ events: count + 1,
+ }),
+ );
+ process.exitCode = exitCode;
+} catch (error) {
+ console.error(error);
+ process.exitCode = 2;
+}