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 { execFile as execFileCallback } from "node:child_process";
import { lstat, readdir, realpath } from "node:fs/promises";
import { join, relative } from "node:path";
import { promisify } from "node:util";
import { CodexSecurityError, InvalidTargetError } from "./errors.js";
import type { OwnerFinding } from "./suggest-owners.js";
import {
nullIfMissingFile,
enclosingGitWorktreeRoot,
gitMetadataDirectories,
normalizeRepository,
relativePathIsOutside,
validatedGitEnvironment,
} from "./targets.js";
import { resolveTrustedExecutable } from "./trusted-executable.js";
import {
codeownersForPath,
parseCodeowners,
type CodeownerIdentity,
} from "./codeowners.js";
const execFile = promisify(execFileCallback);
export interface OwnerIdentity {
name: string;
email: string;
}
export interface OwnerEvidence {
id: string;
kind: "source" | "blame" | "history" | "codeowners";
path: string;
commit: string;
/** Original blamed commit; blame citations keep commit at the checkout revision. */
blameCommit?: string;
startLine?: number;
endLine?: number;
rule?: string;
matchedPath?: string;
content: string;
identityIndex: number | null;
}
export interface OwnerContext {
identities: OwnerIdentity[];
evidence: OwnerEvidence[];
limitations: string[];
codeowner: CodeownerIdentity | null;
}
/** Read committed objects, so dirty files and source symlinks are never followed. */
export async function ownerRepository(
repository: string,
environment: NodeJS.ProcessEnv,
signal?: AbortSignal,
) {
repository = await normalizeRepository(repository, signal);
validatedGitEnvironment(environment);
repository =
(await enclosingGitWorktreeRoot(repository, signal, {
requireIfPresent: true,
})) ?? repository;
const executable = await resolveTrustedExecutable(
"git",
environment,
repository,
);
if (executable === null)
throw new CodexSecurityError("Git is required to suggest owners.");
const run = async (cwd: string, args: string[], encoding: BufferEncoding) => {
signal?.throwIfAborted();
const { stdout } = await execFile(executable.executable, args, {
cwd,
env: { ...executable.environment, GIT_NO_LAZY_FETCH: "1" },
signal,
maxBuffer: Infinity,
encoding: "buffer",
});
return stdout.toString(encoding);
};
const [gitDirectory, commonDirectory, ...objectDirectories] =
await gitMetadataDirectories(repository, signal, {
includeLocalObjects: true,
});
const metadataDirectories = [...new Set([gitDirectory, commonDirectory])];
if (
objectDirectories.some((path) =>
metadataDirectories.every((root) =>
relativePathIsOutside(relative(root, path)),
),
)
) {
throw new InvalidTargetError(
"Git objects are not bound to the selected checkout. Use a checkout that does not borrow external object stores.",
);
}
await requireBoundMetadata(metadataDirectories, objectDirectories, signal);
// Blame otherwise reads an uncommitted .mailmap from the working directory.
const gitOutput = (encoding: BufferEncoding, ...args: string[]) =>
run(
gitDirectory,
[
`--git-dir=${gitDirectory}`,
"--literal-pathspecs",
"-c",
"core.bare=true",
"-c",
"i18n.logOutputEncoding=UTF-8",
...args,
],
encoding,
);
const git = (...args: string[]) => gitOutput("utf8", ...args);
const revision = (await git("rev-parse", "--verify", "HEAD^{commit}")).trim();
const files = new Set(
(await gitOutput("latin1", "ls-tree", "-r", "-z", "--full-tree", revision))
.split("\0")
.filter((record) => /^100(?:644|755) blob /u.test(record))
.map((record) => record.slice(record.indexOf("\t") + 1)),
);
const shallow =
(await git("rev-parse", "--is-shallow-repository")).trim() === "true";
// Latin-1 keys preserve Git's filename bytes, including unrelated non-UTF-8 names.
const hasFile = (path: string) =>
path.isWellFormed() && files.has(Buffer.from(path).toString("latin1"));
const loadCodeowners = async () => {
const path = [".github/CODEOWNERS", "CODEOWNERS", "docs/CODEOWNERS"].find(
hasFile,
);
if (path === undefined) return null;
const source = await git("cat-file", "blob", `${revision}:${path}`);
// GitHub requires CODEOWNERS to be under 3 MB.
return {
path,
rules:
Buffer.byteLength(source) >= 3_000_000 ? null : parseCodeowners(source),
};
};
let codeowners: ReturnType<typeof loadCodeowners> | undefined;
return {
git,
revision,
hasFile,
shallow,
// Keep the load lazy so failures remain inside per-finding error handling.
codeowners: () => (codeowners ??= loadCodeowners()),
};
}
/** Neither references nor objects may link into another checkout. */
async function requireBoundMetadata(
metadataDirectories: string[],
objectDirectories: string[],
signal?: AbortSignal,
): Promise<void> {
const pending = [
...objectDirectories,
...metadataDirectories.flatMap((directory) =>
["HEAD", "refs", "packed-refs", "reftable"].map((name) =>
join(directory, name),
),
),
];
const visited = new Set<string>();
while (pending.length > 0) {
signal?.throwIfAborted();
const path = pending.pop()!;
if (visited.has(path)) continue;
visited.add(path);
const entry = await lstat(path).catch(nullIfMissingFile);
if (entry?.isSymbolicLink()) {
const destination = await realpath(path);
if (
metadataDirectories.every((root) =>
relativePathIsOutside(relative(root, destination)),
)
) {
throw new InvalidTargetError(
"Git metadata is not bound to the selected checkout. Select the intended checkout or repair its Git metadata.",
);
}
pending.push(destination);
} else if (entry?.isDirectory()) {
for (const name of await readdir(path)) pending.push(join(path, name));
}
}
}
export async function collectOwnerEvidence(
finding: OwnerFinding,
repository: Awaited<ReturnType<typeof ownerRepository>>,
): Promise<OwnerContext> {
const { git, revision, hasFile, shallow } = repository;
const context: OwnerContext = {
identities: [],
evidence: [],
codeowner: null,
limitations: [
"Git authors are not verified tracker accounts or proof of current employment.",
],
};
if (shallow)
context.limitations.push(
"This checkout has shallow history; earlier contributors may be missing.",
);
const stale =
finding.sourceRevision !== undefined && finding.sourceRevision !== revision;
if (stale)
context.limitations.push(
"The finding revision differs from HEAD; its line ranges were not used.",
);
if (finding.locations.length === 0)
context.limitations.push("No source locations were supplied.");
const identityIndex = (name: string, email: string) => {
const index = context.identities.findIndex(
(identity) => identity.email === email,
);
if (index !== -1) return index;
return context.identities.push({ name, email }) - 1;
};
const add = (item: Omit<OwnerEvidence, "id">) => {
context.evidence.push({ id: `e${context.evidence.length + 1}`, ...item });
};
const codeowners = await repository.codeowners();
if (codeowners !== null) {
if (codeowners.rules === null) {
context.limitations.push(
"CODEOWNERS meets or exceeds GitHub's 3 MB file-size limit and was ignored.",
);
} else {
for (const { path } of finding.locations) {
if (!hasFile(path)) continue;
const rule = codeownersForPath(codeowners.rules, path);
if (rule === undefined) continue;
const owner = rule.owners[0];
if (owner === undefined) continue;
context.codeowner = owner;
context.limitations.push(
"CODEOWNERS identities are declarations; their existence and repository access are not verified.",
);
add({
kind: "codeowners",
path: codeowners.path,
commit: revision,
startLine: rule.line,
endLine: rule.line,
rule: rule.rule,
matchedPath: path,
content: rule.rule,
identityIndex: null,
});
return context;
}
}
}
for (const path of new Set(finding.locations.map(({ path }) => path))) {
if (!hasFile(path)) {
context.limitations.push(`Not a regular file at HEAD: ${path}`);
continue;
}
const source = await git("cat-file", "blob", `${revision}:${path}`);
if (!source || source.includes("\0")) {
context.limitations.push(`Source is empty or binary: ${path}`);
continue;
}
const lines = source.replace(/\n$/u, "").split("\n");
const locations = stale
? [{ path }]
: finding.locations.filter((location) => location.path === path);
for (const location of locations) {
const start = location.startLine ?? 1;
if (start > lines.length) {
context.limitations.push(
`Finding line is outside the committed file: ${path}:${start}`,
);
continue;
}
// Include surrounding code for the model, but attribute only the affected lines.
const end = Math.min(
location.endLine ?? location.startLine ?? lines.length,
lines.length,
);
const excerptStart = Math.max(1, start - 10);
const excerptEnd = Math.min(lines.length, end + 10);
add({
kind: "source",
path,
commit: revision,
startLine: excerptStart,
endLine: excerptEnd,
content: lines
.slice(excerptStart - 1, excerptEnd)
.map((line, index) => `${excerptStart + index}: ${line}`)
.join("\n"),
identityIndex: null,
});
const blame = await git(
"blame",
"--line-porcelain",
"--no-textconv",
"--ignore-revs-file=",
"-L",
`${start},${end}`,
revision,
"--",
path,
);
let commit = "",
name = "",
email = "",
line = 0;
for (const value of blame.split("\n")) {
const header = /^([a-f0-9]{40,64}) \d+ (\d+)(?: \d+)?$/u.exec(value);
if (header) {
commit = header[1]!;
line = Number(header[2]);
} else if (value.startsWith("author ")) name = value.slice(7);
else if (value.startsWith("author-mail <")) email = value.slice(13, -1);
else if (value.startsWith("\t") && email.trim()) {
const index = identityIndex(name, email);
const previous = context.evidence.at(-1);
if (
previous?.kind === "blame" &&
previous.blameCommit === commit &&
previous.identityIndex === index &&
previous.endLine === line - 1
) {
previous.endLine = line;
} else {
add({
kind: "blame",
path,
commit: revision,
blameCommit: commit,
startLine: line,
endLine: line,
content: `Authored in ${commit}.`,
identityIndex: index,
});
}
}
}
}
const history = (
await git(
"log",
"--no-use-mailmap",
"--no-show-signature",
"--no-notes",
"--no-decorate",
"--format=%H%x00%an%x00%ae%x00%aI%x00%s",
"-z",
revision,
"--",
path,
)
).split("\0");
for (let index = 0; index + 4 < history.length; index += 5) {
const [commit, name, email, date, subject] = history.slice(
index,
index + 5,
) as [string, string, string, string, string];
if (email.trim())
add({
kind: "history",
path,
commit,
content: `${date}: ${subject}`,
identityIndex: identityIndex(name, email),
});
}
}
return context;
}