ci-security-scanning-with-strix

CI/CD で Strix をセットアップする

PR をゲートする方法は 2 つあります。環境に応じて選ぶか、組み合わせて使用してください。

• マネージドプラットフォーム（ほとんどのチームにおすすめ） — GitHub／GitLab／Bitbucket アプリを一度接続すれば、Strix がワークフローファイル、ランナー、Docker、LLM キーなしですべての PR をレビューします。結果は PR のコメントとして投稿され、チームダッシュボードに反映されます。CI のメンテナンスをなくしたい場合、一元管理したい場合、またはランナーに Docker がない場合に最適です。以下の「マネージドプラットフォーム」と managed-pentesting-with-strix スキルを参照してください。
• ランナーでセルフホストする OSS CLI — パイプラインのステップとして、差分を対象としたスキャンを実行します。すべて自社のインフラ内で完結し、無料（LLM キーは持ち込み）で、外部アカウントも不要です。ランナーに Docker が必要です。エアギャップ環境／セルフホスト型 CI、またはスキャンを環境外に持ち出したくない場合に最適です。

どちらも検証済みの検出結果があるとビルドを失敗させ、SARIF 2.1.0 を出力するため、まず一方を導入し、あとからもう一方を追加できます。

---

オプション A — ランナーでセルフホストする OSS CLI

すべての PR で、差分を対象とした Strix スキャンを実行します。変更されたファイルのみをテストし、quick モードで高速に実行します。検証済みの脆弱性が見つかった場合は、終了コード 2 によりビルドが失敗します。

GitHub Actions

.github/workflows/security.yml を作成します。

name: Security Scan

on:
  pull_request:

