Codex 使用场景
通过 CLI 执行安全审查
在终端中审查选定的代码变更,并查看相关安全证据。
使用 Codex Security CLI 审查尚未提交的变更或分支上的变更。
最适合
- 在终端中检查本地变更或分支变更的开发者。
- 评估单体代码仓库中特定服务、软件包及其使用方的应用安全团队。
- 对照代码仓库中的代码调查现有 GitHub 代码扫描警报的工程师。
目录
通过 CLI 执行安全审查
在终端中审查选定的代码变更,并查看相关安全证据。
使用 Codex Security CLI 审查尚未提交的变更或分支上的变更。
使用 Codex Security CLI 审查尚未提交的变更或分支上的变更。
最适合
- 在终端中检查本地变更或分支变更的开发者。
- 评估单体代码仓库中特定服务、软件包及其使用方的应用安全团队。
- 对照代码仓库中的代码调查现有 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" 相关使用场景
使用 GitHub Actions 创建自定义审查工作流
将安全审查纳入开发流程,以便重复执行。配置 GitHub Actions 工作流,让 Codex Security 检查拟议的代码变更,并保存结果供您的团队查看。
在 CI 中自动运行安全扫描
将 Codex Security CLI 添加到您的 CI 流水线中。选择何时扫描、审查哪些代码,保留扫描发现的问题及扫描覆盖范围的记录,并决定扫描结果如何影响交付流程。
在 CI/CD 中管理供应链风险
使用 Codex Security CLI 评估第三方依赖项对应用安全性的影响。对 Dependabot 警报进行分级和验证,并在引入或更新软件包时运行安全扫描。