ClawSense 🔍

OpenClaw 恶意技能检测器 —— 在技能安装前自动识别威胁，输出 🟢 无毒 / 🟡 可疑 / 🔴 恶意 健康报告。

---

背景

OpenClaw 是一个开放的 AI Agent 技能市场，任何人都可以发布技能。这带来了安全风险——部分技能包含恶意行为：

• 通过 prerequisites 字段注入恶意依赖
• curl | bash 远程执行任意代码
• Base64 混淆 payload 绕过人工审查
• 窃取 .ssh/、.env、AWS 密钥等敏感文件
• 批量仿冒热门技能名（typosquatting）

ClawSense 是一个 ML 驱动的检测器，在技能安装前自动扫描并输出风险报告，保护用户不被恶意技能攻击。

---

快速开始

pip install clawsense

# 命令行扫描
clawsense scan --input skills.json

或在 Python 中直接调用：

from clawsense import ClawSense

cs = ClawSense()
result = cs.scan(skill)
print(cs.health_report(result))

输出示例：

╔══════════════════════════════════════════════════╗
║  ClawSense Skill Health Report                   ║
╠══════════════════════════════════════════════════╣
║  Skill:      suspicious/bulk-agent-deploy        ║
║  Publisher:  suspicious                          ║
╠══════════════════════════════════════════════════╣
║  Result:     🔴 MALICIOUS                        ║
║  Confidence: 97.1%                               ║
║  P(malicious)=97.1%  P(suspicious)=2.5%          ║
╠══════════════════════════════════════════════════╣
║  Detected signals (3)                            ║
║  ⚡  curl | bash 模式，远程代码执行风险           ║
║  🎭  含长 base64 字符串（>50字符），疑似混淆      ║
║  💀  prerequisites 字段疑似被滥用于注入依赖       ║
╚══════════════════════════════════════════════════╝

---

安装

pip install clawsense

依赖：Python 3.8+，详见 requirements.txt

首次使用时会自动下载 all-MiniLM-L6-v2 embedding 模型（约 90MB）。 如需离线使用，下载后指定本地路径：

cs = ClawSense(emb_model="/path/to/all-MiniLM-L6-v2")

---

使用方法

命令行

# 扫描单个或批量技能
clawsense scan --input skills.json

# 保存结果
clawsense scan --input skills.jsonl --output results.jsonl

# 显示所有技能详细报告（包括 benign）
clawsense scan --input skills.json --verbose

命令行检测到恶意技能时退出码为 1，可集成到 CI/CD 流水线。

Python API

扫描单个技能：

from clawsense import ClawSense

cs = ClawSense()

skill = {
    "slug":             "publisher/skill-name",
    "skill_name":       "skill-name",
    "publisher":        "publisher",
    "yaml_description": "技能描述...",
    "body":             "# 技能内容...",
}

result = cs.scan(skill)

print(result)
# 🔴 [MALICIOUS] publisher/skill-name  confidence=97.1%

print(result.label)       # "malicious"
print(result.is_malicious)  # True
print(result.prob_malicious)  # 0.971
print(result.signals)     # [DetectedSignal(...), ...]

扫描批量技能：

results = cs.scan_batch(skill_list)
print(cs.batch_summary(results))

集成到 OpenClaw 安装流程：

from clawsense import ClawSense

cs = ClawSense()

def before_install(skill):
    result = cs.scan(skill)

    if result.is_malicious:
        print(cs.health_report(result))
        raise RuntimeError(f"🔴 已阻断安装：{result.slug} 被检测为恶意技能")

    elif result.should_warn:
        print(cs.health_report(result))
        confirm = input("⚠️  检测到可疑信号，确认安装？[y/N] ")
        if confirm.lower() != "y":
            print("安装已取消")
            return False

    else:
        print(f"✅ {result.slug} — 安全，正在安装...")

    return True

输入格式

每条技能为 JSON 对象，支持以下字段：

字段	是否必须	说明
skill_name	✅	技能标识名
publisher	✅	发布者用户名
slug	推荐	publisher/skill-name
yaml_description	推荐	技能描述文本
body	推荐	技能完整 body 内容（越完整越准确）
has_executable_download	可选	布尔值，是否含可执行文件下载

