managed-pentesting-with-strix

Strix Cloud（托管，无需本地基础设施）

如果你想使用 Strix 的自主渗透测试，又不想自行运行 Docker 或大模型，请使用此方案——扫描将在 Strix 的基础设施上运行，结果会记录在团队仪表板中。这是沙箱化／托管的 Agent 和 CI 环境、团队以及定期／持续测试的理想选择（可下载的 PDF／DOCX 报告是 Enterprise 计划的功能）。如果要完全在本地、免费、隔离网络或使用自带大模型运行，请改用 penetration-testing-with-strix 技能中的开源 CLI——两者使用相同的引擎并生成相同的 SARIF 输出，因此可以混合使用。

两种等效的接口可供选择。建议优先使用 CLI：

• strix cloud CLI——每个 REST 操作都有一个 strix cloud <resource> <verb> 格式的命令。使用 curl -sSL https://strix.ai/install | bash 安装。运行 strix cloud 可列出所有资源，运行 strix cloud <resource> help（或 -h）可列出某个资源的动词；对于具有安全读取操作的资源，直接运行资源命令会执行其文档所述的默认操作。
• REST API——基础 URL 为 https://app.strix.ai/api/v1，每个请求都需携带 Authorization: Bearer <token>。完整参考文档：docs.app.strix.ai · Agent 索引：https://docs.app.strix.ai/llms.txt · OpenAPI：https://docs.app.strix.ai/openapi.json。

Agent 和用户都可以同样方便地使用 CLI。标准输出不是终端时，或传入 --json 时，会输出完整 JSON；终端表格则优先显示名称、分支、生命周期状态和编号选择器。人类可读的列表会保留后续命令所需的选择器，但省略内部组织／用户 ID；如果选择器过长，不适合在紧凑表格中显示，则会在可复制的代码块中完整重复显示。分页列表会显示下一页的 --page 或 --offset；详情视图会在安全的终端长度限制内保留实用说明文字；如需完整记录，请使用 --json。令牌列表会将凭据标记为有效、已过期或已撤销。二进制下载是例外：请有意重定向原始字节，或使用 --output FILE --json 写入文件并接收结构化元数据。标准输入不是终端时，不会出现交互式提示。退出代码：0 表示成功，1 表示请求／运行时错误，2 表示用法无效，4 表示身份验证失败或达到计划限制，5 表示需要付款。

每个具有安全读取操作的资源组都有实用的默认操作，-h 或 help 始终会显示其动词。本机 Tab 补全包含资源、动词、标志、工作区命令和本地路径：

source <(strix completions zsh)       # current zsh session
source <(strix completions bash)      # current bash session
strix completions fish | source       # current fish session

写入命令通过标志接收请求字段。每个写入命令也接受一个通过 --data 传入的 JSON 对象，这是发送没有对应标志的字段的方法：

strix cloud scans start --data '{"engagement_type":"code_review"}'   # literal JSON
strix cloud scans start --data @request.json                         # read a file
cat request.json | strix cloud scans start --data -                  # read standard input

平台会强制执行计划和角色限制，CLI 会原样传递平台消息。下载报告需要 Enterprise 计划。计划任务需要 Pro 计划。账单写入操作需要管理员令牌。受限命令会以代码 4 退出。

设置：登录

运行设备登录。首次使用时会创建用户账户和工作区，并将个人 API 令牌存储在 ~/.strix/platform-auth.json 中：

strix cloud login
# Non-interactive least-privilege example:
strix cloud login --scopes scans:read scans:write uploads:write billing:read vulnerabilities:read assets:read assets:write
# Or use a stable named profile:
strix cloud login --scope-profile recommended

用户在浏览器中批准登录。使用 --scopes（以及可选的 --workspace <name-or-id>）时，不会出现终端提示，因此该命令可在非交互式 Agent shell 中运行。在交互式终端中不带标志运行时，CLI 会提供工作区选择器和权限范围预设（Recommended、Full access、Minimal、Custom）。Recommended 涵盖常规扫描、源代码上传、工作区切换以及经用户批准的额度充值；它不包含 tokens:write，需要进行凭据管理时必须明确申请该权限范围。若要使用权限更窄的自动化令牌，请指定明确的权限范围。

• strix cloud whoami 可快速查看本地状态。strix cloud session --json 可验证远程设备会话；strix cloud session scopes 会显示当前生效的权限和不可更改的登录权限上限。

