Codex Security CLI 參考

使用本參考檢視 codex-security 支援的命令、flag、輸出格式和退出行為。要在引導下完成首次掃描，請從 CLI 快速入門開始。

在專案中安裝公開發布的軟體包：

npm install @openai/codex-security

使用 npx @openai/codex-security 呼叫已安裝的軟體包。當可執行檔案位於 PATH 中時，也可以直接使用 codex-security。

命令概述

usage: codex-security [--version] <command> [options]

CLI 提供以下命令：

命令	目的
`codex-security scan`	執行 Codex Security 掃描。
`codex-security install-hook`	安裝 Git 預提交安全掃描。
`codex-security bulk-scan`	發現儲存庫並執行可恢復批次掃描。
`codex-security scans`	列出、檢查、匹配、重新執行和比較已儲存的掃描。
`codex-security findings`	檢視並更新已儲存的安全發現。
`codex-security export`	將已完成的結果匯出為 CSV、JSON 或 SARIF。
`codex-security validate`	檢查一項或多項候選安全發現。
`codex-security patch`	修補一個或多個安全問題。
`codex-security login`	登入、儲存憑據或檢查登入狀態。
`codex-security logout`	刪除儲存的登入資訊。
`codex-security info`	顯示只讀 SDK 和捆綁外掛後設資料。

CLI 還提供以下整合命令：

命令	目的
`codex-security completions`	生成 shell 完成指令碼。
`codex-security mcp`	將 CLI 註冊為 MCP server。
`codex-security skills`	將 Codex Security 技能同步給智能體。

列出所有可用命令：

npx @openai/codex-security --help

將 --help 新增到命令中以檢查其參數和選項：

npx @openai/codex-security scan --help

codex-security --version 列印安裝的版本並退出。 codex-security info --json 報告 SDK 和捆綁外掛版本。這兩個命令都不需要 Python。

發現命令並連線智能體

列印智能體可讀的命令清單：

npx @openai/codex-security --llms

檢查掃描參數架構為 JSON：

npx @openai/codex-security scan --schema --format json

為 Bash 生成 shell 補全：

npx @openai/codex-security completions bash

對於這些 shell，將 bash 替換為 zsh 或 fish。

掃描結果支援 --format toon|json|yaml|jsonl 和 --full-output。框架級 --format 與 --export-format 相互獨立；後者用於選擇從已完成掃描匯出的產物格式。全域命令幫助中還列出了 md，但掃描結果不支援 Markdown 輸出。

將 CLI 註冊為 MCP server：

npx @openai/codex-security mcp add

將 Codex Security 技能同步給你的智能體：

npx @openai/codex-security skills add

MCP 僅公開只讀 info 後設資料命令。掃描、匯出、認證、驗證和修補仍然僅限 CLI。

`codex-security scan`

對儲存庫、選定的路徑、提交的更改或工作樹執行掃描。

usage: codex-security scan [-h] [--auth {auto,chatgpt,api-key}]
                           [--provider {openai,openrouter,fireworks,amazon-bedrock}]
                           [--path PATH | --diff BASE | --working-tree]
                           [--head HEAD] [--base BASE]
                           [--knowledge-base PATH]
                           [--mode {standard,deep}] [--model MODEL]
                           [--effort {minimal,low,medium,high,xhigh}]
                           [--output-dir DIR]
                           [--archive-existing]
                           [--plugin-path PATH] [--python PATH]
                           [--codex KEY=VALUE] [--fail-on-severity LEVEL]
                           [--max-cost USD] [--dry-run] [--verbose]
                           [--json] [--format {toon,json,yaml,jsonl}]
                           [--full-output] [repository]

repository 預設為當前目錄。

選擇掃描認證方式

使用預設值 --auth auto 可自動選擇憑據。當 ChatGPT 登入和 OPENAI_API_KEY 或 CODEX_API_KEY 同時可用時，使用文本輸出的互動式掃描會詢問要使用哪種憑據。CI、JSON 和 JSONL 掃描，以及其它沒有互動式終端的掃描，使用環境變數中的 API key。試執行不會提示選擇，也不會載入憑據。

如需使用已儲存的憑據，請傳入 --auth chatgpt：

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

