agent-audit 0.1.0__py3-none-any.whl

agent_audit/cli/formatters/json.py

@@ -0,0 +1,138 @@
+"""JSON output formatter."""
+
+import json
+from typing import List, Dict, Any
+from pathlib import Path
+from datetime import datetime
+
+from agent_audit.models.finding import Finding
+from agent_audit.version import __version__
+
+
+class JSONFormatter:
+    """JSON output formatter for scan results."""
+
+    def __init__(self, pretty: bool = True):
+        self.pretty = pretty
+
+    def format(
+        self,
+        findings: List[Finding],
+        scan_path: str = "",
+        scanned_files: int = 0
+    ) -> Dict[str, Any]:
+        """
+        Format findings as JSON.
+
+        Args:
+            findings: List of findings to format
+            scan_path: Path that was scanned
+            scanned_files: Number of files scanned
+
+        Returns:
+            JSON-serializable dictionary
+        """
+        return {
+            "version": __version__,
+            "scan_timestamp": datetime.utcnow().isoformat(),
+            "scan_path": scan_path,
+            "scanned_files": scanned_files,
+            "summary": self._create_summary(findings),
+            "findings": [self._finding_to_dict(f) for f in findings],
+        }
+
+    def format_to_string(
+        self,
+        findings: List[Finding],
+        scan_path: str = "",
+        scanned_files: int = 0
+    ) -> str:
+        """Format findings as JSON string."""
+        data = self.format(findings, scan_path, scanned_files)
+        indent = 2 if self.pretty else None
+        return json.dumps(data, indent=indent, default=str)
+
+    def save(
+        self,
+        findings: List[Finding],
+        output_path: Path,
+        scan_path: str = "",
+        scanned_files: int = 0
+    ):
+        """Save findings as JSON file."""
+        json_str = self.format_to_string(findings, scan_path, scanned_files)
+        output_path.write_text(json_str, encoding="utf-8")
+
+    def _create_summary(self, findings: List[Finding]) -> Dict[str, Any]:
+        """Create summary statistics."""
+        total = len(findings)
+        actionable = sum(1 for f in findings if f.is_actionable())
+        suppressed = sum(1 for f in findings if f.suppressed)
+
+        by_severity = {}
+        for f in findings:
+            sev = f.severity.value
+            by_severity[sev] = by_severity.get(sev, 0) + 1
+
+        by_category = {}
+        for f in findings:
+            cat = f.category.value
+            by_category[cat] = by_category.get(cat, 0) + 1
+
+        return {
+            "total": total,
+            "actionable": actionable,
+            "suppressed": suppressed,
+            "by_severity": by_severity,
+            "by_category": by_category,
+            "risk_score": self._calculate_risk_score(findings),
+        }
+
+    def _finding_to_dict(self, finding: Finding) -> Dict[str, Any]:
+        """Convert finding to dictionary."""
+        return finding.to_dict()
+
+    def _calculate_risk_score(self, findings: List[Finding]) -> float:
+        """Calculate risk score."""
+        from agent_audit.models.risk import Severity
+
+        if not findings:
+            return 0.0
+
+        weights = {
+            Severity.CRITICAL: 3.0,
+            Severity.HIGH: 2.0,
+            Severity.MEDIUM: 1.0,
+            Severity.LOW: 0.3,
+            Severity.INFO: 0.1,
+        }
+
+        score = sum(
+            weights[f.severity] * f.confidence
+            for f in findings
+            if not f.suppressed
+        )
+
+        return min(10.0, round(score, 2))
+
+
+def format_json(
+    findings: List[Finding],
+    scan_path: str = "",
+    scanned_files: int = 0,
+    pretty: bool = True
+) -> str:
+    """Convenience function to format findings as JSON."""
+    formatter = JSONFormatter(pretty=pretty)
+    return formatter.format_to_string(findings, scan_path, scanned_files)
+
+
+def save_json(
+    findings: List[Finding],
+    output_path: Path,
+    scan_path: str = "",
+    scanned_files: int = 0
+):
+    """Convenience function to save findings as JSON."""
+    formatter = JSONFormatter()
+    formatter.save(findings, output_path, scan_path, scanned_files)

agent_audit/cli/formatters/sarif.py

