SSD Nodes Learn Hosting plans →
指南 Matt Connor作者: Matt Connor

用 Codex Security 掃描 repo:安裝、VPS 登入、PR 掃描與成本上限

Codex Security 0.10.1 實作:裝好 CLI、在沒有瀏覽器的 VPS 上登入、只掃 PR 變更並設定成本上限,再把文件沒講清楚的方案、用量、申請門檻與程式碼去向逐一說明。

用 Codex Security 掃描 repo,最短要幾步?

用 Codex Security 掃描自己的 repo,最短的路徑是三個指令。先用 npm install --global @openai/codex-security 安裝,再用 cs login 登入,最後在 repo 目錄裡執行 cs scan .。掃描結束時,終端機會印出 REPORT 路徑。那是一份 Markdown 報告,列出找到的弱點和支持證據。

以下指令都以 npm 套件 @openai/codex-security 0.10.1 為準。這個版本在 2026 年 11 月 18 日發布,授權是 Apache-2.0。2026 年 11 月 21 日查看時,它是 npm 上的 latest,對應的 GitHub 發布標籤是 npm-v0.10.1。這個工具更新很快,新版的旗標可能不同,所以每次升級後先看一次 cs scan --help。

掃描本身需要登入帳號,也需要一個模型供應商,所以下面的指令都是你在自己的電腦或 VPS 上執行的步驟。每一步之後,我會寫出正常的結果長什麼樣子,也會標出文件沒有交代清楚的地方。

Codex Security 有哪幾種用法?

官方文件列出四種執行方式:

  • Daybreak Defense Factory:雲端服務,掃描連接的 GitHub repo。它是另一個外掛,名稱是 Daybreak Defense Factory (Preview),和本機用的 Codex Security 外掛是兩回事。
  • Codex 外掛:在 Codex 裡掃描本機 repo,再用對話的方式逐一處理找到的問題。
  • CLI(命令列介面,command-line interface):在終端機裡重複執行同樣的掃描,也可以放進 CI(持續整合,continuous integration)。
  • SDK(軟體開發套件,software development kit):從你自己的程式呼叫掃描。

在 VPS 上,CLI 是最直接的選擇,因為它不需要桌面程式,指令也能寫進腳本。想在每個 PR(pull request)上自動掃描,就用 GitHub Action,文件把它放在 CLI 的 CI 章節底下。想一邊看結果一邊問問題,就用外掛。

開始之前:只掃你有權評估的程式碼

Codex Security 是防守用的工具。只掃描你自己擁有,或已經取得授權評估的程式碼。在台灣和香港,很多開發者的工作是接案或外包,客戶的程式碼通常受合約約束。如果合約不允許把原始碼交給第三方服務,就不要掃。原因是本機掃描也可能把相關程式碼送到模型供應商,後面「我的程式碼有哪些會送到模型供應商」一節有文件原文。

找到的弱點是線索,不是定論。文件說掃描會先用本機原始碼驗證找到的問題,但模型仍可能判斷錯誤。所以每一個發現都要自己讀程式碼、自己重現,再決定要不要修。

安裝前,先確認 Node.js 和 Python 版本

0.10.1 需要下列其中一種 Node.js:22.x 裡的 22.13.0 以上、24.x,或 26.x。另外還需要 Python 3.10 以上。如果你用的正好是 Python 3.10,還要另外安裝 tomli 這個套件。

node --version
python3 --version
python3 -c 'import tomli' && echo "tomli ok"

node --version 應該印出 22.13.0 以上的 22 版,或是 v24、v26 開頭的版本。Node.js 23 和 25 不在支援範圍內,因為套件的 engines 欄位是 ^22.13.0 || ^24.0.0 || ^26.0.0,只接受這三個主要版本。第三行只有 Python 3.10 需要:印出 tomli ok,就代表套件已經裝好。

有一個容易誤會的地方:cs --version 和 cs info --json 不需要 Python。所以這兩個指令能執行,只代表 Node.js 那一段沒問題,不能證明 Python 也符合需求。

安裝 0.10.1 並確認指令可以用

npm install --global @openai/codex-security@0.10.1
cs --version

套件提供兩個指令名稱:codex-security,以及比較短的別名 cs。兩個指的是同一個程式。cs --version 的輸出裡應該看得到 0.10.1。

