【2026 最新】Codex Security CLI 怎麼用？掃描、驗證、修補與重跑實戰

最後更新：2026年7月30日 · Terry Chen

一行 scan 跑完，終端機列出「高風險漏洞」，你下一步該立刻讓 AI 改 code 嗎？先不要。Codex Security CLI 真正考驗人的地方，不是啟動掃描，而是判斷這個 finding 能不能被利用、是不是重複項目，以及修補會不會順手破壞正常功能。

這篇是寫給第一次接觸應用程式安全掃描的開發者。我會從隔離工作區、限定範圍、第一次 scan 開始，完整走過驗證、最小修補、原測試與重新掃描；你可以把命令直接改成自己的路徑使用。文中以 2026 年 7 月 30 日的 npm 0.1.4 為基準，執行前仍要先看自己的版本。

先說結論

Finding＝待驗證的漏洞假說；有效修補＝原攻擊路徑失敗＋合法行為與原測試仍通過＋同範圍重驗完成。

Table of Contents

Codex Security CLI 是什麼？先分清楚兩種產品

Codex Security 官方 GitHub repo 的 GitHub API 建立時間是 2026 年 7 月 13 日 22:00 UTC（UTC+8 為 7 月 14 日）；截至 7 月 30 日 15:23（UTC+8）的快照有 5,407 stars、351 forks、38 個 open issues 與 23 個 open pull requests。這反映強烈注意力與快速迭代，不代表 5,407 人都需要教學，更不代表掃描準確率。

你在這篇操作的是 npm 套件提供的獨立 CLI：它在你的終端機裡建立掃描、保存 findings 與 coverage，並提供 validate、patch、歷史比對等命令。獨立不代表離線；真正的 scan 會啟動 Codex 並使用模型與網路資源，需依組織的資料政策評估。它與 OpenAI 帳戶裡的 hosted Codex Security 服務相關，但不是同一個操作介面；不要把雲端產品的隔離沙箱描述，直接套用到本機 CLI。

OpenAI 將它定位成會讀 code、執行測試並探索 attack path 的安全 reviewer；實際 finding 仍是待驗證假說。它也能生成 threat model，但部署假設、業務不變條件與可接受風險，仍需要團隊核對。想先理解 agent 為什麼能讀檔、跑工具與迭代，可以搭配 AI Agent Harness 是什麼；要管理大改版的影響範圍，則看大型 Repo 安全改版工作流。

Codex Security CLI 第一次掃描：先隔離，再執行

本文用 OWASP Juice Shop 作為操作載體；它本來就是刻意保留漏洞的安全訓練專案，適合練習流程。請只掃描你擁有或明確獲得授權的程式碼：

git clone --depth 1 https://github.com/juice-shop/juice-shop.git codex-security-lab
cd codex-security-lab

步驟 0：只在可丟棄的 branch 或 worktree 操作

scan 主要產生結果，但後面的 validate 可能建置、執行程式或建立 PoC；patch 更會修改目前目錄。因此，先確認工作區乾淨，再開隔離分支。若 repository 會接觸生產資料、部署憑證或雲端金鑰，改用乾淨 VM／container，並只掛載允許讀取的程式碼。

git status --short
git switch -c security/codex-triage

mkdir -p ../codex-security-results
chmod 700 ../codex-security-results

掃描輸出可能包含原始碼片段、漏洞細節與重現步驟，放在 repo 外、限制權限，並依團隊的保留政策清除。也要先移除這次工作不需要的環境憑證；「選了某個資料夾」不等於作業系統級隔離。

步驟 1：檢查版本與登入狀態

官方套件要求相容的 Node.js 版本；掃描與匯出流程也需要 Python 3.10 以上，若剛好是 Python 3.10 還要安裝 tomli。先固定這篇實測的版本，避免今天的命令被明天的 prerelease 行為悄悄改掉：

node --version
python3 --version
npx --yes @openai/codex-security@0.1.4 --version

npx @openai/codex-security@0.1.4 login
npx @openai/codex-security@0.1.4 login status

這篇採 npx 臨時取得並執行指定版本，不需要先做全域安裝；首次執行會下載套件。截至本文快照，npm 0.1.4 支援 Node ^22.13.0 || ^24.0.0 || ^26.0.0。遠端或無瀏覽器環境可使用 login --device-auth；若要固定安裝在專門的 tooling 專案，完整步驟以官方 CLI quickstart為準。

