
skill-scanner v2.0.13
代理技能的安全扫描器
Skill Scanner
一款针对 AI Agent Skills 的尽力而为型安全扫描器,可检测提示注入、数据外泄和恶意代码模式。它结合了基于模式的检测(YAML + YARA-X)、AST 与数据流分析、可选的 LLM 作为评判者,以及基于类型化检测器事实的有界 CEL 决策层。
重要提示: 本扫描器提供尽力而为的检测,并非全面或完整的覆盖。扫描未返回任何发现并不保证该 skill 不存在任何威胁。请参阅下方的范围与限制。
支持遵循 Agent Skills 规范的 OpenAI Codex Skills 和 Cursor Agent Skills 格式。使用 --lenient 时,还可扫描非标准格式,例如 Claude Code 的 .claude/commands/*.md 以及扁平化的 markdown skill 仓库。
亮点
- 多引擎检测 - 静态分析、行为数据流、LLM 语义分析和基于云的扫描,提供分层、尽力而为的覆盖
- 类型化 CEL 决策 - 核心扫描器使用官方
cel-gov0.32.0 运行时,在确定性检测之后、可选 LLM 分析之前关联有界事实 - 经测量的预设 -
low-noise和quiet预设及 LLM 上限,并为每个预设公布召回率、误报率和 F1(推荐设置) - CI/CD 就绪 - 用于 GitHub Code Scanning 的 SARIF 输出、可复用的 GitHub Actions 工作流、用于构建失败的退出码
- Pre-commit 钩子 - 集成标准 pre-commit 框架,在每次提交前扫描 skills
- 可扩展 - 用于自定义分析器的插件架构
加入 Cisco AI Discord 参与讨论、分享反馈或与团队联系。
范围与限制
Skill Scanner 是一款检测工具。它能识别已知和可能的风险模式,但并不能认证安全性。
主要限制:
- 未发现问题 ≠ 无风险。 扫描返回“未发现问题”仅表示未检测到已知威胁模式。这并不保证某个技能是安全的、无害的或不存在漏洞。
- 覆盖范围本质上是不完整的。 扫描器结合了基于签名的检测、基于 LLM 的语义分析、行为数据流分析、可选的云服务以及可配置的规则包。尽管这种方法提高了覆盖率,但没有任何自动化工具能够检测出所有技术手段,尤其是新型或零日攻击。
- 可能出现误报和漏报。 预设、LLM 评判器和限定范围的抑制规则可减少噪声,但没有任何配置能消除所有错误分类。请从推荐设置中选择一套经过权衡的配置,并根据你的风险容忍度调整扫描策略。
- 人工审查仍然必不可少。 自动化扫描只是纵深防御策略中的一个组成部分。高风险或生产环境部署应将扫描器结果与人工代码审查和/或威胁建模相结合。
实测结果
在留出技能集上(MaliciousSkillBench 的冻结测试集,839 个恶意技能和 545 个无害技能):
- 仅使用规则在 HIGH 级别下捕获 7.7% 的恶意技能,误报率为 4.0%。
- 结合 LLM 评判器(Gemma 4 26B,
balanced),66.7% 的技能在 MEDIUM+ 级别进入审查(误报率 15.4%), 33.7% 的技能在 HIGH 级别被拦截(误报率 6.4%)。
每一项数据及其对应的语料库和方法均记录在实测结果 以及评估 Space中。
文档
文档网站为 cisco-ai-defense.github.io/docs/skill-scanner。
深入讲解页面位于 docs/。
| 指南 | 描述 |
|---|---|
| 快速开始 | 5 分钟快速上手 |
| 推荐设置 | 选择最低 FPR 或最高 F1 的配置方案,附可直接复制的配置 |
| LLM 提供商 | 为任意提供商、网关或本地模型配置 LLM 评判器 |
| 结果与调优 | 阅读发现结果、构建审查队列、降低误报 |
| 架构 | 系统设计与组件 |
| CEL 决策层 | 类型化事实、安全边界、发布模式与遥测 |
| 威胁分类法 | 完整的 AITech 威胁分类法及示例 |
| 分类法参考 | 每个 AITech 和 AISubtech 代码的定义 |
| LLM 分析器 | LLM 配置与使用 |
| System One 分析器 | 可选的建议性筛查层级,以及它为何不能作为门控 |
| 元分析器 | 可选的二次审查(默认关闭;已测量成本) |
| 行为分析器 | 数据流分析细节 |
| 扫描策略 | 自定义策略、预设与调优指南 |
| 策略快速参考 | 策略各节与可调参数的简明参考 |
| 实测结果 | 每个已发布的数字,及其对应的语料库、样本群体和模型 |
| 规则编写 | 如何添加签名规则、YARA 规则和 Python 规则 |
| GitHub Actions | 用于 CI/CD 集成的可复用工作流 |
| API 参考 | REST API 文档 |
| 开发指南 | 贡献与开发环境搭建 |
安装
前置条件: CPython 3.11–3.14 以及 uv(推荐)或 pip。
Wheel 包包含适用于 glibc Linux x86-64/ARM64、macOS 14+ x86-64/ARM64 和 Windows x86-64 的 CEL 辅助组件。其他平台需从源码分发包构建,这要求 Go 1.27.1+。详见 安装与配置。
# Using uv (recommended)
uv pip install cisco-ai-skill-scanner
# As a standalone tool
uv tool install cisco-ai-skill-scanner # or: pipx install cisco-ai-skill-scanner
# Using pip
pip install cisco-ai-skill-scanner
# Using Homebrew (macOS 14+)
brew tap cisco-ai-defense/skill-scanner https://github.com/cisco-ai-defense/skill-scanner
brew install cisco-ai-defense/skill-scanner/skill-scanner
推荐设置中的预设和设置需要 2.2.0 或更高版本(skill-scanner --version)。
云服务提供商附加内容
# AWS Bedrock support (IAM credentials, no API key)
pip install cisco-ai-skill-scanner[bedrock]
# Google AI Studio / Gemini support
pip install cisco-ai-skill-scanner[google]
# Google Vertex AI support
pip install cisco-ai-skill-scanner[vertex]
# Azure OpenAI support
pip install cisco-ai-skill-scanner[azure]
# On-device Apple Foundation Model (experimental: macOS 26+, Apple Intelligence, full Xcode)
pip install "apple-fm-sdk>=0.2.1,<0.3"
# All cloud providers
pip install cisco-ai-skill-scanner[all]
快速开始
推荐设置
每个推荐配置都会运行 LLM 判定器(--use-llm):仅靠规则只能捕获约 8% 的留出恶意技能。