cognis-digital/skillvet

Agent skill 和 MCP server 是你交给助手的代码 —— 它们可以访问你的文件、你的 token 以及一个 shell。人们从 gist 或市场安装它们并且*全凭感觉去信任*。skillvet 就是缺失的供应链检查：将其指向一个包，它就会在该代码接触到你的 agent 之前，静态地暴露出每一个危险的能力。 ``` pip install skillvet skillvet vet ./some-downloaded-skill ``` 零运行时依赖，完全离线，从不执行该包。退出代码可作为 CI/预安装的闸门：`0` TRUST，`1` REVIEW，`2` BLOCK。 ## 查看运行效果 一个读取你的 SSH key、将其外传、执行 shell 命令、隐藏 base64 payload 并运行 `curl | sh` 安装钩子的 skill。skillvet 将凭证读取与网络流出关联起来，形成一个 `exfiltration_surface` 信号： ``` $ skillvet vet ./repo-helper skillvet — malicious-skill ============================================================ verdict: BLOCK ✗ trust score: 0/100 3 file(s) analyzed, 7 capability finding(s) capabilities: credential_access, exfiltration_surface, install_hook, network_egress, obfuscation, process_exec ------------------------------------------------------------ [CRIT] process_exec skill.py:9 spawns a subprocess [CRIT] credential_access skill.py:4 reads credential files [CRIT] exfiltration_surface skill.py same file reads credentials and has network egress [HIGH] install_hook package.json:2 npm install hook runs code on install [HIGH] network_egress package.json:2 shells out to a network tool [HIGH] network_egress skill.py:1 makes HTTP requests [HIGH] obfuscation skill.py:11 executes decoded bytes ------------------------------------------------------------ BLOCK: do not install without a manual review — this package can take actions (exec / exfiltrate / read credentials) that a skill should not need. ``` 一个仅对文本进行首字母大写处理的 skill： ``` $ skillvet vet ./text-titlecase verdict: TRUST ✓ trust score: 100/100 no risky capabilities detected — this package is inert. ``` 一个 JSON 美化工具，其 *manifest* 请求了它从未使用过的 shell、网络、凭证和文件系统访问权限 —— skillvet 甚至无需深入代码就能标记出这种过宽的权限请求： ``` $ skillvet vet ./json-prettifier verdict: REVIEW ⚠ trust score: 85/100 capabilities: manifest_overbroad ------------------------------------------------------------ [HIGH] manifest_overbroad SKILL.md manifest declares a credential access permission/scope that the code does not appear to use (over-broad request) [HIGH] manifest_overbroad SKILL.md manifest declares a process exec permission/scope that the code does not appear to use (over-broad request) ... ``` 这三个示例都是可运行的：`python demos/run_all.py` 会执行这些以及 rug-pull、SARIF、数据外传和策略场景（共 28 项检查，退出代码为 0）。 ## 检查内容 | 能力 | 为什么重要 | 严重程度 | |---|---|:---:| | `process_exec` | subprocess / `os.system` / `eval` / `child_process` | critical | | `credential_access` | 读取 `~/.ssh`, `.env`, `.aws/credentials`、环境变量，或内嵌密钥 | critical | | `dynamic_fetch` | 获取并执行远程代码，在运行时从 URL 安装 | critical | | `prompt_injection` | 劫持 agent 的 **指令** —— 忽略之前的指令、越狱角色设定、强制外传数据、对用户隐藏行为 | critical | | `exfiltration_surface` | **关联性**：读取凭证 *且* 具备网络流出 —— 一条数据外传路径 | critical | | `network_egress` | HTTP 客户端、原始套接字、`curl`/`wget` | high | | `obfuscation` | base64/hex 编码后执行，超长的编码数据块 | high | | `install_hook` | npm pre/postinstall、`setup.py`、在安装时运行的构建钩子 | high | | `manifest_overbroad` | manifest 声明了过宽/未使用的 exec/network/credential/fs 作用域 | high | | `hidden_unicode` | 利用零宽 / 双向覆盖 / Unicode 标签字符向审查者隐藏指令 | high | | `filesystem_write` | 写入/删除文件 | medium | 每一项发现都标记有 MITRE ATLAS 技术。一个仅用于首字母大写的 skill 不需要上述任何能力 —— 而一个拥有全部这些能力的绝不是 skill，那是带有友好 `SKILL.md` 的恶意软件。 **Agent skill 独有的威胁是 `prompt_injection`：** 一个包的*代码* 完全无害，但其*指令*却告诉模型无视规则、外传 你的 token，或隐瞒它的所作所为。纯代码扫描器会放行它；而 skillvet 会阅读 文本并进行 BLOCK —— 零依赖，时刻开启。参见 `demos/prompt-injection-skill`。 ## 核心特性 - **Rug-pull 检测** —— 为你信任的 skill 记录一个[基线](docs/RUG-PULL.md)，然后将更新与之进行 `diff`。在“更新”时出现新的危险能力就是 rug-pull 的信号；`diff` 会以 `2` 退出。 - **SARIF 2.1.0 输出** —— `-f sarif` 让 skillvet 成为 CI 原生的[代码扫描器](docs/SARIF.md)：每种能力对应一条规则，带有 ATLAS 标签，适配 GitHub 代码扫描。 - **Manifest / 权限审查** —— 解析 `SKILL.md` frontmatter、`package.json`、MCP `mcp.json` 和 `pyproject.toml`，查找过宽或声明了但未使用的权限。 - **数据外传面关联分析** —— 一个既读取凭证又回传数据的包，其评分会比只具备单一行为的包更糟。 - **可调策略** —— 通过[策略文件](docs/POLICY.md)为你的环境调整权重、阈值以及基于能力的允许/拒绝规则。 ``` skillvet vet ./skill -f sarif > skillvet.sarif # CI code-scanning skillvet baseline ./skill -o baseline.json # record what you trust skillvet diff baseline.json ./skill # did the update rug you? skillvet vet ./skill --policy policy.json # tune the gate ``` ## 使用方法 ``` skillvet vet ./skill # analyze a package directory skillvet vet ./skill -f json # machine-readable skillvet vet ./skill -f sarif # SARIF 2.1.0 for CI code-scanning skillvet vet ./skill --policy p.json # tune weights/thresholds/allow-deny skillvet vet ./skill --baseline b.json # also rug-pull check against a baseline skillvet baseline ./skill -o b.json # record a fingerprint of a package you trust skillvet diff b.json ./skill # what changed since the baseline ``` 退出代码可作为 CI/预安装的闸门：`0` TRUST，`1` REVIEW，`2` BLOCK。如果发生 rug-pull，`diff` 会以 `2` 退出。 **作为预安装闸门：** ``` skillvet vet "$SKILL_DIR" || { echo "skill failed trust gate"; exit 1; } ``` ## 安装 (Windows / macOS / Linux) 核心代码仅依赖标准库 —— 无需编译，无需拉取额外内容。 ``` pip install skillvet # from PyPI # 或者从 clone： ./install.sh # macOS / Linux (./install.sh --content for shrike scan) ``` ``` .\install.ps1 # Windows PowerShell (.\install.ps1 -Content for shrike scan) ``` ``` make install # or via Makefile: install / test / demos / smoke docker build -t skillvet . && docker run --rm -v "$PWD/skill:/scan:ro" skillvet vet /scan ``` 已在 Linux、macOS 和 Windows 上的 Python 3.10 / 3.11 / 3.12 环境下完成测试。所有文件 I/O 均采用 UTF-8； 路径使用 `pathlib`/`os.path` 并规范化为正斜杠以便于显示和生成指纹。 **更深入的内容扫描：** 安装 `content` 额外依赖，以通过 [shrike](https://github.com/cognis-digital/shrike) 扫描该 skill 的文本是否存在 prompt 注入 / 工具投毒（tool poisoning）： ``` pip install "skillvet[content]" skillvet vet ./skill # now also flags poisoned SKILL.md / tool descriptions ``` ## 文档 - [工作原理](docs/how-it-works.md) —— 流水线一览 - [架构](docs/ARCHITECTURE.md) —— 能力模型、评分、威胁模型 - [Rug-pull 检测](docs/RUG-PULL.md) —— 基线与 diff 工作流 - [SARIF 输出](docs/SARIF.md) —— CI 代码扫描集成 - [策略](docs/POLICY.md) —— 为你的环境调整闸门规则 ## 为什么是静态、为什么是离线 skillvet **从不执行** 包 —— 这正是预安装闸门的意义所在。它读取 文件并报告其能力。它完全离线运行，因此你可以在气隔机器上审查 skill， 在它接触到存有你凭证的设备之前。 ## 与 shrike 搭配使用 - **[skillvet](https://github.com/cognis-digital/skillvet)** —— 在你安装 skill/插件*之前*对其进行审查（本仓库） - **[shrike](https://github.com/cognis-digital/shrike)** —— 审计已接入你技术栈的 MCP server，以及 skillvet 的 `content` 额外依赖在扫描 skill 文本时所使用的 AI 威胁特征库 ## 防御性使用 skillvet 是一款防御性静态分析器。它读取包并报告能力；它不会 执行它们或攻击任何东西。请使用它来决定什么是可信的。 ## 许可证 [COCL 1.0](LICENSE)。参见 [DISCLAIMER.md](DISCLAIMER.md)。

标签：AI智能体, DNS 反向解析, SOC Prime, StruQ, 云安全监控, 开发工具, 网络信息收集, 请求拦截, 逆向工具, 静态分析