kmcp 0.1.5.dev0__py3-none-any.whl

kali_mcp/prompts.py

@@ -0,0 +1,184 @@
+"""MCP prompts — guided workflow templates for clients.
+
+Each prompt renders a short instruction + tool-suggestions message so an
+MCP client can drive a standard pentest workflow step by step.
+"""
+
+from __future__ import annotations
+
+import logging
+
+logger = logging.getLogger("kali_mcp.prompts")
+
+
+def _text(msg: str) -> dict:
+    """Build an assistant/user content block."""
+    return {"type": "text", "text": msg}
+
+
+def _user(msg: str) -> dict:
+    return {"role": "user", "content": _text(msg)}
+
+
+def _assistant(msg: str) -> dict:
+    return {"role": "assistant", "content": _text(msg)}
+
+
+def _recon(target: str, depth: str = "standard", scope: str = "") -> list[dict]:
+    msgs = [
+        _user(
+            "You are an expert penetration tester. Begin external reconnaissance "
+            f"against the target **{target}**"
+            + (f" with scope notes: {scope}" if scope else "")
+            + ". Run one phase at a time and pause for my approval between phases."
+        ),
+        _assistant(
+            "Phase 1 — asset discovery. I will resolve the target, identify "
+            "infrastructure, and map services using the `dns_recon`, `whois_lookup`, "
+            "and `ping_sweep` tools, then `nmap_scan` for open ports."
+            + (
+                " Given the 'deep' depth, I will also enumerate subdomains and "
+                "technology fingerprints."
+                if depth == "deep"
+                else " I will keep verbosity low."
+            )
+            + "\nShall I start?"
+        ),
+    ]
+    return msgs
+
+
+def _webapp(url: str, auth: str = "no") -> list[dict]:
+    msgs = [
+        _user(
+            f"Perform a web application security assessment of **{url}** (authenticated: {auth})."
+        ),
+        _assistant(
+            "I will follow this checklist, running one item at a time and reporting "
+            "evidence for each:\n"
+            "1. `webapp_crawl` — enumerate endpoints, parameters, and tech stack\n"
+            "2. `webapp_scan` — active vulnerability scan\n"
+            "3. Manual review of findings before any exploitation\n"
+            "4. Retest and summary report\n"
+            f"Authenticated assessment: {auth}. Starting with the crawl."
+        ),
+    ]
+    return msgs
+
+
+def _ad(domain: str, credentials: str = "") -> list[dict]:
+    msgs = [
+        _user(
+            "Assess the Active Directory environment for domain "
+            f"**{domain}**" + (f" using credentials {credentials}" if credentials else "") + "."
+        ),
+        _assistant(
+            "I will enumerate in this order:\n"
+            "1. Domain and trust discovery\n"
+            "2. User/group/computer enumeration\n"
+            "3. ACL and delegation analysis\n"
+            "4. Kerberos attack surface (AS-REP roast, Kerberoasting checks)\n"
+            "5. Report with remediation\n"
+            "Beginning with domain discovery."
+        ),
+    ]
+    return msgs
+
+
+def _osint(subject: str, sources: str = "default") -> list[dict]:
+    msgs = [
+        _user(
+            f"Gather open-source intelligence on **{subject}** using the '{sources}' source set."
+        ),
+        _assistant(
+            "OSINT collection plan:\n"
+            "1. Web/DNS footprint — `whois_lookup`, `dns_recon`, certificate search\n"
+            "2. Data breach / credential exposure checks (with the target's consent)\n"
+            "3. Social footprint review\n"
+            "4. Organized intelligence report with sources\n"
+            f"Sources: {sources}. Starting with the DNS/web footprint."
+        ),
+    ]
+    return msgs
+
+
+def _quick_scan(target: str, ports: str = "top1000", profile: str = "fast") -> list[dict]:
+    msgs = [
+        _user(
+            f"Run a {profile} nmap scan of **{target}** on ports **{ports}** "
+            "and summarize findings."
+        ),
+        _assistant(
+            f"Using `nmap_scan` with target={target}, ports={ports}, profile={profile}. "
+            "I'll run the scan and give you an open-port/service summary with "
+            "next-step recommendations."
+        ),
+    ]
+    return msgs
+
+
+def _report(engagement: str, findings: str = "") -> list[dict]:
+    msgs = [
+        _user(
+            f"Generate a professional penetration test report for **{engagement}**"
+            + (f" from these findings: {findings}" if findings else ".")
+        ),
+        _assistant(
+            "Report structure:\n"
+            "1. Executive summary (business impact)\n"
+            "2. Scope and methodology\n"
+            "3. Findings with severity, evidence, and reproduction steps\n"
+            "4. Remediation plan\n"
+            "5. Appendix (raw data)\n"
+            "I'll ask for each finding's evidence as I draft."
+        ),
+    ]
+    return msgs
+
+
+def register_prompts(mcp) -> None:
+    """Register all workflow prompt templates on the FastMCP server."""
+
+    @mcp.prompt(
+        name="recon_workflow",
+        description="Guided external reconnaissance workflow for a target host/domain",
+    )
+    def recon_workflow(target: str, depth: str = "standard", scope: str = "") -> list[dict]:
+        return _recon(target, depth, scope)
+
+    @mcp.prompt(
+        name="webapp_assessment",
+        description="Guided web application security assessment workflow",
+    )
+    def webapp_assessment(url: str, auth: str = "no") -> list[dict]:
+        return _webapp(url, auth)
+
+    @mcp.prompt(
+        name="ad_assessment",
+        description="Guided Active Directory security assessment workflow",
+    )
+    def ad_assessment(domain: str, credentials: str = "") -> list[dict]:
+        return _ad(domain, credentials)
+
+    @mcp.prompt(
+        name="osint_harvest",
+        description="Guided OSINT gathering workflow for a subject",
+    )
+    def osint_harvest(subject: str, sources: str = "default") -> list[dict]:
+        return _osint(subject, sources)
+
+    @mcp.prompt(
+        name="quick_scan",
+        description="Quick nmap scan with findings summary",
+    )
+    def quick_scan(target: str, ports: str = "top1000", profile: str = "fast") -> list[dict]:
+        return _quick_scan(target, ports, profile)
+
+    @mcp.prompt(
+        name="report_template",
+        description="Professional penetration test report generation",
+    )
+    def report_template(engagement: str, findings: str = "") -> list[dict]:
+        return _report(engagement, findings)
+
+    logger.info("Registered %d prompt templates", 6)

