---

---

⚡ 60 秒内安装并使用

选项 A — 免费云 API（无需安装）```bash

Scan any SKILL.md with a single curl — no account, no key

curl -s --data-binary @SKILL.md
https://skillsguard.apiskillsguard.workers.dev/scan | jq .

### 选项 B — 从源码构建并全局链接

> **注意：** SkillsGuard 目前尚未发布到 npm 注册表。请通过克隆并从源码构建来安装。```bash
# 1. Clone, install, build, and link
git clone https://github.com/Teycir/SkillsGuard.git
cd SkillsGuard
npm install
npm run build
npm link

# 2. Scan any skill directory or file
skillsguard /path/to/skill

那就是了。SkillsGuard 将颜色编码的结果输出到终端（或使用 --json 供 CI 使用）。
退出码 0 = 干净 · 1 = 发现 · 2 = 使用错误。

希望 Claude 在您的智能体工作流中自动调用扫描器？请参阅 本地工作流 → 路径 B 了解完整的技能及 MCP 设置。

---

工作原理```mermaid

flowchart TD A([Folder, file, or Git diff target]) --> B[Load config\nskillsguard.config.json] B --> C[File discovery\nFilter JS, PY, PS1, Docker, Ruby...] C --> D{For each file} D --> E[Raw text scan\nApply 100+ rules] D --> F[decode.ts\nExtract encoded blobs] F --> G[Recursive decode\nbase64, hex, URL] G --> H[Scan decoded content] E & H --> I{Findings?} I -->|no| J([✅ Clean — exit 0]) I -->|yes| K[Deduplicate findings] K --> L[Compute Risk Score\n0 - 100] L --> M{Output mode} M -->|CLI| N[ANSI colored report] M -->|--json| O[JSON output] M -->|--sarif| P[SARIF output] M -->|MCP| Q[MCP response] N & O & P & Q --> R{Risk > max-risk?} R -->|yes| S([❌ Exit 1]) R -->|no| J

style A fill:#0d1117,stroke:#00ff88,color:#c3f5dc
style J fill:#0d1117,stroke:#00ff88,color:#00ff88
style S fill:#0d1117,stroke:#ff4444,color:#ff8888
style G fill:#0d1117,stroke:#f0a500,color:#f0c060
style K fill:#0d1117,stroke:#00ff88,color:#c3f5dc

> **关键洞察：** SkillsGuard 在扫描*之前*解码混淆的有效载荷，因此经过 base64 包装的反向 shell 无法蒙混过关。每条发现都会去重——每条规则在每个文件的每行最多触发一次。

---

## 目录

- [对比 SkillsGuard](#how-skillsguard-compares)
- [为什么选择 SkillsGuard](#why-skillsguard)
- [功能特性](#features)
- [威胁覆盖范围](#threat-coverage)
- [快速开始](#quick-start)
- [本地工作流](#local-workflow)
  - [Kiro CLI — 完整示例](#kiro-cli--complete-example)
  - [真实示例 — 自审计已安装的技能](#real-world-example--self-auditing-installed-skills)
- [命令行使用](#cli-usage)
- [Git Diff 模式](#git-diff-mode)
- [配置文件](#configuration-file)
- [风险评分与门控](#risk-scoring--gating)
- [SARIF 输出](#sarif-output)
- [模型特定规则](#model-specific-rules)
- [规则探索与调优](#rule-explorer--tuning)
- [监控模式](#watch-mode)
- [基线工作流](#baseline-workflow)
- [Pre-commit 钩子](#pre-commit-hook)
- [MCP 服务器](#mcp-server)
- [HTTP 服务器](#http-server)
- [云端 API（免费）](#cloud-api-free)
- [在线演示](#live-demo)
- [库 API](#library-api)
- [规则参考](#rules-reference)
- [混淆检测](#obfuscation-detection)
- [测试夹具](#test-fixtures)
- [项目结构](#project-structure)
- [局限性](#limitations)
- [贡献指南](#contributing)
- [许可证](#license)
- [归属](#attribution)
- [相关项目](#related-projects)
- [支持开发](#support-development)

---

## 对比 SkillsGuard

代理技能安全领域在 2026 年迅速饱和——NVIDIA、Cisco、Snyk 和 Mondoo 都推出了针对这一问题的扫描器。在挑选工具（包括本工具）之前，了解该领域的情况是值得的。

### 概览

| 工具 | 支持方 | 是否需要账户/令牌 | 核心扫描是否需要调用 LLM | 检测方法 | 值得注意的额外功能 |
|---|---|---|---|---|---|
| **SkillsGuard** | 独立，MIT | 否 | 否 | 静态正则，解码优先（递归 base64/hex/URL/Unicode 解包） | Pre-commit 钩子 + git-diff 模式；免费 curl API |
| **[NVIDIA SkillSpector](https://github.com/NVIDIA/SkillSpector)** | NVIDIA，Apache 2.0 | 否 | 否（可选，用于语义阶段） | 静态 + 可选 LLM 语义分析 | 实时 OSV.dev 依赖 CVE 查询 |
| **[Cisco AI Defense Skill Scanner](https://github.com/cisco-ai-defense/skill-scanner)** | Cisco | 否 | 否（可选，用于语义阶段） | 多引擎：静态 + 行为数据流 + LLM 语义 + 云端 | 内置 GitHub Actions 工作流 |
| **[Snyk Agent Scan](https://github.com/snyk/agent-scan)** （原 mcp-scan） | Snyk，商业 | **是** — 需要 `SNYK_TOKEN` | 是 — 确定性规则 + LLM 判断器结合 | 跨 Claude/Cursor/Windsurf/Gemini CLI + MCP 服务器的自动发现 | 为 Vercel 的安装时技能扫描提供支持 |
| **[SkillScan](https://github.com/NMitchem/SkillScan)** | 独立 | 否 | 仅用于 `predict` 模式（可选） | YAML 规则引擎 + 可选 LLM 行为试运行 + 可选 Docker 沙箱 | 通过 LLM 角色扮演检测时间/延迟激活 |
| **Mondoo Skill Check** | Mondoo，商业 | 否（免费层，非商业） | 从公开文档看不清楚 | 静态，映射到 OWASP LLM Top 10 | 托管仪表板 + REST API |

**最重要的共同主线：** SkillsGuard 是此表中唯一一款只需 **Node ≥ 18.3** 即可运行完整扫描的工具——无需账户、无需 API 令牌、无需 LLM 端点、无需网络调用。其他所有积极维护的竞品要么需要注册服务（Snyk），要么建议配置 LLM 提供商以获得完整覆盖（NVIDIA、Cisco、SkillScan）。这使得 SkillsGuard 成为 CI 门控或 pre-commit 钩子最简单的选择，因为它每次都能以相同的方式离线运行；而 LLM 增强型工具则在需要语义/意图级别审查且不介意额外依赖时更胜一筹。

它们并非互斥。一个合理的设置是：将 SkillsGuard（或任何零依赖的静态工具）作为快速确定性的 CI/pre-commit 门控，配合一个 LLM 增强型扫描器，在信任一个真正全新或高权限的技能之前进行更深入的一次性审查。

### 最接近的对比：NVIDIA SkillSpector

SkillSpector 是架构上最相似的项目——同样的“安装前扫描”框架，同样的 SARIF/JSON 输出方案，并有已发表的经验研究支持（扫描了 42,447 个技能，26.1% 存在漏洞）。

| | **SkillsGuard** | **NVIDIA SkillSpector** |
|---|---|---|
| 运行时依赖 | 无 — Node ≥18.3，零 npm 依赖 | Python ≥3.12 |
| 检测方法 | 静态正则，解码优先 | 静态 + 可选 LLM 语义分析 |
| 规则数量 | 151 条规则 / 15 个类别 | 64 个模式 / 16 个类别 |
| 依赖 CVE 查询 | 否 | 是 — 实时 OSV.dev 查询 |
| 安装 | `npm link` 或通过免费托管 curl API 零安装 | `pip install` / git clone |
| Pre-commit 钩子 | 是 — `install-hook`，带基线工作流 | 工作流文档中未包含 |
| Git diff / 暂存文件模式 | 是 — `--diff`, `--staged` | 工作流文档中未包含 |
| SARIF 输出 | 是 | 是 |
| MCP 服务器 | 是 — `scan_skill`, `scan_skills_dir`, 可教学的 `SKILL.md` | 不适用（基于 LangGraph 的流水线） |
| 成熟度（撰写时） | v1.1.1 | v2.0.0，5.5k+ GitHub 星标，已发表论文 |

**客观评价：** SkillSpector 拥有更多研究背景，其 LLM 语义阶段能够捕获正则无法捕捉的意图级别问题——例如，一个声称格式化代码但静默读取 `~/.ssh` 的技能。如果这一额外推理层对你来说比保持无依赖更重要，那么它是一个强有力的选择。值得用两者扫描同一个技能并比较结果，而不是盲目选择一个。

---

## 为什么选择 SkillsGuard

AI 代理技能包（`SKILL.md` + 捆绑脚本）是一个新的且基本上未经过审计的攻击面。恶意技能可以：

- **注入提示** 以覆盖 Claude 的指南或劫持其角色
- **外泄秘密** — API 密钥、SSH 密钥、云凭证 — 通过 curl 或 WebSockets
- **执行任意命令** 使用 eval、subprocess 或 child_process
- **持久化** 通过写入 cron 作业、systemd 单位或修改 shell 启动文件
- **提升权限** 通过 sudo stdin、chown root 或 setuid 调用
- **混淆** 以上所有内容，通过 base64 或十六进制编码来逃避那些简单的扫描器

SkillsGuard 静态扫描技能目录——无需执行，无需沙箱——并在 AI 代理读取文件之前捕获这些模式。它还会**解码混淆的 blob**（base64、十六进制、URL 编码，递归地），因此双重编码的有效载荷无法隐藏。

零运行时依赖。可在任何安装 Node ≥18.3 的系统上运行。

---

## 功能特性