isnad-scan 0.3.0__py3-none-any.whl

isnad_scan/__init__.py

@@ -0,0 +1,2 @@
+"""ISNAD Skill Scanner - Security scanner for AI agent skills."""
+__version__ = "0.3.0"

isnad_scan/ast_analyzer.py

@@ -0,0 +1,374 @@
+"""AST-based analysis for Python files.
+
+Catches evasion techniques that regex cannot:
+- Import aliasing (from os import system as s)
+- Nested/chained attribute access
+- Dynamic function construction
+- Control flow to dangerous calls
+"""
+import ast
+from dataclasses import dataclass
+from pathlib import Path
+from typing import List, Set, Dict, Optional, Tuple
+
+from .patterns import Finding, Severity
+
+
+# Dangerous functions we track through the AST
+DANGEROUS_FUNCTIONS = {
+    'eval', 'exec', 'compile', '__import__',
+    'getattr', 'setattr', 'delattr',
+    'open',  # Track for path traversal
+}
+
+DANGEROUS_CALLABLES = {
+    # builtins
+    ('builtins', 'eval'), ('builtins', 'exec'), ('builtins', 'compile'),
+    ('builtins', '__import__'), ('builtins', 'open'),
+    # os module
+    ('os', 'system'), ('os', 'popen'), ('os', 'spawn'),
+    ('os', 'spawnl'), ('os', 'spawnle'), ('os', 'spawnlp'), ('os', 'spawnlpe'),
+    ('os', 'spawnv'), ('os', 'spawnve'), ('os', 'spawnvp'), ('os', 'spawnvpe'),
+    ('os', 'execl'), ('os', 'execle'), ('os', 'execlp'), ('os', 'execlpe'),
+    ('os', 'execv'), ('os', 'execve'), ('os', 'execvp'), ('os', 'execvpe'),
+    ('os', 'remove'), ('os', 'unlink'), ('os', 'rmdir'),
+    # subprocess
+    ('subprocess', 'run'), ('subprocess', 'call'), ('subprocess', 'Popen'),
+    ('subprocess', 'check_call'), ('subprocess', 'check_output'),
+    # pickle
+    ('pickle', 'load'), ('pickle', 'loads'),
+    ('_pickle', 'load'), ('_pickle', 'loads'),
+    # marshal
+    ('marshal', 'load'), ('marshal', 'loads'),
+    # socket
+    ('socket', 'socket'), ('socket', 'create_connection'),
+    # requests
+    ('requests', 'get'), ('requests', 'post'), ('requests', 'put'),
+    ('requests', 'delete'), ('requests', 'patch'),
+    # urllib
+    ('urllib.request', 'urlopen'), ('urllib.request', 'urlretrieve'),
+}
+
+# Modules that when imported suggest suspicious activity
+SUSPICIOUS_MODULES = {
+    'ctypes',  # Memory manipulation
+    'mmap',    # Memory mapping
+    'pty',     # Pseudo-terminal (reverse shells)
+    'fcntl',   # File control
+    'resource', # Resource limits manipulation
+}
+
+
+@dataclass
+class ImportedName:
+    """Tracks an imported name and its origin."""
+    name: str           # Local name (e.g., 's')
+    module: str         # Source module (e.g., 'os')
+    original: str       # Original name (e.g., 'system')
+    line: int
+    
+    @property
+    def qualified(self) -> Tuple[str, str]:
+        return (self.module, self.original)
+
+
+class DangerousCallVisitor(ast.NodeVisitor):
+    """AST visitor that tracks imports and finds dangerous calls."""
+    
+    def __init__(self, filename: str):
+        self.filename = filename
+        self.findings: List[Finding] = []
+        
+        # Track imported names: local_name -> ImportedName
+        self.imports: Dict[str, ImportedName] = {}
+        
+        # Track module aliases: alias -> module_name
+        self.module_aliases: Dict[str, str] = {}
+        
+        # Track variable assignments that might hold dangerous refs
+        self.dangerous_vars: Dict[str, Tuple[str, int]] = {}  # name -> (reason, line)
+    
+    def visit_Import(self, node: ast.Import):
+        """Handle: import os, import subprocess as sp"""
+        for alias in node.names:
+            module = alias.name
+            local_name = alias.asname or alias.name
+            
+            self.module_aliases[local_name] = module
+            
+            # Check for suspicious module imports
+            base_module = module.split('.')[0]
+            if base_module in SUSPICIOUS_MODULES:
+                self.findings.append(Finding(
+                    severity=Severity.WARN,
+                    pattern_id='suspicious_module_import',
+                    description=f'Import of suspicious module: {module}',
+                    file=self.filename,
+                    line=node.lineno,
+                    match=f'import {module}',
+                    context=f'import {module}' + (f' as {alias.asname}' if alias.asname else ''),
+                ))
+        
+        self.generic_visit(node)
+    
+    def visit_ImportFrom(self, node: ast.ImportFrom):
+        """Handle: from os import system, from os import system as s"""
+        module = node.module or ''
+        
+        for alias in node.names:
+            original_name = alias.name
+            local_name = alias.asname or alias.name
+            
+            # Track the import
+            self.imports[local_name] = ImportedName(
+                name=local_name,
+                module=module,
+                original=original_name,
+                line=node.lineno,
+            )
+            
+            # Check if importing something dangerous
+            if (module, original_name) in DANGEROUS_CALLABLES:
+                severity = Severity.DANGER if original_name in ('system', 'popen', 'eval', 'exec') else Severity.WARN
+                
+                # If aliased, it's more suspicious (trying to hide)
+                if alias.asname:
+                    severity = Severity.DANGER
+                    desc = f'Dangerous function imported with alias: {module}.{original_name} as {local_name}'
+                else:
+                    desc = f'Dangerous function imported: {module}.{original_name}'
+                
+                self.findings.append(Finding(
+                    severity=severity,
+                    pattern_id='dangerous_import',
+                    description=desc,
+                    file=self.filename,
+                    line=node.lineno,
+                    match=f'from {module} import {original_name}',
+                    context=ast.unparse(node) if hasattr(ast, 'unparse') else '',
+                ))
+            
+            # Check for suspicious module
+            base_module = module.split('.')[0] if module else ''
+            if base_module in SUSPICIOUS_MODULES:
+                self.findings.append(Finding(
+                    severity=Severity.WARN,
+                    pattern_id='suspicious_module_import',
+                    description=f'Import from suspicious module: {module}',
+                    file=self.filename,
+                    line=node.lineno,
+                    match=f'from {module} import {original_name}',
+                ))
+        
+        self.generic_visit(node)
+    
+    def visit_Assign(self, node: ast.Assign):
+        """Track assignments that might store dangerous references."""
+        # Check for: x = eval, x = __builtins__.eval, etc.
+        if isinstance(node.value, ast.Name):
+            value_name = node.value.id
+            if value_name in ('eval', 'exec', 'compile', 'system', 'open'):
+                for target in node.targets:
+                    if isinstance(target, ast.Name):
+                        self.dangerous_vars[target.id] = (f'alias for {value_name}', node.lineno)
+                        self.findings.append(Finding(
+                            severity=Severity.DANGER,
+                            pattern_id='dangerous_alias',
+                            description=f'Variable assigned dangerous builtin: {target.id} = {value_name}',
+                            file=self.filename,
+                            line=node.lineno,
+                            match=f'{target.id} = {value_name}',
+                        ))
+        
+        # Check for: x = getattr(module, 'dangerous')
+        if isinstance(node.value, ast.Call):
+            call = node.value
+            if isinstance(call.func, ast.Name) and call.func.id == 'getattr':
+                if len(call.args) >= 2 and isinstance(call.args[1], ast.Constant):
+                    attr_name = call.args[1].value
+                    if attr_name in ('eval', 'exec', 'compile', 'system', 'popen'):
+                        for target in node.targets:
+                            if isinstance(target, ast.Name):
+                                self.dangerous_vars[target.id] = (f'getattr result for {attr_name}', node.lineno)
+        
+        self.generic_visit(node)
+    
+    def visit_Call(self, node: ast.Call):
+        """Check function calls for dangerous patterns."""
+        
+        # Direct call to dangerous name: eval(...), exec(...)
+        if isinstance(node.func, ast.Name):
+            func_name = node.func.id
+            
+            # Check if it's an imported dangerous function
+            if func_name in self.imports:
+                imp = self.imports[func_name]
+                if imp.qualified in DANGEROUS_CALLABLES:
+                    self.findings.append(Finding(
+                        severity=Severity.DANGER,
+                        pattern_id='dangerous_call_aliased',
+                        description=f'Call to aliased dangerous function: {func_name} (imported from {imp.module}.{imp.original})',
+                        file=self.filename,
+                        line=node.lineno,
+                        match=f'{func_name}(...)',
+                    ))
+            
+            # Check if it's a variable holding a dangerous reference
+            if func_name in self.dangerous_vars:
+                reason, _ = self.dangerous_vars[func_name]
+                self.findings.append(Finding(
+                    severity=Severity.DANGER,
+                    pattern_id='dangerous_var_call',
+                    description=f'Call via dangerous variable: {func_name} ({reason})',
+                    file=self.filename,
+                    line=node.lineno,
+                    match=f'{func_name}(...)',
+                ))
+        
+        # Attribute call: os.system(...), subprocess.run(..., shell=True)
+        if isinstance(node.func, ast.Attribute):
+            self._check_attribute_call(node)
+        
+        # Check subprocess calls for shell=True
+        self._check_subprocess_shell(node)
+        
+        # Check for eval/exec with dynamic input
+        self._check_dynamic_code_exec(node)
+        
+        self.generic_visit(node)
+    
+    def _check_attribute_call(self, node: ast.Call):
+        """Check attribute-based calls like os.system(), module.func()"""
+        attr = node.func
+        if not isinstance(attr, ast.Attribute):
+            return
+        
+        # Get the full attribute chain
+        parts = []
+        current = attr
+        while isinstance(current, ast.Attribute):
+            parts.append(current.attr)
+            current = current.value
+        
+        if isinstance(current, ast.Name):
+            parts.append(current.id)
+        
+        parts.reverse()
+        
+        if len(parts) >= 2:
+            # Check if first part is an alias
+            base = parts[0]
+            if base in self.module_aliases:
+                module = self.module_aliases[base]
+            elif base in self.imports:
+                module = self.imports[base].module
+            else:
+                module = base
+            
+            func = parts[-1]
+            
+            # Check against dangerous callables
+            if (module, func) in DANGEROUS_CALLABLES:
+                self.findings.append(Finding(
+                    severity=Severity.WARN,  # WARN because might be legitimate
+                    pattern_id='dangerous_module_call',
+                    description=f'Call to potentially dangerous function: {module}.{func}',
+                    file=self.filename,
+                    line=node.lineno,
+                    match='.'.join(parts) + '(...)',
+                ))
+    
+    def _check_subprocess_shell(self, node: ast.Call):
+        """Check for subprocess calls with shell=True."""
+        # Get function name
+        func_name = None
+        if isinstance(node.func, ast.Name):
+            if node.func.id in self.imports:
+                imp = self.imports[node.func.id]
+                if imp.module == 'subprocess':
+                    func_name = imp.original
+        elif isinstance(node.func, ast.Attribute):
+            if isinstance(node.func.value, ast.Name):
+                base = node.func.value.id
+                module = self.module_aliases.get(base, base)
+                if module == 'subprocess':
+                    func_name = node.func.attr
+        
+        if func_name in ('run', 'call', 'Popen', 'check_call', 'check_output'):
+            # Check for shell=True in keyword arguments
+            for kw in node.keywords:
+                if kw.arg == 'shell':
+                    if isinstance(kw.value, ast.Constant) and kw.value.value is True:
+                        self.findings.append(Finding(
+                            severity=Severity.DANGER,
+                            pattern_id='subprocess_shell_true',
+                            description='subprocess call with shell=True - command injection risk',
+                            file=self.filename,
+                            line=node.lineno,
+                            match=f'subprocess.{func_name}(..., shell=True)',
+                        ))
+                    elif not isinstance(kw.value, ast.Constant):
+                        # shell= with a variable - suspicious
+                        self.findings.append(Finding(
+                            severity=Severity.WARN,
+                            pattern_id='subprocess_shell_dynamic',
+                            description='subprocess call with dynamic shell parameter',
+                            file=self.filename,
+                            line=node.lineno,
+                            match=f'subprocess.{func_name}(..., shell=?)',
+                        ))
+    
+    def _check_dynamic_code_exec(self, node: ast.Call):
+        """Check if eval/exec is called with non-literal input."""
+        func_name = None
+        if isinstance(node.func, ast.Name):
+            func_name = node.func.id
+        
+        if func_name in ('eval', 'exec', 'compile'):
+            if node.args:
+                first_arg = node.args[0]
+                # If first arg is not a string literal, it's dynamic
+                if not isinstance(first_arg, ast.Constant):
+                    self.findings.append(Finding(
+                        severity=Severity.DANGER,
+                        pattern_id='dynamic_code_execution',
+                        description=f'{func_name}() called with dynamic input - high risk',
+                        file=self.filename,
+                        line=node.lineno,
+                        match=f'{func_name}(<dynamic>)',
+                    ))
+
+
+def analyze_python_ast(content: str, filename: str) -> List[Finding]:
+    """Analyze Python code using AST for dangerous patterns."""
+    try:
+        tree = ast.parse(content, filename=filename)
+    except SyntaxError as e:
+        # Return a finding about syntax error (might be obfuscation)
+        return [Finding(
+            severity=Severity.WARN,
+            pattern_id='python_syntax_error',
+            description=f'Python syntax error (might be obfuscated or Python 2): {e}',
+            file=filename,
+            line=e.lineno or 1,
+            match=str(e),
+        )]
+    except Exception as e:
+        return [Finding(
+            severity=Severity.INFO,
+            pattern_id='ast_parse_error',
+            description=f'Could not parse Python AST: {e}',
+            file=filename,
+            line=1,
+            match=str(e),
+        )]
+    
+    visitor = DangerousCallVisitor(filename)
+    visitor.visit(tree)
+    
+    return visitor.findings
+
+
+def is_python_file(filename: str) -> bool:
+    """Check if a file is a Python file."""
+    return filename.endswith(('.py', '.pyw', '.pyi'))

