kmcp 0.1.5.dev0__py3-none-any.whl

kali_mcp/__init__.py

@@ -0,0 +1,3 @@
+"""Kali MCP Server — exposes Kali Linux penetration-testing tools via MCP."""
+
+__version__ = "1.0.0"

kali_mcp/__main__.py

@@ -0,0 +1,28 @@
+"""Entry point for ``python -m kali_mcp``.
+
+Usage:
+
+    python -m kali_mcp                              # start the MCP server (default)
+    python -m kali_mcp start [--host HOST] [--port PORT]   # start the MCP server (alias: s)
+    python -m kali_mcp monitor [<url>]              # launch the interactive monitor TUI (alias: m)
+    python -m kali_mcp purge <scope> [--confirm]    # purge data: db | vault | all (alias: p)
+
+The unified ``kmcp`` console script maps to :func:`kali_mcp.cli.main`.
+"""
+
+from __future__ import annotations
+
+import sys
+
+from kali_mcp.cli import main as cli_main
+
+
+def main() -> None:
+    argv = sys.argv[1:]
+    if not argv:
+        argv = ["start"]
+    sys.exit(cli_main(argv))
+
+
+if __name__ == "__main__":
+    main()

kali_mcp/_version.py

@@ -0,0 +1,24 @@
+# file generated by vcs-versioning
+# don't change, don't track in version control
+from __future__ import annotations
+
+__all__ = [
+    "__version__",
+    "__version_tuple__",
+    "version",
+    "version_tuple",
+    "__commit_id__",
+    "commit_id",
+]
+
+version: str
+__version__: str
+__version_tuple__: tuple[int | str, ...]
+version_tuple: tuple[int | str, ...]
+commit_id: str | None
+__commit_id__: str | None
+
+__version__ = version = '0.1.5.dev0'
+__version_tuple__ = version_tuple = (0, 1, 5, 'dev0')
+
+__commit_id__ = commit_id = None

kali_mcp/cli.py