输入文件支持：

• .json：单个技能对象 {} 或列表 [{}, {}]
• .jsonl：每行一个技能对象

结果字段说明

result.label           # "benign" / "suspicious" / "malicious"
result.risk_emoji      # 🟢 / 🟡 / 🔴
result.confidence      # 预测置信度（0~1）
result.prob_benign     # P(benign)
result.prob_suspicious # P(suspicious)
result.prob_malicious  # P(malicious)
result.is_safe         # True if benign
result.should_warn     # True if suspicious
result.is_malicious    # True if malicious
result.signals         # List[DetectedSignal]，触发的风险信号列表
result.to_dict()       # 序列化为 dict

---

工作原理

三类特征

特征类型	维度	作用
语义 embedding（all-MiniLM-L6-v2）	384	捕捉技能整体语义意图
结构化规则特征	36	检测具体攻击模式（正则匹配）
发布者画像特征	8	识别批量投放和历史恶意发布者

检测信号

类别	信号
💀 ClawHavoc 模式	prerequisites 滥用、openclaw-agent 注入、glot.io payload、password-zip
⚡ 危险代码	eval()/exec()、curl | bash、反弹 shell、os.system()
🔑 敏感文件访问	.ssh/、AWS 密钥、.env 文件
🎭 混淆技术	长 base64 字符串（>50字符）、随机后缀名
👤 发布者行为	历史恶意率高、批量投放（>50个技能）

Top 10 重要特征

排名	特征	说明
1	pub_malicious_ratio	发布者历史恶意率（最关键）
2	pub_skill_count	发布者技能总数
3	havoc_prerequisites	prerequisites 字段命中次数
4	name_length	技能名长度异常
5	havoc_total	ClawHavoc 模式总命中数
6	pub_version_diversity	版本多样性
7	has_executable_download	含可执行文件下载
8	num_external_urls	外部 URL 数量
9	has_base64_long	含长 base64
10	has_prerequisites	含 prerequisites 字段

模型性能（5折交叉验证）

指标	分数
Macro F1	93.71%
Precision（恶意）	99.64%
Recall（恶意）	99.26%
AUC-ROC	99.09%

消融实验

实验	特征	Macro F1
Exp-A	仅语义 embedding（384维）	61.26%
Exp-B	规则 + 发布者（44维）	90.21%
Exp-C	Late Fusion（A+B）	89.85%
Exp-D	全特征（428维） ✅	93.71%

核心发现：规则特征和发布者画像远比语义特征更有判别力。pub_malicious_ratio 是最重要的单一特征。

---

Holdout 验证

对 18,949 条无标签技能的检测结果：

预测	数量	比例
🟢 benign	11,853	62.6%
🟡 suspicious	6,967	36.8%
🔴 malicious	129	0.7%

发现 18 个高置信度恶意技能（P≥0.7），均来自已知恶意发布者的未被情报覆盖的技能，验证了模型的泛化能力。

---

项目结构

clawsense/
├── pyproject.toml          # pip 打包配置
├── requirements.txt
├── README.md
├── clawsense/
│   ├── __init__.py         # 公开 API：ClawSense 主类
│   ├── features.py         # 特征提取
│   ├── model.py            # 推理引擎 + SkillResult
│   ├── report.py           # 健康报告格式化
│   ├── cli.py              # clawsense scan 命令行
│   └── data/
│       ├── lgbm_clawsense.pkl   # 内置模型（2.1MB）
│       └── model_meta.json
├── all-MiniLM-L6-v2/       # Embedding 模型（本地，不打包）
├── examples/
│   └── example_skill.json
└── scripts/                # 训练流水线（可复现）
    ├── collect_skills.py
    ├── build_feature.py
    ├── train.py
    ├── eval.py
    └── predict_unknown.py

---

训练数据

标签	数量	来源
malicious	815	ClawHavoc CVE 数据库 + Antiy CERT 恶意发布者
suspicious	5,088	ClawSecure 高/危险风险信号
benign	736	awesome-openclaw-skills 社区白名单
unknown（holdout）	18,949	未被情报覆盖的技能

---

License

MIT