• strix cloud logout 会先撤销远程会话，再移除本地令牌。如果网络或服务发生故障，它会保留令牌，以便用户重试；--local-only 会有意跳过撤销操作。

• 其他所有 strix cloud 命令都会自动使用已存储的令牌。--token <token> 或 STRIX_API_TOKEN 是无状态的单命令覆盖设置，不会覆盖已存储的账户。若覆盖令牌本身是 CLI 会话，还需传入 --workspace-id 或设置 STRIX_WORKSPACE_ID。

• 切勿将令牌硬编码、记录到日志或提交。请将其存储在环境变量或 CI 密钥存储中。

• 权限范围（最小权限原则）： 仅授予集成所需的权限，并定期轮换：

  权限范围	授予的权限
  scans:read / scans:write	列出/读取/查看扫描报告 · 创建/重新运行/取消扫描
  vulnerabilities:read / :write	读取发现的问题 · 更新状态和备注
  assets:read / :write	读取域名/仓库 · 注册/更新域名和仓库
  schedules:read / :write	读取计划 · 创建/触发定期扫描
  pr_reviews:write	触发 PR 安全审查
  webhooks:read / :write	管理 webhook 订阅
  uploads:write	上传本地源代码或文档以供扫描
  organizations:read	读取组织详情（列出/切换已登录用户的工作区无需 API 权限范围）
  organizations:write	创建/更新工作区（管理员）
  tokens:write	创建/撤销普通 API 令牌（管理当前 CLI 会话无需此权限）
  knowledge:read / :write	读取/更新组织知识
  audit:read	读取/导出 Enterprise 审计日志
  billing:read / billing:write	读取额度余额和自动充值设置 · 购买额度（管理员）

HTTP 错误会映射为相应消息和退出代码：401 令牌无效/已过期（退出代码 4），402 额度不足（退出代码 5），403 权限范围/计划层级限制（退出代码 4），422 验证错误（退出代码 1）。

使用 strix cloud tokens create 创建有时限的自动化令牌。使用 --rbac-scopes 将其限制为指定的目标 ID、标签或业务单元；该值是一个 JSON 数组，包含 { "type": "target|tag|business_unit", "value": "..." } 对象：

strix cloud tokens create --type service --name staging-ci \
  --expires-at 2026-12-31T23:59:59Z \
  --scopes scans:read scans:write \
  --rbac-scopes '[{"type":"tag","value":"staging"}]'

令牌密钥只会返回一次。请直接将其存储在密钥管理器中，切勿打印或提交。 --expires-at 和 --expires-in-days 不能同时使用。

0. 额度与充值

非 Enterprise 扫描会消耗组织额度。Enterprise 服务包含在套餐内，不会扣除钱包余额。扫描前请检查余额（billing:read）：

strix cloud credits

余额不足时，使用 strix cloud billing topup 购买额度（billing:write，管理员令牌）。服务器会在首次请求时返回 HTTP 402 和机器支付质询（Stripe Machine Payments Protocol）。Node.js 可用时，CLI 会通过 Stripe Link 钱包客户端支付质询，用户在 Link 应用中批准付款。响应会返回收据（credits_granted、duplicate、reference）和新余额。

默认层级的纯源代码审查目前起价为 60 个额度。上传源代码并非免费：它会启动普通的 code_review，并使用相同的确定性范围估算器。服务会在启动前检查全部余额，仅在验证成功后原子性地预留额度，不会创建或收取被拒绝的扫描费用。复测和 Enterprise 扫描不受此限制。

strix cloud billing topup --credits 20 --yes   # explicit approval; skips the TTY prompt
strix cloud billing topup --credits 20 --no-pay   # print the 402 challenge without paying

默认支付方式为 Stripe Link 钱包。未连接钱包时，交互式 strix cloud billing topup 会为用户启动 Link 登录，并打印验证链接。用户在 Link 应用中批准一次连接，然后在那里批准每笔付款。无需任何密钥或变量。在非交互式进程中，命令会停止，并提示用户前往 link.com/agents连接钱包，或使用托管结账链接。

在非交互式 Agent 或 CI 进程中，除非命令包含 --yes，否则绝不会继续付款。向用户展示质询或预估支出，并在添加额度前征得批准。--no-pay 始终会在打印质询后停止。

