SafeSkill API 文档

SafeSkill 通过 RESTful API 提供 AI Agent Skill 安全检测能力。支持通过文件上传、URL 或 Skill 名称提交检测，包含静态分析、外链威胁情报、LLM 语义分析与动态沙箱检测。
Base URL: https://api.safeskill.cn

认证方式

所有 API 请求需通过 apikey 参数进行认证。登录后在用户中心获取 API Key。
参数类型必填说明
apikeystringYes用于认证的 API 密钥

调用流程

1提交 Skill（文件 / URL / 名称）
2获取 SHA256
3轮询报告接口
4获取检测结果
POST

/api/v1/scan

通过文件上传、URL 或 Skill 名称提交安全扫描。系统自动识别输入类型并执行相应的检测流程。
POSThttps://api.safeskill.cn/api/v1/scan
请求参数
参数类型必填说明
apikeystringYes用于认证的 API 密钥
filefileNo待扫描的 Skill 包文件（zip、tar.gz）或 SKILL.md
urlstringNo支持的 Skill 商店 URL（如 ClawHub、GitHub）或 Skill 包直链
namestringNo在支持的 Skill 商店中搜索并扫描的 Skill 名称（不区分大小写）
响应
JSON
{
  'response_code': 0,
  'verbose_msg': 'OK',
  'data': {
    'sha256': 'a1b2c3d4e5f67890abcdef...1234567890',
    'permalink': 'https://SafeSkill.io/report/{sha256}'
  }
}
参数类型必填说明
data.sha256stringNo扫描 Skill 的 SHA256 哈希，用于查询报告
data.permalinkstringNo在线扫描报告链接
示例
cURL — file
curl -X POST "https://api.safeskill.cn/api/v1/scan" \
  -F "apikey=YOUR_API_KEY" \
  -F "file=@linkedin-skill.zip"
cURL — url
curl -X POST "https://api.safeskill.cn/api/v1/scan" \
  -H "Content-Type: application/json" \
  -d '{"apikey":"YOUR_API_KEY","url":"https://clawhub.ai/ide-rea/linkedin"}'
cURL — name
curl -X POST "https://api.safeskill.cn/api/v1/scan" \
  -H "Content-Type: application/json" \
  -d '{"apikey":"YOUR_API_KEY","name":"linkedin"}'
Python — file
import requests

resp = requests.post(
    "https://api.safeskill.cn/api/v1/scan",
    data={"apikey": "YOUR_API_KEY"},
    files={"file": open("linkedin-skill.zip", "rb")}
)
sha256 = resp.json()["data"]["sha256"]
print(f"Submitted. SHA256: {sha256}")
Python — url / name
import requests

# Scan by URL
resp = requests.post(
    "https://api.safeskill.cn/api/v1/scan",
    json={"apikey": "YOUR_API_KEY", "url": "https://clawhub.ai/ide-rea/linkedin"}
)

# Scan by name
resp = requests.post(
    "https://api.safeskill.cn/api/v1/scan",
    json={"apikey": "YOUR_API_KEY", "name": "linkedin"}
)

sha256 = resp.json()["data"]["sha256"]
print(f"Submitted. SHA256: {sha256}")
GET

/v1/report

根据文件的 SHA256 查询详细扫描报告。返回包含静态分析、外链分析、LLM 语义分析和动态检测的全面检测结果。
GEThttps://api.safeskill.cn/v1/report?apikey=...&sha256=...
请求参数
参数类型必填说明
apikeystringYes用于认证的 API 密钥
sha256stringYes扫描接口返回的 SHA256
响应
JSON
{
  "response_code": 0,
  "verbose_msg": "OK",
  "data": {
    "summary": {
      "sha256": "a1b2c3d4e5f67890...",
      "sha1": "b2c3d4e5f67890ab...",
      "md5": "c3d4e5f67890abcd...",
      "file_type": "application/zip",
      "file_name": "linkedin-skill.zip",
      "threat_level": "malicious",
      "trust_score": 12,
      "is_whitelist": false,
      "multi_engines": "7/25",
      "first_seen": "2026-03-11 14:20:00",
      "last_seen": "2026-03-11 14:23:00",
      "tags": ["zip", "openclaw_skill"],
      "threat_classify": "Trojan",
      "threat_name": "ClawHavoc"
    },
    "skill_details": {
      "type": "OpenClaw Skill",
      "basic_info": {
        "skill_name": "linkedin",
        "developer": "",
        "version": "",
        "skill_type": "OpenClaw Skill",
        "description": "Use when you need to interact..."
      }
    },
    "multi_verdict": {
      "llm": "malicious",
      "static": "malicious",
      "dynamic": "unknown",
      "subfiles": "unknown",
      "external_urls": "malicious"
    },
    "external_urls_details": [
      {
        "url": "https://github.com/...",
        "source": "SKILL.md",
        "trigger_type": "manual",
        "platform": "windows",
        "threat_level": "malicious",
        "last_detection_time": "2026-02-27 17:03:25",
        "ext_info": { ... }
      }
    ],
    "subfile_details": [
      {
        "name": "data_fetcher.py",
        "sha256": "af6a70...",
        "sha1": "9b1442...",
        "md5": "eac269...",
        "size": 9626,
        "threat_level": "unknown",
        "file_type": "PYTHON"
      }
    ],
    "llm_details": {
      "summary": "High-risk behaviors detected...",
      "risk_level": "malicious",
      "risk_indicators": [
        {
          "indicator": "Downloads from unofficial repo",
          "severity": "high",
          "evidence": "https://github.com/..."
        }
      ]
    },
    "permalink": "https://SafeSkill.io/report/..."
  }
}
响应字段
参数类型必填说明
data.summaryobjectNo文件摘要（哈希、威胁等级、可信度、检测详情）
data.summary.sha1stringNo文件 SHA1 哈希
data.summary.md5stringNo文件 MD5 哈希
data.summary.threat_levelstringNoSkill 的总体威胁等级
data.summary.trust_scoreintegerNo信任分数（0–100）；区间含义见 Trust Score
data.summary.first_seenstringNo文件提交时间
data.summary.last_seenstringNo最后检测时间
data.summary.tagsarrayNo标签列表
data.skill_details.typestringNo检测到的 Skill 类型
data.skill_details.basic_infoobjectNoSkill 元数据（名称、开发者、版本、描述）
data.multi_verdictobjectNo各维度判定（llm、static、dynamic、subfiles、external_urls）
data.external_urls_detailsarrayNo各外链的详细分析
data.subfile_detailsarrayNo子文件检测详情
data.llm_detailsobjectNoLLM 语义分析结果
data.permalinkstringNo在线报告链接
示例
cURL
curl "https://api.safeskill.cn/v1/report?apikey=YOUR_API_KEY&sha256=a1b2c3d4..."
Python — Scan + Poll
import requests, time

