pyshield-security 0.1.0__py3-none-any.whl

pyshield/__init__.py

@@ -0,0 +1,4 @@
+"""PyShield: Developer-focused open-source security analysis platform for Python."""
+
+__version__ = "0.1.0"
+__all__ = ["__version__"]

pyshield/__main__.py

@@ -0,0 +1,8 @@
+"""Main entrypoint for python -m pyshield."""
+
+import sys
+
+from pyshield.cli.main import app
+
+if __name__ == "__main__":
+    sys.exit(app())

pyshield/cli/__init__.py

@@ -0,0 +1,5 @@
+"""PyShield CLI package."""
+
+from pyshield.cli.main import app
+
+__all__ = ["app"]

pyshield/cli/main.py

@@ -0,0 +1,115 @@
+"""Command-line interface for PyShield."""
+
+import sys
+from pathlib import Path
+
+import typer
+
+from pyshield import __version__
+from pyshield.config.models import DEFAULT_EXCLUDES, ScanConfig
+from pyshield.core.engine import ScanEngine
+from pyshield.core.models import Severity
+from pyshield.reporters.terminal import TerminalReporter
+
+app = typer.Typer(
+    name="pyshield",
+    help="PyShield: Developer-focused open-source Python security analysis platform.",
+    no_args_is_help=True,
+    add_completion=False,
+)
+
+
+def version_callback(value: bool) -> None:
+    """Print the PyShield version and exit."""
+    if value:
+        typer.echo(f"PyShield {__version__}")
+        raise typer.Exit()
+
+
+@app.callback()
+def main(
+    version: bool | None = typer.Option(
+        None,
+        "--version",
+        "-v",
+        help="Show PyShield version and exit.",
+        callback=version_callback,
+        is_eager=True,
+    ),
+) -> None:
+    """PyShield root command."""
+
+
+@app.command(name="scan", help="Scan Python files or directories for security vulnerabilities.")
+def scan(
+    paths: list[Path] = typer.Argument(
+        None,
+        help="One or more file or directory paths to scan (default: current directory).",
+    ),
+    fail_on: Severity = typer.Option(
+        Severity.LOW,
+        "--fail-on",
+        help="Minimum severity threshold to trigger exit code 1 (LOW, MEDIUM, HIGH, CRITICAL).",
+        case_sensitive=False,
+    ),
+    exclude: list[str] = typer.Option(
+        None,
+        "--exclude",
+        "-e",
+        help="Additional glob patterns or directory names to exclude.",
+    ),
+    disable_rule: list[str] = typer.Option(
+        None,
+        "--disable-rule",
+        "-d",
+        help="Rule IDs to disable (e.g. PS101).",
+    ),
+    enable_rule: list[str] = typer.Option(
+        None,
+        "--enable-rule",
+        help="Explicit rule IDs to enable (only these will run).",
+    ),
+) -> None:
+    """Run deterministic static security analysis on the specified paths."""
+    target_paths = paths if paths else [Path(".")]
+
+    # Validate that all target paths exist; exit with code 2 if not
+    for path in target_paths:
+        if not path.exists():
+            sys.stderr.write(f"Error: Target path does not exist: {path}\n")
+            raise typer.Exit(code=2)
+
+    # Build scan configuration
+    exclude_patterns = list(DEFAULT_EXCLUDES)
+    if exclude:
+        exclude_patterns.extend(exclude)
+
+    config = ScanConfig(
+        target_paths=target_paths,
+        exclude_patterns=exclude_patterns,
+        fail_on=fail_on,
+        disabled_rules=set(disable_rule) if disable_rule else set(),
+        enabled_rules=set(enable_rule) if enable_rule else None,
+    )
+
+    try:
+        engine = ScanEngine(config=config)
+        result = engine.run()
+    except Exception as err:
+        sys.stderr.write(f"Error during scan execution: {err}\n")
+        raise typer.Exit(code=2) from err
+
+    reporter = TerminalReporter()
+    reporter.render(result)
+
+    # Exit code determination
+    # 0 = No findings at or above configured failure threshold
+    # 1 = One or more findings at or above configured threshold
+    # 2 = Scan error (e.g. zero files could be parsed and all failed)
+    if result.summary.files_scanned == 0 and result.summary.files_failed > 0:
+        raise typer.Exit(code=2)
+
+    if any(finding.severity >= fail_on for finding in result.findings):
+        raise typer.Exit(code=1)
+
+    raise typer.Exit(code=0)

