lucidscan 0.5.12__py3-none-any.whl

lucidscan/plugins/reporters/sarif_reporter.py

@@ -0,0 +1,303 @@
+"""SARIF reporter plugin for IDE integration.
+
+Outputs scan results in SARIF 2.1.0 format, compatible with:
+- GitHub Security tab (Code Scanning)
+- VS Code SARIF Viewer extension
+- Other SARIF-compatible tools
+"""
+
+from __future__ import annotations
+
+import json
+from typing import Any, Dict, IO, List, Optional
+
+from lucidscan.plugins.reporters.base import ReporterPlugin
+from lucidscan.core.models import ScanResult, Severity, UnifiedIssue
+
+# SARIF schema URL
+SARIF_SCHEMA = "https://json.schemastore.org/sarif-2.1.0.json"
+SARIF_VERSION = "2.1.0"
+
+# Project information
+LUCIDSCAN_INFO_URI = "https://github.com/voldeq/lucidscan"
+
+# Severity mapping to SARIF security-severity (CVSS-aligned 0.0-10.0)
+# and level (error, warning, note)
+SEVERITY_MAP: Dict[Severity, Dict[str, Any]] = {
+    Severity.CRITICAL: {"security-severity": "9.5", "level": "error"},
+    Severity.HIGH: {"security-severity": "7.5", "level": "error"},
+    Severity.MEDIUM: {"security-severity": "5.5", "level": "warning"},
+    Severity.LOW: {"security-severity": "2.5", "level": "warning"},
+    Severity.INFO: {"security-severity": "0.0", "level": "note"},
+}
+
+
+class SARIFReporter(ReporterPlugin):
+    """Reporter plugin for SARIF 2.1.0 output format.
+
+    Produces SARIF JSON suitable for upload to GitHub Code Scanning
+    or viewing in VS Code with the SARIF Viewer extension.
+    """
+
+    @property
+    def name(self) -> str:
+        return "sarif"
+
+    def report(self, result: ScanResult, output: IO[str]) -> None:
+        """Format and write the scan result as SARIF JSON.
+
+        Args:
+            result: The aggregated scan result to format.
+            output: Output stream to write the formatted result.
+        """
+        sarif_doc = self._build_sarif(result)
+        json.dump(sarif_doc, output, indent=2)
+        output.write("\n")
+
+    def _build_sarif(self, result: ScanResult) -> Dict[str, Any]:
+        """Build the complete SARIF document.
+
+        Args:
+            result: Scan result containing issues and metadata.
+
+        Returns:
+            SARIF document as a dictionary.
+        """
+        # Get lucidscan version from metadata or use default
+        version = "unknown"
+        if result.metadata:
+            version = result.metadata.lucidscan_version
+
+        # Collect unique rules from all issues
+        rules = self._collect_rules(result.issues)
+
+        # Convert issues to SARIF results
+        results = [
+            self._issue_to_result(issue)
+            for issue in result.issues
+        ]
+
+        return {
+            "$schema": SARIF_SCHEMA,
+            "version": SARIF_VERSION,
+            "runs": [
+                {
+                    "tool": {
+                        "driver": {
+                            "name": "lucidscan",
+                            "version": version,
+                            "informationUri": LUCIDSCAN_INFO_URI,
+                            "rules": rules,
+                        }
+                    },
+                    "results": results,
+                }
+            ],
+        }
+
+    def _collect_rules(self, issues: List[UnifiedIssue]) -> List[Dict[str, Any]]:
+        """Collect unique rules from issues.
+
+        Each unique rule ID becomes a SARIF rule definition.
+
+        Args:
+            issues: List of unified issues to extract rules from.
+
+        Returns:
+            List of SARIF rule definitions.
+        """
+        rules_dict: Dict[str, Dict[str, Any]] = {}
+
+        for issue in issues:
+            rule_id = self._get_rule_id(issue)
+
+            # Skip if we already have this rule
+            if rule_id in rules_dict:
+                continue
+
+            # Build rule definition
+            rule = self._build_rule(issue, rule_id)
+            rules_dict[rule_id] = rule
+
+        return list(rules_dict.values())
+
+    def _build_rule(self, issue: UnifiedIssue, rule_id: str) -> Dict[str, Any]:
+        """Build a SARIF rule definition from an issue.
+
+        Args:
+            issue: The issue to build a rule from.
+            rule_id: The rule identifier.
+
+        Returns:
+            SARIF rule definition.
+        """
+        severity_info = SEVERITY_MAP.get(issue.severity, SEVERITY_MAP[Severity.MEDIUM])
+
+        rule: Dict[str, Any] = {
+            "id": rule_id,
+            "shortDescription": {
+                "text": self._truncate(issue.title, 1024),
+            },
+            "defaultConfiguration": {
+                "level": severity_info["level"],
+            },
+            "properties": {
+                "security-severity": severity_info["security-severity"],
+            },
+        }
+
+        # Add full description if we have more detail
+        if issue.description and issue.description != issue.title:
+            rule["fullDescription"] = {
+                "text": issue.description,
+            }
+
+        # Add help URI from documentation_url or recommendation
+        if issue.documentation_url:
+            rule["helpUri"] = issue.documentation_url
+        elif issue.recommendation:
+            # Check if recommendation contains a URL
+            if issue.recommendation.startswith("http"):
+                rule["helpUri"] = issue.recommendation
+            elif "See: " in issue.recommendation:
+                # Extract URL from "See: <url>" format
+                url = issue.recommendation.replace("See: ", "").strip()
+                if url.startswith("http"):
+                    rule["helpUri"] = url
+
+        # Add CWE/OWASP tags from metadata if available
+        tool_metadata = issue.metadata
+        if tool_metadata:
+            tags = []
+            if "cwe" in tool_metadata:
+                cwe_ids = tool_metadata["cwe"]
+                if isinstance(cwe_ids, list):
+                    tags.extend(cwe_ids)
+                elif cwe_ids:
+                    tags.append(cwe_ids)
+            if "owasp" in tool_metadata:
+                owasp_ids = tool_metadata["owasp"]
+                if isinstance(owasp_ids, list):
+                    tags.extend(owasp_ids)
+                elif owasp_ids:
+                    tags.append(owasp_ids)
+            if tags:
+                rule["properties"]["tags"] = tags
+
+        return rule
+
+    def _issue_to_result(self, issue: UnifiedIssue) -> Dict[str, Any]:
+        """Convert a UnifiedIssue to a SARIF result.
+
+        Args:
+            issue: The issue to convert.
+
+        Returns:
+            SARIF result object.
+        """
+        rule_id = self._get_rule_id(issue)
+        severity_info = SEVERITY_MAP.get(issue.severity, SEVERITY_MAP[Severity.MEDIUM])
+
+        result: Dict[str, Any] = {
+            "ruleId": rule_id,
+            "message": {
+                "text": issue.description or issue.title,
+            },
+            "level": severity_info["level"],
+            "fingerprints": {
+                "v1": issue.id,
+            },
+        }
+
+        # Add location if we have file information
+        location = self._build_location(issue)
+        if location:
+            result["locations"] = [location]
+
+        return result
+
+    def _build_location(self, issue: UnifiedIssue) -> Optional[Dict[str, Any]]:
+        """Build a SARIF physical location from issue file info.
+
+        Args:
+            issue: The issue containing file location info.
+
+        Returns:
+            SARIF location object or None if no file info.
+        """
+        if not issue.file_path:
+            return None
+
+        # Use relative path for SARIF (strip leading slash if present)
+        file_uri = str(issue.file_path)
+        if file_uri.startswith("/"):
+            # Try to make it relative - just use the path as-is for now
+            # In practice, the path should already be relative or project-relative
+            pass
+
+        location: Dict[str, Any] = {
+            "physicalLocation": {
+                "artifactLocation": {
+                    "uri": file_uri,
+                },
+            }
+        }
+
+        # Add region if we have line information
+        if issue.line_start is not None:
+            region: Dict[str, Any] = {
+                "startLine": issue.line_start,
+            }
+
+            if issue.line_end is not None:
+                region["endLine"] = issue.line_end
+
+            location["physicalLocation"]["region"] = region
+
+        return location
+
+    def _get_rule_id(self, issue: UnifiedIssue) -> str:
+        """Extract or generate a rule ID for an issue.
+
+        Uses the issue's rule_id field, falling back to scanner-specific
+        identifiers in metadata if needed.
+
+        Args:
+            issue: The issue to get a rule ID from.
+
+        Returns:
+            Rule identifier string.
+        """
+        # Use the new rule_id field if available
+        if issue.rule_id:
+            return issue.rule_id
+
+        # Fallback to metadata for older scanner output formats
+        metadata = issue.metadata
+
+        # Try scanner-specific IDs from metadata
+        if "vulnerability_id" in metadata:
+            return metadata["vulnerability_id"]
+        if "rule_id" in metadata:
+            return metadata["rule_id"]
+        if "check_id" in metadata:
+            return metadata["check_id"]
+
+        # Fallback: construct from source tool and issue title
+        # Use a simplified version of the title as rule ID
+        title_slug = issue.title.split(":")[0].strip()
+        return f"{issue.source_tool}/{title_slug}"
+
+    def _truncate(self, text: str, max_length: int) -> str:
+        """Truncate text to max length with ellipsis.
+
+        Args:
+            text: Text to truncate.
+            max_length: Maximum allowed length.
+
+        Returns:
+            Truncated text.
+        """
+        if len(text) <= max_length:
+            return text
+        return text[: max_length - 3] + "..."

