Skip to content

OpenAI's Codex Security CLI and TypeScript SDK for finding, validating, and fixing security vulnerabilities. npm: https://www.npmjs.com/package/@openai/codex-security

feat: share knowledge bases across bulk scans (#237)

ianw-oai439af612dff2
diff --git a/README.md b/README.md
index c70d402d1..6ae20d94e 100644
--- a/README.md
+++ b/README.md
@@ -79,6 +79,9 @@ revisions. See the [container quick start](sdk/typescript/README.md#containerize
for authentication, private result storage, and optional Ubuntu AppArmor
hardening.
+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 the
diff --git a/sdk/typescript/README.md b/sdk/typescript/README.md
index 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 --su
npx @openai/codex-security install-hook
npx @openai/codex-security bulk-scan
npx @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.pdf
npx @openai/codex-security scans list /path/to/repository
npx @openai/codex-security scans list --scan-root /path/outside/repository/results
npx @openai/codex-security scans show SCAN_ID
@@ -222,8 +222,9 @@ directory and any enclosing Git worktree. When SARIF is produced, it is written
to
`<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 scans
diff --git a/sdk/typescript/src/cli.ts b/sdk/typescript/src/cli.ts
index 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.ts
index 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.ts
index 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.ts
index 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 },
),
);