步驟 2：用 dry-run 檢查輸入，不要把它誤當掃描

npx @openai/codex-security@0.1.4 scan . \
  --path routes \
  --output-dir ../codex-security-results \
  --dry-run

我在刻意含漏洞的測試 repo 上實跑這條流程，dry-run 會回報 repository、target、mode、output directory、model 與 reasoning effort。它的用途是驗證參數與前置輸入；它不會開始掃描，也不會替你證明登入、模型權限或實際分析一定成功。

Codex Security CLI dry-run 第一次掃描命令與輸出解讀 — 先用 dry-run 核對目標與輸出位置；看到 preflight complete，仍不等於安全掃描已完成。

步驟 3：限定範圍，再跑真正的 scan

npx @openai/codex-security@0.1.4 scan . \
  --path routes \
  --output-dir ../codex-security-results \
  --max-cost 5

--path 可重複，用來描述本次目標；--diff BASE 與 --working-tree 則適合檢查變更，三種 selector 不能混用。--max-cost 5 是估算成本到門檻後停止的控制，不是絕不超過 5 美元的硬上限，因為已送出的請求仍可能完成。第一次不要急著用 deep mode，先讓標準掃描的範圍與證據流程跑通。

還有一個容易踩的坑：在公開的 0.1.4 CLI reference 裡，範圍入口是 --path、--diff、--working-tree，不要自行假設有 --exclude。可以在根目錄或較近的 SECURITY.md 寫威脅模型、不可破壞的不變條件、哪些情況才算可回報；但這是給分析器的政策脈絡，不是檔案存取防火牆。真正不能被讀到的內容，要從掃描環境移除，或在獨立 VM／container 中只掛載允許的內容。

先看 coverage，再看 finding 數量

掃描完成後，最值得先開的不是漂亮的 finding 標題，而是輸出目錄裡的 coverage.json：哪些 surface 被檢查、哪些被延後、有哪些 open questions，完整度是 complete、partial 還是 unknown。接著再看 report.md 與 findings.json。

CLI 的 exit code 也不是「0＝沒有漏洞」這麼簡單。預設 scan 是 report-only：0 表示 coverage complete 且命令完成，或已設定的 severity policy 通過；只有加上 --fail-on-severity LEVEL 並命中門檻，才會回傳 1，所以掃到 high finding 仍可能是 0。2 可能是輸入／執行／匯出錯誤，也可能是 coverage 不完整。即使沒有 finding，只要 coverage 是 partial 或 unknown，就不能把它當成安全證明。細節可對照官方 exit code 與 coverage 說明。

Codex Security CLI 怎麼驗證 finding？用證據卡，不看標題投票

每一個 finding 都先當成「值得調查的漏洞假說」。高 severity 不等於已確認可利用；相反地，標題看似普通的授權缺口，也可能跨過最重要的產品邊界。一次只拿一個項目，建立這張證據卡：

攻擊者可控來源：輸入從 URL、request body、header、檔案或訊息佇列哪裡進來？
前置條件：需要登入、特定角色、內網位置或競態時機嗎？
現有控制：驗證、編碼、參數化、授權 middleware 是否真的覆蓋這條路？
危險 sink／結果：最後會查資料庫、執行命令、讀檔，還是把他人資料送出去？
可達性與邊界：source 能否穿過 control 到 sink？跨過哪個信任或產品邊界？
反證與 proof gap：什麼證據會推翻 finding？哪一段因環境限制仍無法證明？

Codex Security finding 驗證證據鏈與三種判定 — 先追 source → control → sink，再依證據判定 confirmed、not actionable 或 needs review。

完整範例：缺少管理員授權，不是看到 200 就修成 403

假設 finding 指向 GET /admin/export，宣稱一般會員也能匯出全部資料。真正要守的是產品不變條件：「只有 admin 能匯出」，所以測試必須同時證明攻擊路徑被拒絕、合法路徑仍可用：

describe("GET /admin/export", () => {
  it("拒絕一般會員匯出全部資料", async () => {
    const response = await api.get("/admin/export").auth(memberToken);
    expect(response.status).toBe(403);
  });

  it("仍允許管理員正常匯出", async () => {
    const response = await api.get("/admin/export").auth(adminToken);
    expect(response.status).toBe(200);
  });
});

修補前，第一個測試若拿到 200 而失敗、第二個測試通過，就得到一個可重複的最小重現。接著再檢查 nearby bypass，例如相同資料是否還能從另一個 endpoint、大小寫不同的路徑或背景 job 匯出。無法安全重現時，不要硬寫 PoC；記錄 proof gap，保留 needs review。