@@ -0,0 +1,155 @@
+"""SARIF 2.1.0 output formatter for GitHub Code Scanning."""
+
+import json
+from typing import List, Dict, Any
+from pathlib import Path
+
+from agent_audit.models.finding import Finding
+from agent_audit.models.risk import Severity
+from agent_audit.version import __version__
+
+
+class SARIFFormatter:
+    """
+    SARIF 2.1.0 formatter for GitHub Code Scanning.
+
+    Produces SARIF-compliant JSON output that can be uploaded to
+    GitHub's code scanning feature.
+    """
+
+    SARIF_SCHEMA = "https://raw.githubusercontent.com/oasis-tcs/sarif-spec/master/Schemata/sarif-schema-2.1.0.json"
+    SARIF_VERSION = "2.1.0"
+
+    def __init__(self, tool_name: str = "agent-audit"):
+        self.tool_name = tool_name
+
+    def format(self, findings: List[Finding]) -> Dict[str, Any]:
+        """
+        Format findings as SARIF.
+
+        Args:
+            findings: List of findings to format
+
+        Returns:
+            SARIF document as dictionary
+        """
+        rules = self._extract_rules(findings)
+        results = [self._finding_to_result(f) for f in findings]
+
+        return {
+            "$schema": self.SARIF_SCHEMA,
+            "version": self.SARIF_VERSION,
+            "runs": [{
+                "tool": {
+                    "driver": {
+                        "name": self.tool_name,
+                        "version": __version__,
+                        "informationUri": "https://github.com/your-org/agent-audit",
+                        "rules": rules
+                    }
+                },
+                "results": results
+            }]
+        }
+
+    def format_to_string(self, findings: List[Finding], indent: int = 2) -> str:
+        """Format findings as SARIF JSON string."""
+        sarif = self.format(findings)
+        return json.dumps(sarif, indent=indent)
+
+    def save(self, findings: List[Finding], output_path: Path):
+        """Save findings as SARIF file."""
+        sarif_str = self.format_to_string(findings)
+        output_path.write_text(sarif_str, encoding="utf-8")
+
+    def _extract_rules(self, findings: List[Finding]) -> List[Dict[str, Any]]:
+        """Extract unique rules from findings."""
+        rules_map: Dict[str, Dict[str, Any]] = {}
+
+        for finding in findings:
+            if finding.rule_id not in rules_map:
+                rule = {
+                    "id": finding.rule_id,
+                    "name": finding.title,
+                    "shortDescription": {
+                        "text": finding.title
+                    },
+                    "fullDescription": {
+                        "text": finding.description
+                    },
+                    "defaultConfiguration": {
+                        "level": self._severity_to_level(finding.severity)
+                    },
+                    "properties": {
+                        "security-severity": self._severity_to_score(finding.severity)
+                    }
+                }
+
+                # Add help text if remediation available
+                if finding.remediation:
+                    rule["help"] = {
+                        "text": finding.remediation.description,
+                        "markdown": finding.remediation.description
+                    }
+
+                # Add CWE/OWASP tags
+                tags = []
+                if finding.cwe_id:
+                    tags.append(f"external/cwe/{finding.cwe_id.lower()}")
+                if finding.owasp_id:
+                    tags.append(f"external/owasp/{finding.owasp_id}")
+                if finding.category:
+                    tags.append(finding.category.value)
+                if tags:
+                    rule["properties"]["tags"] = tags
+
+                rules_map[finding.rule_id] = rule
+
+        return list(rules_map.values())
+
+    def _finding_to_result(self, finding: Finding) -> Dict[str, Any]:
+        """Convert a Finding to a SARIF result."""
+        result = finding.to_sarif()
+
+        # Add suppression info if suppressed
+        if finding.suppressed:
+            result["suppressions"] = [{
+                "kind": "inSource" if "noaudit" in (finding.suppressed_reason or "") else "external",
+                "justification": finding.suppressed_reason or "Suppressed by configuration"
+            }]
+
+        return result
+
+    def _severity_to_level(self, severity: Severity) -> str:
+        """Map severity to SARIF level."""
+        mapping = {
+            Severity.CRITICAL: "error",
+            Severity.HIGH: "error",
+            Severity.MEDIUM: "warning",
+            Severity.LOW: "note",
+            Severity.INFO: "none",
+        }
+        return mapping[severity]
+
+    def _severity_to_score(self, severity: Severity) -> str:
+        """Map severity to security-severity score (1.0-10.0)."""
+        mapping = {
+            Severity.CRITICAL: "9.0",
+            Severity.HIGH: "7.0",
+            Severity.MEDIUM: "5.0",
+            Severity.LOW: "3.0",
+            Severity.INFO: "1.0",
+        }
+        return mapping[severity]
+
+
+def format_sarif(findings: List[Finding]) -> str:
+    """Convenience function to format findings as SARIF."""
+    formatter = SARIFFormatter()
+    return formatter.format_to_string(findings)
+
+
+def save_sarif(findings: List[Finding], output_path: Path):
+    """Convenience function to save findings as SARIF."""
+    formatter = SARIFFormatter()
+    formatter.save(findings, output_path)

