tessen-cli 0.1.0__py3-none-any.whl

tessen/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

tessen/cli.py

@@ -0,0 +1,206 @@
+"""Tessen CLI entry point."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import typer
+from rich.console import Console
+from rich.table import Table
+
+from tessen import __version__
+from tessen.output.human import render_findings, render_scan_summary
+from tessen.output.json_output import render_json
+from tessen.parsers.auto import auto_detect_and_parse
+from tessen.parsers.common import ParseError
+from tessen.parsers.claude_desktop import parse_claude_desktop
+from tessen.parsers.claude_code import parse_claude_code
+from tessen.parsers.cursor import parse_cursor
+from tessen.rules.builtin import BUILTIN_RULES
+from tessen.rules.engine import RuleEngine
+from tessen.rules.models import Finding, Severity
+
+app = typer.Typer(
+    name="tessen",
+    help="Security scanner for AI agent configurations.",
+    add_completion=False,
+    no_args_is_help=True,
+)
+console = Console()
+error_console = Console(stderr=True)
+
+
+CLIENT_LABELS = {
+    "claude_desktop": "Claude Desktop",
+    "claude_code": "Claude Code",
+    "cursor": "Cursor",
+}
+
+
+def _resolve_parser(path: Path, client: str | None):
+    if client is not None:
+        parsers = {
+            "claude_desktop": parse_claude_desktop,
+            "claude_code": parse_claude_code,
+            "cursor": parse_cursor,
+        }
+        if client not in parsers:
+            raise ParseError(
+                f"Unknown client: {client!r}. Valid options: {', '.join(parsers)}"
+            )
+        return parsers[client]
+
+    name = path.name
+    if name == ".mcp.json":
+        return parse_claude_code
+    if name == "mcp.json" and path.parent.name == ".cursor":
+        return parse_cursor
+    if name == "claude_desktop_config.json":
+        return parse_claude_desktop
+    return parse_claude_desktop
+
+
+@app.command()
+def scan(
+    path: Path | None = typer.Argument(
+        None,
+        help="Path to MCP config file. If omitted, auto-detects configs.",
+        resolve_path=True,
+    ),
+    client: str | None = typer.Option(
+        None,
+        "--client",
+        "-c",
+        help="Force a specific parser: claude_desktop, claude_code, or cursor.",
+    ),
+    output: str = typer.Option(
+        "human",
+        "--output",
+        "-o",
+        help="Output format: human (default) or json.",
+    ),
+    fail_on: str = typer.Option(
+        "high",
+        "--fail-on",
+        help="Exit non-zero if any finding at or above this severity. "
+        "One of: critical, high, medium, low, never.",
+    ),
+) -> None:
+    """Scan MCP configurations for vulnerabilities."""
+    if output not in ("human", "json"):
+        error_console.print(
+            f"[bold red]error:[/bold red] Unknown output format: {output!r}. "
+            f"Use 'human' or 'json'."
+        )
+        raise typer.Exit(code=2)
+
+    try:
+        if path is None:
+            if output == "human":
+                console.print(
+                    "[bold cyan]tessen[/bold cyan] auto-detecting MCP configs..."
+                )
+            results = auto_detect_and_parse()
+            if not results:
+                if output == "human":
+                    console.print(
+                        "[yellow]No MCP configs found.[/yellow] "
+                        "Try passing a path explicitly."
+                    )
+                else:
+                    print(render_json({}))
+                raise typer.Exit(code=0)
+        else:
+            if output == "human":
+                console.print(
+                    f"[bold cyan]tessen[/bold cyan] scanning [dim]{path}[/dim]"
+                )
+            parser_fn = _resolve_parser(path, client)
+            results = [parser_fn(path)]
+    except ParseError as e:
+        error_console.print(f"[bold red]error:[/bold red] {e}")
+        raise typer.Exit(code=1)
+
+    engine = RuleEngine(BUILTIN_RULES)
+    all_findings: list[Finding] = []
+    findings_by_source: dict[str, list[Finding]] = {}
+
+    for result in results:
+        label = CLIENT_LABELS.get(result.client_type, result.client_type)
+        source = f"{label} ({result.source_path})"
+        findings = engine.run(result)
+        findings_by_source[source] = findings
+        all_findings.extend(findings)
+
+    if output == "json":
+        print(render_json(findings_by_source))
+    else:
+        for source, findings in findings_by_source.items():
+            render_findings(console, findings, source)
+        render_scan_summary(console, all_findings)
+
+    _exit_with_severity(all_findings, fail_on)
+
+
+@app.command(name="rules")
+def list_rules() -> None:
+    """List all available detection rules."""
+    table = Table(
+        title=f"{len(BUILTIN_RULES)} detection rules",
+        title_style="bold",
+        show_lines=False,
+    )
+    table.add_column("ID", style="cyan", no_wrap=True)
+    table.add_column("Severity", no_wrap=True)
+    table.add_column("Description")
+
+    severity_styles = {
+        Severity.CRITICAL: "bold red",
+        Severity.HIGH: "bold yellow",
+        Severity.MEDIUM: "cyan",
+        Severity.LOW: "dim",
+    }
+
+    for rule in BUILTIN_RULES:
+        meta = rule.METADATA
+        style = severity_styles.get(meta.severity, "")
+        table.add_row(
+            meta.id,
+            f"[{style}]{meta.severity.value}[/{style}]",
+            meta.description[:80] + ("..." if len(meta.description) > 80 else ""),
+        )
+
+    console.print(table)
+
+
+def _exit_with_severity(findings: list[Finding], fail_on: str) -> None:
+    if fail_on == "never":
+        raise typer.Exit(code=0)
+
+    threshold_map = {
+        "critical": Severity.CRITICAL,
+        "high": Severity.HIGH,
+        "medium": Severity.MEDIUM,
+        "low": Severity.LOW,
+    }
+    if fail_on not in threshold_map:
+        error_console.print(
+            f"[bold red]error:[/bold red] Unknown --fail-on value: {fail_on!r}. "
+            f"Use one of: {', '.join(threshold_map)}, never."
+        )
+        raise typer.Exit(code=2)
+
+    threshold = threshold_map[fail_on]
+    if any(f.severity.rank >= threshold.rank for f in findings):
+        raise typer.Exit(code=1)
+    raise typer.Exit(code=0)
+
+
+@app.command()
+def version() -> None:
+    """Show Tessen version."""
+    console.print(f"tessen {__version__}")
+
+
+if __name__ == "__main__":
+    app()

tessen/models.py

@@ -0,0 +1,57 @@
+"""Data models for MCP configurations.
+
+These models represent the parsed shape of MCP config files.
+Security-relevant fields are annotated with `# SECURITY:` comments.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Literal
+
+from pydantic import BaseModel, ConfigDict, Field
+
+ClientType = Literal["claude_desktop", "claude_code", "cursor"]
+
+
+class MCPServerEntry(BaseModel):
+    """A single MCP server definition within a client config."""
+
+    model_config = ConfigDict(extra="allow")
+
+    # SECURITY: command itself can be malicious (typosquatted packages).
+    command: str
+
+    # SECURITY: arg injection, attacker-controlled paths, dangerous flags.
+    args: list[str] = Field(default_factory=list)
+
+    # SECURITY: secrets in cleartext (API keys, tokens, passwords).
+    env: dict[str, str] = Field(default_factory=dict)
+
+    # SECURITY: HTTP transport without auth = remote access risk.
+    transport: Literal["stdio", "http", "sse"] | None = None
+
+    url: str | None = None
+
+
+class MCPConfig(BaseModel):
+    """Generic MCP configuration shared across Claude Desktop, Claude Code, Cursor.
+
+    All three clients use the same `mcpServers` shape, so one model fits all.
+    """
+
+    model_config = ConfigDict(extra="allow")
+
+    mcpServers: dict[str, MCPServerEntry] = Field(default_factory=dict)
+
+
+class ParseResult(BaseModel):
+    """The output of parsing a config file."""
+
+    source_path: Path
+    client_type: ClientType
+    config: MCPConfig
+
+    @property
+    def server_count(self) -> int:
+        return len(self.config.mcpServers)

