strix-ci-setup

在 CI/CD 中设置 Strix

你可以通过两种方式为 PR 设置门禁——根据环境选择一种，也可以组合使用：

• 托管平台（推荐大多数团队使用） — 只需连接一次 GitHub/GitLab/Bitbucket 应用，Strix 就会审核每个 PR，无需工作流文件、运行器、Docker 或 LLM 密钥。结果会作为 PR 评论发布，并显示在团队仪表板中。适合希望免去 CI 维护、集中跟踪，或运行器没有 Docker 的团队。请参阅下文的“托管平台”和 strix-cloud-api skill。
• 在运行器中运行自托管 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

然后告知用户添加两个仓库机密：STRIX_LLM（模型 ID，例如 openai/gpt-5.4）和 LLM_API_KEY（提供商密钥）。不要自行创建这些值。

注意：

• 在 CI/无头运行中，Strix 会自动将范围限定为 PR 的已更改文件（--scope-mode auto）。如果差异解析失败，请保留 fetch-depth: 0，或将 --diff-base 设为 PR 的实际基准分支——在 GitHub Actions 中使用 origin/${{ github.base_ref }}，不要硬编码为 origin/main，因为不同仓库使用的默认分支可能不同。
• 退出代码：0 表示通过，2 表示发现漏洞（作业失败），1 表示设置错误。
• 运行器需要 Docker（默认的 GitHub 托管 Ubuntu 运行器已安装 Docker）。
• 合理设置预算，确保扫描完成——不要让扫描在未完成时仍然通过。 退出代码 0 表示“在已分析内容中没有发现经过验证的漏洞”；如果在完整覆盖差异前触及 --max-budget，扫描会提前结束，但仍可能以 0 退出。上面的“除非扫描已完成，否则失败”步骤可以缩小这一风险：当扫描在硬性预算限制下被截断且未生成最终报告时，strix_runs/<run>/run.json 中的状态会是 "stopped"。但这并非完整的防护——在触及限制前，Agent 会收到逐步升级的结束警告；如果扫描在收到警告后结束，仍会调用 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 系统

任何流水线都可以采用相同方式运行——安装、设置两个环境变量，然后以无头模式运行：

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, e.g. 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 (e.g. 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 或大模型密钥。有两种使用方式：

1. **PR 审查应用（零代码）：**用户安装 Strix GitHub/GitLab/Bitbucket 应用，并在 app.strix.ai 控制面板中为仓库启用 PR 审查。之后，系统会自动审查每个 PR，并将发现的问题作为 PR 评论发布。无需向仓库添加任何内容。这是最省力的方式 — 如果用户只想为 PR 设置门禁，优先推荐此方式。

2. **从任意流水线通过 API 触发：**如果你想从现有流水线触发（或使用没有 SCM 应用的系统），请使用具有 pr_reviews:write（或 scans:write）权限的令牌调用 API。将令牌存储为 CI 密钥；请用户前往 Settings → API Access 创建令牌。GitHub Actions 步骤示例：

   - name: Strix PR review (managed)
     if: github.event_name == 'pull_request'
     env:
       STRIX_API_TOKEN: ${{ secrets.STRIX_API_TOKEN }}
     run: |
       curl -sS --fail https://app.strix.ai/api/v1/pr-reviews/start \
         -H "Authorization: Bearer $STRIX_API_TOKEN" \
         -H "Content-Type: application/json" \
         -d "{\"repository_full_name\":\"${{ github.repository }}\",\"pr_number\":${{ github.event.pull_request.number }}}"
   

   若要根据结果设置构建门禁，请轮询 PR 审查 / 扫描状态，并在存在未解决的严重 / 高危问题时使构建失败。完整端点（PR 审查、扫描、SARIF 导出、定时深度扫描的计划任务）请参阅 strix-cloud-api 技能。

大多数团队建议使用选项 B（无需维护，且有集中式控制面板）；当扫描必须完全留在你自己的基础设施内时，使用选项 A。