如需使用環境變數中的 API key，請傳入 --auth api-key：

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

如需讓已儲存的憑據成為自動選擇的預設值，請執行 unset OPENAI_API_KEY CODEX_API_KEY。

使用 Amazon Bedrock

使用 --provider amazon-bedrock 選擇 Amazon Bedrock，並通過 --model 指定明確的 Bedrock 模型：

npx @openai/codex-security scan . \
  --provider amazon-bedrock \
  --model openai.gpt-5.6-sol

設定 AWS_REGION，並使用 AWS_BEARER_TOKEN_BEDROCK、標準 AWS access key、AWS profile、web identity、容器憑據或預設 AWS 憑據鏈進行認證。Bedrock 掃描使用 AWS 憑據，而不是 --auth、ChatGPT 登入或 OpenAI API key。scan 和 bulk-scan 都支援 --provider。

選擇掃描目標

為每次掃描選擇一種目標類型。

參數	說明
`--path PATH`	掃描儲存庫內的相對路徑。重複該 flag 可新增更多路徑。
`--diff BASE`	掃描從 `BASE` 到 `--head` 的已提交變更。head revision 預設為 `HEAD`。
`--head HEAD`	設定 `--diff` 的 head revision。
`--working-tree`	針對 `--base` 掃描已暫存和未暫存的變更。base revision 預設為 `HEAD`。
`--base BASE`	設定 `--working-tree` 的 base revision。
`--mode {standard,deep}`	選擇掃描模式。預設為 `standard`。

--path、--diff 和 --working-tree 是互斥的。 --head 需要 --diff，--base 需要 --working-tree。深度模式支援儲存庫和路徑目標。

差異和工作樹掃描要求儲存庫參數指向 Git 工作樹根目錄。所選 revision 必須存在於當前檢出內容中。

掃描整個儲存庫：

npx @openai/codex-security scan .

掃描選定的路徑：

npx @openai/codex-security scan . --path src --path tests

掃描提交的更改：

npx @openai/codex-security scan . --diff origin/main --head HEAD

掃描暫存和未暫存的更改：

npx @openai/codex-security scan . --working-tree --base HEAD

對儲存庫進行更深入的審查：

npx @openai/codex-security scan . --mode deep

新增安全上下文

使用 --knowledge-base PATH 提供架構文件、威脅模型或安全策略。要新增更多檔案或目錄，請重複該選項：

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

支援的文件包括 .md、.markdown、.txt、.pdf 和 .docx 檔案。CLI 遞迴搜尋目錄，拒絕連結的輸入路徑，跳過連結的目錄條目，並將提取的文件內容保留在儲存的掃描結果之外。

設定輸出和策略選項

使用這些選項可以保留產物、保留早期結果或建立機器可讀的結果。

參數	說明
`--output-dir DIR`	將掃描產物寫入外層 Git 工作樹之外的私有目錄。預設為持久化的 Codex Security 狀態目錄。
`--archive-existing`	將現有結果移至 `DIR.previous-<timestamp>-<id>` 並從空輸出目錄開始。需要 `--output-dir`。
`--fail-on-severity LEVEL`	當完成的掃描報告結果等於或高於 `critical`、`high`、`medium` 或 `low` 時，返回退出 `1`。
`--max-cost USD`	當估計模型成本超過指定的美元金額時停止掃描。
`--dry-run`	檢查儲存庫、目標、輸出目錄和 Codex 設定，而無需啟動掃描。
`--verbose`	將經過脫敏的生命週期、認證、進度和成本診斷輸出到 stderr。
`--json`	將 manifest、安全發現、覆蓋範圍、路徑和 `turn` 後設資料輸出為一份 JSON 文件。
`--format FORMAT`	把完整掃描結果輸出為 `toon`、`json`、`yaml` 或 `jsonl`。
`--full-output`	使用預設結構化輸出格式列印完整結果。

成本限制是一個估計值，而不是硬性支出上限。已在進行中的請求可能會超出限制，並且部分掃描結果仍然可用。

