cisco-ai-skill-scanner

2.0.11 verified Sat May 09 auth: no python

Security scanner for AI agent skills packages (e.g., MCP, plugins). Detects prompt injection, data exfiltration, and malicious code. Version 2.0.11, active development with frequent releases.

pip install cisco-ai-skill-scanner

Common errors

error ModuleNotFoundError: No module named 'cisco_ai_skill_scanner' ↓

cause Package is not installed or imported with wrong name (using hyphens instead of underscores).

fix

Install: pip install cisco-ai-skill-scanner. Import: from cisco_ai_skill_scanner import ...

error UnicodeDecodeError: 'charmap' codec can't decode byte ... ↓

cause The skill package contains non-UTF-8 encoded files (e.g., binary). The scanner expects UTF-8 by default.

fix

Ensure all text files in the skill package are UTF-8 encoded. For legacy skills, use --lenient (deprecated) or pre-process files.

error ValueError: Unsupported skill format ↓

cause The provided path is not a recognized skill package (must be a .zip file or directory with SKILL.md manifest).

fix

Check that the skill contains a valid SKILL.md file at the root of the archive/directory.

Warnings

breaking In version 2.0.0, the API was restructured. The old function `scan_skill_directory` was removed; use `scan_skill` instead. ↓

fix Replace `scan_skill_directory(path)` with `scan_skill(path)`.

deprecated The `--lenient` CLI flag is deprecated and may be removed in a future version. Its behavior allowed binary/non-UTF-8 content to pass the loader, which introduced security risks. ↓

fix Avoid using `--lenient`. If you need to skip UTF-8 validation, handle decoding manually.

gotcha LLM scanning requires setting environment variables (e.g., `GOOGLE_API_KEY`). Without them, LLM-based rules are skipped silently. ↓

fix Set the relevant API key before calling scan_skill, or use `--llm-provider none` in CLI to disable LLM scanning explicitly.

Imports

SkillScanner

wrong

from skill_scanner import SkillScanner

correct

from cisco_ai_skill_scanner import SkillScanner

Package name uses hyphens on PyPI but underscores in Python imports

scan_skill

wrong

from cisco_ai_skill_scanner.scanner import scan_skill

correct

from cisco_ai_skill_scanner import scan_skill

The function is exposed at top-level, not inside a submodule

Quickstart

Scan an AI skill package for security vulnerabilities.

import os
from cisco_ai_skill_scanner import scan_skill

# Path to the skill package (zip or directory)
skill_path = "./my_skill.zip"

# Optional: set Google API key for LLM-based scanning
os.environ['GOOGLE_API_KEY'] = os.environ.get('GOOGLE_API_KEY', '')

# Run the scan (returns a list of findings)
findings = scan_skill(skill_path)

for f in findings:
    print(f"Severity: {f.severity} - {f.message}")