skillguard

安装

# npm -- JavaScript/TypeScript CLI + library
npm install --save-dev skillguard-cli

# PyPI -- Python CLI + library, a genuine port, not a wrapper around the Node binary
pip install skillguard-cli

这两种安装方式在扫描时都不会获取任何内容：所有十个规则包和模式匹配引擎均随 npm tarball 和 Python wheel 一同打包。

立即试用

npx skillguard-cli scan ./examples/known-bad-skill

此命令会对仓库中捆绑的样例进行扫描。该样例安全、无实际功能，并刻意设计为可被模式匹配；扫描大约在 0.15 秒内返回 11 个真实发现项，并附有文件:行号引用。

说明

每次扫描都会先向 stderr 输出 Loading SkillGuard rule packs...。这是预期的启动输出，并非卡住。

将其与干净的样例进行比较：

npx skillguard-cli scan ./examples/clean-skill

此时会返回零个发现项，退出代码为 0。

为什么需要它

第三方 Agent 技能安装后便会立即获得实际的工具、文件和网络权限，却几乎没有任何机制会在此之前检查它们。Snyk 的 ToxicSkills 研究于 2026 年 2 月扫描了 3,984 个公开列出的技能，发现其中 36% 存在安全缺陷，包括 76 个携带已确认恶意载荷的技能：凭据窃取、反向 Shell、数据外泄。大多数市场和 Agent 框架都没有扫描步骤来检查“有人发布了某项技能”与“用户的 Agent 运行该技能”之间的环节。SkillGuard 就是这个环节：它提供 CLI、库、MCP 服务和 GitHub Action，均读取同一组捆绑的十个规则包。

功能

• 十个专用规则类别（SG01-SG10），涵盖网络不匹配、远程代码执行、文件范围权限提升、钩子供应链风险、混淆载荷、凭据窃取、frontmatter 范围伪造、嵌入在技能自身指导文本中的提示词注入、跨技能权限链，以及市场中的仿冒拼写。每个类别都在 CHANGELOG.md 中逐条记录。
• **跨技能权限链（scan-set）**能发现单技能扫描器在结构上会漏掉的威胁：技能 A 读取敏感文件，技能 B 可以访问网络，二者之间都未声明沙盒隔离，因此组合起来就能外泄技能 A 单独只能读取的数据。npx skillguard-cli scan-set ./my-skills-dir 会扫描目录中的所有技能，并标记这种组合。Snyk Agent Scan 的维护者在 issue #301 中确认，其 --skills 标志一次只能识别一个 SKILL.md，而且根本不会递归查找目录中的技能。因此，这不是 SkillGuard 声称做得更好的功能，而是我们发现目前其他技能扫描器都还不具备的功能。
• 无需身份验证，也无需配置。npx skillguard-cli scan <path> 无需账号、API 令牌或注册。相比之下，Snyk Agent Scan 需要 SNYK_TOKEN 和 Snyk 账号，Socket CLI 则需要 SOCKET_CLI_API_TOKEN 才能使用完整功能。
• 不仅能作为 CLI 调用，还能作为 MCP 工具调用。npx skillguard-cli mcp 会启动一个 stdio MCP 服务，并提供 scan_skill 工具，让 Claude Code、Cursor 或任何编排 Agent 都能在安装或运行下载的技能前，通过工具调用对其进行扫描，无需启动子进程，也无需解析 stdout。已通过与构建后的服务进行真实的 JSON-RPC initialize / tools/list / tools/call 握手验证。
• **两种独立维护、同等维护力度的发行版本。**npm 包和 PyPI 包读取相同的规则包契约，并针对同一目标得出一致的发现结果；二者互不包装。
• **扫描时不会从网络获取任何内容。**所有规则包都随包一同发布，因此扫描不可信内容时，绝不会访问由该内容控制的任何对象。

快速入门

npx skillguard-cli scan ./my-skill --format json --severity-threshold MEDIUM

import { scanSkill } from 'skillguard-cli';

const result = await scanSkill('./my-skill', { severityThreshold: 'HIGH' });
if (result.exitCode === 1) {
  console.log(`${result.findings.length} finding(s) at or above HIGH`);
}