tessen/output/human.py

@@ -0,0 +1,98 @@
+"""Human-readable Rich output for findings."""
+
+from __future__ import annotations
+
+from rich.console import Console
+from rich.panel import Panel
+from rich.text import Text
+
+from tessen.rules.models import Finding, Severity
+
+
+SEVERITY_STYLES = {
+    Severity.CRITICAL: "bold red",
+    Severity.HIGH: "bold yellow",
+    Severity.MEDIUM: "cyan",
+    Severity.LOW: "dim",
+}
+
+SEVERITY_ICONS = {
+    Severity.CRITICAL: "●",
+    Severity.HIGH: "●",
+    Severity.MEDIUM: "○",
+    Severity.LOW: "○",
+}
+
+
+def render_findings(console: Console, findings: list[Finding], source: str) -> None:
+    """Render a list of findings for a single config file."""
+    if not findings:
+        console.print(f"[green]✓[/green] No findings for [dim]{source}[/dim]\n")
+        return
+
+    counts = _count_by_severity(findings)
+    header = _severity_summary(counts)
+    console.print(f"\n[bold]Findings for[/bold] [dim]{source}[/dim]  {header}\n")
+
+    for i, finding in enumerate(findings, 1):
+        _render_finding(console, i, finding)
+
+
+def render_scan_summary(console: Console, all_findings: list[Finding]) -> None:
+    """Render a summary across all scanned configs."""
+    if not all_findings:
+        console.print("\n[bold green]All configs clean — no findings.[/bold green]")
+        return
+
+    counts = _count_by_severity(all_findings)
+    console.print("\n[bold]Scan summary[/bold]")
+    console.print(f"  Total findings: {len(all_findings)}")
+    for sev in [Severity.CRITICAL, Severity.HIGH, Severity.MEDIUM, Severity.LOW]:
+        if counts[sev] > 0:
+            style = SEVERITY_STYLES[sev]
+            console.print(f"  [{style}]{sev.value.title():<9}[/{style}] {counts[sev]}")
+
+
+def _render_finding(console: Console, index: int, finding: Finding) -> None:
+    style = SEVERITY_STYLES[finding.severity]
+    icon = SEVERITY_ICONS[finding.severity]
+
+    title = Text()
+    title.append(f"{icon} ", style=style)
+    title.append(f"[{finding.severity.value.upper()}] ", style=style)
+    title.append(finding.title, style="bold")
+
+    body = Text()
+    body.append(finding.message + "\n\n")
+    body.append("Location:    ", style="dim")
+    body.append(finding.location + "\n", style="cyan")
+    body.append("Rule:        ", style="dim")
+    body.append(finding.rule_id + "\n", style="magenta")
+    if finding.remediation:
+        body.append("Remediation: ", style="dim")
+        body.append(finding.remediation + "\n", style="green")
+
+    panel = Panel(
+        body,
+        title=title,
+        title_align="left",
+        border_style=style,
+        padding=(0, 1),
+    )
+    console.print(panel)
+
+
+def _count_by_severity(findings: list[Finding]) -> dict[Severity, int]:
+    counts = {sev: 0 for sev in Severity}
+    for f in findings:
+        counts[f.severity] += 1
+    return counts
+
+
+def _severity_summary(counts: dict[Severity, int]) -> str:
+    parts = []
+    for sev in [Severity.CRITICAL, Severity.HIGH, Severity.MEDIUM, Severity.LOW]:
+        if counts[sev] > 0:
+            style = SEVERITY_STYLES[sev]
+            parts.append(f"[{style}]{counts[sev]} {sev.value}[/{style}]")
+    return " · ".join(parts)