lucidscan/plugins/reporters/summary_reporter.py

@@ -0,0 +1,61 @@
+"""Summary reporter plugin for lucidscan."""
+
+from __future__ import annotations
+
+from typing import IO, List
+
+from lucidscan.core.models import ScanResult
+from lucidscan.plugins.reporters.base import ReporterPlugin
+
+
+class SummaryReporter(ReporterPlugin):
+    """Reporter plugin that outputs a brief scan summary.
+
+    Produces a concise summary with:
+    - Total issue count
+    - Breakdown by severity
+    - Breakdown by scanner domain
+    - Scan duration and project info
+    """
+
+    @property
+    def name(self) -> str:
+        return "summary"
+
+    def report(self, result: ScanResult, output: IO[str]) -> None:
+        """Format scan result as a summary and write to output.
+
+        Args:
+            result: The scan result to format.
+            output: Output stream to write to.
+        """
+        lines = self._format_summary(result)
+        output.write("\n".join(lines))
+        output.write("\n")
+
+    def _format_summary(self, result: ScanResult) -> List[str]:
+        """Format scan result as a brief summary."""
+        lines: List[str] = []
+
+        if result.summary:
+            lines.append(f"Total issues: {result.summary.total}")
+
+            if result.summary.by_severity:
+                lines.append("\nBy severity:")
+                for sev in ["critical", "high", "medium", "low", "info"]:
+                    count = result.summary.by_severity.get(sev, 0)
+                    if count > 0:
+                        lines.append(f"  {sev.upper()}: {count}")
+
+            if result.summary.by_scanner:
+                lines.append("\nBy scanner domain:")
+                for scanner, count in result.summary.by_scanner.items():
+                    lines.append(f"  {scanner.upper()}: {count}")
+        else:
+            lines.append("No summary available.")
+
+        if result.metadata:
+            lines.append(f"\nScan duration: {result.metadata.duration_ms}ms")
+            lines.append(f"Project: {result.metadata.project_root}")
+
+        return lines

