cisco-ai-skill-scanner 1.0.0__py3-none-any.whl

skillanalyzer/core/loader.py

@@ -0,0 +1,377 @@
+# Copyright 2026 Cisco Systems, Inc.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+# SPDX-License-Identifier: Apache-2.0
+
+"""
+Skill package loader and SKILL.md parser.
+"""
+
+import re
+from pathlib import Path
+
+import frontmatter
+
+from .models import Skill, SkillFile, SkillManifest
+
+
+class SkillLoadError(Exception):
+    """Exception raised when skill loading fails."""
+
+    pass
+
+
+class SkillLoader:
+    """Loads and parses Claude Skill, Codex Skill, and Cursor Agent Skill packages.
+
+    Supports the Agent Skills specification format used by Claude Skills,
+    OpenAI Codex Skills, and Cursor Agent Skills. Skills are structured as:
+    - SKILL.md (required): YAML frontmatter + Markdown instructions
+    - scripts/ (optional): Executable code (Python, Bash)
+    - references/ (optional): Documentation and data files
+    - assets/ (optional): Templates, images, and other resources
+    """
+
+    # File type mappings
+    PYTHON_EXTENSIONS = {".py"}
+    BASH_EXTENSIONS = {".sh", ".bash"}
+    MARKDOWN_EXTENSIONS = {".md", ".markdown"}
+    BINARY_EXTENSIONS = {".exe", ".so", ".dylib", ".dll", ".bin"}
+
+    def __init__(self, max_file_size_mb: int = 10):
+        """
+        Initialize skill loader.
+
+        Args:
+            max_file_size_mb: Maximum file size to read in MB
+        """
+        self.max_file_size_bytes = max_file_size_mb * 1024 * 1024
+
+    def load_skill(self, skill_directory: Path) -> Skill:
+        """
+        Load a skill package from a directory.
+
+        Args:
+            skill_directory: Path to the skill directory
+
+        Returns:
+            Parsed Skill object
+
+        Raises:
+            SkillLoadError: If skill cannot be loaded
+        """
+        if not isinstance(skill_directory, Path):
+            skill_directory = Path(skill_directory)
+
+        if not skill_directory.exists():
+            raise SkillLoadError(f"Skill directory does not exist: {skill_directory}")
+
+        if not skill_directory.is_dir():
+            raise SkillLoadError(f"Path is not a directory: {skill_directory}")
+
+        # Find SKILL.md
+        skill_md_path = skill_directory / "SKILL.md"
+        if not skill_md_path.exists():
+            raise SkillLoadError(f"SKILL.md not found in {skill_directory}")
+
+        # Parse SKILL.md
+        manifest, instruction_body = self._parse_skill_md(skill_md_path)
+
+        # Discover all files in the skill package
+        files = self._discover_files(skill_directory)
+
+        # Extract referenced files from instruction body
+        referenced_files = self._extract_referenced_files(instruction_body)
+
+        return Skill(
+            directory=skill_directory,
+            manifest=manifest,
+            skill_md_path=skill_md_path,
+            instruction_body=instruction_body,
+            files=files,
+            referenced_files=referenced_files,
+        )
+
+    def _parse_skill_md(self, skill_md_path: Path) -> tuple[SkillManifest, str]:
+        """
+        Parse SKILL.md file with YAML frontmatter.
+
+        Args:
+            skill_md_path: Path to SKILL.md
+
+        Returns:
+            Tuple of (SkillManifest, instruction_body)
+
+        Raises:
+            SkillLoadError: If parsing fails
+        """
+        try:
+            with open(skill_md_path, encoding="utf-8") as f:
+                content = f.read()
+        except (OSError, UnicodeDecodeError) as e:
+            raise SkillLoadError(f"Failed to read SKILL.md: {e}")
+
+        # Parse with python-frontmatter
+        try:
+            post = frontmatter.loads(content)
+            metadata = post.metadata
+            body = post.content
+        except Exception as e:
+            raise SkillLoadError(f"Failed to parse YAML frontmatter: {e}")
+
+        # Validate required fields
+        if "name" not in metadata:
+            raise SkillLoadError("SKILL.md missing required field: name")
+        if "description" not in metadata:
+            raise SkillLoadError("SKILL.md missing required field: description")
+
+        # Extract metadata field - if YAML has a 'metadata' key, use it directly
+        # Otherwise, collect remaining fields as metadata
+        metadata_field = None
+        if "metadata" in metadata and isinstance(metadata["metadata"], dict):
+            # YAML has explicit metadata key (Codex Skills format)
+            metadata_field = metadata["metadata"]
+        else:
+            # Collect remaining fields as metadata (Claude Skills format)
+            # Exclude known fields from being collected as metadata
+            known_fields = [
+                "name",
+                "description",
+                "license",
+                "compatibility",
+                "allowed-tools",
+                "allowed_tools",
+                "metadata",
+                "disable-model-invocation",
+                "disable_model_invocation",
+            ]
+            metadata_field = {k: v for k, v in metadata.items() if k not in known_fields}
+            # Only set metadata if there are remaining fields
+            if not metadata_field:
+                metadata_field = None
+
+        # Extract disable-model-invocation (Cursor Agent Skills format)
+        # Supports both kebab-case and snake_case variants
+        # Use explicit None check to properly handle `false` values
+        disable_model_invocation = metadata.get("disable-model-invocation")
+        if disable_model_invocation is None:
+            disable_model_invocation = metadata.get("disable_model_invocation", False)
+
+        # Create manifest
+        manifest = SkillManifest(
+            name=metadata["name"],
+            description=metadata["description"],
+            license=metadata.get("license"),
+            compatibility=metadata.get("compatibility"),
+            allowed_tools=metadata.get("allowed-tools") or metadata.get("allowed_tools"),
+            metadata=metadata_field,
+            disable_model_invocation=bool(disable_model_invocation),
+        )
+
+        return manifest, body
+
+    def _discover_files(self, skill_directory: Path) -> list[SkillFile]:
+        """
+        Discover all files in the skill package.
+
+        Args:
+            skill_directory: Path to skill directory
+
+        Returns:
+            List of SkillFile objects
+        """
+        files = []
+
+        for path in skill_directory.rglob("*"):
+            if not path.is_file():
+                continue
+
+            # Skip hidden files and __pycache__ (relative to the skill directory)
+            #
+            # Important: Skills may live under hidden parent directories like `.claude/skills/`.
+            # We only want to skip hidden files/folders *inside* the skill package, not its parents.
+            rel_parts = path.relative_to(skill_directory).parts
+            if any(part.startswith(".") for part in rel_parts):
+                continue
+            if "__pycache__" in rel_parts:
+                continue
+
+            relative_path = str(path.relative_to(skill_directory))
+            file_type = self._determine_file_type(path)
+            size_bytes = path.stat().st_size
+
+            # Read content if not too large and not binary
+            content = None
+            if size_bytes < self.max_file_size_bytes and file_type != "binary":
+                try:
+                    with open(path, encoding="utf-8") as f:
+                        content = f.read()
+                except (OSError, UnicodeDecodeError):
+                    # Treat as binary if can't read as text
+                    file_type = "binary"
+
+            skill_file = SkillFile(
+                path=path,
+                relative_path=relative_path,
+                file_type=file_type,
+                content=content,
+                size_bytes=size_bytes,
+            )
+            files.append(skill_file)
+
+        return files
+
+    def _determine_file_type(self, path: Path) -> str:
+        """
+        Determine the type of a file based on extension.
+
+        Args:
+            path: File path
+
+        Returns:
+            File type string
+        """
+        suffix = path.suffix.lower()
+
+        if suffix in self.PYTHON_EXTENSIONS:
+            return "python"
+        elif suffix in self.BASH_EXTENSIONS:
+            return "bash"
+        elif suffix in self.MARKDOWN_EXTENSIONS:
+            return "markdown"
+        elif suffix in self.BINARY_EXTENSIONS:
+            return "binary"
+        else:
+            return "other"
+
+    def _extract_referenced_files(self, instruction_body: str) -> list[str]:
+        """
+        Extract file references from instruction body.
+
+        Looks for markdown links, common file reference patterns, directives,
+        and other ways files might be referenced.
+
+        Args:
+            instruction_body: The markdown instruction text
+
+        Returns:
+            List of referenced file paths
+        """
+        references = []
+
+        # Match markdown links: [text](file.md)
+        markdown_links = re.findall(r"\[([^\]]+)\]\(([^\)]+)\)", instruction_body)
+        for _, link in markdown_links:
+            # Filter out URLs, keep relative file paths
+            if not link.startswith(("http://", "https://", "ftp://", "#")):
+                references.append(link)
+
+        # Match "see FILE.md" or "refer to FILE.md" patterns
+        # Use backticks or quotes to identify actual file references, avoiding false matches like "the.py"
+        see_patterns = re.findall(
+            r"(?:see|refer to|check|read)\s+[`'\"]([A-Za-z0-9_\-./]+\.(?:md|py|sh|txt))[`'\"]",
+            instruction_body,
+            re.IGNORECASE,
+        )
+        references.extend(see_patterns)
+
+        # Match script execution patterns: scripts/foo.py
+        script_patterns = re.findall(
+            r"(?:run|execute|invoke)\s+([A-Za-z0-9_\-./]+\.(?:py|sh))", instruction_body, re.IGNORECASE
+        )
+        references.extend(script_patterns)
+
+        # Match @reference: directives (common in documentation)
+        reference_directives = re.findall(r"@reference:\s*([A-Za-z0-9_\-./]+)", instruction_body, re.IGNORECASE)
+        references.extend(reference_directives)
+
+        # Match include: statements
+        include_patterns = re.findall(
+            r"(?:include|import|load):\s*([A-Za-z0-9_\-./]+\.(?:md|py|sh|txt|yaml|json))",
+            instruction_body,
+            re.IGNORECASE,
+        )
+        references.extend(include_patterns)
+
+        # Match file paths in code blocks that look like references
+        code_file_refs = re.findall(r"(?:from|import)\s+([A-Za-z0-9_]+)\s", instruction_body)
+        # Only add if it looks like a local module (not standard lib)
+        for ref in code_file_refs:
+            if not ref.startswith(("os", "sys", "re", "json", "yaml", "typing")):
+                references.append(f"{ref}.py")
+
+        # Match references/* or assets/* patterns
+        asset_patterns = re.findall(r"(?:references|assets|templates)/([A-Za-z0-9_\-./]+)", instruction_body)
+        for pattern in asset_patterns:
+            references.append(f"references/{pattern}")
+            references.append(f"assets/{pattern}")
+            references.append(f"templates/{pattern}")
+
+        # Return unique references
+        return list(set(references))
+
+    def extract_references_from_file(self, file_path: Path, content: str) -> list[str]:
+        """
+        Extract references from a specific file based on its type.
+
+        Args:
+            file_path: Path to the file
+            content: File content
+
+        Returns:
+            List of referenced file paths
+        """
+        references = []
+        suffix = file_path.suffix.lower()
+
+        if suffix in (".md", ".markdown"):
+            # Use the standard markdown extraction
+            references.extend(self._extract_referenced_files(content))
+
+        elif suffix == ".py":
+            # Extract Python imports that might be local modules
+            import_patterns = re.findall(r"^from\s+([A-Za-z0-9_.]+)\s+import", content, re.MULTILINE)
+            relative_imports = re.findall(r"^from\s+\.([A-Za-z0-9_.]*)\s+import", content, re.MULTILINE)
+
+            for imp in import_patterns:
+                # Only include if it looks like a local module
+                if not imp.startswith(("os", "sys", "re", "json", "pathlib", "typing", "collections")):
+                    parts = imp.split(".")
+                    references.append(f"{parts[0]}.py")
+
+            for imp in relative_imports:
+                if imp:
+                    references.append(f"{imp}.py")
+
+        elif suffix in (".sh", ".bash"):
+            # Extract source commands
+            source_patterns = re.findall(r"(?:source|\.)\s+([A-Za-z0-9_\-./]+\.(?:sh|bash))", content)
+            references.extend(source_patterns)
+
+        return list(set(references))
+
+
+def load_skill(skill_directory: Path, max_file_size_mb: int = 10) -> Skill:
+    """
+    Convenience function to load a skill package.
+
+    Args:
+        skill_directory: Path to skill directory
+        max_file_size_mb: Maximum file size to read
+
+    Returns:
+        Loaded Skill object
+    """
+    loader = SkillLoader(max_file_size_mb=max_file_size_mb)
+    return loader.load_skill(skill_directory)