tessen/output/json_output.py

@@ -0,0 +1,68 @@
+"""Machine-readable JSON output for findings."""
+
+from __future__ import annotations
+
+import json
+
+from tessen import __version__
+from tessen.rules.models import Finding
+
+
+def render_json(
+    findings_by_source: dict[str, list[Finding]],
+    file=None,
+) -> str:
+    """Render all findings as a JSON document.
+
+    Returns the JSON string and optionally writes it to a file handle.
+    """
+    output = {
+        "version": __version__,
+        "scanner": "tessen",
+        "summary": {
+            "total": sum(len(f) for f in findings_by_source.values()),
+            "by_severity": _count_severities(findings_by_source),
+            "configs_scanned": len(findings_by_source),
+        },
+        "results": [
+            {
+                "source": source,
+                "findings": [_finding_to_dict(f) for f in findings],
+            }
+            for source, findings in findings_by_source.items()
+        ],
+    }
+
+    json_str = json.dumps(output, indent=2, default=str)
+
+    if file is not None:
+        file.write(json_str)
+
+    return json_str
+
+
+def _finding_to_dict(finding: Finding) -> dict:
+    return {
+        "rule_id": finding.rule_id,
+        "severity": finding.severity.value,
+        "title": finding.title,
+        "message": finding.message,
+        "location": finding.location,
+        "remediation": finding.remediation,
+        "references": finding.references,
+    }
+
+
+def _count_severities(
+    findings_by_source: dict[str, list[Finding]],
+) -> dict[str, int]:
+    counts: dict[str, int] = {
+        "critical": 0,
+        "high": 0,
+        "medium": 0,
+        "low": 0,
+    }
+    for findings in findings_by_source.values():
+        for f in findings:
+            counts[f.severity.value] += 1
+    return counts