API_KEY = "YOUR_API_KEY"

# Step 1: Submit scan (file example)
resp = requests.post(
    "https://api.safeskill.cn/api/v1/scan",
    data={"apikey": API_KEY},
    files={"file": open("linkedin-skill.zip", "rb")}
)
sha256 = resp.json()["data"]["sha256"]

# Step 2: Poll for report
for i in range(30):
    r = requests.get(
        "https://api.safeskill.cn/v1/report",
        params={"apikey": API_KEY, "sha256": sha256}
    )
    data = r.json().get("data", {})
    if data.get("multi_verdict"):
        mv = data["multi_verdict"]
        print(f"LLM: {mv['llm']}, Static: {mv['static']}, Dynamic: {mv['dynamic']}")
        print(f"Trust Score: {data['summary']['trust_score']}")
        break
    time.sleep(10)

枚举值

威胁等级枚举
所有 threat_level 和 risk_level 字段使用以下值：
参数类型必填说明
maliciousstringNo恶意 — 确认威胁
suspiciousstringNo可疑 — 潜在风险
unknownstringNo未知 — 数据不足
cleanstringNo安全 — 未发现威胁
信任分数（trust_score）
trust_score 为 0–100 的整数。分数区间：
参数类型必填说明
80 – 100rangeNo未发现明显安全风险
71 – 79rangeNo灰度区间，证据不足无法定性
41 – 70rangeNo可疑，存在潜在风险行为
0 – 40rangeNo恶意，确认存在威胁
risk_indicators[].category
参数类型必填说明
data_theftstringNo数据窃取
network_riskstringNo网络风险
autonomy_abusestringNo能力滥用
rcestringNo远程代码执行
supply_chainstringNo供应链风险
prompt_injectionstringNo提示词注入
persistencestringNo持久化
obfuscationstringNo代码混淆
social_engineeringstringNo社会工程学
cross_platformstringNo跨平台攻击
agent_hijackstringNoAgent 劫持
discovery_abusestringNo发现/探测滥用
risk_indicators[].severity
参数类型必填说明
highstringNo高
mediumstringNo中
lowstringNo低
external_urls_details[].trigger_type
参数类型必填说明
autostringNo自动
manualstringNo手动
conditionalstringNo条件
external_urls_details[].platform
参数类型必填说明
windowsstringNoWindows
macosstringNomacOS
linuxstringNoLinux
allstringNo全部平台

字段速查表

