如需查看完整的文档索引,请参阅 llms.txt。在文档页面的 URL 末尾加上 .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"

    相关使用场景