Codex 應用案例
透過 CLI 執行安全性審查
在終端審查選定的程式碼變更,並檢視安全性問題的相關證據。
使用 Codex Security CLI 審查尚未提交的變更或分支上的變更。
最適合的對象
- 在終端檢查本機變更或分支變更的開發人員。
- 應用程式安全團隊,需在單一程式碼庫中評估特定服務、套件,以及使用這些服務或套件的元件。
- 對照程式碼庫內容調查現有 GitHub 程式碼掃描警示的工程師。
目錄
透過 CLI 執行安全性審查
在終端審查選定的程式碼變更,並檢視安全性問題的相關證據。
使用 Codex Security CLI 審查尚未提交的變更或分支上的變更。
使用 Codex Security CLI 審查尚未提交的變更或分支上的變更。
最適合的對象
- 在終端檢查本機變更或分支變更的開發人員。
- 應用程式安全團隊,需在單一程式碼庫中評估特定服務、套件,以及使用這些服務或套件的元件。
- 對照程式碼庫內容調查現有 GitHub 程式碼掃描警示的工程師。
審查本機尚未提交的變更
你可以預先提供程式碼庫和安全政策的相關上下文,再使用 CLI 審查本機尚未提交的變更。
請在本機簽出的 Git 程式碼庫中,使用同一個 shell 執行以下範例。範例假設安全政策位於 SECURITY.md,相關文件位於 docs/security/。下列設定會建立暫存目錄,用來存放掃描結果。
northstar_repo="$(git rev-parse --show-toplevel)"
northstar_kb="$northstar_repo/docs/security"
northstar_results="$(mktemp -d)"
npx @openai/codex-security scan "$northstar_repo" \
--working-tree \
--base HEAD \
--knowledge-base "$northstar_repo/SECURITY.md" \
--knowledge-base "$northstar_kb" \
--output-dir "$northstar_results/working-tree"
這項掃描會以 HEAD 為基準,審查已暫存和尚未暫存的變更。
開始前,請務必確認工作樹中包含你要評估的變更。無關的修改會擴大調查範圍,也可能讓你更難判斷審查結果與原先想釐清的問題有何關聯。
審查 PR 或分支中的提交
你也可以審查 PR 或分支,檢查是否有安全問題。先簽出要審查的分支,再擷取其目標分支。此範例使用 origin/main。
northstar_pr_base="$(git -C "$northstar_repo" merge-base origin/main HEAD)"
npx @openai/codex-security scan "$northstar_repo" \
--diff "$northstar_pr_base" \
--head HEAD \
--knowledge-base "$northstar_repo/SECURITY.md" \
--knowledge-base "$northstar_kb" \
--output-dir "$northstar_results/branch"
請注意,差異掃描只會評估擬議的變更,不會掃描整個程式碼庫。掃描完成後,輸出目錄會包含以下檔案:
-
report.md:供人閱讀的審查報告 -
scan-manifest.json:可用來確認掃描實際使用的基底版本、分支頂端提交、掃描目標及產出檔案 -
findings.json:列出各項發現的嚴重程度、信心水準、所在位置及修正方式 -
coverage.json:說明已審查的範圍、排除的項目、延後處理的工作及審查的完整程度
掃描單一程式碼庫中的多個專案
當多個專案共用同一個程式碼庫時,修改共用程式庫可能會影響多個服務。請提供足夠的上下文,讓 Codex 能審查這些服務與程式庫之間的交互影響。至於需要涵蓋哪些元件、執行哪些檢查,則由 CI 決定。
程式碼庫上下文
請將共用的工程指引放在 AGENTS.md,並在 SECURITY.md 中說明安全要求。以下是常見的程式碼庫結構:
monorepo/
├── AGENTS.md
├── SECURITY.md
├── docs/security/
│ ├── architecture.md
│ └── threat-model.md
├── packages/auth/
└── services/
├── billing/
└── reporting/
利用現有的權責歸屬資訊和建置中繼資料,找出每個元件依賴哪些項目、哪些其他元件會使用它,以及對應的測試。例如,修改 packages/auth 時,即使兩個服務的檔案都沒有變更,仍可能需要審查這兩個服務。這些用來界定審查範圍的對應關係由你的組織維護,加入 Codex 並不會自動完成設定。
評估元件
對於大型程式碼庫,每個 PR 不一定都需要掃描全部程式碼。如果同一個程式碼庫包含各自獨立的服務或套件,可以使用路徑掃描。在同一個指令中多次指定 –path,即可一併評估共用程式庫和使用它的元件。
npx @openai/codex-security scan "$northstar_repo" \
--path packages/auth \
--path services/billing \
--path services/reporting \
--knowledge-base "$northstar_repo/SECURITY.md" \
--knowledge-base "$northstar_kb" \
--output-dir "$northstar_results/paths"
這項掃描僅涵蓋選取的路徑,不會掃描整個程式碼庫。
掃描 PR 與程式碼差異
掃描 PR 時,請從經過驗證的 GitHub 中繼資料取得該 PR 的基底提交與分支頂端提交的確切雜湊值。本機簽出的程式碼庫必須包含這兩個版本及其提交歷史。以下範例沿用先前設定的變數,並將差異掃描結果另行儲存:
BASE_SHA="<full PR base commit SHA>"
HEAD_SHA="<full PR head commit SHA>"
BASE_REVISION="$(
git -C "$northstar_repo" merge-base "$BASE_SHA" "$HEAD_SHA"
)" || exit
npx @openai/codex-security scan "$northstar_repo" \
--diff "$BASE_REVISION" \
--head "$HEAD_SHA" \
--knowledge-base "$northstar_kb" \
--auth chatgpt \
--output-dir "$northstar_results/pr"
差異掃描著重於擬議的變更。如果共用程式庫有所變更,需要擴大審查範圍以涵蓋使用它的元件,請另外簽出該 PR 的分支頂端提交,並在乾淨的工作樹中執行元件評估。請分開儲存結果:--diff 和 --path 是兩種不同的掃描模式,無法合併使用。
掃描來自 GitHub 的警示
你也可以使用 Codex Security CLI,評估預設分支上的程式碼掃描警示。
northstar_github_repository="example/northstar"
northstar_github_alerts="$northstar_results/github-alerts.json"
# Import all open alerts as complete JSON.
npx @openai/codex-security import github "$northstar_github_repository" \
--format json \
> "$northstar_github_alerts"
# Or import a selected subset.
npx @openai/codex-security import github "$northstar_github_repository" \
--github-alert 12 \
--github-alert 18 \
--format json \
> "$northstar_github_alerts"
# Run from the corresponding local repository; imported contents are data.
cd "$northstar_repo"
npx @openai/codex-security validate "$northstar_github_alerts" 相關應用案例
使用 GitHub Actions 建立自訂審查工作流程
將安全審查納入開發流程,讓團隊能重複執行。設定 GitHub Actions 工作流程,使用 Codex Security 檢查提議的變更,並儲存結果供團隊檢視。
在 CI 中自動執行安全掃描
將 Codex Security CLI 加入 CI 管線。選擇掃描時機與要審查的程式碼,保留掃描發現與涵蓋範圍的紀錄,並決定如何依據掃描結果調整交付流程。
在 CI/CD 中管理供應鏈風險
使用 Codex Security CLI 評估第三方相依套件對應用程式安全性的影響。判斷 Dependabot 警示的處理優先順序,驗證警示內容,並在引入或更新套件時執行安全掃描。