pyshield/config/__init__.py

@@ -0,0 +1,5 @@
+"""Configuration components for PyShield."""
+
+from pyshield.config.models import DEFAULT_EXCLUDES, ScanConfig
+
+__all__ = ["DEFAULT_EXCLUDES", "ScanConfig"]

pyshield/config/models.py

@@ -0,0 +1,54 @@
+"""Configuration data models for PyShield."""
+
+from pathlib import Path
+
+from pydantic import BaseModel, Field
+
+from pyshield.core.models import Severity
+
+DEFAULT_EXCLUDES: list[str] = [
+    ".git",
+    ".venv",
+    "venv",
+    "env",
+    "__pycache__",
+    "node_modules",
+    "build",
+    "dist",
+    ".pytest_cache",
+    ".mypy_cache",
+    ".ruff_cache",
+    "*.egg-info",
+    ".eggs",
+    ".tox",
+    ".nox",
+]
+
+
+class ScanConfig(BaseModel):
+    """Configuration options for a PyShield scan."""
+
+    target_paths: list[Path] = Field(
+        default_factory=lambda: [Path(".")],
+        description="List of file or directory paths to analyze",
+    )
+    exclude_patterns: list[str] = Field(
+        default_factory=lambda: list(DEFAULT_EXCLUDES),
+        description="Glob patterns or directory names to exclude from analysis",
+    )
+    fail_on: Severity | None = Field(
+        default=Severity.LOW,
+        description="Minimum severity threshold that triggers a non-zero exit code",
+    )
+    max_file_size_bytes: int = Field(
+        default=10 * 1024 * 1024,
+        description="Maximum file size in bytes to inspect (default: 10MB)",
+    )
+    disabled_rules: set[str] = Field(
+        default_factory=set,
+        description="Set of rule IDs to disable during the scan",
+    )
+    enabled_rules: set[str] | None = Field(
+        default=None,
+        description="Explicit set of rule IDs to run (runs all registered if None)",
+    )

pyshield/core/__init__.py

@@ -0,0 +1,19 @@
+"""PyShield core engine components."""
+
+from pyshield.core.models import (
+    Confidence,
+    FileDiagnostic,
+    Finding,
+    ScanResult,
+    ScanSummary,
+    Severity,
+)
+
+__all__ = [
+    "Confidence",
+    "FileDiagnostic",
+    "Finding",
+    "ScanResult",
+    "ScanSummary",
+    "Severity",
+]

pyshield/core/analyzer.py

@@ -0,0 +1,77 @@
+"""AST Analyzer: safely reads, parses, and executes rules on Python files."""
+
+import ast
+from pathlib import Path
+
+from pyshield.core.models import FileDiagnostic, Finding
+from pyshield.rules.base import ASTContext, BaseRule
+
+
+class ASTAnalyzer:
+    """Performs static analysis on Python source files using standard ast."""
+
+    def __init__(self, rules: list[BaseRule]) -> None:
+        self.rules = rules
+
+    def analyze_source(
+        self,
+        source_code: str,
+        file_path: Path,
+    ) -> tuple[list[Finding], FileDiagnostic | None]:
+        """Analyze a string of Python source code against configured rules."""
+        try:
+            tree = ast.parse(source_code, filename=str(file_path))
+        except SyntaxError as err:
+            diagnostic = FileDiagnostic(
+                file_path=file_path,
+                error_type="SyntaxError",
+                message=err.msg or "Syntax error during parsing",
+                line=err.lineno,
+                column=err.offset,
+            )
+            return [], diagnostic
+        except Exception as err:
+            diagnostic = FileDiagnostic(
+                file_path=file_path,
+                error_type=type(err).__name__,
+                message=str(err) or "Failed to parse AST",
+            )
+            return [], diagnostic
+
+        context = ASTContext.create(file_path=file_path, source_code=source_code, tree=tree)
+        findings: list[Finding] = []
+
+        for rule in self.rules:
+            rule_findings = rule.check(context)
+            findings.extend(rule_findings)
+
+        return findings, None
+
+    def analyze_file(
+        self,
+        file_path: Path,
+        max_file_size_bytes: int = 10 * 1024 * 1024,
+    ) -> tuple[list[Finding], FileDiagnostic | None]:
+        """Read and analyze a single Python file from disk."""
+        try:
+            stat = file_path.stat()
+            if stat.st_size > max_file_size_bytes:
+                return [], FileDiagnostic(
+                    file_path=file_path,
+                    error_type="FileSizeLimitExceeded",
+                    message=(
+                        f"File size ({stat.st_size} bytes) exceeds "
+                        f"limit ({max_file_size_bytes} bytes)"
+                    ),
+                )
+
+            # Read with utf-8 and replacement characters for invalid encodings
+            source_code = file_path.read_text(encoding="utf-8", errors="replace")
+        except OSError as err:
+            return [], FileDiagnostic(
+                file_path=file_path,
+                error_type="ReadError",
+                message=f"Could not read file: {err}",
+            )
+
+        return self.analyze_source(source_code=source_code, file_path=file_path)

