Codex Security CLI 快速入門

使用獨立的 Codex Security CLI 對本機儲存庫執行 標準掃描。本快速入門最終會生成一份已儲存的報告，供你審查和日後查閱。 要在 Codex 對話中執行掃描，請使用 Codex Security 外掛。

檢查先決條件

請使用 Node.js 24 或 26，或 22.13.0 及以上的 Node.js 22。 你還需要 Python 3.10 或更高版本。 Python 3.10 還需要 tomli。使用 OpenAI 推理的掃描需要 Codex Security 存取權限。 根據你的帳戶和儲存庫情況，全儲存庫掃描可能還 需要 Trusted Access for Cyber。

CLI 使用你在作業系統中的權限執行，不會暫停以等待 核准。 掃描程序可能繼承你的環境，因此請在開始前移除無關的 憑據。請參閱本機掃描 權限。

設定並驗證 CLI

使用 npx 執行公開發布的包：

npx @openai/codex-security --version

該命令會輸出已安裝的包版本。使用 info --json 檢查 隨包附帶的外掛版本，或使用 --help 列出命令。包的變更記錄 列在 CLI 和 SDK 版本中。

登入

使用你的 ChatGPT 帳戶登入：

npx @openai/codex-security login

在沒有瀏覽器的機器上，新增 --device-auth 並按照顯示的 登入說明操作。在下方的掃描命令中使用 --auth chatgpt，即可選擇 該登入方式，即使環境中同時存在 API key。

有關 API key 和其他供應商，請參閱選擇掃描 身分驗證方式。 對於 Amazon Bedrock，請使用 AWS 憑據和模型 存取權限，而不是 ChatGPT 登入或 OpenAI API key。

準備掃描

將這些路徑替換為你的儲存庫路徑，以及位於 其 Git 工作樹之外的新結果目錄路徑：

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

結果可能包含源程式碼摘錄和漏洞詳情。請選擇私密的 位置。如果省略 --output-dir，CLI 將使用其持久狀態目錄。

檢查目標和輸出位置：

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

試執行成功可確認本機輸入有效。它不會啟動掃描、載入 憑據，也不會檢查外掛的 Python 直譯器，因此不能據此確定 身分驗證和執行環境設定能否成功。

執行首次掃描

移除 --dry-run 以啟動掃描：

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

互動式終端會顯示即時儀表板。非互動式終端會逐行顯示 進度。新增 --headless 也可在互動式終端中逐行顯示進度。 儀表板和儲存的日誌可能包含源程式碼或憑據。分享前請先 檢查這些內容。

掃描完成後，stderr 會包含報告路徑、發現項數量和 耗時。例如：

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

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

預設情況下，發現項的嚴重程度不會導致掃描失敗。如需 機器可讀的 stdout，請新增 --json。要讓發現項導致 CI 檢查失敗，請設定 嚴重程度策略。

檢視結果

從所報告的目錄中開啟 report.md。確認目標和修訂版本， 然後先閱讀覆蓋範圍，再逐一審查發現項。

檢查 scan-manifest.json 中的 scan.status，確認掃描已完成。 檢視 coverage.json，瞭解已審查的範圍、排除的路徑、暫緩的工作 以及待解決的問題。

掃描完成後會以 0 退出，除非發現項達到已設定的嚴重程度 閾值，此時傳回 1。覆蓋缺口不會改變退出碼，因此 退出碼為 0 並不意味著每個檔案都已審查。輸入、執行、結果完整性 或必需輸出方面的故障會傳回 2。 CLI 參考介紹了 這些退出碼。

對於每個發現項，請檢查受影響的程式碼、攻擊者所需的前提條件、驗證 證據以及尚存的不確定性。基於源程式碼的發現項不一定 包含成功的執行時重現。只有在證據足以支援所述問題後， 才應選擇修復該發現項。

分享或歸檔時，請保留完整的掃描目錄。其中包含 scan-manifest.json、findings.json 和 coverage.json，以及報告 和支援性產物。完整佈局請參閱掃描 產物。

重新檢視已儲存的掃描

列出該儲存庫的掃描：

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

從結果中複製掃描 ID：

npx @openai/codex-security scans show SCAN_ID

互動式掃描完成且存在發現項後，CLI 還會提供發現項 瀏覽器。選擇修復方案前，請先在其中審查證據。對於已儲存的發現項， 請使用驗證和修補 命令。

選擇下一次掃描

有關身分驗證問題、重複掃描的差異或誤報 回饋，請參閱 CLI 常見問題。