from skillguard import scan_skill, ScanOptions

result = scan_skill("./my-skill", ScanOptions(severity_threshold="HIGH"))
if result.exit_code == 1:
    print(f"{len(result.findings)} finding(s) at or above HIGH")

命令

npx skillguard-cli <command> [options]
# Python: skillguard <command> [options]

命令	功能
scan <path>	扫描一个技能目录（包含一个 SKILL.md 及其钩子/脚本），查找已知攻击模式。
scan-set <dir>	扫描一个目录，其中每个直接子项都是一个技能目录；对每个子项运行 scan，并额外检查集合内跨技能权限链（SG09）。
mcp	将 SkillGuard 启动为 stdio MCP 服务，向其他 Agent 暴露可调用的工具 scan_skill。参见 MCP 服务。

scan 和 scan-set 共用的标志（已根据 src/cli.ts 和 skillguard/cli.py 验证）：

标志	默认值	描述
--format <human|json|sarif>	human	输出格式。
--severity-threshold <HIGH|MEDIUM|LOW>	HIGH	导致扫描失败（退出代码为 1）的最低严重级别。
--timeout <ms>	10000	每个文件的扫描超时时间，单位为毫秒。
--skillguardignore <path>	无，必须显式传入	抑制文件的路径。不会从扫描目标内部自动加载；参见 抑制问题。
--allow-inline-suppression	false	启用扫描文件中的内联 # skillguard-ignore: SGxx 注释。默认关闭。

退出代码：0 扫描无问题。1 存在达到或超过严重级别阈值的问题。2 目标路径不存在，或（对于 scan）未找到技能文件。

API 参考

TypeScript（src/index.ts），从 npm 包的根导入路径重新导出：

import { scanSkill, scanSkillSet, discoverSkillDirs, computeCrossSkillFindings } from 'skillguard-cli';

scanSkill(path: string, options?: ScanOptions): Promise<ScanResult>
scanSkillSet(dir: string, options?: ScanOptions): Promise<SkillSetScanResult>

scanSkill() 运行与 scan 相同的扫描逻辑；scanSkillSet() 运行与 scan-set 相同的逻辑。两者都会返回结构化结果（findings、timeouts、warnings、exitCode），而不会抛出异常，因此调用方在嵌入 SkillGuard 时，无需仅为了获取判定结果就用 try/catch 包裹调用。随包提供的类型还包括 Finding、ScanOptions、ScanResult、ScanWarning、Severity、OutputFormat、RuleCategory、SkillEntry 和 SkillSetScanResult。

Python（python/src/skillguard/__init__.py）：

from skillguard import scan_skill, scan_skill_set, discover_skill_dirs, compute_cross_skill_findings, ScanOptions

scan_skill(path: str, options: ScanOptions | None = None) -> ScanResult
scan_skill_set(dir: str, options: ScanOptions | None = None) -> SkillSetScanResult

功能相同，命名采用 snake_case。需要如实说明一个差异：Python 包的 scan_skill_set() 运行与 npm 包的 scanSkillSet() 相同的跨技能链检查流程，但 npm 包还会在普通的单技能 scan 中额外运行一个更窄的 SG09 检查（同级路径引用启发式，src/ast/cross-skill-chaining.ts），Python 目前尚无对应实现。如果你依赖单次 scan 调用而非 scan-set 来检测跨技能问题，目前该路径仅支持 TypeScript。

MCP 服务（Agent 原生、工具调用）

npx skillguard-cli mcp

将 SkillGuard 作为 stdio MCP 服务启动，并公开一个工具 scan_skill（{ path, severityThreshold?, timeoutMs? }），供其他 Agent、Claude Code、Cursor 或编排器在安装或运行第三方技能之前，直接通过工具调用进行扫描。本次更新通过真实握手验证：initialize 返回真实的服务信息，tools/list 返回真实的 scan_skill 架构，针对 ./examples/known-bad-skill 的 tools/call 返回与 CLI 报告相同的 11 项发现。客户端配置示例：