agent_audit/cli/formatters/terminal.py

@@ -0,0 +1,221 @@
+"""Terminal formatter with Rich output."""
+
+from typing import List, Dict
+from rich.console import Console
+from rich.panel import Panel
+from rich.text import Text
+
+from agent_audit.models.finding import Finding
+from agent_audit.models.risk import Severity
+
+console = Console()
+
+
+class TerminalFormatter:
+    """Rich terminal output formatter for scan results."""
+
+    SEVERITY_COLORS = {
+        Severity.CRITICAL: "red bold",
+        Severity.HIGH: "red",
+        Severity.MEDIUM: "yellow",
+        Severity.LOW: "blue",
+        Severity.INFO: "dim",
+    }
+
+    SEVERITY_ICONS = {
+        Severity.CRITICAL: "🔴",
+        Severity.HIGH: "🟠",
+        Severity.MEDIUM: "🟡",
+        Severity.LOW: "🔵",
+        Severity.INFO: "⚪",
+    }
+
+    def __init__(self, verbose: bool = False, quiet: bool = False):
+        self.verbose = verbose
+        self.quiet = quiet
+
+    def format_findings(
+        self,
+        findings: List[Finding],
+        scan_path: str,
+        scanned_files: int = 0
+    ):
+        """Format and display findings."""
+        if self.quiet and not findings:
+            return
+
+        # Header
+        self._print_header(scan_path, scanned_files, findings)
+
+        if not findings:
+            console.print("[green]✓ No security issues found![/green]")
+            return
+
+        # Group findings by severity
+        by_severity = self._group_by_severity(findings)
+
+        # Print findings by severity (highest first)
+        for severity in [Severity.CRITICAL, Severity.HIGH, Severity.MEDIUM,
+                        Severity.LOW, Severity.INFO]:
+            severity_findings = by_severity.get(severity, [])
+            if severity_findings:
+                self._print_severity_section(severity, severity_findings)
+
+        # Summary
+        self._print_summary(findings)
+
+    def _print_header(
+        self,
+        scan_path: str,
+        scanned_files: int,
+        findings: List[Finding]
+    ):
+        """Print the report header."""
+        risk_score = self._calculate_risk_score(findings)
+        risk_color = "green" if risk_score < 4 else "yellow" if risk_score < 7 else "red"
+
+        header = Text()
+        header.append("Agent Audit Security Report\n", style="bold")
+        header.append(f"Scanned: {scan_path}\n", style="dim")
+        if scanned_files:
+            header.append(f"Files analyzed: {scanned_files}\n", style="dim")
+        header.append("Risk Score: ", style="dim")
+        header.append(f"{risk_score:.1f}/10", style=f"bold {risk_color}")
+
+        console.print(Panel(header, border_style=risk_color))
+        console.print()
+
+    def _print_severity_section(
+        self,
+        severity: Severity,
+        findings: List[Finding]
+    ):
+        """Print findings for a severity level."""
+        icon = self.SEVERITY_ICONS[severity]
+        color = self.SEVERITY_COLORS[severity]
+        count = len(findings)
+
+        console.print(f"{icon} [{color}]{severity.value.upper()} ({count})[/{color}]")
+        console.print()
+
+        for finding in findings:
+            self._print_finding(finding)
+
+        console.print()
+
+    def _print_finding(self, finding: Finding):
+        """Print a single finding."""
+        color = self.SEVERITY_COLORS[finding.severity]
+
+        # Title and confidence
+        confidence_str = ""
+        if finding.confidence < 1.0:
+            confidence_str = f" (confidence: {finding.confidence:.0%})"
+
+        console.print(f"  [{color}]{finding.rule_id}[/{color}]: {finding.title}{confidence_str}")
+
+        # Location
+        loc = finding.location
+        console.print(f"    [dim]Location:[/dim] {loc.file_path}:{loc.start_line}")
+
+        # Code snippet
+        if loc.snippet:
+            console.print(f"    [dim]Code:[/dim] {loc.snippet[:80]}...")
+
+        # Remediation
+        if finding.remediation and self.verbose:
+            console.print(f"    [dim]Fix:[/dim] {finding.remediation.description[:100]}...")
+
+        console.print()
+
+    def _print_summary(self, findings: List[Finding]):
+        """Print summary table."""
+        # Count by severity
+        counts = {s: 0 for s in Severity}
+        for f in findings:
+            counts[f.severity] += 1
+
+        suppressed = sum(1 for f in findings if f.suppressed)
+
+        # Summary line
+        parts = []
+        for severity in [Severity.CRITICAL, Severity.HIGH, Severity.MEDIUM,
+                        Severity.LOW, Severity.INFO]:
+            if counts[severity] > 0:
+                color = self.SEVERITY_COLORS[severity]
+                parts.append(f"[{color}]{counts[severity]} {severity.value}[/{color}]")
+
+        console.print("━" * 50)
+        console.print(f"[bold]Findings:[/bold] {', '.join(parts)}")
+
+        if suppressed:
+            console.print(f"[dim]Suppressed: {suppressed} (configure in .agent-audit.yaml)[/dim]")
+
+        # Risk bar
+        risk_score = self._calculate_risk_score(findings)
+        self._print_risk_bar(risk_score)
+
+    def _print_risk_bar(self, risk_score: float):
+        """Print a visual risk score bar."""
+        bar_width = 30
+        filled = int((risk_score / 10) * bar_width)
+
+        if risk_score < 4:
+            color = "green"
+            label = "LOW"
+        elif risk_score < 7:
+            color = "yellow"
+            label = "MEDIUM"
+        else:
+            color = "red"
+            label = "HIGH"
+
+        bar = "█" * filled + "░" * (bar_width - filled)
+        console.print(f"[bold]Risk Score:[/bold] [{color}]{bar}[/{color}] {risk_score:.1f}/10 ({label})")
+
+    def _calculate_risk_score(self, findings: List[Finding]) -> float:
+        """Calculate overall risk score from findings."""
+        if not findings:
+            return 0.0
+
+        severity_weights = {
+            Severity.CRITICAL: 3.0,
+            Severity.HIGH: 2.0,
+            Severity.MEDIUM: 1.0,
+            Severity.LOW: 0.3,
+            Severity.INFO: 0.1,
+        }
+
+        score = sum(
+            severity_weights[f.severity] * f.confidence
+            for f in findings
+            if not f.suppressed
+        )
+
+        return min(10.0, score)
+
+    def _group_by_severity(
+        self,
+        findings: List[Finding]
+    ) -> Dict[Severity, List[Finding]]:
+        """Group findings by severity."""
+        groups: Dict[Severity, List[Finding]] = {}
+        for finding in findings:
+            if finding.suppressed and not self.verbose:
+                continue
+            if finding.severity not in groups:
+                groups[finding.severity] = []
+            groups[finding.severity].append(finding)
+        return groups
+
+
+def format_scan_results(
+    findings: List[Finding],
+    scan_path: str,
+    scanned_files: int = 0,
+    verbose: bool = False,
+    quiet: bool = False
+):
+    """Convenience function to format scan results."""
+    formatter = TerminalFormatter(verbose=verbose, quiet=quiet)
+    formatter.format_findings(findings, scan_path, scanned_files)

