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
feat: share knowledge bases across bulk scans (#237)
ianw-oai439af612dff2
diff --git a/README.md b/README.mdindex c70d402d1..6ae20d94e 100644--- a/README.md+++ b/README.md@@ -79,6 +79,9 @@ revisions. See the [container quick start](sdk/typescript/README.md#containerizefor authentication, private result storage, and optional Ubuntu AppArmorhardening.+Pass `--knowledge-base PATH` to share security documents with every repository;+repeat the option for multiple files or directories.+For complete command help, runtime defaults, native multi-agent worker limits,environment variables, deep-scan configuration, and SDK options, see the[package README](sdk/typescript/README.md) and thediff --git a/sdk/typescript/README.md b/sdk/typescript/README.mdindex 12aa405ed..a42b064c4 100644--- a/sdk/typescript/README.md+++ b/sdk/typescript/README.md@@ -187,7 +187,7 @@ npx @openai/codex-security scan /path/to/repository --mode deep --workers 2 --sunpx @openai/codex-security install-hooknpx @openai/codex-security bulk-scannpx @openai/codex-security bulk-scan --model gpt-5.6-terra --effort high-npx @openai/codex-security bulk-scan repositories.csv --output-dir /path/outside/repositories/security-scans --workers 4+npx @openai/codex-security bulk-scan repositories.csv --output-dir /path/outside/repositories/security-scans --workers 4 --knowledge-base /path/to/threat-models --knowledge-base /path/to/architecture.pdfnpx @openai/codex-security scans list /path/to/repositorynpx @openai/codex-security scans list --scan-root /path/outside/repository/resultsnpx @openai/codex-security scans show SCAN_ID@@ -222,8 +222,9 @@ directory and any enclosing Git worktree. When SARIF is produced, it is writtento`<scan-dir>/exports/results.sarif`.-Repeat `--knowledge-base PATH` for multiple files or directories. Directories are-searched recursively for Markdown, text, PDF, and Word (`.docx`) files.+Repeat `--knowledge-base PATH` for multiple files or directories; `bulk-scan`+shares them with every repository. Directories are searched recursively for+Markdown, text, PDF, and Word (`.docx`) files.### Configure deep scansdiff --git a/sdk/typescript/src/cli.ts b/sdk/typescript/src/cli.tsindex 4ff4f0267..34f773d84 100644--- a/sdk/typescript/src/cli.ts+++ b/sdk/typescript/src/cli.ts@@ -1272,6 +1272,10 @@ export async function main(.describe("Resumable results directory; required with a repository CSV.",),+ knowledgeBase: z+ .array(optionValue("--knowledge-base"))+ .default([])+ .describe("Read shared security docs for every repository."),workers: z.number().int()@@ -1343,13 +1347,15 @@ export async function main(if (argument === "--model" ||argument === "--effort" ||- argument === "--codex"+ argument === "--codex" ||+ argument === "--knowledge-base") {optionIndex += 2;} else if (argument.startsWith("--model=") ||argument.startsWith("--effort=") ||- argument.startsWith("--codex=")+ argument.startsWith("--codex=") ||+ argument.startsWith("--knowledge-base=")) {optionIndex += 1;} else {@@ -1358,7 +1364,7 @@ export async function main(}if (argv[0] !== "bulk-scan" || optionIndex !== argv.length) {throw new Error(- "Run 'codex-security bulk-scan [--model MODEL] [--effort EFFORT] [--codex KEY=VALUE]' to discover repositories, or provide a CSV and --output-dir.",+ "Run 'codex-security bulk-scan [--model MODEL] [--effort EFFORT] [--codex KEY=VALUE] [--knowledge-base PATH]' to discover repositories, or provide a CSV and --output-dir.",);}const wizard = await runBulkScanWizard(@@ -1390,6 +1396,7 @@ export async function main(workers: options.workers,mode: options.mode,maxAttempts: options.maxAttempts,+ knowledgeBasePaths: options.knowledgeBase,config: {pluginPath: options.pluginPath,pythonPath: options.python,diff --git a/sdk/typescript/src/multiscan.ts b/sdk/typescript/src/multiscan.tsindex 534715a6c..4795bcfdb 100644--- a/sdk/typescript/src/multiscan.ts+++ b/sdk/typescript/src/multiscan.ts@@ -49,6 +49,7 @@ export interface MultiscanOptions {inputPath: string;outputDir: string;githubHost?: string;+ knowledgeBasePaths?: string[];workers: number;mode: ScanMode;maxAttempts: number;@@ -181,6 +182,9 @@ async function runCampaign(}const result = await security.run(checkout, {...(task.scope === undefined ? {} : { target: [task.scope] }),+ ...(options.knowledgeBasePaths?.length+ ? { knowledgeBasePaths: options.knowledgeBasePaths }+ : {}),mode: task.mode,outputDir: scanDir,...(options.signal === undefined ? {} : { signal: options.signal }),diff --git a/sdk/typescript/tests-ts/cli.test.ts b/sdk/typescript/tests-ts/cli.test.tsindex d71686199..3f4d5879f 100644--- a/sdk/typescript/tests-ts/cli.test.ts+++ b/sdk/typescript/tests-ts/cli.test.ts@@ -674,6 +674,9 @@ describe("CLI", () => {"gpt-5.6-terra","--effort","high",+ "--knowledge-base",+ "/shared/architecture.pdf",+ "--knowledge-base=/shared/threat-models","--codex","features.goals=true","--json",@@ -701,7 +704,13 @@ describe("CLI", () => {model_reasoning_effort: "high",},});- expect(scanOptions).toMatchObject({ mode: "deep" });+ expect(scanOptions).toMatchObject({+ mode: "deep",+ knowledgeBasePaths: [+ "/shared/architecture.pdf",+ "/shared/threat-models",+ ],+ });expect(stderr.text()).toContain("sample started (attempt 1)");expect(stderr.text()).toContain("sample completed (attempt 1)");} finally {@@ -760,6 +769,18 @@ describe("CLI", () => {["bulk-scan", "--codex", 'model_reasoning_effort="high"'],["bulk-scan", '--codex=model_reasoning_effort="high"'],["bulk-scan", "--model", "gpt-5.6-terra", "--effort", "high"],+ ["bulk-scan", "--knowledge-base", "/shared/threat-models"],+ [+ "bulk-scan",+ "--knowledge-base=/shared/architecture.pdf",+ "--model=gpt-5.6-terra",+ "--effort",+ "high",+ "--codex",+ "features.goals=true",+ "--knowledge-base",+ "/shared/threat-models",+ ],] as const) {const stdout = capture();const stderr = capture();@@ -1766,6 +1787,10 @@ describe("CLI", () => {"expected number to be >0",],[["scan", ".", "--path="], "--path must not be empty"],+ [+ ["bulk-scan", "--knowledge-base="],+ "--knowledge-base must not be empty",+ ],[["scan", ".", "--model="], "--model must not be empty"],[["scan", ".", "--effort", "ultra"],diff --git a/sdk/typescript/tests-ts/multiscan.test.ts b/sdk/typescript/tests-ts/multiscan.test.tsindex f357fac97..429bb793e 100644--- a/sdk/typescript/tests-ts/multiscan.test.ts+++ b/sdk/typescript/tests-ts/multiscan.test.ts@@ -331,6 +331,10 @@ describe("multiscan", () => {test("limits simultaneous checkouts to the requested worker count", async () => {const paths = await fixture();+ const knowledgeBasePaths = [+ join(paths.root, "architecture.md"),+ "shared/threat-model.md",+ ];const sources = await Promise.all(["one", "two", "three"].map((name) => repository(paths.root, name)),);@@ -352,6 +356,7 @@ describe("multiscan", () => {release = resolve;});const security = client(async (_repository, scanOptions = {}) => {+ expect(scanOptions.knowledgeBasePaths).toEqual(knowledgeBasePaths);active += 1;maximum = Math.max(maximum, active);if (active === 2) release();@@ -362,6 +367,7 @@ describe("multiscan", () => {const summary = await runMultiscan(options(paths, security, {workers: 2,+ knowledgeBasePaths,createSecurity: () => {created += 1;let running = false;@@ -444,6 +450,7 @@ describe("multiscan", () => {const paths = await fixture();const source = await repository(paths.root, "retry");const secret = "sk-proj-SYNTHETIC_MULTISCAN_SECRET_123";+ const knowledgeBasePaths = ["architecture.md"];const proxyUrl ="https://SYNTHETIC_USER:[email protected]/v1/responses";const queryUrl =@@ -470,6 +477,7 @@ describe("multiscan", () => {options(paths,client(async (_repository, scanOptions = {}) => {+ expect(scanOptions.knowledgeBasePaths).toEqual(knowledgeBasePaths);attempts += 1;if (attempts === 1) {throw new Error(@@ -478,6 +486,7 @@ describe("multiscan", () => {}return await completedScan(scanOptions.outputDir!);}),+ { knowledgeBasePaths },),);