Skill Scanner

Un scanner de sécurité au meilleur effort pour les compétences d'agents IA (AI Agent Skills) qui détecte l'injection de prompt, l'exfiltration de données et les schémas de code malveillant. Il combine la détection par motifs (YAML + YARA), le LLM comme juge et l'analyse comportementale des flux de données afin de maximiser la couverture de détection des menaces probables tout en minimisant les faux positifs.

Important : Ce scanner fournit une détection au meilleur effort, et non une couverture exhaustive ou complète. 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 par LLM et analyse cloud pour une couverture en couches, au meilleur effort
• Filtrage des faux positifs - Le méta-analyseur réduit considérablement le bruit tout en préservant les capacités 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 du 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 schémas 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 « No findings » indique qu'aucun schéma 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 détection par signatures, analyse sémantique par LLM, analyse comportementale des flux de données, services cloud optionnels et 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 des 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 devraient 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

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

Démarrage rapide

Configuration de l'environnement (facultatif)

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

Assistant interactif

Vous ne savez pas quels drapeaux utiliser ? Exécutez skill-scanner sans argument 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

# 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

Remarque sur le fournisseur LLM : --llm-provider accepte actuellement anthropic ou openai. Pour Bedrock, Vertex, Azure, Gemini et les autres backends LiteLLM, définissez des chaînes de modèle et des variables d'environnement spécifiques au fournisseur (voir la documentation de l'analyseur 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")

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 : « No findings » signifie que le scanner n'a détecté aucun schéma 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. Consultez le guide complet pour l'intégration LLM, la configuration des secrets et la mise en place de la protection des branches.

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  # use the latest release tag
    hooks:
      - id: skill-scanner

Ou installez directement le hook intégré :

skill-scanner-pre-commit install

Le hook détecte automatiquement les répertoires de compétences dont les changements sont en staging et n'analyse que ceux-ci, ce qui permet de garder des commits rapides. Utilisez --all pour tout analyser.

Contribuer

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

Licence

Apache 2.0 - Voir LICENSE pour plus de détails.

Copyright 2026 Cisco Systems, Inc. and its affiliates

GitHub • Discord • PyPI