vigilo 0.1.0__py3-none-any.whl

vigilo/__init__.py

@@ -0,0 +1,50 @@
+"""Vigilo — A static, security-focused code scanner for Python."""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+from pathlib import Path
+
+from vigilo.models import DetectorMeta, Finding, Location, Severity
+from vigilo.scanner import ScanConfig, Scanner
+
+__version__ = "0.1.0"
+
+
+def scan(
+    path: Path | str = ".",
+    min_severity: Severity | str = Severity.LOW,
+    exclude_patterns: Sequence[str] | None = None,
+) -> list[Finding]:
+    """Scan a target path for known security vulnerabilities.
+
+    Args:
+        path: Directory or file path to scan (defaults to current directory).
+        min_severity: Minimum severity threshold ("low", "medium", "high").
+        exclude_patterns: Glob patterns to exclude during file discovery.
+
+    Returns:
+        List of Finding objects discovered during scan.
+    """
+    if isinstance(min_severity, str):
+        min_severity = Severity(min_severity.lower())
+
+    config = ScanConfig(
+        paths=[path],
+        min_severity=min_severity,
+        exclude_patterns=exclude_patterns,
+    )
+    scanner = Scanner(config)
+    return scanner.scan()
+
+
+__all__ = [
+    "__version__",
+    "scan",
+    "Scanner",
+    "ScanConfig",
+    "Finding",
+    "Severity",
+    "Location",
+    "DetectorMeta",
+]

vigilo/__main__.py

@@ -0,0 +1,6 @@
+"""Entrypoint for python -m vigilo."""
+
+from vigilo.cli import main
+
+if __name__ == "__main__":
+    main()

vigilo/cli.py

@@ -0,0 +1,130 @@
+"""CLI entry point and command-line parser for Vigilo."""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from collections.abc import Sequence
+from pathlib import Path
+
+from vigilo import __version__
+from vigilo.models import Severity
+from vigilo.reporter import format_report
+from vigilo.scanner import ScanConfig, Scanner
+
+
+def build_parser() -> argparse.ArgumentParser:
+    """Construct the command-line argument parser."""
+    parser = argparse.ArgumentParser(
+        prog="vigilo",
+        description="Vigilo — A static, security-focused code scanner for Python.",
+    )
+    parser.add_argument(
+        "--version",
+        "-V",
+        action="version",
+        version=f"vigilo {__version__}",
+    )
+
+    subparsers = parser.add_subparsers(dest="command", help="Available subcommands")
+
+    scan_parser = subparsers.add_parser(
+        "scan",
+        help="Scan a directory or file for security vulnerabilities",
+    )
+    scan_parser.add_argument(
+        "target",
+        nargs="?",
+        default=".",
+        help="Path to directory or file to scan (default: '.')",
+    )
+    scan_parser.add_argument(
+        "--format",
+        "-f",
+        choices=["text", "json"],
+        default="text",
+        help="Output report format (default: 'text')",
+    )
+    scan_parser.add_argument(
+        "--min-severity",
+        "-s",
+        choices=["low", "medium", "high"],
+        default="low",
+        help="Minimum severity threshold to report (default: 'low')",
+    )
+    scan_parser.add_argument(
+        "--exclude",
+        "-e",
+        action="append",
+        default=[],
+        help="Exclude files/directories matching glob pattern (repeatable)",
+    )
+    scan_parser.add_argument(
+        "--no-color",
+        action="store_true",
+        default=False,
+        help="Disable ANSI color codes in output",
+    )
+
+    return parser
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    """Main execution entrypoint for Vigilo CLI."""
+    if argv is None:
+        argv = sys.argv[1:]
+
+    args_list = list(argv)
+
+    # Normalize alias: `vigilo <path>` -> `vigilo scan <path>`
+    if not args_list:
+        args_list = ["scan", "."]
+    elif args_list[0] not in ("scan", "-h", "--help", "-V", "--version"):
+        args_list = ["scan"] + args_list
+
+    parser = build_parser()
+
+    try:
+        args = parser.parse_args(args_list)
+    except SystemExit as e:
+        return int(e.code) if isinstance(e.code, int) else 2
+
+    if getattr(args, "command", None) != "scan":
+        parser.print_help()
+        return 0
+
+    target_str = getattr(args, "target", ".")
+    target_path = Path(target_str)
+    if not target_path.exists():
+        sys.stderr.write(f"Error: Target path does not exist: {target_str}\n")
+        return 2
+
+    out_format = getattr(args, "format", "text")
+    min_sev_str = getattr(args, "min_severity", "low")
+    excludes = getattr(args, "exclude", [])
+    no_color = getattr(args, "no_color", False)
+
+    min_severity = Severity(min_sev_str.lower())
+    use_color = not no_color and sys.stdout.isatty() and out_format == "text"
+
+    try:
+        config = ScanConfig(
+            paths=[target_path],
+            min_severity=min_severity,
+            exclude_patterns=excludes if excludes else None,
+        )
+        scanner = Scanner(config)
+        findings = scanner.scan()
+    except Exception as e:
+        sys.stderr.write(f"Scan error: {e}\n")
+        return 2
+
+    report_str = format_report(findings, output_format=out_format, use_color=use_color)
+    print(report_str)
+
+    # Exit code: 1 if findings present, 0 if clean
+    return 1 if findings else 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

