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
import { isRecord } from "./record.js";
import { parseJson } from "./value.js";
const MAX_ACTIVITY_PATHS = 8;
const MAX_PROSE_CHARACTERS = 1_000;
const SHELL_TOKEN = /"(?:\\.|[^"\\])*"|'[^']*'|[^\s|;&<>]+/gu;
const POSIX_TOKEN =
/(?:"(?:\\[\s\S]|[^"\\])*"|'[^']*'|\\[\s\S]|[^\s|;&<>'"\\])+/gu;
const POSIX_SHELL = /(?:^|\/)(?:sh|bash|zsh)$/u;
export type ScanActivityStatus = "running" | "completed" | "failed";
export interface ScanActivity {
id: string;
kind: "command" | "tool" | "reasoning" | "message";
status: ScanActivityStatus;
description: string;
paths: string[];
worker?: number;
}
export function scanActivitiesFromEvent(
event: Readonly<Record<string, unknown>>,
repository: string,
): ScanActivity[] {
const activity = scanActivityFromEvent(event, repository);
if (activity === null) return [];
const item = event["item"];
if (
activity.kind !== "reasoning" ||
!isRecord(item) ||
typeof item["text"] !== "string"
) {
return [activity];
}
const summaries = Array.from(item["text"].matchAll(/\*\*([^*\r\n]+)\*\*/gu));
if (
summaries.length < 2 ||
item["text"].replaceAll(/\*\*[^*\r\n]+\*\*/gu, "").trim() !== ""
) {
return [activity];
}
return summaries.map((summary, index) => ({
...activity,
id: index === 0 ? activity.id : `${activity.id}:${index}`,
description: summary[1]!.trim(),
}));
}
export function scanActivityFromEvent(
event: Readonly<Record<string, unknown>>,
repository: string,
): ScanActivity | null {
if (
(event["type"] !== "item.started" &&
event["type"] !== "item.updated" &&
event["type"] !== "item.completed") ||
!isRecord(event["item"])
) {
return null;
}
const item = event["item"];
if (typeof item["id"] !== "string") return null;
const status: ScanActivityStatus =
item["status"] === "failed"
? "failed"
: event["type"] === "item.completed"
? "completed"
: "running";
const command = item["command"];
if (item["type"] === "command_execution" && isCommand(command)) {
return {
id: item["id"],
kind: "command",
status,
...commandDetails(command, repository, item["shell"]),
};
}
if (item["type"] === "mcp_tool_call" && typeof item["tool"] === "string") {
const arguments_ = isRecord(item["arguments"]) ? item["arguments"] : {};
const value = arguments_["cmd"] ?? arguments_["command"];
const details =
item["tool"] === "exec" && isCommand(value)
? commandDetails(
value,
repository,
arguments_["shell"] ?? item["shell"],
)
: {
description: toolDescription(
item["tool"],
arguments_,
item["arguments"],
),
paths: argumentRepositoryPaths(arguments_, repository),
};
return { id: item["id"], kind: "tool", status, ...details };
}
if (
(item["type"] === "reasoning" || item["type"] === "agent_message") &&
typeof item["text"] === "string"
) {
return proseActivity(
item["id"],
item["type"] === "reasoning" ? "reasoning" : "message",
status,
item["text"],
);
}
return null;
}
function isCommand(value: unknown): value is string | string[] {
return (
typeof value === "string" ||
(Array.isArray(value) && value.every((part) => typeof part === "string"))
);
}
function commandDetails(
value: string | string[],
repository: string,
shell: unknown,
) {
let text: string;
let paths: string[];
if (typeof value === "string") {
const command = unwrapCommand(value);
text = command.text;
paths = commandRepositoryPaths(
command.script ?? text,
repository,
shell ?? command.recordedShell,
);
} else {
text = value.join(" ");
paths = literalRepositoryPaths(value, repository);
}
return { description: text.replaceAll(/\s+/gu, " "), paths };
}
/** Decode one literal POSIX word without expanding variables or running a shell. */
function literalPosixWord(argument: string) {
// A sticky match stops at the first unsupported fragment instead of skipping it.
const fragment =
/'([^']*)'|"((?:\\.|[^"\\$\x60])*)"|\\(.)|[^\s'"\\$\x60|;&<>()*?\[\]{}~]+/suy;
let word = "";
do {
const match = fragment.exec(argument);
if (!match) return undefined;
const [raw, single, double, escaped] = match;
if (double !== undefined)
word += double.replace(/\\\n|\\([$\x60"\\])/gu, "$1");
else if (escaped !== "\n") word += single ?? escaped ?? raw;
} while (fragment.lastIndex < argument.length);
return word;
}
function unwrapCommand(command: string) {
const normalized = command.trim();
const powershell =
process.platform === "win32"
? /^(?:"([^"]+)"|([^\s"'|;&<>]+))\s+(?:-NoProfile\s+)?-Command\s+(['"])(.*)\3$/isu.exec(
normalized,
)
: null;
if (
powershell !== null &&
/(?:^|[\\/])(?:powershell|pwsh)(?:\.exe)?$/iu.test(
powershell[1] ?? powershell[2]!,
)
) {
return { text: powershell[4]! };
}
const match =
/^((?:\/(?:usr\/)?bin\/)?(?:zsh|bash|sh))\s+-[a-z]*c[a-z]*\s+(["'].*)$/su.exec(
normalized,
);
if (match === null) return { text: normalized, script: command };
const argument = match[2]!;
const decoded = literalPosixWord(argument);
return {
text: argument.slice(1, argument.endsWith(argument[0]!) ? -1 : undefined),
script: decoded,
recordedShell: decoded === undefined ? undefined : match[1],
};
}
export function scanActivityFromSessionEvent(
event: Readonly<Record<string, unknown>>,
repository: string,
): ScanActivity | null {
if (!isRecord(event["payload"])) {
return null;
}
const payload = event["payload"];
if (event["type"] === "event_msg") {
const type = payload["type"];
const kind =
type === "agent_reasoning" ||
type === "agent_reasoning_delta" ||
type === "agent_reasoning_raw_content" ||
type === "agent_reasoning_raw_content_delta"
? "reasoning"
: type === "agent_message"
? "message"
: null;
const delta =
type === "agent_reasoning_delta" ||
type === "agent_reasoning_raw_content_delta";
const text = delta
? payload["delta"]
: kind === "reasoning"
? payload["text"]
: payload["message"];
if (kind === null || typeof text !== "string") return null;
return proseActivity(
`${type}:${typeof event["timestamp"] === "string" ? event["timestamp"] : ""}:${text}`,
kind,
delta ? "running" : "completed",
text,
);
}
if (event["type"] !== "response_item") return null;
const id = payload["call_id"] ?? payload["id"];
if (typeof id !== "string") return null;
if (payload["type"] === "reasoning") {
return sessionProse(id, "reasoning", payload["summary"]);
}
if (payload["type"] === "message" && payload["role"] === "assistant") {
return sessionProse(id, "message", payload["content"]);
}
if (
payload["type"] !== "function_call" &&
payload["type"] !== "custom_tool_call" &&
payload["type"] !== "local_shell_call"
) {
return null;
}
const arguments_ = sessionCallArguments(payload);
const name =
typeof payload["name"] === "string"
? payload["name"]
: payload["type"] === "local_shell_call"
? "shell"
: null;
if (name === null) return null;
const value =
arguments_["cmd"] ??
arguments_["command"] ??
customShellCommand(name, payload["input"]);
if (
isCommand(value) &&
/^(?:exec|exec_command|shell_command|shell)$/u.test(name)
) {
return {
id,
kind: "command",
status: "running",
...commandDetails(value, repository, arguments_["shell"]),
};
}
return {
id,
kind: "tool",
status: "running",
description: toolDescription(name, arguments_, payload["input"]),
paths: argumentRepositoryPaths(arguments_, repository),
};
}
function sessionProse(
id: string,
kind: "reasoning" | "message",
value: unknown,
): ScanActivity | null {
return proseActivity(
id,
kind,
"completed",
sessionContentText(value, ["summary_text", "output_text"], " "),
);
}
/** @internal */
export function sessionContentText(
content: unknown,
types: readonly string[] = ["output_text"],
separator = "\n",
): string {
if (!Array.isArray(content)) return "";
return content
.filter(
(item): item is Record<string, unknown> & { text: string } =>
isRecord(item) &&
types.some((type) => item["type"] === type) &&
typeof item["text"] === "string",
)
.map((item) => item.text)
.join(separator);
}
function proseActivity(
id: string,
kind: "reasoning" | "message",
status: ScanActivityStatus,
text: string,
): ScanActivity | null {
const description = prose(
text
.split(/\r?\n/u)
.filter(
(line) =>
!/^CODEX_SECURITY_(?:WORKER_STATUS|SCAN_PROGRESS)\s/u.test(line),
)
.join("\n"),
);
if (description === "") {
return null;
}
return { id, kind, status, description, paths: [] };
}
function prose(text: string, limit?: number): string {
const normalized = text
.split(
/((?<!`)`{3,}[^`\r\n]*(?:\r?\n[\s\S]*?(?:\r?\n[ \t]*`{3,}[ \t]*(?=\r?\n|$)|$)|$)|`[^`\r\n]+`)/gu,
)
.reduce((result, part, index) => {
if (index % 2 === 1) {
if (!part.startsWith("```")) return `${result}${part}`;
const previous = result.trimEnd();
return `${previous}${previous === "" ? "" : "\n"}${part}\n`;
}
const plain = part
.replaceAll(/\*\*([\s\S]+?)\*\*/gu, "$1")
.replaceAll(/\s+/gu, " ");
return `${result}${result.endsWith("\n") ? plain.trimStart() : plain}`;
}, "")
.trim();
if (limit === undefined) return normalized;
const characters = Array.from(normalized);
return characters.length <= limit
? normalized
: `${characters.slice(0, limit - 1).join("")}…`;
}
function customShellCommand(name: string, value: unknown): string | null {
if (name !== "exec" || typeof value !== "string") return null;
const quoted =
/\b(?:exec_command|shell_command)\s*\(\s*\{[\s\S]{0,1024}?\b(?:cmd|command)["']?\s*:\s*("(?:\\.|[^"\\])*"|'(?:\\.|[^'\\])*'|`[^`]*`)/u.exec(
value,
)?.[1];
if (quoted === undefined) return null;
if (quoted.startsWith('"')) {
return parseJson(() => quoted) as string | null;
}
return quoted.slice(1, -1).replaceAll(/\\(['`\\])/gu, "$1");
}
function toolDescription(
name: string,
arguments_: Readonly<Record<string, unknown>>,
input: unknown,
): string {
if (name === "send_message" || name === "followup_task") {
const target = arguments_["target"] ?? arguments_["recipient"];
const message = arguments_["message"] ?? arguments_["text"];
return `${name}${typeof target === "string" ? ` → ${target}` : ""}${typeof message === "string" ? `: ${prose(message, MAX_PROSE_CHARACTERS)}` : ""}`;
}
if (name === "spawn_agent") {
const task = arguments_["message"] ?? arguments_["task"];
return typeof task === "string"
? `spawn_agent · ${prose(task, MAX_PROSE_CHARACTERS)}`
: name;
}
if (name === "exec" && typeof input === "string") {
if (/\b(?:exec_command|shell_command)\s*\(/u.test(input)) {
return "exec · run shell command";
}
if (/\bapply_patch\s*\(/u.test(input)) return "exec · apply patch";
const tool = /\btools\.(?:\w+__)?(\w+)\s*\(/u.exec(input)?.[1];
if (tool !== undefined) return tool;
const search =
/\bALL_TOOLS\.(?:filter|find)\s*\([\s\S]{0,512}?\/([^/\r\n]+)\/[a-z]*/u.exec(
input,
)?.[1];
if (search !== undefined) {
return `find tools · ${search.replaceAll("|", ", ").replaceAll(/(?:\.\*|\.\?|_)/gu, "-")}`;
}
}
return name;
}
function sessionCallArguments(
payload: Readonly<Record<string, unknown>>,
): Record<string, unknown> {
if (isRecord(payload["action"])) return payload["action"];
const value = payload["arguments"] ?? payload["input"];
if (isRecord(value)) return value;
if (typeof value !== "string") return {};
const parsed = parseJson(() => value);
return isRecord(parsed) ? parsed : {};
}
const WINDOWS_DRIVE = /^(?:(?:\\\\|\/\/)[?.][\\/])?[a-z]:(?=[\\/])/i;
const UNC_SERVER = /^(?:\\\\|\/\/)(?:[?.][\\/]UNC[\\/])?[^\\/]+/i;
function windowsActivityRoot(path: string): string {
// Inspect the original separators: a POSIX directory name can begin with a backslash.
const root =
WINDOWS_DRIVE.exec(path)?.[0] ?? UNC_SERVER.exec(path)?.[0] ?? "";
return root
.replaceAll("\\", "/")
.replace(/[A-Z]/gu, (letter) => letter.toLowerCase());
}
function repositoryPathMatcher(repository: string, literal: boolean) {
const root = windowsActivityRoot(repository);
const normalize = (path: string) =>
literal && !root ? path : path.replaceAll("\\", "/");
const prefix = `${normalize(repository).replace(/\/$/u, "")}/`;
const directory = prefix.slice(root.length);
// A recorded UNC path can refer to either an SMB share or a case-sensitive
// WebDAV collection. Keep every component after the server exact.
return (raw: string, value = normalize(raw)): string | null => {
if (
value.startsWith(prefix) ||
(root !== "" &&
value.startsWith(directory, root.length) &&
windowsActivityRoot(raw) === root)
) {
return value.slice(prefix.length);
}
return null;
};
}
function literalRepositoryPaths(argv: string[], repository: string): string[] {
// The shell's -c argument is source text. Its positional arguments are literal.
const executable = argv[0] ?? "";
const posix = POSIX_SHELL.test(executable);
const powershell = /(?:^|[\\/])(?:pwsh|powershell)(?:\.exe)?$/iu.test(
executable,
);
let operands = argv;
if (posix || powershell) {
for (let i = 1; i < argv.length; i++) {
const part = argv[i]!;
if (
!part.startsWith("-") ||
part === "--" ||
(powershell && /^-file$/iu.test(part))
)
break;
if (posix && /^-[a-z]*c[a-z]*$/u.test(part)) {
const script = argv[i + 1] === "--" ? i + 2 : i + 1;
operands = argv.filter((_, index) => index !== script);
break;
}
if (powershell && /^-command$/iu.test(part)) {
operands = argv.slice(0, i);
break;
}
}
}
return operandRepositoryPaths(operands, repository, true);
}
function commandRepositoryPaths(
command: string,
repository: string,
shell: unknown,
): string[] {
const posixShell = typeof shell === "string" && POSIX_SHELL.test(shell);
const posixPaths = posixShell && windowsActivityRoot(repository) === "";
const paths = new Set<string>();
const roots = [
"$CODEX_SECURITY_REPOSITORY",
"${CODEX_SECURITY_REPOSITORY}",
repository,
].map((root) => repositoryPathMatcher(root, posixPaths));
for (const token of command.match(posixShell ? POSIX_TOKEN : SHELL_TOKEN) ??
[]) {
let value = token;
const first = token[0]!;
const quote =
(first === "'" || first === '"') && token.endsWith(first)
? first
: undefined;
const hasQuote = /['"]/u.test(token);
const hasEscape = posixPaths
? token.includes("\\")
: /\\[ \t]/u.test(token);
const posixLiteral = posixShell && (hasQuote || hasEscape);
if (posixLiteral) {
if (!posixPaths && !hasQuote && /\\(?![ \t])/u.test(token)) continue;
// A single-quoted or backslash-escaped dollar sign is literal.
const variable =
/^"?(\$(?:CODEX_SECURITY_REPOSITORY|\{CODEX_SECURITY_REPOSITORY\}))/u.exec(
token,
)?.[1];
const literal = literalPosixWord(
variable ? token.replace(variable, "") : token,
);
if (literal === undefined || literal.startsWith("$")) continue;
value = (variable ?? "") + literal;
} else if (quote) value = value.slice(1, -1);
const raw = posixLiteral ? value : value.replaceAll('\\"', '"');
value = posixPaths ? raw : raw.replaceAll("\\", "/");
if (process.platform === "win32" && quote !== "'") {
value = value.replace(
/^\$(?:env:CODEX_SECURITY_REPOSITORY|\{env:CODEX_SECURITY_REPOSITORY\})\//iu,
"$CODEX_SECURITY_REPOSITORY/",
);
}
for (const relativeTo of roots) {
const relative = relativeTo(raw, value);
if (relative === null) continue;
// Quotes, edge whitespace and colon-number suffixes can be filename data.
let path = relative;
if (!posixLiteral) {
// An opposite quote inside a quoted filename is literal data.
const boundary =
quote && !path.includes(quote) ? /[\r\n].*$/u : /["'\r\n].*$/u;
path = path.replace(boundary, "").trim();
}
path = path.replace(/\/+$/u, "");
if (!posixLiteral) path = path.replace(/:\d+(?::\d+)?$/u, "");
if (path !== "" && !path.split("/").includes("..")) paths.add(path);
}
if (paths.size >= MAX_ACTIVITY_PATHS) break;
}
return [...paths];
}
function argumentRepositoryPaths(value: unknown, repository: string): string[] {
if (!isRecord(value)) return [];
const candidates = [value["path"], value["file_path"], value["paths"]].flat();
return operandRepositoryPaths(candidates, repository);
}
function operandRepositoryPaths(
candidates: unknown[],
repository: string,
skipRoot = false,
): string[] {
const paths = new Set<string>();
const relativeTo = repositoryPathMatcher(repository, true);
for (const candidate of candidates) {
if (typeof candidate !== "string") continue;
const path = relativeTo(candidate);
if (
path !== null &&
(!skipRoot || path !== "") &&
!path.split("/").includes("..")
)
paths.add(path);
if (paths.size >= MAX_ACTIVITY_PATHS) break;
}
return [...paths];
}