Codex Security CLI 快速開始

Codex Security 幫助安全和工程團隊發現、確認並修復漏洞。你可以使用命令列介面（CLI）掃描自己擁有或獲准評估的儲存庫，持續審查安全發現，並在變更落地前檢查相關風險。

檢查先決條件

CLI 需要 Node.js 22 或更高版本。執行掃描或匯出結果還需要 Python 3.10 或更高版本。有關更多詳細資訊，請參閱認證和先決條件。

設定並驗證 CLI

安裝公開發布的軟體包：

npm install @openai/codex-security

列出可用的命令：

npx @openai/codex-security --help

另請參閱 CLI 參考。

登入

對於本機使用，請使用你的 ChatGPT 賬號登入：

npx @openai/codex-security login

在遠端或無頭計算機上，使用裝置認證：

npx @openai/codex-security login --device-auth

對於 CI 和其他自動化工作流程，請改用 OpenAI API key：

export OPENAI_API_KEY="<your-api-key>"

有關 AWS 憑據，請參閱 Amazon Bedrock 設定。

如需使用已儲存的登入憑據，請傳入 --auth chatgpt：

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

要強制使用環境變數中的 API key，請顯式選擇 API key 認證：

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

根據你的賬號和儲存庫，完整儲存庫掃描可能還需要 Trusted Access for Cyber。

準備掃描

選擇要掃描的儲存庫和要寫入結果的目錄。

REPOSITORY=/path/to/repository
SCAN_DIR=/path/outside/repository/codex-security-results

如果省略 --output-dir，Codex Security 會將結果儲存在其自己的持久狀態目錄中。結果可以包括源程式碼摘錄和漏洞詳細資訊，因此請選擇私有位置和適當的保留策略。

如果預設狀態目錄不可寫，請選擇掃描儲存庫之外的可寫目錄：

export CODEX_SECURITY_STATE_DIR=/path/outside/repository/codex-security-state

在開始掃描之前檢查儲存庫、目標和輸出目錄：

npx @openai/codex-security scan "$REPOSITORY" --output-dir "$SCAN_DIR" --dry-run

試執行會檢查本機輸入，而無需啟動 Codex、載入憑據或探測外掛的 Python 直譯器。

執行你的第一次掃描

執行標準掃描並將其結果儲存在選定的目錄中：

npx @openai/codex-security scan "$REPOSITORY" --output-dir "$SCAN_DIR"

預設情況下，CLI 會將掃描進度和完成摘要寫入 stderr，而不會把完整掃描結果寫入 stdout。完成的掃描會列印如下摘要：

codex-security: Findings: 2 (1 high, 1 medium). Coverage: complete.
codex-security: Elapsed: 42s.
codex-security: Report: /path/outside/repository/codex-security-results/report.md
codex-security: Results: /path/outside/repository/codex-security-results

如果要把完整結果作為機器可讀的 JSON 輸出，請顯式請求結構化輸出：

npx @openai/codex-security scan "$REPOSITORY" --output-dir "$SCAN_DIR" --json

預設情況下，掃描只生成報告，結果會留在本機供你審查。準備好在 CI 中執行掃描 後，可以再新增嚴重性閾值。

選擇模型和推理強度

掃描預設使用 gpt-5.6-sol 和 xhigh 推理強度。任務需要其它設定時，可以選擇不同的模型和推理強度：

npx @openai/codex-security scan "$REPOSITORY" \
  --model gpt-5.6-terra \
  --effort high

支援的推理強度為 minimal、low、medium、high 和 xhigh。

檢視結果

開啟 report.md 即可得到可讀結果。掃描目錄還包含自動化使用的結構化檔案：

codex-security-results/
├── scan-manifest.json
├── findings.json
├── coverage.json
├── report.md
├── artifacts/
└── exports/
    └── results.sarif       # when produced

• scan-manifest.json 記錄目標、範圍、生產者和已封存的產物。
• findings.json 記錄每項安全發現的嚴重性、置信度、位置、證據和補救措施。
• coverage.json 記錄已審查範圍、排除、延後處理的工作、未解決的問題和覆蓋範圍的完整性。

覆蓋範圍可以是 complete、partial 或 unknown。在將掃描視為審查證據之前，請閱讀任何延後處理的範圍或未解決的問題。 CLI 參考 描述了完整的產物和輸出合約。

選擇下一次掃描

當儲存庫包含單獨的服務或包時，使用路徑掃描：

npx @openai/codex-security scan "$REPOSITORY" --path services/billing --path packages/auth

檢視基礎修訂版和 HEAD 之間已提交的更改：

npx @openai/codex-security scan "$REPOSITORY" --diff origin/main --head HEAD

針對 HEAD 檢查已暫存和未暫存的更改：

