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

skillanalyzer/core/static_analysis/interprocedural/__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
+
+"""Interprocedural analysis for cross-file function tracking."""
+
+from .call_graph_analyzer import CallGraph, CallGraphAnalyzer
+
+__all__ = ["CallGraph", "CallGraphAnalyzer"]

skillanalyzer/core/static_analysis/interprocedural/call_graph_analyzer.py

@@ -0,0 +1,406 @@
+# 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
+
+"""Cross-file analysis for Claude Skills.
+
+Tracks how function parameters flow through function calls across multiple files.
+This enables detection of data exfiltration patterns that span multiple scripts.
+"""
+
+import ast
+import logging
+from pathlib import Path
+from typing import Any
+
+
+class CallGraph:
+    """Call graph for cross-file analysis.
+
+    Tracks function definitions and call relationships across multiple files.
+    """
+
+    def __init__(self) -> None:
+        """Initialize call graph."""
+        self.functions: dict[str, Any] = {}  # full_name -> function node
+        self.calls: list[tuple] = []  # (caller, callee) pairs
+        self.entry_points: set[str] = set()  # Skill entry point functions
+
+    def add_function(self, name: str, node: Any, file_path: Path, is_entry_point: bool = False) -> None:
+        """Add a function definition.
+
+        Args:
+            name: Function name
+            node: Function definition node
+            file_path: File containing the function
+            is_entry_point: Whether this is a skill entry point
+        """
+        full_name = f"{file_path}::{name}"
+        self.functions[full_name] = node
+        if is_entry_point:
+            self.entry_points.add(full_name)
+
+    def add_call(self, caller: str, callee: str) -> None:
+        """Add a function call edge.
+
+        Args:
+            caller: Caller function name
+            callee: Callee function name
+        """
+        self.calls.append((caller, callee))
+
+    def get_callees(self, func_name: str) -> list[str]:
+        """Get functions called by a function.
+
+        Args:
+            func_name: Function name
+
+        Returns:
+            List of callee function names
+        """
+        return [callee for caller, callee in self.calls if caller == func_name]
+
+    def get_entry_points(self) -> set[str]:
+        """Get all entry point functions.
+
+        Returns:
+            Set of entry point function names
+        """
+        return self.entry_points.copy()
+
+
+class CallGraphAnalyzer:
+    """Performs cross-file analysis for Claude Skills.
+
+    Tracks parameter flow from skill entry points through
+    the entire codebase across multiple files.
+    """
+
+    def __init__(self) -> None:
+        """Initialize cross-file analyzer."""
+        self.call_graph = CallGraph()
+        self.analyzers: dict[Path, ast.Module] = {}  # file -> AST
+        self.import_map: dict[Path, list[Path]] = {}  # file -> imported files
+        self.logger = logging.getLogger(__name__)
+
+    def add_file(self, file_path: Path, source_code: str) -> None:
+        """Add a file to the analysis.
+
+        Args:
+            file_path: Path to the file
+            source_code: Source code content
+        """
+        try:
+            tree = ast.parse(source_code)
+            self.analyzers[file_path] = tree
+
+            # Extract function definitions
+            self._extract_functions(file_path, tree)
+
+            # Extract imports
+            self._extract_imports(file_path, tree)
+        except SyntaxError as e:
+            self.logger.debug(f"Skipping unparseable file {file_path}: {e}")
+
+    def _extract_functions(self, file_path: Path, tree: ast.Module) -> None:
+        """Extract function definitions from Python file.
+
+        Args:
+            file_path: File path
+            tree: AST tree
+        """
+        # Extract top-level functions
+        for node in tree.body:
+            if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)):
+                # Check if it looks like an entry point (has main-like name or is decorated)
+                is_entry = self._is_entry_point(node)
+                self.call_graph.add_function(node.name, node, file_path, is_entry)
+
+        # Extract class methods
+        for node in tree.body:
+            if isinstance(node, ast.ClassDef):
+                class_name = node.name
+                for item in node.body:
+                    if isinstance(item, (ast.FunctionDef, ast.AsyncFunctionDef)):
+                        method_full_name = f"{class_name}.{item.name}"
+                        self.call_graph.add_function(method_full_name, item, file_path, False)
+
+    def _is_entry_point(self, func_def: ast.FunctionDef) -> bool:
+        """Check if function is a skill entry point.
+
+        Entry points are identified by:
+        - Function name starts with main, run, or execute
+        - Function has decorators (common pattern for skills)
+
+        Args:
+            func_def: Function definition node
+
+        Returns:
+            True if entry point
+        """
+        # Check function name patterns
+        name_lower = func_def.name.lower()
+        if name_lower in ["main", "run", "execute", "process", "handle"]:
+            return True
+        if name_lower.startswith(("main_", "run_", "execute_", "process_", "handle_")):
+            return True
+
+        # Check for decorators (often indicate entry points)
+        if func_def.decorator_list:
+            return True
+
+        return False
+
+    def _extract_imports(self, file_path: Path, tree: ast.Module) -> None:
+        """Extract import relationships.
+
+        Args:
+            file_path: File path
+            tree: AST tree
+        """
+        imported_files = []
+
+        for node in ast.walk(tree):
+            if isinstance(node, ast.Import):
+                for alias in node.names:
+                    module_name = alias.name
+                    imported_file = self._resolve_import(file_path, module_name)
+                    if imported_file:
+                        imported_files.append(imported_file)
+            elif isinstance(node, ast.ImportFrom):
+                if node.module:
+                    imported_file = self._resolve_import(file_path, node.module)
+                    if imported_file:
+                        imported_files.append(imported_file)
+
+        self.import_map[file_path] = imported_files
+
+    def _resolve_import(self, from_file: Path, module_name: str) -> Path | None:
+        """Resolve Python import to file path.
+
+        Args:
+            from_file: File doing the import
+            module_name: Module name
+
+        Returns:
+            Resolved file path or None
+        """
+        module_parts = module_name.split(".")
+        current_dir = from_file.parent
+
+        # Try relative to current file
+        for i in range(len(module_parts), 0, -1):
+            potential_path = current_dir / "/".join(module_parts[:i])
+
+            # Try as file
+            py_file = potential_path.with_suffix(".py")
+            if py_file.exists():
+                return py_file
+
+            # Try as package
+            init_file = potential_path / "__init__.py"
+            if init_file.exists():
+                return init_file
+
+        return None
+
+    def build_call_graph(self) -> CallGraph:
+        """Build the complete call graph.
+
+        Returns:
+            Call graph
+        """
+        # Extract function calls from each file
+        for file_path, tree in self.analyzers.items():
+            self._extract_calls(file_path, tree)
+
+        return self.call_graph
+
+    def _extract_calls(self, file_path: Path, tree: ast.Module) -> None:
+        """Extract function calls from Python file.
+
+        Args:
+            file_path: File path
+            tree: AST tree
+        """
+        # Extract calls from top-level functions
+        for node in tree.body:
+            if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)):
+                caller_name = f"{file_path}::{node.name}"
+                self._extract_calls_from_function(file_path, node, caller_name)
+
+        # Extract calls from class methods
+        for node in tree.body:
+            if isinstance(node, ast.ClassDef):
+                class_name = node.name
+                for item in node.body:
+                    if isinstance(item, (ast.FunctionDef, ast.AsyncFunctionDef)):
+                        caller_name = f"{file_path}::{class_name}.{item.name}"
+                        self._extract_calls_from_function(file_path, item, caller_name)
+
+    def _extract_calls_from_function(self, file_path: Path, func_node: ast.FunctionDef, caller_name: str) -> None:
+        """Extract calls from a single function.
+
+        Args:
+            file_path: File path
+            func_node: Function AST node
+            caller_name: Full caller name
+        """
+        for node in ast.walk(func_node):
+            if isinstance(node, ast.Call):
+                callee_name = self._get_call_name(node)
+
+                # Try to resolve to full name
+                full_callee = self._resolve_call_target(file_path, callee_name)
+
+                if full_callee:
+                    self.call_graph.add_call(caller_name, full_callee)
+                else:
+                    # Add with partial name
+                    self.call_graph.add_call(caller_name, callee_name)
+
+    def _get_call_name(self, node: ast.Call) -> str:
+        """Get function call name.
+
+        Args:
+            node: Call node
+
+        Returns:
+            Function name
+        """
+        if isinstance(node.func, ast.Name):
+            return node.func.id
+        elif isinstance(node.func, ast.Attribute):
+            parts = []
+            current = node.func
+            while isinstance(current, ast.Attribute):
+                parts.append(current.attr)
+                current = current.value
+            if isinstance(current, ast.Name):
+                parts.append(current.id)
+            return ".".join(reversed(parts))
+        try:
+            return ast.unparse(node.func)
+        except (AttributeError, TypeError, ValueError):
+            return "<unknown>"
+
+    def _resolve_call_target(self, file_path: Path, call_name: str) -> str | None:
+        """Resolve a function call to its full qualified name.
+
+        Args:
+            file_path: File where call occurs
+            call_name: Function call name
+
+        Returns:
+            Full qualified name or None
+        """
+        # Check if it's defined in the same file
+        for func_name in self.call_graph.functions.keys():
+            if func_name.endswith(f"::{call_name}"):
+                if func_name.startswith(str(file_path)):
+                    return func_name
+
+        # Check imported files
+        if file_path in self.import_map:
+            for imported_file in self.import_map[file_path]:
+                potential_name = f"{imported_file}::{call_name}"
+                if potential_name in self.call_graph.functions:
+                    return potential_name
+
+        return None
+
+    def get_reachable_functions(self, start_func: str) -> list[str]:
+        """Get all functions reachable from a starting function.
+
+        Args:
+            start_func: Starting function
+
+        Returns:
+            List of reachable function names
+        """
+        reachable = set()
+        to_visit = [start_func]
+        visited = set()
+
+        while to_visit:
+            current = to_visit.pop()
+            if current in visited:
+                continue
+
+            visited.add(current)
+            reachable.add(current)
+
+            # Add all callees
+            callees = self.call_graph.get_callees(current)
+            for callee in callees:
+                if callee not in visited:
+                    to_visit.append(callee)
+
+        return list(reachable)
+
+    def analyze_parameter_flow_across_files(self, entry_point: str, param_names: list[str]) -> dict[str, Any]:
+        """Analyze how parameters flow across files from an entry point.
+
+        Args:
+            entry_point: Entry point function name
+            param_names: Parameter names to track
+
+        Returns:
+            Dictionary with cross-file flow information
+        """
+        # Get all reachable functions
+        reachable = self.get_reachable_functions(entry_point)
+
+        # Track parameter-influenced functions
+        param_influenced_funcs = set()
+        cross_file_flows = []
+
+        for func_name in reachable:
+            if func_name == entry_point:
+                continue
+
+            # Check if this function is called from entry point or influenced functions
+            for caller, callee in self.call_graph.calls:
+                if callee == func_name and (caller == entry_point or caller in param_influenced_funcs):
+                    param_influenced_funcs.add(func_name)
+
+                    # Extract file information
+                    caller_file = caller.split("::")[0] if "::" in caller else "unknown"
+                    callee_file = callee.split("::")[0] if "::" in callee else "unknown"
+
+                    if caller_file != callee_file:
+                        cross_file_flows.append(
+                            {
+                                "from_function": caller,
+                                "to_function": callee,
+                                "from_file": caller_file,
+                                "to_file": callee_file,
+                            }
+                        )
+
+        return {
+            "reachable_functions": reachable,
+            "param_influenced_functions": list(param_influenced_funcs),
+            "cross_file_flows": cross_file_flows,
+            "total_files_involved": len(set(f.split("::")[0] for f in reachable if "::" in f)),
+        }
+
+    def get_all_files(self) -> list[Path]:
+        """Get all files in the analysis.
+
+        Returns:
+            List of file paths
+        """
+        return list(self.analyzers.keys())