pyshield/core/engine.py

@@ -0,0 +1,165 @@
+"""Scan Engine: discovers Python source files and orchestrates security analysis."""
+
+import fnmatch
+import time
+from collections.abc import Iterator
+from pathlib import Path
+
+from pyshield.config.models import ScanConfig
+from pyshield.core.analyzer import ASTAnalyzer
+from pyshield.core.models import Finding, ScanResult, ScanSummary, Severity
+from pyshield.core.registry import RuleRegistry
+
+
+def should_exclude(path: Path, exclude_patterns: list[str]) -> bool:
+    """Determine whether a given path matches any exclude pattern."""
+    path_str = str(path).replace("\\", "/")
+    parts = path.parts
+
+    for pattern in exclude_patterns:
+        # Check against path components (e.g. '.venv', '__pycache__')
+        for part in parts:
+            if fnmatch.fnmatch(part, pattern):
+                return True
+        # Check against full path string or glob
+        if fnmatch.fnmatch(path_str, pattern) or fnmatch.fnmatch(path.name, pattern):
+            return True
+
+    return False
+
+
+def discover_python_files(
+    target_path: Path,
+    exclude_patterns: list[str],
+) -> list[Path]:
+    """Discover all Python source files recursively, avoiding exclusions and symlink cycles."""
+    if not target_path.exists():
+        raise FileNotFoundError(f"Target path does not exist: {target_path}")
+
+    # If single file target
+    if target_path.is_file():
+        if target_path.suffix == ".py" and not should_exclude(target_path, exclude_patterns):
+            return [target_path]
+        return []
+
+    discovered: list[Path] = []
+    visited_dirs: set[str] = set()
+
+    for root_dir, dirs, files in _safe_walk(target_path, visited_dirs):
+        # Filter directories in-place to prevent traversing excluded dirs
+        dirs[:] = [d for d in dirs if not should_exclude(root_dir / d, exclude_patterns)]
+
+        for file_name in files:
+            if file_name.endswith(".py"):
+                file_path = root_dir / file_name
+                if not should_exclude(file_path, exclude_patterns):
+                    discovered.append(file_path)
+
+    return sorted(discovered)
+
+
+def _safe_walk(
+    target_path: Path, visited_dirs: set[str]
+) -> Iterator[tuple[Path, list[str], list[str]]]:
+    """Walk directory tree while preventing symlink loops."""
+    import os
+
+    try:
+        resolved_root = str(target_path.resolve())
+        visited_dirs.add(resolved_root)
+    except OSError:
+        return
+
+    for root, dirs, files in os.walk(target_path, followlinks=False):
+        current_root_path = Path(root)
+        try:
+            visited_dirs.add(str(current_root_path.resolve()))
+        except OSError:
+            continue
+
+        # Prevent circular symlink recursion
+        filtered_dirs: list[str] = []
+        for d in dirs:
+            dir_path = current_root_path / d
+            try:
+                if dir_path.is_symlink():
+                    resolved_target = str(dir_path.resolve())
+                    if resolved_target in visited_dirs:
+                        continue  # Skip symlink cycle
+                    visited_dirs.add(resolved_target)
+                filtered_dirs.append(d)
+            except OSError:
+                continue
+
+        dirs[:] = filtered_dirs
+        yield current_root_path, dirs, files
+
+
+class ScanEngine:
+    """Coordinates file discovery, AST analysis, and result aggregation."""
+
+    def __init__(
+        self,
+        config: ScanConfig | None = None,
+        registry: RuleRegistry | None = None,
+    ) -> None:
+        self.config = config or ScanConfig()
+        self.registry = registry or RuleRegistry.create_default()
+
+    def run(self) -> ScanResult:
+        """Execute the configured scan across all target paths."""
+        start_time = time.perf_counter()
+
+        active_rules = self.registry.get_active(
+            disabled_rules=self.config.disabled_rules,
+            enabled_rules=self.config.enabled_rules,
+        )
+        analyzer = ASTAnalyzer(rules=active_rules)
+
+        all_findings: list[Finding] = []
+        all_diagnostics = []
+        files_scanned = 0
+        files_failed = 0
+
+        # Collect files from all target paths
+        target_files: list[Path] = []
+        for target in self.config.target_paths:
+            found = discover_python_files(target, self.config.exclude_patterns)
+            target_files.extend(found)
+
+        # Remove potential duplicates while preserving order
+        unique_files = list(dict.fromkeys(target_files))
+
+        for file_path in unique_files:
+            findings, diagnostic = analyzer.analyze_file(
+                file_path=file_path,
+                max_file_size_bytes=self.config.max_file_size_bytes,
+            )
+            if diagnostic is not None:
+                all_diagnostics.append(diagnostic)
+                files_failed += 1
+            else:
+                files_scanned += 1
+                all_findings.extend(findings)
+
+        # Sort findings deterministically: file, line, col, rule_id
+        all_findings.sort(key=lambda f: (str(f.file_path), f.line, f.column, f.rule_id))
+
+        findings_count = {s: 0 for s in Severity}
+        for finding in all_findings:
+            findings_count[finding.severity] += 1
+
+        duration = time.perf_counter() - start_time
+
+        summary = ScanSummary(
+            files_scanned=files_scanned,
+            files_failed=files_failed,
+            findings_count=findings_count,
+            duration_seconds=round(duration, 3),
+        )
+
+        return ScanResult(
+            findings=all_findings,
+            diagnostics=all_diagnostics,
+            summary=summary,
+        )

