stella/skillguard

# SkillGuard SkillGuard 是一个本地优先的安全扫描器和针对 Agent Skills 的策略门禁。 它被设计为在安装第三方 skill 之前运行。 SkillGuard 不是一个认证系统。它是一个确定性的 lint 和策略 引擎，用于在安装前捕获高风险的 skill 行为。 状态：alpha。该扫描器作为本地安装门禁和 CI 信号非常有用，但 它并不能证明一个 skill 是安全的。 ## 目标 - 扫描 skill 目录而不执行 skill 代码。 - 默认离线工作。 - 为安装程序和 CI 生成稳定的 JSON 和 SARIF 报告。 - 保持扫描器通用，同时允许产品强制执行更严格的策略。 - 在 CLI 端保持 Bun 优先，并在核心代码中使用可移植的 TypeScript。 ## 快速开始 ``` bunx @stll/skillguard scan ./skill --preset strict --policy strict ``` 扫描本地目录、zip 文件、Git URL 或直接 URL。远程输入需要 显式开启网络访问权限： ``` bunx @stll/skillguard scan https://github.com/org/skill --allow-network ``` 通过克隆仓库尝试测试固件： ``` bun install bun --filter @stll/skillguard skillguard scan ./fixtures/malicious ``` JSON 输出： ``` bunx @stll/skillguard scan ./skill \ --preset strict \ --policy strict \ --format json ``` Markdown 输出： ``` bunx @stll/skillguard scan ./skill \ --format markdown \ --output skillguard-report.md ``` SARIF 输出： ``` bunx @stll/skillguard scan ./skill --format sarif --output skillguard.sarif ``` ## 预设 `--preset` 控制扫描广度。`--policy` 控制哪些严重程度会导致 安装门禁失败。保持这些调节选项独立：广泛的扫描仍然可以使用咨询性策略， 而快速扫描依然可以针对中等风险的发现报告失败。 | Preset | 用途 | | --- | --- | | `quick` | 用于安装门禁的高可信度本地检查。 | | `standard` | 默认。增加依赖规范性、危险代码、污点流和输出处理检查。 | | `strict` | 增加较低可信度的行为检查：过度自主性、记忆投毒、工具误用、触发器滥用以及 MCP/工具元数据投毒。 | | `paranoid` | 增加恶意软件/攻击性工具指示器、常规网络使用发现、离线依赖建议回退，以及设置 `--allow-network` 时的 OSV 查询。 | 示例： ``` skillguard scan ./skill --preset quick --policy standard skillguard scan ./skill.zip --preset strict --policy strict skillguard scan https://github.com/org/skill --preset paranoid --allow-network ``` ## 语义审查 语义审查是可选的，并且默认关闭。它会向 OpenAI 兼容的模型提供程序发送一个受限且脱敏的 候选 skill 审查数据包，并将 响应转化为 `skillguard.semantic-review` 下标准的 SkillGuard 发现报告。 它需要显式开启网络访问权限： ``` skillguard scan ./skill \ --preset paranoid \ --policy strict \ --allow-network \ --semantic \ --semantic-provider openai ``` 配置： - `OPENAI_API_KEY` 或 `SKILLGUARD_SEMANTIC_API_KEY` - `SKILLGUARD_SEMANTIC_MODEL` 或 `--semantic-model` - `OPENAI_BASE_URL`、`SKILLGUARD_SEMANTIC_BASE_URL` 或 用于兼容 OpenAI 端点的 `--semantic-base-url` 请勿在包含不相关用户文档或机密信息的广泛工作区根目录上运行语义审查。 仅扫描待评估的第三方 skill 包。 ## 包 - `@stll/skillguard-core`：遍历、报告类型、策略评估、规则运行时。 - `@stll/skillguard-rules`：内置确定性规则。 - `@stll/skillguard-sarif`：SARIF 2.1.0 报告转换。 - `@stll/skillguard`：Bun 优先的 CLI 和 TanStack Intent skill。 `@stll/skillguard` 包还在 `skills/security-scan/SKILL.md` 中附带了一个 TanStack Intent skill， 因此能够发现包内置 skill 的 agent 可以 在安装第三方 skill 之前调用 SkillGuard。 ## 公共规则目录 `@stll/skillguard-rules` 导出 `RULE_CATALOG`，这是内置规则集中 64 个稳定 模式 ID 的文档化目录。当特定模式匹配时，发现报告会通过 `finding.metadata.pattern` 包含这些 ID，因此安装程序和 CI 可以抑制、解释或路由发现报告，而无需仅依赖文字描述。 ## 安全默认设置 - 不执行 skill 代码。 - 除非设置 `--allow-network`，否则不进行任何网络调用。 - 不跟随符号链接。 - 具有文件数量、文件大小、总字节数和深度限制。 - 仅进行文本扫描；对二进制文件进行指纹识别并跳过。 - 标记包安装脚本。 - 远程 Git/URL 输入需要 `--allow-network`。 - 本地 zip 解压会阻止 zip-slip 路径。 ## 当前分析器覆盖范围 SkillGuard 的灵感来源于 NVIDIA 基于 Python 的 [SkillSpector](https://github.com/NVIDIA/SkillSpector)，但它并不是 逐行的移植。它针对 Bun 优先的扫描器，在合理的地方实现了相同的安装门禁类别： - prompt injection 和隐藏指令； - system prompt 泄露； - 有害内容； - 数据泄露和机密访问； - 权限提升； - 供应链风险、包生命周期脚本、依赖规范、npm/PyPI lockfile 发现、离线建议回退以及可选的 OSV； - 危险的 Python/JavaScript/TypeScript/shell 执行构造； - 源到 sink 的污点流启发式分析，包括 Python 和 JavaScript/TypeScript 的结构化文件内赋值跟踪； - 输出处理； - 过度自主性； - 记忆投毒； - rogue-agent 持久化和自我修改； - 触发器滥用； - MCP 最小权限和工具元数据投毒； - 恶意软件/攻击性工具指示器。 有意推迟的部分是原生的 YARA 规则执行。由提供商支持的 语义分析是存在的，但它是明确的可选开启项，因为它会将候选的 skill 内容发送给模型提供商。 ## AST 分析 AST 的意思是“抽象语法树”：扫描器将源码解析为语法树， 并在不运行代码的情况下检查其 结构。这可以捕获纯文本匹配可能会遗漏的行为，例如 `exec(requests.get(...))`、 `subprocess.run(...)`、`eval(await fetch(...))`，或者即使空格或格式发生改变也能捕获 被别名的 `child_process.exec(...)` 调用。 SkillGuard 使用原生的 TypeScript 解析器来进行 Python 和 JavaScript/TypeScript 分析，因此 Bun 优先的包不需要安装语言运行时， 也不执行候选的 skill 代码。 ## 测试固件 `fixtures/` 语料库包含了回归测试使用的良性、恶意和规避性 skill。 良性固件预期在面临高风险 发现时保持安静；恶意和规避性固件涵盖了安装 hook、机密/文件 泄露、Python 和 JavaScript/TypeScript 污点流、编码执行 以及隐藏的 Unicode。 ## CI 请参阅 [docs/github-action.md](docs/github-action.md) 了解严格门禁和 SARIF 上传示例。 请参阅 [docs/release.md](docs/release.md) 了解 npm 发布顺序和发布 验证清单。 ## 开发 类型检查始终通过 `scripts/tsc-native.ts` 运行原生的 TypeScript 7 编译器。 经典的 TypeScript 6 仍然被安装，仅用于 规则解析器和 `eslint-plugin-sonarjs` 所使用的编译器 API； 工具链策略测试会阻止包脚本回退到其 `tsc` 二进制文件。 ``` bun install bun run lint:ws bun run typecheck bun run lint bun run format:check bun run test bun run knip bun run build bun --filter @stll/skillguard intent:validate bun run pack:verify ```

标签：API接口, GraphQL安全矩阵, SARIF, TypeScript, 安全扫描器, 安全插件, 暗色界面, 策略引擎, 网络信息收集, 网络安全挑战, 自动化攻击, 错误基检测, 零日漏洞检测, 静态代码分析