报告响应（data）字段路径、类型与说明：
字段路径类型说明
data (top-level)
summaryobject文件摘要
skill_detailsobjectAI Agent 检测详情
multi_verdictobject各维度判定（llm、static、dynamic、subfiles、external_urls）
external_urls_detailsarray各外链的详细分析
subfile_detailsarray子文件检测详情（名称、哈希、大小、威胁等级、文件类型）
llm_detailsobjectLLM 语义分析结果
permalinkstring在线报告链接
summary
summary.sha256string文件 SHA256
summary.sha1string文件 SHA1
summary.md5string文件 MD5
summary.file_typestring文件类型
summary.file_namestring文件名称
summary.threat_levelstring总体威胁等级（静态+引擎+动态）
summary.trust_scoreinteger信任分数（0–100）
summary.first_seenstring提交时间
summary.last_seenstring最后检测时间
summary.tagsarray标签列表
skill_details
skill_details.typestring检测到的 Skill 类型
skill_details.basic_infoobject基础信息
multi_verdict
multi_verdict.llmstringLLM 维度判定
multi_verdict.staticstring静态分析判定
multi_verdict.dynamicstring动态沙箱判定
multi_verdict.subfilesstring子文件维度判定
multi_verdict.external_urlsstring外链判定
external_urls_details
external_urls_details[].urlstring外链 URL
external_urls_details[].threat_levelstring外链检测结论
external_urls_details[].last_detection_timestring检测时间
subfile_details
subfile_details[].namestring子文件名称
subfile_details[].sha256string子文件 SHA256
subfile_details[].sha1string子文件 SHA1
subfile_details[].md5string子文件 MD5
subfile_details[].sizeinteger子文件大小（字节）
subfile_details[].threat_levelstring子文件威胁等级
subfile_details[].file_typestring子文件类型
llm_details
llm_details.analyzed_atstring分析时间
llm_details.llm_modelstringLLM 模型
llm_details.summarystring综合描述
llm_details.risk_levelstring风险等级
llm_details.intent_reconstructionobject意图分析
llm_details.intent_reconstruction.intent_confidenceinteger意图一致性（0–100），数字越高越一致
llm_details.extracted_iocsobject从文件中提取的部分指标，不代表恶意，请谨慎使用。
llm_details.risk_indicators[]array风险指标
llm_details.risk_indicators[].indicatorstring风险描述
llm_details.risk_indicators[].categorystring风险分类
llm_details.risk_indicators[].severitystring危害度：high / medium / low
llm_details.risk_indicators[].evidencestring关键证据
llm_details.platform_analysisobject平台影响分析（windows/macos/linux）

状态码

API 使用标准化响应码。请检查每次响应中的 response_code 与 verbose_msg。
状态码Verbose Msg说明
0OK成功
2No Data没有数据
3In Progress任务进行中
-1Invalid Account Status账户状态无效
-1Invalid Access IP无效的访问 IP：{实际访问IP}
-1Invalid API Key无效的 API key，请输入正确的 API Key。
-1Invalid Key StatusAPI key 状态无效
-1Invalid Parameter: {parameter}无效的 API 接口参数：{参数名}
-1No Access to API Method没有访问接口权限
-1Expired API KeyAPI Key 过期
-1Empty File上传空文件
-1File Size Too Large上传文件过大
-1File Name Too Long上传文件名过长
-2Invalid API Method无效的 API 接口
-3Required:{}接口请求参数必须项缺失：缺失的具体项
-4Frequent Limitation触发访问频次限制
-4BeyondLimitation超出访问限制
-5System Error系统错误

完整示例

恶意 Skill
JSON
{
  "response_code": 0,
  "verbose_msg": "OK",
  "data": {
    "summary": {
      "sha256": "a1b2c3d4e5f67890abcdef...",
      "sha1": "b2c3d4e5f67890ab...",
      "md5": "c3d4e5f67890abcd...",
      "file_type": "application/zip",
      "file_name": "linkedin-skill.zip",
      "threat_level": "malicious",
      "trust_score": 12,
      "first_seen": "2026-03-11 14:20:00",
      "last_seen": "2026-03-11 14:23:00",
      "tags": ["zip", "openclaw_skill"],
    },
    "skill_details": {
      "type": "OpenClaw Skill",
      "basic_info": { "skill_name": "linkedin", ... }
    },
    "multi_verdict": {
      "llm": "malicious",
      "static": "malicious",
      "dynamic": "unknown",
      "subfiles": "unknown",
      "external_urls": "malicious"
    },
    "external_urls_details": [ ... ],
    "subfile_details": [
      { "name": "data_fetcher.py", "sha256": "af6a70...", "size": 9626, "threat_level": "unknown", "file_type": "PYTHON" }
    ],
    "llm_details": {
      "risk_level": "malicious",
      "risk_indicators": [ ... ]
    }
  }
}
安全 Skill
JSON
{
  "response_code": 0,
  "verbose_msg": "OK",
  "data": {
    "summary": {
      "sha256": "f0e1d2c3b4a59678...",
      "sha1": "e1d2c3b4a5967801...",
      "md5": "d2c3b4a596780123...",
      "file_type": "application/zip",
      "file_name": "weather-skill.zip",
      "threat_level": "clean",
      "trust_score": 92,
      "first_seen": "2026-03-10 09:15:00",
      "last_seen": "2026-03-10 09:18:00",
      "tags": ["zip", "openclaw_skill"],
    },
    "skill_details": {
      "type": "OpenClaw Skill",
      "basic_info": { ... }
    },
    "multi_verdict": {
      "llm": "clean",
      "static": "clean",
      "dynamic": "clean",
      "subfiles": "clean",
      "external_urls": "clean"
    },
    "external_urls_details": [],
    "subfile_details": [],
    "llm_details": {
      "risk_level": "clean",
      "risk_indicators": []
    }
  }
}