isnad_scan/binary_scanner.py

@@ -0,0 +1,230 @@
+"""Binary file scanning for embedded scripts and suspicious content.
+
+Scans:
+- .pyc files (compiled Python)
+- Executables for embedded scripts
+- Images for steganography indicators
+- Archives for suspicious contents
+"""
+import re
+import struct
+from pathlib import Path
+from typing import List, Optional, Tuple
+
+from .patterns import Finding, Severity
+
+
+# Suspicious strings to look for in binaries
+SUSPICIOUS_BINARY_PATTERNS = [
+    # URLs (potential C2, exfiltration)
+    (rb'https?://[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}(?:/[^\s\x00]*)?', 'embedded_url', Severity.WARN),
+    
+    # IP addresses
+    (rb'\b(?:\d{1,3}\.){3}\d{1,3}\b', 'embedded_ip', Severity.INFO),
+    
+    # Shell commands
+    (rb'/bin/(?:ba)?sh', 'embedded_shell_path', Severity.WARN),
+    (rb'(?:curl|wget|nc|netcat)\s+', 'embedded_network_cmd', Severity.DANGER),
+    (rb'rm\s+-rf', 'embedded_rm_rf', Severity.DANGER),
+    
+    # Python code patterns
+    (rb'import\s+(?:os|subprocess|socket|requests)', 'embedded_python_import', Severity.WARN),
+    (rb'eval\s*\(|exec\s*\(', 'embedded_eval_exec', Severity.DANGER),
+    (rb'__import__\s*\(', 'embedded_dynamic_import', Severity.DANGER),
+    
+    # JavaScript patterns
+    (rb'require\s*\(\s*["\']child_process', 'embedded_child_process', Severity.DANGER),
+    (rb'new\s+Function\s*\(', 'embedded_function_constructor', Severity.DANGER),
+    
+    # Base64-encoded shell commands (common obfuscation)
+    (rb'(?:YmFz|L2Jpbi|Y3Vy|d2dl|bmV0Y2F0)', 'embedded_b64_cmd', Severity.WARN),  # bash, /bin, curl, wget, netcat
+    
+    # Crypto wallet addresses (exfiltration targets)
+    (rb'(?:bc1|[13])[a-zA-HJ-NP-Z0-9]{25,39}', 'embedded_btc_address', Severity.WARN),
+    (rb'0x[a-fA-F0-9]{40}', 'embedded_eth_address', Severity.INFO),
+    
+    # Private key patterns
+    (rb'-----BEGIN (?:RSA |EC |OPENSSH )?PRIVATE KEY-----', 'embedded_private_key', Severity.DANGER),
+    (rb'AKIA[0-9A-Z]{16}', 'embedded_aws_key', Severity.DANGER),
+]
+
+# Binary file extensions to scan
+BINARY_EXTENSIONS = {
+    '.pyc', '.pyo',  # Compiled Python
+    '.so', '.dll', '.dylib',  # Shared libraries
+    '.exe', '.bin',  # Executables
+    '.whl', '.egg',  # Python packages
+}
+
+# Image extensions (for stego check)
+IMAGE_EXTENSIONS = {'.png', '.jpg', '.jpeg', '.gif', '.bmp', '.webp'}
+
+# Archive extensions
+ARCHIVE_EXTENSIONS = {'.zip', '.tar', '.gz', '.tgz', '.bz2', '.7z', '.rar'}
+
+
+def is_binary_file(path: Path) -> bool:
+    """Check if a file should be treated as binary."""
+    return path.suffix.lower() in BINARY_EXTENSIONS
+
+
+def is_image_file(path: Path) -> bool:
+    """Check if a file is an image."""
+    return path.suffix.lower() in IMAGE_EXTENSIONS
+
+
+def scan_binary_content(content: bytes, filename: str) -> List[Finding]:
+    """Scan binary content for suspicious patterns."""
+    findings = []
+    
+    for pattern, pattern_id, severity in SUSPICIOUS_BINARY_PATTERNS:
+        for match in re.finditer(pattern, content):
+            # Get approximate position
+            pos = match.start()
+            
+            # Get context (surrounding bytes as printable string)
+            start = max(0, pos - 20)
+            end = min(len(content), pos + 100)
+            context_bytes = content[start:end]
+            # Convert to printable string
+            context = ''.join(chr(b) if 32 <= b < 127 else '.' for b in context_bytes)
+            
+            matched = match.group(0)
+            try:
+                match_str = matched.decode('utf-8', errors='replace')[:100]
+            except Exception:
+                match_str = str(matched[:50])
+            
+            findings.append(Finding(
+                severity=severity,
+                pattern_id=f'binary_{pattern_id}',
+                description=f'Suspicious content in binary file: {pattern_id}',
+                file=filename,
+                line=0,  # No line numbers in binary
+                match=match_str,
+                context=context[:200],
+            ))
+    
+    return findings
+
+
+def check_pyc_file(content: bytes, filename: str) -> List[Finding]:
+    """Check compiled Python file for suspicious indicators."""
+    findings = []
+    
+    # Basic PYC validation
+    if len(content) < 16:
+        findings.append(Finding(
+            severity=Severity.WARN,
+            pattern_id='binary_invalid_pyc',
+            description='Invalid or truncated .pyc file',
+            file=filename,
+            line=0,
+            match='<invalid pyc>',
+        ))
+        return findings
+    
+    # Check magic number (varies by Python version)
+    # We won't validate specific versions, just note it exists
+    findings.append(Finding(
+        severity=Severity.INFO,
+        pattern_id='binary_pyc_file',
+        description='Compiled Python bytecode - harder to audit than source',
+        file=filename,
+        line=0,
+        match=f'.pyc file ({len(content)} bytes)',
+    ))
+    
+    # Scan the bytecode for embedded strings
+    binary_findings = scan_binary_content(content, filename)
+    findings.extend(binary_findings)
+    
+    return findings
+
+
+def check_image_for_stego(content: bytes, filename: str) -> List[Finding]:
+    """Basic check for steganography indicators in images."""
+    findings = []
+    
+    # Check for data appended after image end markers
+    # PNG ends with IEND chunk
+    if filename.lower().endswith('.png'):
+        iend_pos = content.find(b'IEND')
+        if iend_pos != -1 and iend_pos + 12 < len(content):
+            # There's significant data after IEND
+            extra_data = len(content) - (iend_pos + 12)
+            if extra_data > 100:
+                findings.append(Finding(
+                    severity=Severity.WARN,
+                    pattern_id='binary_image_extra_data',
+                    description=f'PNG has {extra_data} bytes after IEND marker - possible hidden data',
+                    file=filename,
+                    line=0,
+                    match=f'{extra_data} bytes extra',
+                ))
+    
+    # JPEG ends with FFD9
+    if filename.lower().endswith(('.jpg', '.jpeg')):
+        eoi_pos = content.rfind(b'\xff\xd9')
+        if eoi_pos != -1 and eoi_pos + 2 < len(content):
+            extra_data = len(content) - (eoi_pos + 2)
+            if extra_data > 100:
+                findings.append(Finding(
+                    severity=Severity.WARN,
+                    pattern_id='binary_image_extra_data',
+                    description=f'JPEG has {extra_data} bytes after EOI marker - possible hidden data',
+                    file=filename,
+                    line=0,
+                    match=f'{extra_data} bytes extra',
+                ))
+    
+    # Check for embedded scripts in image
+    script_patterns = [
+        b'<script', b'<?php', b'<%', b'#!/',
+        b'import ', b'eval(', b'exec(',
+    ]
+    for pattern in script_patterns:
+        if pattern in content:
+            findings.append(Finding(
+                severity=Severity.DANGER,
+                pattern_id='binary_image_embedded_script',
+                description=f'Image contains embedded script pattern: {pattern.decode("utf-8", errors="replace")}',
+                file=filename,
+                line=0,
+                match=pattern.decode('utf-8', errors='replace'),
+            ))
+    
+    return findings
+
+
+def scan_binary_file(path: Path) -> Tuple[List[Finding], Optional[str]]:
+    """Scan a binary file for security issues."""
+    try:
+        content = path.read_bytes()
+    except Exception as e:
+        return [], f"Could not read binary file: {e}"
+    
+    # Size limit for binary files (5MB)
+    if len(content) > 5 * 1024 * 1024:
+        return [Finding(
+            severity=Severity.INFO,
+            pattern_id='binary_large_file',
+            description='Large binary file - skipped detailed scan',
+            file=str(path),
+            line=0,
+            match=f'{len(content)} bytes',
+        )], None
+    
+    findings = []
+    filename = str(path)
+    
+    # Type-specific checks
+    if path.suffix.lower() in ('.pyc', '.pyo'):
+        findings.extend(check_pyc_file(content, filename))
+    elif is_image_file(path):
+        findings.extend(check_image_for_stego(content, filename))
+    else:
+        # General binary scan
+        findings.extend(scan_binary_content(content, filename))
+    
+    return findings, None