ci-security-scanning-with-strix

在 CI/CD 中设置 Strix

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

• 托管平台（推荐大多数团队使用）——只需连接一次 GitHub/GitLab/Bitbucket 应用，Strix 就会审核每个 PR，无需工作流文件、运行器、Docker 或 LLM 密钥。结果会作为 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

然后告知用户添加两个仓库密钥：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/${{ github.base_ref }}，不要硬编码为 origin/main，因为不同仓库的默认分支可能不同。
• 退出码：0 表示通过，2 表示发现漏洞（任务失败），1 表示设置错误。添加 --fail-on high，仅在发现高危／严重问题时失败；低级别问题仍会报告，因此任务通过并不意味着报告中没有发现。
• 运行器需要 Docker（默认的 GitHub 托管 Ubuntu 运行器已安装 Docker）。
• 合理设置预算，确保扫描完成——不要让扫描静默放行。 退出码为 0 表示“在已分析的范围内未发现已验证的漏洞”；如果在完整覆盖差异之前就达到 --max-budget，扫描会提前结束，但仍可能以 0 退出。上面的“Fail unless the scan completed”步骤可以缩小这一风险：如果扫描在硬性预算上限处被截断，且没有生成最终报告，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, 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 密钥。有三种使用方式：

1. **PR 审查应用（零代码）：**用户安装 Strix GitHub/GitLab/Bitbucket 应用，并在 app.strix.ai 控制面板中为仓库启用 PR 审查。之后，每个 PR 都会自动接受审查，发现的问题会以 PR 评论的形式发布。无需向仓库添加任何内容。这是工作量最低的方式——如果用户只想对 PR 进行门禁检查，建议优先推荐此方式。

2. **从任意流水线通过 CLI 触发：**如果要从现有流水线触发（或使用未安装 SCM 应用的系统），请使用同一个 strix 二进制文件，并配备具有 pr_reviews:write 权限的令牌。将令牌存储为 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 权限）。两步摘要交接流程可让人工控制哪些内容会离开运行器：

   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。