{ "mcpServers": { "skillguard": { "command": "npx", "args": ["skillguard-cli", "mcp"] } } }

完整的设置说明、工具的输入／输出架构，以及此路径保留的安全保障（与 CLI 使用相同的 .skillguardignore／内联抑制默认值，且无法通过工具传入忽略路径），请参阅 docs/integrations/mcp.md。Python 包通过 skillguard mcp 提供相同的工具（需要可选的 mcp extra，pip install "skillguard-cli[mcp]"，Python >=3.10）：原生且进程内运行，直接调用 scan_skill()，无需子进程，也不会暴露 stdout／JSON 解析接口。uvx 无需手动安装即可运行，这是将其接入 Claude Desktop 的推荐方式：

{
  "mcpServers": {
    "skillguard": {
      "command": "uvx",
      "args": ["--from", "skillguard-cli", "skillguard", "mcp"]
    }
  }
}

GitHub Action

- name: SkillGuard
  uses: RudrenduPaul/skillguard@main
  with:
    path: ./my-skill
    severity-threshold: HIGH

Action 默认使用 --format sarif，并将结果直接上传到 GitHub 代码扫描。裸 CLI 默认输出便于人工阅读的内容，因为终端和 CI 日志各有不同需求。

规则包

每个规则包都位于 rulepacks/（npm）和 python/src/skillguard/rulepacks/data/（Python）下，需手动保持同步，并遵循 CONTRIBUTING.md 中的平行性规则。扫描时不会通过网络获取任何内容。

类别	名称	严重性	检测内容
SG01	网络不匹配	MEDIUM	原始套接字、netcat、/dev/tcp，以及绕过常见纯 HTTP 范围限制的网络原语。
SG02	远程代码执行	HIGH	curl | bash、对获取的响应调用 eval()／exec()，以及使用受远程内容影响的内容调用 shell。
SG03	文件范围越权	MEDIUM	写入／删除／chmod 操作超出技能自身目录的范围，以及用于逃逸的路径遍历（../../..）。
SG04	钩子供应链	HIGH	安装时钩子或依赖项获取并运行远程代码，或固定到可变分支。
SG05	混淆载荷	LOW	用于隐藏载荷的 base64／字符串拼接／动态 Function 惯用写法。请参阅下文的已知限制。
SG06	凭据窃取	HIGH	读取类似凭据的环境变量或凭据文件，尤其是在网络调用附近。
SG07	frontmatter 欺骗	MEDIUM	SKILL.md 声明的网络／文件系统范围与钩子／脚本实际执行的操作不一致。
SG08	通过技能内容进行提示词注入	HIGH	SKILL.md 中的指令文本试图覆盖宿主 Agent 的系统提示词，或劫持其工具路由（7 个规则 ID：sg08-ignore-prior-instructions、sg08-disregard-system-prompt、sg08-fake-mode-switch、sg08-reveal-system-prompt、sg08-hide-action-from-user、sg08-hidden-unicode-characters、sg08-encoded-block-in-instructions）。
SG09	跨技能权限链式利用	HIGH	在 scan-set 运行中组合两个技能的能力：一个具有 sensitive-filesystem-read，另一个具有 network-egress，且两者之间没有沙箱隔离。TypeScript 也会对单个技能运行此检查的范围更窄的同级路径变体；Python 目前仅提供 scan-set 版本。
SG10	市场平台名称仿冒	HIGH	SKILL.md 声明的名称与内置的 51 个热门 npm／PyPI 包名称列表之间的 Levenshtein 编辑距离为 1–2，可能是为了冒充知名工具。

SG05 已知限制：纯静态分析下的混淆检测，其漏报率明显高于其他类别。SG05 可检测已知的常见编码／eval 惯用写法；应将其视为尽力覆盖，而非混淆检测的完整方案。

SkillGuard 的对比

