agentsentinel-cli 0.3.0__py3-none-any.whl

agentsentinel_cli/mcp_report.py

@@ -0,0 +1,186 @@
+"""Rich terminal and JSON output for MCP server security scans."""
+
+import json
+
+from rich.console import Console
+from rich.panel import Panel
+from rich.table import Table
+from rich import box
+from rich.text import Text
+
+from agentsentinel_cli.mcp_rules import McpContext, McpFinding, mcp_posture_score
+
+console = Console()
+
+_SEVERITY_COLOR = {
+    "CRITICAL": "bold red",
+    "HIGH":     "bold orange1",
+    "MEDIUM":   "bold yellow",
+    "LOW":      "bold cyan",
+}
+_STATUS_COLOR = {
+    "TRUSTED":  "bold green",
+    "WATCH":    "bold yellow",
+    "ALERT":    "bold orange1",
+    "CRITICAL": "bold red",
+}
+
+
+def _status_label(score: int) -> str:
+    if score >= 80:
+        return "TRUSTED"
+    if score >= 60:
+        return "WATCH"
+    if score >= 40:
+        return "ALERT"
+    return "CRITICAL"
+
+
+def print_mcp_result(
+    ctx: McpContext,
+    findings: list[McpFinding],
+    score: int,
+    target: str,
+) -> None:
+    """Render the full MCP scan report to the terminal."""
+    server = ctx.server
+    status = _status_label(score)
+    status_color = _STATUS_COLOR[status]
+
+    console.print()
+    console.print(Panel.fit(
+        f"[bold white]AgentSentinel MCP Security Scan[/bold white]\n"
+        f"[dim]Target: {target}[/dim]",
+        border_style="bright_blue",
+        padding=(0, 2),
+    ))
+
+    auth_tag = (
+        "[bold red]✗ No auth required[/bold red]"
+        if not ctx.auth_required
+        else "[dim green]✓ Authenticated[/dim green]"
+    )
+    transport_tag = f"[dim]{server.transport.upper()}[/dim]"
+    console.print(
+        f"\n  Server   [bold white]{server.name}[/bold white] [dim]v{server.version}[/dim]\n"
+        f"  Transport {transport_tag}   Auth {auth_tag}"
+    )
+
+    if not server.tools:
+        console.print("\n  [yellow]No tools found on this server.[/yellow]")
+        _print_footer(findings, score, status_color, server.tools, ctx)
+        return
+
+    # Tools table
+    console.print()
+    table = Table(box=box.SIMPLE, show_header=True, header_style="dim", padding=(0, 1))
+    table.add_column("Tool", style="bold white", min_width=22)
+    table.add_column("Category", style="dim", width=16)
+    table.add_column("Scope", width=6)
+    table.add_column("", width=13)
+    table.add_column("Description", style="dim", max_width=52)
+
+    for tool in sorted(server.tools, key=lambda t: t.name):
+        scope_text = (
+            Text("write", style="yellow") if tool.scope == "write"
+            else Text("read", style="green")
+        )
+        danger_tag = Text("⚠ dangerous", style="bold red") if tool.is_dangerous else Text("")
+        desc = (tool.description[:50] + "…") if len(tool.description) > 52 else tool.description
+        table.add_row(tool.name, tool.category, scope_text, danger_tag, desc)
+
+    console.print(table)
+
+    # Findings
+    if findings:
+        for f in findings:
+            color = _SEVERITY_COLOR.get(f.severity, "white")
+            console.print(
+                f"  [{color}]● {f.severity:<8}[/{color}]  [bold white]{f.rule_id}[/bold white]"
+            )
+            console.print(f"  [dim]           {f.message}[/dim]")
+            if f.detail:
+                console.print(f"  [dim]           {f.detail}[/dim]")
+            console.print()
+    else:
+        console.print("  [green]✓ No security findings[/green]\n")
+
+    _print_footer(findings, score, status_color, server.tools, ctx)
+
+
+def _print_footer(
+    findings: list[McpFinding],
+    score: int,
+    status_color: str,
+    tools: list,
+    ctx: McpContext,
+) -> None:
+    status = _status_label(score)
+    bar_filled = int(score / 5)
+    bar = "█" * bar_filled + "░" * (20 - bar_filled)
+    console.print(
+        f"  Posture Score  [{status_color}]{score:>3}/100[/{status_color}]  "
+        f"[dim]{bar}[/dim]  [{status_color}]{status}[/{status_color}]"
+    )
+
+    n_critical = sum(1 for f in findings if f.severity == "CRITICAL")
+    n_high = sum(1 for f in findings if f.severity == "HIGH")
+    total = len(findings)
+
+    console.print()
+    console.rule(style="bright_blue")
+    parts = [f"[bold white]{len(tools)}[/bold white] tools enumerated"]
+    parts.append(f"[bold white]{total}[/bold white] finding{'s' if total != 1 else ''}")
+    if n_critical:
+        parts.append(f"[bold red]{n_critical} CRITICAL[/bold red]")
+    if n_high:
+        parts.append(f"[bold orange1]{n_high} HIGH[/bold orange1]")
+    console.print("  " + " · ".join(parts))
+
+    if not ctx.auth_required and any(f.rule_id == "NO_AUTH" for f in findings):
+        console.print(
+            "\n  [bold red]⚠  This server requires no authentication.[/bold red]  "
+            "[dim]Any process with network access can enumerate and invoke all tools.[/dim]"
+        )
+
+    console.print()
+
+
+def as_mcp_json(
+    ctx: McpContext,
+    findings: list[McpFinding],
+    score: int,
+    target: str,
+) -> str:
+    """Serialize MCP scan results as JSON."""
+    server = ctx.server
+    return json.dumps({
+        "target": target,
+        "transport": server.transport,
+        "server_name": server.name,
+        "server_version": server.version,
+        "auth_required": ctx.auth_required,
+        "tool_count": len(server.tools),
+        "tools": [
+            {
+                "name": t.name,
+                "description": t.description,
+                "scope": t.scope,
+                "is_dangerous": t.is_dangerous,
+                "category": t.category,
+                "has_input_schema": bool(t.input_schema.get("properties")),
+            }
+            for t in server.tools
+        ],
+        "findings": [
+            {
+                "severity": f.severity,
+                "rule_id": f.rule_id,
+                "message": f.message,
+                "detail": f.detail,
+            }
+            for f in findings
+        ],
+        "posture_score": score,
+        "status": _status_label(score),
+    }, indent=2)

