Skip to content

Autonomous OODA-loop pentesting agent. Hermes brain, Kali + Playwright tools over MCP, ATT&CK as the Orient language.

14.9 KB
Raw Blame
"""Runner multi-herramienta genérico de `kali-mcp` (STDLIB PURA).

Generaliza el patrón de collection EN VIVO (hasta ahora específico de Prowler) a varias
tools (Prowler/ScoutSuite/Cloudsplaining) bajo UN contrato único: un **registro** por
fuente aporta (a) el binario a comprobar con ``shutil.which``, (b) el/los comando(s) a
ejecutar y dónde escriben su salida, (c) cómo localizar el fichero crudo (NO el HTML) y su
nombre canónico de artefacto, y (d) la finalización (stagear el crudo como artefacto y
construir el ``done`` con la REFERENCIA, nunca la carga). NO es una ruta nueva por
herramienta: es un worker/finalize genérico + registro.

Por qué un módulo aparte (igual que ``tool_streaming``/``artifact_store``/``prowler_artifact``):
``kali_mcp_server.py`` importa ``mcp``/``anyio`` (no están en el venv de dev). Toda la
mecánica del runner vive aquí con SOLO la librería estándar, así se cubre con tests sin el
SDK. Reutiliza ``tool_streaming`` (streaming + kill de grupo + cancelación) y
``artifact_store`` (staging del crudo) ya existentes; Prowler delega en ``prowler_artifact``
(mismo finalize + puente SSE de compat) — cero duplicación.

Separación de planos: el crudo de CUALQUIER tool viaja por el plano de DATOS (artefactos);
el ``done`` del CONTROL sólo lleva la referencia. Para fuentes no-Prowler NO se popula el
puente SSE ``set_findings``: su salida es un documento JSON único que se baja por el plano
de datos. Disciplina arm64: si el binario no está, se reporta (no se finge).
"""

from __future__ import annotations

import os
import shutil
import tempfile
from dataclasses import dataclass
from datetime import datetime, timezone
from pathlib import Path
from typing import Any, Callable

import artifact_store
import prowler_artifact
import tool_streaming

# Timeout por defecto de una collection (segundos); el server puede pasar el suyo.
DEFAULT_TIMEOUT = int(os.environ.get("COLLECTION_TIMEOUT", os.environ.get("PROWLER_TIMEOUT", "900")))

# Nombres canónicos del artefacto crudo por fuente.
PROWLER_ARTIFACT_NAME = prowler_artifact.PROWLER_ARTIFACT_NAME  # "prowler.ocsf.json"
SCOUTSUITE_ARTIFACT_NAME = "scoutsuite.results.json"
CLOUDSPLAINING_ARTIFACT_NAME = "cloudsplaining.results.json"


def _now_iso() -> str:
    return datetime.now(timezone.utc).isoformat().replace("+00:00", "Z")


def _ring_tail(execution_id: str, max_lines: int = 20) -> str:
    """Últimas líneas de salida de una ejecución (dato NO confiable, verbatim)."""
    page = tool_streaming.read(execution_id, 0)
    lines = page.get("lines", [])
    tail = lines[-max_lines:]
    return "\n".join(f"[{line['stream']}] {line['text']}" for line in tail)


# --------------------------------------------------------------- comandos por fuente


def _prowler_binary() -> str | None:
    return shutil.which("prowler")


def _build_prowler_cmd(outdir: str) -> list[str]:
    """Args del comando Prowler (sin shell) escribiendo en ``outdir`` (igual que antes).

    Reúne la configuración por entorno del MVP (status/regiones/servicios/verbose). Asume
    que Prowler está disponible (el runner lo valida con ``shutil.which``).
    """
    cmd = [
        _prowler_binary() or "prowler",
        "aws",
        "--output-formats",
        "json-ocsf",
        "--output-directory",
        outdir,
        "--status",
        *os.environ.get("PROWLER_STATUS", "FAIL").split(),
    ]
    _regions = os.environ.get("PROWLER_REGIONS", os.environ.get("AWS_REGION", "")).strip()
    if _regions:
        cmd += ["--region", *_regions.split()]
    _services = os.environ.get("PROWLER_SERVICES", "").strip()
    if _services:
        cmd += ["--service", *_services.split()]
    cmd += ["--verbose", "--log-level", "INFO"]
    return cmd


