Codex Security CLI 常見問題

尋找有關從終端掃描儲存庫和管理安全結果的常見問題的答案。對於安裝和首次掃描，請從 CLI 快速入門 開始。

儲存庫掃描

為什麼登入後掃描仍使用 API key

當環境中包含 OPENAI_API_KEY 或 CODEX_API_KEY 時，沒有互動式終端的掃描以及 JSON 和 JSONL 掃描預設使用環境變數中的 API key，即使你已經成功通過 ChatGPT 或 access token 登入。若 ChatGPT 登入也可用，使用文字輸出的互動式掃描會詢問要選擇哪種憑據。試執行不會提示選擇，也不會載入憑據。

如需在掃描中使用已儲存的憑據，請顯式選擇：

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

要強制使用 OPENAI_API_KEY 或 CODEX_API_KEY 中的 API key：

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

如需讓已儲存的憑據成為自動選擇的預設值，請執行 unset OPENAI_API_KEY CODEX_API_KEY。所有支援的認證模式請參閱 CLI 參考。

中斷的批次掃描可以恢復嗎

可以。使用原始 CSV 和輸出目錄執行相同的 bulk-scan 命令。 Codex Security 會跳過已完成的儲存庫。

新增 --max-attempts 3 以重試臨時儲存庫或掃描錯誤：

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

已完成的掃描會保留結果，且不會重試，即使仍存在覆蓋缺口 也是如此。覆蓋缺口不會導致批次掃描任務以退出碼 2 退出。

安全發現與覆蓋範圍

團隊在哪裡可以找到早期的掃描結果

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

npx @openai/codex-security scans list /path/to/repository

使用結果中的掃描 ID 來檢查其結果：

npx @openai/codex-security scans show SCAN_ID

每次完成的掃描都會將其報告、結果、覆蓋範圍和支援產物儲存在一起。有關完整佈局，請參閱掃描產物。

要檢查已儲存的掃描及其 worker 事件，請執行 scans logs SCAN_ID。這些日誌不會經過脫敏，可能包含源程式碼或憑據。

CLI 無法儲存掃描歷史記錄時怎麼辦

Codex Security 會把掃描歷史記錄儲存在工作臺資料庫中。如果預設狀態目錄不可寫，請選擇儲存庫之外的私有目錄：

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

掃描如何區分新發現和已知發現

列出某個儲存庫所有掃描中仍處於 open 狀態的發現：

npx @openai/codex-security findings list /path/to/repository

列表會標明最新掃描中已確認的發現，以及未在該次掃描中確認、但仍為 open 的較早發現。

比較兩次掃描中的發現：

npx @openai/codex-security scans compare PREVIOUS_SCAN_ID CURRENT_SCAN_ID

比較會按根本原因自動匹配發現項，複用已儲存的 匹配關係，並識別新增、持續存在、重新開啟、未觀測到、已解決和 未知的發現項。如果後續掃描在其掃描的程式碼中未找到先前的發現項， 該發現項的狀態就是未觀測到。只有將其 明確以已修復為由關閉後，才算已解決。被排除的路徑和不確定的匹配關係仍 歸為未知。

誤報回饋如何發揮作用

檢查已儲存的掃描，找到安全發現的 occurrence ID：

npx @openai/codex-security scans show SCAN_ID

記錄為什麼該發現不適用：

npx @openai/codex-security findings false-positive FINDING_OCCURRENCE_ID \
  --reason "The framework escapes this input before it reaches the query"

未來對同一儲存庫的掃描會將該解釋作為上下文。這些掃描仍會獨立檢查當前源程式碼、控制措施和可達性。將發現標記為誤報不會遮蔽規則、路徑或漏洞類別。

有關命令的詳細資訊，請參閱安全發現參考。

為什麼重複掃描會傳回不同的結果

即使掃描設定相同，AI 輔助掃描的結果也可能不同。首先重新執行基線掃描：

npx @openai/codex-security scans rerun BASELINE_SCAN_ID

重新執行時會保留原始掃描設定，並且要求使用相同的外掛 版本。如果已安裝的外掛發生變化，該命令將停止。

將基準掃描與新掃描進行比較：

npx @openai/codex-security scans compare BASELINE_SCAN_ID REPEAT_SCAN_ID

當缺少上下文可能導致變化時，提供共享架構和安全指導。匹配可以識別執行中相同的潛在發現，但它並不使掃描具有確定性。直接重新檢查任何消失的重要發現。

團隊如何確認修復是否有效

針對更改後的檢出目錄重新檢查原始發現項。在該檢出目錄中， 傳入原始發現項的報告以及要驗證的問題：

npx @openai/codex-security validate /path/to/original/findings.json \
  "Recheck the SQL injection in src/orders.ts:42 against the current code"

審查相關證據，確認漏洞路徑已被封堵，且正常行為 仍可正常執行。如果有原始重現程式或迴歸測試，請執行它們。 如果無法執行檢查，請在結果中註明仍存在的不確定性。

掃描比較 可以顯示發現項的變化，但僅憑某個發現項未再出現，無法驗證修復是否有效。

覆蓋不完全是什麼意思

檢視 coverage.json，瞭解被排除的路徑、推遲審查的範圍和待解答的問題。 新結果不包含覆蓋完整性欄位。檢視 scan-manifest.json 中的 scan.status，瞭解執行狀態。

覆蓋缺口不會改變已完成掃描的退出碼。退出碼為 0 並不意味著 每個檔案都經過了審查。如果後續掃描未覆蓋先前發現項的原始路徑， 就無法確定該發現項是否已不復存在。

自動化和成本

深度掃描的時間限制如何運作

啟動深度掃描時設定工作程序的截止時間：

npx @openai/codex-security scan . --mode deep --max-time-hours 1.5

預設值為 96 小時。可以使用不超過 96 的任意正數，包括 小數。到達截止時間時，Codex Security 會停止未完成的工作程序，保留 已完成的標準掃描結果，並將其彙總到最終報告中。 檢視報告，瞭解已審查的區域和推遲的工作。截止時間本身 不決定退出碼；退出碼由執行狀態和嚴重級別策略決定。

對於持久化設定或批次掃描活動，請在深度掃描 設定的 [deep_scan] 下設定 max_time_hours。

掃描成本限制如何運作

在開始掃描之前設定以美元為單位的估計成本限制：

npx @openai/codex-security scan . --max-cost 5

該限制是估算值，並非嚴格的支出上限。已經在 進行中的請求完成時，費用可能超出該限制。如果深度掃描在 Codex Security 彙總已完成的工作程序結果後達到限制，CLI 可以儲存一份已完成的 報告，並附帶預算警告。它會傳回 0；如果發現項達到 設定的嚴重級別閾值，則傳回 1。如果無法生成有效的已完成結果， 則傳回 2，並保留所有可用輸出。

對於 GitHub PR檢查和定時儲存庫掃描，請使用Codex Security GitHub Action。使用action-v0.3.0 時，掃描完成意味著所設定的分析生成了有效結果。排除的掃描範圍和推遲的調查不會繞過嚴重性策略。請檢視 coverage.json，以評估掃描的範圍和侷限性。如果還要拒絕空差異和試執行，請要求 Action 的scan-status 輸出為 completed；請參閱選擇嚴重性策略。

對於其他供應商，請參閱 CI/CD 概述。要在每次提交前執行檢查，請使用install-hook。