aevrin 0.1.0__tar.gz

aevrin-0.1.0/.gitignore

@@ -0,0 +1,45 @@
+# Secrets — never commit
+.env
+.env.*
+!.env.example
+env.txt
+infra/defectdojo/secrets.generated.md
+*.pem
+*.key
+
+# Node
+node_modules/
+.next/
+out/
+dist/
+build/
+.turbo/
+npm-debug.log*
+yarn-error.log*
+
+# Python
+__pycache__/
+*.pyc
+.venv/
+venv/
+*.egg-info/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.uv-cache/
+
+# OS / editor
+.DS_Store
+.vscode/*
+!.vscode/extensions.json
+*.swp
+
+# Playwright
+test-results/
+playwright-report/
+blob-report/
+.playwright-mcp/
+
+# Misc
+*.log
+.cache/

aevrin-0.1.0/.python-version

@@ -0,0 +1 @@
+3.11

aevrin-0.1.0/PKG-INFO

@@ -0,0 +1,86 @@
+Metadata-Version: 2.4
+Name: aevrin
+Version: 0.1.0
+Summary: Aevrin MCP Security Scanner CLI — scan a GitHub repo, local path, or live MCP server.
+Project-URL: Homepage, https://github.com/aevrin-projects/aevrin-mcp-scanner
+Project-URL: Repository, https://github.com/aevrin-projects/aevrin-mcp-scanner
+Author: Aevrin
+License-Expression: MIT
+Keywords: mcp,model-context-protocol,scanner,security
+Requires-Python: >=3.11
+Requires-Dist: aevrin-scanner-core>=0.1.0
+Requires-Dist: httpx>=0.27
+Requires-Dist: rich>=13.9
+Requires-Dist: typer>=0.15
+Description-Content-Type: text/markdown
+
+# aevrin
+
+Aevrin MCP Security Scanner CLI. Wraps the same open-source scanner binaries and normalization logic (`aevrin-scanner-core`) that the Aevrin backend uses, run locally against your own machine — no network call required unless you pass `--upload`.
+
+## Install
+
+```bash
+pip install aevrin
+```
+
+Requires Docker (each scanner runs in its own disposable container — see the main repo README for why).
+
+## Usage
+
+```bash
+aevrin scan ./my-mcp-server
+aevrin scan github.com/owner/repo
+aevrin scan https://my-live-server.example.com --json
+aevrin scan ./my-mcp-server --fail-on high
+aevrin scan ./my-mcp-server --upload   # requires AEVRIN_API_KEY env var
+```
+
+Target type is auto-detected: a `github.com` URL scans the full pipeline (static analysis, secrets, dependencies, tool-description checks); any other `http(s)://` URL is treated as a live MCP server (manifest-level checks only); anything that exists on disk is scanned as a local path (full pipeline, no cloning).
+
+### Flags
+
+| Flag | Behavior |
+|---|---|
+| `--json` | Machine-readable JSON on stdout instead of a formatted table. |
+| `--upload` | Pushes the result to your Aevrin account. Requires `AEVRIN_API_KEY`, set from your account's API keys settings page — never required for a local-only scan. |
+| `--fail-on <severity>` | Minimum severity that causes a non-zero exit code. One of `critical`, `high`, `medium`, `low`, `info`. Defaults to `high` (both `critical` and `high` findings fail the build). |
+
+### Exit codes
+
+| Code | Meaning |
+|---|---|
+| `0` | Clean — no findings at or above the `--fail-on` threshold. |
+| `1` | Findings at or above the `--fail-on` threshold were found. |
+| `2` | Misuse — bad arguments, a target that couldn't be resolved, every scan stage failed to run, or `--upload` failed. |
+
+Results go to stdout; stage progress and diagnostics go to stderr — safe to pipe `--json` output without stage-progress noise mixed in.
+
+### Example output
+
+```
+[✓] static analysis
+[✓] secrets
+[✓] dependencies
+[✓] tool description check
+[✓] aggregating
+
+Target: ./my-mcp-server
+Score:  62/100  Significant risk — do not deploy as-is
+
+┏━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━┓
+┃ Severity ┃ Title                ┃ OWASP category                      ┃ Tool    ┃
+┡━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━┩
+│ CRITICAL │ Hardcoded secret     │ MCP01: Token Mismanagement          │ trivy   │
+│ HIGH     │ subprocess shell true│ MCP05: Command Injection, ...       │ semgrep │
+└──────────┴──────────────────────┴──────────────────────────────────────┴─────────┘
+```
+
+## Development
+
+```bash
+uv sync
+uv run pytest tests -v
+uv run ruff check .
+uv run mypy src
+```

aevrin-0.1.0/README.md

@@ -0,0 +1,70 @@
+# aevrin
+
+Aevrin MCP Security Scanner CLI. Wraps the same open-source scanner binaries and normalization logic (`aevrin-scanner-core`) that the Aevrin backend uses, run locally against your own machine — no network call required unless you pass `--upload`.
+
+## Install
+
+```bash
+pip install aevrin
+```
+
+Requires Docker (each scanner runs in its own disposable container — see the main repo README for why).
+
+## Usage
+
+```bash
+aevrin scan ./my-mcp-server
+aevrin scan github.com/owner/repo
+aevrin scan https://my-live-server.example.com --json
+aevrin scan ./my-mcp-server --fail-on high
+aevrin scan ./my-mcp-server --upload   # requires AEVRIN_API_KEY env var
+```
+
+Target type is auto-detected: a `github.com` URL scans the full pipeline (static analysis, secrets, dependencies, tool-description checks); any other `http(s)://` URL is treated as a live MCP server (manifest-level checks only); anything that exists on disk is scanned as a local path (full pipeline, no cloning).
+
+### Flags
+
+| Flag | Behavior |
+|---|---|
+| `--json` | Machine-readable JSON on stdout instead of a formatted table. |
+| `--upload` | Pushes the result to your Aevrin account. Requires `AEVRIN_API_KEY`, set from your account's API keys settings page — never required for a local-only scan. |
+| `--fail-on <severity>` | Minimum severity that causes a non-zero exit code. One of `critical`, `high`, `medium`, `low`, `info`. Defaults to `high` (both `critical` and `high` findings fail the build). |
+
+### Exit codes
+
+| Code | Meaning |
+|---|---|
+| `0` | Clean — no findings at or above the `--fail-on` threshold. |
+| `1` | Findings at or above the `--fail-on` threshold were found. |
+| `2` | Misuse — bad arguments, a target that couldn't be resolved, every scan stage failed to run, or `--upload` failed. |
+
+Results go to stdout; stage progress and diagnostics go to stderr — safe to pipe `--json` output without stage-progress noise mixed in.
+
+### Example output
+
+```
+[✓] static analysis
+[✓] secrets
+[✓] dependencies
+[✓] tool description check
+[✓] aggregating
+
+Target: ./my-mcp-server
+Score:  62/100  Significant risk — do not deploy as-is
+
+┏━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━┓
+┃ Severity ┃ Title                ┃ OWASP category                      ┃ Tool    ┃
+┡━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━┩
+│ CRITICAL │ Hardcoded secret     │ MCP01: Token Mismanagement          │ trivy   │
+│ HIGH     │ subprocess shell true│ MCP05: Command Injection, ...       │ semgrep │
+└──────────┴──────────────────────┴──────────────────────────────────────┴─────────┘
+```
+
+## Development
+
+```bash
+uv sync
+uv run pytest tests -v
+uv run ruff check .
+uv run mypy src
+```

aevrin-0.1.0/pyproject.toml

@@ -0,0 +1,47 @@
+[project]
+name = "aevrin"
+version = "0.1.0"
+description = "Aevrin MCP Security Scanner CLI — scan a GitHub repo, local path, or live MCP server."
+readme = "README.md"
+requires-python = ">=3.11"
+license = "MIT"
+authors = [{ name = "Aevrin" }]
+keywords = ["mcp", "security", "scanner", "model-context-protocol"]
+dependencies = [
+    "aevrin-scanner-core>=0.1.0",
+    "typer>=0.15",
+    "rich>=13.9",
+    "httpx>=0.27",
+]
+
+[project.scripts]
+aevrin = "aevrin_cli.main:app"
+
+[project.urls]
+Homepage = "https://github.com/aevrin-projects/aevrin-mcp-scanner"
+Repository = "https://github.com/aevrin-projects/aevrin-mcp-scanner"
+
+[dependency-groups]
+dev = [
+    "pytest>=8.3",
+    "ruff>=0.7",
+    "mypy>=1.13",
+]
+
+[tool.uv.sources]
+aevrin-scanner-core = { path = "../scanner-core", editable = true }
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/aevrin_cli"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py311"
+
+[tool.mypy]
+python_version = "3.11"
+strict = true

aevrin-0.1.0/src/aevrin_cli/main.py

@@ -0,0 +1,116 @@
+from __future__ import annotations
+
+import os
+from typing import Annotated
+from uuid import uuid4
+
+import typer
+from aevrin_scanner_core import Finding, ScanStage, Severity, StageStatus
+from aevrin_scanner_core.pipeline import PipelineConfig, run_pipeline
+
+from . import output
+from .target_detection import TargetDetectionError, detect_target
+from .upload import UploadError, upload_scan
+
+app = typer.Typer(
+    name="aevrin",
+    help="Scan MCP servers for vulnerabilities using established open-source security tools.",
+    no_args_is_help=True,
+)
+
+_SEVERITY_RANK: dict[Severity, int] = {
+    Severity.INFO: 0,
+    Severity.LOW: 1,
+    Severity.MEDIUM: 2,
+    Severity.HIGH: 3,
+    Severity.CRITICAL: 4,
+}
+
+
+@app.command()
+def scan(
+    target: Annotated[str, typer.Argument(help="GitHub URL, local path, or live MCP server URL.")],
+    json_output: Annotated[bool, typer.Option("--json", help="Machine-readable JSON output.")] = False,
+    upload: Annotated[
+        bool, typer.Option("--upload", help="Upload results to your Aevrin account (requires AEVRIN_API_KEY).")
+    ] = False,
+    fail_on: Annotated[
+        str, typer.Option("--fail-on", help="Minimum severity that causes a non-zero exit code.")
+    ] = "high",
+) -> None:
+    """Run the full Aevrin scan pipeline against TARGET."""
+    try:
+        fail_on_severity = Severity(fail_on.lower())
+    except ValueError:
+        output.print_error(
+            f"Invalid --fail-on value '{fail_on}'. Expected one of: "
+            f"{', '.join(s.value for s in Severity)}."
+        )
+        raise typer.Exit(code=2) from None
+
+    try:
+        target_type, normalized_target = detect_target(target)
+    except TargetDetectionError as exc:
+        output.print_error(str(exc))
+        raise typer.Exit(code=2) from None
+
+    config = PipelineConfig(github_token=os.environ.get("GITHUB_TOKEN"))
+
+    def on_stage(stage: ScanStage) -> None:
+        if not json_output:
+            output.print_stage_update(stage.name.value, stage.status.value, stage.error)
+
+    def on_findings(findings: list[Finding]) -> None:
+        pass  # collected on the returned Scan object; nothing to stream for the CLI
+
+    result = run_pipeline(
+        target_type=target_type,
+        target=normalized_target,
+        config=config,
+        on_stage=on_stage,
+        on_findings=on_findings,
+        scan_id=uuid4(),
+    )
+
+    if json_output:
+        output.print_json_report(result)
+    else:
+        output.print_terminal_report(result)
+
+    if upload:
+        try:
+            upload_scan(result)
+            if not json_output:
+                output.stderr_console.print("[green]Uploaded to your Aevrin account.[/green]")
+        except UploadError as exc:
+            output.print_error(str(exc))
+            raise typer.Exit(code=2) from None
+
+    all_stages_failed = result.stages and all(s.status == StageStatus.FAILED for s in result.stages)
+    if all_stages_failed:
+        raise typer.Exit(code=2)
+
+    worst = max(
+        (f.severity for f in result.findings if not f.not_tested),
+        key=lambda s: _SEVERITY_RANK[s],
+        default=None,
+    )
+    if worst is not None and _SEVERITY_RANK[worst] >= _SEVERITY_RANK[fail_on_severity]:
+        raise typer.Exit(code=1)
+    raise typer.Exit(code=0)
+
+
+@app.command()
+def version() -> None:
+    """Print the installed aevrin CLI version."""
+    from importlib.metadata import version as pkg_version
+
+    typer.echo(pkg_version("aevrin"))
+
+
+def main() -> None:
+    app()
+
+
+if __name__ == "__main__":
+    main()

aevrin-0.1.0/src/aevrin_cli/output.py

@@ -0,0 +1,100 @@
+"""Terminal + JSON rendering. Severity colors match the website's dedicated
+severity tokens (critical/high/medium/low get distinct, consistent colors
+used nowhere else), approximated in the 256-color terminal palette.
+"""
+
+from __future__ import annotations
+
+import json
+from typing import Any
+
+from aevrin_scanner_core import Scan, Severity, category_label, verdict
+from rich.console import Console
+from rich.table import Table
+
+stdout_console = Console()
+stderr_console = Console(stderr=True)
+
+_SEVERITY_STYLE: dict[Severity, str] = {
+    Severity.CRITICAL: "bold red",
+    Severity.HIGH: "bold dark_orange",
+    Severity.MEDIUM: "bold yellow",
+    Severity.LOW: "bold blue",
+    Severity.INFO: "dim",
+}
+
+
+def print_stage_update(name: str, status: str, error: str | None = None) -> None:
+    icon = {"running": "…", "done": "✓", "failed": "✗", "skipped": "–"}.get(status, "?")
+    line = f"[dim]\\[{icon}][/dim] {name.replace('_', ' ')}"
+    if error:
+        line += f" [red]({error})[/red]"
+    stderr_console.print(line)
+
+
+def print_terminal_report(scan: Scan) -> None:
+    stdout_console.print()
+    stdout_console.print(f"[bold]Target:[/bold] {scan.target}")
+    score = scan.score if scan.score is not None else 0
+    score_style = "bold green" if score >= 90 else "bold yellow" if score >= 40 else "bold red"
+    stdout_console.print(f"[bold]Score:[/bold]  [{score_style}]{score}/100[/{score_style}]  {verdict(score)}")
+    stdout_console.print()
+
+    real_findings = [f for f in scan.findings if not f.not_tested]
+    not_tested = [f for f in scan.findings if f.not_tested]
+
+    if not real_findings:
+        stdout_console.print("[green]No findings — clean scan.[/green]")
+    else:
+        table = Table(show_lines=False)
+        table.add_column("Severity")
+        table.add_column("Title")
+        table.add_column("OWASP category")
+        table.add_column("Tool")
+        for f in sorted(real_findings, key=lambda f: list(Severity).index(f.severity)):
+            style = _SEVERITY_STYLE[f.severity]
+            table.add_row(
+                f"[{style}]{f.severity.value.upper()}[/{style}]",
+                f.title,
+                category_label(f.owasp_category),
+                f.tool.value,
+            )
+        stdout_console.print(table)
+
+    for f in not_tested:
+        stdout_console.print()
+        stdout_console.print(f"[dim]Note: {f.description}[/dim]")
+
+
+def print_json_report(scan: Scan) -> None:
+    payload: dict[str, Any] = {
+        "target": scan.target,
+        "target_type": scan.target_type.value,
+        "status": scan.status.value,
+        "score": scan.score,
+        "verdict": verdict(scan.score) if scan.score is not None else None,
+        "findings": [
+            {
+                "id": str(f.id),
+                "tool": f.tool.value,
+                "owasp_category": f.owasp_category.value,
+                "owasp_category_label": category_label(f.owasp_category),
+                "severity": f.severity.value,
+                "title": f.title,
+                "description": f.description,
+                "file_path": f.location.file_path,
+                "line_start": f.location.line_start,
+                "line_end": f.location.line_end,
+                "manifest_field": f.location.manifest_field,
+                "remediation": f.remediation,
+                "verified": f.verified,
+                "not_tested": f.not_tested,
+            }
+            for f in scan.findings
+        ],
+    }
+    print(json.dumps(payload, indent=2))
+
+
+def print_error(message: str) -> None:
+    stderr_console.print(f"[bold red]Error:[/bold red] {message}")

aevrin-0.1.0/src/aevrin_cli/target_detection.py

@@ -0,0 +1,46 @@
+"""Auto-detects whether a CLI target is a GitHub URL, a local path, or a
+live MCP server URL — the three modes Section 7 of the spec lists for
+`aevrin scan <target>`. Website Screen 1's fourth mode (paste config) is a
+browser-only affordance, not something the CLI needs to detect from a
+single string argument.
+"""
+
+from __future__ import annotations
+
+import os
+
+from aevrin_scanner_core import TargetType
+
+
+class TargetDetectionError(Exception):
+    pass
+
+
+def detect_target(raw: str) -> tuple[TargetType, str]:
+    """Returns (target_type, normalized_target)."""
+    target = raw.strip()
+    if not target:
+        raise TargetDetectionError("Target must not be empty.")
+
+    if target.startswith(("http://", "https://")):
+        host = target.split("://", 1)[1].split("/", 1)[0]
+        if host in ("github.com", "www.github.com"):
+            return TargetType.GITHUB_REPO, _normalize_github_url(target)
+        return TargetType.LIVE_MCP_SERVER, target
+
+    if target.startswith("github.com/"):
+        return TargetType.GITHUB_REPO, _normalize_github_url(f"https://{target}")
+
+    if os.path.exists(target):
+        return TargetType.LOCAL_PATH, os.path.abspath(target)
+
+    raise TargetDetectionError(
+        f"Could not determine target type for '{raw}'. Expected a GitHub URL "
+        "(https://github.com/owner/repo), a live server URL (https://...), "
+        "or a local path that exists on disk."
+    )
+
+
+def _normalize_github_url(url: str) -> str:
+    normalized = url.replace("://www.github.com", "://github.com")
+    return normalized.removesuffix("/").removesuffix(".git")

aevrin-0.1.0/src/aevrin_cli/upload.py

@@ -0,0 +1,66 @@
+from __future__ import annotations
+
+import os
+
+import httpx
+from aevrin_scanner_core import Scan
+
+DEFAULT_API_URL = "https://api.aevrin.dev"
+
+
+class UploadError(Exception):
+    pass
+
+
+def upload_scan(scan: Scan) -> None:
+    api_key = os.environ.get("AEVRIN_API_KEY")
+    if not api_key:
+        raise UploadError(
+            "--upload requires AEVRIN_API_KEY. Get one from your account settings "
+            "(Aevrin dashboard → API keys) and set it in your environment."
+        )
+    api_url = os.environ.get("AEVRIN_API_URL", DEFAULT_API_URL)
+
+    body = {
+        "target_type": scan.target_type.value,
+        "target": scan.target,
+        "score": scan.score if scan.score is not None else 0,
+        "findings": [
+            {
+                "id": str(f.id),
+                "tool": f.tool.value,
+                "owasp_category": f.owasp_category.value,
+                "severity": f.severity.value,
+                "title": f.title,
+                "description": f.description,
+                "file_path": f.location.file_path,
+                "line_start": f.location.line_start,
+                "line_end": f.location.line_end,
+                "manifest_field": f.location.manifest_field,
+                "tool_name_in_manifest": f.location.tool_name_in_manifest,
+                "remediation": f.remediation,
+                "verified": f.verified,
+                "not_tested": f.not_tested,
+                "raw": None,  # don't upload raw tool output — keep the payload small and predictable
+            }
+            for f in scan.findings
+        ],
+    }
+
+    try:
+        resp = httpx.post(
+            f"{api_url}/cli/upload",
+            json=body,
+            headers={"X-API-Key": api_key},
+            timeout=30,
+        )
+    except httpx.HTTPError as exc:
+        raise UploadError(f"Could not reach {api_url}: {exc}") from exc
+
+    if resp.status_code >= 400:
+        detail = resp.text
+        try:
+            detail = resp.json().get("detail", detail)
+        except ValueError:
+            pass
+        raise UploadError(f"Upload failed ({resp.status_code}): {detail}")

aevrin-0.1.0/tests/test_target_detection.py

@@ -0,0 +1,49 @@
+import pytest
+from aevrin_scanner_core import TargetType
+
+from aevrin_cli.target_detection import TargetDetectionError, detect_target
+
+
+def test_detects_github_https_url():
+    target_type, normalized = detect_target("https://github.com/owner/repo")
+    assert target_type == TargetType.GITHUB_REPO
+    assert normalized == "https://github.com/owner/repo"
+
+
+def test_detects_github_shorthand():
+    target_type, normalized = detect_target("github.com/owner/repo")
+    assert target_type == TargetType.GITHUB_REPO
+    assert normalized == "https://github.com/owner/repo"
+
+
+def test_normalizes_trailing_slash_and_git_suffix():
+    _, normalized = detect_target("https://github.com/owner/repo.git/")
+    assert normalized == "https://github.com/owner/repo"
+
+
+def test_normalizes_www_github():
+    target_type, normalized = detect_target("https://www.github.com/owner/repo")
+    assert target_type == TargetType.GITHUB_REPO
+    assert normalized == "https://github.com/owner/repo"
+
+
+def test_detects_live_server_url():
+    target_type, normalized = detect_target("https://my-mcp-server.example.com")
+    assert target_type == TargetType.LIVE_MCP_SERVER
+    assert normalized == "https://my-mcp-server.example.com"
+
+
+def test_detects_local_path(tmp_path):
+    target_type, normalized = detect_target(str(tmp_path))
+    assert target_type == TargetType.LOCAL_PATH
+    assert normalized == str(tmp_path)
+
+
+def test_rejects_empty_target():
+    with pytest.raises(TargetDetectionError):
+        detect_target("   ")
+
+
+def test_rejects_nonexistent_path_and_non_url():
+    with pytest.raises(TargetDetectionError):
+        detect_target("./definitely-does-not-exist-xyz")