這裡刻意寫死版本號。全域安裝的 npm 套件會帶進它的相依套件,0.10.1 依賴 @openai/codex 和 @openai/codex-sdk 的 0.167.1 版。版本寫死之後,你至少知道裝的是哪一版的 Codex Security,升級也變成一個看得到的動作。為什麼這件事在伺服器上特別重要,可以看伺服器上的 npm 供應鏈攻擊的說明。

不想全域安裝的話,文件也接受用 npx 執行,例如 npx @openai/codex-security@0.10.1 login。文件的範例大多用 npx 寫法,README 則用 cs,兩者後面接的是同一組子指令。

在沒有瀏覽器的 VPS 上怎麼登入?

在有瀏覽器的電腦上,cs login 會讓你用 ChatGPT 帳號登入。VPS 沒有瀏覽器,文件給了兩條路。

第一條是裝置授權。如果你的工作區允許,加上 --device-auth,然後依照畫面上的指示,在另一台裝置的瀏覽器完成登入:

cs login --device-auth

第二條是 SSH(Secure Shell)連接埠轉發,用在工作區關掉裝置授權的時候。在你自己的電腦上執行:

ssh -L 1455:localhost:1455 user@remote-host

這個指令把你電腦上的 1455 連接埠轉到 VPS 的 1455 連接埠。連上之後,在同一個 SSH 工作階段裡執行 codex-security login,把它印出的登入網址貼到你自己電腦的瀏覽器。登入完成之前不要中斷 SSH 連線。連線一斷,轉發也跟著消失,瀏覽器那一端就接不回 VPS 上正在等待的登入程式。

ChatGPT 登入和 API 金鑰,掃描用的是哪一個?

cs scan 有一個 --auth 旗標,值可以是 auto、chatgpt 或 api-key,預設是 auto。auto 有一個陷阱:在 CI、JSON 或 JSONL 輸出的掃描,以及其他沒有互動式終端機的情況下,CLI 會使用環境變數裡的 API 金鑰。即使你已經用 ChatGPT 登入成功,也一樣。

這代表什麼?如果 shell 的環境裡還留著 OPENAI_API_KEY,然後你用 cron 排程跑掃描,這次掃描會用 API 金鑰,而不是你以為的 ChatGPT 帳號。Codex 的價格頁說,使用 API 金鑰的工作階段走另外的 API 計價。想確定用 ChatGPT 登入,就明確指定:

cs scan . --auth chatgpt

要用 API 金鑰時,不要把金鑰打在指令列上,因為整行指令會留在 shell 的歷史紀錄裡。用 read -rs 讓 shell 在不顯示的情況下讀入金鑰,掃描完就清掉:

read -rs OPENAI_API_KEY
export OPENAI_API_KEY
cs scan . --auth api-key --max-cost 5
unset OPENAI_API_KEY

執行 read -rs 後,游標會停住等你貼上金鑰。畫面上不會出現任何字元,按 Enter 就結束。README 說 CI 可以用 OPENAI_API_KEY 或 CODEX_API_KEY。不管用哪一個,金鑰都不能寫進 repo 裡的 .env 或設定檔,因為本機掃描可能把 repo 的相關內容送給模型供應商,而掃描的 log 不會遮蔽機密。更完整的做法可以看不讓 AI 代理碰到機密的做法。如果你想先弄清楚 ChatGPT 訂閱和 Codex 之間的關係,可以看用 ChatGPT 訂閱使用 Codex。

第一次掃描:執行 cs scan . 之後會看到什麼?

在 repo 的根目錄執行:

cd ~/src/myapp
cs scan .

掃描結束後,輸出裡會有 REPORT 路徑。打開那個 Markdown 檔,就是這次的報告。沒有指定 --output-dir 時,結果會存在 $CODEX_HOME/state/plugins/codex-security/scans/<repository> 底下。

報告和 log 要當成機密看待。文件寫得很直接:結果可能包含原始碼片段和弱點細節,要選私人的位置存放;儀表板和儲存的 log 可能含有原始碼或憑證,而且 log 沒有經過遮蔽。用 --output-dir 改位置時,不要放進會被 commit 的資料夾,也不要放在多人共用的帳號底下。要把報告貼到 issue 或群組聊天之前,先自己讀過一遍。