如果用户不想使用钱包，请使用 strix cloud billing subscribe --plan strix_top_up 创建托管结账链接，并将链接提供给用户。用户可在浏览器中付款。

自动充值（管理员）：strix cloud billing auto-topup 会显示当前设置。使用以下命令启用：

strix cloud billing auto-topup update --enabled --topup-credits 20 --monthly-cap-credits 200

省略 --monthly-cap-credits 会保留已存储的上限。传入 --no-monthly-cap 可移除上限。

工作区与账户设置

使用 strix cloud login 获取的个人令牌管理工作区：

strix cloud workspaces list                    # numbered name/role/current list
strix cloud workspaces create --name "My Team"  # admin + organizations:write
strix cloud workspaces use 2                   # displayed number, exact name, or ID
strix cloud workspace use "My Team"            # singular `workspace` alias also works
strix cloud session scopes                     # effective scopes + consent ceiling
strix cloud session scopes set minimal         # narrow the session
strix cloud org members invite --email [email protected] --role analyst

workspaces use 会将当前个人令牌切换到用户已加入的工作区，并存储更新后的工作区元数据；承载令牌的密钥和过期时间保持不变。普通切换时不会再次提示用户授权：服务器会保留选定的配置，执行不可变的登录权限上限，并将有效权限范围限制在目标角色允许的范围内。使用 --scope-profile 或 --scopes 可在该上限内缩小权限范围；如需更广泛的授权，必须重新运行 strix cloud login。CLI 会将每个进程固定到其启动时所在的工作区，因此并发的终端会因可恢复的冲突而失败，而不会悄悄切换到其他组织。

需要由用户完成的交接事项

有四个步骤需要用户亲自完成。命令会创建链接或记录并将其打印出来。Strix 仅会在交互式终端中打开浏览器。传入 --no-browser 只会打印 URL。

strix cloud billing subscribe --plan strix_cloud # hosted checkout page for the Cloud plan
strix cloud billing portal                       # billing portal for the card and the plan
strix cloud integrations install github          # GitHub App or Slack installation page
strix cloud domains verify <domain-id>           # DNS record to add, then run it again

将打印出的 URL 或 DNS 记录提供给用户并等待。不要声称付款、安装或 DNS 更改已经完成。之后使用 strix cloud credits、strix cloud integrations list 或 strix cloud domains list 确认结果。除 domains verify 需要 assets:write 外，其余三个命令都需要管理员令牌。

组织知识

Agent 无需使用仪表板即可管理组织知识库（knowledge:read / knowledge:write）：

strix cloud knowledge list --search authentication
strix cloud knowledge add --title "Authentication" --content "Staging uses SSO."
strix cloud knowledge update <document-id> --content "Staging uses SSO and TOTP."
strix cloud knowledge delete <document-id>
strix cloud knowledge policies add --key staging-only --content "Never test production."
strix cloud knowledge policies delete staging-only
strix cloud knowledge repos entries usestrix/strix

知识策略写入需要管理员令牌。仓库名称以普通的 owner/name 值传入；CLI 会处理 URL 编码。costs 和 llm-settings 命令面向本地部署安装，在 app.strix.ai 上会返回 404。

1. 将目标注册为资产

扫描针对的是已注册资产，而不是原始 URL。注册一次，然后重复使用返回的 UUID。

# Domain (black-box / live target). Requires domain verification before external scanning.
# --asset-type must be one of: web_app | api | attack_surface.
strix cloud domains add --domain staging.example.com --asset-type web_app

# Repository (white-box / code review). `full_name` is "owner/name".
strix cloud repos add --data '{"full_name":"org/app","provider":"github"}'

请先查找现有资产，而不是重复添加：strix cloud domains list、strix cloud repos list（两者都需要 assets:read）。

2. 启动扫描

strix cloud scans start（需要 scans:write）。至少通过 --domain-ids、--repository-ids 或 --internal-targets 指定一个目标（内部基础设施需要网络连接器 — 请参阅文档）。

strix cloud scans start \
  --engagement-type live_test \
  --domain-ids <domain-uuid> \
  --focus "IDOR, auth bypass, SSRF" \
  --context "Staging. Test account creds are configured as a test user." \
  --notify-on-completion

实用标志（每个标志都对应一个 CreateScanRequest 字段）：