jobs:
  strix-scan:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0   # required for diff-scope resolution

      - name: Install Strix
        run: curl -sSL https://strix.ai/install | bash

      - name: Run Security Scan
        env:
          STRIX_LLM: ${{ secrets.STRIX_LLM }}
          LLM_API_KEY: ${{ secrets.LLM_API_KEY }}
        run: strix -n -t ./ --scan-mode quick --max-budget 10

      # Don't fail open: a run that hits the hard budget stop exits 0 but leaves
      # run.json status "stopped", not "completed". Enforce completion explicitly.
      # This does not catch an agent that wrapped up early on a budget *warning*
      # (it still calls finish_scan and records "completed"), so size the budget.
      - name: Fail unless the scan completed
        run: |
          run_json=$(ls -t strix_runs/*/run.json | head -1)
          status=$(jq -r .status "$run_json")
          if [ "$status" != "completed" ]; then
            echo "Strix run status is '$status' — the scan did not complete (likely budget exhausted). Raise --max-budget." >&2
            exit 1
          fi

次に、ユーザーに 2 つのリポジトリシークレットを追加するよう伝えてください。STRIX_LLM（モデル ID。例：openrouter/z-ai/glm-5.3）と LLM_API_KEY（プロバイダーのキー）です。これらの値を自分で作成しないでください。

注意事項：

• CI／ヘッドレス実行では、Strix は PR で変更されたファイルに自動的にスコープを絞ります（--scope-mode auto）。差分の解決に失敗する場合は、fetch-depth: 0 を指定するか、--diff-base に PR の実際のベースブランチを設定してください。GitHub Actions では、リポジトリごとにデフォルトブランチが異なるため、固定の origin/main ではなく origin/${{ github.base_ref }} を使用してください。
• 終了コード：0 は成功、2 は脆弱性が見つかった場合（ジョブが失敗）、1 はセットアップエラーです。重大度が高またはクリティカルの検出結果がある場合にのみ失敗させるには、--fail-on high を追加します。それより低い重大度の検出結果も報告されるため、ジョブが成功しても検出結果がないとは限りません。
• ランナーには Docker が必要です（デフォルトの GitHub ホステッド Ubuntu ランナーにはインストールされています）。
• スキャンが完了するように予算を設定してください。スキャンを失敗時に成功扱いにしないでください。 終了コード 0 は、「解析した範囲内に検証済みの脆弱性がなかった」ことを意味します。差分全体をカバーする前に --max-budget に達すると、スキャンは早期に終了し、それでも終了コード 0 になる可能性があります。上記の「スキャンが完了しない限り失敗させる」ステップを追加すると、この問題を軽減できます。最終レポートなしでハード予算上限に達して打ち切られた場合、strix_runs/<run>/run.json は "stopped" になります。ただし、これだけで完全に防げるわけではありません。その上限に達する前にエージェントには段階的に終了警告が表示されます。また、警告を受けて終了した実行は finish_scan を呼び出し、カバレッジが部分的でも "completed" として記録されます。そのため、マージをゲートするパイプラインではこのステップを必ず含め、スキャンに十分な余裕を持たせてください（run.json の llm_usage.cost と --max-budget を比較し、上限近くまで実行されていた場合は予算を引き上げます）。quick モードで差分を対象とした PR スキャンを行う場合、通常 --max-budget 10 で十分ですが、差分が大きい場合は引き上げてください。

オプション：検出結果を GitHub code scanning にアップロードする

Strix は SARIF 2.1.0 を strix_runs/<run>/findings.sarif に出力します。

      - name: Upload SARIF
        if: always()
        uses: github/codeql-action/upload-sarif@v3
        with:
          sarif_file: strix_runs

その他の CI システム

どのパイプラインでも手順は同じです。インストールし、2 つの環境変数を設定して、ヘッドレスモードで実行します。

curl -sSL https://strix.ai/install | bash
# Resolve the PR's base branch robustly (use your CI's base-branch variable if it
# has one, for example GitHub Actions: origin/${{ github.base_ref }}). Avoid piping the
# git lookup into another command — a failed lookup would otherwise be masked.
BASE_BRANCH="${CI_MERGE_REQUEST_TARGET_BRANCH_NAME:-}"   # GitLab MR target
if [ -z "$BASE_BRANCH" ]; then
  BASE_BRANCH=$(git symbolic-ref --quiet --short refs/remotes/origin/HEAD 2>/dev/null)
  BASE_BRANCH="${BASE_BRANCH#origin/}"
fi
DIFF_BASE="origin/${BASE_BRANCH:-main}"
# Fail loudly rather than silently narrowing scope (for example, to HEAD~1, which on a
# multi-commit branch would scan only the last commit and let earlier ones pass).
if ! git rev-parse --verify --quiet "$DIFF_BASE" >/dev/null; then
  echo "Cannot resolve diff base '$DIFF_BASE'. Fetch the base branch (git fetch origin <base>) or set --diff-base explicitly." >&2
  exit 1
fi
strix -n -t ./ --scan-mode quick --scope-mode diff --diff-base "$DIFF_BASE" --max-budget 10

終了コードに基づいてパイプラインをゲートしてください（予算と失敗時に成功扱いにすることに関する注意点については上記を参照し、スキャンを完了できる十分な予算を設定してください）。standard スキャンは毎晩、deep スキャンはリリース候補に対してスケジュールしてください。

---

オプション B — マネージドプラットフォーム（実行環境のインフラ不要）

ワークフローファイルも、Docker も、LLM キーも不要です。利用方法は 3 つあります。

1. **PR レビューアプリ（コード不要）：**ユーザーが Strix の GitHub／GitLab／Bitbucket アプリをインストールし、app.strix.ai ダッシュボードでリポジトリの PR レビューを有効にします。その後、すべての PR が自動でレビューされ、検出結果が PR コメントとして投稿されます。リポジトリに追加するものはありません。最も手間がかからない方法です。ユーザーが PR のチェックだけを希望している場合は、最初にこちらをおすすめしてください。

2. **任意のパイプラインから CLI で実行：**既存のパイプラインから実行したい場合（または SCM アプリのないシステムの場合）は、pr_reviews:write 権限のあるトークンで同じ strix バイナリを使用します。トークンは CI シークレットとして保存し、Settings → API Access で作成するようユーザーに案内してください。strix cloud repos list でリポジトリの provider と installation_id を一度取得します。GitHub Actions のステップの例：

   - name: Strix PR review (managed)
     if: github.event_name == 'pull_request'
     env:
       STRIX_API_TOKEN: ${{ secrets.STRIX_API_TOKEN }}
     run: |
       curl -sSL https://strix.ai/install | bash
       strix cloud pr-reviews start \
         --provider github \
         --installation-id "${{ vars.STRIX_INSTALLATION_ID }}" \
         --repository-full-name "${{ github.repository }}" \
         --pr-number "${{ github.event.pull_request.number }}"
   

   stdout がターミナルでない場合、出力は JSON 形式になります。また、TTY がない場合はプロンプトが表示されません。結果に基づいてビルドを制御するには、strix cloud pr-reviews get <id> --json をポーリングし、未解決のクリティカルまたは高リスクの問題があれば失敗させます。パイプラインに CLI をインストールできない場合は、REST エンドポイント（POST /api/v1/pr-reviews/start）も使用できます。

3. **SCM アプリのないパイプラインからソースをアップロード：**チェックアウトしたツリーをクラウドコードレビューとしてアップロードします（scans:write と uploads:write が必要です）。2 段階のダイジェスト引き継ぎにより、実行環境から外部に送信する内容を人が制御できます。

   strix cloud scans start --source . --dry-run --show-files --json   # review, capture source.archive_sha256
   strix cloud scans start --source . --approve-sha256 "$SOURCE_SHA256" --wait
   

   終了コード：0 は成功、4 は認証エラーまたはプラン上限、5 は支払いが必要です。Enterprise 以外のスキャンではクレジットを消費します。

CLI の全機能（PR レビュー、スキャン、SARIF エクスポート、スケジュール設定）については、managed-pentesting-with-strix スキルをご覧ください。

ほとんどのチームにはオプション B（メンテナンス不要、中央ダッシュボード）をおすすめします。スキャンを完全に自社インフラ内にとどめる必要がある場合は、オプション A を使用してください。