agentsentinel_cli/mcp_rules.py

@@ -0,0 +1,231 @@
+"""Security rules for MCP server audits.
+
+Each rule maps to one or more OWASP LLM Top 10 categories (noted in docstrings).
+Rules operate on McpContext so they have access to both server info and scan metadata.
+"""
+
+import dataclasses
+from agentsentinel_cli.mcp_client import McpServerInfo, McpToolInfo
+
+
+@dataclasses.dataclass
+class McpContext:
+    """Full context for a single MCP scan — passed to every rule."""
+
+    server: McpServerInfo
+    auth_required: bool  # True = credentials were required/provided; False = open server
+
+
+@dataclasses.dataclass
+class McpFinding:
+    """A security finding from an MCP server audit."""
+
+    severity: str   # CRITICAL | HIGH | MEDIUM | LOW
+    rule_id: str
+    message: str
+    detail: str = ""
+
+
+# Keyword sets for exfiltration detection (aligned with posture rules in rules.py)
+_INTERNAL_READ_KW = frozenset({
+    "db", "database", "crm", "file", "filesystem",
+    "s3_read", "storage_read", "read_file",
+})
+_EXTERNAL_WRITE_KW = frozenset({
+    "email", "smtp", "webhook", "http_post", "http_external",
+    "s3_write", "send", "slack",
+})
+
+
+# ── Rules ─────────────────────────────────────────────────────────────────────
+
+def _rule_no_auth(ctx: McpContext) -> McpFinding | None:
+    """CRITICAL: HTTP server requires no credentials to enumerate tools. (OWASP LLM06)
+
+    Not applicable to stdio transport — stdio processes are isolated by the OS.
+    """
+    if ctx.server.transport == "stdio":
+        return None
+    if not ctx.auth_required and ctx.server.tools:
+        return McpFinding(
+            severity="CRITICAL",
+            rule_id="NO_AUTH",
+            message=(
+                "MCP server accepted initialize and tools/list with no credentials. "
+                "Any process with network access can enumerate and invoke all tools."
+            ),
+            detail=f"{len(ctx.server.tools)} tool(s) exposed without authentication.",
+        )
+    return None
+
+
+def _rule_unauth_dangerous(ctx: McpContext) -> McpFinding | None:
+    """CRITICAL: dangerous tools callable without auth on HTTP server. (OWASP LLM06)"""
+    if ctx.server.transport == "stdio":
+        return None
+    if ctx.auth_required:
+        return None
+    dangerous = [t.name for t in ctx.server.tools if t.is_dangerous]
+    if dangerous:
+        return McpFinding(
+            severity="CRITICAL",
+            rule_id="UNAUTH_DANGEROUS_EXEC",
+            message=(
+                "Dangerous tools are accessible without authentication. "
+                "An attacker with local network access can invoke these directly."
+            ),
+            detail=f"Unauthenticated dangerous tools: {', '.join(dangerous)}",
+        )
+    return None
+
+
+def _rule_exfiltration_path(ctx: McpContext) -> McpFinding | None:
+    """CRITICAL: internal-read + external-write tools present. (OWASP LLM02, LLM06)"""
+    names = {t.name.lower() for t in ctx.server.tools}
+    internal = [n for n in names if any(kw in n for kw in _INTERNAL_READ_KW)]
+    external = [n for n in names if any(kw in n for kw in _EXTERNAL_WRITE_KW)]
+    if internal and external:
+        return McpFinding(
+            severity="CRITICAL",
+            rule_id="EXFILTRATION_PATH",
+            message=(
+                "Server exposes both internal-read and external-write tools. "
+                "Prompt injection can chain these into a data exfiltration path."
+            ),
+            detail=f"Internal-read: {', '.join(internal)} | External-write: {', '.join(external)}",
+        )
+    return None
+
+
+def _rule_code_execution(ctx: McpContext) -> McpFinding | None:
+    """CRITICAL: server exposes code execution tools. (OWASP LLM01, LLM06)"""
+    exec_tools = [t.name for t in ctx.server.tools if t.category == "code_execution"]
+    if exec_tools:
+        return McpFinding(
+            severity="CRITICAL",
+            rule_id="CODE_EXECUTION_TOOL",
+            message=(
+                "Server exposes code-execution tools. "
+                "Prompt injection into any connected agent grants full host execution."
+            ),
+            detail=f"Execution tools: {', '.join(exec_tools)}",
+        )
+    return None
+
+
+def _rule_unbounded_input(ctx: McpContext) -> McpFinding | None:
+    """HIGH: unconstrained string inputs increase injection payload surface. (OWASP LLM01)"""
+    unvalidated: list[str] = []
+    for tool in ctx.server.tools:
+        schema = tool.input_schema
+        props = schema.get("properties", {})
+        if not props and schema.get("type") == "object":
+            unvalidated.append(f"{tool.name} (no schema)")
+            continue
+        for prop_name, prop_def in props.items():
+            if (
+                prop_def.get("type") == "string"
+                and "maxLength" not in prop_def
+                and "enum" not in prop_def
+                and "pattern" not in prop_def
+            ):
+                unvalidated.append(f"{tool.name}.{prop_name}")
+                break
+
+    if unvalidated:
+        sample = unvalidated[:5]
+        suffix = "…" if len(unvalidated) > 5 else ""
+        return McpFinding(
+            severity="HIGH",
+            rule_id="UNBOUNDED_INPUT",
+            message=(
+                "Tools accept unconstrained string inputs with no maxLength, enum, or pattern. "
+                "Injection payloads can be passed directly through tool arguments."
+            ),
+            detail=f"Unconstrained inputs: {', '.join(sample)}{suffix}",
+        )
+    return None
+
+
+def _rule_tool_sprawl(ctx: McpContext) -> McpFinding | None:
+    """MEDIUM: excessive tool count increases blast radius. (OWASP LLM06)"""
+    categories = {t.category for t in ctx.server.tools} - {"other"}
+    if len(ctx.server.tools) > 10 or len(categories) >= 5:
+        return McpFinding(
+            severity="MEDIUM",
+            rule_id="TOOL_SPRAWL",
+            message=(
+                f"Server exposes {len(ctx.server.tools)} tools across {len(categories)} categories. "
+                "Every tool is an attack surface — reduce to the minimum required."
+            ),
+            detail=f"Categories: {', '.join(sorted(categories))}",
+        )
+    return None
+
+
+def _rule_vague_descriptions(ctx: McpContext) -> McpFinding | None:
+    """MEDIUM: thin tool descriptions expand prompt injection surface. (OWASP LLM01)"""
+    vague = [t.name for t in ctx.server.tools if len(t.description.strip()) < 20]
+    if len(vague) >= 2:
+        return McpFinding(
+            severity="MEDIUM",
+            rule_id="VAGUE_TOOL_DESCRIPTIONS",
+            message=(
+                "Multiple tools have short or missing descriptions. "
+                "Vague descriptions make it easier for prompt injection to misdirect tool use."
+            ),
+            detail=f"Thin descriptions on: {', '.join(vague[:5])}{'…' if len(vague) > 5 else ''}",
+        )
+    return None
+
+
+def _rule_missing_rate_limit(ctx: McpContext) -> McpFinding | None:
+    """LOW: MCP protocol has no built-in rate limiting. (OWASP LLM06)"""
+    dangerous = [t.name for t in ctx.server.tools if t.is_dangerous]
+    if dangerous:
+        return McpFinding(
+            severity="LOW",
+            rule_id="MISSING_RATE_LIMIT",
+            message=(
+                "Dangerous tools detected. MCP has no built-in rate limiting — "
+                "ensure the server layer enforces per-client call limits."
+            ),
+            detail=f"Verify limits on: {', '.join(dangerous)}",
+        )
+    return None
+
+
+_ALL_RULES = [
+    # CRITICAL
+    _rule_no_auth,
+    _rule_unauth_dangerous,
+    _rule_exfiltration_path,
+    _rule_code_execution,
+    # HIGH
+    _rule_unbounded_input,
+    # MEDIUM
+    _rule_tool_sprawl,
+    _rule_vague_descriptions,
+    # LOW
+    _rule_missing_rate_limit,
+]
+
+_SEVERITY_WEIGHT = {"CRITICAL": 40, "HIGH": 20, "MEDIUM": 10, "LOW": 5}
+
+
+def run_mcp_rules(ctx: McpContext) -> list[McpFinding]:
+    """Run all MCP security rules and return deduplicated findings."""
+    findings: list[McpFinding] = []
+    seen: set[str] = set()
+    for rule_fn in _ALL_RULES:
+        finding = rule_fn(ctx)
+        if finding and finding.rule_id not in seen:
+            findings.append(finding)
+            seen.add(finding.rule_id)
+    return findings
+
+
+def mcp_posture_score(findings: list[McpFinding]) -> int:
+    """0–100 posture score — same deduction weights as the platform Trust Score."""
+    deductions = sum(_SEVERITY_WEIGHT.get(f.severity, 0) for f in findings)
+    return max(0, 100 - deductions)

