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

skillanalyzer/data/yara_rules/tool_chaining_abuse.yara

@@ -0,0 +1,60 @@
+//////////////////////////////////////////
+// Tool Chaining Abuse Detection
+// Target: Suspicious multi-step operations that could exfiltrate data
+// For Claude Skills that chain operations suspiciously
+//////////////////////////////////////////
+
+rule tool_chaining_abuse{
+
+    meta:
+        author = "Cisco"
+        description = "Detects suspicious tool chaining patterns that could lead to data exfiltration"
+        classification = "harmful"
+        threat_type = "TOOL CHAINING ABUSE"
+
+    strings:
+
+        // Read → Send pattern
+        $read_then_send = /\b(read|fetch|get|retrieve|collect|gather)\b[^\n]{0,100}\b(send|post|upload|transmit|forward|email|slack|webhook)\b/i
+
+        // Collect → Exfiltrate pattern
+        $collect_exfiltrate = /\b(collect (all |every |entire )?(data|files?|info|credentials?|secrets?|keys?|tokens?))\b[^\n]{0,150}\b(send|post|upload|transmit|curl|wget|requests\.post)\b/i
+
+        // Multi-step with network
+        $multistep_network = /\b(first|then|next|after|finally),? (read|collect|gather)\b[^\n]{0,100}\b(then|next|after|finally),? (send|post|upload)\b/i
+
+        // Summarize and send externally
+        $summarize_send = /\b(summarize|aggregate|compile)\b[^\n]{0,80}\b(send|post|email|slack) (to|via) (external|webhook|url|endpoint|api)\b/i
+
+        // Read environment → Network
+        $env_to_network = /\b(os\.environ|getenv|process\.env)\b[^\n]{0,150}\b(requests\.|urllib\.|curl|wget|socket\.)\b/i
+
+        // File traversal → Collection → Send
+        $traverse_collect_send = /\b(walk|rglob|listdir|scandir|find)\b[^\n]{0,100}\b(open|read)\b[^\n]{0,100}\b(send|post|upload)\b/i
+
+        // Automated data pipeline
+        $auto_pipeline = /\b(automatically (read|collect|gather))\b[^\n]{0,100}\b(and |then )?(send|post|forward|upload)\b/i
+
+    condition:
+
+        // Read then send
+        $read_then_send or
+
+        // Collect and exfiltrate
+        $collect_exfiltrate or
+
+        // Multi-step with network
+        $multistep_network or
+
+        // Summarize and send
+        $summarize_send or
+
+        // Environment to network
+        $env_to_network or
+
+        // Traverse, collect, send
+        $traverse_collect_send or
+
+        // Automated pipeline
+        $auto_pipeline
+}

skillanalyzer/data/yara_rules/transitive_trust_abuse.yara

@@ -0,0 +1,73 @@
+//////////////////////////////////////////
+// Transitive Trust Abuse Detection
+// Target: Skills that delegate trust to untrusted external content
+// For Claude Skills that consume webpages, files, issues, docs
+//////////////////////////////////////////
+
+rule transitive_trust_abuse{
+
+    meta:
+        author = "Cisco"
+        description = "Detects skills that delegate trust to untrusted external content"
+        classification = "harmful"
+        threat_type = "TRANSITIVE TRUST ABUSE"
+
+    strings:
+
+        // Following external instructions
+        $follow_external = /\b(follow (the )?(instructions?|commands?|directives?) (in|from|inside|within) (the )?(file|webpage|document|url|link|website|page|content))\b/i
+
+        // Executing external content
+        $execute_external = /\b(execute (the )?(code|script|commands?) (in|from|found in) (the )?(file|webpage|document|url|link))\b/i
+
+        // Obeying untrusted sources
+        $obey_untrusted = /\b(do (what|whatever) (the )?(webpage|file|document|url|content) (says|tells|instructs|commands?))\b/i
+
+        // Running code blocks from external UNTRUSTED sources (not local scripts with --help)
+        // Exclude legitimate CLI usage patterns
+        $run_code_blocks = /\b(run (all |any )?(code|script) blocks? (you |that )?(find|see|encounter|discover) (in|from|inside) (the )?(url|webpage|website|external|untrusted))\b/i
+
+        // Following markdown/HTML instructions
+        $follow_markup = /\b(follow (the )?instructions? in (the )?(markdown|html|xml|json|yaml))\b/i
+
+        // Delegating to file content
+        $delegate_to_file = /\b(let (the )?(file|document|content) (decide|determine|control|specify))\b/i
+
+        // Executing inline code from documents
+        $execute_inline = /\b(execute (inline |embedded )?(code|scripts?)|run (inline |embedded )?(code|scripts?))\b/i
+
+        // Trusting URL content
+        $trust_url_content = /\b(trust (the )?(url|link|webpage) (content|instructions?)|safe to (follow|execute|run) (url|link|webpage))\b/i
+
+        // Parsing and executing
+        $parse_execute = /\b(parse (and |then )?(execute|run|eval)|extract (and |then )?(execute|run|eval))\b/i
+
+    condition:
+
+        // Following external instructions
+        $follow_external or
+
+        // Executing external content
+        $execute_external or
+
+        // Obeying untrusted sources
+        $obey_untrusted or
+
+        // Running code blocks
+        $run_code_blocks or
+
+        // Following markup instructions
+        $follow_markup or
+
+        // Delegating to file content
+        $delegate_to_file or
+
+        // Executing inline code
+        $execute_inline or
+
+        // Trusting URL content
+        $trust_url_content or
+
+        // Parse and execute
+        $parse_execute
+}