kali_mcp/registry.py

@@ -0,0 +1,33 @@
+"""Tool registry — maps tool names to BaseTool instances."""
+
+from __future__ import annotations
+
+import logging
+
+from kali_mcp.tools.base import BaseTool
+
+logger = logging.getLogger("kali_mcp.registry")
+
+
+class ToolRegistry:
+    def __init__(self) -> None:
+        self._tools: dict[str, BaseTool] = {}
+
+    def register(self, tool: BaseTool) -> None:
+        """Register a tool instance. Overwrites if name already exists."""
+        if tool.name in self._tools:
+            logger.warning("Overwriting tool: %s", tool.name)
+        self._tools[tool.name] = tool
+        logger.info("Registered tool: %s", tool.name)
+
+    def get(self, name: str) -> BaseTool | None:
+        return self._tools.get(name)
+
+    def list_all(self) -> list[BaseTool]:
+        return list(self._tools.values())
+
+    def tool_names(self) -> list[str]:
+        return list(self._tools.keys())
+
+
+registry = ToolRegistry()

kali_mcp/resources.py

@@ -0,0 +1,263 @@
+"""MCP resources — server metadata exposed to clients.
+
+Resources (URIs, not tools) give the MCP client a browseable view of:
+  - live server configuration
+  - registered tool inventory
+  - health status
+  - execution/server logs (JSON lines)
+  - generated artifacts
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+from pathlib import Path
+from typing import Any
+
+from kali_mcp.config import config
+
+logger = logging.getLogger("kali_mcp.resources")
+
+RESOURCE_NAMESPACE = "kali"
+
+# Templates registered for template listing (uriTemplate → {name, description})
+TEMPLATES: dict[str, dict[str, str]] = {
+    "kali://artifacts/{artifact}": {
+        "name": "kali_artifact",
+        "description": "Read a generated artifact from the artifact directory",
+    },
+}
+
+
+def _config_resource() -> str:
+    """Live server configuration as JSON."""
+    cfg = {
+        "server_name": config.server_name,
+        "server_version": config.server_version,
+        "host": config.host,
+        "port": config.port,
+        "transport": config.transport,
+        "default_timeout": config.default_timeout,
+        "max_timeout": config.max_timeout,
+        "max_concurrent": config.max_concurrent,
+        "log_dir": str(config.log_dir),
+        "artifact_dir": str(config.artifact_dir),
+        "debug": config.debug,
+        "rate_limit_per_minute": config.rate_limit_per_minute,
+        "auth_enabled": bool(config.api_token),
+    }
+    return json.dumps(cfg, indent=2)
+
+
+def _tools_resource() -> str:
+    """Registered tool inventory as JSON."""
+    from kali_mcp.registry import registry
+
+    tools = []
+    for tool in registry.list_all():
+        tools.append(
+            {
+                "name": tool.name,
+                "description": tool.description,
+                "schema": tool.input_schema(),
+            }
+        )
+    return json.dumps({"count": len(tools), "tools": tools}, indent=2)
+
+
+def _make_health_resource(health):
+    """Build a resource reader returning live health status as JSON."""
+
+    def _read() -> str:
+        return json.dumps(health.get_status(), indent=2)
+
+    return _read
+
+
+def _tail_file(path: Path, max_lines: int = 2000) -> str:
+    """Return the tail of a JSON-lines log file as pretty JSON."""
+    if not path.exists():
+        return json.dumps({"error": f"no log file at {path}"}, indent=2)
+    lines: list = []
+    try:
+        with open(path, "r", encoding="utf-8", errors="replace") as fh:
+            for line in fh:
+                line = line.strip()
+                if not line:
+                    continue
+                try:
+                    lines.append(json.loads(line))
+                except json.JSONDecodeError:
+                    lines.append({"raw": line})
+    except OSError as exc:
+        return json.dumps({"error": str(exc)}, indent=2)
+    return json.dumps({"count": len(lines), "tail": lines[-max_lines:]}, indent=2)
+
+
+def _executions_resource() -> str:
+    """Tail of the executions log."""
+    return _tail_file(config.log_dir / "executions.jsonl")
+
+
+def _server_log_resource() -> str:
+    """Tail of the server log."""
+    return _tail_file(config.log_dir / "server.log")
+
+
+def _artifacts_index_resource() -> str:
+    """List artifacts in the artifact directory."""
+    entries = []
+    if config.artifact_dir.exists():
+        for p in sorted(config.artifact_dir.iterdir()):
+            if p.is_file():
+                entries.append(
+                    {
+                        "name": p.name,
+                        "size_bytes": p.stat().st_size,
+                        "uri": f"{RESOURCE_NAMESPACE}://artifacts/{p.name}",
+                    }
+                )
+    return json.dumps({"count": len(entries), "artifacts": entries}, indent=2)
+
+
+def _artifact_resource(artifact: str) -> str:
+    """Read a single artifact, safely (no path traversal)."""
+    name = Path(artifact).name
+    if name != artifact:
+        return json.dumps({"error": "invalid artifact name"}, indent=2)
+    path = config.artifact_dir / name
+    if not path.exists() or not path.is_file():
+        return json.dumps({"error": f"artifact not found: {name}"}, indent=2)
+    if path.stat().st_size > 1_000_000:
+        return json.dumps({"error": "artifact too large to read"}, indent=2)
+    try:
+        content = path.read_text(encoding="utf-8", errors="replace")
+    except OSError as exc:
+        return json.dumps({"error": str(exc)}, indent=2)
+    try:
+        payload = json.loads(content)
+    except json.JSONDecodeError:
+        payload = content
+    return json.dumps(payload, indent=2, default=str)
+
+
+def _db_stats_resource() -> str:
+    """SQLite persistence statistics as JSON."""
+    try:
+        from kali_mcp.db import manager as dbm
+
+        db = dbm.get_db()
+        if db is None:
+            return json.dumps({"error": "database disabled or unavailable"}, indent=2)
+        stats: dict[str, Any] = {"db_path": str(db.path)}
+        for table in ("targets", "scans", "findings", "credentials"):
+            try:
+                stats[table] = db.conn.execute(f"SELECT COUNT(*) FROM {table}").fetchone()[0]
+            except Exception:  # noqa: BLE001
+                stats[table] = "error"
+        try:
+            stats["findings_by_severity"] = {
+                row[0]: row[1]
+                for row in db.conn.execute(
+                    "SELECT severity, COUNT(*) FROM findings GROUP BY severity"
+                ).fetchall()
+            }
+        except Exception:  # noqa: BLE001, S110
+            pass
+        return json.dumps(stats, indent=2)
+    except Exception as exc:  # noqa: BLE001
+        return json.dumps({"error": str(exc)}, indent=2)
+
+
+def _vault_index_resource() -> str:
+    """Vault index — the inter-agent knowledge-sharing catalog."""
+    try:
+        from kali_mcp.utils.vault import VAULT_ROOT, ensure_vault_dirs
+
+        ensure_vault_dirs()
+        index_path = VAULT_ROOT / "index.json"
+        if not index_path.exists():
+            return json.dumps({"count": 0, "entries": []}, indent=2)
+        data = json.loads(index_path.read_text())
+        # Enrich entries with browseable resource URIs where possible
+        for entry in data.get("entries", []):
+            path = Path(entry.get("path", ""))
+            if path.is_file() and config.artifact_dir in path.parents:
+                rel = path.relative_to(config.artifact_dir)
+                entry["uri"] = f"{RESOURCE_NAMESPACE}://artifacts/{rel}"
+        return json.dumps(data, indent=2)
+    except Exception as exc:  # noqa: BLE001
+        return json.dumps({"error": str(exc)}, indent=2)
+
+
+def register_resources(mcp, health=None) -> None:
+    """Register all kali:// resources and templates on the FastMCP server."""
+    mcp.resource(
+        f"{RESOURCE_NAMESPACE}://config",
+        name="kali_config",
+        description="Live server configuration",
+        mime_type="application/json",
+    )(_config_resource)
+
+    mcp.resource(
+        f"{RESOURCE_NAMESPACE}://tools",
+        name="kali_tools",
+        description="Registered tool inventory with schemas",
+        mime_type="application/json",
+    )(_tools_resource)
+
+    mcp.resource(
+        f"{RESOURCE_NAMESPACE}://health",
+        name="kali_health",
+        description="Live server health status",
+        mime_type="application/json",
+    )(_make_health_resource(health))
+
+    mcp.resource(
+        f"{RESOURCE_NAMESPACE}://logs/executions",
+        name="kali_executions_log",
+        description="Tail of the executions log (JSON lines)",
+        mime_type="application/json",
+    )(_executions_resource)
+
+    mcp.resource(
+        f"{RESOURCE_NAMESPACE}://logs/server",
+        name="kali_server_log",
+        description="Tail of the server log (JSON lines)",
+        mime_type="application/json",
+    )(_server_log_resource)
+
+    mcp.resource(
+        f"{RESOURCE_NAMESPACE}://artifacts",
+        name="kali_artifacts",
+        description="List generated artifacts",
+        mime_type="application/json",
+    )(_artifacts_index_resource)
+
+    mcp.resource(
+        f"{RESOURCE_NAMESPACE}://artifacts/{{artifact}}",
+        name="kali_artifact",
+        description="Read a generated artifact by name",
+        mime_type="application/json",
+    )(_artifact_resource)
+
+    mcp.resource(
+        f"{RESOURCE_NAMESPACE}://db/stats",
+        name="kali_db_stats",
+        description="SQLite persistence statistics (targets, scans, findings, credentials)",
+        mime_type="application/json",
+    )(_db_stats_resource)
+
+    mcp.resource(
+        f"{RESOURCE_NAMESPACE}://vault/index",
+        name="kali_vault_index",
+        description="Index of the inter-agent vault (findings, credentials, evidence, notes)",
+        mime_type="application/json",
+    )(_vault_index_resource)
+
+    logger.info(
+        "Registered %d resources + %d templates",
+        9,
+        len(TEMPLATES),
+    )