@@ -0,0 +1,169 @@
+"""Kali MCP CLI — unified entry point for server, monitor, and data purge.
+
+Usage:
+
+    kmcp start [--host HOST] [--port PORT]   # start the MCP server (alias: s)
+    kmcp monitor [URL]                        # launch the monitor TUI (alias: m)
+    kmcp purge SCOPE [--confirm]              # purge data: db | vault | all (alias: p)
+
+Environment variables (MCP_HOST, MCP_PORT, etc.) are read from .env via python-dotenv,
+just like ``just start``.
+"""
+
+from __future__ import annotations
+
+import argparse
+import os
+import shutil
+import sys
+from pathlib import Path
+
+try:
+    from dotenv import load_dotenv
+except Exception:  # pragma: no cover - optional dependency missing # noqa: BLE001
+
+    def load_dotenv(*args, **kwargs):
+        return None
+
+
+REPO_ROOT = Path(__file__).resolve().parent.parent.parent
+
+
+def _load_env() -> None:
+    """Load .env from the repo root (idempotent)."""
+    load_dotenv(str(REPO_ROOT / ".env"), override=False)
+
+
+def cmd_start(args: argparse.Namespace) -> int:
+    """Start the MCP server."""
+    _load_env()
+    os.environ.setdefault("MCP_HOST", args.host or os.getenv("MCP_HOST", "0.0.0.0"))
+    os.environ.setdefault("MCP_PORT", args.port or os.getenv("MCP_PORT", "8399"))
+
+    from kali_mcp.server import main
+
+    main()
+    return 0
+
+
+def cmd_monitor(args: argparse.Namespace) -> int:
+    """Launch the interactive monitor TUI."""
+    _load_env()
+    url = args.url or os.getenv("MCP_MONITOR_URL", "http://127.0.0.1:8399")
+
+    from kali_mcp.monitor.tui import main as monitor_main
+
+    monitor_main(url)
+    return 0
+
+
+def _confirm(prompt: str) -> bool:
+    """Ask the user for confirmation. Returns True on 'y'/'yes'."""
+    try:
+        response = input(f"{prompt} [y/N] ").strip().lower()
+    except (EOFError, KeyboardInterrupt):
+        print("\naborted")
+        return False
+    return response in ("y", "yes")
+
+
+def cmd_purge(args: argparse.Namespace) -> int:
+    """Purge stored data (SQLite DB and/or vault)."""
+    _load_env()
+
+    scope = args.scope.lower()
+
+    valid = {"db", "vault", "all"}
+    if scope not in valid:
+        print(f"unknown scope '{scope}' — use: db | vault | all", file=sys.stderr)
+        return 1
+
+    if not args.confirm and not _confirm(f"Purge '{scope}' data — this cannot be undone"):
+        print("aborted")
+        return 1
+
+    removed: list[str] = []
+
+    def rm(path: Path) -> None:
+        if path.exists():
+            if path.is_dir():
+                shutil.rmtree(path, ignore_errors=True)
+            else:
+                try:
+                    path.unlink()
+                except FileNotFoundError:
+                    pass
+            removed.append(str(path))
+
+    if scope in ("db", "all"):
+        for name in ("kali-mcp.sqlite", "kali-mcp.sqlite-wal", "kali-mcp.sqlite-shm"):
+            rm(REPO_ROOT / "data" / name)
+
+    if scope in ("vault", "all"):
+        rm(REPO_ROOT / "artifacts" / "vault")
+
+    print(f"purged: {scope}")
+    if removed:
+        print("removed:")
+        for path in removed:
+            print(f"  {path}")
+    else:
+        print("nothing to remove")
+    return 0
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="kmcp",
+        description="Kali MCP Server CLI — server, monitor, and data purge utilities.",
+    )
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    # start / s
+    p_start = sub.add_parser("start", aliases=["s"], help="Start the MCP server")
+    p_start.add_argument(
+        "--host", default=None, help="Listen address (default: MCP_HOST or 0.0.0.0)"
+    )
+    p_start.add_argument("--port", default=None, help="Listen port (default: MCP_PORT or 8399)")
+    p_start.set_defaults(func=cmd_start)
+
+    # monitor / m
+    p_monitor = sub.add_parser("monitor", aliases=["m"], help="Launch the monitor TUI")
+    p_monitor.add_argument(
+        "url",
+        nargs="?",
+        default=None,
+        help="Base URL of the MCP server (default: http://127.0.0.1:8399)",
+    )
+    p_monitor.set_defaults(func=cmd_monitor)
+
+    # purge / p
+    p_purge = sub.add_parser("purge", aliases=["p"], help="Purge stored data")
+    p_purge.add_argument(
+        "scope",
+        choices=["db", "vault", "all"],
+        help="What to purge: db (SQLite), vault (artifacts/vault), or all",
+    )
+    p_purge.add_argument(
+        "--confirm",
+        "-y",
+        action="store_true",
+        help="Skip confirmation prompt",
+    )
+    p_purge.set_defaults(func=cmd_purge)
+
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    if argv is None:
+        argv = sys.argv[1:]
+    if not argv:
+        argv = ["start"]
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    return args.func(args)
+
+
+if __name__ == "__main__":
+    sys.exit(main())

kali_mcp/config.py