def _prowler_commands(account_id: str, workdir: str, outdir: str, params: dict) -> list[list[str]]:
    return [_build_prowler_cmd(outdir)]


def _scoutsuite_commands(account_id: str, workdir: str, outdir: str, params: dict) -> list[list[str]]:
    """ScoutSuite AWS, read-only, salida JSON en ``outdir/scoutsuite-results/*.js``.

    ``--no-browser`` evita abrir el navegador; las credenciales AWS read-only se toman del
    entorno del contenedor (igual que Prowler).
    """
    return [
        [
            "scout",
            "aws",
            "--no-browser",
            "--result-format",
            "json",
            "--report-dir",
            outdir,
            "--report-name",
            "hermes",
        ]
    ]


def _cloudsplaining_commands(account_id: str, workdir: str, outdir: str, params: dict) -> list[list[str]]:
    """Cloudsplaining en dos pasos: descargar los detalles IAM y escanearlos.

    1. ``cloudsplaining download --output <dir>`` baja el account-authorization-details. OJO:
       su ``--output`` es un DIRECTORIO EXISTENTE (``click.Path(exists=True)``, default el cwd),
       NO un fichero; escribe ``<profile>.json`` dentro (sin ``--profile`` -> ``default.json``).
       Las credenciales AWS vienen del entorno (sin ``--profile``), así que el crudo descargado
       es ``<workdir>/default.json``.
    2. ``cloudsplaining scan --input-file <workdir>/default.json`` lo analiza y escribe el JSON
       de resultados (``iam-results-*.json`` / ``iam-findings-*.json``) en ``outdir``
       (``--skip-open-report`` evita abrir el navegador). El JSON es lo que se stagea; el HTML
       (presentación) se ignora. ``download`` escribe en ``workdir`` (FUERA de ``outdir``), así
       que el localizador ``*.json`` de ``outdir`` solo ve la salida del scan, no el crudo IAM.
    """
    authfile = str(Path(workdir) / "default.json")
    return [
        ["cloudsplaining", "download", "--output", workdir],
        [
            "cloudsplaining",
            "scan",
            "--input-file",
            authfile,
            "--output",
            outdir,
            "--skip-open-report",
        ],
    ]


# --------------------------------------------------------------- localizadores de crudo


def _locate_newest(outdir: Path, patterns: tuple[str, ...]) -> Path | None:
    """Fichero más reciente y legible que casa alguno de los ``patterns`` (rglob)."""
    candidates: list[Path] = []
    for pattern in patterns:
        candidates.extend(p for p in outdir.rglob(pattern) if p.is_file())
    if not candidates:
        return None
    candidates.sort(key=lambda p: p.stat().st_mtime if p.exists() else 0, reverse=True)
    return candidates[0]


def _scoutsuite_locate(outdir: Path) -> Path | None:
    # ScoutSuite escribe el crudo en ``scoutsuite-results/scoutsuite_results_*.js`` (o .json
    # con --result-format json). El envoltorio ``.js`` lo tolera el normalizador del consumidor.
    return _locate_newest(
        outdir, ("scoutsuite_results_*.js", "scoutsuite_results_*.json")
    )


