Skill Scanner

Un scanner de sécurité « best-effort » pour les compétences d'agent IA qui détecte les injections de prompt, l'exfiltration de données et les modèles de code malveillant. Il combine la détection par motifs (YAML + YARA), le LLM comme juge et l'analyse comportementale de flux de données pour maximiser la couverture de détection des menaces probables tout en minimisant les faux positifs.

Important : Ce scanner fournit une détection « best-effort », pas une couverture complète ou exhaustive. Une analyse qui ne renvoie aucun résultat ne garantit pas qu'une compétence est exempte de toute menace. Voir Portée et limites ci-dessous.

Prend en charge les formats OpenAI Codex Skills et Cursor Agent Skills conformément à la spécification Agent Skills. Avec --lenient, il analyse également les formats non standard tels que .claude/commands/*.md de Claude Code et les dépôts de compétences en Markdown plat.

Points forts

• Détection multi-moteurs - Analyse statique, flux de données comportemental, analyse sémantique LLM et analyse cloud pour une couverture « best-effort » en couches
• Filtrage des faux positifs - Le méta-analyseur réduit considérablement le bruit tout en préservant la capacité de détection
• Prêt pour CI/CD - Sortie SARIF pour GitHub Code Scanning, workflow GitHub Actions réutilisable, codes de sortie pour les échecs de build
• Hook Pre-commit - Intégration avec le framework standard pre-commit pour analyser les compétences avant chaque commit
• Extensible - Architecture de plugins pour des analyseurs personnalisés

Rejoignez le Discord Cisco AI pour discuter, partager vos retours ou contacter l'équipe.

Portée et limites

Skill Scanner est un outil de détection. Il identifie les modèles de risque connus et probables, mais il ne certifie pas la sécurité.

Limites clés :

• Aucun résultat ≠ aucun risque. Une analyse qui renvoie « Aucun résultat » indique qu'aucun modèle de menace connu n'a été détecté. Elle ne garantit pas qu'une compétence est sécurisée, bénigne ou exempte de vulnérabilités.
• La couverture est intrinsèquement incomplète. Le scanner combine la détection par signatures, l'analyse sémantique basée sur LLM, l'analyse comportementale de flux de données, des services cloud optionnels et des packs de règles configurables. Bien que cette approche améliore la couverture, aucun outil automatisé ne peut détecter toutes les techniques, en particulier les attaques nouvelles ou zero-day.
• Des faux positifs et faux négatifs peuvent survenir. Les modes de consensus et la méta-analyse réduisent le bruit, mais aucune configuration n'élimine toutes les classifications incorrectes. Ajustez la politique d'analyse en fonction de votre tolérance au risque.
• La revue humaine reste essentielle. L'analyse automatisée est un composant d'une stratégie de défense en profondeur. Les déploiements à haut risque ou en production doivent associer les résultats du scanner à une revue manuelle du code et/ou à une modélisation des menaces.

Documentation

Installation

Prérequis : Python 3.10+ et uv (recommandé) ou pip

# Avec uv (recommandé)
uv pip install cisco-ai-skill-scanner

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

# Prise en charge AWS Bedrock
pip install cisco-ai-skill-scanner[bedrock]

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

# Prise en charge Google Vertex AI
pip install cisco-ai-skill-scanner[vertex]

# Prise en charge Azure OpenAI
pip install cisco-ai-skill-scanner[azure]

# Tous les fournisseurs cloud
pip install cisco-ai-skill-scanner[all]

Démarrage rapide

Configuration de l'environnement (optionnel)

# Pour l'analyseur LLM et le méta-analyseur
export SKILL_SCANNER_LLM_API_KEY="your_api_key"
export SKILL_SCANNER_LLM_MODEL="claude-3-5-sonnet-20241022"
# Optionnel : disabled, minimal, low, medium, high, xhigh, ou max
export SKILL_SCANNER_LLM_REASONING_EFFORT="low"

# Pour l'analyse binaire VirusTotal
export VIRUSTOTAL_API_KEY="your_virustotal_api_key"

# Pour Cisco AI Defense
export AI_DEFENSE_API_KEY="your_aidefense_api_key"

Assistant interactif

Vous ne savez pas quels indicateurs utiliser ? Exécutez skill-scanner sans arguments pour lancer l'assistant interactif :

skill-scanner

L'assistant vous guide dans la sélection d'une cible d'analyse, des analyseurs, de la politique et du format de sortie, puis affiche la commande assemblée avant de l'exécuter. Idéal pour apprendre la CLI.

Utilisation de la CLI

# Analyser une seule compétence (analyseurs de base : statique + bytecode + pipeline)
skill-scanner scan /path/to/skill

# Analyser avec l'analyseur comportemental (analyse de flux de données)
skill-scanner scan /path/to/skill --use-behavioral

# Analyser avec tous les moteurs
skill-scanner scan /path/to/skill --use-behavioral --use-llm --use-aidefense

# Analyser avec le méta-analyseur pour le filtrage des faux positifs
skill-scanner scan /path/to/skill --use-llm --enable-meta

# Analyser avec l'analyseur de déclenchement pour les vérifications de descriptions vagues
skill-scanner scan /path/to/skill --use-trigger

# Exécuter l'analyseur LLM plusieurs fois et conserver les résultats approuvés à la majorité
skill-scanner scan /path/to/skill --use-llm --llm-consensus-runs 3

# Analyser plusieurs compétences de manière récursive
skill-scanner scan-all /path/to/skills --recursive --use-behavioral

# Analyser plusieurs compétences avec détection de chevauchement entre compétences
skill-scanner scan-all /path/to/skills --recursive --check-overlap

# Analyser un dépôt GitHub (raccourci propriétaire/dépôt ou URL complète)
skill-scanner scan-repo owner/repo
skill-scanner scan-repo https://github.com/owner/repo --use-llm

# Mode permissif : tolérer les compétences malformées au lieu d'échouer
skill-scanner scan /path/to/skill --lenient
skill-scanner scan-all /path/to/skills --recursive --lenient

# Mode permissif avec formats de compétences non standard (pas de SKILL.md requis)
skill-scanner scan .claude/commands/deploy --lenient
skill-scanner scan-all .claude/commands --recursive --lenient

# Utiliser un nom de fichier de métadonnées personnalisé au lieu de SKILL.md
skill-scanner scan /path/to/skill --skill-file README.md

# CI/CD : Échouer le build si des menaces sont trouvées
skill-scanner scan-all ./skills --fail-on-severity high --format sarif --output results.sarif

# Générer un rapport HTML interactif avec des groupes de corrélation d'attaques
skill-scanner scan /path/to/skill --use-llm --enable-meta --format html --output report.html

# Utiliser des règles YARA personnalisées
skill-scanner scan /path/to/skill --custom-rules /path/to/my-rules/

# Utiliser une taxonomie personnalisée + des profils de mappage des menaces (JSON/YAML)
skill-scanner scan /path/to/skill --taxonomy /path/to/taxonomy.json --threat-mapping /path/to/threat_mapping.json

# Analyse de hachage VirusTotal avec téléversement optionnel des fichiers inconnus
skill-scanner scan /path/to/skill --use-virustotal --vt-upload-files

# Utiliser un préréglage de politique d'analyse (strict, balanced, permissive)
skill-scanner scan /path/to/skill --policy strict

# Utiliser un fichier de politique organisationnelle personnalisé
skill-scanner scan /path/to/skill --policy my_org_policy.yaml

# Générer un fichier de politique à personnaliser
skill-scanner generate-policy -o my_org_policy.yaml

# Configurateur de politique interactif (TUI)
skill-scanner configure-policy

Le mode consensus ne conserve un résultat que lorsqu'il apparaît dans plus de la moitié des exécutions configurées. Lorsque ces votes sont en désaccord sur la sévérité, la sévérité observée la plus élevée l'emporte, indépendamment de l'ordre des réponses. Les exécutions échouées et les exécutions réussies qui omettent le résultat ne votent pas mais restent dans le dénominateur. Cela rend la sélection de sévérité stable pour les résultats approuvés à la majorité. Cela ne rend pas un échantillon LLM individuel déterministe, et les champs descriptifs des votes de sévérité égale, de la sortie d'une seule exécution et des résultats non majoritaires peuvent encore varier entre les analyses.

Remarque sur le fournisseur LLM : --llm-provider accepte actuellement anthropic ou openai. Pour Bedrock, Vertex, Azure, Gemini et autres backends LiteLLM, définissez des chaînes de modèle et des variables d'environnement spécifiques au fournisseur (voir docs de l'analyseur LLM).

SDK Python

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

# Créer un scanner avec des analyseurs
scanner = SkillScanner(analyzers=[
    BehavioralAnalyzer(),
])

# Analyser une compétence
result = scanner.scan_skill("/path/to/skill")

print(f"Résultats : {len(result.findings)}")
print(f"Sévérité maximale : {result.max_severity}")

# Remarque : is_safe indique qu'aucun résultat HIGH/CRITICAL n'a été détecté.
# Cela ne garantit pas que la compétence est exempte de tout risque.
if not result.is_safe:
    print("Problèmes détectés -- examinez les résultats avant le déploiement")

Analyseurs de sécurité

Options de la CLI

Exemple de sortie

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

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

Remarque : « Aucun résultat » signifie que le scanner n'a détecté aucun modèle de menace connu -- ce n'est pas une garantie que la compétence est exempte de tout risque. Voir Portée et limites.

GitHub Actions

Analysez automatiquement les compétences à chaque push ou PR à l'aide du workflow réutilisable :

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

Les résultats apparaissent sous forme d'annotations en ligne dans les PR via GitHub Code Scanning. Voir le guide complet pour l'intégration LLM, la configuration des secrets et la configuration de la protection de branche.

Hook Pre-commit

Analysez les compétences avant chaque commit à l'aide du framework pre-commit :

# .pre-commit-config.yaml
repos:
  - repo: https://github.com/cisco-ai-defense/skill-scanner
    rev: v1.0.0  # utilisez le dernier tag de version
    hooks:
      - id: skill-scanner

Ou installez directement le hook intégré :

skill-scanner-pre-commit --install

Le hook fait correspondre les fichiers modifiés à leur SKILL.md le plus proche et analyse chaque compétence affectée une fois. Lors d'un commit normal, il lit le diff indexé. En CI, comparez deux révisions afin qu'aucun index indexé ne soit requis :

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

Les deux révisions doivent exister dans le checkout. Pour analyser chaque compétence configurée, invoquez directement le hook :

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

Alternativement, configurez args: [--scan-all] pour le hook dans .pre-commit-config.yaml.

Contribuer

Nous accueillons les contributions ! Veuillez consulter CONTRIBUTING.md pour les directives.

Licence

Apache 2.0 - Voir LICENSE pour les détails.

Copyright 2026 Cisco Systems, Inc. et ses affiliés

GitHub • Discord • PyPI