vigilo/detectors/__init__.py

@@ -0,0 +1,28 @@
+"""Detector registry and public interface for Vigilo."""
+
+from __future__ import annotations
+
+from vigilo.detectors.base import BaseDetector
+from vigilo.detectors.code_injection import CodeInjectionDetector
+from vigilo.detectors.command_injection import CommandInjectionDetector
+from vigilo.detectors.path_traversal import PathTraversalDetector
+from vigilo.detectors.sql_injection import SQLInjectionDetector
+from vigilo.detectors.unsafe_deserialization import UnsafeDeserializationDetector
+
+ALL_DETECTORS: list[type[BaseDetector]] = [
+    SQLInjectionDetector,
+    CommandInjectionDetector,
+    CodeInjectionDetector,
+    UnsafeDeserializationDetector,
+    PathTraversalDetector,
+]
+
+__all__ = [
+    "BaseDetector",
+    "ALL_DETECTORS",
+    "SQLInjectionDetector",
+    "CommandInjectionDetector",
+    "CodeInjectionDetector",
+    "UnsafeDeserializationDetector",
+    "PathTraversalDetector",
+]

vigilo/detectors/base.py

@@ -0,0 +1,89 @@
+"""Base classes and interfaces for vulnerability detectors in Vigilo."""
+
+from __future__ import annotations
+
+import ast
+from abc import ABC, abstractmethod
+from pathlib import Path
+
+from vigilo.models import DetectorMeta, Finding, Location, Severity
+
+
+class BaseDetector(ABC):
+    """Abstract base class for all Vigilo vulnerability detectors."""
+
+    meta: DetectorMeta
+
+    @abstractmethod
+    def run(self, tree: ast.Module, file_path: Path, source: str) -> list[Finding]:
+        """Scan a parsed Python AST module for vulnerability patterns.
+
+        Args:
+            tree: Parsed AST module node.
+            file_path: Path to the scanned file.
+            source: Raw string content of the source file.
+
+        Returns:
+            List of findings discovered in this file.
+        """
+        ...
+
+    def create_finding(
+        self,
+        node: ast.AST,
+        file_path: Path,
+        source: str,
+        message: str,
+        fix_hint: str,
+        severity: Severity | None = None,
+        confidence: str = "high",
+    ) -> Finding:
+        """Create a standardized Finding instance from an AST node."""
+        lineno = getattr(node, "lineno", 1)
+        col_offset = getattr(node, "col_offset", 0)
+        end_lineno = getattr(node, "end_lineno", None)
+        end_col_offset = getattr(node, "end_col_offset", None)
+
+        source_lines = source.splitlines()
+        source_line = ""
+        if 1 <= lineno <= len(source_lines):
+            source_line = source_lines[lineno - 1]
+
+        location = Location(
+            file=file_path,
+            line=lineno,
+            col=col_offset,
+            end_line=end_lineno,
+            end_col=end_col_offset,
+        )
+
+        return Finding(
+            detector=self.meta,
+            location=location,
+            message=message,
+            fix_hint=fix_hint,
+            severity=severity or self.meta.severity,
+            confidence=confidence,
+            source_line=source_line,
+        )
+
+    @staticmethod
+    def build_parent_map(tree: ast.Module) -> dict[ast.AST, ast.AST]:
+        """Build a mapping of child AST nodes to their parent nodes."""
+        parent_map: dict[ast.AST, ast.AST] = {}
+        for parent in ast.walk(tree):
+            for child in ast.iter_child_nodes(parent):
+                parent_map[child] = parent
+        return parent_map
+
+    @staticmethod
+    def get_enclosing_function(
+        node: ast.AST, parent_map: dict[ast.AST, ast.AST]
+    ) -> ast.FunctionDef | ast.AsyncFunctionDef | None:
+        """Find the enclosing function definition for a given AST node."""
+        curr: ast.AST | None = node
+        while curr is not None:
+            if isinstance(curr, (ast.FunctionDef, ast.AsyncFunctionDef)):
+                return curr
+            curr = parent_map.get(curr)
+        return None