當你省略 --output-dir 時，結果將保留在 $CODEX_HOME/state/plugins/codex-security/scans/<repository> 下。 CODEX_HOME 預設為 ~/.codex。設定 CODEX_SECURITY_STATE_DIR 以將結果保留在 $CODEX_SECURITY_STATE_DIR/scans/<repository> 下。這些目錄可以包含源程式碼摘錄和漏洞詳細資訊，因此請相應地管理其權限和保留。

工作臺把掃描歷史記錄儲存在 $CODEX_HOME/state/plugins/codex-security/workbench.sqlite3。設定 CODEX_SECURITY_STATE_DIR 也會移動工作臺資料庫。

輸出目錄必須位於被掃描目錄和任何外層 Git 工作樹之外。掃描可以用 --archive-existing 替換現有結果目錄。

要在複用輸出目錄前保留早期結果：

npx @openai/codex-security scan . \
  --output-dir /path/outside/repository/results \
  --archive-existing

預設情況下，掃描僅報告。新增 --fail-on-severity 以評估 CI 中的嚴重性策略：

npx @openai/codex-security scan . \
  --diff origin/main \
  --output-dir /path/outside/repository/results \
  --json \
  --fail-on-severity high \
  > /path/outside/repository/codex-security.json

空執行檢查本機輸入，無需載入憑據、啟動 Codex 或探測外掛的 Python 直譯器：

npx @openai/codex-security scan . --output-dir /path/outside/repository/results --dry-run

設定執行時

當你需要顯式模型、直譯器、外掛或 Codex 設定值時，請使用執行時選項。

參數	說明
`--auth {auto,chatgpt,api-key}`	選擇掃描憑據。預設為 `auto`。
`--provider {openai,openrouter,fireworks,amazon-bedrock}`	選擇推理提供商。預設為 `openai`。
`--model MODEL`	選擇模型。預設為 `gpt-5.6-sol`；使用 `--provider amazon-bedrock` 時必須指定。
`--effort {minimal,low,medium,high,xhigh}`	選擇模型的推理強度。預設為 `xhigh`。
`--plugin-path PATH`	使用 Codex Security 外掛目錄或 ZIP 覆蓋捆綁的外掛。
`--python PATH`	為外掛執行時選擇 Python 直譯器。
`--codex KEY=VALUE`	覆蓋隔離的 Codex 設定值。值使用 TOML 語法。重複該 flag 可新增更多值。

要在不寫 TOML 的情況下選擇其它模型和推理強度：

npx @openai/codex-security scan . --model gpt-5.6-terra --effort high

引用通過 --codex 傳遞的字串值，以便 TOML 解析器接收一個字串：

npx @openai/codex-security scan . --codex 'model="gpt-5.6-terra"'

`codex-security install-hook`

為當前儲存庫安裝 Git 預提交安全檢查：

npx @openai/codex-security install-hook

檢查會在每次提交之前掃描暫存和未暫存的更改，並阻止高嚴重性發現或掃描錯誤。它尊重 core.hooksPath 並且不會替換現有的預提交指令碼。需要時設定不同的嚴重性閾值：

npx @openai/codex-security install-hook . --fail-on-severity medium

`codex-security bulk-scan`

發現並掃描 GitHub 儲存庫，或從儲存庫 CSV 執行可恢復掃描：

有關 GitHub 發現、CSV 清單、批次掃描結果和容器化掃描的完整指南，請參閱執行批次安全掃描。

usage: codex-security bulk-scan [input] [--output-dir DIR]
                                [--workers N] [--mode {standard,deep}]
                                [--provider {openai,openrouter,fireworks,amazon-bedrock}]
                                [--model MODEL]
                                [--effort {minimal,low,medium,high,xhigh}]
                                [--max-attempts N] [--plugin-path PATH]
                                [--python PATH] [--codex KEY=VALUE]

執行不帶參數的 npx @openai/codex-security bulk-scan，以互動方式選擇儲存庫。此流程需要 GitHub CLI 登入。

要在互動式發現期間選擇模型和推理強度：

npx @openai/codex-security bulk-scan --model gpt-5.6-terra --effort high

對於準備好的儲存庫列表，請提供 CSV 和 --output-dir：

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

