skillguard

用于 OpenClaw 技能的人工智能安全扫描仪。在安装前扫描技能文件是否存在凭据盗窃、数据泄露、反向 shell、混淆和其他威胁。

# SkillGuard 🛡️

AI-powered security scanner for OpenClaw skills. Analyzes skill code for malicious behaviour before you install it.

## Commands

### Scan before install (recommended)

```bash
skillguard install <skill-name>
```

Downloads the skill to a temp directory, runs AI security analysis, shows verdict, then asks for confirmation before installing via clawhub.

**Example:**
```
skillguard install my-new-skill
```

### Audit installed skills

```bash
skillguard audit
```

Scans all skills in `/usr/lib/node_modules/openclaw/skills/`, `~/.openclaw/workspace/skills/`, and `~/.openclaw/skills/`. Prints a table summary with details on any flagged skills.

### Scan a local path

```bash
skillguard scan <path>
```

Scan any local skill directory without installing. Useful for reviewing skills you've already downloaded or developed locally.

**Example:**
```
skillguard scan ./my-skill-folder
skillguard scan /usr/lib/node_modules/openclaw/skills/some-skill
```

## Risk Levels

| Level  | Meaning |
|--------|---------|
| ✅ CLEAN  | No security issues detected |
| 🟡 LOW    | Minor concerns, generally safe |
| ⚠️ MEDIUM | Review recommended before installing |
| 🚨 HIGH   | Dangerous — do not install without careful manual review |

## What Gets Checked

- **Credential theft**: Reads to `~/.ssh/`, `~/.openclaw/`, API keys, `.env` files
- **Data exfiltration**: curl/wget/fetch POSTing data to external servers
- **Reverse shells**: netcat, bash TCP redirects, socat to external IPs
- **Privilege escalation**: sudo abuse, setuid bits, writing to `/etc/`
- **Persistence**: cron installs, systemd units, `.bashrc` modifications
- **Obfuscation**: base64-piped-to-bash, eval with dynamic content
- **Package smuggling**: undisclosed npm/pip installs
- **Reconnaissance**: network scanning, system info harvesting

## Usage by the AI Agent

When the user asks to install a skill, use skillguard first:

```bash
python3 /root/.openclaw/workspace/skills/skillguard/skillguard.py install <skill-name>
```

When the user asks to check their installed skills for security issues:

```bash
python3 /root/.openclaw/workspace/skills/skillguard/skillguard.py audit
```

When the user asks to check a specific local skill directory:

```bash
python3 /root/.openclaw/workspace/skills/skillguard/skillguard.py scan /path/to/skill
```

## Output Examples

**Clean skill:**
```
✅ SkillGuard: good-skill — Clean. Installing...
```

**Flagged skill:**
```
🚨 SkillGuard: bad-skill — Risk: HIGH
   Reads /root/.openclaw/*.json and POSTs to external IP.

   [HIGH] Data Exfiltration: curl POST of ~/.openclaw/openclaw.json to 45.33.32.156 [scripts/init.sh:14-22]
   [MEDIUM] Credential Theft: Reads ~/.ssh/id_rsa without disclosure [scripts/setup.sh:8]

Install bad-skill anyway? (type YES to confirm)
```

## Requirements

- Python 3.6+
- An Anthropic, OpenRouter, or DeepSeek API key configured in OpenClaw
- `clawhub` CLI (for `install` command only)

## Notes

- Binary files are automatically skipped
- Files larger than 100KB are truncated before analysis
- Analysis uses Claude Opus (or best available model) for maximum accuracy
- The scan itself is safe — skills are text files, not executed during scanning

---

## 中文说明

# SkillGuard 🛡️

面向 OpenClaw 技能的 AI 驱动安全扫描器。在你安装技能之前，对其代码进行恶意行为分析。

## 命令

### 安装前扫描（推荐）

```bash
skillguard install <skill-name>
```

将技能下载到临时目录，运行 AI 安全分析，显示裁定结果，然后在通过 clawhub 安装前请求确认。

**示例：**
```
skillguard install my-new-skill
```

### 审计已安装的技能

```bash
skillguard audit
```

扫描 `/usr/lib/node_modules/openclaw/skills/`、`~/.openclaw/workspace/skills/` 和 `~/.openclaw/skills/` 中的所有技能。打印表格摘要，并附带任何被标记技能的详情。

### 扫描本地路径

```bash
skillguard scan <path>
```

无需安装即可扫描任意本地技能目录。适用于审查你已下载或本地开发的技能。

**示例：**
```
skillguard scan ./my-skill-folder
skillguard scan /usr/lib/node_modules/openclaw/skills/some-skill
```

## 风险等级

| 等级  | 含义 |
|--------|---------|
| ✅ CLEAN  | 未检测到安全问题 |
| 🟡 LOW    | 轻微隐患，总体安全 |
| ⚠️ MEDIUM | 建议安装前审查 |
| 🚨 HIGH   | 危险 — 未经仔细人工审查请勿安装 |

## 检查内容

- **凭据盗窃**：对 `~/.ssh/`、`~/.openclaw/`、API 密钥、`.env` 文件的读取
- **数据外泄**：curl/wget/fetch 将数据 POST 到外部服务器
- **反向 shell**：netcat、bash TCP 重定向、socat 连接外部 IP
- **提权**：滥用 sudo、setuid 位、写入 `/etc/`
- **持久化**：cron 安装、systemd 单元、`.bashrc` 修改
- **混淆**：base64 管道到 bash、对动态内容使用 eval
- **包夹带**：未声明的 npm/pip 安装
- **侦察**：网络扫描、系统信息采集

## AI 代理的使用方式

当用户要求安装某个技能时，先使用 skillguard：

```bash
python3 /root/.openclaw/workspace/skills/skillguard/skillguard.py install <skill-name>
```

当用户要求检查其已安装技能是否存在安全问题时：

```bash
python3 /root/.openclaw/workspace/skills/skillguard/skillguard.py audit
```

当用户要求检查某个特定的本地技能目录时：

```bash
python3 /root/.openclaw/workspace/skills/skillguard/skillguard.py scan /path/to/skill
```

## 输出示例

**安全的技能：**
```
✅ SkillGuard: good-skill — Clean. Installing...
```

**被标记的技能：**
```
🚨 SkillGuard: bad-skill — Risk: HIGH
   Reads /root/.openclaw/*.json and POSTs to external IP.

   [HIGH] Data Exfiltration: curl POST of ~/.openclaw/openclaw.json to 45.33.32.156 [scripts/init.sh:14-22]
   [MEDIUM] Credential Theft: Reads ~/.ssh/id_rsa without disclosure [scripts/setup.sh:8]

Install bad-skill anyway? (type YES to confirm)
```

## 要求

- Python 3.6+
- 在 OpenClaw 中配置的 Anthropic、OpenRouter 或 DeepSeek API 密钥
- `clawhub` CLI（仅 `install` 命令需要）

## 说明

- 二进制文件会被自动跳过
- 大于 100KB 的文件在分析前会被截断
- 分析使用 Claude Opus（或可用的最佳模型）以获得最高准确度
- 扫描本身是安全的 — 技能是文本文件，在扫描期间不会被执行