Codex Security TypeScript SDK

Use the Codex Security TypeScript SDK to run security scans on repositories and code changes from your application or developer tool. The SDK returns typed findings, coverage details, and paths to scan artifacts. For longer scans, it supports preflight checks, cost limits, progress callbacks, and cancellation.

The SDK uses ECMAScript modules (ESM) and runs server-side with Node.js 22 or later. Scanning also requires Python 3.10 or later.

Set up the SDK

Follow the installation instructions provided for your Codex Security access. Then set OPENAI_API_KEY or CODEX_API_KEY, or use an existing file-backed Codex sign-in before starting a scan.

Depending on your account and repository, full-repository scans may also require Trusted Access for Cyber, which signing in or providing an API key does not grant.

Run a scan

Create one CodexSecurity client, run a standard repository scan, and close the client when the work completes. Pass outputDir to choose a private results directory outside the enclosing Git worktree.

If you omit outputDir, Codex Security saves results in its own persistent state directory. Results can include source excerpts and vulnerability details, so choose appropriate permissions and retention policies.

import { CodexSecurity } from "@openai/codex-security";

const security = new CodexSecurity();

try {
  const result = await security.run("/path/to/repository", {
    outputDir: "/path/outside/repository/results",
  });

  console.log(result.reportPath);
  console.log(result.coverage.completeness);
  console.log(result.findings.findings.length);
} finally {
  await security.close();
}

run starts the scan, waits for completion, validates the sealed artifacts, and returns a ScanResult. close releases the isolated runtime and supports repeated calls.

Check inputs with preflight

Use preflight to check a repository, target, mode, output location, and Codex configuration before starting a scan:

const plan = await security.preflight("/path/to/repository", {
  target: ["services/billing", "packages/auth"],
  outputDir: "/path/outside/repository/results",
});

console.log(plan.repository);
console.log(plan.target.kind);
console.log(plan.mode);
console.log(plan.outputDir);

Preflight leaves the Codex runtime and credentials untouched. It also leaves plugin and Python discovery for the scan itself. This makes preflight useful for checking user input before a long-running or credentialed operation.

To preview archival for an existing result directory, set archiveExisting: true:

const plan = await security.preflight("/path/to/repository", {
  outputDir: "/path/outside/repository/results",
  archiveExisting: true,
});

console.log(plan.archiveDir);

The returned archiveDir previews the archive naming. The final path can differ because run generates its own unique destination. Capture the actual archive path with onOutputArchived:

await security.run("/path/to/repository", {
  outputDir: "/path/outside/repository/results",
  archiveExisting: true,
  onOutputArchived(archiveDir) {
    console.log("Archived results:", archiveDir);
  },
});

The scan archives the earlier results and starts with an empty output directory.

Choose a scan target

The SDK supports repository, path, committed-diff, and working-tree targets. The default target is the complete repository.

Scan selected paths

Pass an array of paths inside the repository:

const result = await security.run("/path/to/repository", {
  target: ["services/billing", "packages/auth"],
});

Paths can identify files or directories. The SDK resolves each path inside the repository and removes duplicates.

Scan committed changes

Use DiffTarget.refs to scan committed changes between two locally available Git revisions:

import { DiffTarget } from "@openai/codex-security";

const target = DiffTarget.refs({
  base: "origin/main",
  head: "HEAD",
});

const result = await security.run("/path/to/repository", { target });

The head defaults to HEAD. Diff targets require the repository argument to be the Git worktree root.

Scan the working tree

Use DiffTarget.workingTree to scan staged and unstaged changes against a base revision:

const target = DiffTarget.workingTree({ base: "HEAD" });
const result = await security.run("/path/to/repository", { target });

The base defaults to HEAD. Fetch the selected revisions before starting a diff or working-tree scan.

Select deep mode

Set mode: "deep" for a repository or path scan that needs broader review:

const result = await security.run("/path/to/repository", {
  target: ["services/billing"],
  mode: "deep",
});

