第 2 章 · 01 CLI 参考

第 2 章 · 01 CLI 参考

本节摘要:本节是 Strix 命令行接口(CLI)的完整参考。基本用法是 strix (--target | --target-list | --mount) [options]——必须至少有一个目标来源。本节逐一讲解所有参数:目标类(--target/--target-list/--mount)、指令类(--instruction/--instruction-file)、深度类(--scan-mode/--scope-mode/--diff-base)、运行类(--non-interactive/--config/--max-budget/--max-turns),并给出常见用法示例与退出码含义。

内容来源:原项目文档 docs/usage/cli.mdx,汉化并套用体系化模板。

⚠️ 仅限授权测试:所有命令仅用于测试你自己的应用或有书面授权的目标。

学习目标

阅读完本节,你应当能够:

1. 写出 Strix 的基本调用形式与「至少一个目标来源」的硬要求。
2. 区分三类目标参数(--target/--target-list/--mount)及何时用 --mount。
3. 用 --instruction / --instruction-file 给 Strix 凭据与关注点。
4. 选对 --scan-mode(quick/standard/deep)与 --scope-mode(auto/diff/full)。
5. 用 --max-budget 与 --max-turns 控制成本与轮次。
6. 用 --non-interactive 跑 CI/CD 无头模式。
7. 根据退出码判断扫描结果。

一、基本用法

strix (--target <target> | --target-list <path> | --mount <path>) [options]
​

Strix 的参数可分为四大类,下图给出全局视图:

strix ──┬─ 目标类   ── --target / --target-list / --mount   (至少一个)
        ├─ 指令类   ── --instruction / --instruction-file   (引导关注点)
        ├─ 深度类   ── --scan-mode / --scope-mode / --diff-base  (深度+范围)
        └─ 运行类   ── --non-interactive / --config
                     ── --max-budget / --max-turns          (成本+轮次控制)
                                                            ↓
                                                         退出码 0/1/2
​

⚠️ 硬要求:每次新跑至少要有一个目标来源——--target、--target-list 或 --mount。三者可组合使用(如多个 --target + 一个 --target-list)。

二、目标类参数

--target, -t(字符串,可重复)

要测试的目标。接受 URL、仓库、本地目录、域名或 IP 地址。可多次指定。

--target-list(字符串,可重复)

