Codex Security CLI 快速開始 | 本機掃描與報告 | Codex Security

Codex Security 可幫助安全和工程團隊發現、確認並修復漏洞。使用其命令列介面 (CLI) 掃描您擁有或獲准評估的儲存庫、持續檢視發現的問題，並在更改合入前進行檢查。

檢查先決條件

CLI 需要 Node.js 22（22.13.0 或更高版本）、24 或 26。掃描、批次掃描、匯出、掃描歷史記錄和已儲存的發現也需要 Python 3.10 或更高版本。有關更多詳細資訊，請參閱身份驗證和先決條件。

設定並驗證 CLI

使用 npx 執行 CLI 並檢查其版本：

npx @openai/codex-security --version

要同時檢視包版本及其捆綁外掛的版本，請執行：

npx @openai/codex-security info --json

有關包的變更，請參閱 CLI 和 SDK 版本。

列出可用命令：

npx @openai/codex-security --help

另請參閱 CLI 參考。

準備掃描

選擇您信任且獲准評估的儲存庫。掃描會使用您的本機作業系統權限，且不會暫停以等待核准。掃描程序可能會繼承您的環境，因此請在開始前移除無關憑據。請參閱本機掃描權限。

在儲存庫外選擇一個目錄來儲存掃描結果：

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

試執行會檢查本機輸入，包括所有 --knowledge-base 路徑，但不會啟動 Codex、載入憑據或探測外掛的 Python 直譯器。

執行首次掃描

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

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

互動式終端會顯示即時掃描器錶板。新增 --headless 可改為顯示純文本進度行。CI 和沒有互動式會話的終端會自動使用純文本進度。

儀表板還會顯示即時會話詳細資訊。這些資訊可能包含源程式碼或憑據，因此請在分享前進行檢查。

預設情況下，CLI 會將掃描進度及其完成摘要寫入 stderr。它不會將完整掃描結果輸出到 stdout。掃描完成後會輸出類似以下內容的摘要：

  REPORT    /path/outside/repository/codex-security-results/report.md

  FINDINGS  2 (2 confirmed this scan; 0 previously found; 1 high, 1 medium)
  COVERAGE  complete
  ELAPSED   42s
  RESULTS   /path/outside/repository/codex-security-results

Token 用量和預估費用會在可用時顯示。要以機器可讀的 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 和 max。

檢視結果

開啟 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 參考介紹了完整的工件和輸出約定。

檢視並修復發現的問題

完成包含發現問題的互動式掃描後，CLI 會提供發現問題瀏覽器。檢視證據並選擇要修復的問題。您可以在 Codex 桌面應用中找到已儲存的任務。

要在不使用瀏覽器的情況下修復高危和嚴重問題：

npx @openai/codex-security scan "$REPOSITORY" \
  --patch --patch-severity high --json

新增 --create-pr 可提交已驗證的補丁並建立 GitHub pull request。

您還可以修復已儲存的發現問題或匯入 Linear issue。請參閱 validate 和 patch 參考。

選擇下一種掃描

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

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

要控制 worker、子智能體以及掃描何時停止：

npx @openai/codex-security scan "$REPOSITORY" \
  --mode deep \
  --workers 2 \
  --subagents 0 \
  --stop-after-no-new 3 \
  --max-discovery-runs 10 \
  --max-time-hours 1.5

這些選項需要深度模式；該模式支援儲存庫和路徑目標，不支援差異掃描或工作樹掃描。此處，--workers 控制一次掃描中的獨立標準掃描 worker；bulk-scan --workers 控制並發儲存庫掃描。--max-time-hours 接受不超過 96 的正數，包括小數小時。達到限制時，掃描會停止尚未完成的 worker、保留已完成的掃描結果，並將其彙總到最終報告中。

新增架構和安全上下文

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

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

新增自定義掃描指令

新增指令，使掃描聚焦於您的安全重點。使用第二個檔案提供後續指令：

npx @openai/codex-security scan "$REPOSITORY" \
  --scan-prompt-file /path/to/scan.md \
  --post-scan-prompt-file /path/to/follow-up.md

後續操作會在成功掃描以及覆蓋不完整或出現錯誤的掃描之後，在同一已驗證身份的會話中執行。如果後續操作失敗，CLI 會報告警告並保留已完成的掃描。它不會在掃描取消或達到費用限制後執行。這兩個選項也適用於 bulk-scan；CSV 的 prompt 列可新增儲存庫專屬指令。

設定掃描預算

使用 --max-cost 可在掃描的預估模型費用超過以 USD 計的限制時停止掃描：

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

正在進行的請求完成後可能會略微超過限制。如果深度掃描在 Codex Security 彙總已完成的 worker 結果後達到限制，CLI 會儲存已完成的報告，將其覆蓋範圍標記為 partial，並傳回退出程式碼 2。如果掃描無法生成完整報告，任何可用的部分輸出都會保留在磁碟上。

在每次提交前掃描更改

為您的儲存庫安裝 Git pre-commit 安全檢查：

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

再次執行相同命令即可恢復現有的批次掃描。Codex Security 會跳過已完成的儲存庫。要重試臨時的儲存庫或掃描錯誤，請新增 --max-attempts 3。

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

在 Docker 中執行批次掃描

如果您的存取權限包含 Codex Security Docker 映象，請在 Linux Docker 主機上使用隨附的強化 Compose 設定和安全設定檔。主機必須支援建立非特權使用者名稱空間。提供儲存庫 CSV，將結果和登入狀態儲存在持久化掛載目錄中，並通過環境或金鑰管理器提供憑據：

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

容器執行批次掃描時不會顯示互動式提示。要以互動方式發現儲存庫，請在 Docker 外使用 CLI。對於私有儲存庫，請通過環境或金鑰管理器提供 GH_TOKEN 或 GITHUB_TOKEN。登入要求（包括帳戶和儲存庫存取權限）也適用於容器化掃描。

重新檢視已儲存的掃描

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

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

從結果中複製掃描 ID，以檢查其發現的問題和設定：

npx @openai/codex-security scans show SCAN_ID

要檢查某次掃描及其 worker 儲存的事件：

npx @openai/codex-security scans logs SCAN_ID

儲存的日誌未經過脫敏，可能包含源程式碼或憑據。請在分享前進行檢查。

列出儲存庫各次掃描中仍未解決的發現：

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

如果最新掃描未確認某個較早的發現，該發現仍會保持未解決狀態。

要將已檢視的發現標記為誤報，請說明該發現為何不適用：

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

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

使用原始設定對當前 checkout 執行相同的掃描：

npx @openai/codex-security scans rerun SCAN_ID

比較兩次掃描，以找出新增、持續存在、重新出現、已解決或狀態未知的發現：

npx @openai/codex-security scans compare PREVIOUS_SCAN_ID CURRENT_SCAN_ID

比較功能會按根本原因自動匹配發現，並複用已儲存的匹配結果。

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

繼續選擇符合您目標的工作流程：

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

最近搜尋

建議搜尋

文件導覽

Codex Security CLI 快速入門