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(cli): include scan-owned Deep worker session logs (#426)

mldangelo-oai4174e38bcf88
diff --git a/sdk/typescript/src/cli.ts b/sdk/typescript/src/cli.ts
index 9f73b0489..89ac05e2f 100644
--- a/sdk/typescript/src/cli.ts
+++ b/sdk/typescript/src/cli.ts
@@ -976,6 +976,9 @@ export async function main(
const scan = value["scan"] as {
scanId: string;
continuationThreadId?: string;
+ mode?: string;
+ progress?: { status?: string; updatedAt?: string };
+ scanDir?: string;
};
const threadId = scan.continuationThreadId;
if (!threadId) {
@@ -987,6 +990,15 @@ export async function main(
scanId: scan.scanId,
threadId,
codexHome: codexSecurityCredentialHome(dependencies.environment),
+ scanDirectory: scan.mode === "deep" ? scan.scanDir : undefined,
+ completedAt:
+ scan.progress?.status === "running"
+ ? null
+ : scan.progress?.status === "complete" ||
+ scan.progress?.status === "failed" ||
+ scan.progress?.status === "canceled"
+ ? scan.progress.updatedAt ?? ""
+ : "",
})) as unknown as JsonObject;
},
);
diff --git a/sdk/typescript/src/scan-logs.ts b/sdk/typescript/src/scan-logs.ts
index 51673c1eb..36ca1164f 100644
--- a/sdk/typescript/src/scan-logs.ts
+++ b/sdk/typescript/src/scan-logs.ts
@@ -1,5 +1,6 @@
-import { readFile } from "node:fs/promises";
-import { join } from "node:path";
+import { createReadStream } from "node:fs";
+import { basename, dirname, isAbsolute, join, relative, sep } from "node:path";
+import { createInterface } from "node:readline";
import { sessionFiles } from "./cost.js";
import { CodexSecurityError } from "./errors.js";
@@ -7,53 +8,48 @@ interface ScanLogOptions {
scanId: string;
threadId: string;
codexHome: string;
+ scanDirectory?: string;
+ completedAt?: string | null;
}
interface SessionLog {
threadId: string;
parentThreadId: string | null;
startedAt: number | null;
+ workingDirectory: string | null;
path: string;
- events: Record<string, unknown>[];
}
export async function readScanLogs(options: ScanLogOptions) {
const logs = new Map<string, SessionLog>();
for await (const path of sessionFiles(join(options.codexHome, "sessions"))) {
- const events = (await readFile(path, "utf8"))
- .split("\n")
- .filter((line) => line.trim() !== "")
- .flatMap((line) => {
- try {
- const event: unknown = JSON.parse(line);
- return isRecord(event) ? [event] : [];
- } catch {
- return [];
- }
+ for await (const first of sessionEvents(path)) {
+ if (first["type"] !== "session_meta" || !isRecord(first["payload"])) {
+ break;
+ }
+ const metadata = first["payload"];
+ const threadId = metadata["id"];
+ if (typeof threadId !== "string") break;
+ const source = metadata["source"];
+ const subagent = isRecord(source) ? source["subagent"] : undefined;
+ const spawn = isRecord(subagent) ? subagent["thread_spawn"] : undefined;
+ const parent =
+ metadata["parent_thread_id"] ??
+ (isRecord(spawn) ? spawn["parent_thread_id"] : undefined);
+ const startedAt =
+ typeof metadata["timestamp"] === "string"
+ ? Date.parse(metadata["timestamp"])
+ : Number.NaN;
+ logs.set(threadId, {
+ threadId,
+ parentThreadId: typeof parent === "string" ? parent : null,
+ startedAt: Number.isFinite(startedAt) ? startedAt : null,
+ workingDirectory:
+ typeof metadata["cwd"] === "string" ? metadata["cwd"] : null,
+ path,
});
- const first = events[0];
- if (first?.["type"] !== "session_meta" || !isRecord(first["payload"])) {
- continue;
+ break;
}
- const metadata = first["payload"];
- const threadId = metadata["id"];
- if (typeof threadId !== "string") continue;
- const source = metadata["source"];
- const subagent = isRecord(source) ? source["subagent"] : undefined;
- const spawn = isRecord(subagent) ? subagent["thread_spawn"] : undefined;
- const parent =
- metadata["parent_thread_id"] ??
- (isRecord(spawn) ? spawn["parent_thread_id"] : undefined);
- logs.set(threadId, {
- threadId,
- parentThreadId: typeof parent === "string" ? parent : null,
- startedAt:
- typeof metadata["timestamp"] === "string"
- ? Math.floor(Date.parse(metadata["timestamp"]) / 1_000)
- : null,
- path,
- events,
- });
}
const root = logs.get(options.threadId);
@@ -64,15 +60,25 @@ export async function readScanLogs(options: ScanLogOptions) {
}
const sessions = [root];
+ const included = new Set([root.threadId]);
for (const parent of sessions) {
for (const session of logs.values()) {
- if (session.parentThreadId === parent.threadId) sessions.push(session);
+ if (
+ !included.has(session.threadId) &&
+ (session.parentThreadId === parent.threadId ||
+ (parent === root &&
+ session.parentThreadId === null &&
+ belongsToScan(session, root, options)))
+ ) {
+ included.add(session.threadId);
+ sessions.push(session);
+ }
}
}
const events: Record<string, unknown>[] = [];
for (const session of sessions) {
let replaying = false;
- for (const event of session.events) {
+ for await (const event of sessionEvents(session.path)) {
const payload = event["payload"];
if (event["type"] === "session_meta" && isRecord(payload)) {
replaying = payload["id"] !== session.threadId;
@@ -84,7 +90,7 @@ export async function readScanLogs(options: ScanLogOptions) {
payload["type"] !== "task_started" ||
typeof payload["started_at"] !== "number" ||
session.startedAt === null ||
- payload["started_at"] < session.startedAt
+ payload["started_at"] < Math.floor(session.startedAt / 1_000)
) {
continue;
}
@@ -106,6 +112,84 @@ export async function readScanLogs(options: ScanLogOptions) {
};
}
+function belongsToScan(
+ session: SessionLog,
+ root: SessionLog,
+ options: ScanLogOptions,
+): boolean {
+ const { scanDirectory, completedAt } = options;
+ if (
+ scanDirectory === undefined ||
+ session.workingDirectory === null ||
+ root.startedAt === null ||
+ session.startedAt === null ||
+ session.startedAt < root.startedAt
+ ) {
+ return false;
+ }
+ if (completedAt !== undefined && completedAt !== null) {
+ const completed = Date.parse(completedAt);
+ if (!Number.isFinite(completed) || session.startedAt >= completed) {
+ return false;
+ }
+ }
+
+ const roots = [scanDirectory];
+ const name = basename(scanDirectory);
+ const marker = name.lastIndexOf(".previous-");
+ if (
+ marker > 0 &&
+ root.workingDirectory !== null &&
+ relative(
+ join(dirname(scanDirectory), name.slice(0, marker)),
+ root.workingDirectory,
+ ) === ""
+ ) {
+ roots.push(root.workingDirectory);
+ }
+
+ for (const directoryRoot of roots) {
+ const artifacts = join(directoryRoot, "artifacts");
+ if (relative(artifacts, session.workingDirectory) === "") return true;
+ const workers = join(artifacts, "deep_discovery", "workers");
+ const directory = relative(workers, session.workingDirectory);
+ const components = directory.split(sep);
+ if (
+ !isAbsolute(directory) &&
+ components.length === 2 &&
+ components[0] !== ".." &&
+ relative(
+ join(workers, components[0]!, "output"),
+ session.workingDirectory,
+ ) === ""
+ ) {
+ return true;
+ }
+ }
+ return false;
+}
+
+async function* sessionEvents(
+ path: string,
+): AsyncGenerator<Record<string, unknown>> {
+ const stream = createReadStream(path, { encoding: "utf8" });
+ const lines = createInterface({ input: stream, crlfDelay: Infinity });
+ try {
+ for await (const line of lines) {
+ if (line.trim() === "") continue;
+ try {
+ const event: unknown = JSON.parse(line);
+ if (isRecord(event)) yield event;
+ } catch {
+ continue;
+ }
+ }
+ } finally {
+ lines.close();
+ stream.destroy();
+ }
+}
+
function isRecord(value: unknown): value is Record<string, unknown> {
return typeof value === "object" && value !== null && !Array.isArray(value);
}
diff --git a/sdk/typescript/tests-ts/cli-workbench.test.ts b/sdk/typescript/tests-ts/cli-workbench.test.ts
index cbcc0e891..9766a2615 100644
--- a/sdk/typescript/tests-ts/cli-workbench.test.ts
+++ b/sdk/typescript/tests-ts/cli-workbench.test.ts
@@ -241,13 +241,17 @@ describe("CLI workbench", () => {
);
try {
const sessions = join(state, "codex-home", "sessions", "2026", "08");
+ const scanDirectory = join(state, "scans", "scan-1");
await mkdir(sessions, { recursive: true });
await writeFile(
join(sessions, "rollout-thread-1.jsonl"),
[
{
type: "session_meta",
- payload: { id: "thread-1" },
+ payload: {
+ id: "thread-1",
+ timestamp: "2026-08-11T12:00:00.000Z",
+ },
},
{
type: "response_item",
@@ -264,6 +268,47 @@ describe("CLI workbench", () => {
.map((event) => JSON.stringify(event))
.join("\n"),
);
+ await writeFile(
+ join(sessions, "rollout-worker.jsonl"),
+ [
+ {
+ type: "session_meta",
+ payload: {
+ id: "worker",
+ timestamp: "2026-08-11T12:01:00.000Z",
+ cwd: join(scanDirectory, "artifacts"),
+ },
+ },
+ {
+ type: "event_msg",
+ payload: { type: "agent_message", message: "independent worker" },
+ },
+ ]
+ .map((event) => JSON.stringify(event))
+ .join("\n"),
+ );
+ await writeFile(
+ join(sessions, "rollout-after-completion.jsonl"),
+ [
+ {
+ type: "session_meta",
+ payload: {
+ id: "after-completion",
+ timestamp: "2026-08-11T12:03:00.000Z",
+ cwd: join(scanDirectory, "artifacts"),
+ },
+ },
+ {
+ type: "event_msg",
+ payload: {
+ type: "agent_message",
+ message: "PRIVATE LATER SESSION",
+ },
+ },
+ ]
+ .map((event) => JSON.stringify(event))
+ .join("\n"),
+ );
const calls: Array<readonly string[]> = [];
const stdout = capture();
@@ -275,6 +320,12 @@ describe("CLI workbench", () => {
scan: {
scanId: "scan-1",
continuationThreadId: "thread-1",
+ mode: "deep",
+ progress: {
+ status: "complete",
+ updatedAt: "2026-08-11T12:02:00.000Z",
+ },
+ scanDir: scanDirectory,
},
};
},
@@ -292,6 +343,8 @@ describe("CLI workbench", () => {
).toBe(0);
expect(calls).toEqual([["get-scan", "--scan-id", "scan-1"]]);
expect(stdout.text()).toContain("SYNTHETIC_KEY");
+ expect(stdout.text()).toContain("independent worker");
+ expect(stdout.text()).not.toContain("PRIVATE LATER SESSION");
} finally {
await rm(state, { recursive: true, force: true });
}
diff --git a/sdk/typescript/tests-ts/scan-logs.test.ts b/sdk/typescript/tests-ts/scan-logs.test.ts
index c6a1ae680..f29bb87ad 100644
--- a/sdk/typescript/tests-ts/scan-logs.test.ts
+++ b/sdk/typescript/tests-ts/scan-logs.test.ts
@@ -1,7 +1,14 @@
-import { mkdir, mkdtemp, realpath, rm, writeFile } from "node:fs/promises";
+import {
+ mkdir,
+ mkdtemp,
+ readFile,
+ realpath,
+ rm,
+ writeFile,
+} from "node:fs/promises";
import { tmpdir } from "node:os";
import { join } from "node:path";
-import { afterEach, describe, expect, test } from "bun:test";
+import { afterEach, describe, expect, spyOn, test } from "bun:test";
import { readScanLogs } from "../src/scan-logs.js";
const directories: string[] = [];
@@ -20,6 +27,7 @@ async function writeSession(
events: Record<string, unknown>[],
parentThreadId?: string,
startedAt?: string,
+ workingDirectory?: string,
): Promise<void> {
const directory = join(home, "sessions", "2026", "08", "11");
await mkdir(directory, { recursive: true });
@@ -31,6 +39,7 @@ async function writeSession(
payload: {
id: threadId,
...(startedAt === undefined ? {} : { timestamp: startedAt }),
+ ...(workingDirectory === undefined ? {} : { cwd: workingDirectory }),
...(parentThreadId === undefined
? {}
: {
@@ -140,7 +149,7 @@ describe("saved scan logs", () => {
test("excludes inherited parent history from worker logs", async () => {
const home = await temporaryHome();
await writeSession(home, "parent", []);
- const startedAt = "2026-08-11T12:02:00.000Z";
+ const startedAt = "2026-08-11T12:02:00.900Z";
await writeSession(
home,
"worker",
@@ -167,7 +176,7 @@ describe("saved scan logs", () => {
type: "event_msg",
payload: {
type: "task_started",
- started_at: Date.parse(startedAt) / 1_000,
+ started_at: Math.floor(Date.parse(startedAt) / 1_000),
},
},
{
@@ -191,6 +200,232 @@ describe("saved scan logs", () => {
expect(JSON.stringify(result)).not.toContain("PRIVATE PRE-SCAN");
});
+ test("includes independent Deep workers without crossing scan boundaries", async () => {
+ const home = await temporaryHome();
+ const scanDirectory = join(home, "scans", "current");
+ const artifacts = join(scanDirectory, "artifacts");
+ await writeSession(
+ home,
+ "parent",
+ [],
+ undefined,
+ "2026-08-11T12:00:00.900Z",
+ scanDirectory,
+ );
+ const workerDirectory = join(
+ artifacts,
+ "deep_discovery",
+ "workers",
+ "worker-1",
+ "output",
+ );
+ await writeSession(
+ home,
+ "worker",
+ [commandEvent("review current worker", "worker-call")],
+ undefined,
+ "2026-08-11T12:00:00.950Z",
+ process.platform === "win32"
+ ? workerDirectory.toUpperCase()
+ : workerDirectory,
+ );
+ await writeSession(
+ home,
+ "reducer",
+ [commandEvent("reduce current findings", "reducer-call")],
+ undefined,
+ "2026-08-11T12:02:00.000Z",
+ process.platform === "win32" ? artifacts.toUpperCase() : artifacts,
+ );
+ await writeSession(home, "worker-child", [], "worker");
+ for (const [threadId, directory, startedAt] of [
+ [
+ "stale-worker",
+ join(artifacts, "deep_discovery", "workers", "stale", "output"),
+ "2026-08-11T11:59:00.000Z",
+ ],
+ ["same-second-previous-scan", artifacts, "2026-08-11T12:00:00.100Z"],
+ ["completion-instant", artifacts, "2026-08-11T12:02:00.001Z"],
+ ["after-completion", artifacts, "2026-08-11T12:02:00.002Z"],
+ [
+ "invalid-start",
+ join(artifacts, "deep_discovery", "workers", "invalid", "output"),
+ "not-a-timestamp",
+ ],
+ [
+ "sibling-directory",
+ join(artifacts, "deep_discovery", "output"),
+ "2026-08-11T12:03:00.000Z",
+ ],
+ [
+ "nested-scan",
+ join(scanDirectory, "nested", "artifacts"),
+ "2026-08-11T12:03:00.000Z",
+ ],
+ ] as const) {
+ await writeSession(
+ home,
+ threadId,
+ [commandEvent(`exclude ${threadId}`, `${threadId}-call`)],
+ undefined,
+ startedAt,
+ directory,
+ );
+ }
+ await writeSession(
+ home,
+ "unknown-start",
+ [commandEvent("exclude unknown-start", "unknown-call")],
+ undefined,
+ undefined,
+ join(artifacts, "deep_discovery", "workers", "unknown", "output"),
+ );
+
+ const result = await readScanLogs({
+ scanId: "scan-1",
+ threadId: "parent",
+ codexHome: home,
+ scanDirectory,
+ completedAt: "2026-08-11T12:02:00.001Z",
+ });
+
+ expect(result.sessions.map(({ threadId }) => threadId).sort()).toEqual([
+ "parent",
+ "reducer",
+ "worker",
+ "worker-child",
+ ]);
+ expect(JSON.stringify(result)).toContain("review current worker");
+ expect(JSON.stringify(result)).toContain("reduce current findings");
+ expect(JSON.stringify(result)).not.toContain("exclude ");
+ });
+
+ test("keeps archived Deep workers without exposing later replacement sessions", async () => {
+ const home = await temporaryHome();
+ const original = join(home, "scans", "results");
+ const archived = `${original}.previous-20260811T120300-a1b2c3d4`;
+ const completedAt = "2026-08-11T12:02:00.000Z";
+ await writeSession(
+ home,
+ "archived-parent",
+ [],
+ undefined,
+ "2026-08-11T12:00:00.000Z",
+ original,
+ );
+ await writeSession(
+ home,
+ "archived-worker",
+ [commandEvent("review archived scan", "archived-call")],
+ undefined,
+ "2026-08-11T12:01:00.000Z",
+ join(original, "artifacts", "deep_discovery", "workers", "old", "output"),
+ );
+ await writeSession(
+ home,
+ "replacement-worker",
+ [commandEvent("PRIVATE REPLACEMENT SCAN", "replacement-call")],
+ undefined,
+ "2026-08-11T12:03:00.000Z",
+ join(original, "artifacts"),
+ );
+
+ const options = {
+ scanId: "archived-scan",
+ threadId: "archived-parent",
+ codexHome: home,
+ scanDirectory: archived,
+ completedAt,
+ };
+ const archivedLogs = await readScanLogs(options);
+ expect(archivedLogs.sessions.map(({ threadId }) => threadId)).toEqual([
+ "archived-parent",
+ "archived-worker",
+ ]);
+ expect(JSON.stringify(archivedLogs)).toContain("review archived scan");
+ expect(JSON.stringify(archivedLogs)).not.toContain("PRIVATE REPLACEMENT");
+
+ const unrelatedRoot = await readScanLogs({
+ ...options,
+ scanDirectory: join(home, "scans", "unrelated.previous-fixture"),
+ });
+ expect(unrelatedRoot.sessions.map(({ threadId }) => threadId)).toEqual([
+ "archived-parent",
+ ]);
+
+ const malformedCompletion = await readScanLogs({
+ ...options,
+ completedAt: "invalid-timestamp",
+ });
+ expect(
+ malformedCompletion.sessions.map(({ threadId }) => threadId),
+ ).toEqual(["archived-parent"]);
+
+ const runningLogs = await readScanLogs({ ...options, completedAt: null });
+ expect(runningLogs.sessions.map(({ threadId }) => threadId).sort()).toEqual(
+ ["archived-parent", "archived-worker", "replacement-worker"],
+ );
+ });
+
+ test("does not parse event bodies from unrelated saved sessions", async () => {
+ const home = await temporaryHome();
+ await writeSession(home, "parent", [
+ commandEvent("included", "parent-call"),
+ ]);
+ await writeSession(home, "unrelated", [
+ commandEvent("UNRELATED_PRIVATE_EVENT_BODY", "unrelated-call"),
+ ]);
+ const originalParse = JSON.parse;
+ let unrelatedBodies = 0;
+ const parseSpy = spyOn(JSON, "parse").mockImplementation(
+ (text, reviver) => {
+ if (text.includes("UNRELATED_PRIVATE_EVENT_BODY")) unrelatedBodies++;
+ return originalParse(text, reviver);
+ },
+ );
+
+ try {
+ const result = await readScanLogs({
+ scanId: "scan-1",
+ threadId: "parent",
+ codexHome: home,
+ });
+ expect(result.sessions.map(({ threadId }) => threadId)).toEqual([
+ "parent",
+ ]);
+ expect(unrelatedBodies).toBe(0);
+ } finally {
+ parseSpy.mockRestore();
+ }
+ });
+
+ test("preserves large selected events and skips malformed metadata prefixes", async () => {
+ const home = await temporaryHome();
+ const output = "x".repeat(2 * 1024 * 1024 + 1);
+ await writeSession(home, "parent", [
+ { type: "response_item", payload: { output } },
+ ]);
+ const path = join(
+ home,
+ "sessions",
+ "2026",
+ "08",
+ "11",
+ "rollout-parent.jsonl",
+ );
+ await writeFile(path, `not json\n42\n${await readFile(path, "utf8")}`);
+
+ const result = await readScanLogs({
+ scanId: "scan-1",
+ threadId: "parent",
+ codexHome: home,
+ });
+
+ expect(result.events.at(-1)?.["event"]).toMatchObject({
+ payload: { output },
+ });
+ });
+
test("reports when the saved scan session is missing", async () => {
const home = await temporaryHome();
await expect(