SkillGuard 专为 Agent 技能威胁模型而构建，关注前置元数据声明的范围与实际行为之间的差异、钩子层面的供应链风险、跨技能权限组合，以及技能打包和安装方式特有的凭据窃取模式。这项工作比通用扫描器的职责范围更窄。下表对此有直白说明，而不会暗示 SkillGuard 胜过那些为不同任务而构建的工具。

	SkillGuard	Snyk Agent Scan	Semgrep (CE)	Socket CLI
扫描对象	Agent 技能文件：SKILL.md、钩子、脚本	Agent 技能和 MCP 服务配置	通用源代码，支持 30 多种语言	npm/PyPI 等包的安装
专用于 Agent 技能的规则集	是，全部 10 个类别均针对这一威胁模型专门构建	是，其全部重点所在（提示词注入、工具投毒、有毒流、技能恶意软件）	否，仅通用 SAST 规则	否，侧重供应链，而非技能文件
一次扫描多个技能，以检查组合风险	是，scan-set（SG09 跨技能权限链式组合）	否，根据 issue #301 确认仅支持单文件／非递归扫描	不适用于此威胁模型	不适用于此威胁模型
可作为 MCP 工具供其他 Agent 调用	是，skillguard-cli mcp	未公开说明	否	否
基础扫描是否需要身份验证	不需要（npx skillguard-cli scan <path>）	需要 Snyk 账户和 SNYK_TOKEN	Community Edition 本地扫描不需要	完整功能需要 SOCKET_CLI_API_TOKEN
运行时	Node.js，无外部二进制文件（也提供 Python 移植版）	通过 uvx 使用 Python	自有二进制文件（基于 Python 的命令行工具）	Node.js
许可证	Apache 2.0	Apache 2.0	LGPL-2.1	MIT（根据 socket npm 软件包页面；代码库本身没有 LICENSE 文件）
GitHub 星标数（截至 2026-08-10）	1 个星标，发布约一个月，发布于 2026-07-11	2,897 个星标，258 个复刻	16,173 个星标，1,021 个复刻	311 个星标，58 个复刻

坦诚说明几点。安全工具的可信度，取决于是否敢于直言不讳地说出那些不那么好听的部分：

• Snyk Agent Scan 是最接近的真正竞争者，也更成熟（2,897 个星标，而 SkillGuard 只有 1 个），覆盖范围也更广（15 个以上的检测类别，还能扫描 MCP 服务配置，而 SkillGuard 不支持）。真正的差异在于身份验证方式（SkillGuard 无需注册或令牌）以及跨技能分析（Snyk 的维护者已确认，其工具目前仅处理单个文件）。如果你已有 Snyk 账户，也希望覆盖 MCP 服务，那么 Agent Scan 覆盖面更广；如果你想要无需身份验证的检查，同时还能分析整个技能目录，那么 SkillGuard 正是为此而设计。
• **SkillGuard 并未封装 Semgrep。**它使用自有的小型进程内模式引擎（受 Semgrep 启发，但并非 Semgrep），因此 npx 安装不会依赖 Python/PyPI 工具链。如果你需要真正支持多语言、覆盖 30 多种语言的通用静态分析，Semgrep 是更成熟的选择。
• **Socket CLI 属于相邻类别，并非直接竞争者。**它专门检测 npm/PyPI 软件包中的拼写仿冒和恶意安装脚本，而非技能自身 SKILL.md 中的前置元数据，以及声明行为与实际行为之间的差异。
• SkillGuard 本身确实还处于早期阶段：GitHub 上只有 1 个星标，首次提交至今约一个月。这是一个真实的“尚早但已落地”的项目现状，不值得粉饰：本 README 展示的每条命令和每项发现，都是编写时针对当前实际代码运行得出的，并非从旧草稿中照搬而来。

什么是 SkillGuard，它为何存在

SkillGuard 是一款静态分析扫描器，用于扫描第三方 AI Agent 技能文件、SKILL.md 清单及其打包的钩子和脚本，可在安装或执行不受信任的技能之前运行。它之所以存在，是因为技能市场和框架通常都没有自己的扫描步骤：某个技能可以在前置元数据中声明 network: false，却仍附带一个 postinstall 钩子，在安装时立即将远程脚本传入 shell 执行，而大多数 Agent 运行时都不会检查声明的范围是否与实际行为相符。SkillGuard 可通过 CLI、库、MCP 服务和 GitHub Action 使用相同的十个规则包，因此同一项检查既可用于设置 CI 流水线门禁，也可在 Agent 自身的工具调用循环中运行，或直接通过代码调用。

