AI Skill 安装前安全扫描与阻断工具。
Install-time security scanning and blocking for AI Skills.
Skill Sentinel 是一个只针对 AI Skill 的安装前安全扫描器和安装闸门。它扫描包含 SKILL.md 的 Skill 目录、ZIP 包或 Git 来源，生成 Markdown/JSON 安全报告；如果发现阻断级风险，就不会把候选 Skill 写入目标平台目录。
当前支持的目标平台：
- Codex
- Claude Code
- Cursor
- WorkBuddy
- CodeBuddy Code
扫描核心不依赖具体平台，平台适配器只负责确定目标平台的 Skill 目录。
本项目只处理 Skill 的安装前静态审计：
- 不处理 MCP、Plugin、Agent 或 Tool；
- 不执行候选 Skill 中的脚本或其他代码；
- 不提供调用前阻断或运行时沙箱；
- 不承诺静态扫描能够证明 Skill 绝对安全。
ALLOW 只表示：按照当前版本的规则和策略，没有发现阻断级证据。
需要 Python 3.10 或更高版本。项目无第三方运行时依赖：
python3 -m pip install .只扫描本地目录、ZIP 包或 Git 来源：
skill-sentinel scan ./my-skill --format both --output ./reports
skill-sentinel scan ./my-skill.zip --format json
skill-sentinel scan https://github.com/example/my-skill.git --output ./reports扫描通过后安装到目标平台：
skill-sentinel install ./my-skill --target codex
skill-sentinel install ./my-skill.zip --target claude-code
skill-sentinel install ./my-skill --target cursor
skill-sentinel install ./my-skill.zip --target workbuddy
skill-sentinel install ./my-skill --target codebuddy-code项目级安装：
skill-sentinel install ./my-skill --target cursor --scope project --project /path/to/project默认策略会阻止 CRITICAL、HIGH、MEDIUM 风险和任何扫描错误。安装前，候选 Skill 会被复制到临时隔离目录；扫描器不会执行其中任何代码，只有通过策略才会原子写入目标 Skill 目录。
常见的非执行型资源（例如 PNG、JPEG、GIF、字体和音视频文件）只会记录为 INFO 提醒，不会因为资源本身阻断安装；无法识别的二进制文件和可疑的可执行二进制文件仍按严格策略处理。扫描器自身的规则定义也不会被误判为候选 Skill 的网络、凭据或外泄能力。
报告包含：
- 来源、来源类型和来源版本（如可获取）；
- 扫描器版本和扫描文件数；
- 内容 SHA-256；
- 风险等级、安装决定、规则编号；
- 文件路径、行号和处理建议。
安装清单写入 ~/.skill-sentinel/install-manifest.json，报告默认写入 ~/.skill-sentinel/reports/。
本仓库使用 Apache-2.0 许可证。面向 Red Skill 上传的包是独立构建产物：它不作为本仓库中的运行入口，也不放入 GitHub 仓库；发布时由维护者从同一版本的独立打包源构建。
Skill Sentinel is an install-time security scanner and gate for AI Skills. It scans Skill directories, ZIP archives, and Git sources containing SKILL.md, then produces Markdown and/or JSON security reports. When a blocking risk is found, the candidate Skill is not written to the target platform directory.
Supported target platforms:
- Codex
- Claude Code
- Cursor
- WorkBuddy
- CodeBuddy Code
The scanning core is platform-independent. Platform adapters only determine where Skills are installed.
This project performs static, pre-install auditing for Skills only:
- It does not scan or manage MCPs, Plugins, Agents, or Tools.
- It never executes scripts or other code from the candidate Skill.
- It does not provide pre-call blocking or a runtime sandbox.
- Static analysis cannot prove that a Skill is absolutely safe.
ALLOW means only that the current version of the scanner and policy found no blocking evidence.
Python 3.10 or newer is required. There are no third-party runtime dependencies:
python3 -m pip install .Scan a local directory, ZIP archive, or Git source:
skill-sentinel scan ./my-skill --format both --output ./reports
skill-sentinel scan ./my-skill.zip --format json
skill-sentinel scan https://github.com/example/my-skill.git --output ./reportsInstall after a successful scan:
skill-sentinel install ./my-skill --target codex
skill-sentinel install ./my-skill.zip --target claude-code
skill-sentinel install ./my-skill --target cursor
skill-sentinel install ./my-skill.zip --target workbuddy
skill-sentinel install ./my-skill --target codebuddy-codeProject-scoped installation:
skill-sentinel install ./my-skill --target cursor --scope project --project /path/to/projectBy default, the policy blocks CRITICAL, HIGH, and MEDIUM findings, as well as any scan error. Before installation, the candidate Skill is copied into a temporary isolated directory. The scanner does not execute candidate code; only a passing result is atomically written to the target Skill directory.
Common non-executable assets such as PNG, JPEG, GIF, fonts, and audio/video files are reported as INFO observations and do not block installation by themselves. Unknown binary files and suspicious executable binaries remain subject to the strict policy. The scanner also avoids treating its own rule definitions as network, credential, or exfiltration capabilities.
Reports include:
- Source, source type, and source revision when available;
- Scanner version and number of scanned files;
- Content SHA-256;
- Severity, installation decision, and rule identifiers;
- File paths, line numbers, and remediation guidance.
The installation manifest is stored at ~/.skill-sentinel/install-manifest.json. Reports are written to ~/.skill-sentinel/reports/ by default.
This repository is licensed under Apache-2.0. The package intended for Red Skill upload is a separately built artifact. It is not the runtime entry point in this repository and is intentionally excluded from GitHub. Maintainers build it from a separate packaging source corresponding to the same version.
Run the local checks:
python3 -m compileall -q skill_sentinel
PYTHONPATH=. python3 -m unittest discover -s tests -v