kali_mcp/responses.py

@@ -0,0 +1,39 @@
+"""Standardized MCP response builders."""
+
+from __future__ import annotations
+
+import json
+from typing import Any
+
+from kali_mcp.models import ExecutionResult, ToolError
+
+
+def success_response(result: ExecutionResult) -> dict[str, Any]:
+    """Build a successful tool result for MCP."""
+    return {
+        "content": [
+            {
+                "type": "text",
+                "text": json.dumps(result.to_dict(), indent=2),
+            }
+        ],
+        "isError": False,
+    }
+
+
+def error_response(error: ToolError) -> dict[str, Any]:
+    """Build an error tool result for MCP."""
+    return {
+        "content": [
+            {
+                "type": "text",
+                "text": json.dumps(error.to_dict(), indent=2),
+            }
+        ],
+        "isError": True,
+    }
+
+
+def error_response_from_exception(exc: Exception) -> dict[str, Any]:
+    """Build error response from caught exception — never exposes traceback."""
+    return error_response(ToolError(error=str(exc)))

kali_mcp/security.py

@@ -0,0 +1,15 @@
+"""Security helpers for command sanitization."""
+
+from __future__ import annotations
+
+import shlex
+
+
+def sanitize_command_parts(parts: list[str]) -> list[str]:
+    """Ensure command parts are safe for subprocess exec (no shell injection)."""
+    return [str(p) for p in parts]
+
+
+def quote_argument(arg: str) -> str:
+    """Shell-safe quote a single argument."""
+    return shlex.quote(arg)