忽略发现项

警告

SkillGuard 的用途是审核你 未 编写的目录。以下两种抑制机制都可以隐藏发现项，因此不会自动信任扫描对象中的任何一种。两者都需要运行扫描的人明确、有意地选择启用。

.skillguardignore 文件按 glob 忽略整个文件，使用方式与 .gitignore 类似：

# .skillguardignore
vendor/**
*.generated.js

只有在传入 --skillguardignore <path>（或使用库选项 ignoreFilePath）时才会启用此文件。SkillGuard 绝不会自行读取扫描目标中包含的 .skillguardignore。恶意技能提交即使包含自己的 .skillguardignore，也无法隐藏针对自身的发现项，除非你明确指定 SkillGuard 使用该文件。如果你维护自己的技能并希望忽略自身的发现项，请保留自己的 .skillguardignore，并明确传入其路径：

npx skillguard-cli scan ./my-skill --skillguardignore ./my-skill/.skillguardignore

行内注释 # skillguard-ignore: SG02（与匹配项位于同一行，或紧邻其上一行）可就地抑制单条发现项。此功能默认关闭，需要使用 --allow-inline-suppression 启用，原因相同：注释位于正在审核的确切不受信任内容中，因此默认情况下，扫描目标中的任何内容都不能隐藏针对自身的发现项。只有在你已信任某个目标时才启用，例如在发布前扫描自己的技能。

已知限制

SkillGuard 会主动公开说明自身的不足。除了上文 SG05 的漏报说明外，这里还需指出两点：符号链接形式的扫描目标不会跟随扫描，而是直接跳过；Python 包的跨技能检测目前仅存在于 scan-set 中，没有像 TypeScript 版本那样进行单技能的同级路径检查。完整列表（包括单一模式残留的 ReDoS 风险）见 CHANGELOG.md。在将 SkillGuard 接入你计划信任的 CI 门禁之前，请先阅读该文件。

开发

# TypeScript
npm install
npm run build
npm test

# Python
cd python
python3 -m venv .venv && source .venv/bin/activate
pip install -e ".[dev,mcp]"
pytest

请参阅 CONTRIBUTING.md：规则包变更必须同时提交到 rulepacks/ 和 python/src/skillguard/rulepacks/data/，并在两套测试中提供等效的测试覆盖，因为仅存在于一种语言中的规则会造成两个 CLI 之间的行为差异，且不易察觉。

常见问题

什么是 SkillGuard？它与通用安全扫描器有何不同？ SkillGuard 是一款静态分析扫描器，专为一种威胁模型打造：第三方 AI Agent 技能文件、SKILL.md 清单及其打包的钩子和脚本。它提供十类规则（SG01-SG10），用于检查通用扫描器默认不会检查的内容：前置元数据声明的范围与实际行为是否一致、安装时钩子的供应链风险、技能自身说明文本中嵌入的提示词注入，以及同一目录中多个技能带来的综合风险。像 Semgrep 这样的通用 SAST 工具可以发现一些相同的代码级模式，但它不了解 SKILL.md 清单，也不了解跨技能的权限关系。 SkillGuard 运行扫描是否需要账户或 API 令牌？ 不需要。npx skillguard-cli scan <path> 和 pip install skillguard-cli && skillguard scan <path> 都可以直接运行，无需注册、无需令牌，扫描时也不会发起网络请求。

SkillGuard 支持哪些平台和语言运行时？ npm 包需要 Node.js >=20（根据 package.json 的 engines 字段），且没有原生／编译型依赖。PyPI 包的基础安装需要 Python >=3.9；如果安装用于 MCP 服务模式的可选 mcp 扩展，则需要 Python >=3.10（根据 pyproject.toml 的 requires-python 和其中关于 mcp 可选依赖的注释）。这两个包都是纯语言包，无需针对操作系统进行构建；Python 包的分类器也声明了 Operating System :: OS Independent。

SG08、SG09 和 SG10 检查什么？它们也能通过 MCP 服务运行吗？ SG08（HIGH）会检查技能自身的指令文本中是否存在提示注入，试图覆盖宿主 Agent 的系统提示词或劫持其工具路由；该检查包含 7 个不同的规则 ID。SG09（HIGH）检查跨技能权限链：当目录中的一个技能具备敏感文件系统读取能力，另一个技能具备网络出口能力，且两者之间未声明沙箱隔离时，scan-set 会标记 HIGH 级别的问题；TypeScript 的普通 scan 也会运行同一检查的较窄版本，仅检查同级路径。SG10（HIGH）检查市场中的名称仿冒：技能声明的名称与内置列表中 51 个热门 npm／PyPI 包名的 Levenshtein 编辑距离为 1-2。通过 npx skillguard-cli mcp 的 scan_skill 工具运行时，这三项检查的行为与 CLI 完全一致，因为 MCP 服务会调用相同的底层扫描逻辑。

AI Agent 能否直接调用 SkillGuard，而不通过 shell 执行 CLI 再解析输出？ 可以。npx skillguard-cli mcp（或 Python 端的 skillguard mcp）会启动一个 stdio MCP 服务，并提供 scan_skill 工具，让编排器或编码 Agent 能在安装或运行下载的技能之前，将其作为普通工具调用进行扫描。

SkillGuard 能否检测引用了另一个权限更高技能的技能？ scan-set 可以：将其指向包含技能子目录的目录，当一个技能具备敏感文件系统读取能力，另一个技能具备网络出口能力，且两者之间未声明沙箱隔离时，它会标记 HIGH 级别的问题。这正是 Snyk Agent Scan 自身的问题追踪器确认其工具尚未覆盖的特定漏洞（仅扫描单个文件，不递归）。

npm 包和 PyPI 包有什么区别？ 两者是独立维护、维护力度相同的移植版本，读取相同的规则包契约，并针对同一目标生成一致的问题结果；PyPI 包是真正的 Python 实现，而不是 Node 二进制文件的包装器。目前两者有一处差异：TypeScript 的 scan 命令会额外运行一种同级路径跨技能启发式检查，而 Python 版本尚未实现（Python 的跨技能检测完全由 scan-set 负责）。如果你依赖单次 scan 调用而非 scan-set 进行跨技能检测，目前这项功能仅 TypeScript 版本支持；在 Python 端改用 scan-set 即可获得同等覆盖范围。

SkillGuard 能取代 Semgrep 或 Snyk 吗？ 不能。Semgrep 是一款成熟的通用静态分析引擎，支持 30 多种语言；Snyk 广泛覆盖依赖项和代码漏洞，而 Snyk Agent Scan 目前覆盖的 Agent 技能和 MCP 配置威胁范围也比 SkillGuard 更广。SkillGuard 的用途更窄：针对特定的 SKILL.md／hooks／frontmatter 威胁模型，无需身份验证，并提供这两款工具目前都尚未提供的跨技能检查。 SkillGuard 已准备好用于生产环境了吗？ 它还处于早期阶段：问世约一个月，尚未达到 1.0 版本，截至本文撰写时有 1 个 GitHub 星标。测试套件（157/157 个 TypeScript 测试、110/110 个 Python 测试）在全新安装后全部通过，本文中的每条命令也都已针对当前代码单独重新运行；但它尚未在大型真实语料库上测试过，因此其误报率和漏报率在大规模场景下仍未得到验证，不能视为已确定。

我可以将 SkillGuard 用于商业用途吗？许可证是否收费？ 可以，也不收费。SkillGuard 采用 Apache License 2.0（参见 LICENSE），允许免费用于商业用途、修改和再分发，包括用于专有软件中，但须保留版权和许可证声明。Apache 2.0 还明确授予贡献者的专利许可，而普通 MIT 许可证没有这一条款。

许可证

Apache 2.0，参见 LICENSE。