Skill Scanner

Ein Security-Scanner mit Best-Effort-Ansatz für KI-Agent-Skills, der Prompt-Injection, Datenerfiltration und bösartige Code-Muster erkennt. 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 eine Best-Effort-Erkennung, keine umfassende oder vollständige Abdeckung. Ein Scan ohne Befunde garantiert nicht, dass ein Skill frei von allen Bedrohungen ist. Siehe Umfang und Einschränkungen unten.

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

Highlights

• Multi-Engine-Erkennung - Statische Analyse, verhaltensbasierte Datenflussanalyse, LLM-semantische Analyse und cloudbasierte Scan-Funktionen für eine mehrschichtige Best-Effort-Abdeckung
• Fehlalarm-Filterung - 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 - Standard-Pre-commit-Framework Integration zum Scannen von Skills vor jedem Commit
• 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 verbinden.

Umfang und Einschränkungen

Skill Scanner ist ein Erkennungstool. Es identifiziert bekannte und wahrscheinliche Risikomuster, zertifiziert jedoch keine Sicherheit.

Wichtige Einschränkungen:

• Keine Befunde ≠ kein Risiko. Ein Scan, der „Keine Befunde" zurückgibt, bedeutet, dass keine bekannten Bedrohungsmuster erkannt wurden. Es garantiert nicht, dass ein Skill sicher, harmlos oder frei von Schwachstellen ist.
• Die Abdeckung ist von Natur aus unvollständig. Der Scanner kombiniert signaturbasierte Erkennung, LLM-basierte semantische Analyse, verhaltensbasierte Datenflussanalyse, optionale Cloud-Dienste und konfigurierbare Regelpakete. Obwohl 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-Richtlinie an Ihre Risikotoleranz an.
• Menschliche Überprüfung bleibt unerlässlich. Automatisiertes Scannen ist eine Komponente einer Defense-in-Depth-Strategie. Hochrisiko- oder Produktionsbereitstellungen sollten Scanner-Ergebnisse mit manueller Code-Überprüfung und/oder Bedrohungsmodellierung kombinieren.

Dokumentation

Installation

Voraussetzungen: Python 3.10+ und uv (empfohlen) oder pip

# Mit uv (empfohlen)
uv pip install cisco-ai-skill-scanner

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

# AWS Bedrock Unterstützung
pip install cisco-ai-skill-scanner[bedrock]

# Google AI Studio / Gemini Unterstützung
pip install cisco-ai-skill-scanner[google]

# Google Vertex AI Unterstützung
pip install cisco-ai-skill-scanner[vertex]

# Azure OpenAI Unterstützung
pip install cisco-ai-skill-scanner[azure]

# Alle Cloud-Anbieter
pip install cisco-ai-skill-scanner[all]

Schnellstart

Umgebungseinrichtung (Optional)

# Für LLM-Analysator und Meta-Analysator
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, oder max
export SKILL_SCANNER_LLM_REASONING_EFFORT="low"

# Für VirusTotal-Binärdatei-Scans
export VIRUSTOTAL_API_KEY="your_virustotal_api_key"

# Für Cisco AI Defense
export AI_DEFENSE_API_KEY="your_aidefense_api_key"

Interaktiver Assistent

Nicht sicher, welche Flags verwendet werden 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 eines Scan-Ziels, der Analysatoren, der Richtlinie und des Ausgabeformats und zeigt dann den zusammengesetzten Befehl an, bevor er ihn ausführt. Ideal zum Erlernen der CLI.

CLI-Nutzung

# Einzelnen Skill scannen (Kern-Analysatoren: statisch + Bytecode + Pipeline)
skill-scanner scan /path/to/skill

# Mit Verhaltensanalysator scannen (Datenflussanalyse)
skill-scanner scan /path/to/skill --use-behavioral

# Mit allen Engines scannen
skill-scanner scan /path/to/skill --use-behavioral --use-llm --use-aidefense

# Mit Meta-Analysator für Fehlalarm-Filterung scannen
skill-scanner scan /path/to/skill --use-llm --enable-meta

# Mit Trigger-Analysator für Prüfungen auf vage Beschreibungen scannen
skill-scanner scan /path/to/skill --use-trigger

# LLM-Analysator mehrmals ausführen und mehrheitlich bestätigte Befunde behalten
skill-scanner scan /path/to/skill --use-llm --llm-consensus-runs 3

# Mehrere Skills rekursiv scannen
skill-scanner scan-all /path/to/skills --recursive --use-behavioral

# Mehrere Skills mit übergreifender Überlappungserkennung scannen
skill-scanner scan-all /path/to/skills --recursive --check-overlap

# Ein GitHub-Repository scannen (owner/repo-Kurzform oder vollständige URL)
skill-scanner scan-repo owner/repo
skill-scanner scan-repo https://github.com/owner/repo --use-llm