CSV 需要 id、repository 和 revision 列。修訂必須是完整的提交雜湊。可選的 scope 和 mode 列設定單獨的儲存庫：

id,repository,revision,scope,mode
service,https://github.com/example/service.git,0123456789abcdef0123456789abcdef01234567,src,standard

--workers 限制併發掃描數，預設為 4。--mode 預設為 standard，--max-attempts 預設為 1。需要在錯誤後重試儲存庫時，請設定 --max-attempts。再次運行同一命令即可從現有輸出目錄恢復批次掃描。只有記錄的結果產物仍然存在時，CLI 才會跳過已完成掃描的儲存庫。

對於容器化批次掃描，請參閱在 Docker 中執行批次掃描。

`codex-security scans`

查詢儲存的掃描

列出當前目錄的已儲存掃描：

npx @openai/codex-security scans

列出不同儲存庫的掃描：

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

查詢儲存在特定輸出目錄下的掃描：

npx @openai/codex-security scans list --scan-root /path/outside/repository/results

檢查或重複掃描

顯示儲存的掃描結果和設定：

npx @openai/codex-security scans show SCAN_ID

使用其原始設定針對當前檢出內容重新執行掃描：

npx @openai/codex-security scans rerun SCAN_ID

匹配和比較結果

匹配兩次掃描中具有相同根本原因的結果：

npx @openai/codex-security scans match PREVIOUS_SCAN_ID CURRENT_SCAN_ID

比較匹配的掃描以查詢新的、持續存在的、重新開啟的、已解決的和未知的發現：

npx @openai/codex-security scans compare PREVIOUS_SCAN_ID CURRENT_SCAN_ID

當後續掃描覆蓋不完整，或沒有覆蓋某項安全發現的原始位置時，該發現的狀態為未知。需要重新計算現有匹配時，請為 match 新增 --force。

要匹配當前儲存庫的所有已完成掃描，包括來自其他簽出的掃描：

npx @openai/codex-security scans match --all

即使重新執行相同的設定，掃描結果也可能會有所不同。匹配和比較追蹤變化；它們不會使結果具有確定性或證明漏洞不再存在。使用 validate 根據當前程式碼重新檢查安全關鍵發現。

`codex-security findings`

將安全發現標記為誤報：

usage: codex-security findings false-positive OCCURRENCE_ID
                       --reason REASON

檢查已儲存的掃描，找到安全發現的 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"

原因不能為空。Codex Security 保存儲存庫的決策並將其作為未來掃描的上下文。每次掃描都會獨立地重新檢查當前源、控制項和可達性。先前的決定不會抑制規則、路徑或漏洞類別。

`codex-security export`

從已完成並封存的掃描中匯出 CSV、JSON 或 SARIF。匯出會在寫入輸出前驗證掃描產物，且不會改動 Codex 執行時和憑據。

usage: codex-security export [--export-format {csv,json,sarif}]
                             [--output FILE|-] [--source-root PATH]
                             [--python PATH] scan_dir

scan_dir 是完成的掃描目錄。

參數	說明
`--export-format {csv,json,sarif}`	選擇匯出格式。預設為 `sarif`。
`--output FILE\|-`	將選定的格式寫入檔案或標準輸出。預設為當前目錄中的檔案。
`--source-root PATH`	使用儲存庫簽出將源行指紋新增到 SARIF。
`--python PATH`	為捆綁匯出器選擇 Python 直譯器。

--source-root 僅適用於 --export-format sarif。JSON 會儲存已封存的安全發現檔案。CSV 包含可移植的安全發現欄位，不包括本機工作臺的分類狀態。

如果省略 --output，CLI 會在當前工作目錄中把 SARIF 寫入 results.sarif、JSON 寫入 findings.json、CSV 寫入 findings.csv。匯出結果可能包含源程式碼摘錄和漏洞詳情。請在儲存庫外執行該命令，或通過 --output 指定掃描檢出目錄之外的私有路徑。

將 SARIF 寫入檔案：

npx @openai/codex-security export /path/to/scan \
  --export-format sarif \
  --source-root /path/to/repository \
  --output /path/outside/repository/exports/results.sarif

將 SARIF 寫入標準輸出：

