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 { existsSync } from "node:fs";
import { readFile } from "node:fs/promises";
import { join } from "node:path";
import { z } from "zod";
import { parse as parseToml } from "smol-toml";
import { loadContract, sha256Text as sha256 } from "./contract.js";
import {
AuthenticationRequiredError,
CodexSecurityError,
errorMessage,
} from "./errors.js";
import type { Finding, ScanManifest } from "./models.js";
import {
CSV_TARGET_ID,
bindImportedFindings,
csvRowFinding,
parseFindingsCsv,
} from "./findings-import.js";
import {
bundledPluginRoot,
codexSecurityCredentialAllowsAmbientImport,
codexSecurityCredentialHome,
codexSecurityHasStoredFileCredentials,
credentialHomeUsesFileStorage,
withCredentialHomeLock,
expandHome,
} from "./runtime.js";
import { VERSION } from "./version.js";
import { cloudBaseUrl } from "./cloud-endpoint.js";
const CHATGPT_LOGIN_REQUIRED =
"Cloud publication requires a ChatGPT login already available to Codex Security and saved to a file. Set cli_auth_credentials_store = \"file\" in ~/.codex/config.toml (or $CODEX_HOME/config.toml), run 'codex-security login', then retry.";
const credentialsSchema = z.object({
auth_mode: z.literal("chatgpt").optional(),
OPENAI_API_KEY: z.null().optional(),
tokens: z.object({
access_token: z.string().trim().min(1),
account_id: z.string().trim().min(1),
}),
});
const receiptSchema = z.object({
status: z.literal("accepted"),
finding_ids: z.array(z.string().min(1)),
finding_count: z.number().int().positive(),
});
export interface CloudPublicationResult {
scanId: string;
findingIds: string[];
findingCount: number;
dryRun?: true;
findings?: Finding[];
}
interface CloudPublicationDependencies {
environment?: NodeJS.ProcessEnv;
fetch?: (url: string, options: RequestInit) => Promise<Response>;
signal?: AbortSignal;
dryRun?: boolean;
}
export async function publishScanToCloud(
scanDirectory: string,
dependencies: CloudPublicationDependencies & {
expectedScanId?: string;
} = {},
): Promise<CloudPublicationResult> {
const { manifest, findings } = await loadContract(scanDirectory, {
pluginRoot: await bundledPluginRoot(),
signal: dependencies.signal,
expectedScanId: dependencies.expectedScanId,
});
if (findings.findings.length === 0) {
throw new CodexSecurityError(
"The completed scan has no findings to publish.",
);
}
return publishCloudPayload(manifest.scan, findings.findings, dependencies);
}
export async function publishFindingsCsvToCloud(
csvPath: string,
dependencies: CloudPublicationDependencies = {},
): Promise<CloudPublicationResult> {
dependencies.signal?.throwIfAborted();
let source: string;
try {
source = new TextDecoder("utf-8", { fatal: true, ignoreBOM: true }).decode(
await readFile(csvPath),
);
} catch (error) {
throw new CodexSecurityError(
`Could not read findings CSV. ${errorMessage(error)}`,
{ cause: error },
);
}
dependencies.signal?.throwIfAborted();
const rows = parseFindingsCsv(source);
if (rows.length === 0) {
throw new CodexSecurityError(
"Findings CSV must contain at least one finding.",
);
}
const digest = sha256(source);
const scanId = `scan_csv_${sha256(
["codex-security-csv-import/v1", VERSION, source].join("\0"),
).slice(0, 24)}`;
const findings = bindImportedFindings(
rows.map(csvRowFinding),
"csv",
scanId,
CSV_TARGET_ID,
);
const timestamp = "1970-01-01T00:00:00.000Z";
const findingsDocument = JSON.stringify({
documentType: "codex-security.findings",
schemaVersion: "1.0",
scanId,
findings,
});
const scan: ScanManifest["scan"] = {
id: scanId,
producer: { name: "codex-security-cli", version: VERSION },
status: "completed",
startedAt: timestamp,
completedAt: timestamp,
sealedAt: timestamp,
target: {
kind: "directory_snapshot",
targetId: CSV_TARGET_ID,
displayName: "findings.csv",
snapshotDigest: `codex-security-snapshot/v1:sha256:${digest}`,
},
scope: {
includePaths: ["."],
excludePaths: [],
summary: "Findings imported from a Codex Security CSV export.",
},
mode: "repository",
review: { excludedPaths: [] },
findingsRef: "findings.json",
artifacts: [
{
path: "findings.json",
sha256: sha256(findingsDocument),
mediaType: "application/json",
},
{
path: "findings.csv",
sha256: digest,
mediaType: "text/csv",
},
],
};
return publishCloudPayload(scan, findings, dependencies);
}
async function publishCloudPayload(
scan: ScanManifest["scan"],
findings: Finding[],
dependencies: CloudPublicationDependencies,
): Promise<CloudPublicationResult> {
dependencies.signal?.throwIfAborted();
if (dependencies.dryRun) {
return {
scanId: scan.id,
findingIds: [],
findingCount: findings.length,
dryRun: true,
findings,
};
}
const environment = dependencies.environment ?? process.env;
const publishUrl =
environment["CODEX_SECURITY_CLOUD_PUBLISH_URL"]?.trim() ||
`${cloudBaseUrl(environment)}/cli/findings`;
const credentials = await readCloudCredentials(
environment,
dependencies.signal,
);
const timeout = AbortSignal.timeout(30_000);
const signal = dependencies.signal
? AbortSignal.any([dependencies.signal, timeout])
: timeout;
let response: Response;
try {
response = await (dependencies.fetch ?? globalThis.fetch)(publishUrl, {
method: "POST",
headers: {
Authorization: `Bearer ${credentials.access_token}`,
"ChatGPT-Account-ID": credentials.account_id,
"Content-Type": "application/json",
Accept: "application/json",
},
body: JSON.stringify({
schemaVersion: "1.0",
scan,
findings,
}),
redirect: "error",
signal,
});
} catch (error) {
dependencies.signal?.throwIfAborted();
// A lost response does not establish whether the server accepted the POST.
throw new CodexSecurityError(
`Cloud publication was not confirmed: ${errorMessage(error)}. The request was not retried; check whether it was accepted before submitting again.`,
{ cause: error },
);
}
if (!response.ok) {
await response.body?.cancel().catch(() => undefined);
const detail =
response.status === 401
? "Sign in with ChatGPT again before retrying."
: response.status === 403
? "The signed-in account is not authorized to publish to Cloud."
: response.status === 404
? "Cloud publication is not available for this account or deployment."
: "The request was not retried.";
throw new CodexSecurityError(
`Cloud publication failed (HTTP ${response.status}). ${detail}`,
);
}
const receipt = receiptSchema.safeParse(
await response.json().catch(() => {
dependencies.signal?.throwIfAborted();
return undefined;
}),
);
// Cloud assigns opaque IDs in request order, so they cannot be compared to
// local finding IDs. The authenticated response must still preserve the
// submitted count and return one distinct observation for each finding.
if (
(response.status !== 200 && response.status !== 201) ||
!receipt.success ||
receipt.data.finding_count !== findings.length ||
receipt.data.finding_ids.length !== findings.length ||
new Set(receipt.data.finding_ids).size !== receipt.data.finding_ids.length
) {
throw new CodexSecurityError(
"Cloud publication returned an invalid acceptance receipt. Check whether the request was accepted before submitting again.",
);
}
return {
scanId: scan.id,
findingIds: receipt.data.finding_ids,
findingCount: receipt.data.finding_count,
};
}
/** @internal Shared sign-in for local Cloud publishers. */
export async function readCloudCredentials(
environment: NodeJS.ProcessEnv,
signal?: AbortSignal,
) {
const dedicatedHome = codexSecurityCredentialHome(environment);
if (existsSync(dedicatedHome)) {
const dedicated = await withCredentialHomeLock(
dedicatedHome,
async () => {
if (
!(await codexSecurityCredentialAllowsAmbientImport(dedicatedHome))
) {
throw new AuthenticationRequiredError(CHATGPT_LOGIN_REQUIRED);
}
if (await codexSecurityHasStoredFileCredentials(dedicatedHome)) {
if (await credentialHomeUsesFileStorage(dedicatedHome))
return readCloudLoginFile(dedicatedHome);
throw new AuthenticationRequiredError(CHATGPT_LOGIN_REQUIRED);
}
// A dedicated configuration may point to a different account in the keyring.
if (existsSync(join(dedicatedHome, "config.toml")))
throw new AuthenticationRequiredError(CHATGPT_LOGIN_REQUIRED);
},
signal,
);
if (dedicated) return dedicated;
}
const configuredHome = environment["CODEX_HOME"];
const home = expandHome(
configuredHome?.trim() ? configuredHome : "~/.codex",
environment,
);
let credentialStorage: unknown;
try {
credentialStorage = parseToml(
await readFile(join(home, "config.toml"), "utf8"),
{ integersAsBigInt: "asNeeded" },
)["cli_auth_credentials_store"];
} catch {
throw new AuthenticationRequiredError(CHATGPT_LOGIN_REQUIRED);
}
// Ambient auto storage can leave a file for another account.
if (credentialStorage !== "file")
throw new AuthenticationRequiredError(CHATGPT_LOGIN_REQUIRED);
return readCloudLoginFile(home);
}
async function readCloudLoginFile(home: string) {
try {
const credentials = credentialsSchema.safeParse(
JSON.parse(await readFile(join(home, "auth.json"), "utf8")),
);
if (credentials.success) return credentials.data.tokens;
} catch {
// Parsing and filesystem diagnostics must not reflect credential contents.
}
throw new AuthenticationRequiredError(CHATGPT_LOGIN_REQUIRED);
}