繁體中文

審查程式碼變更的安全性

對一個由 Git 支撐的變更集做安全迴歸審查,而不是展開成全儲存庫審計。

執行安全變更審查,查詢一個由 Git 支撐的變更集中的安全迴歸。Codex 會審查每個發生變更的原始碼類檔案及其直接支撐程式碼,但不會把審查擴充套件成完整儲存庫審計。

如果你想掃描完整儲存庫,而不是某個具體變更,請參見執行安全掃描

執行手動審查

在桌面 App 中開啟 Security(安全),選擇 Scans(掃描),再選擇 + Scan(新建掃描)。選擇儲存庫,然後選擇 Changes(變更)。你可以審查未提交變更、單個 commit,或 base 與 head revision。變更掃描不支援 Deep scan(深度掃描)

也可以在 Codex 對話中請求審查未提交變更:

Use $codex-security:security-diff-scan to review my current uncommitted changes for security regressions.

對於 commit 或 branch range,必要時明確兩端:

Use $codex-security:security-diff-scan to review the changes from origin/main to HEAD for security regressions. Focus on authentication, authorization, input handling, filesystem access, network requests, and secrets.

當 pull request 的 base 和 head revision 在本機 checkout 中可用時,也可以直接指定 pull request。

在設定中確認變更

  1. 選擇 Changes(變更)
  2. 確認已 checkout 的儲存庫、當前分支和最新 commit。
  3. Changes to review(待審查改動) 下選擇:
    • Uncommitted changes:當前 Git 工作區中的未提交改動。
    • 最新 commit:單個 commit 的審查。
    • base revision 和 head revision:分支或 pull request 的修訂版本區間。
  4. 確認摘要描述的是你想審查的變更。
  5. 選擇 Start scan(開始掃描)

這個工作流程不會檢出另一個分支,也不會修改選中的 Git 工作區。如果請求的 revision 在本機不可用,請先執行 fetch,或提供一組本機可用的 base revision 和 head revision。

處理發現結果

審查結果後,可以修復並驗證已接受的發現,或匯出和跟蹤發現

在 CI/CD 中自動化審查

當 CI runner 能以非互動方式呼叫 Codex CLI 時,可以在 CI 中運行同一個 $codex-security:security-diff-scan skill。先安裝 CLI 與 plugin,同時避免暴露掃描憑據:

npm install --global @openai/codex

在 CLI 中安裝 Codex Security 外掛:

codex plugin add codex-security@openai-curated

安裝命令使用公開的 Codex CLI plugin marketplace,其版本可能與託管的桌面 App catalog 不同。在 CI 中依賴特定外掛版本或功能前,請檢視外掛更新日誌

然後,只在掃描期間把 CI secret store 中的 OpenAI API key 作為 CODEX_SECURITY_API_KEY 暴露:

CODEX_API_KEY="$CODEX_SECURITY_API_KEY" codex exec \
  --sandbox workspace-write \
  "Use \$codex-security:security-diff-scan to review changes from $BASE_REVISION to $HEAD_REVISION for security regressions. Do not modify the checkout."

掃描會把輸出寫入 $TMPDIR/codex-security-scans/<repository>/<scan-id>/

檔案 內容
report.md 完整掃描目錄的主要可讀入口。
findings/<slug>/ 每項需報告發現對應一份詳細漏洞報告;有可用材料時還會包含 PoC 檔案。
hardening/ 掃描存在需報告發現時,包含結構性加固方案集及配套提案或圖示。
findings.json 帶穩定標識、嚴重程度、置信度、原始碼位置與修復建議的發現,可交給已核准的內部安全工作流程或下游工具。
scan-manifest.json 封存的掃描回執,包含審查目標、修訂版本和產物 hash。
coverage.json 已審查與延後處理的範圍、排除項和覆蓋完整性。

完整結構由 findings.json schema定義,其中包括以下欄位:

欄位 類型 說明
documentType String 標識文件類型為 codex-security.findings
schemaVersion String 標識 findings schema 版本。
scanId String 標識生成這些發現的掃描。
findings Array 包含零個或多個發現物件。
findings[].findingId String 根據發現 fingerprint 派生的穩定發現標識。
findings[].occurrenceId String 標識該發現出現在某次具體掃描中的例項。
findings[].ruleId String 標識漏洞類別。
findings[].identity Object 包含語義錨點和可選的同級例項標識。
findings[].fingerprints Object 包含 fingerprint 演算法與主要 fingerprint。
findings[].title String 簡短的發現標題。
findings[].summary String 概述漏洞及其影響。
findings[].severity Object 包含嚴重程度等級和可選評分詳情。
findings[].confidence Object 包含置信度等級和理由。
findings[].taxonomy Object 包含漏洞類別與 CWE 標識。
findings[].locations Array 列出受影響檔案、行號和位置角色。
findings[].remediation String 說明建議修復方式。
findings[].provenance Object 標識發現來源。

例如,下面的命令會為每項發現輸出一行製表符分隔的資料:

jq -r '
  .findings[] |
  [.findingId, .severity.level, .confidence.level, .locations[0].path, .locations[0].startLine, .title] |
  @tsv
' findings.json

下面的範例假設使用受信任的 Linux runner,並已安裝 Node.js 與 npm、Git、Python 3、jq 以及相應平台的 CLI。npm 的全域 package prefix 必須可寫。

根據你的 CI provider 選擇範例。掃描結果可能包含敏感的漏洞詳情。請保持產物私密,只有在審查受眾、內容和所需審批後才釋出安全發現。

name: Codex Security review

on:
  pull_request:

jobs:
  security-review:
    if: github.event.pull_request.head.repo.full_name == github.repository
    runs-on: ubuntu-latest
    permissions:
      contents: read
    steps:
      - uses: actions/checkout@v5
        with:
          ref: ${{ github.event.pull_request.head.sha }}
          fetch-depth: 0
          persist-credentials: false

      - name: Install Codex Security
        env:
          CODEX_HOME: ${{ runner.temp }}/codex-home
        run: |
          npm install --global @openai/codex
          codex plugin add codex-security@openai-curated

      - name: Review code changes
        env:
          CODEX_SECURITY_API_KEY: ${{ secrets.CODEX_SECURITY_API_KEY }}
          CODEX_HOME: ${{ runner.temp }}/codex-home
          TMPDIR: ${{ runner.temp }}/codex-security
          BASE_SHA: ${{ github.event.pull_request.base.sha }}
          HEAD_REVISION: ${{ github.event.pull_request.head.sha }}
        run: |
          BASE_REVISION="$(git merge-base "$BASE_SHA" "$HEAD_REVISION")"
          CODEX_API_KEY="$CODEX_SECURITY_API_KEY" codex exec \
            --sandbox workspace-write \
            "Use \$codex-security:security-diff-scan to review changes from $BASE_REVISION to $HEAD_REVISION for security regressions. Do not modify the checkout."

      - uses: actions/upload-artifact@v4
        if: always()
        with:
          name: codex-security-review
          path: ${{ runner.temp }}/codex-security/codex-security-scans

這些範例會跳過來自 fork 的 pull request。只有受保護的 pipeline 定義,以及可以信任其接觸掃描憑據的貢獻者,才能執行帶憑據的作業。請歸檔 codex-security-scans,把結構化發現、manifest、覆蓋產物、report.md 及其連結的 findings/hardening/ 輸出儲存在一起。先以非阻斷方式執行,審查覆蓋範圍和執行時間後,再把作業設為 required check。

API key 處理與沙箱控制請參見非互動模式。如果組織允許使用 Codex GitHub Action,它可以在執行時安裝 CLI,但你仍需先安裝 plugin,並讓 action 的 codex-home 輸入指向同一個 CODEX_HOME


來源:</zh-TW/docs/security/plugin/code-changes> 更新時間:2026-07-18(UTC)