Skill Scanner

Сканер безопасности, работающий по принципу наилучшего усилия, для AI Agent Skills, который обнаруживает внедрение промптов, утечку данных и вредоносные шаблоны кода. Объединяет обнаружение на основе шаблонов (YAML + YARA), LLM-as-a-judge и анализ потоков данных поведения для максимального охвата обнаружения вероятных угроз при минимизации ложных срабатываний.

Важно: Этот сканер обеспечивает обнаружение по принципу наилучшего усилия, а не исчерпывающий или полный охват. Сканирование, не вернувшее результатов, не гарантирует, что навык свободен от всех угроз. См. Область применения и ограничения ниже.

Поддерживает форматы OpenAI Codex Skills и Cursor Agent Skills в соответствии со спецификацией Agent Skills. С флагом --lenient также сканирует нестандартные форматы, такие как Claude Code .claude/commands/*.md и плоские репозитории навыков в markdown.

Ключевые возможности

• Многофакторное обнаружение — статический анализ, анализ потоков данных поведения, семантический анализ LLM и облачное сканирование для многоуровневого охвата по принципу наилучшего усилия
• Фильтрация ложных срабатываний — мета-анализатор значительно снижает шум, сохраняя способность обнаружения
• Готовность к CI/CD — вывод SARIF для GitHub Code Scanning, переиспользуемый рабочий процесс GitHub Actions, коды выхода для сбоев сборки
• Pre-commit Hook — интеграция со стандартным фреймворком pre-commit для сканирования навыков перед каждым коммитом
• Расширяемость — архитектура плагинов для пользовательских анализаторов

Присоединяйтесь к Cisco AI Discord, чтобы обсудить, поделиться отзывами или связаться с командой.

Область применения и ограничения

Skill Scanner — это инструмент обнаружения. Он выявляет известные и вероятные шаблоны риска, но не сертифицирует безопасность.

Ключевые ограничения:

• Отсутствие находок ≠ отсутствие риска. Сканирование, возвращающее «No findings», указывает на то, что известные шаблоны угроз не были обнаружены. Это не гарантирует, что навык безопасен, безвреден или свободен от уязвимостей.
• Охват по своей природе неполон. Сканер объединяет обнаружение на основе сигнатур, семантический анализ на основе LLM, анализ потоков данных поведения, опциональные облачные сервисы и настраиваемые наборы правил. Хотя этот подход улучшает охват, ни один автоматизированный инструмент не может обнаружить все техники, особенно новые или zero-day атаки.
• Возможны ложные срабатывания и ложные пропуски. Режимы консенсуса и мета-анализ снижают шум, но ни одна конфигурация не устраняет все некорректные классификации. Настройте политику сканирования под вашу толерантность к риску.
• Ручная проверка остаётся необходимой. Автоматизированное сканирование — один из компонентов стратегии эшелонированной защиты. Для высокорисковых или производственных развёртываний следует сочетать результаты сканера с ручной проверкой кода и/или моделированием угроз.

Документация

Установка

Предварительные требования: Python 3.10+ и uv (рекомендуется) или pip

# Using uv (recommended)
uv pip install cisco-ai-skill-scanner

# Using pip
pip install cisco-ai-skill-scanner

# 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]

Быстрый старт

Настройка окружения (опционально)

# 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 без аргументов, чтобы открыть интерактивный мастер:

skill-scanner

Мастер проведёт вас через выбор цели сканирования, анализаторов, политики и формата вывода, а затем покажет собранную команду перед её запуском. Отлично подходит для изучения CLI.

Использование CLI

# Scan a single skill (core analyzers: static + bytecode + pipeline)
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

# Scan multiple skills recursively
skill-scanner scan-all /path/to/skills --recursive --use-behavioral

# Scan multiple skills with cross-skill overlap detection
skill-scanner scan-all /path/to/skills --recursive --check-overlap

# Scan a GitHub repository (owner/repo shorthand or full URL)
skill-scanner scan-repo owner/repo
skill-scanner scan-repo https://github.com/owner/repo --use-llm

# Lenient mode: tolerate malformed skills instead of failing
skill-scanner scan /path/to/skill --lenient
skill-scanner scan-all /path/to/skills --recursive --lenient

# Lenient mode with non-standard skill formats (no SKILL.md required)
skill-scanner scan .claude/commands/deploy --lenient
skill-scanner scan-all .claude/commands --recursive --lenient

# Use a custom metadata filename instead of SKILL.md
skill-scanner scan /path/to/skill --skill-file README.md

# CI/CD: Fail build if threats found
skill-scanner scan-all ./skills --fail-on-severity high --format sarif --output results.sarif

# Generate interactive HTML report with attack correlation groups
skill-scanner scan /path/to/skill --use-llm --enable-meta --format html --output report.html

# Use custom YARA rules
skill-scanner scan /path/to/skill --custom-rules /path/to/my-rules/

# Use custom taxonomy + threat mapping profiles (JSON/YAML)
skill-scanner scan /path/to/skill --taxonomy /path/to/taxonomy.json --threat-mapping /path/to/threat_mapping.json

# VirusTotal hash scan with optional unknown-file uploads
skill-scanner scan /path/to/skill --use-virustotal --vt-upload-files

# Use a scan policy preset (strict, balanced, permissive)
skill-scanner scan /path/to/skill --policy strict

# Use a custom org policy file
skill-scanner scan /path/to/skill --policy my_org_policy.yaml

# Generate a policy file to customise
skill-scanner generate-policy -o my_org_policy.yaml

# Interactive policy configurator (TUI)
skill-scanner configure-policy

Режим консенсуса сохраняет находку только тогда, когда она появляется более чем в половине настроенных запусков. Когда эти голоса расходятся в оценке серьёзности, побеждает наивысшая наблюдаемая серьёзность, независимо от порядка ответов. Неудачные запуски и успешные запуски, в которых находка отсутствует, не голосуют, но остаются в знаменателе. Это делает выбор серьёзности стабильным для находок, согласованных большинством. Это не делает отдельную выборку LLM детерминированной, и описательные поля из голосов с равной серьёзностью, вывод одиночного запуска и находки без большинства всё ещё могут различаться между сканированиями.

Примечание о провайдере LLM: --llm-provider в настоящее время принимает anthropic или openai. Для Bedrock, Vertex, Azure, Gemini и других бэкендов LiteLLM задайте специфичные для провайдера строки моделей и переменные окружения (см. документацию LLM Analyzer).

Python SDK

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

# Create scanner with analyzers
scanner = SkillScanner(analyzers=[
    BehavioralAnalyzer(),
])

# Scan a skill
result = scanner.scan_skill("/path/to/skill")

print(f"Findings: {len(result.findings)}")
print(f"Max severity: {result.max_severity}")

# Note: is_safe indicates no HIGH/CRITICAL findings were detected.
# It does not guarantee the skill is free of all risk.
if not result.is_safe:
    print("Issues detected -- review findings before deployment")

Анализаторы безопасности

Опции CLI

Пример вывода

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

============================================================
Skill: my-skill
============================================================
Status: [OK] No findings
Max Severity: NONE
Total Findings: 0
Scan Duration: 0.15s

Примечание: «No findings» означает, что сканер не обнаружил известных шаблонов угроз — это не гарантия того, что навык свободен от всех рисков. См. Область применения и ограничения.

GitHub Actions

Автоматически сканируйте навыки при каждом push или 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

Результаты отображаются в виде встроенных аннотаций в PR через GitHub Code Scanning. См. полное руководство по интеграции с LLM, настройке секретов и настройке защиты веток.

Pre-commit Hook

Сканируйте навыки перед каждым коммитом с помощью фреймворка pre-commit:

# .pre-commit-config.yaml
repos:
  - repo: https://github.com/cisco-ai-defense/skill-scanner
    rev: v1.0.0  # use the latest release tag
    hooks:
      - id: skill-scanner

Или установите встроенный хук напрямую:

skill-scanner-pre-commit --install

Хук сопоставляет изменённые файлы с ближайшим SKILL.md и сканирует каждый затронутый навык один раз. Во время обычного коммита он читает проиндексированный diff. В CI сравните две ревизии, чтобы не требовался проиндексированный индекс:

pre-commit run skill-scanner --from-ref "$BASE_SHA" --to-ref "$HEAD_SHA"

Обе ревизии должны существовать в рабочей копии. Чтобы просканировать каждый настроенный навык, вызовите хук напрямую:

skill-scanner-pre-commit --scan-all

Либо настройте args: [--scan-all] для хука в .pre-commit-config.yaml.

Участие в разработке

Мы приветствуем вклад! Пожалуйста, см. CONTRIBUTING.md для руководящих принципов.

Лицензия

Apache 2.0 — см. LICENSE для подробностей.

Copyright 2026 Cisco Systems, Inc. and its affiliates

GitHub • Discord • PyPI