Codex Security CLI 常見問題
解答有關 Codex Security 掃描、安全發現、誤報、覆蓋範圍、成本和 CI 的常見問題。
查詢有關從終端掃描儲存庫和管理安全結果的常見問題的答案。對於安裝和首次掃描，請從 CLI 快速入門 開始。
儲存庫掃描
誰可以使用 CLI
@openai/codex-security 軟體包已公開發布。安裝 CLI 和 SDK：
npm install @openai/codex-security執行掃描仍需獲得 Codex Security 存取權限。為取得最佳效果，請使用已通過 Trusted Access for Cyber 驗證的賬號。
為什麼登入後掃描仍使用 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 參考。
批次儲存庫掃描如何工作
使用 GitHub CLI 登入：
gh auth login從 GitHub 賬號或組織中發現並選擇儲存庫：
npx @openai/codex-security bulk-scan對於準備好的列表，請提供儲存庫 CSV 和輸出目錄：
npx @openai/codex-security bulk-scan repositories.csv \
--output-dir /path/outside/repositories/security-scans \
--workers 4請參閱執行批次安全掃描，瞭解 GitHub 發現、CSV 格式、批次掃描結果和可用選項。
中斷的批次掃描可以恢復嗎
是的。對原始 CSV 和輸出目錄執行相同的批次掃描命令。當記錄的掃描產物保持完整時，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掃描如何使用架構和安全策略
使用 --knowledge-base 傳遞架構文件、威脅模型或安全策略：
npx @openai/codex-security scan . \
--knowledge-base /path/to/architecture.md \
--knowledge-base /path/to/security-policiesCodex Security 使用這些文件作為當前掃描的上下文。有關支援的檔案類型和目錄行為，請參閱新增安全上下文。
安全發現與覆蓋範圍
團隊在哪裡可以找到早期的掃描結果
列出儲存庫的已儲存掃描：
npx @openai/codex-security scans list /path/to/repository使用結果中的掃描 ID 來檢查其結果：
npx @openai/codex-security scans show SCAN_ID每次完成的掃描都會將其報告、結果、覆蓋範圍和支援產物儲存在一起。有關完整佈局，請參閱掃描產物。
CLI 無法儲存掃描歷史記錄時怎麼辦
Codex Security 會把掃描歷史記錄儲存在工作臺資料庫中。如果預設狀態目錄不可寫，請選擇儲存庫之外的私有目錄：
export CODEX_SECURITY_STATE_DIR=/path/outside/repository/codex-security-state掃描如何區分新發現和已知發現
匹配兩次掃描中共享根本原因的結果：
npx @openai/codex-security scans match PREVIOUS_SCAN_ID CURRENT_SCAN_ID比較匹配的結果：
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 match BASELINE_SCAN_ID REPEAT_SCAN_ID比較匹配結果：
npx @openai/codex-security scans compare BASELINE_SCAN_ID REPEAT_SCAN_ID當缺少上下文可能導致變化時，提供共享架構和安全指導。匹配可以識別執行中相同的潛在發現，但它並不使掃描具有確定性。直接重新檢查任何消失的重要發現。
團隊如何確認修復是否有效
應用修復後，重新執行原始掃描：
npx @openai/codex-security scans rerun BEFORE_SCAN_ID將原始結果與新掃描進行匹配：
npx @openai/codex-security scans match BEFORE_SCAN_ID AFTER_SCAN_ID比較匹配的結果：
npx @openai/codex-security scans compare BEFORE_SCAN_ID AFTER_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"僅缺少發現或掃描比較並不能證明修復有效。
覆蓋不完全是什麼意思
覆蓋範圍可以是 complete、partial 或 unknown。在將掃描視為審查證據前，請審查 coverage.json 中排除的路徑、延後處理的範圍和未解決的問題。
即使沒有嚴重性策略，部分或未知覆蓋範圍的掃描也會返回退出碼 2。這些掃描仍然保留任何可用的安全發現和報告。當稍後的掃描未覆蓋該結果的原始路徑時，無法確定較早的結果不再存在。
自動化和成本
掃描成本限制如何運作
在開始掃描之前設定以美元為單位的估計成本限制：
npx @openai/codex-security scan . --max-cost 5該限制是一個估計，而不是硬性支出上限。已在處理的請求可能會超出限制。Codex Security 在掃描停止時保留可用結果。
能否掃描 commit 和 pull request
為暫存和未暫存的更改安裝預提交安全檢查：
npx @openai/codex-security install-hook對於 pull request 檢查，請掃描已提交的更改並設定嚴重性閾值：
npx @openai/codex-security scan . \
--diff origin/main \
--fail-on-severity high當完整掃描發現安全問題達到或超過所選嚴重性時，會返回退出碼 1。有關完整的 GitHub Actions 工作流程、產物處理和 SARIF 匯出，請參閱在 CI 中執行掃描。
其他應用可以直接執行掃描嗎
是的。使用 TypeScript SDK 啟動掃描、選擇目標、檢查結果和覆蓋範圍、跟蹤進度以及從應用或開發工具應用成本控制。