enkryptai/skill-sentinel

# Enkrypt AI Skill Sentinel 一款专为 Agent Skill 包设计的安全扫描器。Skill Sentinel 使用多 Agent AI 分析来检测隐藏在 Cursor、Claude Code、Codex 和 OpenClaw skill 包中的 prompt 注入、数据泄露、命令注入、恶意软件及其他威胁。 Agent Skills 通过自定义指令和脚本来扩展 AI 编程助手的功能——但它们也创建了新的攻击面。单个恶意 skill 就可以窃取凭证、注入隐藏的 prompt、泄露代码或执行任意命令。Skill Sentinel 会在这些威胁到达您的 agent 之前将其捕获。 ### 支持的平台

Cursor

Claude Code

Codex

OpenClaw

and other agents

## 核心功能 ### 🔍 多 Agent 安全流水线 专门的 Agent 协同工作，从多个角度分析 Skills——包括 manifest 检查、文件校验、交叉引用和威胁关联。 ### 🦠 内置恶意软件检测 自动集成 VirusTotal，在任何 LLM 分析开始之前，扫描二进制文件（可执行文件、压缩包、PDF）以查找已知恶意软件。 ### 📄 无截断限制 读取完整的文件内容，没有任意的截断——能够捕获隐藏在文档深处的恶意指令，而其他扫描器往往会停止深入查找。 ### 🔗 跨文件威胁关联 通过跟踪数据流并验证脚本行为是否与文档声明相符，检测跨越多个文件的复杂攻击。 ### 🎯 AI Agent 攻击检测 专为 AI 编程助手定制的检测机制，针对 prompt 注入、命令注入、凭证窃取及其他特定威胁。 ### ⚡ 并行批量扫描 并发扫描整个 Skills 目录并生成有组织的报告——只需一条命令即可审计您所有的 Cursor、Claude Code、Codex 和 OpenClaw Skills。 ## 安装说明 要求 Python >= 3.10, < 3.14。 ### 从 PyPI 安装 ``` pip install skill-sentinel ``` 或者使用 `uv`（推荐）： ``` uv pip install skill-sentinel ``` ### 从源码安装 用于开发或本地修改： ``` # Clone 仓库 git clone https://github.com/enkryptai/skill-sentinel.git cd skill-sentinel # 使用 uv 安装（推荐） uv venv --python 3.13 .venv source .venv/bin/activate uv pip install -e . # 或使用 pip 安装 pip install -e . ``` ## 快速开始 ``` # 1. Export 你的 OpenAI API key export OPENAI_API_KEY="sk-..." # 2. (可选) Export 你的 VirusTotal API key 以进行二进制恶意软件扫描 export VIRUSTOTAL_API_KEY="your-vt-api-key" # 3. 扫描 skill 目录 skill-sentinel scan /path/to/skill/directory ``` 或者，在项目根目录下创建一个 `.env` 文件，而不是通过 export 变量： ``` cp .env.example .env # 使用你的 keys 编辑 .env ``` ## 使用说明 ``` skill-sentinel scan [provider] [OPTIONS] Positional: provider cursor / claude / codex / openclaw to auto-discover that provider's skills, or omit to discover all. Can also be a direct path to a skill directory. Path flags (mutually exclusive): --skill PATH Scan a single skill directory. --dir PATH Scan all skill subdirectories inside a parent directory. Options: -o, --output PATH Single scan: output file (default: report.json). Multi-scan: output directory (default: ./skill_sentinel_reports). --parallel Scan multiple skills in parallel (5 concurrent). -m, --model MODEL OpenAI model to use (default: gpt-5.4-mini). --api-key KEY OpenAI API key (prefer OPENAI_API_KEY env var). -V, --version Show version and exit. ``` ### 示例 ``` # 扫描单个 skill 目录 skill-sentinel scan --skill ./my-skill skill-sentinel scan --skill ./my-skill -o report.json # 扫描父目录内的所有 skills skill-sentinel scan --dir ./all-my-skills/ skill-sentinel scan --dir ./all-my-skills/ -o ./reports/ # 并行扫描（5个并发） skill-sentinel scan --dir ./all-my-skills/ --parallel # 自动发现并扫描来自 cursor、claude、codex 和 openclaw 路径的所有 skills skill-sentinel scan # 仅并行自动发现 Cursor skills skill-sentinel scan cursor --parallel # 仅扫描 Claude skills skill-sentinel scan claude # 用于自动发现的自定义输出目录 skill-sentinel scan codex -o ./my-reports/ # 使用不同的 model skill-sentinel scan --skill ./my-skill -m gpt-4o ``` ### 自动发现 当未提供路径（或使用了提供商关键词）时，扫描器会在以下已知位置搜索包含 `SKILL.md` 的 skill 目录： | 位置 | 范围 | |---|---| | `.cursor/skills/` | 项目级 (Cursor) | | `.claude/skills/` | 项目级 (Claude) | | `.codex/skills/` | 项目级 (Codex) | | `skills/` | Agent 工作区级 (OpenClaw) | | `~/.cursor/skills/` | 用户全局级 (Cursor) | | `~/.claude/skills/` | 用户全局级 (Claude) | | `~/.codex/skills/` | 用户全局级 (Codex) | | `~/.openclaw/skills/` | 用户全局级 (OpenClaw) | 报告将保存为 `./skill_sentinel_reports/`（或通过 `-o` 指定的目录）下的 `__.json` 文件。 ### 编程方式使用 ``` from skill_sentinel.main import scan report = scan("/path/to/skill", output_path="report.json", model="gpt-5.4-mini") print(report["overall_risk_assessment"]["skill_verdict"]) ``` ## 工作原理 扫描器执行多步骤的安全分析： 1. **文件发现** — 列出 skill 目录中的所有文件（静态分析，不使用 LLM）。 2. **VirusTotal 二进制扫描** *（可选）* — 如果发现了二进制文件（可执行文件、压缩包、图像、PDF 等）并且设置了 `VIRUSTOTAL_API_KEY`，每个二进制文件都会通过 SHA-256 哈希值在 VirusTotal 的恶意软件数据库中进行校验。结果将传递给报告合成器。 3. **SKILL.md 分析** — 一个 Agent 读取 SKILL.md manifest 和指令，寻找 prompt 注入、信任滥用、发现滥用和其他威胁。 4. **文件校验** *（条件性）* — 如果 skill 包含脚本或 SKILL.md 之外被引用的文件，第二个 Agent 会读取每个文件并检查其与 SKILL.md 声明的一致性，搜索命令注入、数据泄露、硬编码 secrets、混淆等行为。 5. **报告综合** — 最终的 Agent 会整合所有发现（包括 VirusTotal 的结果），过滤误报，对发现的问题进行优先级排序，并生成结构化的 JSON 报告。 ### 恶意软件扫描 (VirusTotal) 如果设置了 `VIRUSTOTAL_API_KEY` 环境变量，Skill Sentinel 会自动使用 VirusTotal 的恶意软件数据库扫描在 skill 包中发现的二进制文件。这在 agent 流水线**之前**运行——不需要进行 LLM 调用。 **支持的二进制文件类型：** 可执行文件 (`.exe`, `.dll`, `.so`, `.dylib`, `.bin`)、压缩包 (`.zip`, `.tar`, `.gz`, `.7z`, `.rar`)、文档 (`.pdf`, `.doc`, `.xls`)、图像 (`.png`, `.jpg`, `.gif`)、JVM/WASM (`.jar`, `.war`, `.wasm`, `.class`) 等。 **获取免费 API 密钥：** 在 [virustotal.com](https://www.virustotal.com/) 注册——免费层级允许每天进行 500 次查询，这对于 skill 扫描来说绰绰有余。 ## 输出结果 扫描器会生成一个包含以下内容的 JSON 报告： - `skill_path` — 被扫描 skill 目录的绝对路径 - `validated_findings` — 已确认的威胁，包含严重程度、证据、修复建议 - `false_positives` — 已被驳回的发现及理由 - `priority_order` — 按优先级排序的发现 ID 列表 - `correlations` — 分组在一起的关联发现 - `recommendations` — 可执行的后续步骤 - `references` — VirusTotal 扫描链接和其他参考 URL - `overall_risk_assessment` — 风险级别、结论 (SAFE / SUSPICIOUS / MALICIOUS)、推理过程 - `token_usage` — 本次扫描的 LLM token 使用指标 ## 项目结构 ``` skill_scanner_package/ ├── pyproject.toml # Package build config ├── README.md └── src/skill_sentinel/ ├── __init__.py # Package version ├── cli.py # CLI entry point ├── main.py # Programmatic API ├── crew.py # Multi-agent crew definition ├── config/ │ ├── agents.yaml # Agent definitions │ └── tasks.yaml # Task definitions ├── data/ │ ├── threat_categories.md # Threat taxonomy │ └── report_schema.json # Output JSON schema └── tools/ ├── custom_tool.py # ReadFile & Grep tools ├── file_discovery.py # Static file listing └── virustotal_tool.py # VirusTotal binary malware scanning ``` ## 环境变量 | 变量 | 描述 | 默认值 | |---|---|---| | `OPENAI_API_KEY` | 您的 OpenAI API 密钥（必填） | — | | `OPENAI_MODEL_NAME` | 用于分析的模型 | `gpt-5.4-mini` | | `VIRUSTOTAL_API_KEY` | 用于二进制恶意软件扫描的 VirusTotal API 密钥（可选） | — | ## 威胁类别 Skill Sentinel 检测以下威胁类别，这些类别映射到 [OWASP Top 10 for LLM Applications 2025](https://genai.owasp.org/llm-top-10/) 和 [OWASP Top 10 for Agentic Applications](https://genai.owasp.org/agentic-top-10/)： | 类别 | 严重程度 | 描述 | |---|---|---| | Prompt 注入 | HIGH–CRITICAL | 隐藏在 SKILL.md 中的覆盖尝试、模式更改、策略绕过 | | 传递性信任滥用 | HIGH | 将信任委托给外部/不可信数据源的指令 | | 数据泄露 | CRITICAL | 窃取凭证、文件或环境变量的网络调用 | | 命令注入 | CRITICAL | 危险的 `eval()`, `exec()`, `os.system()`，shell 注入 | | 硬编码 Secrets | CRITICAL | 嵌入在代码中的 API 密钥、密码、私钥 | | 混淆 | HIGH | Base64 blob + exec，十六进制编码的 payload，故意写成的不可读代码 | | 未经授权的工具使用 | HIGH | 违反 skill 自身 `allowed-tools` 声明的代码 | | Skill 发现滥用 | HIGH | 品牌冒充、关键词诱饵、误导性描述 | | 工具链滥用 | HIGH | 读取敏感数据然后将其传输的多步骤工作流 | | 资源滥用 | MEDIUM | 无限循环、无限制的内存分配、递归炸弹 | | 自主性滥用 | MEDIUM | 未经请求的激活、无限制的重试、无需用户确认 | | 过度收集 | MEDIUM | 相对于声明的目的而言不成比例的数据访问 | | 跨上下文桥接 | MEDIUM | 访问来自其他会话、对话或工作区的数据 | | 依赖项风险 | MEDIUM | 未锁版本的 `pip install`、域名抢注、未知的 GitHub repo | | 恶意软件 | MEDIUM–CRITICAL | 被 VirusTotal 标记的二进制文件或无法验证的二进制文件 | ## 贡献指南 欢迎您作出贡献！通过提交 pull request 或其他贡献方式，即表示您同意我们的 [贡献者许可协议 (CLA)](CLA.md) 条款。请参阅 [CONTRIBUTING.md](CONTRIBUTING.md) 了解设置、项目结构以及如何提交 PR。 ## 许可证 本项目基于 [Apache License 2.0](LICENSE) 授权。 版权所有 2025 [Enkrypt AI, Inc.](https://www.enkryptai.com/)

标签：AI安全, Chat Copilot, DevSecOps, DLL 劫持, DNS 反向解析, Petitpotam, PyRIT, 上游代理, 多智能体系统, 大语言模型, 逆向工具