npx @openai/codex-security scan "$REPOSITORY" --working-tree --base HEAD

差異和工作樹掃描期望儲存庫參數是 Git 工作樹根。在開始差異掃描之前獲取選定的修訂版本。

當儲存庫或路徑需要更廣泛的審查時，請使用深度模式：

npx @openai/codex-security scan "$REPOSITORY" --mode deep

深度模式支援儲存庫和路徑目標，不支援 diff 或工作樹掃描。

新增架構和安全上下文

提供架構文件、威脅模型或安全策略作為掃描上下文。這有助於 Codex Security 根據系統的實際工作方式評估結果：

npx @openai/codex-security scan "$REPOSITORY" \
  --knowledge-base /path/to/architecture.md \
  --knowledge-base /path/to/security-policies

設定掃描預算

當估計模型成本超過美元限制時，使用 --max-cost 停止掃描：

npx @openai/codex-security scan "$REPOSITORY" --max-cost 5

已在處理的請求可能會超出限制。Codex Security 在掃描停止時保留可用結果。

每次提交前掃描更改

為你的儲存庫安裝 Git 預提交安全檢查：

npx @openai/codex-security install-hook

該檢查會在每次提交前掃描已暫存和未暫存的更改。它可以阻止高嚴重性安全發現和掃描錯誤，且不會替換現有的 pre-commit 指令碼。

批次掃描儲存庫

在發現儲存庫之前登入 GitHub：

gh auth login

從你的 GitHub 賬號或組織中發現並選擇儲存庫：

npx @openai/codex-security bulk-scan

互動流程不會列出已歸檔儲存庫和 fork，並會要求你在掃描前確認所選儲存庫。

要掃描準備好的儲存庫列表，請提供 CSV 和輸出目錄：

npx @openai/codex-security bulk-scan repositories.csv \
  --output-dir /path/outside/repositories/security-scans \
  --workers 4

再次運行同一命令即可恢復現有批次掃描。已經完成且結果產物完整的儲存庫不會被重複掃描。需要重試臨時的儲存庫檢出錯誤或掃描錯誤時，請新增 --max-attempts 3。

有關 GitHub 發現、CSV 準備、批次掃描結果和 Docker 設定，請參閱執行批次安全掃描。

在 Docker 中執行批次掃描

如果你的存取權限包含 Codex Security Docker 映象，請在 Linux Docker 主機上使用提供的加固版 Compose 設定和安全設定檔。主機必須支援建立非特權使用者名稱空間。準備儲存庫 CSV，將結果和登入狀態儲存在持久掛載目錄中，並通過環境變數或 secret manager 提供憑據：

docker compose run --rm codex-security \
  bulk-scan /input/repositories.csv \
  --output-dir /output \
  --workers 4

容器會以非互動方式執行批次掃描。如需互動式發現儲存庫，請在 Docker 外部使用 CLI。對於私有儲存庫，請通過環境變數或 secret manager 提供 GH_TOKEN 或 GITHUB_TOKEN。登入要求（包括賬號和儲存庫存取權限）同樣適用於容器化掃描。

重新存取儲存的掃描

列出儲存庫中儲存的掃描：

npx @openai/codex-security scans list "$REPOSITORY"

從結果中複製掃描 ID 以檢查其結果和設定：

npx @openai/codex-security scans show SCAN_ID

要把已審查的安全發現標記為誤報，請說明為什麼該發現不適用：

npx @openai/codex-security findings false-positive FINDING_OCCURRENCE_ID \
  --reason "The route already checks permissions"

後續掃描會參考這項說明，但仍會重新檢查當前程式碼。

使用原始設定針對當前檢出內容重新運行同一掃描：

npx @openai/codex-security scans rerun SCAN_ID

要比較兩次掃描，首先匹配具有相同根本原因的結果：

npx @openai/codex-security scans match PREVIOUS_SCAN_ID CURRENT_SCAN_ID

然後檢查哪些結果是新的、持續存在的、重新開啟的、已解決的或未知的：

npx @openai/codex-security scans compare PREVIOUS_SCAN_ID CURRENT_SCAN_ID

有關批次掃描 CSV 格式、掃描歷史過濾器和命令選項，請參閱 CLI 參考。

繼續適合你目標的工作流程：

• 執行批次安全掃描，發現 GitHub 儲存庫或掃描固定 revision 的 CSV 清單。
• 閱讀 CLI 常見問題解答 瞭解有關掃描歷史記錄、誤報回饋、覆蓋範圍和修復驗證的答案。
• 在 CI 中執行掃描 以檢視 pull requests、保留結果並設定嚴重性策略。
• 使用 CLI 參考，檢視每個 flag、輸出格式、產物和退出碼。
• 整合 TypeScript SDK 從應用或開發工具執行掃描。