API Reference

API 的用途不是“跑个扫描”。
而是把 trust decision 接进你的系统。

ClawSafe API 的核心价值，不在于让你拿到一串 JSON，而在于让你的系统在安装、合并、同步、审计这些动作之前，先得到一个可执行的安装建议。

Base URL https://clawsafe.dev

认证

API 请求通过 Bearer Token 认证。在"账户 → API 密钥"页创建密钥，格式为 sk_xxx…。每个密钥仅在创建时完整显示一次，请妥善保存。

示例请求

curl -X POST https://clawsafe.dev/api/scan \
  -H "Authorization: Bearer sk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://github.com/user/skill-repo","locale":"zh"}'

最重要的返回契约

verdictLevel

安装建议层级：trusted / low_risk / suspicious / high_risk / malicious。

riskScore.score

风险分，适合排序和阈值判断，但不应脱离证据单独使用。

findings

结构化发现列表，适合展示主要风险原因。

capabilityMap

声明能力与实际能力对照，用来识别越权。

extraction

IOC、文件树、语言和敏感文件等静态证据。

核心端点

POST /api/scan

提交一个待判断对象。支持 URL 或文件上传。

请求

curl -X POST https://clawsafe.dev/api/scan \
  -H "Content-Type: application/json" \
  -d '{"url":"https://github.com/user/skill-repo","locale":"zh"}'

响应

{
  "reportId": "vtKznl4",
  "id": "vtKznl4",
  "status": "completed",
  "verdictLevel": "high_risk",
  "riskScore": { "score": 82, "breakdown": [...] },
  "findings": [...],
  "capabilityMap": [...],
  "extraction": {...},
  "report_url": "https://clawsafe.dev/report/vtKznl4"
}

GET /api/report/:id

获取一份已生成报告的完整 JSON。

请求

curl https://clawsafe.dev/api/report/vtKznl4

响应

{
  "data": {
    "id": "vtKznl4",
    "type": "scan-report",
    "attributes": {
      "verdictLevel": "high_risk",
      "riskScore": { "score": 82 },
      "findings": [...],
      "capabilityMap": [...],
      "extraction": {...}
    }
  }
}

GET /api/stats

读取平台级统计，用于趋势面板或外部展示。

请求

curl https://clawsafe.dev/api/stats

响应

{
  "data": {
    "totalScans": 18,
    "maliciousBlocked": 7,
    "byVerdict": [...],
    "recentScans": [...]
  }
}

速率限制

POST /api/scan 按账户等级限流：免费版 5 次/天，入门版 50 次/天，专业版不限（合理使用）。未登录用户按 IP 限流 1 次/小时。GET 查询不要求认证。每次响应包含 X-RateLimit-Limit / X-RateLimit-Remaining / X-RateLimit-Reset 三个响应头，用 API Key 调用时反映的是 API 专属配额（入门版 10 次/天、专业版 1000 次/月），而非扫描总配额。

CLI 工具

通过 clawsafe 命令行工具在终端直接扫描，支持 URL 或本地文件，输出人类可读报告或纯 JSON。可集成到 CI/CD 流水线，用退出码（0=低风险，1=可疑，2=高风险，3=恶意，99=错误）做流水线门禁。

安装

# 方式一：直接下载运行（无需安装）
node clawsafe.js scan <url> --key sk_xxx

# 方式二：npm 全局安装
npm install -g clawsafe
clawsafe scan <url> --key sk_xxx

使用示例

# 扫描 GitHub 仓库
clawsafe scan https://github.com/user/my-skill --key sk_xxx

# 扫描本地压缩包
clawsafe scan --file ./skill.zip --key sk_xxx

# CI/CD 门禁（风险分 >= 70 时阻断）
clawsafe scan "$SKILL_URL" --key "$CLAWSAFE_KEY" --threshold 70 || exit 1

# 输出原始 JSON（适合脚本处理）
clawsafe scan <url> --json | jq '.verdictLevel'

套餐与限额

套餐	价格	扫描配额	报告保留	API 调用	附加权益
免费版	$0	5 次/天	7 天	–	–
入门版	$1.98/月	50 次/天	90 天	10 次/天	报告可私密
专业版	$8.98/月	无限（合理使用）	永久	1000 次/月	报告可私密 + 监控任务

查看集成示例直接在线扫描

API 的用途不是“跑个扫描”。而是把 trust decision 接进你的系统。