從寫程式碼,到創作下一幕

探索 字節跳動 - 火山方舟 的 AI 程式設計與影片創作活動。

Agent Plan & Coding Plan

一站體驗多款熱門模型,為 AI 程式設計與智能體開發提供更多選擇。新使用者可聯絡(微信: goo_lvyouyou)免費體驗 9.9 agent plan。

Seedance 2.5

讓創意,躍然成片。探索 30 秒影片、多模態參考與局部編輯,把腦海中的畫面變成下一支作品。

繁體中文

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 參考

登入

在本機使用時,請使用您的 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 設定。對於 OpenRouter 或 Fireworks,請設定 供應商的 API key,並使用 --provider--model 選擇模型。

要在同時設定 API key 時使用 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

試執行會檢查本機輸入,包括所有 --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

支援的強度級別為 minimallowmediumhighxhighmax

檢視結果

開啟 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 記錄已檢查的範圍、排除項、延後工作、待解決 問題和覆蓋完整度。

覆蓋範圍可以是 completepartialunknown。在將掃描視為檢查證據之前, 請閱讀所有延後區域或待解決問題。 CLI 參考介紹了 完整的工件和輸出約定。

檢視並修復發現的問題

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

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

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

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

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

選擇下一種掃描

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

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_TOKENGITHUB_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 參考

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