還有兩件事會影響你在哪裡跑掃描。第一,掃描程序會繼承你的環境變數,所以開始前要把無關的憑證移掉。第二,CLI 用你的作業系統權限執行,過程中不會停下來請你核准。比較穩的做法是用一個專門的使用者帳號跑掃描,帳號裡只有這個 repo,沒有別的金鑰。設定方式可以參考在 VPS 上建立最小權限的使用者。想再隔離一層,就照用拋棄式 VM 跑程式碼代理的方式另開一台機器。

只掃一部分:--path、--exclude-path 與 --diff

整個 repo 掃一次可能很久。下面的旗標可以縮小範圍:

cs scan . --path src --path tests
cs scan . --exclude-path examples/
git fetch origin
cs scan . --diff origin/main
  • --path 只掃指定的路徑。路徑相對於 repo 根目錄,可以重複寫多次。
  • --exclude-path 排除一個檔案或目錄,也可以重複寫。路徑照字面比對,相對於 repo 根目錄。
  • --diff BASE 掃描從 BASE 到 HEAD 之間已經 commit 的變更,適合 PR 大小的掃描。

--exclude-path 的行為要讀清楚。被排除的檔案仍然可能被讀取,當作理解其他程式碼的背景資料。被過濾掉的,只有位置全部落在排除路徑底下的發現。所以一個問題如果同時牽涉 examples/ 和 src/,它還是會出現在報告裡。

--diff 只看已經 commit 的變更,所以還沒 commit 的修改不在範圍內。先執行 git fetch origin,是為了讓 origin/main 指向遠端最新的狀態。否則比較基準是你上次 fetch 時的舊 main,掃描範圍可能包含不屬於這個 PR 的變更。CLI 另外有一個 --working-tree 旗標,細節請看 cs scan --help。

--path、--diff 和 --working-tree 三者互斥,同一個指令只能用其中一個。所以想「只掃 src/ 裡的 PR 變更」,不能把 --path src 和 --diff 寫在同一行。

標準模式、深度模式,以及 --max-time

--mode 可以選 standard 或 deep,預設是 standard。

cs scan . --mode deep
cs scan . --max-time 15

深度模式支援兩種目標:整個 repo,以及指定的路徑。文件沒有把 diff 列為深度模式的目標,所以 PR 大小的掃描用標準模式就好。

--max-time 是探索階段的時間上限,單位是分鐘,可以寫小數。預設值和最大值都是 5,760 分鐘,也就是 96 小時。README 把 cs scan . --max-time 15 描述成標準模式的 15 分鐘調查額度,用的字是 advisory(建議性)。所以請把它當成給調查的時間預算,不要期待它在第 15 分鐘準時停止。第一次掃大型 repo 時,先用 --max-time 和 --path 跑一個小範圍,看要花多久,再決定要不要掃全部。

0.10.1 的發布說明還提到一個改變:深度掃描遇到 misalignment 政策的拒絕時,現在會停下來回報,不會重試。所以看到深度掃描回報拒絕後結束,這是 0.10.1 的預期行為,不是程式當掉。

用 --max-cost 設成本上限,以及它擋不住的部分

一般的 cs scan 用 --max-cost USD 設上限。預估的模型費用超過這個美元金額時,CLI 會停止掃描和背後的 worker。

cs scan . --max-cost 5

這個上限是預估值,不是帳單上限。文件同時寫了「This limit is not a billing cap」和「The limit is an estimate, not a hard spending cap」。它擋不住超支的原因很具體:已經送出的請求會跑完,所以最後的金額可以超過你設的數字。另外,CLI 要知道模型的價格才能估算費用。文件提醒,使用 --max-cost 時要選有內建價格資料的模型,掃描才能執行這個限制。

那 --max-total-cost 呢?它不是一般 cs scan . 的旗標。文件把它放在掃描專案元件的章節:明確列出多個元件時,用它把一個預估預算分給這些元件。只掃一個 repo 時,用 --max-cost 就對了。

為什麼要設上限?用 API 金鑰跑的掃描走 API 計價,可能產生費用。GitHub Action 的文件也寫明,這些 workflow 會用你的 API 金鑰,並可能產生費用。Codex Security 的文件沒有寫出本機或 CLI 用 API 金鑰掃描時的計價細節,而 Action 的 README 提醒成本估算不是帳單總額。實際花了多少,以你 API 帳戶的帳單為準。