npx @openai/codex-security export /path/to/scan --export-format sarif --source-root . --output -

將結果匯出為 JSON：

npx @openai/codex-security export /path/to/scan \
  --export-format json \
  --output /path/outside/repository/exports/findings.json

將結果匯出為 CSV：

npx @openai/codex-security export /path/to/scan \
  --export-format csv \
  --output /path/outside/repository/exports/findings.csv

`codex-security validate` 和 `codex-security patch`

檢查候選結果是否有效：

npx @openai/codex-security validate findings.json "Possible SQL injection in src/query.ts:42"

使用捆綁的修復技能生成補丁：

npx @openai/codex-security patch findings.json "Missing authorization check in src/routes.ts:18"

每個參數都可以是字面文本或檔案路徑。這兩個命令都針對當前目錄執行。修復完成後，或後續掃描不再報告原始發現時，可以使用 validate 直接重新檢查原始發現。只比較掃描結果並不能證明修復有效。外部工具也可以使用這些命令，無需重新建置掃描環境。

使用 --effort 為任一命令選擇推理強度：

npx @openai/codex-security validate "Possible SQL injection" --effort high

`codex-security login`、`logout` 和 `info`

互動式登入：

npx @openai/codex-security login

在遠端或無頭計算機上使用裝置認證：

npx @openai/codex-security login --device-auth

檢查當前登入情況：

npx @openai/codex-security login status

刪除儲存的登入資訊：

npx @openai/codex-security logout

通過將 API key 傳遞到 stdin 來儲存它：

printenv OPENAI_API_KEY | npx @openai/codex-security login --with-api-key

儲存企業存取令牌：

printenv CODEX_ACCESS_TOKEN | npx @openai/codex-security login --with-access-token

檢查只讀 SDK 和捆綁外掛後設資料：

npx @openai/codex-security info --json

當你將 CLI 公開為 MCP server 時，info 是唯一可用的命令。掃描、匯出、登入、驗證和修補仍然僅限 CLI。

讀取掃描輸出

預設情況下，掃描會把進度、完成摘要和錯誤傳送到 stderr，而不會把完整掃描結果寫入 stdout。使用 --json、--format 或 --full-output 才會把結構化掃描結果傳送到 stdout。

詳細診斷

新增 --verbose 可將經過脫敏的生命週期、認證、進度和成本診斷輸出到 stderr：

npx @openai/codex-security scan . --verbose

設定 CODEX_SECURITY_LOG_LEVEL=debug 可以在不使用該 flag 時啟用相同診斷。當 CODEX_SECURITY_LOG_LEVEL 未設定時，LOG_LEVEL=debug 也會啟用診斷。

這些日誌控制只適用於 CLI。憑據和提供商識別符號仍會被脫敏，結構化掃描結果仍保留在 stdout。

完成總結

完成的掃描會把安全發現數量、嚴重性細分、覆蓋範圍、耗時、報告路徑和結果目錄寫入 stderr；如果可用，還會包含 token 用量和估算成本：

codex-security: Findings: 4 (1 critical, 2 high, 1 informational). Coverage: complete.
codex-security: Elapsed: 1s.
codex-security: Tokens: 1,250 input, 200 cached, 30 output.
codex-security: Report: /path/to/scan/report.md
codex-security: Results: /path/to/scan

informational 安全發現會計入彙總總數。嚴重性策略只評估 critical、high、medium 和 low 級別的結果。

JSON 輸出

scan --json 將一份完整的 JSON 文件寫入標準輸出。它的頂層形狀是：

manifest
findings
coverage
scanDir
threadId
reportPath
artifactsDir
sarifPath
turn
  id
  status
  durationMs
  finalResponse
  usage

進度、完成摘要、存檔通知和錯誤保留在 stderr 上。當嚴重性策略返回退出 1 或不完整覆蓋返回退出 2 時，已完成的掃描仍會列印完整的 JSON 結果。

掃描產物

完整的掃描將可讀的報告和結構化產物放在一起：

<scan-directory>/
├── scan-manifest.json
├── findings.json
├── coverage.json
├── report.md
├── artifacts/
└── exports/
    └── results.sarif       # when produced

結構化檔案服務於不同的工作：