lucidscan/plugins/reporters/table_reporter.py

@@ -0,0 +1,81 @@
+"""Table reporter plugin for lucidscan."""
+
+from __future__ import annotations
+
+from typing import IO, List
+
+from lucidscan.core.models import ScanResult, Severity
+from lucidscan.plugins.reporters.base import ReporterPlugin
+
+
+class TableReporter(ReporterPlugin):
+    """Reporter plugin that outputs scan results as a human-readable table.
+
+    Produces a formatted table suitable for terminal display with:
+    - Severity-sorted issues
+    - Truncated fields for readability
+    - Summary statistics at the bottom
+    """
+
+    @property
+    def name(self) -> str:
+        return "table"
+
+    def report(self, result: ScanResult, output: IO[str]) -> None:
+        """Format scan result as a table and write to output.
+
+        Args:
+            result: The scan result to format.
+            output: Output stream to write to.
+        """
+        lines = self._format_table(result)
+        output.write("\n".join(lines))
+        output.write("\n")
+
+    def _format_table(self, result: ScanResult) -> List[str]:
+        """Format scan result as a human-readable table."""
+        lines: List[str] = []
+
+        if not result.issues:
+            lines.append("No issues found.")
+            return lines
+
+        # Header
+        lines.append(f"{'SEVERITY':<10} {'ID':<20} {'DEPENDENCY':<40} {'TITLE'}")
+        lines.append("-" * 100)
+
+        # Sort by severity
+        severity_order = {
+            Severity.CRITICAL: 0,
+            Severity.HIGH: 1,
+            Severity.MEDIUM: 2,
+            Severity.LOW: 3,
+            Severity.INFO: 4,
+        }
+
+        sorted_issues = sorted(
+            result.issues, key=lambda x: severity_order.get(x.severity, 5)
+        )
+
+        for issue in sorted_issues:
+            sev = issue.severity.value.upper()
+            # Use rule_id first, then check metadata for vulnerability_id, fallback to issue id
+            rule_id = issue.rule_id or issue.metadata.get("vulnerability_id", issue.id)
+            rule_id = rule_id[:20]
+            dep = (issue.dependency or "")[:40]
+            title = issue.title[:60] if len(issue.title) > 60 else issue.title
+            lines.append(f"{sev:<10} {rule_id:<20} {dep:<40} {title}")
+
+        # Summary
+        lines.append("")
+        lines.append("-" * 100)
+        if result.summary:
+            lines.append(f"Total: {result.summary.total} issues")
+            sev_parts = [
+                f"{sev}: {count}"
+                for sev, count in result.summary.by_severity.items()
+            ]
+            if sev_parts:
+                lines.append(f"By severity: {', '.join(sev_parts)}")
+
+        return lines

