strix-cloud-api

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

如果你希望使用 Strix 的自主渗透测试**，但不想自行运行 Docker 或大模型**，请使用此方案——扫描在 Strix 的基础设施上运行，结果会记录在团队仪表板中。此方案适用于沙箱／托管 Agent 和 CI 环境、团队，以及计划性／持续测试（可下载的 PDF／DOCX 报告是 Enterprise 计划功能）。如果要完全本地、免费、隔离网络或使用自有大模型运行，请改用 strix-pentest 技能中的开源 CLI——两者共用同一引擎和 SARIF 输出，因此可以混合使用。

完整参考文档：docs.app.strix.ai · OpenAPI：https://docs.app.strix.ai/openapi.json

设置

• 基础 URL： https://app.strix.ai/api/v1

• 身份验证： 每个请求都要发送 Authorization: Bearer <token>。令牌的作用范围为组织级。

• 获取令牌： 用户可在仪表板的 Settings → API Access（app.strix.ai）中创建令牌。请向用户索取；切勿将其硬编码、记录到日志或提交。将其存储在环境变量或 CI 密钥存储中。

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

  权限范围	授予权限
  scans:read / scans:write	列出／读取／报告扫描 · 创建／重新运行／取消扫描
  vulnerabilities:read / :write	读取发现项 · 更新状态和备注
  assets:read / :write	读取域名／代码仓库 · 注册／更新它们
  schedules:read / :write	读取计划 · 创建／触发定期扫描
  pr_reviews:write	触发 PR 安全审查
  webhooks:read / :write	管理 Webhook 订阅
  tokens:write	创建／撤销 API 令牌

export STRIX_API_TOKEN="<token>"
BASE=https://app.strix.ai/api/v1
auth=(-H "Authorization: Bearer $STRIX_API_TOKEN")

所有示例都使用 jq 解析 JSON。请处理 HTTP 错误：401 表示令牌无效或已过期，402 表示额度不足，403 表示权限范围／计划层级限制，422 表示验证错误。

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.
curl -sS "$BASE/domains" "${auth[@]}" -H "Content-Type: application/json" \
  -d '{"domain":"staging.example.com","asset_type":"web_app"}' | jq '{id:.domain.id, status, reachable, verification}'

# Repository (white-box / code review). `full_name` is "owner/name".
# Send one repository object, or a bare JSON array for several — not an object
# wrapping a "repositories" key (that is rejected with 400).
curl -sS "$BASE/repositories" "${auth[@]}" -H "Content-Type: application/json" \
  -d '[{"full_name":"org/app","provider":"github"}]' | jq '.repositories[] | {id, full_name}'

查找现有资产，而不是重复添加：GET /domains、GET /repositories（两者都需要 assets:read，并通过 ?page=&limit= 分页）。

2. 启动扫描

POST /scans（需要 scans:write）。至少通过 domain_ids、repository_ids 或 internal_targets 提供一个目标（内部基础设施需要网络连接器，详见文档）。

scan_id=$(curl -sS "$BASE/scans" "${auth[@]}" -H "Content-Type: application/json" -d '{
  "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": true
}' | jq -r .scan_id)
echo "$scan_id"

实用的 CreateScanRequest 字段：

字段	用途
engagement_type	live_test（默认）、code_review、internal_infra、compliance_pentest
domain_ids / repository_ids / internal_targets	目标（至少一个）
domain_paths / repository_branches	将范围缩小到特定路径／分支
credentials	经过身份验证的扫描，包括 mfa_method（totp/email_otp/…）和 totp_secret
headers	为目标添加额外 HTTP 标头（例如 API 密钥）
focus / concerns / context	引导 Agent
upload_ids	附加上传的源代码／文档归档，提供白盒上下文
notify_on_completion / notification_emails	完成时发送邮件

响应为 { scan_id, title, status }，其中 status = pending。

3. 轮询直至完成

GET /scans/{scanId}（需要 scans:read）。状态流转：pending → running → completed（或 failed / cancelled）。请按间隔轮询——扫描需要几分钟到几小时；不要阻塞。

while :; do
  s=$(curl -sS "$BASE/scans/$scan_id" "${auth[@]}" | jq -r .status)
  echo "status=$s"; [[ "$s" =~ ^(completed|failed|cancelled)$ ]] && break
  sleep 60
done

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。

curl -sS "$BASE/scans/$scan_id" "${auth[@]}" \
  | jq '["critical","high","medium","low","info"] as $order
       | .vulnerabilities
       | sort_by(.severity as $s | $order | index($s))
       | .[] | {title, severity, endpoint, cwe}'

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

跨扫描进行组织范围的分诊：使用 GET /vulnerabilities（vulnerabilities:read；按严重性/状态筛选）。使用漏洞 :write 端点更新分诊状态。要修复问题，请交由 strix-fix-findings 技能处理。

5. 导出与报告

# SARIF 2.1.0 for GitHub code scanning / ASPM ingestion
curl -sS "$BASE/scans/$scan_id/sarif" "${auth[@]}" -o findings.sarif

# Report. The format and file type are query params (`Accept` is ignored):
#   format=technical (default) | retest | attestation | executive_summary
#   type=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.
curl -sS "$BASE/scans/$scan_id/report?format=technical&type=pdf" "${auth[@]}" -o strix-report.pdf

6. PR 评审

触发对拉取请求的自动安全评审（pr_reviews:write）；结果会显示为 PR 评论，并出现在仪表板中：

curl -sS "$BASE/pr-reviews/start" "${auth[@]}" -H "Content-Type: application/json" \
  -d '{"repository_full_name":"org/app","pr_number":123}'

使用 GET /pr-reviews 和 GET /pr-reviews/{id} 列出/检查评审。仓库级 PR 评审行为通过仓库设置端点配置。

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

• 计划任务（schedules:write，Pro 计划）：创建定期扫描并按需触发，相当于托管式的 cron 驱动命令行循环。
• Webhook（webhooks:write）：订阅渗透测试/漏洞生命周期事件（例如 scan.completed、vulnerability.created），将结果推送到 Slack、工单系统或你自己的流水线，而不是通过轮询获取。

有关载荷，请参阅 docs.app.strix.ai 上的计划任务和 Webhook 章节。

安全

仅扫描用户组织拥有或获准测试的资产。外部域名扫描需要验证（DNS/文件/Meta 标签），平台会强制执行此要求——不要尝试绕过。