中文

评审代码变更的安全性

对一个由 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