Skill Scanner

Uno scanner di sicurezza best-effort per AI Agent Skills che rileva prompt injection, esfiltrazione di dati e pattern di codice dannoso. Combina rilevamento basato su pattern (YAML + YARA), LLM-as-a-judge e analisi comportamentale del dataflow per massimizzare la copertura di rilevamento delle minacce probabili riducendo al minimo i falsi positivi.

Importante: Questo scanner fornisce un rilevamento best-effort, non una copertura completa o esaustiva. Una scansione che non restituisce risultati non garantisce che una skill sia priva di tutte le minacce. Vedere Ambito e Limitazioni di seguito.

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

Punti Salienti

• Rilevamento Multi-Motore - Analisi statica, dataflow comportamentale, analisi semantica LLM e scansione basata su cloud per una copertura best-effort a più livelli
• 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, workflow GitHub Actions riutilizzabile, codici di uscita per errori di build
• Hook Pre-commit - Integrazione con il framework standard pre-commit per scansionare le skill prima di ogni commit
• Estensibile - 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 chiave:

• Nessun risultato ≠ nessun rischio. Una scansione che restituisce "Nessun risultato" 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 basata su LLM, analisi comportamentale del dataflow, 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 policy 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 distribuzioni ad alto rischio o in produzione dovrebbero abbinare i risultati dello scanner a una revisione manuale del codice e/o alla modellazione delle minacce.

Documentazione

Installazione

Prerequisiti: Python 3.10+ e uv (consigliato) o pip

# Usando uv (consigliato)
uv pip install cisco-ai-skill-scanner

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

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

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

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

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

# Tutti i provider cloud
pip install cisco-ai-skill-scanner[all]

Avvio Rapido

Configurazione dell'Ambiente (Opzionale)

# Per l'analizzatore LLM e il meta-analizzatore
export SKILL_SCANNER_LLM_API_KEY="your_api_key"
export SKILL_SCANNER_LLM_MODEL="claude-3-5-sonnet-20241022"
# Opzionale: disabled, minimal, low, medium, high, xhigh, o max
export SKILL_SCANNER_LLM_REASONING_EFFORT="low"

# Per la scansione binaria VirusTotal
export VIRUSTOTAL_API_KEY="your_virustotal_api_key"

# Per Cisco AI Defense
export AI_DEFENSE_API_KEY="your_aidefense_api_key"

Procedura Guidata Interattiva

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

skill-scanner

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

Utilizzo della CLI

# Scansiona una singola skill (analizzatori core: static + bytecode + pipeline)
skill-scanner scan /path/to/skill

# Scansiona con l'analizzatore comportamentale (analisi del dataflow)
skill-scanner scan /path/to/skill --use-behavioral

# Scansiona con tutti i motori
skill-scanner scan /path/to/skill --use-behavioral --use-llm --use-aidefense

# Scansiona con il meta-analizzatore per il filtraggio dei falsi positivi
skill-scanner scan /path/to/skill --use-llm --enable-meta

# Scansiona con l'analizzatore di trigger per i controlli di descrizioni vaghe
skill-scanner scan /path/to/skill --use-trigger

# Esegui l'analizzatore LLM più volte e mantieni i risultati concordati a maggioranza
skill-scanner scan /path/to/skill --use-llm --llm-consensus-runs 3

# Scansiona più skill in modo ricorsivo
skill-scanner scan-all /path/to/skills --recursive --use-behavioral

# Scansiona più skill con rilevamento di sovrapposizioni tra skill
skill-scanner scan-all /path/to/skills --recursive --check-overlap

# Scansiona un repository GitHub (abbreviazione owner/repo o URL completo)
skill-scanner scan-repo owner/repo
skill-scanner scan-repo https://github.com/owner/repo --use-llm

# Modalità lenient: tollera skill malformate invece di fallire
skill-scanner scan /path/to/skill --lenient
skill-scanner scan-all /path/to/skills --recursive --lenient

# Modalità lenient con formati di skill non standard (SKILL.md non richiesto)
skill-scanner scan .claude/commands/deploy --lenient
skill-scanner scan-all .claude/commands --recursive --lenient