skillanalyzer/core/static_analysis/interprocedural/cross_file_analyzer.py

@@ -0,0 +1,190 @@
+# 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
+
+"""
+Cross-file correlation analyzer for detecting multi-step attacks.
+
+Tracks how data flows across multiple Python files in a skill package.
+"""
+
+from dataclasses import dataclass, field
+from typing import Any
+
+from ..context_extractor import SkillScriptContext
+
+
+@dataclass
+class CrossFileCorrelation:
+    """Represents a correlated threat across multiple files."""
+
+    threat_type: str  # "exfiltration_chain", "collection_pipeline"
+    severity: str
+    files_involved: list[str] = field(default_factory=list)
+    evidence: dict[str, Any] = field(default_factory=dict)
+    description: str = ""
+
+
+class CrossFileAnalyzer:
+    """
+    Analyzes correlations across multiple files in a skill package.
+
+    Detects multi-step attacks like:
+    1. File A: Collects credentials/env vars
+    2. File B: Encodes data
+    3. File C: Sends to network
+    """
+
+    def __init__(self):
+        self.file_contexts: dict[str, SkillScriptContext] = {}
+        self.correlations: list[CrossFileCorrelation] = []
+
+    def add_file_context(self, file_name: str, context: SkillScriptContext):
+        """Add a file's context for correlation analysis."""
+        self.file_contexts[file_name] = context
+
+    def analyze_correlations(self) -> list[CrossFileCorrelation]:
+        """
+        Analyze all files together to find multi-step attack patterns.
+
+        Returns:
+            List of detected cross-file correlations
+        """
+        self.correlations = []
+
+        # Pattern 1: Collection → Encoding → Exfiltration chain
+        self._detect_exfiltration_chain()
+
+        # Pattern 2: Credential access in one file + Network in another
+        self._detect_credential_network_separation()
+
+        # Pattern 3: Environment harvesting + Network transmission
+        self._detect_env_var_exfiltration_chain()
+
+        return self.correlations
+
+    def _detect_exfiltration_chain(self):
+        """
+        Detect Collection → Encoding → Network chain across files.
+
+        Pattern:
+        - File A: has_env_var_access or has_credential_access
+        - File B: has encoding (base64, json)
+        - File C: has_network
+        """
+        has_collection = []
+        has_encoding = []
+        has_network = []
+
+        for file_name, context in self.file_contexts.items():
+            if context.has_env_var_access or context.has_credential_access:
+                has_collection.append(file_name)
+
+            # Check for encoding operations
+            if any("base64" in call or "encode" in call for call in context.all_function_calls):
+                has_encoding.append(file_name)
+
+            if context.has_network:
+                has_network.append(file_name)
+
+        # If we have all three stages across different files
+        if has_collection and has_network and len(self.file_contexts) > 1:
+            correlation = CrossFileCorrelation(
+                threat_type="exfiltration_chain",
+                severity="CRITICAL",
+                files_involved=list(set(has_collection + has_encoding + has_network)),
+                evidence={
+                    "collection_files": has_collection,
+                    "encoding_files": has_encoding,
+                    "network_files": has_network,
+                },
+                description=f"Multi-file exfiltration chain detected: {', '.join(has_collection)} collect data → {', '.join(has_encoding) if has_encoding else 'encode'} → {', '.join(has_network)} transmit to network",
+            )
+            self.correlations.append(correlation)
+
+    def _detect_credential_network_separation(self):
+        """
+        Detect credential access separated from network calls.
+
+        This is a common evasion technique: put credential access in one file
+        and network transmission in another to avoid simple pattern detection.
+        """
+        credential_files = []
+        network_files = []
+
+        for file_name, context in self.file_contexts.items():
+            if context.has_credential_access:
+                credential_files.append(file_name)
+            if context.has_network:
+                network_files.append(file_name)
+
+        # If credentials and network are in DIFFERENT files
+        if credential_files and network_files and not set(credential_files) & set(network_files):
+            correlation = CrossFileCorrelation(
+                threat_type="credential_network_separation",
+                severity="HIGH",
+                files_involved=credential_files + network_files,
+                evidence={
+                    "credential_files": credential_files,
+                    "network_files": network_files,
+                },
+                description=f"Credential access ({', '.join(credential_files)}) separated from network transmission ({', '.join(network_files)}) - possible evasion technique",
+            )
+            self.correlations.append(correlation)
+
+    def _detect_env_var_exfiltration_chain(self):
+        """
+        Detect environment variable harvesting + network transmission across files.
+
+        Pattern:
+        - File A: Iterates os.environ collecting secrets
+        - File B: Has network calls
+        - Together: Likely exfiltrating environment variables
+        """
+        env_var_files = []
+        network_files = []
+
+        for file_name, context in self.file_contexts.items():
+            if context.has_env_var_access:
+                env_var_files.append(file_name)
+            if context.has_network:
+                network_files.append(file_name)
+
+        # If env vars and network exist (even in same or different files)
+        if env_var_files and network_files:
+            # Check if they're in different files (more sophisticated)
+            if not set(env_var_files) & set(network_files):
+                severity = "CRITICAL"
+                desc = f"Environment variable harvesting ({', '.join(env_var_files)}) separated from network transmission ({', '.join(network_files)}) across files"
+            else:
+                # Same file - less sophisticated but still dangerous
+                severity = "CRITICAL"
+                desc = f"Environment variable access with network calls in {', '.join(env_var_files)}"
+
+            correlation = CrossFileCorrelation(
+                threat_type="env_var_exfiltration",
+                severity=severity,
+                files_involved=list(set(env_var_files + network_files)),
+                evidence={
+                    "env_var_files": env_var_files,
+                    "network_files": network_files,
+                },
+                description=desc,
+            )
+            self.correlations.append(correlation)
+
+    def get_critical_correlations(self) -> list[CrossFileCorrelation]:
+        """Get only CRITICAL severity correlations."""
+        return [c for c in self.correlations if c.severity == "CRITICAL"]

skillanalyzer/core/static_analysis/parser/__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
+
+"""Python AST parsers for static analysis."""
+
+from .python_parser import FunctionInfo, PythonParser
+
+__all__ = ["PythonParser", "FunctionInfo"]