OpenAI's codex-security is a CLI and TypeScript SDK that scans codebases for vulnerabilities, validates findings, and drafts SECURITY.md policy for authorized security work.
| Tool | openai/codex-security — CLI and TypeScript SDK for defining security policy and finding, validating, and fixing vulnerabilities in code |
| Category | AI-assisted application security testing / SAST automation |
| Primary Use | Running npx @openai/codex-security scan against your own repositories during development, CI, or authorized assessments to surface and triage vulnerabilities |
| Safe Use | Use only against codebases you own or are explicitly authorized to test — internal development pipelines, CI security gates, and lab-based defensive research |
| Telemetry Note | Findings, embeddings, and classification checkpoints persist locally in SQLite; scans consume your configured inference provider's API, so review SECURITY.md and knowledge-base handling since supporting documents stay outside the repository by design |
@openai/codex-security is OpenAI's entry into the application-security tooling space: a CLI and TypeScript SDK, written in TypeScript and published to npm, that positions itself as a full loop for vulnerability management — finding, validating, and fixing security issues in code, plus generating the policy documents that guide future scans. The repository has gathered over ten thousand stars, is licensed under Apache-2.0, and carries topics from devsecops and code-scanning to ai-security and vulnerability-scanning, which tells you the intended audience is engineering teams integrating security automation into normal development workflows rather than offensive operators.
The runtime prerequisites are specific and worth noting: Node.js 22.13.0 or later and Python 3.10 or later. The Python requirement suggests the tooling spans more than a pure Node package internally, even though the primary distribution channel is npm. Installation is the expected one-liner, npm install @openai/codex-security, followed by npx @openai/codex-security login for interactive authentication. For CI environments the README explicitly directs you to set OPENAI_API_KEY instead of signing in, which is the right pattern for headless pipelines where browser-based OAuth isn't available.
The core operation is npx @openai/codex-security scan /path/to/directory. What makes this more interesting than a typical static analyzer is that the SDK exposes tunable discovery behavior: mode: "deep", workers, subagents, stopAfterNoNew, maxDiscoveryRuns, and maxTimeHours. The stopAfterNoNew and maxDiscoveryRuns parameters in particular reveal an iterative, agent-driven architecture — the scanner is apparently looping discovery passes and terminating on diminishing returns or a hard ceiling, not just running a fixed ruleset. That's a meaningful design signal: resource consumption and cost are first-class concerns, and operators get budget knobs (maxTimeHours: 1.5 in the example) to cap them.
The policy-generation side is a distinct workflow rather than a scan byproduct. Running npx @openai/codex-security policy . drafts a SECURITY.md, either repository-wide or scoped to a component via --path services/api. The --knowledge-base architecture.md flag lets you feed in supporting architecture or threat-model documents. Critically, the README is careful about safety here: the draft is saved outside the checkout, not installed, and no scan runs as part of generation. You're expected to review the proposed diff before copying the policy into place. The same caution applies to the knowledge-base files themselves — they may contain sensitive details and deliberately stay outside the repository.
Programmatic access goes through the CodexSecurity class exported from the package. The pattern is clean: instantiate, call run() on a directory (optionally with the tuning object described above), read result.reportPath, and call close() to release resources. The explicit close() in the example implies the SDK holds state — likely worker processes or provider connections — that needs deterministic teardown, which matters if you're embedding it in a long-lived service rather than a script.
For teams operating at fleet scale, the README ships a Docker Compose configuration for bulk scans of many repositories, built around a common image at ghcr.io/openai/codex-security. Separately, a workflow runner Compose example reuses the same image for individual CLI stages with durable state. The architecture here is compositional: one scanner image serves both interactive bulk scanning and orchestrated, stage-by-stage pipelines that talk to a separately deployed findings service.
The findings service, marked as preview, is where the triage machinery lives. It can be started without Docker via npx @openai/codex-security serve, or deployed through compose.findings.yaml with its own container and state volume. It stores findings and embeddings in SQLite, exposes paginated listing, and serves a read-only dashboard at /dashboard that refreshes every five seconds. The embedding similarity feature is the standout: the service groups potential duplicates within a repository or, if you opt in with --all-repositories, across your entire corpus — a direct answer to the deduplication problem that plagues any large-scale scanning program.
The deduplication loop itself is well designed from a trust standpoint. npx @openai/codex-security publish scan --to custom --findings-url http://localhost:3000 uploads completed findings to the service, and the dedupe command (or the SDK) retrieves candidate duplicates and then runs independent Codex reviews locally before persisting accepted duplicate groups. In other words, embedding similarity proposes, and a separate model review disposes — a two-stage pipeline that avoids both blind automatic merging and manual drudgery.
Severity triage gets the same policy-driven treatment. npx @openai/codex-security classify-severity --scan SCAN_ID --rubric /path/to/policy.md assesses selected findings under your own rubric before tickets are published, checkpoints each assessment in SQLite, and reuses matching assessments on reruns unless you pass --reprocess. Notably, original scan severity is left unchanged — classification is an overlay, not a mutation, which preserves the audit trail of what the scanner originally reported versus what your policy concluded.
Provider flexibility is a pragmatic touch for enterprises with existing inference commitments. Beyond the default, the tool supports amazon-bedrock (via AWS_BEARER_TOKEN_BEDROCK and AWS_REGION), openrouter, and fireworks, each selected with --provider and --model flags on the scan command. This means the analysis engine isn't hard-coupled to OpenAI's API surface, which materially changes procurement and data-residency conversations for organizations already running models in Bedrock.
One access-control detail deserves attention: the README states that some cybersecurity requests and protected findings require approval through Trusted Access for Cyber, with enrollment at chatgpt.com/cyber. This is a deliberate gatekeeping mechanism — presumably to keep the more powerful discovery capabilities out of misuse paths — and anyone planning serious adoption should factor the enrollment process into their rollout timeline. Configuration is handled through reusable YAML/JSON project settings with CLI overrides and editor schema support, documented in docs/project-configuration.md.
For defenders and AppSec leads, codex-security is best understood as an AI-augmented SAST-plus-triage platform: it finds issues, deduplicates them with embedding similarity plus independent review, classifies them under your own severity rubric, and generates the SECURITY.md policy that constrains future runs. Deployed against code you own in CI or an authorized assessment context, it consolidates a workflow that traditionally spans three or four separate tools. Watch the operational details — local SQLite state, out-of-repo knowledge bases, and API consumption across providers — and it slots cleanly into a modern DevSecOps pipeline.
openai/codex-security.Educational analysis for authorized security professionals. Use only in controlled, authorized environments.
0 comentários:
Post a Comment
Note: Only a member of this blog may post a comment.