rrrrrredy/skill-security-guard

skill-security-guard

CI
License: MIT
Python

用于 agent skill 包的静态安全扫描器。

skill-security-guard 执行确定性的 7 维度扫描，给出 A-F 风险评级，报告置信度，并提供修复指导。该 CLI 仅使用 Python 标准库，因此可在 Windows、macOS 和 Linux 上运行，无需项目依赖。

它可作为 OpenClaw skill、DeepSeek Harness 社区 Bundle，或作为本地 skill 包的独立扫描器使用。

扫描内容

- 提示注入和指令覆盖模式
- 敏感文件读取和数据外泄模式
- 合规红线，例如隧道、受限系统访问、高度敏感数据处理，以及敏感配置备份/上传
- scripts/ 中的恶意脚本模式
- 从非默认或可疑来源安装依赖
- 过宽或不清晰的 description 触发范围
- Frontmatter 合规性（name 和 description）

快速开始

git clone https://github.com/rrrrrredy/skill-security-guard.git
cd skill-security-guard

python scripts/scan.py path/to/SKILL.md
python scripts/scan.py path/to/skill-directory
python scripts/scan.py path/to/skills.zip
python scripts/scan.py --text "inline skill text"

Shell 包装脚本：

bash scripts/scan.sh path/to/skill-directory

JSON 输出：

python scripts/scan.py path/to/skill-directory --format json

每份生成的报告都是一份确定性的 skill-security-scan.v1 证明。
它包含扫描器版本、所扫描的精确 UTF-8 bundle 的 SHA-256、
按排序的每次运行忽略列表，以及 complete: true。下游发布或
影响台账应拒绝 input_sha256 与候选字节不匹配的报告。参见 schemas/skill-security-scan.v1.schema.json。

在一次运行中忽略某条已审查的规则：

python scripts/scan.py path/to/skill-directory --ignore R3-N5

示例输出

安全 skill：

Skill Security Report: safe-skill
Scanner: 5.2.1 (skill-security-scan.v1)
Input SHA-256: sha256:
Complete: true
Rating: A (100/100)

Issues: none

Passed dimensions:
- Prompt injection
- Sensitive file access / data exfiltration
- Compliance violations
- Malicious scripts
- Dependency safety
- Description trigger reasonability
- Frontmatter compliance

高风险 skill：

Skill Security Report: high-risk-skill
Rating: F (0/100)

Issues (5):
- [high/confirmed] M4-REMOTE-SCRIPT-EXEC: Remote script execution detected
- [high/confirmed] S2-EXFILTRATION: Sensitive data exfiltration pattern detected
- [medium/confirmed] P1-PROMPT-INJECTION: Prompt-injection instruction detected
输入支持

- SKILL.md 或任意本地文本/代码文件
- 包含一个或多个 SKILL.md 文件的技能目录
- .zip 包，解压时进行路径遍历检查并限制大小/文件数量
- - 表示标准输入
- --text 表示内联文本
- 公开的 http:// 或 https:// 文本 URL，受响应大小和超时限制

目录和 zip 扫描默认包含 SKILL.md 以及 scripts/ 下的文件。为减少误报，会跳过参考文档；当你明确想要同时扫描参考 markdown 时，请使用 --include-references。

要求

- Python 3.10+
- 无运行时包依赖

扫描器 CI 任务在 Ubuntu 上测试 Python 3.11 和 3.12。DeepSeek Harness Bundle 任务在 Ubuntu 和 Windows 上使用 Python 3.11 测试 Node.js 22.19 和 24。

DeepSeek Harness

dsh-skill-security-guard 社区 Bundle 通过原生 Cordis Skill Provider API 注册本仓库现有的 SKILL.md。它打包了相同的扫描器和检测规则，而不是维护第二套实现。

包发布后，将其安装到某个 profile：

dsh plugin --profile headless add dsh-skill-security-guard@0.1.0
dsh --profile headless --dump-config
dsh --profile headless "Use skill-security-guard to scan ./path/to/a-skill."

然后让 agent 使用 skill-security-guard 扫描文件、目录、zip、URL 或内联技能文本。扫描器运行时需要 Python 3.10+。有关兼容性、隐私边界、本地包验证和卸载说明，请参见 integrations/deepseek-harness。

这是社区插件，不是 DeepSeek 官方插件。

评级模型

- A：无发现
- B：仅提示性或轻微发现
- C：应审查的中等风险发现
- D：多个已确认的中等风险发现或严重降级
- F：直接的高风险发现，例如数据外泄、隧道、破坏性命令或远程脚本执行

确切的检测模式和评分规则位于 references/detection-rules.md。

开发

运行测试：

python -m unittest discover -s tests -p "test_*.py"

运行示例扫描：

python scripts/scan.py tests/fixtures/safe-skill
python scripts/scan.py tests/fixtures/high-risk-skill

对本仓库运行扫描器：

python scripts/scan.py .

项目结构

skill-security-guard/
├── SKILL.md
├── scripts/
│   ├── scan.py
│   └── scan.sh
├── references/
│   └── detection-rules.md
├── tests/
│   ├── fixtures/
│   └── test_scan.py
└── .github/workflows/ci.yml

DeepSeek Harness 集成（包括其包清单、源代码、构建脚本和测试）位于 integrations/deepseek-harness。

限制

这是一个静态扫描器。它不会执行技能、监控运行时行为、证明软件包来源，也不会取代人工安全审查。发现结果有意保持保守，在阻止某个技能之前应先进行审查。

贡献

欢迎贡献。有关本地开发和规则设计指南，请参阅 CONTRIBUTING.md。

有关漏洞报告，请参阅 SECURITY.md。

许可证

MIT