agentsentinel_cli/report.py

@@ -0,0 +1,191 @@
+"""Terminal output and JSON report formatting."""
+
+import json
+from pathlib import Path
+
+from rich.console import Console
+from rich.panel import Panel
+from rich.table import Table
+from rich import box
+from rich.text import Text
+
+from agentsentinel_cli.scanner import AgentInfo
+from agentsentinel_cli.rules import Finding
+
+console = Console()
+
+_SEVERITY_COLOR = {
+    "CRITICAL": "bold red",
+    "HIGH":     "bold orange1",
+    "MEDIUM":   "bold yellow",
+    "LOW":      "bold cyan",
+}
+_STATUS_COLOR = {
+    "TRUSTED":  "bold green",
+    "WATCH":    "bold yellow",
+    "ALERT":    "bold orange1",
+    "CRITICAL": "bold red",
+}
+_SCOPE_STYLE = {
+    "read":  ("green", "read "),
+    "write": ("yellow", "write"),
+}
+
+
+def _status_from_score(score: int) -> str:
+    if score >= 80:
+        return "TRUSTED"
+    if score >= 60:
+        return "WATCH"
+    if score >= 40:
+        return "ALERT"
+    return "CRITICAL"
+
+
+def _severity_icon(severity: str) -> str:
+    return {"CRITICAL": "●", "HIGH": "●", "MEDIUM": "●", "LOW": "●"}.get(severity, "●")
+
+
+def print_scan_result(
+    agents: list[AgentInfo],
+    findings_map: dict[Path, list[Finding]],
+    scores_map: dict[Path, int],
+    target: Path,
+    connect_url: str | None = None,
+) -> None:
+    total_findings = sum(len(f) for f in findings_map.values())
+    total_critical = sum(1 for fl in findings_map.values() for f in fl if f.severity == "CRITICAL")
+    total_high = sum(1 for fl in findings_map.values() for f in fl if f.severity == "HIGH")
+
+    console.print()
+    console.print(Panel.fit(
+        f"[bold white]AgentSentinel Security Scan[/bold white]\n"
+        f"[dim]Target: {target}[/dim]",
+        border_style="bright_blue",
+        padding=(0, 2),
+    ))
+
+    if not agents:
+        console.print("\n[yellow]No agent tool definitions found in target.[/yellow]")
+        console.print("[dim]Tip: AgentSentinel detects @tool decorators, BaseTool subclasses, and Tool() calls.[/dim]")
+        return
+
+    for agent in agents:
+        findings = findings_map.get(agent.file, [])
+        score = scores_map.get(agent.file, 100)
+        status = _status_from_score(score)
+
+        console.print(f"\n[bold white]File:[/bold white] [dim]{agent.file}[/dim]")
+
+        # Hardcoded credentials warning (show before tools table)
+        if agent.hardcoded_creds:
+            console.print()
+            for cred in agent.hardcoded_creds:
+                console.print(f"  [bold red]⛔ HARDCODED CREDENTIAL[/bold red]  [dim]{cred}[/dim]")
+            console.print()
+
+        # Tools table
+        tools_table = Table(box=box.SIMPLE, show_header=True, header_style="dim", padding=(0, 1))
+        tools_table.add_column("Scope", style="dim", width=6)
+        tools_table.add_column("Tool", style="bold white")
+        tools_table.add_column("Category", style="dim", width=14)
+        tools_table.add_column("", width=12)
+
+        for tool in sorted(agent.tools, key=lambda t: (t.scope, t.name)):
+            scope_color, scope_label = _SCOPE_STYLE[tool.scope]
+            danger_tag = Text("⚠ dangerous", style="bold red") if tool.is_dangerous else Text("")
+            tools_table.add_row(
+                Text(scope_label, style=scope_color),
+                tool.name,
+                tool.category,
+                danger_tag,
+            )
+        console.print(tools_table)
+
+        if agent.model:
+            console.print(f"  [dim]Model:[/dim] {agent.model}")
+        if agent.description:
+            console.print(f"  [dim]Description:[/dim] {agent.description[:80]}")
+
+        # Findings
+        if findings:
+            console.print()
+            for f in findings:
+                color = _SEVERITY_COLOR.get(f.severity, "white")
+                console.print(f"  [{color}]{_severity_icon(f.severity)} {f.severity:<8}[/{color}]  "
+                               f"[bold white]{f.rule_id}[/bold white]")
+                console.print(f"  [dim]         {f.message}[/dim]")
+                if f.detail:
+                    console.print(f"  [dim]         {f.detail}[/dim]")
+                console.print()
+        else:
+            console.print("  [green]✓ No posture findings[/green]\n")
+
+        # Score bar
+        status_color = _STATUS_COLOR.get(status, "white")
+        bar_filled = int(score / 5)
+        bar = "█" * bar_filled + "░" * (20 - bar_filled)
+        console.print(
+            f"  Posture Score  [{status_color}]{score:>3}/100[/{status_color}]  "
+            f"[dim]{bar}[/dim]  [{status_color}]{status}[/{status_color}]"
+        )
+
+    # Summary footer
+    console.print()
+    console.rule(style="bright_blue")
+    summary_parts = [
+        f"[bold white]{len(agents)}[/bold white] agent{'s' if len(agents) != 1 else ''} scanned",
+        f"[bold white]{total_findings}[/bold white] finding{'s' if total_findings != 1 else ''}",
+    ]
+    if total_critical:
+        summary_parts.append(f"[bold red]{total_critical} CRITICAL[/bold red]")
+    if total_high:
+        summary_parts.append(f"[bold orange1]{total_high} HIGH[/bold orange1]")
+    console.print("  " + " · ".join(summary_parts))
+
+    if connect_url:
+        console.print(f"\n  [dim]Connected to AgentSentinel at {connect_url} — open dashboard for live behavior data.[/dim]")
+    else:
+        console.print(
+            "\n  [dim]This is a static scan. Run with [bold]--connect[/bold] to include live behavior "
+            "monitoring data from a running AgentSentinel instance.[/dim]"
+        )
+    console.print()
+
+
+def as_json(
+    agents: list[AgentInfo],
+    findings_map: dict[Path, list[Finding]],
+    scores_map: dict[Path, int],
+) -> str:
+    output = []
+    for agent in agents:
+        findings = findings_map.get(agent.file, [])
+        score = scores_map.get(agent.file, 100)
+        output.append({
+            "file": str(agent.file),
+            "model": agent.model,
+            "description": agent.description,
+            "hardcoded_credentials": agent.hardcoded_creds,
+            "tools": [
+                {
+                    "name": t.name,
+                    "scope": t.scope,
+                    "is_dangerous": t.is_dangerous,
+                    "category": t.category,
+                }
+                for t in agent.tools
+            ],
+            "findings": [
+                {
+                    "severity": f.severity,
+                    "rule_id": f.rule_id,
+                    "message": f.message,
+                    "detail": f.detail,
+                }
+                for f in findings
+            ],
+            "posture_score": score,
+            "status": _status_from_score(score),
+        })
+    return json.dumps(output, indent=2)