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 { AsyncLocalStorage } from "node:async_hooks";
import { constants } from "node:fs";
import { pathToFileURL } from "node:url";
import { access, realpath, stat } from "node:fs/promises";
import {
basename,
delimiter,
dirname,
extname,
isAbsolute,
join,
relative,
resolve,
sep,
} from "node:path";
export interface TrustedExecutable {
executable: string;
environment: Record<string, string | undefined>;
}
export interface InspectedExecutable {
executable: string | null;
environment: Record<string, string | undefined>;
}
interface ToolPathView {
path: string;
cleanup(): void;
allows: (path: string) => boolean;
}
const campaignScope = new AsyncLocalStorage<{
roots: readonly string[];
views: Map<string, ToolPathView>;
project: (
path: string,
cwd: string,
roots: readonly string[],
mode: "campaign",
) => ToolPathView;
}>();
function canonicalRoot(root: string): Promise<string> {
return realpath(root).catch(() => resolve(root));
}
async function bundledToolHelpers() {
const { bundledPluginRoot } = await import("./bundled-plugin.js");
const path = join(await bundledPluginRoot(), "mcp/helpers.mjs");
return (await import(pathToFileURL(path).href)).default;
}
export async function trustedHostPathResolver(
cwd: string,
roots: readonly string[],
): Promise<(path: string) => string | null> {
const { protectedHostPathResolver } = await bundledToolHelpers();
if (typeof protectedHostPathResolver !== "function")
throw new Error("The bundled plugin is missing host path protection.");
return protectedHostPathResolver(cwd, roots);
}
async function campaignPathHelper() {
const { inventoryToolPath: project } = await bundledToolHelpers();
if (typeof project !== "function")
throw new Error("The bundled plugin is missing campaign tool lookup.");
return project;
}
/** Include every selected source when a campaign launches tools from a new checkout. */
export async function withProtectedExecutableRoots<T>(
roots: readonly string[],
run: () => Promise<T>,
): Promise<T> {
const canonical = await Promise.all(roots.map(canonicalRoot));
const scope = {
roots: [
...new Set([...(campaignScope.getStore()?.roots ?? []), ...canonical]),
],
views: new Map<string, ToolPathView>(),
project: await campaignPathHelper(),
};
try {
return await campaignScope.run(scope, run);
} finally {
for (const view of scope.views.values()) view.cleanup();
}
}
/** Bind an actual host launcher and its environment within this campaign. */
export function campaignExecutable(
candidate: string,
environment:
Readonly<NodeJS.ProcessEnv> | (() => Readonly<NodeJS.ProcessEnv>),
): Promise<TrustedExecutable> | undefined {
if (!campaignScope.getStore()) return;
const env = typeof environment === "function" ? environment() : environment;
return resolveTrustedExecutable(candidate, env, []).then(async (command) => {
if (!command)
throw new Error(
`Campaign executable is unavailable on a trusted PATH: ${candidate}`,
);
// Windows launchers inherit the same filtered PATH as checkout.
if (process.platform === "win32" && candidate !== "git")
command.environment = (
await inspectTrustedExecutable("git", command.environment, [])
).environment;
return command;
});
}
/** Host launchers and the workbench inherit the same Git search path as checkout. */
export function campaignCommandEnvironment(
environment: Record<string, string | undefined>,
): Promise<Record<string, string | undefined>> | undefined {
if (!campaignScope.getStore()) return undefined;
return inspectTrustedExecutable("git", environment, []).then(
(command) => command.environment,
);
}
function searchPath(
environment: Readonly<NodeJS.ProcessEnv>,
): string | undefined {
return (
environment["PATH"] ??
Object.entries(environment).find(
([name, value]) => value !== undefined && name.toUpperCase() === "PATH",
)?.[1]
);
}
export async function resolveTrustedExecutable(
candidate: string,
environment: Readonly<Record<string, string | undefined>>,
protectedRoot: string | readonly string[],
): Promise<TrustedExecutable | null> {
const inspected = await inspectTrustedExecutable(
candidate,
environment,
protectedRoot,
);
return inspected.executable === null
? null
: { executable: inspected.executable, environment: inspected.environment };
}
export async function inspectTrustedExecutable(
candidate: string,
environment: Readonly<Record<string, string | undefined>>,
protectedRoot: string | readonly string[],
): Promise<InspectedExecutable> {
const selectedRoots = await Promise.all(
(typeof protectedRoot === "string" ? [protectedRoot] : protectedRoot).map(
canonicalRoot,
),
);
const campaign = campaignScope.getStore();
const extra = campaign
? selectedRoots.filter(
(root) => !campaign.roots.some((base) => isWithin(base, root)),
)
: selectedRoots;
const roots = campaign ? [...campaign.roots, ...extra] : selectedRoots;
const isProtected = (path: string) =>
roots.some((root) => isWithin(root, path));
const path =
searchPath(environment) ??
(campaign
? process.platform === "win32"
? searchPath(process.env)
: "/usr/bin:/bin"
: undefined);
const entries: string[] = [];
for (let entry of path?.split(delimiter) ?? []) {
if (
process.platform === "win32" &&
entry.startsWith('"') &&
entry.endsWith('"')
) {
entry = entry.slice(1, -1);
}
if (entry.length === 0) continue;
const canonical = await realpath(entry).catch(() => null);
if (canonical === null || isProtected(canonical)) continue;
// A directory containing the separator can be on PATH through a safe alias.
// Keep that absolute spelling so joining the entries cannot split its name.
const directory = canonical.includes(delimiter)
? isAbsolute(entry)
? entry
: `${process.cwd()}${sep}${entry}`
: canonical;
if (
!directory.includes(delimiter) &&
!isProtected(directory) &&
!entries.includes(directory)
)
entries.push(directory);
}
let view: ToolPathView | undefined;
if (campaign) {
// Workers inherit this PATH across process boundaries. Keep the links until
// every row, including its pending child processes, has settled.
const path = entries.join(delimiter);
const cwd = process.cwd();
const key = JSON.stringify([cwd, extra, path]);
view = campaign.views.get(key);
if (!view) {
view = campaign.project(path || "/dev/null", cwd, roots, "campaign");
campaign.views.set(key, view);
}
}
const pathLike = candidate.includes("/") || candidate.includes("\\");
// execFile cannot launch batch files, but their symlink targets still affect PATH trust.
// CreateProcess appends .exe to an extensionless explicit path, so inspect the file that
// will actually run instead of rejecting an otherwise valid Windows configuration.
const windows = process.platform === "win32";
const suffixes =
!windows || /\.(?:exe|com)$/iu.test(candidate)
? [""]
: pathLike
? [extname(candidate) === "" ? ".exe" : ""]
: [".exe", ".com", ".bat", ".cmd", ""];
const primary = suffixes.map((suffix) => candidate + suffix);
// The Windows MCP launcher and inventory look up Node and ripgrep on this PATH.
const names =
campaign && windows && candidate === "git"
? [...primary, "node.exe", "rg.exe", "rg.com"]
: primary;
const candidates = (pathLike ? [null] : entries).flatMap((entry) => {
// PATH lookup traverses links before "..". join() would collapse it first.
const directory = entry ?? "";
const prefix =
directory && !directory.endsWith(sep) ? directory + sep : directory;
return names.map((name) => ({
entry,
path: entry === null && windows ? resolve(name) : prefix + name,
runnable:
primary.includes(name) && (!windows || /\.(?:exe|com)$/iu.test(name)),
}));
});
const unsafeEntries = new Set<string>();
let executable: string | null = null;
for (const current of candidates) {
const crossesSource = view !== undefined && !view.allows(current.path);
if (!pathLike && crossesSource) {
if (current.entry !== null) unsafeEntries.add(current.entry);
continue;
}
const canonical = await realpath(current.path).catch(() => null);
if (canonical === null) continue;
if (
isProtected(canonical) ||
(pathLike && view && crossesSource && !view.allows(canonical))
) {
if (current.entry !== null) unsafeEntries.add(current.entry);
continue;
}
if (process.platform === "win32" && /\.(?:bat|cmd)$/iu.test(canonical)) {
continue;
}
if (!current.runnable) continue;
try {
await access(
canonical,
process.platform === "win32" ? constants.F_OK : constants.X_OK,
);
if (!(await stat(canonical)).isFile()) continue;
// Keep explicit virtualenv launchers, but resolve repository-local aliases
// to the trusted target instead of invoking them from the repository.
const invocationPath = pathLike
? join(await realpath(dirname(current.path)), basename(current.path))
: current.path;
executable ??=
pathLike &&
(crossesSource ||
isProtected(current.path) ||
isProtected(invocationPath))
? canonical
: invocationPath;
} catch {
continue;
}
}
const sanitizedEnvironment = { ...environment };
for (const name of Object.keys(sanitizedEnvironment)) {
if (name.toUpperCase() === "PATH") delete sanitizedEnvironment[name];
}
const filteredPath =
(windows ? undefined : view?.path) ??
entries.filter((entry) => !unsafeEntries.has(entry)).join(delimiter);
// An empty POSIX PATH searches the current directory.
sanitizedEnvironment["PATH"] =
campaign && process.platform !== "win32" && !filteredPath
? "/dev/null"
: filteredPath;
return { executable, environment: sanitizedEnvironment };
}
/** @internal */
export function isWithin(root: string, candidate: string): boolean {
const path = relative(root, candidate);
return (
path === "" ||
(path !== ".." && !path.startsWith(`..${sep}`) && !isAbsolute(path))
);
}