def _cloudsplaining_locate(outdir: Path) -> Path | None:
    # El scan de Cloudsplaining escribe DOS JSON en ``outdir`` (ambos serializados desde
    # ``authorization_details.results`` en la versión pinada 0.9.1): ``iam-results-<name>.json``
    # y ``iam-findings-<name>.json``. Los dos llevan la forma de secciones de políticas
    # (``customer_managed_policies``/``inline_policies``/``aws_managed_policies``) que el
    # normalizador (``CloudsplainingImportCollector``) sabe parsear. Se fija el prefijo de
    # forma DETERMINISTA —primero ``iam-results-*``, con ``iam-findings-*`` como respaldo— en
    # vez de "el ``*.json`` más reciente" (que, con dos ficheros, elige por mtime a ciegas y
    # puede quedarse con el crudo equivocado -> 0 findings). NUNCA el ``*.html`` (presentación)
    # ni el ``default.json`` de descarga (input del scan, FUERA de ``outdir``).
    return _locate_newest(outdir, ("iam-results-*.json",)) or _locate_newest(
        outdir, ("iam-findings-*.json",)
    )


# --------------------------------------------------------------- finalización por fuente


def _finalize_artifact(
    execution_id: str,
    outdir: Path,
    returncode: int,
    params: dict,
    *,
    source: str,
    artifact_name: str,
    locate: Callable[[Path], Path | None],
) -> dict[str, Any] | None:
    """Finaliza una collection NO-Prowler: stagea el crudo y construye el ``done``.

    NO popula el puente SSE ``set_findings`` (la salida es un documento JSON único que se
    baja por el plano de datos). Si no hay salida legible, devuelve ``None`` (el caller
    publica ``failed`` con diagnóstico).
    """
    path = locate(outdir)
    if path is None:
        return None
    meta = {
        "tool": source,
        "phase": "collection",
        "params": dict(params),
        "ts": _now_iso(),
        "returncode": returncode,
        "status": "done",
    }
    entry = artifact_store.put_file(execution_id, artifact_name, path, meta)
    return {
        "status": "done",
        "returncode": returncode,
        "timed_out": False,
        "artifact": {
            "execution_id": execution_id,
            "name": artifact_name,
            "size": entry["size"],
            "sha256": entry["sha256"],
        },
    }


def _prowler_finalize(
    execution_id: str, outdir: Path, returncode: int, params: dict
) -> dict[str, Any] | None:
    """Finaliza Prowler reutilizando ``prowler_artifact`` (stage + puente SSE + ``done``)."""
    return prowler_artifact.finalize_scan(execution_id, outdir, returncode, dict(params))


# --------------------------------------------------------------- registro de fuentes


@dataclass(frozen=True)
class CollectorSpec:
    """Contrato de un collector EN VIVO (una entrada del registro)."""

    source: str
    binary: str
    artifact_name: str
    build_commands: Callable[[str, str, str, dict], list[list[str]]]
    finalize: Callable[[str, Path, int, dict], "dict[str, Any] | None"]


def _non_bridged_finalize(
    source: str, artifact_name: str, locate: Callable[[Path], Path | None]
) -> Callable[[str, Path, int, dict], "dict[str, Any] | None"]:
    def _f(execution_id: str, outdir: Path, returncode: int, params: dict) -> "dict[str, Any] | None":
        return _finalize_artifact(
            execution_id,
            outdir,
            returncode,
            params,
            source=source,
            artifact_name=artifact_name,
            locate=locate,
        )

    return _f


REGISTRY: dict[str, CollectorSpec] = {
    "prowler": CollectorSpec(
        source="prowler",
        binary="prowler",
        artifact_name=PROWLER_ARTIFACT_NAME,
        build_commands=_prowler_commands,
        finalize=_prowler_finalize,
    ),
    "scoutsuite": CollectorSpec(
        source="scoutsuite",
        binary="scout",
        artifact_name=SCOUTSUITE_ARTIFACT_NAME,
        build_commands=_scoutsuite_commands,
        finalize=_non_bridged_finalize(
            "scoutsuite", SCOUTSUITE_ARTIFACT_NAME, _scoutsuite_locate
        ),
    ),
    "cloudsplaining": CollectorSpec(
        source="cloudsplaining",
        binary="cloudsplaining",
        artifact_name=CLOUDSPLAINING_ARTIFACT_NAME,
        build_commands=_cloudsplaining_commands,
        finalize=_non_bridged_finalize(
            "cloudsplaining", CLOUDSPLAINING_ARTIFACT_NAME, _cloudsplaining_locate
        ),
    ),
}


