Agents-OSS
日本語
掲載申請
← プロジェクト一覧に戻る

codex-security

コードベースを走査して脆弱性を検出し、裏取りと修正まで行うCLIとTypeScript SDK。

公式Apache-2.0
スター
9.9k
フォーク
689
オープンIssue
129
最終コミット
2026年8月16日

概要

基本形は`npx @openai/codex-security scan .`で、結果のJSONはstdoutに出ます。`--mode deep`ではworkerとsubagentを並べ、新しい検出が出なくなるまで探索を続けます。再スキャン時は`scans compare BEFORE_SCAN_ID AFTER_SCAN_ID`が根本原因で前回と突き合わせ、new／persisting／reopened／resolved／unknownに分類するため、差分だけを追えます。ただし探索は既定で96時間まで回る長丁場であり、コミット前の軽量チェックには向きません。実行にはCodex Securityへのアクセスが前提で、一部のサイバーセキュリティ要求やprotected findingsはTrusted Access for Cyberの承認が必要になる点も、導入前に確認しておきたいところです。

codex-securityで何ができますか？

  • 1コマンドとSDKの両方から — 入口はnpx @openai/codex-security scan .で、--modelと--effort highにより走らせ方を調整します。TypeScriptではnew CodexSecurity()に対してrun(".")を呼ぶと同じ処理が走り、result.reportPathが返ります。
  • deepモードの打ち切り条件 — --mode deepは--workersと--subagentsで並列度を決め、--stop-after-no-new 3や--max-discovery-runs 10、--max-time-hours 1.5で上限を切ります。指定しなければ96時間で停止し、その時点で完了した検出結果は保持されて返却されます。
  • スキャン間の差分管理 — scans compareは保存済みのマッチを再利用しつつ根本原因で照合しますが、カバレッジが不完全だったり元の箇所が未レビューの場合はunknownのまま残ります。findings list [repository]は最新スキャンで再確認できなかった未解決の検出も示します。
  • 推論プロバイダの差し替え — --provider openrouterや--provider fireworks、--provider amazon-bedrockを--modelと組み合わせます。BedrockはAWS_BEARER_TOKEN_BEDROCKのほか、アクセスキーやプロファイル、web identity、既定のAWS認証チェーンにも対応します。
  • コンテナでの一括スキャン — 公式イメージと同梱のDocker Compose構成により、不変のGitリビジョンに固定した複数リポジトリを非対話かつ再開可能に処理します。--knowledge-base PATHは全リポジトリ共通のセキュリティ資料、--scan-prompt-file PATHは全リポジトリ共通のスキャン指示を渡すもので、リポジトリ個別の指示はCSVのprompt列に書きます。

ドキュメント

openai/codex-security のREADMEより転載（Apache-2.0）。 原文を読む ↗

Codex Security

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

See the Codex Security documentation for more details.

Some cybersecurity requests and protected findings require approval through Trusted Access for Cyber. To apply or check your access, visit chatgpt.com/cyber.

Quick start

Requires Node.js 22.13.0 or later in the 22.x release line, Node.js 24.x, or Node.js 26.x; Python 3.10 or later; and access to Codex Security.

npm install @openai/codex-security
npx @openai/codex-security login
npx @openai/codex-security scan .
npx @openai/codex-security scan . --model gpt-5.6-terra --effort high
npx @openai/codex-security scan . --scan-prompt-file scan.md --post-scan-prompt-file follow-up.md
npx @openai/codex-security scan . --mode deep --workers 2 --subagents 0 --stop-after-no-new 3 --max-discovery-runs 10 --max-time-hours 1.5

For CI, set OPENAI_API_KEY or CODEX_API_KEY instead of signing in. Environment API keys are passed directly to the current scan and are never stored in Codex’s credential home or system keyring.

Deep-scan discovery stops after 96 hours by default. Set --max-time-hours to any positive number of hours, including fractional hours, up to 96. Completed findings are preserved and returned when the limit is reached.

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

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

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

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

Amazon Bedrock also supports standard AWS access keys, profiles, web identity, container credentials, and the default AWS credential chain.

Local sign-in honors Codex’s configured credential backend, including a system keyring required by a managed device. Codex Security keeps login and scan credentials in the same private, persistent state directory.

If both a ChatGPT sign-in and an API key are available, interactive scans ask which credential to use. CI and other noninteractive scans keep the existing API-key precedence. Select a credential explicitly when needed:

npx @openai/codex-security scan . --auth chatgpt
npx @openai/codex-security scan . --auth api-key

To make your ChatGPT sign-in the automatic default, unset any configured API keys:

unset OPENAI_API_KEY CODEX_API_KEY

Scan history is stored in the Codex Security workbench state directory. If that directory cannot be written, set CODEX_SECURITY_STATE_DIR to a writable directory outside the repository.

findings list [repository] shows open findings across a repository’s scans and identifies findings not confirmed in its latest scan.

scans compare BEFORE_SCAN_ID AFTER_SCAN_ID automatically matches findings by root cause, reuses saved matches, and identifies new, persisting, reopened, resolved, or unknown findings. Missing findings remain unknown when coverage is incomplete or their original location was not reviewed.

Verbose diagnostics

Add --verbose to print scan diagnostics to stderr:

npx @openai/codex-security scan . --verbose

CODEX_SECURITY_LOG_LEVEL=debug also enables diagnostics; LOG_LEVEL=debug is its fallback. JSON results remain on stdout.

Verbose diagnostics may contain sensitive data. Review local logs before sharing them. Saved failure summaries, bulk-scan receipts, and the interactive dashboard omit messages that contain recognizable credentials.

Use npx @openai/codex-security scans logs SCAN_ID to inspect saved session events from a scan and its workers.

TypeScript SDK

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

const security = new CodexSecurity();
const result = await security.run(".");
await security.run(".", {
  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 official image and included Docker Compose configuration for noninteractive, resumable scans of repositories pinned to immutable Git revisions. See the container quick start 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.

Use --scan-prompt-file PATH to add shared scan instructions, and add a prompt CSV column for repository-specific instructions. Use --post-scan-prompt-file PATH to run a follow-up after each scan, including incomplete or failed scans.

For complete command help, runtime defaults, native multi-agent worker limits, environment variables, deep-scan configuration, and SDK options, see the package README and the official CLI reference.