vigilo/detectors/code_injection.py

@@ -0,0 +1,63 @@
+"""Detector for Code Injection vulnerabilities (CWE-94 / VIGILO-003)."""
+
+from __future__ import annotations
+
+import ast
+from pathlib import Path
+
+from vigilo.detectors.base import BaseDetector
+from vigilo.flow import FlowAnalyzer
+from vigilo.models import DetectorMeta, Finding, Severity
+
+CODE_EXEC_FUNCTIONS = {"eval", "exec", "compile"}
+
+
+class CodeInjectionDetector(BaseDetector):
+    """Detects dangerous evaluation or execution of dynamically constructed code."""
+
+    meta = DetectorMeta(
+        id="VIGILO-003",
+        name="Code Injection",
+        cwe=94,
+        description="Detects dynamic expressions passed to eval(), exec(), or compile()",
+        severity=Severity.HIGH,
+    )
+
+    def run(self, tree: ast.Module, file_path: Path, source: str) -> list[Finding]:
+        findings: list[Finding] = []
+        parent_map = self.build_parent_map(tree)
+
+        for node in ast.walk(tree):
+            if not isinstance(node, ast.Call):
+                continue
+
+            func_name = None
+            if isinstance(node.func, ast.Name):
+                func_name = node.func.id
+            elif isinstance(node.func, ast.Attribute) and isinstance(node.func.value, ast.Name):
+                if node.func.value.id == "builtins":
+                    func_name = node.func.attr
+
+            if func_name in CODE_EXEC_FUNCTIONS and node.args:
+                code_arg = node.args[0]
+                scope = self.get_enclosing_function(node, parent_map)
+
+                if FlowAnalyzer.is_dynamic(code_arg, scope):
+                    msg = f"Possible code injection: dynamic expression passed to `{func_name}()`."
+                    hint = (
+                        "Avoid executing arbitrary code. Use `ast.literal_eval()` for safely "
+                        "parsing literals, or use `json.loads()` for structured data."
+                    )
+                    findings.append(
+                        self.create_finding(
+                            node=node,
+                            file_path=file_path,
+                            source=source,
+                            message=msg,
+                            fix_hint=hint,
+                            severity=self.meta.severity,
+                            confidence="high",
+                        )
+                    )
+
+        return findings

