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: preserve completed scans when targets change (#78)

ianw-oai7cb6e0b76378
diff --git a/sdk/typescript/_bundled_plugin/scripts/workbench_db.py b/sdk/typescript/_bundled_plugin/scripts/workbench_db.py
index 8e79b0569..683cfe574 100644
--- a/sdk/typescript/_bundled_plugin/scripts/workbench_db.py
+++ b/sdk/typescript/_bundled_plugin/scripts/workbench_db.py
@@ -40,7 +40,9 @@ import workbench_progress as progress
import workbench_remediation as remediation
import workbench_scan_history as scan_history
from filesystem_identity import serialize_filesystem_identity as serialize_filesystem_identity
-from filesystem_identity import stored_filesystem_identity_matches
+from filesystem_identity import (
+ stored_filesystem_identity_matches as stored_filesystem_identity_matches,
+)
from finalize_scan_contract import (
PRODUCER_NAME,
ContractError,
@@ -98,6 +100,10 @@ from workbench_target import (
git_submodule_paths,
git_target_metadata,
git_worktree_context,
+ require_git_worktree_head,
+ require_remediation_target,
+ require_scan_target_identity,
+ scan_target_warning,
worktree_content_digest,
worktree_content_digest_for_context,
)
@@ -325,49 +331,6 @@ def require_target(value: str) -> Path:
return target
-def require_remediation_target(value: str) -> Path:
- stored = Path(value).expanduser()
- if not stored.is_absolute():
- raise SystemExit("Remediation target must be an absolute local directory path.")
- try:
- resolved = stored.resolve(strict=True)
- except (FileNotFoundError, OSError) as exc:
- raise SystemExit(
- "Remediation is unavailable because the selected checkout is no longer accessible."
- ) from exc
- if resolved != stored or not stored.is_dir():
- raise SystemExit(
- "Remediation is unavailable because the selected checkout path was replaced. Start a new scan."
- )
- return stored
-
-
-def require_scan_target_identity(scan: sqlite3.Row) -> Path:
- target = require_remediation_target(scan["target_path"])
- expected_device = scan["target_device"]
- expected_inode = scan["target_inode"]
- if expected_device is None or expected_inode is None:
- raise SystemExit(
- "Remediation is unavailable because this scan does not record checkout identity. "
- "Start a new scan."
- )
- try:
- metadata = target.stat()
- except OSError as exc:
- raise SystemExit(
- "Remediation is unavailable because the selected checkout is no longer accessible."
- ) from exc
- if not (
- stored_filesystem_identity_matches(expected_device, metadata.st_dev)
- and stored_filesystem_identity_matches(expected_inode, metadata.st_ino)
- ):
- raise SystemExit(
- "Remediation is unavailable because the selected checkout path was replaced. "
- "Start a new scan."
- )
- return target
-
-
def inspect_target(target_path: str) -> dict[str, Any]:
target = require_target(target_path)
return {
@@ -510,13 +473,6 @@ def inspect_setup(args: argparse.Namespace) -> dict[str, Any]:
)
-def require_git_worktree_head(target: Path) -> str:
- metadata = git_target_metadata(target)
- if not metadata["isGit"] or not metadata["isWorktree"] or not metadata["hasHead"]:
- raise SystemExit("Review changes requires a non-bare Git worktree with a resolvable HEAD.")
- return str(metadata["revision"])
-
-
def require_review_changes_target(target: Path) -> str:
revision = require_git_worktree_head(target)
repository_root = git_output(target, "rev-parse", "--show-toplevel")
@@ -1372,42 +1328,6 @@ def start_prompt_only_scan(
return {**scan_context(connection, scan_id), "startDisposition": "created"}
-def require_unchanged_target(scan: sqlite3.Row) -> None:
- if scan["diff_target_kind"] != "working_tree" and not scan["target_snapshot_digest"]:
- return
- target = require_target(scan["target_path"])
- if scan["target_revision"] == "unversioned":
- current_digest = directory_content_digest(
- target,
- excluded=(Path(scan["scan_dir"]),),
- )
- if current_digest != scan["target_snapshot_digest"]:
- raise SystemExit(
- "Directory contents changed while the scan was running. Start a new scan."
- )
- return
- if git_revision(target) == "unversioned":
- raise SystemExit("The scan target revision no longer matches the selected target.")
- current_head = require_git_worktree_head(target)
- expected_head = (
- scan["diff_head_revision"]
- if scan["diff_target_kind"] == "working_tree"
- else scan["target_revision"]
- )
- if current_head != expected_head:
- raise SystemExit("Repository HEAD changed while the scan was running. Start a new scan.")
- current_digest = worktree_content_digest(target)
- expected_digest = (
- scan["diff_content_digest"]
- if scan["diff_target_kind"] == "working_tree"
- else scan["target_snapshot_digest"]
- )
- if current_digest != expected_digest:
- raise SystemExit(
- "Working-tree contents changed while the scan was running. Start a new scan."
- )
-
-
def scan_local_file_digest(scan_dir: Path, relative_path: str) -> str:
digest = hashlib.sha256()
with open_scan_local_file(scan_dir, relative_path) as source:
@@ -1491,7 +1411,10 @@ def complete_scan_locked(
)
if scan["recipe_json"] is None:
deep_scan.require_deep_scan_ready_for_parent_completion(connection, scan)
- require_unchanged_target(scan)
+ warnings = []
+ warning = scan_target_warning(scan)
+ if warning is not None:
+ warnings.append(warning)
scan_dir = require_canonical_scan_directory(Path(scan["scan_dir"]))
completion_timestamp = now()
completion_binding = workbench_completion_binding(scan, completion_timestamp)
@@ -1507,8 +1430,9 @@ def complete_scan_locked(
expected_coverage_mode=expected_coverage_mode(scan),
completion_binding=completion_binding,
)
- # Recheck the target after finalization and before writing.
- require_unchanged_target(scan)
+ warning = scan_target_warning(scan)
+ if warning is not None and warning not in warnings:
+ warnings.append(warning)
manifest, findings, _ = _write_prepared_scan_finalization(prepared)
except ContractError as exc:
raise SystemExit(str(exc)) from exc
@@ -1557,10 +1481,17 @@ def complete_scan_locked(
"""
UPDATE scans
SET status = 'complete', phase = 'reporting', completed_at = ?, updated_at = ?,
- seal_manifest_digest = ?, cost_json = ?
+ seal_manifest_digest = ?, cost_json = ?, completion_warnings_json = ?
WHERE id = ? AND status = 'running'
""",
- (timestamp, timestamp, manifest_digest, cost_json, scan["id"]),
+ (
+ timestamp,
+ timestamp,
+ manifest_digest,
+ cost_json,
+ json.dumps(warnings),
+ scan["id"],
+ ),
)
if updated.rowcount != 1:
raise SystemExit("Only a running scan can be completed.")
@@ -3072,6 +3003,7 @@ def scan_result(
finding_management_updated_at(connection, scan["id"]) or "",
),
"userContext": scan["user_context"],
+ "warnings": json.loads(scan["completion_warnings_json"]),
}
diff --git a/sdk/typescript/_bundled_plugin/scripts/workbench_scan_history.py b/sdk/typescript/_bundled_plugin/scripts/workbench_scan_history.py
index 835dc56dc..c92f14901 100644
--- a/sdk/typescript/_bundled_plugin/scripts/workbench_scan_history.py
+++ b/sdk/typescript/_bundled_plugin/scripts/workbench_scan_history.py
@@ -85,7 +85,7 @@ def list_workspace_scans(
"""
SELECT id, mode, status, phase, scope, target_revision,
seal_manifest_digest, started_at, completed_at, canceled_at,
- updated_at, failure_message
+ updated_at, failure_message, completion_warnings_json
FROM scans
WHERE workspace_id = ?
ORDER BY created_at DESC, id DESC
@@ -112,6 +112,11 @@ def list_workspace_scans(
"status": "canceled" if row["canceled_at"] else row["status"],
"targetRevision": row["target_revision"],
"updatedAt": row["updated_at"],
+ **(
+ {"warnings": json.loads(row["completion_warnings_json"])}
+ if row["completion_warnings_json"] != "[]"
+ else {}
+ ),
}
for row in rows
],
@@ -242,6 +247,11 @@ def list_scans(
"targetRevision": row["target_revision"],
"targetSummary": row["target_summary"],
"updatedAt": max(row["updated_at"], row["progress_updated_at"]),
+ **(
+ {"warnings": json.loads(row["completion_warnings_json"])}
+ if row["completion_warnings_json"] != "[]"
+ else {}
+ ),
}
for row in rows[:limit]
]
diff --git a/sdk/typescript/_bundled_plugin/scripts/workbench_schema.py b/sdk/typescript/_bundled_plugin/scripts/workbench_schema.py
index 0b7244eae..748772c4c 100644
--- a/sdk/typescript/_bundled_plugin/scripts/workbench_schema.py
+++ b/sdk/typescript/_bundled_plugin/scripts/workbench_schema.py
@@ -602,6 +602,14 @@ MIGRATIONS = (
ALTER TABLE scans ADD COLUMN cost_json TEXT;
""",
),
+ (
+ 25,
+ "persist scan completion warnings",
+ """
+ ALTER TABLE scans
+ ADD COLUMN completion_warnings_json TEXT NOT NULL DEFAULT '[]';
+ """,
+ ),
)
diff --git a/sdk/typescript/_bundled_plugin/scripts/workbench_target.py b/sdk/typescript/_bundled_plugin/scripts/workbench_target.py
index ff46e904a..9d1ce9c33 100644
--- a/sdk/typescript/_bundled_plugin/scripts/workbench_target.py
+++ b/sdk/typescript/_bundled_plugin/scripts/workbench_target.py
@@ -6,6 +6,7 @@ import argparse
import hashlib
import os
import shutil
+import sqlite3
import stat
import subprocess
import sys
@@ -14,6 +15,7 @@ from typing import Any
# Some plugin hosts launch Python with safe-path isolation enabled.
sys.path.insert(0, str(Path(__file__).resolve().parent))
+from filesystem_identity import stored_filesystem_identity_matches
from workbench_constants import GIT_REPOSITORY_ENVIRONMENT
@@ -461,6 +463,99 @@ def git_target_metadata(target: Path) -> dict[str, Any]:
return metadata
+def require_remediation_target(value: str) -> Path:
+ stored = Path(value).expanduser()
+ if not stored.is_absolute():
+ raise SystemExit("Remediation target must be an absolute local directory path.")
+ try:
+ resolved = stored.resolve(strict=True)
+ except (FileNotFoundError, OSError) as exc:
+ raise SystemExit(
+ "Remediation is unavailable because the selected checkout is no longer accessible."
+ ) from exc
+ if resolved != stored or not stored.is_dir():
+ raise SystemExit(
+ "Remediation is unavailable because the selected checkout path was replaced. Start a new scan."
+ )
+ return stored
+
+
+def require_scan_target_identity(scan: sqlite3.Row) -> Path:
+ target = require_remediation_target(scan["target_path"])
+ expected_device = scan["target_device"]
+ expected_inode = scan["target_inode"]
+ if expected_device is None or expected_inode is None:
+ raise SystemExit(
+ "Remediation is unavailable because this scan does not record checkout identity. "
+ "Start a new scan."
+ )
+ try:
+ metadata = target.stat()
+ except OSError as exc:
+ raise SystemExit(
+ "Remediation is unavailable because the selected checkout is no longer accessible."
+ ) from exc
+ if not (
+ stored_filesystem_identity_matches(expected_device, metadata.st_dev)
+ and stored_filesystem_identity_matches(expected_inode, metadata.st_ino)
+ ):
+ raise SystemExit(
+ "Remediation is unavailable because the selected checkout path was replaced. "
+ "Start a new scan."
+ )
+ return target
+
+
+def require_git_worktree_head(target: Path) -> str:
+ metadata = git_target_metadata(target)
+ if not metadata["isGit"] or not metadata["isWorktree"] or not metadata["hasHead"]:
+ raise SystemExit("Review changes requires a non-bare Git worktree with a resolvable HEAD.")
+ return str(metadata["revision"])
+
+
+def scan_target_warning(scan: sqlite3.Row) -> str | None:
+ if scan["diff_target_kind"] != "working_tree" and not scan["target_snapshot_digest"]:
+ return None
+ try:
+ target = require_scan_target_identity(scan)
+ if scan["target_revision"] == "unversioned":
+ if (
+ directory_content_digest(target, excluded=(Path(scan["scan_dir"]),))
+ != scan["target_snapshot_digest"]
+ ):
+ return (
+ "Directory contents changed while the scan was running; "
+ "results were saved for the original snapshot."
+ )
+ return None
+ if git_revision(target) == "unversioned":
+ return (
+ "The scanned Git repository became unavailable while the scan was running; "
+ "results were saved for the original revision."
+ )
+ working_tree = scan["diff_target_kind"] == "working_tree"
+ expected_head = scan["diff_head_revision"] if working_tree else scan["target_revision"]
+ if require_git_worktree_head(target) != expected_head:
+ return (
+ "Repository HEAD changed while the scan was running; "
+ "results were saved for the original revision."
+ )
+ expected_digest = (
+ scan["diff_content_digest"] if working_tree else scan["target_snapshot_digest"]
+ )
+ if worktree_content_digest(target) != expected_digest:
+ return (
+ "Working-tree contents changed while the scan was running; "
+ "results were saved for the original snapshot."
+ )
+ except (OSError, SystemExit):
+ return (
+ "The scan target became unavailable while the scan was running; "
+ "results were saved for the original revision or snapshot."
+ )
+ return None
+
+
def main() -> None:
argparse.ArgumentParser(description=__doc__).parse_args()
diff --git a/sdk/typescript/src/api.ts b/sdk/typescript/src/api.ts
index ca1d04afc..31925d11f 100644
--- a/sdk/typescript/src/api.ts
+++ b/sdk/typescript/src/api.ts
@@ -133,6 +133,7 @@ export interface ScanOptions {
details?: ScanReconnectDetails,
) => void;
onWorkerStatus?: (status: ScanWorkerStatus) => void;
+ onWarning?: (warning: string) => void;
onObserverError?: (observer: ScanObserverName, error: unknown) => void;
signal?: AbortSignal;
}
@@ -162,7 +163,8 @@ type ScanObserverName =
| "onOutputDirReady"
| "onScanStarted"
| "onReconnect"
- | "onWorkerStatus";
+ | "onWorkerStatus"
+ | "onWarning";
export interface ScanPreflight {
repository: string;
@@ -700,18 +702,37 @@ export class CodexSecurity {
const snapshot = await tracker.stop(usage);
throwIfAborted(signal, scanDir);
if (options.maxCostUsd !== undefined && snapshot.cost === null) {
- throw new CodexSecurityError(
- "Cannot evaluate the cost limit: model pricing or token usage is unavailable.",
+ notifyObserver(
+ "onWarning",
+ options.onWarning,
+ options.onObserverError,
+ "Scan completed, but its cost limit could not be verified because model pricing or token usage is unavailable.",
);
}
const cost = snapshot.cost;
- await workbench(workbenchOptions, [
+ const completion = await workbench(workbenchOptions, [
"complete-scan",
"--scan-id",
scanId,
...(cost === null ? [] : ["--cost-json", JSON.stringify(cost)]),
]);
activeScan = null;
+ const completedScan = completion["scan"];
+ if (
+ isRecord(completedScan) &&
+ Array.isArray(completedScan["warnings"])
+ ) {
+ for (const warning of completedScan["warnings"]) {
+ if (typeof warning === "string") {
+ notifyObserver(
+ "onWarning",
+ options.onWarning,
+ options.onObserverError,
+ warning,
+ );
+ }
+ }
+ }
return snapshot.usage;
},
onScanStarted: options.onScanStarted,
diff --git a/sdk/typescript/src/cli.ts b/sdk/typescript/src/cli.ts
index 34333df0b..7de2cfc36 100644
--- a/sdk/typescript/src/cli.ts
+++ b/sdk/typescript/src/cli.ts
@@ -2385,6 +2385,11 @@ async function runScan(
progress.stage(message);
progress.startTimer(runningMessage());
},
+ onWarning: (warning) => {
+ errorOutput.write(
+ `codex-security: warning: ${cliErrorMessage(warning)}\n`,
+ );
+ },
onObserverError: (observer, error) => {
errorOutput.write(
`codex-security: warning: ${observer} observer failed: ${cliErrorMessage(error)}\n`,
diff --git a/sdk/typescript/src/scan-history-renderer.ts b/sdk/typescript/src/scan-history-renderer.ts
index c0696df09..1c4e79a0b 100644
--- a/sdk/typescript/src/scan-history-renderer.ts
+++ b/sdk/typescript/src/scan-history-renderer.ts
@@ -213,6 +213,14 @@ export function renderScanHistory(
if (result["failureMessage"]) {
wrap(String(result["failureMessage"]), 11, ` ${paint("ERROR", 31)} `);
}
+ const warnings = result["warnings"];
+ if (Array.isArray(warnings)) {
+ for (const warning of warnings) {
+ if (typeof warning === "string") {
+ wrap(warning, 11, ` ${paint("WARNING", 33)} `);
+ }
+ }
+ }
if (result["parentScanId"]) {
lines.push(
` ${strong("PARENT SCAN")} ${clean(result["parentScanId"]).slice(0, 8)}`,
diff --git a/sdk/typescript/tests-ts/api.test.ts b/sdk/typescript/tests-ts/api.test.ts
index a87067457..c4d5f4da8 100644
--- a/sdk/typescript/tests-ts/api.test.ts
+++ b/sdk/typescript/tests-ts/api.test.ts
@@ -1252,8 +1252,11 @@ describe("CodexSecurity orchestration", () => {
let threadOptions: Record<string, unknown> | null = null;
let prompt = "";
let scanStarted = false;
+ const warnings: string[] = [];
const reconnects: Array<[number, number]> = [];
const commands: Array<readonly string[]> = [];
+ const completionWarning =
+ "Repository HEAD changed while the scan was running; results were saved for the original revision.";
const client = new TestClient(
{ codexOverrides: { model: "replay-model" } },
@@ -1297,6 +1300,9 @@ describe("CodexSecurity orchestration", () => {
falsePositives: [],
};
}
+ if (args[0] === "complete-scan") {
+ return { scan: { warnings: [completionWarning] } };
+ }
return {};
},
createCodex: (options: CodexOptions) => {
@@ -1328,12 +1334,16 @@ describe("CodexSecurity orchestration", () => {
onScanStarted: () => {
scanStarted = true;
},
+ onWarning: (warning) => {
+ warnings.push(warning);
+ },
onReconnect: (attempt, maxAttempts) => {
reconnects.push([attempt, maxAttempts]);
},
});
expect(result.threadId).toBe("thread-1");
expect(scanStarted).toBe(true);
+ expect(warnings).toEqual([completionWarning]);
expect(reconnects).toEqual([[2, 5]]);
const startedAt = (codexOptions as CodexOptions | null)?.env?.[
"CODEX_SECURITY_STARTED_AT"
@@ -1674,7 +1684,7 @@ describe("CodexSecurity orchestration", () => {
await client.close();
});
- test("fails a budgeted scan when token usage is unavailable", async () => {
+ test("saves a budgeted scan with a warning when token usage is unavailable", async () => {
const root = await temporaryDirectory();
const repository = join(root, "repository");
const codexHome = join(root, "codex-home");
@@ -1682,6 +1692,8 @@ describe("CodexSecurity orchestration", () => {
await mkdir(repository);
await mkdir(codexHome);
await mkdir(scanDir, { mode: 0o700 });
+ const warnings: string[] = [];
+ const commands: Array<readonly string[]> = [];
const client = new TestClient(
{},
{
@@ -1690,10 +1702,29 @@ describe("CodexSecurity orchestration", () => {
resolvePluginPython: async () => "/managed/python",
prepareOutputDir: async () => scanDir,
repositoryRevision: async () => "deadbeef",
+ runWorkbench: async (_options: unknown, args: readonly string[]) => {
+ commands.push(args);
+ if (args[0] === "register-cli-scan") {
+ return {
+ scanId: "scan_example_001",
+ targetId: "target_sha256_example",
+ scanDir,
+ };
+ }
+ if (args[0] === "get-scan-feedback") {
+ return {
+ scanId: "scan_example_001",
+ targetId: "target_sha256_example",
+ falsePositives: [],
+ };
+ }
+ return {};
+ },
createCodex: () => ({
startThread: () => ({
id: null,
async runStreamed() {
+ await copyCompletedScan(root);
async function* events() {
yield { type: "thread.started", thread_id: "scan-thread" };
yield { type: "turn.completed", usage: null };
@@ -1705,9 +1736,23 @@ describe("CodexSecurity orchestration", () => {
},
);
- await expect(client.run(repository, { maxCostUsd: 1 })).rejects.toThrow(
- "Cannot evaluate the cost limit",
- );
+ const result = await client.run(repository, {
+ maxCostUsd: 1,
+ onWarning: (warning) => {
+ warnings.push(warning);
+ },
+ });
+ expect(result.threadId).toBe("scan-thread");
+ expect(result.cost).toBeNull();
+ expect(warnings).toEqual([
+ "Scan completed, but its cost limit could not be verified because model pricing or token usage is unavailable.",
+ ]);
+ expect(commands.map(([command]) => command)).toEqual([
+ "register-cli-scan",
+ "get-scan-feedback",
+ "complete-scan",
+ ]);
+ expect(commands.some((args) => args[0] === "fail-scan")).toBe(false);
await client.close();
});
diff --git a/sdk/typescript/tests-ts/cli.test.ts b/sdk/typescript/tests-ts/cli.test.ts
index f8d91509f..cab31756b 100644
--- a/sdk/typescript/tests-ts/cli.test.ts
+++ b/sdk/typescript/tests-ts/cli.test.ts
@@ -1789,6 +1789,30 @@ describe("CLI", () => {
expect(stdout.text()).toContain("completeness: complete");
});
+ test("prints scan completion warnings without failing the scan", async () => {
+ const stdout = capture();
+ const stderr = capture();
+ const deps = dependencies();
+ deps.createSecurity = () => ({
+ run: async (_repository, options) => {
+ options?.onWarning?.(
+ "Repository HEAD changed while the scan was running; results were saved for the original revision.",
+ );
+ return fakeResult();
+ },
+ close: async () => {},
+ preflight: async () => fakePreflight(),
+ });
+
+ expect(
+ await main(["scan", ".", "--json"], stdout.stream, stderr.stream, deps),
+ ).toBe(0);
+ expect(JSON.parse(stdout.text())).toEqual(fakeResult().toJSON());
+ expect(stderr.text()).toContain(
+ "codex-security: warning: Repository HEAD changed while the scan was running; results were saved for the original revision.",
+ );
+ });
+
test("reports isolated observer failures without failing the scan", async () => {
const stdout = capture();
const stderr = capture();
diff --git a/sdk/typescript/tests-ts/scan-history-renderer.test.ts b/sdk/typescript/tests-ts/scan-history-renderer.test.ts
index 4c7a0aafc..465209d71 100644
--- a/sdk/typescript/tests-ts/scan-history-renderer.test.ts
+++ b/sdk/typescript/tests-ts/scan-history-renderer.test.ts
@@ -241,6 +241,31 @@ describe("scan history renderer", () => {
expect(failed).toContain("ERROR Repository checkout became unavailable.");
});
+ test("shows saved completion warnings without marking a scan failed", () => {
+ const output = stripVTControlCharacters(
+ renderScanHistory(
+ {
+ scanId: "12345678-abcd-4567-abcd-1234567890ab",
+ targetPath: "/demo/juice-shop",
+ mode: "standard",
+ progress: { status: "complete" },
+ findings: [],
+ warnings: [
+ "Repository HEAD changed while the scan was running; results were saved for the original revision.",
+ ],
+ },
+ "show",
+ ),
+ );
+
+ expect(output).toContain("COMPLETE");
+ expect(output).toContain("WARNING");
+ expect(output).toContain(
+ "Repository HEAD changed while the scan was running",
+ );
+ expect(output).not.toContain("ERROR");
+ });
+
test("renders match-all results from the original workbench data", () => {
const output = stripVTControlCharacters(
renderScanHistory(