tessen/parsers/auto.py

@@ -0,0 +1,77 @@
+"""Auto-detect which MCP client config to scan.
+
+Walks up from the current directory looking for project-scoped configs,
+then falls back to user-scoped configs in standard locations.
+"""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+from tessen.parsers.claude_code import find_claude_code_config, parse_claude_code
+from tessen.parsers.claude_desktop import parse_claude_desktop
+from tessen.parsers.cursor import find_cursor_config, parse_cursor
+from tessen.models import ParseResult
+
+
+def find_claude_desktop_config() -> Path | None:
+    """Find the user-scoped Claude Desktop config based on the OS."""
+    home = Path.home()
+    if sys.platform == "darwin":
+        candidate = (
+            home
+            / "Library"
+            / "Application Support"
+            / "Claude"
+            / "claude_desktop_config.json"
+        )
+    elif sys.platform == "win32":
+        import os
+
+        appdata = os.environ.get("APPDATA")
+        if not appdata:
+            return None
+        candidate = Path(appdata) / "Claude" / "claude_desktop_config.json"
+    else:  # linux and friends
+        candidate = home / ".config" / "Claude" / "claude_desktop_config.json"
+    return candidate if candidate.is_file() else None
+
+
+def auto_detect_and_parse(start: Path | None = None) -> list[ParseResult]:
+    """Find all MCP configs reachable from `start` and parse them.
+
+    Searches in this order:
+      1. Project-scoped Claude Code (.mcp.json, walking up from start)
+      2. Project-scoped Cursor (.cursor/mcp.json, walking up from start)
+      3. User-scoped Claude Desktop (OS-specific location)
+
+    Returns a list of ParseResults for everything found. Empty list if
+    nothing was found. Individual parse errors propagate (we don't silently
+    skip malformed configs).
+
+    Args:
+        start: Directory to begin the project-scoped search from.
+            Defaults to current working directory.
+    """
+    if start is None:
+        start = Path.cwd()
+
+    results: list[ParseResult] = []
+
+    claude_code_path = find_claude_code_config(start)
+    if claude_code_path is not None:
+        results.append(parse_claude_code(claude_code_path))
+
+    cursor_path = find_cursor_config(start)
+    if cursor_path is not None:
+        results.append(parse_cursor(cursor_path))
+
+    desktop_path = find_claude_desktop_config()
+    if desktop_path is not None:
+        results.append(parse_claude_desktop(desktop_path))
+
+    return results
+
+
+__all__ = ["auto_detect_and_parse", "find_claude_desktop_config"]

tessen/parsers/claude_code.py

