返回更新列表
新发布Aug 4, 2026

skill-scanner v2.0.13

代理技能的安全扫描器

分享

Skill Scanner

License CPython 3.11–3.14 PyPI version CI Discord Cisco AI Defense AI Security Framework Ask DeepWiki

一款针对 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-go v0.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% 的留出恶意技能。

分类