The Problem

Developers need a repeatable way to discover, validate, and remediate security findings across codebases and CI pipelines. Existing manual scans are fragmented and hard to integrate with automated workflows, leading to missed vulnerabilities and inconsistent reporting.

What This Does

@openai/codex-security delivers a Node‑based CLI and a TypeScript SDK that orchestrate Codex Security scans, store results in a local work‑bench, and expose a programmatic API. The core runtime lives in sdk/typescript/src/, e.g.:

  • cli.ts – parses commands, handles authentication, and drives the scan flow.
  • api.ts – implements the high‑level CodexSecurity class used by the SDK (new CodexSecurity().run(.)).
  • runtime.ts – prepares the persistent state directory and launches the bundled plug‑in workers.

Support files (Dockerfile, docker/entrypoint.sh) enable containerised execution, while the test suite under sdk/typescript/tests-ts/ validates the CLI and SDK behavior.

How It Is Wired

Execution begins in sdk/typescript/src/cli.ts, function run (line 611). run invokes 65 functions across the CLI module and reaches 101 distinct functions downstream. The most traversed path is:

  1. run → runScan (line 2186) – initiates a scan.
  2. runScan calls preflight in api.ts, which validates input and authenticates via auth.ts.
  3. preflight → checkOpen, loginApiKey, and finally scanFailureMessage.
  4. scanFailureMessage → classifyConnectionFailure, the only place the code touches a database (detected via a regex match on SQLite‑related terms).

Key hub modules:

  • src/index.ts – imported by 17 other modules (instability 0.41). It re‑exports public SDK symbols, making it a high‑blast‑radius surface.
  • src/cli.ts – imported by 9 modules (instability 0.63) and imports 15 others, handling most command‑line logic.

The internal call graph contains 642 call edges; the most widely used functions are throwIfAborted (31 callers) and isRecord (23 callers). No circular import cycles were found, simplifying static reasoning.

External effects are limited: only the database read/write path noted above leaves the process. All other operations interact with the filesystem (state directory, bundled plug‑in scripts) or the network via the Codex Security API, but those calls are encapsulated in the SDK’s HTTP client (not exposed in the static graph).

How To Use It

# Clone the repo
git clone https://github.com/moses-y/codex-security
cd codex-security/sdk/typescript

# Install dependencies (pnpm is the lockfile format)
pnpm install

# Authenticate (requires an OpenAI API key)
npx codex-security login   # or set OPENAI_API_KEY beforehand

# Run a scan on the current directory
npx codex-security scan .

For containerised usage, build the image defined by Dockerfile:

docker build -t codex-security .
docker run --rm -v "$(pwd)":/work -e OPENAI_API_KEY=$OPENAI_API_KEY codex-security scan /work

Configuration is driven by environment variables (OPENAI_API_KEY, CODEX_SECURITY_STATE_DIR) as documented in README.md. No additional config files are required.

Real‑World Use

A CI job can invoke the CLI after checkout:

- name: Security scan
  run: npx codex-security scan .
  env:
    OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}

The scan writes a scan-manifest.json and findings.json to the work‑bench directory, which downstream steps can consume to fail builds on new high‑severity findings.

Code Health & Issues

  • MEDIUM – Enable Dependabot or Renovate – only one manifest (package.json) and no auto‑update bot.
  • MEDIUM – Add dependency‑vulnerability scan to CI – no existing scan in .github/workflows.
  • LOW – Set timeout-minutes on workflow jobs – node-release.yml lacks job timeouts.

Measured static findings (42 total) include:

  • HIGH – Oversized files (cli.ts, api.ts, runtime.ts each > 2 800 lines).
  • HIGH – Duplicated code blocks across bundled‑plugin Python scripts (≈ 87 repeats).
  • HIGH – Deep nesting (up to 8 levels) in several bundled‑plugin scripts.

These issues are reported by the analysis and include concrete fix suggestions (split files, extract shared helpers, flatten control flow). No critical or low‑severity structural problems were detected, and the repository contains tests, CI, a Dockerfile, and a license.

The Bottom Line

codex-security offers a functional CLI/SDK that integrates Codex Security scans into development and CI pipelines, with a clear entry point (cli.ts) and a well‑scoped SDK surface (index.ts). The codebase is sizable and contains several large, duplicated, or deeply nested files that increase maintenance cost. Adding automated dependency updates and a vulnerability‑scan step would improve long‑term reliability. Teams comfortable with TypeScript and containerised tooling will find it usable; smaller teams should be aware of the refactoring effort needed to tame the high‑complexity modules.