# Lenient-Modus: Fehlerhafte Skills tolerieren statt fehlschlagen
skill-scanner scan /path/to/skill --lenient
skill-scanner scan-all /path/to/skills --recursive --lenient

# Lenient-Modus mit nicht standardkonformen Skill-Formaten (kein SKILL.md erforderlich)
skill-scanner scan .claude/commands/deploy --lenient
skill-scanner scan-all .claude/commands --recursive --lenient

# Benutzerdefinierten Metadaten-Dateinamen statt SKILL.md verwenden
skill-scanner scan /path/to/skill --skill-file README.md

# CI/CD: Build fehlschlagen lassen, wenn Bedrohungen gefunden werden
skill-scanner scan-all ./skills --fail-on-severity high --format sarif --output results.sarif

# Interaktiven HTML-Bericht mit Angriffs-Korrelationsgruppen generieren
skill-scanner scan /path/to/skill --use-llm --enable-meta --format html --output report.html

# Benutzerdefinierte YARA-Regeln verwenden
skill-scanner scan /path/to/skill --custom-rules /path/to/my-rules/

# Benutzerdefinierte Taxonomie + Bedrohungszuordnungsprofile verwenden (JSON/YAML)
skill-scanner scan /path/to/skill --taxonomy /path/to/taxonomy.json --threat-mapping /path/to/threat_mapping.json

# VirusTotal-Hash-Scan mit optionalen Uploads unbekannter Dateien
skill-scanner scan /path/to/skill --use-virustotal --vt-upload-files

# Eine Scan-Richtlinien-Voreinstellung verwenden (strict, balanced, permissive)
skill-scanner scan /path/to/skill --policy strict

# Eine benutzerdefinierte Organisationsrichtliniendatei verwenden
skill-scanner scan /path/to/skill --policy my_org_policy.yaml

# Eine Richtliniendatei zur Anpassung generieren
skill-scanner generate-policy -o my_org_policy.yaml

# Interaktiver Richtlinienkonfigurator (TUI)
skill-scanner configure-policy

Der Konsensmodus behält einen Befund nur dann, wenn er in mehr als der Hälfte der konfigurierten Läufe erscheint. Wenn diese Stimmen hinsichtlich des Schweregrads uneinig sind, gewinnt der höchste beobachtete Schweregrad, unabhängig von der Reihenfolge der Antworten. Fehlgeschlagene Läufe und erfolgreiche Läufe, die den Befund auslassen, geben keine Stimme ab, bleiben aber im Nenner. Dies macht die Schweregradauswahl für mehrheitlich bestätigte Befunde stabil. Es macht eine einzelne LLM-Stichprobe nicht deterministisch, und beschreibende Felder aus Stimmen mit gleichem Schweregrad, Einzellauf-Ausgaben und Nicht-Mehrheitsbefunden können zwischen Scans variieren.

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

Python SDK

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

# Scanner mit Analysatoren erstellen
scanner = SkillScanner(analyzers=[
    BehavioralAnalyzer(),
])

# Einen Skill scannen
result = scanner.scan_skill("/path/to/skill")

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

# Hinweis: is_safe zeigt an, dass keine HIGH/CRITICAL-Befunde erkannt wurden.
# Es garantiert nicht, dass der Skill frei von allen Risiken ist.
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: „Keine Befunde" bedeutet, dass der Scanner keine bekannten Bedrohungsmuster erkannt hat – es ist keine Garantie, dass der Skill frei von allen Risiken ist. Siehe Umfang und Einschränkungen.

GitHub Actions

Scannen Sie Skills automatisch bei jedem Push oder PR 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

Ergebnisse erscheinen als Inline-Anmerkungen in PRs über GitHub Code Scanning. Siehe die vollständige Anleitung für LLM-Integration, Geheimnis-Konfiguration und Branch-Schutz-Einrichtung.

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 ordnet geänderte Dateien ihrem nächstgelegenen SKILL.md zu und scannt jeden betroffenen Skill einmal. Während eines normalen Commits liest er den gestaffelten Diff. In CI vergleichen Sie zwei Revisionen, sodass kein gestaffelter Index erforderlich ist:

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

Beide Revisionen müssen im Checkout vorhanden sein. Um jeden konfigurierten Skill zu scannen, rufen Sie den Hook direkt auf:

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

Alternativ konfigurieren Sie args: [--scan-all] für den Hook in .pre-commit-config.yaml.

Beiträge

Wir freuen uns über Beiträge! Bitte lesen Sie CONTRIBUTING.md für Richtlinien.

Lizenz

Apache 2.0 - Siehe LICENSE für Details.

Copyright 2026 Cisco Systems, Inc. und seine Tochtergesellschaften

GitHub • Discord • PyPI