這篇帶你在自己電腦上跑完 Codex Security 第一次掃描，從安裝、空跑驗證到匯出 SARIF 報告接進 CI。附上五個會讓你燒錢的地雷。
（前情提要：OpenAI 推出 Daybreak 資安計畫：四大能力偵測高風險漏洞，正面挑戰 Claude Mythos）
（背景補充：Claude Security 資安審查怎麼用？安裝、掃描到修補檔完整解析）
這篇帶你在自己電腦上把 OpenAI 剛開源的 Codex Security 跑起來，從安裝、第一次掃描，一路到匯出報告接進 CI（Continuous Integration，持續整合）。順便講清楚一件很多人會誤會的事，下載原始碼不代表你就能用。
適合手上有 ChatGPT Pro、Business、Edu 或 Enterprise 帳號，想把 AI 資安掃描接進開發流程的工程師。沒有這些方案也可以先看第一節，弄清楚 OpenAI 這次開源了什麼，再決定要不要用。
本篇大綱
- 這次開源的是什麼，以及沒開源的是什麼
- 環境需求與安裝，三行指令跑完第一次掃描
- 五個會讓你燒錢或白做工的踩雷點
- 接進 CI 與每次 commit 前的自動檢查
- 掃描歷史追蹤、誤報標記與批次掃描
開源的是「外殼」
先說結論。上 GitHub 的 openai/codex-security 採 Apache-2.0 授權，內容是「跑掃描、管結果、接 CI」的那一層工具程式碼。真正讀你的程式碼、在隔離環境重現漏洞、生出修補檔的分析服務，仍然跑在 OpenAI 自己的伺服器上。
所以 clone 下來能改、能重新發布，掃描還是要登入 OpenAI 帳號，而且要有 Codex Security 的存取權限。README 開頭列的環境需求第三條就是 access to Codex Security，這條沒有繞道。目前它處於研究預覽階段，開放給 ChatGPT Pro、Business、Edu 與 Enterprise，企業帳號可能還要管理員先開權限。
版本節奏也值得看一眼，npm 上的 @openai/codex-security 首版 0.1.0 在 7 月 28 日世界標準時間 17:09 發布，0.1.1 在同一天 23:48 就跟上，中間隔 6 小時 39 分。SDK 說明文件自己標明，1.0.0 之前公開 API 可能在 minor 版本之間變動。要接進生產環境的話，版本鎖死比較安全。
它是開源，但不收外部 PR
翻 CONTRIBUTING.md 會看到一句話。這個 repo 是從 OpenAI 內部的 canonical repository 單向映象（one-way mirror）出來的，外部 pull request 沒辦法被匯入原始碼。
你能開 issue、能回報 bug、能提功能需求，維護者評估後自己把改動搬進內部倉庫，但你送的 PR 不會直接進去。授權條款確實給你修改跟散布的自由，協作模式則是另一回事，這兩件事不一樣。
流程：安裝、第一次掃描
環境需求三條：
- Node.js 22 以上，這個套件是 ESM-only，舊版跑不動
- Python 3.10 以上，掃描跟匯出都會用到
- Codex Security 存取權限
macOS、Linux 跟 Windows 都支援。裝起來就三行：
npm install @openai/codex-security
npx codex-security login
npx codex-security scan .登入那步如果你人在遠端主機或沒有瀏覽器的環境，改用裝置認證：
npx codex-security login --device-authCI 環境不用登入，設環境變數就好：
export OPENAI_API_KEY=<YOUR_KEY>想確認目前生效的是哪組憑證，跑 npx codex-security login status，它會告訴你來源，而且不會把金鑰印出來。
先空跑一次不花錢
直接下 scan . 之前，建議先空跑：
npx codex-security scan . --dry-run這個指令不會啟動 Codex、不碰網路、也不載入憑證，只驗證 repo、掃描目標、輸出位置跟模型設定，順便告訴你這次會用哪個模型、推理強度多少。零成本，跑之前先過一次很划算。
預設模型
掃描預設走 gpt-5.6-sol，推理強度是 extra-high。要換模型的話：
npx codex-security scan . --model gpt-5.6-terra其他 Codex 設定用 --codex KEY=VALUE 覆蓋，例如把推理強度降一級：
npx codex-security scan . --codex 'model_reasoning_effort="high"'推理強度直接影響 token 用量，也就是直接影響帳單。第一次試水溫沒必要開最高。
五個會讓你燒錢或白做工的地雷點
1. max-cost 不是硬性停止成本
--max-cost 看起來像保險，實際上有個邊界要先知道。官方說明寫得很清楚，累計成本超過上限時掃描會停，包含它派出去的 worker，但已經在進行中的 request 可以在超過上限之後完成。
意思是你設 5 美元，實際帳單可能落在 5 美元以上，部分結果會保留，錢也已經被花掉了…
如果你第一次跑建議挑小一點的 repo，或者用 --path 限制範圍：
npx codex-security scan . --path src --max-cost 5每次掃描回報的估算成本是用 OpenAI 標準 API token 價格算的，含快取輸入與快取寫入，但官方明講不含手續費與附加費，那個數字是「下限」。
2. 輸出目錄放錯位置會被擋下來
這一步最容易卡住，輸出目錄必須在被掃描的目錄外面，而且要在任何包住它的 Git worktree 外面，放在 repo 裡面會直接被拒絕。
原因不難理解，掃描結果裡面有原始碼片段、漏洞細節跟重現步驟，等於一份攻擊路線圖了。不小心 commit 上去就麻煩了。
macOS 跟 Linux 還有一條，如果輸出目錄已經存在，權限必須是 chmod 700，只有自己能讀寫，否則會被擋。
mkdir -p ~/security-scans/myrepo
chmod 700 ~/security-scans/myrepo
npx codex-security scan . --output-dir ~/security-scans/myrepo目錄裡已經有舊結果的話加 --archive-existing，CLI 會把舊的搬到 <output-dir>.previous-<timestamp>-<id>，然後在原路徑開一個乾淨目錄。搭 --dry-run 可以先看它打算搬去哪，不會真的動檔案。
3. 環境變數的金鑰會蓋掉你的 ChatGPT 登入
這個坑比較陰，預設規則是環境變數裡的 API 金鑰優先於已儲存的 ChatGPT 登入。互動式掃描會跳出來問你要用哪個憑證，但 JSON 輸出、空跑、CI 這些非互動情境不會問，直接沿用金鑰優先。
結果就是你以為在用 ChatGPT 方案額度，帳其實記在 API 那邊。要指定就加 --auth：
npx codex-security scan . --auth chatgpt
npx codex-security scan . --auth api-key--auth chatgpt 會完全忽略 OPENAI_API_KEY 跟 CODEX_API_KEY。想讓 ChatGPT 登入變成長期預設，把這兩個環境變數清掉：
unset OPENAI_API_KEY CODEX_API_KEY4. Python 3.10 要自己補裝 tomli
環境需求寫 Python 3.10 以上，但你如果剛好就是 3.10，要另外裝 tomli 套件。3.11 之後標準庫內建 tomllib，就沒這個問題。
想用其他直譯器，--python 引數、SDK 的 pythonPath 或 PYTHON 環境變數都能指定。
5. MCP 只給唯讀資訊，別想拿來跑掃描
CLI 可以用 npx codex-security mcp add 註冊成 MCP（Model Context Protocol，模型上下文協定）伺服器，但 MCP 那邊只暴露唯讀的 metadata 查詢。掃描、批次掃描、認證、匯出、驗證、修補全部只能走 CLI。
官方給的理由很實際，MCP 傳輸層沒辦法取消進行中的掃描。一個跑到一半、停不下來又在計費的掃描，比不能用還糟。
接進 CI 與每次 commit 前的自動檢查
先講 commit 前的部分：
npx codex-security install-hook裝完之後每次 commit 前會掃暫存跟未暫存的變更，它會尊重 core.hooksPath，也不會覆蓋你既有的 hook，預設擋 high 以上的發現，門檻用 --fail-on-severity 調。
CI 的標準寫法長這樣：
SCAN_ROOT="$(mktemp -d)"
npx codex-security scan . \
--diff origin/main \
--output-dir "$SCAN_ROOT/results" \
--json \
--fail-on-severity high > "$SCAN_ROOT/findings.json"--diff origin/main 只掃這次動到的部分，比整庫掃便宜很多。--working-tree 則是掃暫存加未暫存的變更。
Exit code 的設計值得看一下：
0，report-only 掃描完成，或政策透過1，掃描完成但違反政策2，輸入無效、覆蓋不完整，或 runtime 與匯出錯誤130，被中斷143，被終止
把「覆蓋不完整」歸到 2 而不是 0，是為了避免掃到一半失敗被誤判成透過。掃不完的時候，可用的結果照樣寫到 stdout，覆蓋率警告寫到 stderr，report-only 模式也一樣。進度訊息走 stderr、結構化結果走 stdout，所以 --json 導向檔案不會被進度條污染。
要把結果接進現有的資安平台就用 export：
npx codex-security export ~/security-scans/myrepo \
--export-format sarif \
--output ~/security-scans/results.sarif支援 SARIF、CSV、JSON 三種。SARIF 產出時會同時寫一份到 <scan-dir>/exports/results.sarif，加 --source-root 可以補上原始碼行的識別指紋。
export 有個好處，它不啟動 Codex 也不載入憑證，等於不花錢。掃完封存的結果要換格式，直接匯出就好，不用重掃。
掃描歷史、誤報標記與批次掃描
掃描紀錄存在本機 SQLite，路徑在 $CODEX_HOME/state/plugins/codex-security/workbench.sqlite3。那個位置不能寫的話，用 CODEX_SECURITY_STATE_DIR 指到別的地方。
npx codex-security scans list
npx codex-security scans show SCAN_ID
npx codex-security scans rerun SCAN_IDscan ID 不用打完整串，至少 8 個字元的字首就認得出來。
修完漏洞想確認有沒有真的修好，scans rerun 會用原本的設定對現在的 checkout 再跑一次。要比較兩次掃描：
npx codex-security scans match BEFORE_ID AFTER_ID
npx codex-security scans compare BEFORE_ID AFTER_IDmatch 把同一個根本原因的發現串起來，compare 讀這些配對，把結果分成新增、持續存在、重新出現、已解決、未知五類。這裡有個細節做得不錯，如果後一次掃描不完整、或沒有涵蓋到原本的範圍，消失的發現不會被算成已解決。這樣就不會出現「掃描範圍縮小導致漏洞看起來被修好」的假象。
誤報標記的機制也值得一提：
npx codex-security findings false-positive OCCURRENCE_ID --reason "The route already checks permissions"--reason 不是給你交差用的欄位。後續掃描只有在同一個理由仍然成立的時候才會忽略這個發現。程式碼改了、那條路由不再檢查權限，它會再冒出來。
一次掃很多 repo
先 gh auth login，然後：
npx codex-security bulk-scan它會撈出你 90 天內有推送的 GitHub repo，排除掉封存的跟 fork，讓你搜尋、勾選、確認之後才開掃。選好的清單會存成 <output-dir>/repositories.csv，之後可以重跑或續跑。
自己準備清單也行，CSV 必要欄位是 id、repository、revision，revision 要完整的 commit hash，選填的 scope 跟 mode 可以縮小個別掃描範圍。--workers 控制併發數，--max-attempts 設重試次數。
repo 裡附了 Dockerfile 跟 compose.yaml，容器設定該關的都關了，cap_drop: ALL、no-new-privileges、自訂 seccomp profile、非 root 用戶 10001。要在共用機器上跑批次掃描，直接拿這份來改會省事很多。
附錄：延伸工具與參考資源
- openai/codex-security：GitHub 原始碼與 README，Apache-2.0 授權
- Codex Security CLI 官方快速上手：完整指令與引數列表
- TypeScript SDK 官方指南：程式化整合的寫法
- npm 套件頁：版本紀錄與發布時間
- Incur：CLI 拿來做結構化輸出與代理探索的框架，
--llms、--schema這些引數來自它
想用程式呼叫而不是打指令，TypeScript SDK 的最小範例是這樣：
import { CodexSecurity } from "@openai/codex-security";
const security = new CodexSecurity();
try {
const result = await security.run("/path/to/repository", {
outputDir: "/path/outside/repository/results",
});
console.log(result.reportPath);
console.log(result.findings.findings.length);
} finally {
await security.close();
}SDK 支援整庫、指定路徑、已提交 diff 與工作樹四種目標，preflight() 對應 CLI 的空跑，onWorkerStatus 跟 onReconnect 可以觀察長時間掃描的進度，也能用 AbortSignal 取消。
常見問題
Q1. 沒有 ChatGPT Pro 或企業方案，下載原始碼能用嗎？
A：不行。開源的是跑掃描跟管結果的工具層，實際做分析的服務在 OpenAI 那邊，一定要登入帳號並取得 Codex Security 存取權。目前是研究預覽，開放 ChatGPT Pro、Business、Edu 與 Enterprise，企業帳號可能還要管理員先開權限。
Q2. 掃一次要多少錢？
A：沒有固定價目，每次掃描按實際 token 用量估算，用的是標準 API token 價格，含快取輸入與快取寫入，但不含手續費與附加費。--max-cost 設上限、--path 或 --diff 縮小範圍都能控成本。
Q3. 用 API 金鑰跟用 ChatGPT 登入有什麼差別？
A：計費來源不同，而且環境變數的金鑰預設會蓋過已儲存的 ChatGPT 登入。CI 這種非互動情境不會提示你選，要明確指定就加 --auth chatgpt 或 --auth api-key。
Q4. 為什麼輸出目錄不能放在 repo 裡面？
A：掃描結果包含原始碼片段、漏洞細節與重現步驟，等於一份攻擊路線圖，放在 repo 裡有機會被 commit 出去。CLI 直接擋掉這個情況，macOS 與 Linux 還會要求既有目錄是 chmod 700。
Q5. 我可以送 PR 改進這個工具嗎？
A：可以送，但不會被合併。CONTRIBUTING.md 寫明這個 repo 是從 OpenAI 內部倉庫單向映象出來的，外部 PR 無法匯入原始碼。回報 bug 或提功能需求走 GitHub issue，維護者評估後自己搬進去。
Q6. 掃描結果可以接進現有的資安平台嗎？
A：可以。export 支援 SARIF、CSV、JSON 三種格式，SARIF 是多數資安平台通用的標準。匯出不啟動 Codex 也不載入憑證，換格式重匯不用再付一次錢。
Q7. Windows 能跑嗎？
A：可以，macOS、Linux、Windows 都支援。Windows 在 PowerShell 設金鑰用 $env:OPENAI_API_KEY = "<your-api-key>"，然後 npx codex-security scan C:\code\repository。
本文參考 openai/codex-security 官方 README 與 CLI 文件，由 Mickey帽鼠（教學文作家）整理撰寫。
📍相關報導📍
Claude Security 資安審查怎麼用？安裝、掃描到修補檔完整解析