标志	用途
--engagement-type	live_test（默认）、code_review、internal_infra、compliance_pentest
--domain-ids / --repository-ids / --internal-targets	目标（至少一个）
--domain-paths / --repository-branches	缩小到特定路径 / 分支范围（JSON 映射）
--credentials	通过身份验证进行扫描，包括 mfa_method（totp/email_otp/…）和 totp_secret（JSON 列表）
--headers	作为 JSON 标头对象数组提供的额外目标 HTTP 标头
--focus / --concerns / --context	用于引导 Agent 的自由格式字符串
--upload-ids	附加已上传的源代码 / 文档归档，以提供白盒上下文
--notify-on-completion / --notification-emails	完成后发送电子邮件

如果不指定 --source，响应将为 { scan_id, title, status }，其中 status = pending。 本地源代码扫描成功时，会将该平台响应包装为 { source, upload_id, scan: { scan_id, title, status } }，以便自动化流程保留经过批准的确切清单 和已暂存的上传标识符，以及已创建的扫描。

在云端扫描本地工作区

对于 Agent 或 CI 工作流，请将审批绑定到已审查的确切源快照。使用预期的源选择标志运行试运行，审查清单和所选路径，并记录 source.archive_sha256。然后使用相同的 --source、每个 --exclude 以及任何 --include-hidden、--include-sensitive 或 --include-archives 标志，再加上 --approve-sha256 重复运行：

strix cloud scans start --source . --exclude 'private/' --dry-run --show-files --json
# After reviewing the output, capture its source.archive_sha256 value:
SOURCE_SHA256="<reviewed source.archive_sha256>"
# Repeat every source-selection flag unchanged; a source-only scan infers code_review.
strix cloud scans start --source . --exclude 'private/' \
  --approve-sha256 "$SOURCE_SHA256" --wait

CLI 会重新构建归档；如果其 SHA-256 不再匹配，就会拒绝上传。--yes 的语义有意设得更窄：它只批准本次调用期间构建的快照。请将它用于经审慎考虑的人工审批或一次性审批，而不要将它用作基于摘要的 Agent/CI 审查流程的第二步。在没有 TTY 的情况下，源上传需要匹配的 --approve-sha256 审批或 --yes；交互式终端则可以显示摘要、在设置 --show-files 时显示所选文件名，并针对当前快照提示 [y/N] 确认。

默认选择方式注重隐私：在 Git 工作树中，会包含已跟踪文件以及未被忽略的未跟踪文件；遵循 .gitignore，排除所有隐藏路径组件，并始终排除 .git、符号链接、依赖项/构建输出、类似密钥的文件名和嵌套归档。将项目排除项添加到 .strixignore（每行一个排除 glob），或重复使用 --exclude GLOB；末尾带斜杠的写法（如 private/）会排除该目录及其子树。

客户端会拒绝超过 20,000 个文件、单个文件超过 25 MiB、解压后总量超过 250 MiB 或 ZIP 超过 50 MiB 的情况。随后，服务会流式解压 ZIP，并独立拒绝格式错误或不受支持的条目、不安全的路径、过多条目、超大条目、解压后数据过多以及压缩输入过大等情况，因此不可信客户端无法通过伪造元数据绕过 ZIP 炸弹防护。

只有在试运行清单表明扫描需要时，才使用 --include-hidden、--include-sensitive 或 --include-archives。隐藏文件和敏感文件是两个独立的可选项：例如，要包含 .env，必须同时使用 --include-hidden 和 --include-sensitive。

CLI 会在每次调用后删除其私有本地临时归档。远程上传暂存后，如果扫描明确被拒绝，CLI 会将其删除。网络故障、5xx 响应、格式错误的成功响应，或扫描启动后发生中断，都属于结果不确定的情况——平台可能已接受扫描，因此 CLI 会保留上传，并返回其 upload_id 以及 launch_outcome_unknown: true。如果无法确认自动删除操作是否成功，则会改为返回保留的 upload_id 以及 cleanup_unknown: true。重试前，请运行 strix cloud scans list，以避免重复扫描或重复收费。如果没有扫描关联到该保留上传，请使用 strix cloud uploads delete UPLOAD_ID 删除它；已关联扫描的上传无法删除。

未指定类型时，仅提供源会推断为 code_review。任何域名目标都会优先，并推断为 live_test，因此，源加上已部署域名是常见的白盒实时测试工作流。需要覆盖推断结果时，请传入 --engagement-type。

