opentrapp/skill-firewall
GitHub: opentrapp/skill-firewall
一款用于在 AI Agent 加载 skills 和插件前扫描恶意软件与 prompt injection 的离线安全检查工具，提供 GitHub Action 和 CLI 两种使用方式。
Stars: 0 | Forks: 0
# OpenTrApp 技能 Firewall (GitHub Action)
在 agent 加载之前扫描其 **skills 和插件是否存在恶意软件和 prompt injection**，直接在您的 CI 中进行。这是 [OpenTrApp](https://github.com/albertdobmeyer/opentrapp) skill 防御体系的一个独立、可在宿主机上运行的半成品组件（Vault 是完整的五容器防御边界；而这是一个单行的安装前检查工具）。
扫描过程**完全离线**：不需要模型，也不需要网络。它运行的是 OpenTrApp 在其防御边界内运行的同一引擎，因此没有需要您单独信任的分叉版本。
## 检查内容
- 一个映射到 MITRE ATT&CK 的 **87 种模式拦截列表**，其中包括 **16 种 prompt injection** 模式。
- 一个 **零信任行分类器**，如果发现某一行无法识别，就会隔离该 skill，这是针对模式集合尚未见过的新型攻击的防御手段。
- 输出格式为 **SARIF**，因此扫描结果会显示在您代码仓库的 **Security 选项卡**（代码扫描）中。
## 诚实边界（请阅读）
此 Action **读取并进行文本的模式匹配。它不会执行 skill。** 它的保证是“*在 agent 加载前审查 skill*”，而不是“*没有不受信任的内容会触及您的 runner*”。它会在 runner 上读取不受信任的文本，这比执行 skill 的风险要低得多，但风险并非为零。更严格的“不受信任的内容仅在隔离的 container 内处理”这一特性属于完整的 OpenTrApp 防御边界（Vault）。参见 [ADR-0025](https://github.com/albertdobmeyer/opentrapp/blob/main/docs/adr/0025-standalone-skill-firewall-scope.md)。
## 用法
```
name: skill-firewall
on: [pull_request]
permissions:
contents: read
security-events: write # only needed to upload findings to the Security tab
jobs:
scan:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: opentrapp/skill-firewall@v1
with:
path: ./skills # a skill dir, a parent of several, or a single SKILL.md
strict: false
```
如果检测到发现结果，job 就会失败（这是安装前拦截机制的意义所在）。如果只想报告而不导致失败，请设置 `fail-on-finding: false`。如果您没有授予 `security-events: write` 权限，请设置 `upload-sarif: false`，这样 Action 仍然会执行扫描和拦截，只是会跳过向 Security 选项卡的上传。
## 输入参数
| 输入参数 | 默认值 | 描述 |
|-------|---------|-------------|
| `path` | `.` | 扫描目标：一个 skill 或插件目录、多个目录的父目录，或单个 `SKILL.md`。 |
| `strict` | `false` | 将可疑行视为扫描发现，而不仅仅是那些明显恶意的行。 |
| `format` | `summary` | 打印到 job 日志中的人类可读格式：`default`、`summary` 或 `json`。 |
| `upload-sarif` | `true` | 将扫描结果上传到 Security 选项卡。需要 `security-events: write` 权限。 |
| `fail-on-finding` | `true` | 检测到发现结果时使 job 失败。设置为 `false` 则仅作报告。 |
## 退出行为
底层扫描器使用一个简单的约定：`0` 表示干净，`1` 表示有发现，`2` 表示用法错误。不包含 `SKILL.md` 的路径会被视为“无可扫描内容”并通过检查，这样拦截机制就不会在路径为空或重构后发生误报失败。
## 环境要求
配备 `bash` 和 `python3` 的 Linux 或 macOS runner（标准 GitHub 托管的 runner 上均包含这两者）。目前不支持 Windows runner，因为扫描器是一个 bash 工具链。
## CI 外的安装前 hook
同一个扫描器可以在本地作为单行拦截命令运行，例如在安装 agent 插件之前：
```
skill scan "$PLUGIN_DIR" --strict || { echo "blocked by the skill firewall" >&2; exit 1; }
```
MIT 许可证，公开构建。欢迎在 [albertdobmeyer/opentrapp](https://github.com/albertdobmeyer/opentrapp) 提交 Issue 和进行审查。
标签：AI安全, Chat Copilot, DNS 反向解析, GitHub Action, LLM Agent, SARIF, 云安全监控, 应用安全, 搜索语句（dork）, 静态分析