掃描完之後:找回結果、匯出威脅模型

cs scans show
cs export --scan SCAN_ID --artifact threat-model --output threatmodel.md

在同一個 repo 裡執行 cs scans show,可以再次找到這個 repo 最近一次完成的掃描。cs export 把威脅模型匯出成檔案:把 SCAN_ID 換成你要的那次掃描。省略 --scan,就會用目前 repo 最近一次完成的掃描。

匯出不需要登入,也不會再呼叫一次模型,所以不會產生模型費用。標準、深度和 diff 掃描都會把威脅模型和結果一起存下來。如果某次掃描沒有存到威脅模型,export 會回傳錯誤。--artifact 還接受哪些值,請看 cs export --help。

把威脅模型和檢查伺服器上已知 CVE 的結果放在一起看,會比較完整。CVE(Common Vulnerabilities and Exposures)是公開漏洞的編號系統。Codex Security 讀的是你寫的程式碼,CVE 掃描檢查的是你裝了哪些已知有漏洞的套件版本,兩者回答的是不同的問題。

在 Codex 裡用外掛掃描

如果你已經在用 Codex,外掛是最省事的路,適合一邊看結果一邊處理。

Codex CLI:在 repo 目錄啟動 codex,輸入 /plugins,搜尋 Codex Security,選 Install plugin。裝好之後輸入 /new,為這個 repo 開一個新的對話。

桌面版 App:打開 Plugins,搜尋 Codex Security 並安裝。確認外掛是啟用狀態,再從側邊欄打開 Security。

文件說外掛掃描不會改動你的原始碼,並會存下一份含證據和修補建議的報告。

在公司管理的工作區裡,安裝時可能看到 Disabled by admin。這代表外掛的存取權由管理員控制,你這一端改不了,要請工作區擁有者檢查外掛存取設定。

用 GitHub Action 在每個 PR 上掃描

CI 裡沒有人可以開瀏覽器登入,所以 Action 用 API 金鑰。步驟如下:

  1. 把 OpenAI API 金鑰存成 repo secret,名稱是 CODEX_SECURITY_API_KEY。
  2. 在 workflow 的 env 裡,把 OPENAI_API_KEY 設成這個 secret。
  3. 把 uses: 釘在一個你審查過的完整 commit SHA 上。

在 repo 目錄裡用 GitHub CLI 設定 secret,可以讓金鑰不進 shell 的歷史紀錄:

gh secret set CODEX_SECURITY_API_KEY

這個指令會提示你貼上值,金鑰不會出現在指令列上。

repo 裡的範例要讀,不要照抄。0.10.1 標籤下的 github-action/examples/repository.yml 寫的是 uses: openai/codex-security@REPLACE_WITH_REVIEWED_COMMIT。這是一個佔位字串,不是真的 commit,要換成你自己審查過的 SHA。這個範例用 model: gpt-5.6-sol、max-cost: "5" 和 fail-on-severity: none。PR 範例則用 scope: diff、effort: high、max-cost: "5" 和 fail-on-severity: high,也就是只掃 PR 的變更,並以 high 嚴重度作為讓檢查失敗的門檻。

max-cost: "5" 代表每次執行的預估成本上限是 5 美元。Action 的 README 同樣寫了,正在進行的請求可以超過這個上限。

注意版本差異。官方文件頁的範例把 Action 釘在 a98b35d7eef9f85c298c86229445bb64ac427aaf,註解是 action-v0.9.1,repository 範例用的模型是 gpt-6-sol,而且沒有設 max-cost。repo 裡 0.10.1 標籤的範例則用 gpt-5.6-sol,並設了 max-cost。兩份範例來自不同版本,所以先選定一個 commit,再讀那個 commit 底下的 README,模型名稱和輸入參數都以它為準。不管用哪一份,都自己加上 max-cost。

另外兩件事:

  • Daybreak 不是必要的,Action 可以用一般用途的模型。不過,如果拒絕或安全阻擋讓掃描中止,Action 會失敗。
  • 結果的預設保留天數是七天,用 retention-days 可以改。