skillanalyzer/core/models.py

@@ -0,0 +1,300 @@
+# Copyright 2026 Cisco Systems, Inc.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+# SPDX-License-Identifier: Apache-2.0
+
+"""
+Data models for Claude Skills and security findings.
+"""
+
+from dataclasses import dataclass, field
+from datetime import datetime
+from enum import Enum
+from pathlib import Path
+from typing import Any
+
+
+class Severity(str, Enum):
+    """Severity levels for security findings."""
+
+    CRITICAL = "CRITICAL"
+    HIGH = "HIGH"
+    MEDIUM = "MEDIUM"
+    LOW = "LOW"
+    INFO = "INFO"
+    SAFE = "SAFE"
+
+
+class ThreatCategory(str, Enum):
+    """Categories of security threats."""
+
+    PROMPT_INJECTION = "prompt_injection"
+    COMMAND_INJECTION = "command_injection"
+    DATA_EXFILTRATION = "data_exfiltration"
+    UNAUTHORIZED_TOOL_USE = "unauthorized_tool_use"
+    OBFUSCATION = "obfuscation"
+    HARDCODED_SECRETS = "hardcoded_secrets"
+    SOCIAL_ENGINEERING = "social_engineering"
+    RESOURCE_ABUSE = "resource_abuse"
+    POLICY_VIOLATION = "policy_violation"
+    MALWARE = "malware"
+    # New threat categories
+    SKILL_DISCOVERY_ABUSE = "skill_discovery_abuse"
+    TRANSITIVE_TRUST_ABUSE = "transitive_trust_abuse"
+    AUTONOMY_ABUSE = "autonomy_abuse"
+    TOOL_CHAINING_ABUSE = "tool_chaining_abuse"
+    UNICODE_STEGANOGRAPHY = "unicode_steganography"
+
+
+@dataclass
+class SkillManifest:
+    """Parsed YAML frontmatter from SKILL.md.
+
+    Supports Claude Skills, Codex Skills, and Cursor Agent Skills formats,
+    which follow the Agent Skills specification. The format includes:
+    - Required: name, description
+    - Optional: license, compatibility, allowed-tools, metadata
+    - Cursor Skills: disable-model-invocation (controls automatic invocation)
+    - Codex Skills: metadata.short-description (optional user-facing description)
+    """
+
+    name: str
+    description: str
+    license: str | None = None
+    compatibility: str | None = None
+    allowed_tools: list[str] | None = None
+    metadata: dict[str, Any] | None = None
+    disable_model_invocation: bool = False
+
+    def __post_init__(self):
+        """Normalize allowed_tools to list."""
+        if self.allowed_tools is None:
+            self.allowed_tools = []
+        elif isinstance(self.allowed_tools, str):
+            # Claude Code/Codex docs commonly show comma-separated tool lists in YAML frontmatter
+            # (e.g., "allowed-tools: Read, Grep, Glob"). Treat this as a list.
+            parts = [p.strip() for p in self.allowed_tools.split(",")]
+            self.allowed_tools = [p for p in parts if p]
+
+    @property
+    def short_description(self) -> str | None:
+        """Get short-description from metadata (Codex Skills format)."""
+        if self.metadata and isinstance(self.metadata, dict):
+            return self.metadata.get("short-description")
+        return None
+
+
+@dataclass
+class SkillFile:
+    """A file within a skill package."""
+
+    path: Path
+    relative_path: str
+    file_type: str  # 'markdown', 'python', 'bash', 'binary', 'other'
+    content: str | None = None
+    size_bytes: int = 0
+
+    def read_content(self) -> str:
+        """Read file content if not already loaded."""
+        if self.content is None and self.path.exists():
+            try:
+                with open(self.path, encoding="utf-8") as f:
+                    self.content = f.read()
+            except (OSError, UnicodeDecodeError):
+                self.content = ""  # Binary or unreadable file
+        return self.content or ""
+
+
+@dataclass
+class Skill:
+    """Represents a complete Claude Skill, Codex Skill, or Cursor Agent Skill package.
+
+    Supports the Agent Skills specification format used by Claude Skills,
+    OpenAI Codex Skills, and Cursor Agent Skills. The package structure includes:
+    - SKILL.md (required): Manifest and instructions
+    - scripts/ (optional): Executable code
+    - references/ (optional): Documentation files
+    - assets/ (optional): Templates and resources
+    """
+
+    directory: Path
+    manifest: SkillManifest
+    skill_md_path: Path
+    instruction_body: str
+    files: list[SkillFile] = field(default_factory=list)
+    referenced_files: list[str] = field(default_factory=list)
+
+    @property
+    def name(self) -> str:
+        return self.manifest.name
+
+    @property
+    def description(self) -> str:
+        return self.manifest.description
+
+    def get_scripts(self) -> list[SkillFile]:
+        """Get all script files (Python, Bash)."""
+        return [f for f in self.files if f.file_type in ("python", "bash")]
+
+    def get_markdown_files(self) -> list[SkillFile]:
+        """Get all markdown files."""
+        return [f for f in self.files if f.file_type == "markdown"]
+
+
+@dataclass
+class Finding:
+    """A security issue discovered in a skill."""
+
+    id: str  # Unique finding identifier (e.g., rule ID + line number)
+    rule_id: str  # Rule that triggered this finding
+    category: ThreatCategory
+    severity: Severity
+    title: str
+    description: str
+    file_path: str | None = None
+    line_number: int | None = None
+    snippet: str | None = None
+    remediation: str | None = None
+    analyzer: str | None = None  # Which analyzer produced this finding (e.g., "static", "llm", "behavioral")
+    metadata: dict[str, Any] = field(default_factory=dict)
+
+    def to_dict(self) -> dict[str, Any]:
+        """Convert finding to dictionary."""
+        return {
+            "id": self.id,
+            "rule_id": self.rule_id,
+            "category": self.category.value,
+            "severity": self.severity.value,
+            "title": self.title,
+            "description": self.description,
+            "file_path": self.file_path,
+            "line_number": self.line_number,
+            "snippet": self.snippet,
+            "remediation": self.remediation,
+            "analyzer": self.analyzer,
+            "metadata": self.metadata,
+        }
+
+
+@dataclass
+class ScanResult:
+    """Results from scanning a single skill."""
+
+    skill_name: str
+    skill_directory: str
+    findings: list[Finding] = field(default_factory=list)
+    scan_duration_seconds: float = 0.0
+    analyzers_used: list[str] = field(default_factory=list)
+    timestamp: datetime = field(default_factory=datetime.now)
+
+    @property
+    def is_safe(self) -> bool:
+        """Check if skill passed all security checks."""
+        return not any(f.severity in (Severity.CRITICAL, Severity.HIGH) for f in self.findings)
+
+    @property
+    def max_severity(self) -> Severity:
+        """Get the highest severity level found."""
+        if not self.findings:
+            return Severity.SAFE
+
+        severity_order = [Severity.CRITICAL, Severity.HIGH, Severity.MEDIUM, Severity.LOW, Severity.INFO]
+        for severity in severity_order:
+            if any(f.severity == severity for f in self.findings):
+                return severity
+        return Severity.SAFE
+
+    def get_findings_by_severity(self, severity: Severity) -> list[Finding]:
+        """Get all findings of a specific severity."""
+        return [f for f in self.findings if f.severity == severity]
+
+    def get_findings_by_category(self, category: ThreatCategory) -> list[Finding]:
+        """Get all findings of a specific category."""
+        return [f for f in self.findings if f.category == category]
+
+    def to_dict(self) -> dict[str, Any]:
+        """Convert scan result to dictionary.
+
+        Output format is compatible with mcp-scanner-plugin's SkillResultParser.
+        See: https://github.com/cisco/mcp-scanner-plugin
+        """
+        return {
+            "skill_name": self.skill_name,
+            "skill_path": self.skill_directory,  # Plugin expects skill_path
+            "skill_directory": self.skill_directory,  # Keep for backward compatibility
+            "is_safe": self.is_safe,
+            "max_severity": self.max_severity.value,
+            "findings_count": len(self.findings),
+            "findings": [f.to_dict() for f in self.findings],
+            "scan_duration_seconds": self.scan_duration_seconds,
+            "duration_ms": int(self.scan_duration_seconds * 1000),  # Plugin expects duration_ms
+            "analyzers_used": self.analyzers_used,
+            "timestamp": self.timestamp.isoformat(),
+        }
+
+
+@dataclass
+class Report:
+    """Aggregated report from scanning one or more skills."""
+
+    scan_results: list[ScanResult] = field(default_factory=list)
+    total_skills_scanned: int = 0
+    total_findings: int = 0
+    critical_count: int = 0
+    high_count: int = 0
+    medium_count: int = 0
+    low_count: int = 0
+    info_count: int = 0
+    safe_count: int = 0
+    timestamp: datetime = field(default_factory=datetime.now)
+
+    def add_scan_result(self, result: ScanResult):
+        """Add a scan result and update counters."""
+        self.scan_results.append(result)
+        self.total_skills_scanned += 1
+        self.total_findings += len(result.findings)
+
+        for finding in result.findings:
+            if finding.severity == Severity.CRITICAL:
+                self.critical_count += 1
+            elif finding.severity == Severity.HIGH:
+                self.high_count += 1
+            elif finding.severity == Severity.MEDIUM:
+                self.medium_count += 1
+            elif finding.severity == Severity.LOW:
+                self.low_count += 1
+            elif finding.severity == Severity.INFO:
+                self.info_count += 1
+
+        if result.is_safe:
+            self.safe_count += 1
+
+    def to_dict(self) -> dict[str, Any]:
+        """Convert report to dictionary."""
+        return {
+            "summary": {
+                "total_skills_scanned": self.total_skills_scanned,
+                "total_findings": self.total_findings,
+                "safe_skills": self.safe_count,
+                "findings_by_severity": {
+                    "critical": self.critical_count,
+                    "high": self.high_count,
+                    "medium": self.medium_count,
+                    "low": self.low_count,
+                    "info": self.info_count,
+                },
+                "timestamp": self.timestamp.isoformat(),
+            },
+            "results": [result.to_dict() for result in self.scan_results],
+        }

skillanalyzer/core/reporters/__init__.py

@@ -0,0 +1,26 @@
+# Copyright 2026 Cisco Systems, Inc.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+# SPDX-License-Identifier: Apache-2.0
+
+"""
+Report generation modules for different output formats.
+"""
+
+from .json_reporter import JSONReporter
+from .markdown_reporter import MarkdownReporter
+from .sarif_reporter import SARIFReporter
+from .table_reporter import TableReporter
+
+__all__ = ["JSONReporter", "MarkdownReporter", "TableReporter", "SARIFReporter"]