ローカルの未コミット変更のレビュー

CLI では、リポジトリとセキュリティポリシーに関するコンテキストをあらかじめ渡して、ローカルの未コミット変更をレビューできます。

以下の例は、Git でチェックアウトしたリポジトリ内で、同じシェルを使って実行してください。セキュリティポリシーは 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"