lucidscan/plugins/scanners/__init__.py

@@ -0,0 +1,57 @@
+"""Scanner plugins for integrating external security tools.
+
+Plugins are discovered via Python entry points (lucidscan.scanners group).
+"""
+
+from pathlib import Path
+from typing import Dict, Optional, Type
+
+from lucidscan.plugins.scanners.base import ScannerPlugin
+from lucidscan.plugins.scanners.trivy import TrivyScanner
+from lucidscan.plugins.scanners.opengrep import OpenGrepScanner
+from lucidscan.plugins.scanners.checkov import CheckovScanner
+from lucidscan.plugins import SCANNER_ENTRY_POINT_GROUP
+from lucidscan.plugins.discovery import discover_plugins, get_plugin, list_available_plugins as _list_plugins
+
+
+def discover_scanner_plugins() -> Dict[str, Type[ScannerPlugin]]:
+    """Discover all installed scanner plugins via entry points."""
+    return discover_plugins(SCANNER_ENTRY_POINT_GROUP, ScannerPlugin)
+
+
+def get_scanner_plugin(
+    name: str,
+    project_root: Optional[Path] = None,
+) -> ScannerPlugin | None:
+    """Get an instantiated scanner plugin by name.
+
+    Args:
+        name: Scanner plugin name (e.g., 'trivy').
+        project_root: Optional project root for tool installation.
+                     If provided, tools are installed to {project_root}/.lucidscan/
+
+    Returns:
+        Instantiated scanner plugin or None if not found.
+    """
+    kwargs = {}
+    if project_root:
+        kwargs["project_root"] = project_root
+    return get_plugin(SCANNER_ENTRY_POINT_GROUP, name, ScannerPlugin, **kwargs)
+
+
+def list_available_scanners() -> list[str]:
+    """List names of all available scanner plugins."""
+    return _list_plugins(SCANNER_ENTRY_POINT_GROUP)
+
+
+__all__ = [
+    "ScannerPlugin",
+    "TrivyScanner",
+    "OpenGrepScanner",
+    "CheckovScanner",
+    "discover_scanner_plugins",
+    "get_scanner_plugin",
+    "list_available_scanners",
+]
+
+

lucidscan/plugins/scanners/base.py

@@ -0,0 +1,60 @@
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from pathlib import Path
+from typing import List, Optional
+
+from lucidscan.core.models import ScanContext, ScanDomain, UnifiedIssue
+
+
+class ScannerPlugin(ABC):
+    """Base class for all scanner plugins.
+
+    Each scanner plugin wraps an underlying security tool and exposes it
+    through a common interface. Plugins are self-contained and manage
+    their own binary lifecycle.
+    """
+
+    def __init__(self, project_root: Optional[Path] = None, **kwargs) -> None:
+        """Initialize the scanner plugin.
+
+        Args:
+            project_root: Optional project root for tool installation.
+            **kwargs: Additional arguments for subclasses.
+        """
+        self.project_root = project_root
+
+    @property
+    @abstractmethod
+    def name(self) -> str:
+        """Plugin identifier (e.g., 'trivy', 'opengrep')."""
+
+    @property
+    @abstractmethod
+    def domains(self) -> List[ScanDomain]:
+        """Scan domains this plugin supports (SCA, SAST, IAC, CONTAINER)."""
+
+    @abstractmethod
+    def ensure_binary(self) -> Path:
+        """Ensure the scanner binary is available, downloading if needed.
+
+        Returns:
+            Path to the scanner binary.
+        """
+
+    @abstractmethod
+    def get_version(self) -> str:
+        """Return the version of the underlying scanner."""
+
+    @abstractmethod
+    def scan(self, context: ScanContext) -> List[UnifiedIssue]:
+        """Execute scan and return normalized issues.
+
+        Args:
+            context: Scan context containing target paths and configuration.
+
+        Returns:
+            List of unified issues found during the scan.
+        """
+
+