指向一个目标文件的路径,每行一个非空、非注释行(# 开头被忽略)。可与 --target 组合。

--mount(字符串,可重复)

把一个本地目录绑定挂载进沙箱(只读),而非逐文件复制进去。用于太大、无法流式传入容器的大型仓库,可多次指定。

💡 何时用 --mount:Strix 默认把本地 --target 目录逐文件复制进沙箱,在超大文件树上会卡住。当本地目标超过复制上限(见 STRIX_MAX_LOCAL_COPY_MB,默认 1024 MB)时,Strix 会提前退出并提示你用 --mount 重跑。

⚠️ 安全注意:--mount 是只读的,保护源码不被意外修改。但这不是硬安全边界——容器内的 root 进程能重新挂载为可写。所以把 --mount 当作「扫描我自己的代码」,而非「隔离不受信代码」。

大小预检只覆盖本地目录目标;远程仓库(扫描时克隆)不做大小检查。

三、指令类参数

--instruction(字符串)

扫描的自定义指令。用于提供凭据、关注区域或特定测试方法。

--instruction-file(字符串)

指向一个含详细指令的文件的路径。

💡 指令的完整用法(认证测试、范围聚焦、排除项、API 测试)见本章 03 节「自定义指令」。

四、深度类参数

--scan-mode, -m(字符串,默认 deep)

扫描深度:quick、standard 或 deep。三种模式的深度与耗时对比见本章 02 节。

--scope-mode(字符串,默认 auto)

代码范围模式:

• auto:在 CI/无头运行中启用 PR diff 范围
• diff:强制变更文件范围
• full:禁用 diff 范围(全量扫)

--diff-base(字符串)

要对比的目标分支或提交(如 origin/main)。默认为仓库的默认分支。

💡 diff 范围是 CI/CD 场景的关键——只扫变更文件能大幅缩短耗时,把安全检查塞进 PR 流程而不拖慢迭代。auto 会自动判断是否在 CI/无头环境。

五、运行类参数

--non-interactive, -n(布尔)

以无头模式运行,不带 TUI。适合 CI/CD。

--config(字符串)

指向自定义配置文件(JSON)的路径,替代默认的 ~/.strix/cli-config.json。

--max-budget(数字)

整次扫描的最大 LLM 花费(美元),跨根代理与所有子代理累计计算。预算在每次模型响应后检查。

无头模式(-n):运行成本达到阈值时,扫描以 stopped 状态(非失败)干净停止,沙箱被拆除。子代理提前在 90% 预算处停止,留最后一段给根代理收尾并产出最终报告。

交互模式:达到预算会暂停而非结束——所有代理停靠,发送任意消息即恢复扫描,上限按原预算金额延展。交互模式无子代理预留。

渐进式收尾警告:接近预算时,分级警告会推给每个代理,让它们能在硬停前完成工作并调用生命周期工具。警告带位于各角色自身停止点之下:根代理在 70%、85%、95% 警告(100% 停止),子代理在 75%、80%、85% 警告(90% 预留处停止)。交互模式下所有代理用 70%、85%、95% 带。警告中显示的百分比是相对完整预算的真实累计花费。

必须大于 0。省略该标志则无限制。

⚠️ 限制:检查在响应返回之后触发,故最终花费可能因阈值跨越时已在途中的调用而略超(并发子代理多时最明显);花费是基于 token 用量与模型定价的最佳估计;对 LiteLLM 路由的模型,Strix 启用流式成功回调以捕获 provider 报告的成本(消息内容仍被排除,但同进程配置的第三方 LiteLLM 回调可能收到模型名、请求 ID、token 数等流式元数据)。

--max-turns(整数,默认 500)

分配给每个代理的最大轮次(一次模型响应加其工具轮),按运行计。代理达到此限制即被强制停止。

接近限制时,分级收尾警告(70%、85%、95%)注入该代理的下一个模型轮,让它优先处理剩余工作并在硬停前调用生命周期工具(根代理的 finish_scan,子代理的 agent_finish)。必须大于 0。

六、常见用法示例

# 基本扫描
strix --target https://example.com

# 认证测试
strix --target https://app.com --instruction "Use credentials: user:pass"

# 聚焦测试
strix --target api.example.com --instruction "Focus on IDOR and auth bypass"

# CI/CD 模式
strix -n --target ./ --scan-mode quick

# 控制成本与每代理轮次
strix --target https://example.com --max-budget 25 --max-turns 300

# 强制 diff 范围,对比指定 base
strix -n --target ./ --scan-mode quick --scope-mode diff --diff-base origin/main

# 多目标白盒测试
strix -t https://github.com/org/app -t https://staging.example.com

# 从文件读目标
strix --target-list ./targets.txt

# 大型本地仓库——绑定挂载而非复制
strix --mount ./huge-monorepo
​

七、退出码

💡 CI/CD 集成的关键:无头模式下,退出码 2 可直接用作 CI 门禁——「发现漏洞则阻断合并」。配合 --scan-mode quick + --scope-mode diff,即可在 PR 上做快速、聚焦的安全检查。这部分在第 4 章的集成节详讲。

本节要点回顾

1. 基本形式:strix (--target | --target-list | --mount) [options],至少一个目标来源是硬要求。
2. 三类目标:--target(URL/仓库/目录/域名/IP,可重复)、--target-list(文件,每行一个)、--mount(大型仓库绑定挂载,只读,超过 1024 MB 默认上限时用)。
3. 指令类:--instruction(内联)与 --instruction-file(文件),给凭据与关注点。
4. 深度类:--scan-mode(quick/standard/deep,默认 deep)、--scope-mode(auto/diff/full,默认 auto)、--diff-base(对比的分支/提交)。
5. 运行类:--non-interactive(无头,CI/CD)、--config(自定义 JSON 配置)、--max-budget(累计花费上限,分级警告)、--max-turns(每代理轮次上限,默认 500)。
6. 预算行为差异:无头模式达阈值 stopped 干净停止(子代理 90% 预留);交互模式达阈值暂停,发消息恢复并延展上限。
7. 退出码:0(成功/无漏洞)、1(致命错误)、2(发现漏洞,仅无头);2 可作 CI 门禁。

下一节,我们对比三种扫描模式(quick/standard/deep)的深度、耗时与适用场景,帮你选对模式。