@@ -0,0 +1,95 @@
+"""Server configuration loaded from environment variables."""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass, field
+from pathlib import Path
+
+# Optional: dotenv for local development. If not installed, fall back gracefully.
+try:
+    from dotenv import load_dotenv
+except Exception:  # pragma: no cover - optional dependency missing in test env # noqa: BLE001
+
+    def load_dotenv(*args, **kwargs):
+        return None
+
+
+load_dotenv(verbose=True)
+
+
+def _int_env(key: str, default: int) -> int:
+    """Parse int from env var with safe fallback."""
+    val = os.getenv(key, "")
+    if not val:
+        return default
+    try:
+        return int(val)
+    except ValueError:
+        return default
+
+
+def _bool_env(key: str, default: bool) -> bool:
+    """Parse bool from env var with safe fallback."""
+    val = os.getenv(key, "")
+    if not val:
+        return default
+    return val.lower() in ("1", "true", "yes")
+
+
+@dataclass(frozen=True)
+class Config:
+    # Server
+    host: str = field(default_factory=lambda: os.getenv("MCP_HOST", "0.0.0.0"))
+    port: int = field(default_factory=lambda: _int_env("MCP_PORT", 8399))
+    server_name: str = field(default_factory=lambda: os.getenv("MCP_SERVER_NAME", "kali-mcp"))
+    server_version: str = field(default_factory=lambda: os.getenv("MCP_SERVER_VERSION", "1.0.0"))
+
+    # Execution
+    default_timeout: int = field(default_factory=lambda: _int_env("MCP_DEFAULT_TIMEOUT", 300))
+    max_timeout: int = field(default_factory=lambda: _int_env("MCP_MAX_TIMEOUT", 3600))
+    max_concurrent: int = field(default_factory=lambda: _int_env("MCP_MAX_CONCURRENT", 10))
+
+    # Paths
+    log_dir: Path = field(default_factory=lambda: Path(os.getenv("MCP_LOG_DIR", "logs")))
+    artifact_dir: Path = field(
+        default_factory=lambda: Path(os.getenv("MCP_ARTIFACT_DIR", "artifacts"))
+    )
+
+    # Encoding
+    default_encoding: str = field(default_factory=lambda: os.getenv("MCP_ENCODING", "utf-8"))
+
+    # Debug
+    debug: bool = field(default_factory=lambda: _bool_env("MCP_DEBUG", False))
+
+    # Transport: "sse" (default) or "streamable-http"
+    transport: str = field(default_factory=lambda: os.getenv("MCP_TRANSPORT", "sse"))
+
+    # Auth
+    api_token: str = field(default_factory=lambda: os.getenv("MCP_API_TOKEN", ""))
+
+    # CORS
+    allowed_origins: str = field(default_factory=lambda: os.getenv("MCP_ALLOWED_ORIGINS", "*"))
+
+    # Rate limiting (0 = unlimited)
+    rate_limit_per_minute: int = field(default_factory=lambda: _int_env("MCP_RATE_LIMIT", 0))
+
+    # Vault
+    vault_max_row_bytes: int = field(
+        default_factory=lambda: _int_env("MCP_VAULT_MAX_ROW_BYTES", 26_214_400)
+    )  # 25MB ceiling per vault row (0 = unlimited)
+
+    # Database
+    db_path: Path = field(
+        default_factory=lambda: Path(os.getenv("MCP_DB_PATH", "data/kali-mcp.sqlite"))
+    )
+    db_enabled: bool = field(default_factory=lambda: _bool_env("MCP_DB_ENABLED", True))
+
+    def __post_init__(self) -> None:
+        self.log_dir.mkdir(parents=True, exist_ok=True)
+        self.artifact_dir.mkdir(parents=True, exist_ok=True)
+        if self.db_enabled:
+            self.db_path.parent.mkdir(parents=True, exist_ok=True)
+
+
+config = Config()

kali_mcp/db/__init__.py

@@ -0,0 +1 @@
+"""Database package for Kali MCP — SQLite storage backend."""

kali_mcp/db/manager.py