檔案	內容
`scan-manifest.json`	掃描標識、狀態、目標、範圍、生產者和已封存的產物記錄。
`findings.json`	安全發現的識別符號、嚴重性、置信度、分類、位置、證據、驗證、資料流、可達性和補救措施。
`coverage.json`	已審查範圍、排除、延後處理的工作、懸而未決的問題和覆蓋範圍的完整性。
`report.md`	可讀的掃描報告。
`artifacts/`	支援掃描產物。
`exports/results.sarif`	SARIF 在掃描期間生成（如果存在）。

覆蓋完整性具有三個值：

complete：掃描記錄其選定範圍的完整覆蓋範圍。
partial：掃描記錄延後處理的工作或其他覆蓋範圍限制。
unknown：掃描報告覆蓋完整性未知。

在使用覆蓋範圍作為安全決策的證據之前，請檢查延遲的表面、明確的排除和懸而未決的問題。

退出碼和訊號

CLI 使用以下退出碼：

退出碼	條件
`0`	掃描完成並完全覆蓋並通過了其嚴重性策略，批次掃描完成且沒有失敗，或者另一個命令成功。
`1`	完成的掃描會報告等於或高於設定的嚴重性的安全發現。
`2`	CLI 發現輸入、執行時或匯出錯誤，掃描覆蓋不完整，或者批次掃描儲存庫有錯誤。
`130`	Ctrl-C 中斷掃描。
`143`	SIGTERM 終止掃描。

即使沒有嚴重性策略，任何具有 partial 或 unknown 覆蓋範圍的掃描都會返回 2。當你請求結構化輸出時，完成的掃描仍會把可用結果寫入 stdout。CLI 會在中斷或執行時錯誤後列印任何部分輸出的位置。

認證和先決條件

設定 OPENAI_API_KEY 或 CODEX_API_KEY，使用 npx @openai/codex-security login 登入，或複用現有的檔案式 Codex 登入。對於 Amazon Bedrock，請改用 Bedrock API key 或標準 AWS 憑據鏈。

憑據選擇規則請參閱選擇掃描認證方式。

對於 CI，請把 API key 的作用域限制在掃描步驟，並使用可信工作流程。

CLI 需要 Node.js 22 或更高版本。執行掃描或匯出結果還需要 Python 3.10 或更高版本。 Python 3.10 還需要 tomli。當自動發現不適合時，使用 --python 或 PYTHON 選擇直譯器。

繼續閱讀 CLI 快速入門、批次掃描指南、CLI 常見問題解答、CI 指南或 TypeScript SDK指南。

純文本別名

--output FILE|-

最近搜尋

建議搜尋

文件導覽

命令概述

發現命令並連線智能體

`codex-security scan`

選擇掃描認證方式

使用 Amazon Bedrock

選擇掃描目標

新增安全上下文

設定輸出和策略選項

設定執行時

`codex-security install-hook`

`codex-security bulk-scan`

`codex-security scans`

查詢儲存的掃描

檢查或重複掃描

匹配和比較結果

`codex-security findings`

`codex-security export`

`codex-security validate` 和 `codex-security patch`

`codex-security login`、`logout` 和 `info`

讀取掃描輸出

詳細診斷

完成總結

JSON 輸出

掃描產物

退出碼和訊號

認證和先決條件

純文本別名

命令概述

發現命令並連線智能體

codex-security scan

選擇掃描認證方式

使用 Amazon Bedrock

選擇掃描目標

新增安全上下文

設定輸出和策略選項

設定執行時

codex-security install-hook

codex-security bulk-scan

codex-security scans

查詢儲存的掃描

檢查或重複掃描

匹配和比較結果

codex-security findings

codex-security export

codex-security validate 和 codex-security patch

codex-security login、logout 和 info

讀取掃描輸出

詳細診斷

完成總結

JSON 輸出

掃描產物

退出碼和訊號

認證和先決條件

純文本別名

`codex-security scan`

`codex-security install-hook`

`codex-security bulk-scan`

`codex-security scans`

`codex-security findings`

`codex-security export`

`codex-security validate` 和 `codex-security patch`

`codex-security login`、`logout` 和 `info`