Deep mode supports repository and path targets. Use standard mode for diff and working-tree scans.

Add a security knowledge base

Pass architecture documents, threat models, or security policies through knowledgeBasePaths:

const result = await security.run("/path/to/repository", {
  knowledgeBasePaths: [
    "/path/to/architecture.md",
    "/path/to/security-policies",
  ],
});

The SDK accepts files or directories and searches directories recursively. Supported document formats are .md, .markdown, .txt, .pdf, and .docx. The SDK rejects linked input paths, skips linked directory entries, and keeps extracted document content outside the saved scan results.

Set a scan budget

Set maxCostUsd to stop a scan when its estimated model cost exceeds a limit. Use onCost to track cost as the scan runs:

const result = await security.run("/path/to/repository", {
  maxCostUsd: 5,
  onCost(cost) {
    console.log(cost.estimatedUsd);
  },
});

console.log(result.cost?.estimatedUsd);

The limit is an estimate, not a hard spending cap. Requests already in progress can finish above it. If the scan exceeds the limit, the SDK throws ScanCostLimitExceededError and preserves the available results.

Work with scan results

ScanResult exposes the structured documents, scan metadata, and artifact paths:

Use the structured findings and coverage directly:

for (const finding of result.findings.findings) {
  const location = finding.locations[0];
  if (location === undefined) continue;

  console.log(
    finding.severity.level,
    `${location.path}:${location.startLine}`,
    finding.title
  );
}

for (const deferred of result.coverage.deferred) {
  console.log(deferred.id, deferred.reason);
}

Coverage completeness is complete, partial, or unknown. Review deferred surfaces, exclusions, and open questions before using a scan as evidence for a security decision.

result.toJSON() returns the manifest, findings, coverage, scan and thread identifiers, reportPath, artifactsDir, sarifPath, and turn metadata in one JSON-ready object.

Track or cancel a scan

Pass ScanOptions callbacks to report scan startup, worker progress, and connection retries:

const result = await security.run("/path/to/repository", {
  outputDir: "/path/outside/repository/results",
  onScanStarted() {
    console.log("Scan started");
  },
  onWorkerStatus(status) {
    console.log(status.kind, status);
  },
  onReconnect(attempt, maxAttempts) {
    console.log(`Reconnect attempt ${attempt} of ${maxAttempts}`);
  },
  onObserverError(observer, error) {
    console.error(`${observer} failed`, error);
  },
});

console.log(result.reportPath);

Pass an AbortSignal when cancellation comes from a request, job controller, or timeout:

import { ScanInterruptedError } from "@openai/codex-security";

const controller = new AbortController();

try {
  const scan = security.run("/path/to/repository", {
    outputDir: "/path/outside/repository/results",
    signal: controller.signal,
  });

  controller.abort();
  await scan;
} catch (error) {
  if (error instanceof ScanInterruptedError) {
    console.error(error.scanDir);
  } else {
    throw error;
  }
}

An interrupted scan can leave partial output in scanDir. Preserve that directory when the result needs investigation.

Applications that display scan setup progress can also use the ScanOptions lifecycle callbacks:

Configure the runtime and credentials

Pass runtime configuration when you need a specific plugin, interpreter, or Codex setting:

const security = new CodexSecurity({
  pluginPath: "/path/to/codex-security-plugin",
  pythonPath: "/path/to/python",
  codexOverrides: {
    model: "<model>",
  },
});

pluginPath accepts a plugin directory or ZIP. pythonPath selects the plugin interpreter. codexOverrides merges supported values into the isolated Codex configuration.

The client also exposes supported authentication methods:

A login handle provides waitForInstructions, authUrl, verificationUrl, userCode, wait, and cancel so an application can present and complete the selected sign-in flow. The SDK can reuse a file-backed Codex sign-in. API keys are a useful fit for CI and server-side automation.

Handle scan errors

Catch the exported error class that matches the action your application can take:

Continue with the CLI quickstart, CI guide, or CLI reference.