如需完整的文件索引,請參閱 llms.txt。在文件頁面的網址末尾加上 .md ,即可取得該頁面的 Markdown 版本。
主要導覽
主題
Codex

Codex 應用案例

透過 CLI 執行安全性審查

在終端審查選定的程式碼變更,並檢視安全性問題的相關證據。

難度 Intermediate
任務時間跨度 30m

使用 Codex Security CLI 審查尚未提交的變更或分支上的變更。

最適合的對象

  • 在終端檢查本機變更或分支變更的開發人員。
  • 應用程式安全團隊,需在單一程式碼庫中評估特定服務、套件,以及使用這些服務或套件的元件。
  • 對照程式碼庫內容調查現有 GitHub 程式碼掃描警示的工程師。

目錄

    ← 所有應用案例

    透過 CLI 執行安全性審查

    在終端審查選定的程式碼變更,並檢視安全性問題的相關證據。

    使用 Codex Security CLI 審查尚未提交的變更或分支上的變更。

    Intermediate
    30m
    查看設定步驟

    使用 Codex Security CLI 審查尚未提交的變更或分支上的變更。

    Intermediate
    30m

    最適合的對象

    • 在終端檢查本機變更或分支變更的開發人員。
    • 應用程式安全團隊,需在單一程式碼庫中評估特定服務、套件,以及使用這些服務或套件的元件。
    • 對照程式碼庫內容調查現有 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"

    相關應用案例