@@ -0,0 +1,248 @@
+"""SQLite data manager for Kali MCP.
+
+Provides a lightweight, thread-safe interface to store targets, scans,
+findings, and credentials discovered by AI agents.
+"""
+
+from __future__ import annotations
+
+import sqlite3
+from pathlib import Path
+
+from kali_mcp.config import config
+
+
+class DBManager:
+    def __init__(self, path: Path) -> None:
+        self.path = Path(path)
+        self.conn = sqlite3.connect(str(self.path), check_same_thread=False)
+        self.conn.execute("PRAGMA foreign_keys = ON;")
+        self.conn.execute("PRAGMA journal_mode=WAL;")
+        self.conn.row_factory = sqlite3.Row
+
+    def ensure_schema(self) -> None:
+        cur = self.conn.cursor()
+        cur.executescript(
+            """
+            CREATE TABLE IF NOT EXISTS targets (
+                id INTEGER PRIMARY KEY AUTOINCREMENT,
+                target TEXT NOT NULL UNIQUE,
+                target_type TEXT NOT NULL,
+                scope TEXT NOT NULL DEFAULT 'in-scope',
+                tags TEXT,
+                notes TEXT,
+                created_at TEXT NOT NULL,
+                updated_at TEXT NOT NULL
+            );
+            CREATE INDEX IF NOT EXISTS idx_targets_scope ON targets(scope);
+            CREATE INDEX IF NOT EXISTS idx_targets_type ON targets(target_type);
+
+            CREATE TABLE IF NOT EXISTS scans (
+                id INTEGER PRIMARY KEY AUTOINCREMENT,
+                target_id INTEGER NOT NULL,
+                tool TEXT NOT NULL,
+                command TEXT NOT NULL,
+                started_at TEXT NOT NULL,
+                completed_at TEXT,
+                duration REAL,
+                success INTEGER DEFAULT 0,
+                findings_count INTEGER DEFAULT 0,
+                artifact_uri TEXT,
+                FOREIGN KEY (target_id) REFERENCES targets(id)
+            );
+            CREATE INDEX IF NOT EXISTS idx_scans_target ON scans(target_id);
+            CREATE INDEX IF NOT EXISTS idx_scans_tool ON scans(tool);
+
+            CREATE TABLE IF NOT EXISTS findings (
+                id INTEGER PRIMARY KEY AUTOINCREMENT,
+                target_id INTEGER NOT NULL,
+                scan_id INTEGER,
+                tool TEXT NOT NULL,
+                finding_type TEXT NOT NULL,
+                severity TEXT,
+                title TEXT NOT NULL,
+                description TEXT,
+                evidence TEXT,
+                port INTEGER,
+                service TEXT,
+                url TEXT,
+                status TEXT DEFAULT 'open',
+                created_at TEXT NOT NULL,
+                updated_at TEXT NOT NULL,
+                FOREIGN KEY (target_id) REFERENCES targets(id),
+                FOREIGN KEY (scan_id) REFERENCES scans(id)
+            );
+            CREATE INDEX IF NOT EXISTS idx_findings_target ON findings(target_id);
+            CREATE INDEX IF NOT EXISTS idx_findings_severity ON findings(severity);
+            CREATE INDEX IF NOT EXISTS idx_findings_status ON findings(status);
+
+            CREATE TABLE IF NOT EXISTS credentials (
+                id INTEGER PRIMARY KEY AUTOINCREMENT,
+                target_id INTEGER NOT NULL,
+                service TEXT NOT NULL,
+                username TEXT NOT NULL,
+                password TEXT,
+                hash TEXT,
+                source_tool TEXT NOT NULL,
+                captured_at TEXT NOT NULL,
+                notes TEXT,
+                FOREIGN KEY (target_id) REFERENCES targets(id)
+            );
+            CREATE INDEX IF NOT EXISTS idx_credentials_target ON credentials(target_id);
+            CREATE INDEX IF NOT EXISTS idx_credentials_service ON credentials(service);
+            """
+        )
+        self.conn.commit()
+
+    def close(self) -> None:
+        try:
+            self.conn.close()
+        except Exception:  # noqa: BLE001, S110
+            pass
+
+    # Convenience helpers for common operations
+    def upsert_target(
+        self,
+        target: str,
+        target_type: str = "host",
+        scope: str = "in-scope",
+        tags: str = "",
+        notes: str = "",
+    ) -> int:
+        cur = self.conn.cursor()
+        cur.execute("SELECT id FROM targets WHERE target = ?", (target,))
+        row = cur.fetchone()
+        now = __import__("datetime").datetime.utcnow().isoformat() + "Z"
+        if row:
+            tid = int(row[0])
+            cur.execute(
+                "UPDATE targets SET target_type=?, scope=?, tags=?, notes=?, updated_at=? WHERE id=?",
+                (target_type, scope, tags, notes, now, tid),
+            )
+        else:
+            cur.execute(
+                "INSERT INTO targets (target, target_type, scope, tags, notes, created_at, updated_at) VALUES (?,?,?,?,?,?,?)",
+                (target, target_type, scope, tags, notes, now, now),
+            )
+            tid = cur.lastrowid
+        self.conn.commit()
+        return int(tid)
+
+    def add_scan(
+        self,
+        target_id: int,
+        tool: str,
+        command: str,
+        started_at: str,
+        completed_at: str,
+        duration: float,
+        success: int,
+        findings_count: int,
+        artifact_uri: str | None,
+    ) -> int:
+        cur = self.conn.cursor()
+        cur.execute(
+            "INSERT INTO scans (target_id, tool, command, started_at, completed_at, duration, success, findings_count, artifact_uri) VALUES (?,?,?,?,?,?,?,?,?)",
+            (
+                target_id,
+                tool,
+                command,
+                started_at,
+                completed_at,
+                duration,
+                int(bool(success)),
+                int(findings_count),
+                artifact_uri,
+            ),
+        )
+        self.conn.commit()
+        return cur.lastrowid
+
+    def add_finding(
+        self,
+        target_id: int,
+        scan_id: int | None,
+        tool: str,
+        finding_type: str,
+        severity: str,
+        title: str,
+        description: str,
+        evidence: str,
+        port: int | None = None,
+        service: str | None = None,
+        url: str | None = None,
+        status: str = "open",
+    ) -> int:
+        cur = self.conn.cursor()
+        now = __import__("datetime").datetime.utcnow().isoformat() + "Z"
+        cur.execute(
+            "INSERT INTO findings (target_id, scan_id, tool, finding_type, severity, title, description, evidence, port, service, url, status, created_at, updated_at) VALUES (?,?,?,?,?,?,?,?,?,?,?,?,?,?)",
+            (
+                target_id,
+                scan_id,
+                tool,
+                finding_type,
+                severity,
+                title,
+                description,
+                evidence,
+                port,
+                service,
+                url,
+                status,
+                now,
+                now,
+            ),
+        )
+        self.conn.commit()
+        return cur.lastrowid
+
+    def add_credential(
+        self,
+        target_id: int,
+        service: str,
+        username: str,
+        password: str | None = None,
+        hash_value: str | None = None,
+        source_tool: str = "",
+        notes: str = "",
+    ) -> int:
+        cur = self.conn.cursor()
+        now = __import__("datetime").datetime.utcnow().isoformat() + "Z"
+        cur.execute(
+            "INSERT INTO credentials (target_id, service, username, password, hash, source_tool, captured_at, notes) VALUES (?,?,?,?,?,?,?,?)",
+            (
+                target_id,
+                service,
+                username,
+                password,
+                hash_value,
+                source_tool,
+                now,
+                notes,
+            ),
+        )
+        self.conn.commit()
+        return cur.lastrowid
+
+
+_db_singleton: DBManager | None = None
+
+
+def get_db() -> DBManager | None:
+    global _db_singleton
+    if _db_singleton is None:
+        try:
+            if getattr(config, "db_enabled", True):
+                _db_singleton = DBManager(config.db_path)
+                _db_singleton.ensure_schema()
+        except Exception:  # noqa: BLE001
+            _db_singleton = None
+    return _db_singleton
+
+
+def _now():
+    import datetime
+    from datetime import timezone
+
+    return datetime.datetime.now(timezone.utc).isoformat() + "Z"