agent_audit/cli/main.py

@@ -0,0 +1,34 @@
+"""CLI main entry point for agent-audit."""
+
+import click
+from rich.console import Console
+
+from agent_audit.version import __version__
+
+console = Console()
+
+
+@click.group()
+@click.version_option(version=__version__)
+@click.option('--verbose', '-v', is_flag=True, help='Enable verbose output')
+@click.option('--quiet', '-q', is_flag=True, help='Only show errors')
+@click.pass_context
+def cli(ctx: click.Context, verbose: bool, quiet: bool):
+    """Agent Audit - Security scanner for AI agents and MCP configurations."""
+    ctx.ensure_object(dict)
+    ctx.obj['verbose'] = verbose
+    ctx.obj['quiet'] = quiet
+
+
+# Register commands - imports here to avoid circular imports
+from agent_audit.cli.commands.inspect import inspect  # noqa: E402
+from agent_audit.cli.commands.scan import scan  # noqa: E402
+from agent_audit.cli.commands.init import init  # noqa: E402
+
+cli.add_command(inspect)
+cli.add_command(scan)
+cli.add_command(init)
+
+
+if __name__ == '__main__':
+    cli()

agent_audit/config/__init__.py

@@ -0,0 +1 @@
+"""Configuration management for agent-audit."""