也可以讓 CLI 直接驗證某個候選 finding。請注意：它會以目前目錄為工作區，可能建置、執行或寫入驗證產物，所以仍要在乾淨、隔離的 branch／worktree 進行：

npx @openai/codex-security@0.1.4 validate \
  ../codex-security-results/findings.json \
  "驗證 src/routes/admin.ts 的匯出授權缺口；保留可重複證據與 proof gap"

誤報與重複項目要分開處理

當現有 control 確實切斷 source 到 sink，而且你能指出具體證據，才標記 false positive：

npx @openai/codex-security@0.1.4 scans show SCAN_ID

npx @openai/codex-security@0.1.4 findings false-positive OCCURRENCE_ID \
  --reason "此輸入在抵達查詢前由框架參數化；測試 X 證明 payload 不會改變查詢結構"

這個理由會成為未來掃描的脈絡；它不是永久關閉某一條規則，後續仍會重新檢查現在的 source、control 與 reachability。至於兩個 finding 若其實來自同一個共用授權函式，應保留各自的 occurrence／source ID，再關聯到同一個 root cause；重複不是誤報。

怎麼修補？最小改動、雙向測試、人類看 diff

確認 finding 後，一次只修一個 root cause。你可以自己改，也能用 patch 生成候選修補：

npx @openai/codex-security@0.1.4 patch \
  ../codex-security-results/findings.json \
  "修補 src/routes/admin.ts 的授權缺口；只做最小改動，加入攻擊與合法路徑測試"

patch 以目前 checkout 為 workspace，具有寫入權限且可能直接修改檔案；生成結果不等於已核准。先看 git diff --check 與完整 diff，確認沒有擴張權限、刪掉原本功能、把敏感值寫進 log，或只針對測試 payload 打補丁。再跑「修補前會失敗、修補後會通過」的 focused regression test、正常使用測試、附近 bypass 測試，最後跑 repo 原有測試。測試命令依專案而定，不要盲目假設一定是 npm test。

如果你常讓 coding agent 跨很多檔案修改，先讀 Blast Radius 與冷審查教學；若想理解權限、工具與 secrets 如何被 harness 放大，可接著看 AI Agent secrets 安全。這兩篇處理的是改動邊界與執行邊界，正好補上漏洞修補工作流的另外兩面。

修完怎麼證明？重跑不等於結案

保存修補前的 scan ID，完成測試後重跑原始掃描設定。本文固定的 0.1.4 流程要明確做四步：

# 1. 以原設定重跑，記下輸出的 AFTER_SCAN_ID
npx @openai/codex-security@0.1.4 scans rerun BEFORE_SCAN_ID

# 2. 對齊同一 root cause
npx @openai/codex-security@0.1.4 scans match BEFORE_SCAN_ID AFTER_SCAN_ID

# 3. 看 new / persisting / reopened / resolved / unknown
npx @openai/codex-security@0.1.4 scans compare BEFORE_SCAN_ID AFTER_SCAN_ID

# 4. 對目前 checkout 直接重驗原 finding
npx @openai/codex-security@0.1.4 validate \
  ../codex-security-results/findings.json \
  "重新驗證原本的 admin export 授權缺口"

為什麼不能只看「resolved」？AI 輔助掃描即使設定相同，也可能出現差異；finding 消失，可能是修好了，也可能是後一次沒有完整覆蓋原 target 與 affected path。只有 coverage 沒有缺口、直接 validate 不再重現、攻擊測試失敗且合法路徑與原測試仍通過，證據才閉環。官方 FAQ 也明確提醒：scan comparison 本身不能證明修補成功。

Codex Security 漏洞修補驗證閉環 — 有效修補需要三種獨立證據：攻擊失敗、合法行為通過、同範圍重掃與直接重驗。

Codex Security 與 dependency、secret、SAST 怎麼分工？

不要問「哪一套可以取代全部」，應該問「哪一層證據還缺」。dependency／SCA 擅長對已知套件與漏洞資料庫；secret scanning 擅長找 token、key 與憑證模式；SAST／CodeQL 擅長可重複的規則與資料流查詢；Codex Security 適合用語意推理追跨檔案的應用程式邏輯與產品邊界；人類 review 則負責核對真實威脅模型、業務不變條件與可接受風險。