# Usa un nome file di metadati personalizzato invece di SKILL.md
skill-scanner scan /path/to/skill --skill-file README.md

# CI/CD: Fallisci la build se vengono trovate minacce
skill-scanner scan-all ./skills --fail-on-severity high --format sarif --output results.sarif

# Genera un report HTML interattivo con gruppi di correlazione degli attacchi
skill-scanner scan /path/to/skill --use-llm --enable-meta --format html --output report.html

# Usa regole YARA personalizzate
skill-scanner scan /path/to/skill --custom-rules /path/to/my-rules/

# Usa tassonomia personalizzata + profili di mappatura delle minacce (JSON/YAML)
skill-scanner scan /path/to/skill --taxonomy /path/to/taxonomy.json --threat-mapping /path/to/threat_mapping.json

# Scansione hash VirusTotal con caricamento opzionale di file sconosciuti
skill-scanner scan /path/to/skill --use-virustotal --vt-upload-files

# Usa un preset di policy di scansione (strict, balanced, permissive)
skill-scanner scan /path/to/skill --policy strict

# Usa un file di policy organizzativa personalizzato
skill-scanner scan /path/to/skill --policy my_org_policy.yaml

# Genera un file di policy da personalizzare
skill-scanner generate-policy -o my_org_policy.yaml

# Configuratore interattivo della policy (TUI)
skill-scanner configure-policy

La modalità di consenso mantiene un risultato solo quando appare in più della metà delle esecuzioni configurate. Quando questi voti non concordano sulla gravità, vince la gravità osservata più alta, indipendentemente dall'ordine delle risposte. Le esecuzioni fallite e quelle riuscite che omettono il risultato non esprimono voto ma rimangono nel denominatore. Questo rende stabile la selezione della gravità per i risultati concordati a maggioranza. Non rende deterministico un singolo campione LLM, e i campi descrittivi dei voti a parità di gravità, dell'output di una singola esecuzione e dei risultati non di maggioranza possono comunque variare tra le scansioni.

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

SDK Python

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

# Crea lo scanner con gli analizzatori
scanner = SkillScanner(analyzers=[
    BehavioralAnalyzer(),
])

# Scansiona una skill
result = scanner.scan_skill("/path/to/skill")

print(f"Risultati: {len(result.findings)}")
print(f"Gravità massima: {result.max_severity}")

# Nota: is_safe indica che non sono stati rilevati risultati HIGH/CRITICAL.
# Non garantisce che la skill sia priva di ogni rischio.
if not result.is_safe:
    print("Rilevati problemi -- rivedi i risultati prima della distribuzione")

Analizzatori di Sicurezza

Opzioni CLI

Esempio di Output

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

============================================================
Skill: my-skill
============================================================
Stato: [OK] Nessun risultato
Gravità Massima: NONE
Totale Risultati: 0
Durata Scansione: 0.15s

Nota: "Nessun risultato" significa che lo scanner non ha rilevato alcun pattern di minaccia noto -- non è una garanzia che la skill sia priva di ogni rischio. Vedere Ambito e Limitazioni.

GitHub Actions

Scansiona le skill automaticamente a ogni push o PR usando il workflow 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 branch.

Hook Pre-commit

Scansiona le skill prima di ogni commit usando il framework pre-commit:

# .pre-commit-config.yaml
repos:
  - repo: https://github.com/cisco-ai-defense/skill-scanner
    rev: v1.0.0  # usa l'ultimo tag di release
    hooks:
      - id: skill-scanner

Oppure installa direttamente l'hook integrato:

skill-scanner-pre-commit --install

L'hook mappa i file modificati al loro SKILL.md più vicino e scansiona ogni skill interessata una volta. Durante un commit normale, legge il diff in staging. In CI, confronta due revisioni così non è richiesto alcun indice in staging:

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

Entrambe le revisioni devono esistere nel checkout. Per scansionare ogni skill configurata, invoca direttamente l'hook:

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

In alternativa, configura args: [--scan-all] per l'hook in .pre-commit-config.yaml.

Contributi

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 le sue affiliate

GitHub • Discord • PyPI