Skill Scanner

Ein Best-Effort-Sicherheitsscanner für AI Agent Skills, der Prompt-Injection, Datenexfiltration und bösartige Codemuster erkennt. Er kombiniert musterbasierte Erkennung (YAML + YARA), LLM-as-a-judge und verhaltensbasierte Datenflussanalyse, um die Erkennungsabdeckung wahrscheinlicher Bedrohungen zu maximieren und gleichzeitig Fehlalarme zu minimieren.

Wichtig: Dieser Scanner bietet Best-Effort-Erkennung, keine umfassende oder vollständige Abdeckung. Ein Scan, der keine Befunde liefert, garantiert nicht, dass ein Skill frei von allen Bedrohungen ist. Siehe Umfang und Einschränkungen unten.

Unterstützt die Formate OpenAI Codex Skills und Cursor Agent Skills gemäß der Agent-Skills-Spezifikation. Mit --lenient werden auch nicht standardkonforme Formate gescannt, wie Claude Code .claude/commands/*.md und flache Markdown-Skill-Repositories.

Highlights

• Multi-Engine-Erkennung – Statische Analyse, verhaltensbasierte Datenflussanalyse, LLM-semantische Analyse und cloudbasiertes Scannen für mehrschichtige Best-Effort-Abdeckung
• Fehlalarm-Filterung – Der Meta-Analysator reduziert Rauschen erheblich, während die Erkennungsfähigkeit erhalten bleibt
• CI/CD-bereit – SARIF-Ausgabe für GitHub Code Scanning, wiederverwendbarer GitHub-Actions-Workflow, Exit-Codes für Build-Fehler
• Pre-commit-Hook – Integration in das Standard-Pre-commit-Framework, um Skills vor jedem Commit zu scannen
• Erweiterbar – Plugin-Architektur für benutzerdefinierte Analysatoren

Treten Sie dem Cisco-AI-Discord bei, um zu diskutieren, Feedback zu teilen oder sich mit dem Team zu vernetzen.

Umfang und Einschränkungen

Skill Scanner ist ein Erkennungstool. Es identifiziert bekannte und wahrscheinliche Risikomuster, bescheinigt aber keine Sicherheit.

Wichtigste Einschränkungen:

• Keine Befunde ≠ kein Risiko. Ein Scan, der „No findings“ zurückgibt, zeigt an, dass keine bekannten Bedrohungsmuster erkannt wurden. Er garantiert nicht, dass ein Skill sicher, harmlos oder frei von Schwachstellen ist.
• Die Abdeckung ist grundsätzlich unvollständig. Der Scanner kombiniert signaturbasierte Erkennung, LLM-basierte semantische Analyse, verhaltensbasierte Datenflussanalyse, optionale Cloud-Dienste und konfigurierbare Regelpakete. Auch wenn dieser Ansatz die Abdeckung verbessert, kann kein automatisiertes Tool jede Technik erkennen – insbesondere neuartige oder Zero-Day-Angriffe.
• Fehlalarme und falsch-negative Ergebnisse können auftreten. Konsensmodi und Meta-Analyse reduzieren Rauschen, aber keine Konfiguration eliminiert alle falschen Klassifizierungen. Passen Sie die Scan-Policy an Ihre Risikotoleranz an.
• Menschliche Überprüfung bleibt unverzichtbar. Automatisiertes Scannen ist eine Komponente einer Defense-in-Depth-Strategie. Bei Hochrisiko- oder Produktionsbereitstellungen sollten Scannerergebnisse mit manueller Code-Überprüfung und/oder Threat Modeling kombiniert werden.

Dokumentation

Installation

Voraussetzungen: Python 3.10+ und uv (empfohlen) oder 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]

Schnellstart

Umgebungseinrichtung (optional)

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

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

Interaktiver Assistent

Nicht sicher, welche Flags Sie verwenden sollen? Führen Sie skill-scanner ohne Argumente aus, um den interaktiven Assistenten zu starten:

skill-scanner

Der Assistent führt Sie durch die Auswahl von Scan-Ziel, Analysatoren, Policy und Ausgabeformat und zeigt dann den zusammengestellten Befehl, bevor er ihn ausführt. Ideal, um die CLI kennenzulernen.

CLI-Nutzung

# 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

Hinweis zum LLM-Anbieter: --llm-provider akzeptiert derzeit anthropic oder openai. Für Bedrock, Vertex, Azure, Gemini und andere LiteLLM-Backends konfigurieren Sie anbieterspezifische Modellzeichenfolgen und Umgebungsvariablen (siehe LLM-Analysator-Dokumentation).

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")

Sicherheits-Analysatoren

CLI-Optionen

Beispielausgabe

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

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

Hinweis: „No findings“ bedeutet, dass der Scanner keine bekannten Bedrohungsmuster erkannt hat – es ist keine Garantie dafür, dass der Skill frei von jeglichem Risiko ist. Siehe Umfang und Einschränkungen.

GitHub Actions

Scannen Sie Skills bei jedem Push oder PR automatisch mit dem wiederverwendbaren Workflow:

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

Die Ergebnisse erscheinen als Inline-Anmerkungen in PRs über GitHub Code Scanning. Weitere Informationen zur LLM-Integration, Secret-Konfiguration und Einrichtung des Branch-Schutzes finden Sie in der vollständigen Anleitung.

Pre-commit-Hook

Scannen Sie Skills vor jedem Commit mit dem pre-commit-Framework:

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

Oder installieren Sie den integrierten Hook direkt:

skill-scanner-pre-commit install

Der Hook erkennt automatisch, welche Skill-Verzeichnisse Änderungen in der Staging-Area enthalten, und scannt nur diese, sodass die Commit-Zeiten kurz bleiben. Verwenden Sie --all, um alles zu scannen.

Mitwirken

Wir freuen uns über Beiträge! Richtlinien finden Sie in CONTRIBUTING.md.

Lizenz

Apache 2.0 – Details siehe LICENSE.

Copyright 2026 Cisco Systems, Inc. und verbundene Unternehmen

GitHub • Discord • PyPI