For the complete documentation index, see llms.txt. Markdown versions of documentation pages are available by appending .md to the page URL.
主导航

对代码更改进行安全审查

手动或在 CI/CD 中审查 Pull Request 和本地更改,查找安全回归问题。

对 Git 管理的单个变更集运行安全审查,以发现安全回归问题。 Codex 会审查每个已更改的源代码类文件,以及直接支持该文件的代码。 审查不会扩大为对整个代码仓库的全面审计。

若要扫描整个代码仓库而非特定更改,请参阅运行安全 扫描

手动运行审查

在桌面应用中,打开 安全,选择 扫描,再选择 + 扫描。 选择代码仓库,然后选择 更改。您可以审查未提交的更改、 单个提交,或基准修订版本和目标修订版本。 深度扫描 不适用于 更改扫描。

您还可以在对话中让 Codex 审查未提交的更改:

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

对于提交范围或分支范围,必要时请同时指定两个修订版本:

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 的基准修订版本和目标修订版本在本地检出中均可用, 您也可以指定该 Pull Request。

在设置中确认更改

  1. 选择 更改
  2. 确认已检出的代码仓库、当前分支和最新提交。
  3. 待审查的更改中,选择以下内容:
    • Uncommitted changes,用于当前工作树。
    • 最新提交,用于审查单个提交。
    • 基准修订版本和目标修订版本,用于审查分支或 Pull Request 范围。
  4. 确认摘要描述的是您打算审查的更改。
  5. 选择 开始扫描

Codex 不会检出其他分支,也不会切换选定的工作树。如果 所需修订版本在本地不可用,请在审查前获取该版本,或者 提供本地可用的基准修订版本和目标修订版本。

处理发现项

审查结果后,修复并验证已接受的 发现项,或导出并跟踪 发现项

在 CI/CD 中自动执行审查

如果您可以使用测试版独立 CLI,请参阅在 CI 中 运行 Codex Security,了解结构化 JSON、严重程度策略和 SARIF 上传。请继续阅读本节,了解如何通过 codex exec 调用已安装的插件技能。

当运行器能够以非交互方式调用 Codex CLI 时,请在 CI 中运行 $codex-security:security-diff-scan。 首先,请在不暴露扫描凭据的情况下 安装 CLI:

npm install --global @openai/codex

在 CLI 中安装 Codex Security 插件:

codex plugin add codex-security@openai-curated

该安装命令使用公开的 Codex CLI 插件市场。 请先查看插件更新日志,再在 CI 中 依赖特定插件版本或功能。

接下来,请将 CI 机密存储中的 OpenAI API 密钥作为 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."

可写沙盒允许扫描创建临时工件。提示 仍要求 Codex 保持已检出的源代码不变。

扫描会将输出写入 $TMPDIR/codex-security-scans/<repository>/<scan-id>/

文件内容
report.md查看完整扫描目录的主要可读入口。
findings/<slug>/按需提供详细的漏洞报告及配套的概念验证文件。
hardening/按需提供结构性加固指南及配套方案。
findings.json包含稳定标识符、严重程度、置信度、源代码位置和修复措施的发现项。将这些发现项提供给经批准的内部安全工作流或下游工具。
scan-manifest.json密封的扫描回执,包含审查目标、修订版本和工件哈希。
coverage.json已审查和暂缓审查的范围、排除项以及覆盖完整性。

findings.json 模式 定义了完整结构。该模式包含以下字段:

字段类型说明
documentType字符串将文档标识为 codex-security.findings
schemaVersion字符串标识发现项模式的版本。
scanId字符串标识生成这些发现项的扫描。
findings数组包含零个或多个发现项对象。
findings[].findingId字符串根据发现项指纹派生的稳定发现项标识符。
findings[].occurrenceId字符串标识该发现项在特定扫描中的本次出现。
findings[].ruleId字符串标识漏洞家族。
findings[].identity对象包含语义锚点和可选的同级实例标识符。
findings[].fingerprints对象包含指纹算法和主指纹。
findings[].title字符串提供简短的发现项标题。
findings[].summary字符串概述漏洞及其影响。
findings[].severity对象包含严重性级别和可选的评分详情。
findings[].confidence对象包含置信度级别和判断依据。
findings[].taxonomy对象包含漏洞类别和 CWE 标识符。
findings[].locations数组列出受影响的文件、行号和位置角色。
findings[].remediation字符串说明建议的修复方法。
findings[].provenance对象标明发现项的来源。

例如,以下命令会为每个发现项打印一行以制表符分隔的数据:

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

这些示例假定使用受信任的 Linux 运行器,其中安装了 Node.js 和 npm、Git、Python 3、jq 以及相应提供商的命令行工具。npm 的全局软件包前缀 必须可写。

请选择与您的 CI 提供商对应的示例:

扫描结果可能包含敏感的漏洞详情。请确保构件 不公开,并仅在审查发布对象、内容和 所需审批后发布发现项。

选择一个选项
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

这些示例会跳过来自派生代码仓库的 Pull Request。仅可基于 受保护的流水线定义运行需要凭证的作业,并且只能为受信任且可接触扫描 凭证的贡献者运行此类作业。请归档 codex-security-scans,将结构化发现项、 清单、覆盖范围和 report.md 一并保存,并包含任何已请求的 findings/hardening/ 输出。初期请将结果仅作为参考,并审查 覆盖范围和运行时间,再将该作业设为必需检查项。

有关 API 密钥处理和沙盒控制,请参阅非交互 模式。如果您的组织允许使用 Codex GitHub Action,它可以在运行时安装 CLI,但 您仍须先安装插件,并将该 GitHub Action 的 codex-home 输入指向同一个 CODEX_HOME