如果你用的是自架 runner,要記得掃描程序會繼承環境變數,runner 主機上的其他憑證也在範圍內。設定和隔離方式可以看自架 GitHub Actions runner。

不用 OpenAI 也能掃嗎?模型供應商的選擇

README 寫的是,掃描支援 OpenAI、Amazon Bedrock、OpenRouter、Fireworks AI 和 Cheaper Inference。CLI 參考文件裡的 --provider 則列出四個值:openai、openrouter、fireworks、amazon-bedrock,預設是 openai。這份清單裡看不到 Cheaper Inference,要用它的話,先看 cs scan --help。

Bedrock 掃描用的是 AWS 憑證,不需要 --auth、OpenAI 登入或 OpenAI API 金鑰。OpenRouter 則要提供它的 API 金鑰 OPENROUTER_API_KEY,並明確指定模型。

對受合約約束的程式碼來說,供應商的選擇很重要,因為程式碼會送到你設定的那一家。如果公司已經和某家雲端簽了資料處理協議,選那一家通常比較容易通過內部審查。

文件沒說清楚的四件事

下面四個問題,官方文件沒有給出完整答案。我把文件實際寫了什麼列出來,沒寫的部分就直接說沒寫。

哪些 ChatGPT 方案可以用外掛或 CLI 掃描?

文件沒有說。README、CLI 文件和說明中心都沒有列出外掛或 CLI 需要哪些方案。價格頁的方案表裡只有一列「Codex Security for connected GitHub repositories」,標示只有 Enterprise 可用。這一列講的是連接 GitHub 的雲端產品,不能拿來推論本機掃描。

價格頁另外寫了 Codex 包含在 ChatGPT 的 Free、Go、Plus、Pro、Business、Edu 和 Enterprise 方案裡。這句話講的是 Codex 整體,沒有提到 Codex Security。對 Plus 或 Pro 使用者來說,最可靠的答案是自己試:執行 cs login,再用 --path 跑一個很小的掃描。

用 ChatGPT 登入掃描,會用掉 Codex 的使用額度嗎?

文件沒有直接說。文件說清楚的是雲端那一邊:repo 掃描和持續監控按 token 用量計費,方案內含的使用額度不涵蓋這些掃描。

本機掃描只有一條線索。CLI 文件說,當 Codex 提供帳號額度資訊時,進度畫面會顯示每個回報時段已用的百分比;用 ChatGPT 登入時,如果 Codex 還沒回報額度,進度畫面也會註明。所以實際跑一次小掃描,看進度畫面有沒有出現額度百分比,是目前最直接的判斷方式。價格頁另外說,使用 API 金鑰的工作階段走另外的 API 計價,不會用到 ChatGPT 的額度,但這句話是針對 Codex 整體寫的。

CLI 現在還需要申請才能用嗎?

我讀過的 0.10.1 README、CLI 文件頁和參考文件,都沒有 beta、預覽或僅限核准客戶之類的字眼。一般的標準掃描,文件沒有描述成需要申請。網路上如果看到較早的不同說法,請以目前的文件為準,並自己試一次。

文件寫的門檻是另一件事:部分資安相關的請求和受保護的發現,需要 Trusted Access for Cyber。這是 OpenAI 的資安存取計畫,也叫 Daybreak Access。如果你的 ChatGPT 工作區有 Daybreak Blue 存取權,文件說可以在掃描指令加上這兩個旗標:

cs scan . --model gpt-6-sol --cyber-access-program daybreak_blue

--cyber-access-program 在 OpenAI 掃描上接受 standard、daybreak_blue 或 daybreak_red。使用 Daybreak Blue 的本機掃描需要 trusted access。如果介面出現 Apply for Daybreak,就是要你從那裡申請。

說明中心寫的申請條件如下。審核不是自動通過的。個人申請需要符合資格的付費方案、開啟 Advanced Account Security、至少一把相容的 FIDO2 硬體安全金鑰,而且要年滿 18 歲。說明中心沒有列出是哪幾種付費方案。Daybreak Red 目前只開放給通過核准的商業和企業組織。README 指向的申請頁是 chatgpt.com/cyber。

我的程式碼有哪些會送到模型供應商?