skillanalyzer/data/yara_rules/unicode_steganography.yara

@@ -0,0 +1,65 @@
+//////////////////////////////////////////
+// Unicode Steganography and Hidden Characters Detection
+// Target: Invisible Unicode used for prompt injection
+// Based on: https://en.wikipedia.org/wiki/Tags_(Unicode_block)
+//////////////////////////////////////////
+
+rule unicode_steganography{
+
+    meta:
+        author = "Cisco"
+        description = "Detects hidden Unicode characters used for invisible prompt injection and steganography"
+        classification = "harmful"
+        threat_type = "PROMPT INJECTION"
+        reference = "https://en.wikipedia.org/wiki/Tags_(Unicode_block)"
+
+    strings:
+
+        // --- 1. Unicode Tag Regex Patterns ---
+        // Catches \uE00xx, \u{E00xx}, and \U000E00xx encoding styles
+        $unicode_tag_pattern = /\\u(\{)?[Ee]00[0-7][0-9A-Fa-f](\})?/
+        $unicode_long_tag = /\\U000[Ee]00[0-7][0-9A-Fa-f]/
+
+        // --- 2. Zero-width characters (steganography) ---
+        // UTF-8 hex encoding
+        $zw_space = "\xE2\x80\x8B"  // U+200B ZERO WIDTH SPACE
+        $zw_non_joiner = "\xE2\x80\x8C"  // U+200C
+        $zw_joiner = "\xE2\x80\x8D"  // U+200D
+
+        // --- 3. Directional Overrides (text spoofing) ---
+        $rtlo = "\xE2\x80\xAE"  // U+202E RIGHT-TO-LEFT OVERRIDE
+        $ltro = "\xE2\x80\xAD"  // U+202D LEFT-TO-RIGHT OVERRIDE
+
+        // --- 4. Invisible separators ---
+        $line_separator = "\xE2\x80\xA8"  // U+2028 LINE SEPARATOR
+        $paragraph_separator = "\xE2\x80\xA9"  // U+2029 PARAGRAPH SEPARATOR
+
+        // --- 5. Homoglyph detection ---
+        $cyrillic_a = "\xD0\x90"  // А (Cyrillic A mimics Latin A)
+        $cyrillic_e = "\xD0\x95"  // Е (Cyrillic E mimics Latin E)
+        $cyrillic_o = "\xD0\x9E"  // О (Cyrillic O mimics Latin O)
+
+    condition:
+
+        // Detection logic - flag and manually review (better safe than miss attack)
+        (
+            // Encoded tag characters in strings (any occurrence is suspicious)
+            $unicode_tag_pattern or
+            $unicode_long_tag or
+
+            // Zero-width steganography (tools alternate chars to encode binary 0s/1s)
+            // Aggregate count across all types is more effective than individual checks
+            (#zw_space + #zw_non_joiner + #zw_joiner) > 10 or
+
+            // Any directional override (highly suspicious in code/English text)
+            $rtlo or
+            $ltro or
+
+            // Invisible separators (no legitimate use in source code)
+            $line_separator or
+            $paragraph_separator or
+
+            // Homoglyph attacks (5+ Cyrillic chars mimicking Latin in English context)
+            (#cyrillic_a + #cyrillic_e + #cyrillic_o) > 5
+        )
+}

skillanalyzer/hooks/__init__.py

@@ -0,0 +1,21 @@
+# 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
+
+"""Git hooks for skill-analyzer."""
+
+from .pre_commit import main as pre_commit_hook
+
+__all__ = ["pre_commit_hook"]

skillanalyzer/hooks/pre_commit.py

@@ -0,0 +1,450 @@
+#!/usr/bin/env python3
+# 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
+
+"""
+Pre-commit hook for scanning Claude Skills for security issues.
+
+This hook scans staged skill directories for security vulnerabilities
+and blocks commits that contain HIGH or CRITICAL severity findings.
+
+Usage:
+    1. Install as a pre-commit hook:
+       skill-analyzer-pre-commit install
+
+    2. Or add to .pre-commit-config.yaml:
+       - repo: local
+         hooks:
+           - id: skill-analyzer
+             name: Skill Analyzer
+             entry: skill-analyzer-pre-commit
+             language: python
+             types: [file]
+             pass_filenames: false
+
+Configuration:
+    Create a .skillanalyzerrc file in your repo root:
+
+    {
+        "severity_threshold": "high",  # block on: critical, high, medium, low
+        "skills_path": ".claude/skills",
+        "fail_fast": true
+    }
+"""
+
+import argparse
+import json
+import subprocess
+import sys
+from pathlib import Path
+
+# Default configuration
+DEFAULT_CONFIG = {
+    "severity_threshold": "high",  # Block commits on HIGH or CRITICAL
+    "skills_path": ".claude/skills",  # Default Claude skills location
+    "fail_fast": True,
+    "use_behavioral": False,
+    "use_trigger": True,
+}
+
+# Severity levels (higher number = more severe)
+SEVERITY_LEVELS = {
+    "safe": 0,
+    "info": 1,
+    "low": 2,
+    "medium": 3,
+    "high": 4,
+    "critical": 5,
+}
+
+
+def load_config(repo_root: Path) -> dict:
+    """
+    Load configuration from .skillanalyzerrc file.
+
+    Args:
+        repo_root: Repository root directory
+
+    Returns:
+        Configuration dictionary
+    """
+    config = DEFAULT_CONFIG.copy()
+
+    config_paths = [
+        repo_root / ".skillanalyzerrc",
+        repo_root / ".skillanalyzerrc.json",
+        repo_root / "skillanalyzer.json",
+    ]
+
+    for config_path in config_paths:
+        if config_path.exists():
+            try:
+                with open(config_path) as f:
+                    user_config = json.load(f)
+                    config.update(user_config)
+                    break
+            except (OSError, json.JSONDecodeError) as e:
+                print(f"Warning: Failed to load config from {config_path}: {e}", file=sys.stderr)
+
+    return config
+
+
+def get_staged_files() -> list[str]:
+    """
+    Get list of staged files from git.
+
+    Returns:
+        List of staged file paths relative to repo root
+    """
+    try:
+        result = subprocess.run(
+            ["git", "diff", "--cached", "--name-only", "--diff-filter=ACMR"],
+            capture_output=True,
+            text=True,
+            check=True,
+        )
+        return [f.strip() for f in result.stdout.split("\n") if f.strip()]
+    except subprocess.CalledProcessError:
+        return []
+
+
+def get_affected_skills(staged_files: list[str], skills_path: str) -> set[Path]:
+    """
+    Identify skill directories affected by staged changes.
+
+    Args:
+        staged_files: List of staged file paths
+        skills_path: Base path for skills
+
+    Returns:
+        Set of affected skill directory paths
+    """
+    affected_skills = set()
+    skills_prefix = skills_path.rstrip("/") + "/"
+
+    for file_path in staged_files:
+        # Check if file is in skills directory
+        if file_path.startswith(skills_prefix) or file_path.startswith(skills_path):
+            # Extract the skill directory (first subdirectory under skills_path)
+            relative = file_path[len(skills_path) :].lstrip("/")
+            parts = relative.split("/")
+
+            if parts:
+                skill_dir = Path(skills_path) / parts[0]
+                skill_md = skill_dir / "SKILL.md"
+                if skill_md.exists():
+                    affected_skills.add(skill_dir)
+
+        # Also check for SKILL.md directly in case skills are at different paths
+        if file_path.endswith("SKILL.md"):
+            skill_dir = Path(file_path).parent
+            affected_skills.add(skill_dir)
+
+    return affected_skills
+
+
+def scan_skill(skill_dir: Path, config: dict) -> dict:
+    """
+    Scan a skill directory and return findings.
+
+    Args:
+        skill_dir: Path to skill directory
+        config: Configuration dictionary
+
+    Returns:
+        Scan results as dictionary
+    """
+    try:
+        from ..core.analyzers.base import BaseAnalyzer
+        from ..core.analyzers.static import StaticAnalyzer
+        from ..core.scanner import SkillScanner
+
+        analyzers: list[BaseAnalyzer] = [StaticAnalyzer()]
+
+        # Add optional analyzers based on config
+        if config.get("use_behavioral"):
+            try:
+                from ..core.analyzers.behavioral_analyzer import BehavioralAnalyzer
+
+                analyzers.append(BehavioralAnalyzer(use_static_analysis=True))
+            except ImportError:
+                pass
+
+        if config.get("use_trigger"):
+            try:
+                from ..core.analyzers.trigger_analyzer import TriggerAnalyzer
+
+                analyzers.append(TriggerAnalyzer())
+            except ImportError:
+                pass
+
+        scanner = SkillScanner(analyzers=analyzers)
+        result = scanner.scan_skill(skill_dir)
+
+        # Count findings by severity
+        counts = {"critical": 0, "high": 0, "medium": 0, "low": 0}
+        for f in result.findings:
+            sev = f.severity.value.lower() if hasattr(f.severity, "value") else str(f.severity).lower()
+            if sev in counts:
+                counts[sev] += 1
+
+        return {
+            "skill_name": result.skill_name,
+            "skill_directory": result.skill_directory,
+            "findings": [
+                {
+                    "rule_id": f.rule_id,
+                    "severity": f.severity.value if hasattr(f.severity, "value") else str(f.severity),
+                    "title": f.title,
+                    "description": f.description,
+                    "file_path": f.file_path,
+                    "line_number": f.line_number,
+                }
+                for f in result.findings
+            ],
+            "critical_count": counts["critical"],
+            "high_count": counts["high"],
+            "medium_count": counts["medium"],
+            "low_count": counts["low"],
+        }
+
+    except Exception as e:
+        return {
+            "skill_name": skill_dir.name,
+            "skill_directory": str(skill_dir),
+            "findings": [],
+            "error": str(e),
+        }
+
+
+def check_severity_threshold(result: dict, threshold: str) -> bool:
+    """
+    Check if scan result exceeds severity threshold.
+
+    Args:
+        result: Scan result dictionary
+        threshold: Severity threshold string
+
+    Returns:
+        True if threshold is exceeded (should block commit)
+    """
+    threshold_level = SEVERITY_LEVELS.get(threshold.lower(), SEVERITY_LEVELS["high"])
+
+    for finding in result.get("findings", []):
+        finding_level = SEVERITY_LEVELS.get(finding["severity"].lower(), 0)
+        if finding_level >= threshold_level:
+            return True
+
+    return False
+
+
+def format_finding(finding: dict) -> str:
+    """Format a finding for console output."""
+    severity = finding["severity"].upper()
+    title = finding["title"]
+    location = finding.get("file_path", "")
+
+    if finding.get("line_number"):
+        location = f"{location}:{finding['line_number']}"
+
+    return f"  [{severity}] {title}\n    Location: {location}"
+
+
+def main(args: list[str] | None = None) -> int:
+    """
+    Main entry point for pre-commit hook.
+
+    Args:
+        args: Command line arguments (for testing)
+
+    Returns:
+        Exit code (0 = success, 1 = blocked)
+    """
+    parser = argparse.ArgumentParser(description="Pre-commit hook for scanning Claude Skills")
+    parser.add_argument(
+        "--severity",
+        choices=["critical", "high", "medium", "low"],
+        help="Override severity threshold from config",
+    )
+    parser.add_argument(
+        "--skills-path",
+        help="Override skills path from config",
+    )
+    parser.add_argument(
+        "--all",
+        action="store_true",
+        help="Scan all skills, not just staged ones",
+    )
+    parser.add_argument(
+        "install",
+        nargs="?",
+        help="Install pre-commit hook",
+    )
+
+    parsed_args = parser.parse_args(args)
+
+    # Handle install command
+    if parsed_args.install == "install":
+        return install_hook()
+
+    # Find repo root
+    try:
+        result = subprocess.run(
+            ["git", "rev-parse", "--show-toplevel"],
+            capture_output=True,
+            text=True,
+            check=True,
+        )
+        repo_root = Path(result.stdout.strip())
+    except subprocess.CalledProcessError:
+        print("Error: Not a git repository", file=sys.stderr)
+        return 1
+
+    # Load config
+    config = load_config(repo_root)
+
+    # Apply command line overrides
+    if parsed_args.severity:
+        config["severity_threshold"] = parsed_args.severity
+    if parsed_args.skills_path:
+        config["skills_path"] = parsed_args.skills_path
+
+    # Get staged files and affected skills
+    if parsed_args.all:
+        skills_dir = repo_root / config["skills_path"]
+        if skills_dir.exists():
+            affected_skills = {d for d in skills_dir.iterdir() if d.is_dir() and (d / "SKILL.md").exists()}
+        else:
+            affected_skills = set()
+    else:
+        staged_files = get_staged_files()
+        affected_skills = get_affected_skills(staged_files, config["skills_path"])
+
+    if not affected_skills:
+        # No skills affected, allow commit
+        return 0
+
+    print(f"Scanning {len(affected_skills)} skill(s)...")
+
+    # Scan each affected skill
+    blocked = False
+    all_findings = []
+
+    for skill_dir in sorted(affected_skills):
+        print(f"\n📦 {skill_dir.name}")
+
+        result = scan_skill(skill_dir, config)
+
+        if result.get("error"):
+            print(f"  ⚠️  Error: {result['error']}", file=sys.stderr)
+            continue
+
+        findings = result.get("findings", [])
+
+        if not findings:
+            print("  ✅ No issues found")
+            continue
+
+        # Check if threshold is exceeded
+        if check_severity_threshold(result, config["severity_threshold"]):
+            blocked = True
+            print(f"  🚫 Blocked (threshold: {config['severity_threshold'].upper()})")
+        else:
+            print(f"  ⚠️  {len(findings)} finding(s) below threshold")
+
+        # Print findings
+        for finding in findings:
+            print(format_finding(finding))
+            all_findings.append(finding)
+
+        if blocked and config.get("fail_fast"):
+            break
+
+    # Summary
+    print(f"\n{'=' * 50}")
+    if blocked:
+        print("❌ Commit BLOCKED - fix security issues before committing")
+        print(f"   Threshold: {config['severity_threshold'].upper()} and above")
+        return 1
+    elif all_findings:
+        print(f"⚠️  {len(all_findings)} finding(s) detected (below threshold)")
+        print("   Consider reviewing and fixing these issues")
+        return 0
+    else:
+        print("✅ All skills passed security checks")
+        return 0
+
+
+def install_hook() -> int:
+    """
+    Install the pre-commit hook in the current repository.
+
+    Returns:
+        Exit code
+    """
+    try:
+        result = subprocess.run(
+            ["git", "rev-parse", "--show-toplevel"],
+            capture_output=True,
+            text=True,
+            check=True,
+        )
+        repo_root = Path(result.stdout.strip())
+    except subprocess.CalledProcessError:
+        print("Error: Not a git repository", file=sys.stderr)
+        return 1
+
+    hooks_dir = repo_root / ".git" / "hooks"
+    hooks_dir.mkdir(exist_ok=True)
+
+    hook_path = hooks_dir / "pre-commit"
+
+    hook_script = """#!/bin/sh
+# Skill Analyzer Pre-commit Hook
+# Automatically scans Claude Skills for security issues
+
+skill-analyzer-pre-commit "$@"
+exit_code=$?
+
+if [ $exit_code -ne 0 ]; then
+    echo ""
+    echo "To bypass this check (not recommended), use: git commit --no-verify"
+fi
+
+exit $exit_code
+"""
+
+    # Check if hook already exists
+    if hook_path.exists():
+        print(f"Warning: Pre-commit hook already exists at {hook_path}")
+        response = input("Overwrite? [y/N] ").strip().lower()
+        if response != "y":
+            print("Aborted")
+            return 1
+
+    hook_path.write_text(hook_script)
+    hook_path.chmod(0o755)
+
+    print(f"✅ Pre-commit hook installed at {hook_path}")
+    print("\nConfiguration:")
+    print("  Create .skillanalyzerrc in your repo root to customize behavior:")
+    print('  { "severity_threshold": "high", "skills_path": ".claude/skills" }')
+
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

skillanalyzer/threats/__init__.py

@@ -0,0 +1,25 @@
+# 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
+
+"""
+Threat mapping and taxonomy for Claude Skill Analyzer.
+
+Aligned with MCP Scanner's threat taxonomy.
+"""
+
+from .threats import LLM_THREAT_MAPPING, YARA_THREAT_MAPPING, ThreatMapping
+
+__all__ = ["ThreatMapping", "LLM_THREAT_MAPPING", "YARA_THREAT_MAPPING"]