def available_collectors() -> dict[str, bool]:
    """Disponibilidad REAL de cada collector (``shutil.which`` del binario), sin fingir."""
    return {src: shutil.which(spec.binary) is not None for src, spec in REGISTRY.items()}


def finalize(
    source: str, execution_id: str, outdir: str | os.PathLike[str], returncode: int, params: dict | None = None
) -> dict[str, Any] | None:
    """Finaliza una collection ya ejecutada: stagea el crudo y construye el ``done``.

    Punto único reutilizable (lo usan ``run_collection`` y los tests, que stagean un crudo
    de fixture por fuente). Despacha al ``finalize`` de la fuente.
    """
    spec = REGISTRY.get(source)
    if spec is None:
        raise ValueError(f"fuente de collection desconocida: {source!r}")
    return spec.finalize(execution_id, Path(outdir), returncode, dict(params or {}))


def run_collection(
    source: str,
    account_id: str,
    execution_id: str,
    params: str = "",
    timeout: int = DEFAULT_TIMEOUT,
) -> dict[str, Any]:
    """Worker genérico: lanza la tool de ``source`` y devuelve el ``done``/``failed``.

    Corre en el hilo de ``tool_streaming.start_background`` (indexado por ``execution_id``).
    Flujo: valida binario -> ejecuta el/los comando(s) con streaming de logs en vivo y kill
    de grupo al timeout/cancelación -> localiza el crudo -> stagea como
    artefacto -> construye el ``done`` con la REFERENCIA (no la carga). Reporta ``failed`` con
    diagnóstico si no hay binario o salida legible; ``cancelled`` si el usuario cancela.
    """
    spec = REGISTRY.get(source)
    if spec is None:
        raise RuntimeError(f"fuente de collection desconocida: {source!r}")
    if shutil.which(spec.binary) is None:
        # arm64 u otra arquitectura sin la tool: se reporta, no se finge.
        raise RuntimeError(
            f"La tool {spec.binary!r} (fuente {source!r}) no está disponible en este "
            f"runtime ({os.uname().machine}); no se finge la collection."
        )

    workdir = tempfile.mkdtemp(prefix=f"{source}-")
    try:
        outdir = Path(workdir) / "out"
        outdir.mkdir(parents=True, exist_ok=True)
        commands = spec.build_commands(account_id, workdir, str(outdir), _parse_params(params))

        returncode = 0
        for cmd in commands:
            returncode, timed_out, cancelled = tool_streaming.run_tool_streaming(
                cmd, execution_id, timeout=timeout, cwd=workdir
            )
            if cancelled:
                return {"status": "cancelled", "cancelled": True, "returncode": returncode}
            if timed_out:
                return {
                    "status": "failed",
                    "timed_out": True,
                    "returncode": returncode,
                    "error": (
                        f"{source} excedió el timeout ({timeout}s). "
                        f"Últimas líneas: {_ring_tail(execution_id)}"
                    ),
                }

        done = spec.finalize(
            execution_id,
            outdir,
            returncode,
            {"account_id": account_id, "source": source},
        )
        if done is None:
            return {
                "status": "failed",
                "returncode": returncode,
                "error": (
                    f"{source} no produjo salida legible (exit={returncode}): "
                    f"{_ring_tail(execution_id)}"
                ),
            }
        return done
    finally:
        shutil.rmtree(workdir, ignore_errors=True)


def _parse_params(params: Any) -> dict:
    """Parse tolerante de los params del start_collection (string JSON opcional)."""
    if isinstance(params, dict):
        return params
    if isinstance(params, str) and params.strip():
        try:
            import json

            parsed = json.loads(params)
            return parsed if isinstance(parsed, dict) else {}
        except Exception:  # noqa: BLE001 - params libre, no fatal
            return {}
    return {}