vigilo/detectors/command_injection.py

@@ -0,0 +1,107 @@
+"""Detector for OS Command Injection vulnerabilities (CWE-78 / VIGILO-002)."""
+
+from __future__ import annotations
+
+import ast
+from pathlib import Path
+
+from vigilo.detectors.base import BaseDetector
+from vigilo.flow import FlowAnalyzer
+from vigilo.models import DetectorMeta, Finding, Severity
+
+SUBPROCESS_METHODS = {
+    "run",
+    "Popen",
+    "call",
+    "check_call",
+    "check_output",
+}
+
+
+class CommandInjectionDetector(BaseDetector):
+    """Detects dangerous OS command executions with dynamic or unsanitized input."""
+
+    meta = DetectorMeta(
+        id="VIGILO-002",
+        name="OS Command Injection",
+        cwe=78,
+        description="Detects dynamic shell commands passed to execution functions",
+        severity=Severity.HIGH,
+    )
+
+    def _has_shell_true(self, node: ast.Call) -> bool:
+        """Check if shell=True is present in keyword arguments."""
+        for kw in node.keywords:
+            if kw.arg == "shell":
+                val = FlowAnalyzer.get_constant_value(kw.value)
+                return bool(val is True)
+        return False
+
+    def run(self, tree: ast.Module, file_path: Path, source: str) -> list[Finding]:
+        findings: list[Finding] = []
+        parent_map = self.build_parent_map(tree)
+
+        for node in ast.walk(tree):
+            if not isinstance(node, ast.Call):
+                continue
+
+            scope = self.get_enclosing_function(node, parent_map)
+
+            # Check os.system(...) and os.popen(...)
+            if isinstance(node.func, ast.Attribute) and isinstance(node.func.value, ast.Name):
+                if node.func.value.id == "os" and node.func.attr in ("system", "popen"):
+                    if node.args and FlowAnalyzer.is_dynamic(node.args[0], scope):
+                        attr = node.func.attr
+                        msg = f"Possible OS command injection: dynamic command in `os.{attr}()`."
+                        hint = (
+                            "Use `subprocess.run([...], shell=False)` with an argument list "
+                            "instead of invoking shell commands."
+                        )
+                        findings.append(
+                            self.create_finding(
+                                node=node,
+                                file_path=file_path,
+                                source=source,
+                                message=msg,
+                                fix_hint=hint,
+                                severity=self.meta.severity,
+                                confidence="high",
+                            )
+                        )
+                        continue
+
+            # Check subprocess methods with shell=True and dynamic input
+            is_subprocess = False
+            func_name = ""
+            if isinstance(node.func, ast.Attribute):
+                if isinstance(node.func.value, ast.Name) and node.func.value.id == "subprocess":
+                    is_subprocess = True
+                    func_name = node.func.attr
+            elif isinstance(node.func, ast.Name) and node.func.id in SUBPROCESS_METHODS:
+                is_subprocess = True
+                func_name = node.func.id
+
+            if is_subprocess and func_name in SUBPROCESS_METHODS and node.args:
+                cmd_arg = node.args[0]
+                if self._has_shell_true(node) and FlowAnalyzer.is_dynamic(cmd_arg, scope):
+                    msg = (
+                        f"Possible OS command injection: dynamic command in "
+                        f"`subprocess.{func_name}(shell=True)`."
+                    )
+                    hint = (
+                        "Avoid `shell=True`. Pass a list of command arguments with `shell=False` "
+                        "(e.g., subprocess.run(['cmd', arg], shell=False))."
+                    )
+                    findings.append(
+                        self.create_finding(
+                            node=node,
+                            file_path=file_path,
+                            source=source,
+                            message=msg,
+                            fix_hint=hint,
+                            severity=self.meta.severity,
+                            confidence="high",
+                        )
+                    )
+
+        return findings

vigilo/detectors/path_traversal.py