pyshield/core/models.py

@@ -0,0 +1,117 @@
+"""Core data models for PyShield security analysis."""
+
+from enum import StrEnum
+from pathlib import Path
+from typing import Any
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class Severity(StrEnum):
+    """Vulnerability severity levels ordered by criticality."""
+
+    LOW = "LOW"
+    MEDIUM = "MEDIUM"
+    HIGH = "HIGH"
+    CRITICAL = "CRITICAL"
+
+    @property
+    def level(self) -> int:
+        """Integer priority level for comparison (higher = more severe)."""
+        mapping = {
+            Severity.LOW: 1,
+            Severity.MEDIUM: 2,
+            Severity.HIGH: 3,
+            Severity.CRITICAL: 4,
+        }
+        return mapping[self]
+
+    def __ge__(self, other: Any) -> bool:
+        if isinstance(other, Severity):
+            return self.level >= other.level
+        return NotImplemented
+
+    def __gt__(self, other: Any) -> bool:
+        if isinstance(other, Severity):
+            return self.level > other.level
+        return NotImplemented
+
+    def __le__(self, other: Any) -> bool:
+        if isinstance(other, Severity):
+            return self.level <= other.level
+        return NotImplemented
+
+    def __lt__(self, other: Any) -> bool:
+        if isinstance(other, Severity):
+            return self.level < other.level
+        return NotImplemented
+
+
+class Confidence(StrEnum):
+    """Confidence levels in the deterministic finding."""
+
+    LOW = "LOW"
+    MEDIUM = "MEDIUM"
+    HIGH = "HIGH"
+
+
+class Finding(BaseModel):
+    """Represents a deterministic security finding detected by a rule."""
+
+    model_config = ConfigDict(frozen=True)
+
+    rule_id: str = Field(description="Unique stable rule identifier, e.g. PS101")
+    title: str = Field(description="Brief title of the finding")
+    severity: Severity = Field(description="Severity classification")
+    confidence: Confidence = Field(description="Confidence level in the match")
+    file_path: Path = Field(description="Path to the file where the finding was detected")
+    line: int = Field(description="Line number (1-indexed)")
+    column: int = Field(description="Column number (1-indexed)")
+    end_line: int | None = Field(default=None, description="Ending line number if known")
+    end_column: int | None = Field(default=None, description="Ending column number if known")
+    message: str = Field(description="Context-specific finding message")
+    description: str = Field(description="Detailed explanation of the vulnerability risk")
+    remediation: str = Field(description="Actionable guidance to remediate the issue")
+    cwe: str | None = Field(default=None, description="Common Weakness Enumeration ID, e.g. CWE-95")
+    snippet: str | None = Field(default=None, description="Safe code excerpt at finding location")
+
+
+class FileDiagnostic(BaseModel):
+    """Represents a non-fatal diagnostic or error encountered when processing a file."""
+
+    model_config = ConfigDict(frozen=True)
+
+    file_path: Path = Field(description="Path to the file that caused the diagnostic")
+    error_type: str = Field(description="Type of error (e.g. SyntaxError, UnicodeDecodeError)")
+    message: str = Field(description="Detailed diagnostic message")
+    line: int | None = Field(default=None, description="Line number if available")
+    column: int | None = Field(default=None, description="Column number if available")
+
+
+class ScanSummary(BaseModel):
+    """Summary metrics of a scan execution."""
+
+    files_scanned: int = Field(default=0, description="Total number of files parsed successfully")
+    files_failed: int = Field(default=0, description="Number of files that failed parsing/reading")
+    findings_count: dict[Severity, int] = Field(
+        default_factory=lambda: {s: 0 for s in Severity},
+        description="Count of findings per severity level",
+    )
+    duration_seconds: float = Field(default=0.0, description="Scan execution duration in seconds")
+
+    @property
+    def total_findings(self) -> int:
+        """Total number of findings detected across all severities."""
+        return sum(self.findings_count.values())
+
+
+class ScanResult(BaseModel):
+    """Aggregated result of a scan execution."""
+
+    findings: list[Finding] = Field(default_factory=list, description="All detected findings")
+    diagnostics: list[FileDiagnostic] = Field(
+        default_factory=list, description="Diagnostics for failed files"
+    )
+    summary: ScanSummary = Field(
+        default_factory=ScanSummary, description="Summary metrics of the scan"
+    )

