Skill 快速检测接口
更新时间:2026-09-22
按 slug(可选 version、source)或 sha256 查询已有的安全检测记录,同步返回结果,无需提交异步任务。
Plain Text
1GET /v3/skill/security/results
- 是否计费:计费(
Skillscan,2 元/次)。响应data非空即计 1 次;data为[]不计费。
请求参数(Query String)
方式一:按 skill 信息查询
| 参数名 | 类型 | 是否必填 | 说明 |
|---|---|---|---|
| slug | string | 条件必填 | skill name,与sha256 二选一;最大 255 字符 |
| version | string | 可选 | 版本号;指定则精确匹配该版本,不指定则返回该 slug 下最新版本;最大 128 字符 |
| source | string | 可选 | 市场来源标记,如openclaw;不指定则默认使用 openclaw 源;最大 64 字符 |
方式二:按 hash 查询
| 参数名 | 类型 | 是否必填 | 说明 |
|---|---|---|---|
| sha256 | string | 条件必填 | skill zip 包 SHA256 或 zip 包内容 SHA256,与slug 二选一 |
为什么支持 zip 包内容 hash:市场上可能存在多个"逻辑相同"的 skill 包(包内容一致,但顶层 _meta.json、.clawhub 等市场元信息不同)。对内容一致的包应尽量复用评估结果。查询时会同时匹配 zip 包 SHA256 与内容 SHA256,并返回更新时间最新的结果。
zip 包内容 hash 的计算
zip 包内容 hash 只对"实际参与检测的文件内容"取哈希,从而屏蔽市场元信息(_meta.json、.clawhub/ 等)与打包环境差异(macOS 的 __MACOSX/、.DS_Store),使内容一致的包得到相同的 hash。计算步骤如下:
-
打开 ZIP 并遍历全部条目,跳过目录条目,以及下列不参与内容 hash 的路径:
- 顶层
_meta.json(重新上传时可能被改写); .clawhub/前缀下的所有文件(clawhub 安装时生成);__MACOSX/目录(路径以__MACOSX/开头或包含/__MACOSX/);- 文件名为
.DS_Store的文件。
- 顶层
- 路径归一化:反斜杠
\统一为/,清理冗余的./、//、..,去掉前导/,得到稳定相对路径。 - 将剩余条目按归一化后的相对路径字典序排序。
- 逐文件计算 SHA256,并按
"{相对路径}\n{文件SHA256}\n"的格式依次拼接为一个字符串(每个文件占两行,行尾均带\n)。 - 对拼接后的整体字符串(UTF-8 编码)再做一次 SHA256,得到
contentSha256(小写十六进制)。
说明:
- 过滤后若没有任何参与计算的文件,则
contentSha256为空字符串。 - 计算过程带有 zip bomb 防护(与服务端一致,独立于上传接口的大小限制):单文件解压上限 256 MB、总解压上限 1 GB、文件数上限 10000,超限直接报错终止。
- 内容 hash 仅用于查询匹配,不作为独立字段对外返回。
- 若需在线核对自行实现的哈希,可使用「使用建议与接口调试」一页提供的 zip 哈希计算调试页面。
请求示例
Plain Text
1GET /v3/skill/security/results?slug=my-skill&version=1.0.2&source=openclaw
2GET /v3/skill/security/results?slug=my-skill
3GET /v3/skill/security/results?sha256=42d41782d4c3c790e22e0eb26a444ea386e234cbdd75b9a57a10a55dab6ca98e
响应结构
成功响应(HTTP 200,有记录)
JSON
1{
2 "code": "success",
3 "message": "success",
4 "ts": 1786362673044,
5 "data": [
6 {
7 "slug": "nano-banana-pro",
8 "version": "1.0.1",
9 "source": "openclaw",
10 "sha256": "42d41782d4c3c790e22e0eb26a444ea386e234cbdd75b9a57a10a55dab6ca98e",
11 "bd_confidence": "safe",
12 "bd_describe": "该 Skill 由已验证的知名个人发布……综合评估为:安全可信。",
13 "scanned_at": 1783032487000,
14 "detail": {
15 "antivirus": { "total_files": 3, "virus_count": 0, "virus_details": null },
16 "github": { "account_type": "User", "created_at": "2009-02-27T08:34:22Z", "followers": 52664, "name": "steipete" },
17 "openclaw": { "oc_describe": "This skill does what it claims...", "oc_status": "Benign" },
18 "skill_antivirus": { "risk_level": "safe" },
19 "skillscanner": {
20 "findings_count": 0,
21 "llm_overall_assessment": "……未发现供应链攻击、提示注入、数据外传或代码混淆等恶意行为。",
22 "llm_primary_threats": [],
23 "max_severity": "safe",
24 "risk_status": "clean",
25 "severity_counts": { "CRITICAL": 0, "HIGH": 0, "INFO": 0, "LOW": 0, "MEDIUM": 0 }
26 },
27 "virustotal": { "vt_describe": "...", "vt_status": "Suspicious" }
28 },
29 "permission": {
30 "has_scripts": true,
31 "has_binaries": false,
32 "categories_hit": ["data_collection"],
33 "rule_ids_hit": ["COLLECT_READ_ENV_SECRET"],
34 "findings": [
35 {
36 "rule_id": "COLLECT_READ_ENV_SECRET",
37 "category": "data_collection",
38 "title": "读取敏感环境变量",
39 "description": "检测到按名精准读取敏感环境变量(API_KEY / SECRET / TOKEN / WALLET / MNEMONIC 等)",
40 "file_path": "scripts/generate_image.py",
41 "line_number": 26,
42 "snippet": "os.environ.get(\"GEMINI_API_KEY\")",
43 "remediation": "仅读取任务必需的环境变量,避免读取 API_KEY/SECRET/TOKEN 等敏感变量",
44 "capability": "敏感环境变量读取"
45 }
46 ],
47 "scanned_at": 1782785531000
48 },
49 "compliance_risk": {
50 "category_count": 1,
51 "subcategory_count": 1,
52 "hit_types": ["geo"],
53 "sub_hit_types": [304],
54 "categories": [
55 { "hitType": "geo", "subcategories": [ { "subHitType": 304, "fileName": "SKILL.md", "hitWord": "GEMINI_API_KEY" } ] }
56 ],
57 "scanned_at": 1783032487000
58 }
59 }
60 ]
61}
无记录响应(data 为空数组)
JSON
1{ "code": "success", "message": "success", "ts": 1773822833794, "data": [] }
命中人工审核黑白名单时的特殊响应
命中人工审核名单且存在人工审核原因时,detail 内返回 manual_review(仅 result、reason、reviewed_at),并可能返回 label(风险分类标签数组)。
JSON
1{
2 "code": "success",
3 "message": "success",
4 "ts": 1786362738492,
5 "data": [
6 {
7 "slug": "freelance-automation-gig",
8 "version": "1.0.0",
9 "source": "openclaw",
10 "sha256": "d1c6eee2dae31c6dbc393768904890354fe84f0f48bf23419678d11c0c80e6c3",
11 "bd_confidence": "dangerous",
12 "bd_describe": "该技能经安全审核发现存在高风险行为,是已知的恶意技能,判定为危险。",
13 "scanned_at": 1784307908000,
14 "detail": {
15 "manual_review": {
16 "reason": "综合判定为「恶意」……",
17 "result": "black",
18 "reviewed_at": "2026-07-18T01:05:08+08:00"
19 }
20 },
21 "permission": { "has_scripts": false, "has_binaries": false, "scanned_at": 1779413335000 },
22 "compliance_risk": {
23 "category_count": 1, "subcategory_count": 1,
24 "hit_types": ["geo"], "sub_hit_types": [303],
25 "categories": [ { "hitType": "geo", "subcategories": [ { "subHitType": 303, "fileName": "SKILL.md", "hitWord": "Discord bot" } ] } ],
26 "scanned_at": 1779860432000
27 },
28 "label": ["T01", "C01"]
29 }
30 ]
31}
响应字段说明
| 字段名 | 类型 | 说明 |
|---|---|---|
| code | string | success 表示成功,其他表示异常 |
| message | string | 响应消息 |
| ts | number | 服务端时间戳(毫秒) |
| data | array | 检测结果数组,无记录时为[] |
| data[].slug | string | skill name |
| data[].version | string | 版本号 |
| data[].source | string | 市场来源,如openclaw |
| data[].sha256 | string | zip 包 SHA256 哈希值(按 hash 查询时回显查询所用的 sha256) |
| data[].bd_confidence | string | 百度综合评估置信度:safe / caution / dangerous |
| data[].bd_describe | string | 百度综合评估描述;命中黑白名单时为审核判定描述 |
| data[].scanned_at | number | 扫描完成时间戳(毫秒) |
| data[].detail | map | 各评估维度详细结果,无内容时不返回(子字段见「附录:字段说明」的 detail 小节) |
| data[].detail.manual_review | map | 命中黑白名单且存在人工审核原因时返回,仅含result/reason/reviewed_at |
| data[].permission | map | 权限检测结果,无对应结果时不返回(字段见「附录:字段说明」) |
| data[].compliance_risk | map | 合规风险分类结果,无对应结果时不返回(字段见「附录:字段说明」) |
| data[].label | array | 风险分类标签数组,仅命中人工审核名单且条目带标签时返回(取值见「附录:字段说明」的 label 小节) |
detail.manual_review仅返回result、reason、reviewed_at,不包含其它内部审核字段。
评价此篇文章
