codex-security README

The project's README from github.com/openai/codex-security. As one markdown file: README.md.

Codex Security

@openai/codex-security is a CLI and TypeScript SDK for defining security policy and finding, validating, and fixing security vulnerabilities in your code.

👉👉 See the Codex Security documentation for full documentation.

Some cybersecurity requests and protected findings require approval through Trusted Access for Cyber. To join the program, visit chatgpt.com/cyber.

Quick start

Requires Node.js 22.13.0 or later and Python 3.10 or later.

npm install @openai/codex-security
codex-security login
codex-security scan /path/to/directory

For CI, set OPENAI_API_KEY instead of signing in.

Generate SECURITY.md

Draft repository-wide or component-scoped SECURITY.md guidance for future scans:

codex-security policy .
codex-security policy . --path services/api --knowledge-base architecture.md

The command saves a draft outside the checkout; it does not install it or run a vulnerability scan. Review the proposed diff before copying the policy. Supporting architecture, threat-model, and review documents stay outside the repository and may contain sensitive details. See the SDK policy guide for headless generation, saved artifacts, and SDK usage.

TypeScript SDK

Codex Security is a Javascript package:

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

const security = new CodexSecurity();
const result = await security.run("/path/to/directory");
await security.run("/path/to/directory", {
  mode: "deep",
  workers: 2,
  subagents: 0,
  stopAfterNoNew: 3,
  maxDiscoveryRuns: 10,
  maxTimeHours: 1.5,
});

console.log(result.reportPath);
await security.close();

Containerized bulk scans

Use the included Docker Compose configuration for scans of many repositories. See the container quick start for more detail.

For individual CLI stages with durable state and access to a separately deployed findings service, use the same scanner image with the workflow runner Compose example.

Findings service (preview)

Run codex-security serve to start the service without Docker. See running without Docker for prerequisites, credentials, and storage configuration.

The findings service runs from the same ghcr.io/openai/codex-security image as the scanner (or a local source build), with a separate container and state volume configured by compose.findings.yaml. It stores findings and embeddings in SQLite and lists findings with pagination. Its read-only dashboard at /dashboard refreshes every five seconds and shows stored findings and duplicate groups from the service's database. It also returns potential duplicates by embedding similarity within a repository or an explicit all-repository scope. The codex-security publish scan --to custom --findings-url http://localhost:3000 command uploads completed findings and their repository ID. The SDK and codex-security dedupe command retrieve candidates, run independent Codex reviews locally, and persist accepted duplicate groups; --all-repositories opts into the broader scope.

Use codex-security classify-severity --scan SCAN_ID --rubric /path/to/policy.md to assess selected findings under your own policy before publishing tickets. Scan classification checkpoints each finding in SQLite and reuses matching assessments on reruns; --reprocess forces reassessment. The SDK exposes the same classification operation; original scan severity stays unchanged. See severity classification.

Other providers

To use another inference provider, set its API key and select a model:

export AWS_BEARER_TOKEN_BEDROCK="<your-bedrock-api-key>"
export AWS_REGION="us-east-2"
codex-security scan . --provider amazon-bedrock --model openai.gpt-5.6-luna

export OPENROUTER_API_KEY="<your-openrouter-api-key>"
codex-security scan . --provider openrouter --model anthropic/claude-sonnet-4.5

export FIREWORKS_API_KEY="<your-fireworks-api-key>"
codex-security scan . --provider fireworks --model accounts/fireworks/models/qwen3-235b-a22b

Documentation

👉👉 See the Codex Security documentation for full documentation.

codex-security (openai/codex-security)

Searching Database…

11.1K ·GitHub
Codex-security
这是什么？Codex Security 是 OpenAI 推出的命令行工具和 TypeScript SDK，用于定义安全策略，并在代码中发现、验证和修复安全漏洞。
它是命令行工具、SDK，还是两者都是？两者都是：既可以在终端中运行的命令行工具，也可以作为 JavaScript 包安装的 TypeScript SDK；另外还提供基于 Docker 的扫描器和检测结果服务，适用于规模更大的部署。
我该怎么把它跑起来？安装 @openai/codex-security npm 包，然后运行快速开始命令，生成 SECURITY.md 并开始扫描；如需批量扫描多个代码仓库，请使用随附的 Docker Compose 配置。
我需要先安装什么？还需要登录吗？你需要先安装 Node.js 22.13.0 或更高版本，以及 Python 3.10 或更高版本；交互使用时需要登录，在持续集成（CI）中则需要设置 OpenAI API 密钥。
它能扫描或报告的内容有限制吗？部分网络安全相关请求和受保护的检测结果需要先通过 OpenAI 的 Trusted Access for Cyber 计划审批，才能使用。
我的扫描结果存在哪里？检测结果服务会将检测结果及其嵌入向量存储在本地 SQLite 中，并提供一个只读仪表板，每五秒刷新一次，显示已存储的检测结果和重复组。
我能一次扫描很多代码仓库吗？可以，随附的 Docker Compose 配置专门用于通过扫描器镜像对多个代码仓库进行容器化批量扫描。
我只能使用 OpenAI 的模型吗？不是，你可以设置其他推理服务商的 API 密钥并选择其模型，切换到该服务商。
classify-severity 命令有什么作用？codex-security classify-severity 可让你按照自己的策略评分标准，对选定的检测结果进行评估，然后再发布工单；结果会按每次扫描缓存，重新运行时会复用，除非你传入 --reprocess。
检测结果如何发布或分享？codex-security publish scan --to custom --findings-url 命令会将已完成的检测结果及其代码仓库 ID 上传到检测结果服务，该服务还支持通过嵌入向量相似度进行去重。
What are similar projects?0, cynative, VulnHunter, strix, mantis, shannon, Myrqen, SkillSpector
Which topics is it in?application-security, devsecops, vulnerability-scanner, ai-security, static-analysis, cli-tool, cybersecurity, security-tools, sqlite, sdk, dashboard, openai
Creator
openai
Size
59.6 MB
Stars
11.1K
Updated
CommitOct 16Releasenpm-v0.3.0Oct 15
Age
3mo
Commits · 90 Days