pyshield/core/registry.py

@@ -0,0 +1,65 @@
+"""Rule registry for managing and querying PyShield security rules."""
+
+from collections.abc import Iterable
+
+from pyshield.rules.base import BaseRule
+from pyshield.rules.builtin import BUILTIN_RULES
+
+
+class RuleRegistry:
+    """Registry managing available PyShield security rules."""
+
+    def __init__(self) -> None:
+        self._rules: dict[str, BaseRule] = {}
+
+    def register(self, rule: BaseRule | type[BaseRule], overwrite: bool = False) -> None:
+        """Register a new rule instance or class in the registry."""
+        rule_instance = rule() if isinstance(rule, type) else rule
+        rule_id = rule_instance.rule_id
+
+        if rule_id in self._rules and not overwrite:
+            raise ValueError(f"Rule with ID '{rule_id}' is already registered.")
+
+        self._rules[rule_id] = rule_instance
+
+    def register_all(
+        self, rules: Iterable[BaseRule | type[BaseRule]], overwrite: bool = False
+    ) -> None:
+        """Register multiple rules."""
+        for r in rules:
+            self.register(r, overwrite=overwrite)
+
+    def get(self, rule_id: str) -> BaseRule | None:
+        """Retrieve a rule by its ID, or None if not found."""
+        return self._rules.get(rule_id)
+
+    def get_all(self) -> list[BaseRule]:
+        """Return all registered rule instances sorted by rule_id."""
+        return sorted(self._rules.values(), key=lambda r: r.rule_id)
+
+    def get_active(
+        self,
+        disabled_rules: set[str] | None = None,
+        enabled_rules: set[str] | None = None,
+    ) -> list[BaseRule]:
+        """Return active rules considering enabled and disabled rule sets."""
+        disabled = disabled_rules or set()
+        rules = self.get_all()
+
+        if enabled_rules is not None:
+            rules = [r for r in rules if r.rule_id in enabled_rules]
+
+        return [r for r in rules if r.rule_id not in disabled]
+
+    def __len__(self) -> int:
+        return len(self._rules)
+
+    def __contains__(self, rule_id: str) -> bool:
+        return rule_id in self._rules
+
+    @classmethod
+    def create_default(cls) -> "RuleRegistry":
+        """Instantiate a registry prepopulated with all built-in rules."""
+        registry = cls()
+        registry.register_all(BUILTIN_RULES)
+        return registry

pyshield/reporters/__init__.py

@@ -0,0 +1,5 @@
+"""PyShield reporters module."""
+
+from pyshield.reporters.terminal import TerminalReporter
+
+__all__ = ["TerminalReporter"]