文件的原話有兩句。設定頁寫:「A local scan can send relevant code and prompts to the configured model provider.」意思是本機掃描可能把相關的程式碼和提示詞送到你設定的模型供應商。CLI 文件寫:「Validation sends each finding to the configured model provider.」意思是用 --validate 做後續驗證時,每一個發現都會送給模型供應商。同一段也說,驗證用的審查工具只有唯讀的檔案系統權限,網路存取和網頁搜尋都是關閉的。

文件沒寫的部分有四項:相關程式碼的範圍到底多大、供應商保留多久、會不會拿去訓練,以及本機或 API 金鑰掃描是否適用零資料保留(Zero Data Retention,ZDR)。唯一提到 ZDR 的一句,是 Trusted Access 不會自動給你零資料保留。

所以做法要保守:假設 repo 裡任何檔案都可能被送出去,掃描前先把機密從 repo 裡清乾淨。被掃描的程式碼本身就是模型的輸入,如果你掃描的是 vendored 的第三方程式碼,裡面的註解和文字也可能進到模型的上下文,程式碼代理的提示詞注入講的就是這類輸入的風險。雲端連線是選用的,README 寫明本機掃描不需要它。

掃描出錯時,先看這幾個症狀

  • 以為用 ChatGPT 登入,實際卻用了 API 金鑰。 原因是 --auth auto 在非互動的執行環境裡會用環境變數的 API 金鑰。用 unset OPENAI_API_KEY 清掉,或加上 --auth chatgpt。
  • 花費超過 --max-cost 的數字。 原因是上限是預估值,已經送出的請求會跑完。把上限設得比你能接受的金額低一些。
  • cs export 回傳錯誤。 那次掃描沒有存下威脅模型。用 cs scans show 找一次完成的掃描,再用 --scan 指定它。
  • --path 和 --diff 一起用時失敗。 這兩個旗標互斥。拆成兩次掃描,或只用 --diff。
  • 安裝外掛時看到 Disabled by admin。 外掛存取由工作區管理員控制,請工作區擁有者處理。
  • GitHub Action 失敗,log 提到拒絕或安全阻擋。 掃描被中止時 Action 就會失敗,這是 Action 的設計行為,不代表 workflow 的語法寫錯。

常見問題 FAQ

Codex Security 掃描會把整個 repo 上傳嗎?

文件只說本機掃描可能把相關的程式碼和提示詞送到設定的模型供應商,而用 --validate 驗證時,每個發現也會送出。哪些檔案算相關、保留多久、會不會用於訓練,文件都沒有說明。保守的做法是假設任何檔案都可能被送出,掃描前先把機密移出 repo。受合約約束的程式碼,要先確認你有權這樣處理。

ChatGPT Plus 或 Pro 可以用 Codex Security CLI 嗎?

官方文件沒有列出外掛或 CLI 支援哪些方案。價格頁唯一的 Codex Security 項目是連接 GitHub 的雲端掃描,標示只有 Enterprise 可用,但那不是本機 CLI。最可靠的方法是自己執行 cs login,再用 cs scan . --path src 掃一個小目錄,看能不能完成。

--max-cost 是硬性的花費上限嗎?

不是。文件寫明它是預估值,不是帳單上限,已經送出的請求可以在超過上限之後才結束。使用時要選有內建價格資料的模型,CLI 才能執行這個限制。實際花費以 API 帳戶的帳單為準。--max-total-cost 是掃描多個專案元件時用來分配總預算的旗標,一般的 cs scan . 用 --max-cost。

在沒有瀏覽器的 VPS 上要怎麼登入 Codex Security?

工作區允許的話,用 cs login --device-auth。如果裝置授權被關閉,就在自己的電腦執行 ssh -L 1455:localhost:1455 user@remote-host,在這個 SSH 工作階段裡執行 codex-security login,再把印出的登入網址貼到自己電腦的瀏覽器。登入完成前不要中斷 SSH 連線,因為轉發會跟著連線一起消失。

Codex Security 找到的問題可以直接當成漏洞嗎?

不行。掃描會先用本機原始碼驗證,但結果仍是需要人確認的線索。每個發現都要讀相關程式碼、自己重現,再決定修補方式。也請只掃描你擁有或已獲授權評估的程式碼。

這篇文章對您有幫助嗎?

#codex#security#vulnerability-scanning#ci#npm