審查程式碼變更的安全性
對一個由 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。
在設定中確認變更
- 選擇 Changes(變更)。
- 確認已 checkout 的儲存庫、當前分支和最新 commit。
- 在 Changes to review(待審查改動) 下選擇:
Uncommitted changes:當前 Git 工作區中的未提交改動。- 最新 commit:單個 commit 的審查。
- base revision 和 head revision:分支或 pull request 的修訂版本區間。
- 確認摘要描述的是你想審查的變更。
- 選擇 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 建立 masked CODEX_SECURITY_API_KEY CI/CD variable,並在分享安全發現前私下審查掃描產物。
codex-security-review:
rules:
- if: '$CI_PIPELINE_SOURCE == "merge_request_event" && $CI_MERGE_REQUEST_SOURCE_PROJECT_ID == $CI_PROJECT_ID'
variables:
GIT_DEPTH: "0"
script:
- |
codex_security_api_key="$CODEX_SECURITY_API_KEY"
unset CODEX_SECURITY_API_KEY
export CODEX_HOME="/tmp/codex-home-$CI_JOB_ID"
export TMPDIR="/tmp/codex-security-$CI_JOB_ID"
export BASE_REVISION="$CI_MERGE_REQUEST_DIFF_BASE_SHA"
export HEAD_REVISION="${CI_MERGE_REQUEST_SOURCE_BRANCH_SHA:-$CI_COMMIT_SHA}"
npm install --global @openai/codex
codex plugin add codex-security@openai-curated
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."
after_script:
- |
unset CODEX_SECURITY_API_KEY
scan_root="/tmp/codex-security-$CI_JOB_ID/codex-security-scans"
if [ -d "$scan_root" ]; then
tar -czf codex-security-artifacts.tar.gz -C "$scan_root" .
fi
artifacts:
when: always
paths:
- codex-security-artifacts.tar.gz trigger: none
pool:
vmImage: ubuntu-latest
steps:
- checkout: self
fetchDepth: 0
- bash: |
set -euo pipefail
export CODEX_HOME="$AGENT_TEMPDIRECTORY/codex-home"
npm install --global @openai/codex
codex plugin add codex-security@openai-curated
displayName: Install Codex Security
- bash: |
set -euo pipefail
export CODEX_HOME="$AGENT_TEMPDIRECTORY/codex-home"
export TMPDIR="$AGENT_TEMPDIRECTORY/codex-security"
export HEAD_REVISION="$SYSTEM_PULLREQUEST_SOURCECOMMITID"
export BASE_REVISION="$(git merge-base HEAD^1 "$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."
displayName: Review code changes
condition: and(succeeded(), ne(variables['System.PullRequest.IsFork'], 'True'))
env:
CODEX_SECURITY_API_KEY: $(CODEX_SECURITY_API_KEY)
- publish: $(Agent.TempDirectory)/codex-security/codex-security-scans
artifact: codex-security-review
condition: always()對於 Azure Repos,請設定 Build validation branch policy,使該 pipeline 在 pull request 上執行。
pipeline {
agent { label 'linux' }
stages {
stage('Codex Security review') {
when {
allOf {
changeRequest()
expression { !env.CHANGE_FORK?.trim() }
}
}
steps {
sh '''#!/usr/bin/env bash
set -euo pipefail
export CODEX_HOME="/tmp/codex-home-$BUILD_TAG"
export TMPDIR="/tmp/codex-security-$BUILD_TAG"
mkdir -p "$TMPDIR"
git fetch --no-tags origin "$CHANGE_TARGET"
target="$(git rev-parse FETCH_HEAD)"
git fetch --no-tags origin "$CHANGE_BRANCH"
git rev-parse FETCH_HEAD > "$TMPDIR/head"
git merge-base "$target" "$(cat "$TMPDIR/head")" > "$TMPDIR/base"
npm install --global @openai/codex
codex plugin add codex-security@openai-curated
'''
withCredentials([string(credentialsId: 'codex-security-api-key', variable: 'CODEX_SECURITY_API_KEY')]) {
sh '''#!/usr/bin/env bash
set +x
set -euo pipefail
export CODEX_HOME="/tmp/codex-home-$BUILD_TAG"
export TMPDIR="/tmp/codex-security-$BUILD_TAG"
export HEAD_REVISION="$(cat "$TMPDIR/head")"
export BASE_REVISION="$(cat "$TMPDIR/base")"
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."
'''
}
}
post {
always {
sh '''#!/usr/bin/env bash
set -euo pipefail
scan_root="/tmp/codex-security-$BUILD_TAG/codex-security-scans"
if [ -d "$scan_root" ]; then
tar -czf codex-security-artifacts.tar.gz -C "$scan_root" .
fi
'''
archiveArtifacts artifacts: 'codex-security-artifacts.tar.gz', allowEmptyArchive: true
}
}
}
}
} 這些範例會跳過來自 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)