3. 等待完成

在 scans start 中传入 --wait，轮询直至扫描进入最终状态；也可以使用 strix cloud scans get <scan-id>（scans:read）自行轮询。使用 --wait-timeout SECONDS 为自动化设置时限；超时会正常退出，不会取消远程扫描。状态流转：pending → running → completed（或 failed / cancelled）。扫描需要数分钟到数小时——请按间隔轮询，不要无限期阻塞。

4. 阅读发现

扫描详情响应包含 executive_summary、methodology、recommendations、findings 严重程度汇总，以及 vulnerabilities[] 数组。每个漏洞包含 title, severity, status, cvss, cwe, endpoint, method, impact, technical_analysis, poc_description, poc_script_code，对于代码发现，还包含 code_file/code_diff/code_before/code_after。

strix cloud scans get <scan-id> --json \
  | jq '["critical","high","medium","low","info"] as $order
       | .vulnerabilities
       | sort_by(.severity as $s | $order | index($s))
       | .[] | {title, severity, endpoint, cwe}'

Cloud 严重程度为 critical | high | medium | low，状态为 open | in_progress | snoozed | fixed | ignored | not_affected。请按明确的严重程度顺序排序，而不要使用 sort_by(.severity)，因为它会按字母顺序排序（critical、high、low、medium）。

跨扫描进行组织范围的分类：strix cloud vulns list --severity critical（需要 vulnerabilities:read，也支持按 --status、--scan-id 等进行筛选）。使用 strix cloud vulns update <id> --status fixed 更新分类状态。要修复漏洞，请交由 fix-security-vulnerabilities-with-strix 技能处理。

5. 导出与报告

# SARIF 2.1.0 for GitHub code scanning / ASPM ingestion
strix cloud scans sarif <scan-id> --output findings.sarif

# Report. Formats: technical (default) | retest | attestation | executive_summary
# Types: pdf (default) | docx
# Any report download requires the Enterprise plan. Formats beyond `technical`,
# DOCX, and white-label branding are Enterprise-only too. Scan must be completed.
strix cloud scans report <scan-id> --format technical --type pdf --output strix-report.pdf

除非明确指定 --force，否则下载不会覆盖文件。企业版审计日志可以流式传输为 JSON，或直接导出而不尝试对响应正文进行 JSON 解码：

strix cloud audit list --format csv --all --output audit.csv
strix cloud audit list --format ndjson --all --output audit.ndjson

6. PR 审查

触发对拉取请求的自动安全审查（需要 pr_reviews:write）。使用 strix cloud repos list 读取仓库的 provider 和 installation_id；两者共同标识已安装的源代码管理集成。结果会显示为 PR 评论，并出现在仪表板中：

strix cloud pr-reviews start \
  --provider github \
  --installation-id <installation-id> \
  --repository-full-name org/app \
  --pr-number 123

使用 strix cloud pr-reviews list 和 strix cloud pr-reviews get <id> 列出或查看审查结果。仓库级别的 PR 审查行为通过 strix cloud pr-reviews settings 配置。

7. 持续测试（计划与 Webhook）

• 计划（schedules:write，Pro 计划）：strix cloud schedules create 可创建定期扫描，strix cloud schedules trigger <id> 可按需运行一次——这是由服务托管、等效于通过 cron 循环运行 CLI 的方案。
• Webhook（webhooks:write）：strix cloud webhooks create 可订阅渗透测试/漏洞生命周期事件，例如 scan.completed 和 vulnerability.created，并将结果推送到 Slack、工单系统或你自己的流水线，无需轮询。

有关负载的详情，请参阅 docs.app.strix.ai 上的计划与 Webhook 章节。

网络连接器仅面向 Enterprise。strix cloud connectors create 可能会返回包含凭据的一次性注册命令；请勿将其粘贴到日志中，且只有在用户准备好安装时才使用 --include-command 请求该命令。浏览器结账、源代码管理安装、DNS 验证、连接器安装、聊天共享，以及向外部服务商发布 SARIF，均属于需要用户介入或明确执行的外部变更——请先准备命令或链接，再在完成操作前取得相应批准。

安全

仅扫描用户组织拥有或获准测试的资产。平台会强制要求验证（DNS/文件/元标签）后才能扫描外部域名；请勿尝试绕过此要求。