OpenAI 在 2026 年 7 月中把 codex-security 開源了。它不是一個 GitHub Action，也不是一個網頁服務，而是一支裝在你自己機器上的 CLI 加一套 TypeScript SDK：npx @openai/codex-security scan . 就會派一群 AI agent 去翻你的程式碼，找出可能被利用的漏洞，然後產出一份可以進 CI 的結構化報告。
這篇文章不推銷也不唱衰，只做一件事：把 repo clone 下來、把原始碼和設定讀完，告訴你它到底是什麼、設計上做了哪些取捨、以及什麼情況下你不該用它。
本文所有數字與行為描述都來自 2026 年 8 月 3 日當天的 openai/codex-security 主分支與 npm 上的 0.1.5 版。
codex-security 是什麼
一句話：一支跑在本機、用 Codex agent 做語意層漏洞掃描的命令列工具，掃完可以驗證、可以直接叫它產修補、可以輸出 SARIF 進 CI。
先看官方 repo 的基本資料，這些決定了它的定位：
| 項目 | 內容 |
|---|---|
| Repo | openai/codex-security |
| 授權 | Apache-2.0 |
| 主要語言 | TypeScript |
| npm 套件 | @openai/codex-security，最新版 0.1.5 |
| 首次公開 | 2026-07-13 |
| Star 數 | 約 8,200 |
| 文件 | developers.openai.com/codex/security |
0.1.x，套件 README 自己標明了語意化版號的警告：1.0.0 之前，公開 API 在 minor 版本之間就可能變動。這不是穩定期產品，是早期釋出。
它跟一般 SAST 差在哪
傳統靜態掃描工具（Semgrep、CodeQL 那一類）靠的是規則和資料流分析：先寫好 pattern，再去比對。好處是快、可重現、零成本重跑；壞處是它不理解你的業務意圖，看不出「這個 endpoint 少了一層授權」這種需要讀懂上下文才成立的問題。
codex-security 走的是另一條路：讓語言模型實際讀你的程式碼，理解這段程式在幹嘛，再判斷它有沒有可被利用的破口。代價很直接——它要花錢、每次跑結果不完全一樣、而且需要網路和 OpenAI 帳號。
安裝與最小可用流程
前置條件在 README 裡寫得很死，照抄如下：
- Node.js 22.13.0 以上的 22.x、或 24.x、或 26.x
- Python 3.10 以上（掃描與匯出findings 需要；用 3.10 的話要另裝
tomli） - 一個能存取 Codex Security 的 OpenAI 帳號
npm install @openai/codex-security
npx @openai/codex-security login
npx @openai/codex-security scan .CI 環境不要用互動登入，改設環境變數。README 特別註明環境變數裡的 API key 只會傳給當次掃描，不會被寫進 Codex 的憑證目錄或系統 keyring：
export OPENAI_API_KEY="..." # 或 CODEX_API_KEY
npx @openai/codex-security scan . --json --fail-on-severity high遠端或無頭機器登入走裝置授權：
npx @openai/codex-security login --device-auth一個容易踩的預設值：它預設不會擋你的 CI
掃描預設是 report-only，也就是說有漏洞它也回 exit code 0。要讓它真的擋門，得自己加 --fail-on-severity：
npx @openai/codex-security scan . --diff origin/main --fail-on-severity highexit code 的設計是我覺得這個工具做得比較細的地方，值得整理出來：
| Exit code | 意義 |
|---|---|
| 0 | 掃描完成且符合政策（或 report-only） |
| 1 | 掃描完成，但有 finding 觸犯了 severity 政策 |
| 2 | 輸入無效、覆蓋範圍不完整、或執行期/匯出錯誤 |
| 130 | 被中斷（SIGINT） |
| 143 | 被終止（SIGTERM） |
掃描模式與可調的旋鈕
standard 與 deep
--mode 有 standard 和 deep 兩種。deep 模式跑的是「重複發掘」引擎：派多個 discovery worker 反覆掃，直到連續幾輪都找不到新東西為止。
npx @openai/codex-security scan . \
--mode deep --workers 2 --subagents 0 \
--stop-after-no-new 3 --max-discovery-runs 10四個旋鈕的意思：
--workers：同時跑幾個發掘 worker--subagents：每個 worker 底下再開幾個子 agent--stop-after-no-new：連續幾輪沒有新發現就收工--max-discovery-runs：總共最多跑幾輪
CODEX_HOME，不會讀取環境裡的 deep scan 設定檔。結果是 scan --mode deep 目前只能吃引擎的預設值，而且這四個設定沒有對應的獨立 CLI flag。--codex 只能調 Codex 的 session 執行緒上限，調不到 [deep_scan]。
換句話說，上面那個 --workers 2 這類參數是 scan 子命令自己的介面，而 plugin 內部那層 [deep_scan] 引擎設定在獨立 CLI 情境下你動不到。這是目前版本的實際限制，不是我猜的。
掃描範圍
四種 target，對應四種常見場境：
# 整個 repo
npx @openai/codex-security scan /path/to/repo
# 限定路徑
npx @openai/codex-security scan . --path src --path tests
# 只掃 commit 過的差異（CI 最常用）
npx @openai/codex-security scan . --diff origin/main
# 掃工作區（staged + unstaged）
npx @openai/codex-security scan . --working-tree
--diff 這個在 CI 裡特別有意義：只掃這次 PR 動到的東西，成本和時間都壓得下來。
餵它背景知識
這個功能一般 SAST 給不了。你可以把架構文件、威脅模型、資安政策丟進去當背景：
npx @openai/codex-security scan . \
--knowledge-base /path/to/threat-models \
--knowledge-base /path/to/architecture.pdf目錄會被遞迴搜尋，吃 Markdown、純文字、PDF、Word（.docx）。這是語意掃描才做得到的事——你可以告訴它「我們的信任邊界長這樣」，它據此判斷什麼算越界。
成本控制：這是它跟免費 SAST 最大的分野
每次掃描都會把模型、token 數、估算成本記進 JSON 結果、掃描歷史和 bulk-scan 收據裡。預設模型是 gpt-5.6-sol、推理強度 xhigh——這是相當貴的組合。
可以設上限：
npx @openai/codex-security scan . --max-cost 5超過 5 美元就停，含它派出去的 worker。部分結果會保留，但已經發出去的請求可能跑完後略微超標。README 也註明成本是用標準 API token 價格估的，不含額外費用與附加費——所以那個數字是估算，不是帳單。
另外有個細節值得知道：成本追蹤接受的 Codex session event 上限是 1 MiB，超過就中止掃描，理由是超大事件會讓執行中成本無法被安全驗證。寧可停也不要在成本失控的情況下繼續跑，這個取捨我認同。
想省錢就換模型和推理強度：
npx @openai/codex-security scan . --model gpt-5.6-terra --effort high--effort 可選 minimal|low|medium|high|xhigh。
掃完之後：驗證、比對、修補
這是我認為 codex-security 設計上最有價值的一段，也是它跟「掃一掃給你一份清單就結束」的工具真正拉開差距的地方。
掃描歷史與比對
掃描結果存在 workbench 的 SQLite 資料庫，可以列、可以看、可以重跑：
npx @openai/codex-security scans list
npx @openai/codex-security scans show SCAN_ID
npx @openai/codex-security scans rerun SCAN_ID
npx @openai/codex-security scans compare BEFORE_ID AFTER_IDcompare 會依「根本原因」把兩次掃描的 finding 配對，然後標成 new / persisting / reopened / resolved / unknown 五種狀態。這裡有一個很誠實的設計：當後一次掃描不完整、或沒覆蓋到原本的位置時，消失的 finding 會被標成 unknown，不會被當成 resolved。
這個細節很重要。很多工具會把「這次沒掃到」等同於「修好了」，於是漏洞就從報告裡人間蒸發。codex-security 選擇區分「確認修好」和「這次沒看到」，這是對的。
標記假陽性
npx @openai/codex-security findings false-positive OCCURRENCE_ID \
--reason "The route already checks permissions"而且是有條件的忽略——README 寫明後續掃描只有在「同一個理由仍然成立」時才會沿用這個 dismiss。理由失效了它會重新報。
叫它產修補
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 跑內建的驗證 skill 去確認這個 finding 是不是真的，patch 跑修補 skill 產出修法。兩個命令都限制輸入最多 64 項、總計 1 MiB。
匯出
npx @openai/codex-security export ./results --export-format sarif --output results.sarif
npx @openai/codex-security export ./results --export-format csv --output findings.csv支援 SARIF、CSV、JSON。SARIF 這條路等於接上了 GitHub Code Scanning 生態。匯出不需要啟動 Codex 也不用載入憑證，會先驗證掃描結果的封印（seal）才寫出。
批次掃描與容器化
如果要一次掃一整個組織的 repo，有 bulk-scan：
gh auth login
npx @openai/codex-security bulk-scan互動模式會列出近 90 天有 push 的 GitHub repo（排除 archived 和 fork），選完確認才掃。也可以吃 CSV，欄位是 id,repository,revision，revision 必須是完整 commit hash：
id,repository,revision,scope,mode
service,https://github.com/acme/service.git,0123456789abcdef0123456789abcdef01234567,src,standard官方另外提供了 Docker 映像和 compose 設定。這份 compose.yaml 的硬化程度值得一提，我把實際內容整理成表：
| 設定 | 值 | 作用 |
|---|---|---|
user | 10001:10001 | 非 root 執行 |
cap_drop | ALL | 丟掉所有 Linux capability |
no-new-privileges | true | 禁止提權 |
seccomp | 自帶 profile | 限制系統呼叫 |
| repositories.csv | read_only: true | 輸入唯讀掛載 |
你必須知道的安全模型
這段是 README 的 "Local security model"，我認為是整份文件最該讀的一節，因為它講的是這個工具的風險而不是功能。
原文的意思很清楚：codex-security 用你本機的作業系統權限執行。每次掃描套用 codex_security_scan 檔案系統設定檔和 approvalPolicy: "never"——它不會跳出來問你要不要批准。它可以讀本機檔案系統，可以寫入工作區根目錄和指定的狀態目錄。
而且透過 --codex 或 SDK 的 codexOverrides 去設 approval_policy、sandbox_mode 或權限，不會取代這些控制，也不會讓它更嚴格。
還有一句我覺得每個要在公司機器上跑它的人都該讀三遍：
掃描與 workbench 的子行程會繼承你的環境變數，包含不相關的 API token 和雲端憑證。
實務上的意思是：如果你的 shell 裡塞著 AWS key、資料庫密碼、公司內網 token，這些東西會一起進到掃描行程的環境。README 給的建議是「只帶它需要的憑證去啟動掃描」。這在共用開發機或 CI runner 上是真實風險，不是理論警告。
另外 README 反覆強調的一點：輸出目錄要放在被掃 repo 之外，而且在 macOS/Linux 上已存在的輸出目錄必須是 chmod 700 只有自己能讀。因為掃描結果裡會包含原始碼片段、漏洞細節和重現步驟——那份報告本身就是一份攻擊指南，不小心 commit 進 repo 等於公開自己的弱點。
它不適合用在哪
客觀講幾個「不要用」的情況：
你需要每次跑出完全一樣的結果。 這是 LLM 掃描的本質限制。同一份程式碼跑兩次，找到的 finding 可能不同。要可重現的 baseline，規則式 SAST 還是必要的。
你的預算不能浮動。 預設 gpt-5.6-sol + xhigh 推理強度，一次深掃的成本不是固定的。--max-cost 能設上限，但那是「花到上限就停」，不是「保證只花這麼多還掃得完」。
你要掃別人的程式碼。 SECURITY.md 和 README 都寫明只該掃你信任、且擁有或被授權評估的 repo。
你在完全離線的環境。 它要連 OpenAI。
你想要一個穩定不變的 API。 0.1.x，官方自己說 minor 版之間可能破壞相容性。而且從 git log 看，2026 年 7 月一個月就有 158 個 commit，8 月又 2 個——三週 160 個 commit，這是還在高速變動的專案。
我的判斷
codex-security 最有價值的部分不是「AI 會找漏洞」——這件事很多工具都在做。它真正做對的是掃描之後那一段流程：finding 可以被驗證、可以被標假陽性且理由會被檢查、兩次掃描可以按根本原因比對、掃不完整不會被當成掃過了、成本被記錄且可以設上限。
這些是把一次性掃描變成可持續資安流程的零件，而且每一個都反映出「不要製造假綠燈」這個立場。exit code 2 把覆蓋不完整獨立出來、compare 把「沒看到」和「修好了」分開，都是同一個設計哲學的體現。
它的代價也一樣明確：不可重現、要花錢、需要連線、API 還會變、而且它跑在你的權限下並繼承你的環境變數。
務實的用法是把它當補充而非替代：規則式 SAST 守可重現的底線和 CI 快速回饋，codex-security 用 --diff 掃 PR 差異，去抓那些規則寫不出來、需要讀懂上下文才看得見的邏輯漏洞。兩者的強項幾乎不重疊。
如果你要開始，我建議的第一步不是整個 repo 全掃——先用 --dry-run 確認設定，再用 --diff 挑一個你熟到閉著眼睛都知道有什麼問題的 PR 掃掃看。你比工具更清楚那份程式碼的真相，這是唯一能判斷它值不值得留下的方法。
npx @openai/codex-security scan . --dry-run
npx @openai/codex-security scan . --diff origin/main --output-dir /tmp/scan-results--dry-run 會驗證 repo、target、模式、輸出位置和 Codex 覆寫設定，但不啟動執行期、不載入憑證、不碰網路，還會告訴你實際生效的模型和推理強度。花不到一分鐘，先做這步。