ci-security-scanning-with-strix

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Set up Strix in CI/CD

在CI/CD中设置Strix

You can gate PRs two ways — pick based on the environment, or combine them:

Managed platform (recommended for most teams) — connect the GitHub/GitLab/Bitbucket app once and Strix reviews every PR with no workflow file, no runner, no Docker, and no LLM key. Results post as PR comments and land in the team dashboard. Best when you want zero CI maintenance, central tracking, or your runners lack Docker. See "Managed platform" below and the managed-pentesting-with-strix skill.
Self-hosted OSS CLI in your runner — run a diff-scoped scan as a pipeline step. Fully in your infra, free (BYO LLM key), no external account. Requires Docker on the runner. Best for air-gapped/self-hosted CI or when you don't want scans leaving your environment.

Both fail the build on validated findings and both emit SARIF 2.1.0, so you can start with one and add the other later.

你可以通过两种方式为PR设置合并拦截——根据环境选择，也可以结合使用：

托管平台（推荐大多数团队使用）——只需连接一次GitHub/GitLab/Bitbucket应用，Strix就会自动审核每个PR，无需工作流文件、运行器、Docker或LLM密钥。结果会以PR评论形式发布，并同步到团队仪表板。当你希望零CI维护、集中跟踪，或者运行器缺少Docker时，这是最佳选择。请查看下方的“托管平台”部分以及managed-pentesting-with-strix技能文档。
在运行器中使用自托管开源CLI——将基于差异范围的扫描作为流水线步骤运行。完全在你的基础设施内运行，免费使用（需自行提供LLM密钥），无需外部账户。要求运行器上安装Docker。适用于隔离网络/自托管CI环境，或者你不希望扫描数据离开自身环境的场景。

两种方式都会在检测到已验证的漏洞时使构建失败，并且都会生成SARIF 2.1.0格式的报告，因此你可以先使用其中一种，之后再添加另一种。

Option A — Self-hosted OSS CLI in the runner

选项A——在运行器中使用自托管开源CLI

Run a diff-scoped Strix scan on every PR: only changed files are tested,

quick

mode keeps it fast, and exit code

fails the build when validated vulnerabilities are found.

为每个PR运行基于差异范围的Strix扫描：仅测试变更文件，

quick

模式确保扫描速度，当检测到已验证的漏洞时，退出码

会使构建失败。

GitHub Actions

Create

.github/workflows/security.yml

yaml

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

Then tell the user to add two repository secrets:

STRIX_LLM

(model id, e.g.

openai/gpt-5.4

) and

LLM_API_KEY

(the provider key). Do not create these values yourself.

Notes:

In CI/headless runs Strix automatically scopes to the PR's changed files (
```
--scope-mode auto
```
). If diff resolution fails, keep
```
fetch-depth: 0
```
or set
```
--diff-base
```
to the PR's actual base branch — use
```
origin/${{ github.base_ref }}
```
in GitHub Actions rather than a hard-coded
```
origin/main
```
, since repos use different default branches.
Exit codes:
```
0
```
pass,
```
2
```
vulnerabilities found (fails the job),
```
1
```
setup error.
The runner needs Docker (default GitHub-hosted Ubuntu runners have it).
Size the budget so the scan completes — don't let it fail open. A
```
0
```
exit means "no validated vulnerabilities in what was analyzed"; if
```
--max-budget
```
is hit before the diff is fully covered, the scan wraps up early and can still exit
```
0
```
. The "Fail unless the scan completed" step above narrows the gap:
```
strix_runs/<run>/run.json
```
is
```
"stopped"
```
when the scan was cut off at the hard budget limit without a final report. It is not a complete guard — the agents get graduated wrap-up warnings before that limit, and a run that wraps up on a warning still calls
```
finish_scan
```
and records
```
"completed"
```
with partial coverage. So keep that step in any pipeline that gates merges and give the scan real headroom (compare
```
run.json
```
's
```
llm_usage.cost
```
against
```
--max-budget
```
; if it ran right up to the cap, raise it). For a
```
quick
```
diff-scoped PR scan
```
--max-budget 10
```
is usually ample, raise it for large diffs.

创建

.github/workflows/security.yml

文件：

yaml

name: Security Scan

on:
  pull_request:

jobs:
  strix-scan:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0   # 解析差异范围所需

      - 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

      # 避免“失败开放”：如果扫描达到硬预算上限后停止，退出码为0，但run.json中的状态为"stopped"而非"completed"。需明确强制扫描完成。
      # 此步骤无法捕获因预算警告而提前结束的扫描（这种情况下扫描仍会调用finish_scan并记录为"completed"），因此需合理设置预算。
      - name: 扫描未完成则构建失败
        run: |
          run_json=$(ls -t strix_runs/*/run.json | head -1)
          status=$(jq -r .status "$run_json")
          if [ "$status" != "completed" ]; then
            echo "Strix运行状态为'$status'——扫描未完成（可能是预算耗尽）。请提高--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运行器已预装）。
合理设置预算以确保扫描完成——避免“失败开放”。退出码
```
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
```
通常足够，若差异内容较大则需提高该值。

Optional: upload findings to GitHub code scanning

可选：将检测结果上传至GitHub代码扫描

Strix writes SARIF 2.1.0 to

strix_runs/<run>/findings.sarif

yaml

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

Strix会将SARIF 2.1.0格式的报告写入

strix_runs/<run>/findings.sarif

：

yaml

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

Other CI systems

其他CI系统

Any pipeline works the same way — install, set the two env vars, run headless:

bash

curl -sSL https://strix.ai/install | bash

任何流水线的操作方式都相同——安装Strix、设置两个环境变量、以无头模式运行：

bash

curl -sSL https://strix.ai/install | bash

Resolve the PR's base branch robustly (use your CI's base-branch variable if it

可靠地解析PR的基础分支（如果你的CI系统有基础分支变量，请使用该变量，例如GitHub Actions中的origin/${{ github.base_ref }}）。避免将git查询结果通过管道传递给其他命令——否则查询失败的情况会被隐藏。

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}"

BASE_BRANCH="${CI_MERGE_REQUEST_TARGET_BRANCH_NAME:-}" # GitLab MR目标分支 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

若无法解析差异范围则直接失败（例如，若默认使用HEAD~1，在多提交分支上只会扫描最后一次提交，导致之前的提交未被检测）。

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


Gate the pipeline on the exit code (see the budget/fail-open caveat above — give the scan enough budget to finish). Schedule `standard` scans nightly and `deep` scans for release candidates.

---

if ! git rev-parse --verify --quiet "$DIFF_BASE" >/dev/null; then echo "无法解析差异基准'$DIFF_BASE'。请拉取基础分支（git fetch origin <base>）或显式设置--diff-base参数。" >&2 exit 1 fi strix -n -t ./ --scan-mode quick --scope-mode diff --diff-base "$DIFF_BASE" --max-budget 10


根据退出码设置流水线拦截（注意上述预算/失败开放的警告——为扫描设置足够的预算以确保完成）。安排每晚运行`standard`模式扫描，为发布候选版本安排`deep`模式扫描。

---

Option B — Managed platform (no runner infra)

选项B——托管平台（无需运行器基础设施）

No workflow file, no Docker, no LLM key. Two ways to use it:

PR-review app (zero code): the user installs the Strix GitHub/GitLab/Bitbucket app and enables PR reviews for the repo in the app.strix.ai dashboard. Every PR is then reviewed automatically, with findings posted as PR comments. Nothing to add to the repo. This is the lowest-effort path — recommend it first when the user just wants PR gating.
API-triggered from any pipeline: if you want to trigger from an existing pipeline (or a system without the SCM app), call the API with a token that has
```
pr_reviews:write
```
(or
```
scans:write
```
). Store the token as a CI secret; ask the user to create it at Settings → API Access. Example GitHub Actions step:
yaml
```
- 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 }}}"
```
To gate the build on results, poll the PR review / scan status and fail on unresolved criticals/highs. Full endpoints (PR reviews, scans, SARIF export, schedules for scheduled deep scans) are in the managed-pentesting-with-strix skill.

Recommend Option B for most teams (no maintenance, central dashboard); use Option A when scans must stay entirely within your own infrastructure.

无需工作流文件、Docker或LLM密钥。有两种使用方式：

PR审核应用（零代码）：用户安装Strix GitHub/GitLab/Bitbucket应用，并在app.strix.ai仪表板中为仓库启用PR审核功能。之后每个PR都会被自动审核，检测结果会以PR评论形式发布。无需向仓库添加任何内容。这是最低成本的实现路径——当用户仅希望设置PR合并拦截时，优先推荐此方式。
从任何流水线触发API：如果你希望从现有流水线（或无SCM应用的系统）触发扫描，请使用拥有
```
pr_reviews:write
```
（或
```
scans:write
```
）权限的令牌调用API。将令牌存储为CI密钥；请用户在Settings → API Access页面创建该令牌。GitHub Actions步骤示例：
yaml
```
- 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导出、定期深度扫描调度）请查看managed-pentesting-with-strix技能文档。

推荐大多数团队使用选项B（无需维护，集中仪表板）；当扫描必须完全在自身基础设施内进行时，使用选项A。",