@@ -0,0 +1,42 @@
+"""Parser for Claude Code MCP configurations.
+
+Config locations:
+  - Project-scoped: <project_root>/.mcp.json
+  - User-scoped:    ~/.claude.json (contains both user settings and MCP servers)
+
+For V1 we focus on .mcp.json (project-scoped) — the most common case
+for security audits.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from tessen.parsers.common import ParseError, parse_mcp_json_file
+from tessen.models import ParseResult
+
+
+PROJECT_CONFIG_NAME = ".mcp.json"
+
+
+def parse_claude_code(path: Path) -> ParseResult:
+    """Parse a Claude Code .mcp.json file."""
+    return parse_mcp_json_file(path, client_type="claude_code")
+
+
+def find_claude_code_config(start: Path) -> Path | None:
+    """Walk up from `start` looking for a .mcp.json file.
+
+    Returns the path if found, None otherwise. Used by auto-detection.
+    """
+    current = start.resolve()
+    while True:
+        candidate = current / PROJECT_CONFIG_NAME
+        if candidate.is_file():
+            return candidate
+        if current.parent == current:  # reached filesystem root
+            return None
+        current = current.parent
+
+
+__all__ = ["parse_claude_code", "find_claude_code_config", "ParseError"]

tessen/parsers/claude_desktop.py

@@ -0,0 +1,22 @@
+"""Parser for Claude Desktop MCP configurations.
+
+Config locations:
+  - macOS:   ~/Library/Application Support/Claude/claude_desktop_config.json
+  - Linux:   ~/.config/Claude/claude_desktop_config.json
+  - Windows: %APPDATA%\\Claude\\claude_desktop_config.json
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from tessen.parsers.common import ParseError, parse_mcp_json_file
+from tessen.models import ParseResult
+
+
+def parse_claude_desktop(path: Path) -> ParseResult:
+    """Parse a Claude Desktop config file."""
+    return parse_mcp_json_file(path, client_type="claude_desktop")
+
+
+__all__ = ["parse_claude_desktop", "ParseError"]

tessen/parsers/common.py

@@ -0,0 +1,66 @@
+"""Shared parsing logic across MCP-format clients.
+
+Claude Desktop, Claude Code, and Cursor all use the same JSON shape
+under different filenames. This module holds the actual parsing work.
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import get_args
+
+from pydantic import ValidationError
+
+from tessen.models import ClientType, MCPConfig, ParseResult
+
+
+class ParseError(Exception):
+    """Raised when a config file cannot be parsed."""
+
+
+def parse_mcp_json_file(path: Path, *, client_type: ClientType) -> ParseResult:
+    """Parse a JSON file using the standard MCP config schema.
+
+    Args:
+        path: Path to the config file.
+        client_type: Which client the file came from. Affects rules later.
+
+    Returns:
+        ParseResult containing the parsed config and metadata.
+
+    Raises:
+        ParseError: If the file doesn't exist, isn't valid JSON, or doesn't
+            match the expected schema.
+    """
+    if client_type not in get_args(ClientType):
+        raise ValueError(f"Unknown client_type: {client_type!r}")
+
+    if not path.exists():
+        raise ParseError(f"Config file not found: {path}")
+
+    if not path.is_file():
+        raise ParseError(f"Path is not a file: {path}")
+
+    try:
+        raw_text = path.read_text(encoding="utf-8")
+    except OSError as e:
+        raise ParseError(f"Could not read {path}: {e}") from e
+
+    try:
+        raw_json = json.loads(raw_text)
+    except json.JSONDecodeError as e:
+        raise ParseError(
+            f"Invalid JSON in {path} at line {e.lineno}, col {e.colno}: {e.msg}"
+        ) from e
+
+    try:
+        config = MCPConfig.model_validate(raw_json)
+    except ValidationError as e:
+        raise ParseError(f"Config schema validation failed for {path}:\n{e}") from e
+
+    return ParseResult(
+        source_path=path,
+        client_type=client_type,
+        config=config,
+    )

tessen/parsers/cursor.py

@@ -0,0 +1,38 @@
+"""Parser for Cursor MCP configurations.
+
+Config locations:
+  - Project-scoped: <project_root>/.cursor/mcp.json
+  - Global:         ~/.cursor/mcp.json
+
+Cursor uses the same schema as Claude Desktop, just at a different path.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from tessen.parsers.common import ParseError, parse_mcp_json_file
+from tessen.models import ParseResult
+
+
+PROJECT_CONFIG_PATH = Path(".cursor") / "mcp.json"
+
+
+def parse_cursor(path: Path) -> ParseResult:
+    """Parse a Cursor MCP config file."""
+    return parse_mcp_json_file(path, client_type="cursor")
+
+
+def find_cursor_config(start: Path) -> Path | None:
+    """Walk up from `start` looking for a .cursor/mcp.json file."""
+    current = start.resolve()
+    while True:
+        candidate = current / PROJECT_CONFIG_PATH
+        if candidate.is_file():
+            return candidate
+        if current.parent == current:
+            return None
+        current = current.parent
+
+
+__all__ = ["parse_cursor", "find_cursor_config", "ParseError"]