Codex Security 與 SCA、secret scan、SAST、人工 review 分工圖 — 五層工具回答不同問題；重疊是防線，不是浪費，也沒有任何單層等於「程式安全」。

實務上，可以把 Dependabot、secret scanning、CodeQL 與 Codex Security 疊在一起，再由人類對高影響變更做 review，讓不同種類的證據互相校驗。若你還在比較 coding agent 本身，可看 Claude Code vs Codex 客觀比較。

最常見的 7 個錯誤

把 severity 當 exploitability：先驗證前置條件、可達性與邊界。
看到 0 finding 就宣布安全：先看 coverage 是否 complete。
把 dry-run 當權限測試：它只檢查輸入，沒有真的啟動分析。
把 --path 當硬隔離：敏感 code 應從掃描環境移除。
把重複 finding 標成誤報：保留來源 ID，關聯 root cause。
修到 scanner 不叫就好：測產品不變條件，而不是迎合一段文字。
重掃沒看到就結案：補上 match、compare、coverage 與 direct validate。

FAQ：Codex Security CLI 新手最常問的 8 題

1. Codex Security CLI 是免費的嗎？

套件是公開的，但實際掃描會使用模型資源。成本與可用權限依帳戶而異；用 --max-cost 做軟性控制，先對小範圍跑標準模式。

2. 可以直接在公司主 repo 跑嗎？

可以，但不建議第一次就在含敏感憑證的日常工作區操作。先用授權的測試 repo 或乾淨 checkout，確認資料邊界、輸出保留與帳戶政策。

3. `--path src` 代表工具絕不讀其他地方嗎？

不代表。它描述掃描目標，不是 OS sandbox。分析為理解脈絡可能需要查看相鄰程式；不可讀內容要從環境中移除。

4. Finding 標示 high 就一定要立刻修嗎？

要立刻 triage，不等於盲修。先驗證攻擊者控制、前置條件、現有 control、可達性與影響，再決定優先級。

5. 能讓 `patch` 一次修完全部嗎？

不該。一次處理一個 accepted finding／root cause，才能看懂 diff、建立 focused test，也容易回退。

6. False positive 會永久被忽略嗎？

不會。你的理由會提供給未來掃描作為脈絡，但工具仍會依當下程式碼重新檢查 control 與 reachability。

7. 重跑後 finding 消失，就代表修好了嗎？

不一定。先確認同範圍 coverage complete，再 match、compare，最後 direct validate 原 finding，並跑攻擊與合法路徑測試。

8. 它能取代 SAST、secret scan 與人工 review 嗎？

不能。不同工具產生不同種類的證據；最佳做法是分層搭配，讓規則型偵測、語意推理與人類產品判斷互相補位。

給新手的最短執行清單

確認授權範圍，建立乾淨 branch／worktree，輸出放 repo 外。
固定 CLI 版本，先跑 --dry-run 核對 target。
小範圍 scan；先讀 coverage，再讀 findings。
每次只 triage 一個 finding，建立 source→control→sink 證據卡。
用最小重現與雙向測試確認 confirmed／not actionable／needs review。
在隔離分支做最小修補，人類 review diff，跑 focused 與原有測試。
執行 rerun→match→compare→validate，確認原範圍 coverage complete。

📚 延伸閱讀：把掃描接進完整 AI 開發工作流

AI Agent Harness 是什麼：先理解模型如何透過工具讀檔、執行與迭代。
動手做 AI Agent Harness：把權限、停止條件與驗證寫進執行層。
大型 Repo 安全改版：用 blast radius、分段 commit 與冷審查控制修補風險。
AI Agent secrets 安全：避免掃描與 agent 工作區順手碰到不必要的憑證。
AlphaLab AI 專區：繼續補齊 agent、模型與實作知識。
AlphaLab 課程：把零散工具整理成可重複的 AI 實戰系統。

結語：掃描器給假說，工程流程給證明

Codex Security CLI 最有價值的輸出，不是一串看起來很嚇人的標題，而是一個可以被重現、反駁、修補與回歸驗證的起點。記住本文的錨點：Finding 是待驗證的漏洞假說；有效修補要同時讓攻擊路徑失敗、合法路徑通過，並在同範圍完成重驗。

現在就拿一個你有權測試的小型 repo：先建隔離 branch，執行 version check 與 dry-run，再只掃一個資料夾。第一輪的成功標準不是「找到幾個洞」，而是你能否替第一個 finding 寫出一張完整證據卡。