Skill Scanner

Uno scanner di sicurezza che opera al meglio delle possibilità per le Skill di Agenti AI, in grado di rilevare prompt injection, data exfiltration e pattern di codice dannoso. Combina rilevamento basato su pattern (YAML + YARA), LLM-as-a-judge e analisi comportamentale del flusso di dati per massimizzare la copertura di rilevamento delle minacce probabili minimizzando i falsi positivi.

Importante: Questo scanner fornisce un rilevamento al meglio delle possibilità, non una copertura completa o esaustiva. Una scansione che non restituisce alcun riscontro non garantisce che una skill sia priva di tutte le minacce. Vedi Ambito e Limitazioni di seguito.

Supporta i formati OpenAI Codex Skills e Cursor Agent Skills seguendo la specifica Agent Skills. Con --lenient, scansiona anche formati non standard come .claude/commands/*.md di Claude Code e repository di skill in markdown flat.

Punti salienti

• Rilevamento Multi-Motore - Analisi statica, flusso di dati comportamentale, analisi semantica LLM e scansione cloud per una copertura a strati al meglio delle possibilità
• Filtraggio dei Falsi Positivi - Il meta-analizzatore riduce significativamente il rumore preservando la capacità di rilevamento
• Pronto per CI/CD - Output SARIF per GitHub Code Scanning, flusso di lavoro GitHub Actions riutilizzabile, codici di uscita per fallimenti di build
• Hook Pre-commit - Integrazione con il framework standard pre-commit per scansionare le skill prima di ogni commit
• Estendibile - Architettura a plugin per analizzatori personalizzati

Unisciti al Discord Cisco AI per discutere, condividere feedback o contattare il team.

Ambito e Limitazioni

Skill Scanner è uno strumento di rilevamento. Identifica pattern di rischio noti e probabili, ma non certifica la sicurezza.

Limitazioni principali:

• Nessun riscontro ≠ nessun rischio. Una scansione che restituisce "Nessun riscontro" indica che non sono stati rilevati pattern di minaccia noti. Non garantisce che una skill sia sicura, benigna o priva di vulnerabilità.
• La copertura è intrinsecamente incompleta. Lo scanner combina rilevamento basato su firme, analisi semantica LLM, analisi comportamentale del flusso di dati, servizi cloud opzionali e pacchetti di regole configurabili. Sebbene questo approccio migliori la copertura, nessuno strumento automatizzato può rilevare ogni tecnica, specialmente attacchi nuovi o zero-day.
• Possono verificarsi falsi positivi e falsi negativi. Le modalità di consenso e la meta-analisi riducono il rumore, ma nessuna configurazione elimina tutte le classificazioni errate. Regola la politica di scansione in base alla tua tolleranza al rischio.
• La revisione umana rimane essenziale. La scansione automatizzata è una componente di una strategia di difesa in profondità. Le implementazioni ad alto rischio o in produzione dovrebbero abbinare i risultati dello scanner a una revisione manuale del codice e/o a un modello di minaccia.

Documentazione

Installazione

Prerequisiti: Python 3.10+ e uv (consigliato) o 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]

Avvio Rapido

Configurazione dell'Ambiente (Opzionale)

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

Procedura Guidata Interattiva

Non sei sicuro di quali flag usare? Esegui skill-scanner senza argomenti per avviare la procedura guidata interattiva:

skill-scanner

La procedura guidata ti accompagna nella selezione di un target di scansione, analizzatori, politica e formato di output, quindi mostra il comando assemblato prima di eseguirlo. Ottima per imparare la CLI.

Utilizzo 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

Nota sul provider LLM: --llm-provider attualmente accetta anthropic o openai. Per i backend Bedrock, Vertex, Azure, Gemini e altri LiteLLM, imposta le stringhe del modello specifiche del provider e le variabili d'ambiente (vedi documentazione Analizzatore LLM).

SDK Python

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

Analizzatori di Sicurezza

Opzioni CLI

Esempio di Output

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

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

Nota: "Nessun riscontro" significa che lo scanner non ha rilevato alcun pattern di minaccia noto -- non è una garanzia che la skill sia priva di tutti i rischi. Vedi Ambito e Limitazioni.

GitHub Actions

Scansiona le skill automaticamente ad ogni push o PR utilizzando il flusso di lavoro riutilizzabile:

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

I risultati appaiono come annotazioni inline nelle PR tramite GitHub Code Scanning. Vedi la guida completa per l'integrazione LLM, la configurazione dei segreti e la configurazione della protezione dei rami.

Hook Pre-commit

Scansiona le skill prima di ogni commit utilizzando il framework 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

Oppure installa direttamente l'hook integrato:

skill-scanner-pre-commit install

L'hook rileva automaticamente quali directory di skill hanno modifiche in stage e scansiona solo quelle, mantenendo i tempi di commit veloci. Usa --all per scansionare tutto.

Contribuire

Accogliamo con piacere i contributi! Consulta CONTRIBUTING.md per le linee guida.

Licenza

Apache 2.0 - Vedi LICENSE per i dettagli.

Copyright 2026 Cisco Systems, Inc. e affiliate

GitHub • Discord • PyPI