@@ -0,0 +1,103 @@
+"""Detector for Path Traversal vulnerabilities (CWE-22 / VIGILO-005)."""
+
+from __future__ import annotations
+
+import ast
+from pathlib import Path
+
+from vigilo.detectors.base import BaseDetector
+from vigilo.flow import FlowAnalyzer
+from vigilo.models import DetectorMeta, Finding, Severity
+
+PATH_OPEN_FUNCTIONS = {"open"}
+PATH_MODULE_FUNCTIONS = {("os", "open"), ("io", "open")}
+
+
+class PathTraversalDetector(BaseDetector):
+    """Detects unsafe file path construction that may allow directory traversal."""
+
+    meta = DetectorMeta(
+        id="VIGILO-005",
+        name="Path Traversal",
+        cwe=22,
+        description="Detects dynamic or user-controlled paths passed to file open functions",
+        severity=Severity.HIGH,
+    )
+
+    def _is_dynamic_path(
+        self,
+        node: ast.AST,
+        scope: ast.FunctionDef | ast.AsyncFunctionDef | None,
+    ) -> bool:
+        """Check if an expression represents a dynamic path."""
+        if FlowAnalyzer.is_constant(node):
+            return False
+
+        # Dynamic string concatenation (e.g., "/base/" + filename)
+        if isinstance(node, ast.BinOp) and isinstance(node.op, ast.Add):
+            return FlowAnalyzer.is_dynamic(node, scope)
+
+        # Dynamic f-string (e.g., f"/base/{filename}")
+        if isinstance(node, ast.JoinedStr):
+            return FlowAnalyzer.is_dynamic(node, scope)
+
+        # String formatting with % or .format()
+        if isinstance(node, ast.BinOp) and isinstance(node.op, ast.Mod):
+            return FlowAnalyzer.is_dynamic(node, scope)
+
+        if isinstance(node, ast.Call) and isinstance(node.func, ast.Attribute):
+            if node.func.attr == "format":
+                return any(FlowAnalyzer.is_dynamic(arg, scope) for arg in node.args)
+
+        # Path passed directly from dynamic variable / parameter
+        if isinstance(node, ast.Name):
+            return FlowAnalyzer.is_dynamic(node, scope)
+
+        return False
+
+    def run(self, tree: ast.Module, file_path: Path, source: str) -> list[Finding]:
+        findings: list[Finding] = []
+        parent_map = self.build_parent_map(tree)
+
+        for node in ast.walk(tree):
+            if not isinstance(node, ast.Call):
+                continue
+
+            scope = self.get_enclosing_function(node, parent_map)
+            is_file_open = False
+            func_name = ""
+
+            # Check built-in open(...)
+            if isinstance(node.func, ast.Name) and node.func.id in PATH_OPEN_FUNCTIONS:
+                is_file_open = True
+                func_name = node.func.id
+
+            # Check os.open(...), io.open(...)
+            elif isinstance(node.func, ast.Attribute) and isinstance(node.func.value, ast.Name):
+                module_name = node.func.value.id
+                method_name = node.func.attr
+                if (module_name, method_name) in PATH_MODULE_FUNCTIONS:
+                    is_file_open = True
+                    func_name = f"{module_name}.{method_name}"
+
+            if is_file_open and node.args:
+                path_arg = node.args[0]
+                if self._is_dynamic_path(path_arg, scope):
+                    msg = f"Possible path traversal: dynamic path in `{func_name}()`."
+                    hint = (
+                        "Sanitize file paths using `os.path.basename()` or verify that "
+                        "the resolved path starts with the intended base directory."
+                    )
+                    findings.append(
+                        self.create_finding(
+                            node=node,
+                            file_path=file_path,
+                            source=source,
+                            message=msg,
+                            fix_hint=hint,
+                            severity=self.meta.severity,
+                            confidence="high",
+                        )
+                    )
+
+        return findings