Skill Scanner

一款尽力而为（best-effort）的 AI Agent Skills 安全扫描器，用于检测提示注入、数据外泄和恶意代码模式。结合基于模式的检测（YAML + YARA）、LLM 评审和行为数据流分析，在最小化误报的同时最大化对潜在威胁的检测覆盖率。

重要提示： 本扫描器提供的是尽力而为的检测，而非全面或完整的覆盖。扫描结果为"无发现"并不保证技能不存在任何威胁。请参阅下方的范围和限制。

支持遵循 Agent Skills 规范 的 OpenAI Codex Skills 和 Cursor Agent Skills 格式。使用 --lenient 时，还可扫描非标准格式，如 Claude Code .claude/commands/*.md 和扁平化的 Markdown 技能仓库。

亮点

• 多引擎检测 - 静态分析、行为数据流、LLM 语义分析和云端扫描，实现分层、尽力而为的覆盖
• 误报过滤 - 元分析器显著降低噪音，同时保持检测能力
• CI/CD 就绪 - SARIF 输出用于 GitHub 代码扫描、可复用的 GitHub Actions 工作流、构建失败的退出码
• Pre-commit 钩子 - 集成标准 pre-commit 框架，在每次提交前扫描技能
• 可扩展 - 插件架构，支持自定义分析器

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

范围和限制

Skill Scanner 是一款检测工具。它识别已知和潜在的风险模式，但不提供安全认证。

主要限制：

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

文档

安装

前置要求： Python 3.10+ 和 uv（推荐）或 pip

# 使用 uv（推荐）
uv pip install cisco-ai-skill-scanner

# 使用 pip
pip install cisco-ai-skill-scanner

# AWS Bedrock 支持
pip install cisco-ai-skill-scanner[bedrock]

# Google AI Studio / Gemini 支持
pip install cisco-ai-skill-scanner[google]

# Google Vertex AI 支持
pip install cisco-ai-skill-scanner[vertex]

# Azure OpenAI 支持
pip install cisco-ai-skill-scanner[azure]

# 所有云提供商
pip install cisco-ai-skill-scanner[all]

快速开始

环境设置（可选）

# 用于 LLM 分析器和元分析器
export SKILL_SCANNER_LLM_API_KEY="your_api_key"
export SKILL_SCANNER_LLM_MODEL="claude-3-5-sonnet-20241022"

# 用于 VirusTotal 二进制文件扫描
export VIRUSTOTAL_API_KEY="your_virustotal_api_key"

# 用于 Cisco AI Defense
export AI_DEFENSE_API_KEY="your_aidefense_api_key"

交互式向导

不确定使用哪些参数？不带任何参数运行 skill-scanner 以启动交互式向导：

skill-scanner

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

CLI 用法

# 扫描单个技能（核心分析器：静态 + 字节码 + 流水线）
skill-scanner scan /path/to/skill

# 使用行为分析器扫描（数据流分析）
skill-scanner scan /path/to/skill --use-behavioral

# 使用所有引擎扫描
skill-scanner scan /path/to/skill --use-behavioral --use-llm --use-aidefense

# 使用元分析器进行误报过滤
skill-scanner scan /path/to/skill --use-llm --enable-meta

# 使用触发器分析器检查模糊描述
skill-scanner scan /path/to/skill --use-trigger

# 多次运行 LLM 分析器并保留多数同意的发现
skill-scanner scan /path/to/skill --use-llm --llm-consensus-runs 3

# 递归扫描多个技能
cd ~/cisco-ascanner
source .venv/bin/activate
cd ~/.hermes
skill-scanner scan-all ./skills --recursive --use-behavioral

# 跨技能描述重叠检测扫描多个技能
skill-scanner scan-all /path/to/skills --recursive --check-overlap

# 宽松模式：容忍格式错误的技能而不是失败
skill-scanner scan /path/to/skill --lenient
skill-scanner scan-all /path/to/skills --recursive --lenient

# 宽松模式与非标准技能格式（不需要 SKILL.md）
skill-scanner scan .claude/commands/deploy --lenient
skill-scanner scan-all .claude/commands --recursive --lenient

# 使用自定义元文件名代替 SKILL.md
skill-scanner scan /path/to/skill --skill-file README.md

# CI/CD：如果发现威胁则使构建失败
skill-scanner scan-all ./skills --fail-on-severity high --format sarif --output results.sarif

# 生成带有攻击关联组的交互式 HTML 报告
skill-scanner scan /path/to/skill --use-llm --enable-meta --format html --output report.html

# 使用自定义 YARA 规则
skill-scanner scan /path/to/skill --custom-rules /path/to/my-rules/

# 使用自定义分类 + 威胁映射配置文件（JSON/YAML）
skill-scanner scan /path/to/skill --taxonomy /path/to/taxonomy.json --threat-mapping /path/to/threat_mapping.json

# VirusTotal 哈希扫描，可选择上传未知文件
skill-scanner scan /path/to/skill --use-virustotal --vt-upload-files

# 使用扫描策略预设（strict、balanced、permissive）
skill-scanner scan /path/to/skill --policy strict

# 使用自定义组织策略文件
skill-scanner scan /path/to/skill --policy my_org_policy.yaml

# 生成策略文件以进行自定义
skill-scanner generate-policy -o my_org_policy.yaml

# 交互式策略配置器（TUI）
skill-scanner configure-policy

LLM 提供商说明： --llm-provider 目前接受 anthropic 或 openai。 对于 Bedrock、Vertex、Azure、Gemini 和其他 LiteLLM 后端，请设置特定提供商的模型字符串和环境变量（参见 LLM 分析器文档）。

Python SDK

from skill_scanner import SkillScanner
from skill_scanner.core.analyzers import BehavioralAnalyzer

# 创建带有分析器的扫描器
scanner = SkillScanner(analyzers=[
    BehavioralAnalyzer(),
])

# 扫描技能
result = scanner.scan_skill("/path/to/skill")

print(f"发现数: {len(result.findings)}")
print(f"最高严重级别: {result.max_severity}")

# 注意：is_safe 表示未检测到 HIGH/CRITICAL 发现。
# 它不保证技能完全没有风险。
if not result.is_safe:
    print("检测到问题 -- 部署前请审查发现")

安全分析器

CLI 选项

输出示例

$ skill-scanner scan ./my-skill --use-behavioral

============================================================
技能: my-skill
============================================================
状态: [OK] 无发现
最高严重级别: NONE
总发现数: 0
扫描耗时: 0.15s

注意： "无发现"表示扫描器未检测到任何已知的威胁模式——它不保证技能完全没有风险。请参阅范围和限制。

GitHub Actions

使用可复用工作流在每次推送或 PR 时自动扫描技能：

# .github/workflows/scan-skills.yml
name: Scan Skills
on:
  pull_request:
    paths: [".cursor/skills/**"]
jobs:
  scan:
    uses: cisco-ai-defense/skill-scanner/.github/workflows/scan-skills.yml@main
    with:
      skill_path: .cursor/skills
    permissions:
      security-events: write
      contents: read

结果将通过 GitHub 代码扫描以内联注释的形式出现在 PR 中。有关 LLM 集成、密钥配置和分支保护设置的详细信息，请参阅完整指南。

Pre-commit 钩子

使用 pre-commit 框架在每次提交前扫描技能：

# .pre-commit-config.yaml
repos:
  - repo: https://github.com/cisco-ai-defense/skill-scanner
    rev: v1.0.0  # 使用最新的发布标签
    hooks:
      - id: skill-scanner

或直接安装内置钩子：

skill-scanner-pre-commit install

钩子会自动检测哪些技能目录有暂存的更改，并仅扫描这些目录，保持提交速度快速。使用 --all 可扫描所有内容。

贡献

我们欢迎贡献！请参阅 CONTRIBUTING.md 获取指南。

许可证

Apache 2.0 - 详见 LICENSE。

Copyright 2026 Cisco Systems, Inc. and its affiliates

GitHub • Discord • PyPI