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-go v0.32.0 运行时，在确定性检测之后、可选 LLM 分析之前关联有界事实
发现项审查 - 可选的元分析器可关联、排序并过滤发现项；配对的准确性验证仍待完成
CI/CD 就绪 - 支持 SARIF 输出以用于 GitHub Code Scanning、可复用的 GitHub Actions 工作流、用于构建失败的退出码
Pre-commit 钩子 - 标准 pre-commit 框架集成，可在每次提交前扫描 skills
可扩展 - 插件架构，支持自定义分析器

加入 Cisco AI Discord 参与讨论、分享反馈或与团队交流。

范围与局限性

Skill Scanner 是一款检测工具。它能识别已知和可能的风险模式，但并不能认证安全性。

主要局限性：

无发现 ≠ 无风险。 扫描返回“无发现”表示未检测到已知威胁模式。它并不保证某个 skill 是安全的、良性的或不存在漏洞。
覆盖范围本质上是不完整的。 扫描器结合了基于签名的检测、基于 LLM 的语义分析、行为数据流分析、可选的云服务以及可配置的规则包。虽然这种方法提高了覆盖率，但没有任何自动化工具能够检测每一种技术，尤其是新型或零日攻击。
可能出现误报和漏报。 共识模式和元分析有助于审查发现项，但没有任何配置能消除所有错误分类。请根据您的风险承受能力调整扫描策略。
人工审查仍然必不可少。 自动化扫描是纵深防御策略的一个组成部分。高风险或生产环境部署应将扫描器结果与人工代码审查和/或威胁建模相结合。

当前现代化证据

最终的核心 + CEL 开发基准包含 5,256 个恶意和 1,338 个良性的 MaliciousSkillBench 包。与 origin/main 相比，当前扫描器将 F1 从 32.92% 提升至 47.73%，召回率从 19.88% 提升至 31.43%，同时将良性误报率从 3.59% 降低至 1.05%。精确率为 99.16%。五次 CEL 影子运行完全一致且具有确定性；CEL 评估了 154 个候选，未提出任何抑制，也未发生回退。

锁定的源不相交划分表现较弱：TP=65、FP=42、TN=503、FN=774，精确率 60.75%、召回率 7.75%、F1 13.74%、FPR 7.71%。这相比 origin/main（7.40%）提升了 F1，但 FPR 出现回退（3.67%），因此未通过晋升门槛。因此，所有捆绑的 CEL 规则仍保持在 shadow 状态；此变更不会晋升任何 CEL 抑制。

兼容性和补充检查在 111 个官方 Codex、Claude Code 和 Cursor skills（30 个 MEDIUM+ 和 8 个 HIGH/CRITICAL 包）上发现 CEL-OFF/CEL-SHADOW 结果完全一致，且五次运行稳定。NotInject 硬负样本集有 0/339 个可操作匹配。HarmfulSkillBench 有 7/200 个可操作和 6/200 个 HIGH+ 包，其中有一个被隔离样本；而 OpenSkillRisk 有 76/263 个可操作包，其中有两个主机隔离。后两者是仅正向的召回率诊断，无法衡量精确率或 FPR。可选的 ATR 结果不在本次发布范围内。有关方法学、来源、置信区间和局限性，请参阅检测评估与推广。

文档

指南	描述
快速开始	5 分钟快速上手
推荐设置	针对不同任务应运行什么、为什么以及如何配置
架构	系统设计与组件
CEL 决策层	类型化事实、安全边界、推广模式和遥测
威胁分类法	完整的 AITech 威胁分类法及示例
LLM 分析器	LLM 配置与使用
System One 分析器	可选的咨询性筛查层级，以及为何它不能作为门控
元分析器	误报过滤与优先级排序
行为分析器	数据流分析细节
扫描策略	自定义策略、预设和调优指南
策略快速参考	策略章节和可调参数的简明参考
实测结果	每个已发布的数字，及其语料库、总体和模型
规则编写	如何添加签名、YARA 和 Python 规则
GitHub Actions	用于 CI/CD 集成的可复用工作流
API 参考	REST API 文档
开发指南	贡献与开发环境搭建

安装

此检出以及包含这些变更的发布版本的前置条件： CPython 3.11–3.14 以及 uv（推荐）或 pip

包含此分支 CEL 变更的发布版本将在其 wheel 中包含所需的辅助程序；没有单独的 CEL extra。该发布版本配置为支持 CPython 3.11–3.14，而源码安装额外需要 Go 1.27.1+ 来构建辅助程序。在它发布之前，PyPI 当前提供的包可能具有不同的兼容性约定。详情请参阅安装与配置。```bash

Using uv (recommended)

uv pip install cisco-ai-skill-scanner

Using pip

pip install cisco-ai-skill-scanner

<details>
<summary><strong>云服务提供商扩展</strong></summary>```bash
# AWS Bedrock support
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]

# All cloud providers
pip install cisco-ai-skill-scanner[all]

快速开始

环境设置（可选）```bash

For LLM analyzer and Meta-analyzer

export SKILL_SCANNER_LLM_API_KEY="your_api_key" export SKILL_SCANNER_LLM_MODEL="claude-3-5-sonnet-20241022"

Optional: disabled, minimal, low, medium, high, xhigh, or max

export SKILL_SCANNER_LLM_REASONING_EFFORT="low"

For VirusTotal binary scanning

export VIRUSTOTAL_API_KEY="your_virustotal_api_key"

For Cisco AI Defense

export AI_DEFENSE_API_KEY="your_aidefense_api_key"

### 交互式向导

不确定该使用哪些标志？不带任何参数运行 `skill-scanner` 即可启动交互式向导：```bash
skill-scanner

向导会引导你选择扫描目标、分析器、策略和输出格式，然后在运行前展示组装好的命令。非常适合学习 CLI。

CLI 用法```bash

Scan a single skill (core analyzers: static + bytecode + pipeline + correlation)

skill-scanner scan /path/to/skill

Scan with behavioral analyzer (dataflow analysis)

skill-scanner scan /path/to/skill --use-behavioral

Scan with all engines

skill-scanner scan /path/to/skill --use-behavioral --use-llm --use-aidefense

Scan with meta-analyzer for false positive filtering

skill-scanner scan /path/to/skill --use-llm --enable-meta

Scan with trigger analyzer for vague description checks

skill-scanner scan /path/to/skill --use-trigger

Run LLM analyzer multiple times and keep majority-agreed findings

skill-scanner scan /path/to/skill --use-llm --llm-consensus-runs 3

最受欢迎

skill-scanner