vfa-mcp 1.0.0__py3-none-any.whl

app/__init__.py

@@ -0,0 +1 @@
+"""Agente Visual & Functional Auditor (VFA): modulos de configuracion, navegador, captura, vision, semantica y tools MCP."""

app/adapters/__init__.py

@@ -0,0 +1 @@
+"""Adaptadores de infraestructura (navegador y LLM)."""

app/adapters/browser/__init__.py

@@ -0,0 +1,30 @@
+"""Adaptadores de navegador basados en Playwright."""
+
+from app.adapters.browser.capture import ErrorCapture, attach_capture
+from app.adapters.browser.playwright_adapter import (
+    PlaywrightBrowserAdapter,
+    PlaywrightSession,
+    is_session_dead,
+)
+from app.adapters.browser.session_pool import (
+    SessionPool,
+    get_current_session_id,
+    get_session_pool,
+    new_session_id,
+    reset_current_session_id,
+    set_current_session_id,
+)
+
+__all__ = [
+    "ErrorCapture",
+    "PlaywrightBrowserAdapter",
+    "PlaywrightSession",
+    "SessionPool",
+    "attach_capture",
+    "get_current_session_id",
+    "get_session_pool",
+    "is_session_dead",
+    "new_session_id",
+    "reset_current_session_id",
+    "set_current_session_id",
+]

app/adapters/browser/capture.py

@@ -0,0 +1,102 @@
+"""Capturador de errores de runtime: console.error, pageerror y HTTP >= 400."""
+
+from __future__ import annotations
+
+from typing import Any, Iterable, List
+
+from app.domain.models import CONSOLE, HTTP, PAGE_ERROR, RuntimeErrorEvent
+
+_MAX_EVENTS = 200
+
+
+class ErrorCapture:
+    """Acumula `RuntimeErrorEvent` de una pagina Playwright.
+
+    Es deliberadamente agnostico del driver: solo necesita objetos con
+    atributos `type`, `text` o `message`, lo que permite usar dobles en los
+    tests sin levantar un navegador real.
+    """
+
+    def __init__(self, max_events: int = _MAX_EVENTS) -> None:
+        self._events: List[RuntimeErrorEvent] = []
+        self._max_events = max_events
+
+    # ---------------------------------------------------------------- registro
+    def _push(self, event: RuntimeErrorEvent) -> None:
+        if len(self._events) < self._max_events:
+            self._events.append(event)
+
+    def record_console(self, message: Any) -> None:
+        """Registra un mensaje de consola solo si es un error."""
+        msg_type = str(getattr(message, "type", "") or "").lower()
+        if msg_type not in ("error", "warning", "assert"):
+            return
+        if msg_type != "error":
+            return
+        text = str(getattr(message, "text", "") or getattr(message, "message", ""))
+        location = getattr(message, "location", None) or {}
+        url = ""
+        if isinstance(location, dict):
+            url = str(location.get("url") or "")
+        self._push(RuntimeErrorEvent(kind=CONSOLE, message=text, url=url))
+
+    def record_page_error(self, error: Any) -> None:
+        """Registra una excepcion JavaScript no capturada."""
+        text = str(getattr(error, "message", None) or error)
+        self._push(RuntimeErrorEvent(kind=PAGE_ERROR, message=text))
+
+    def record_response(self, response: Any) -> None:
+        """Registra respuestas HTTP con status >= 400."""
+        status = getattr(response, "status", None)
+        try:
+            status_int = int(status)
+        except (TypeError, ValueError):
+            return
+        if status_int < 400:
+            return
+        url = str(getattr(response, "url", "") or "")
+        self._push(
+            RuntimeErrorEvent(
+                kind=HTTP,
+                message=f"HTTP {status_int} {url}".strip(),
+                url=url,
+                status=status_int,
+            )
+        )
+
+    # ---------------------------------------------------------------- consulta
+    def events(self) -> List[RuntimeErrorEvent]:
+        return list(self._events)
+
+    def as_dicts(self) -> List[dict]:
+        return [event.to_dict() for event in self._events]
+
+    def drain(self) -> List[RuntimeErrorEvent]:
+        """Devuelve y limpia los eventos acumulados."""
+        pending = self._events
+        self._events = []
+        return pending
+
+    def clear(self) -> None:
+        self._events = []
+
+    def __len__(self) -> int:
+        return len(self._events)
+
+
+def attach_capture(page: Any, capture: ErrorCapture) -> ErrorCapture:
+    """Engancha los listeners de Playwright a un `ErrorCapture`."""
+    on = getattr(page, "on", None)
+    if callable(on):
+        on("console", capture.record_console)
+        on("pageerror", capture.record_page_error)
+        on("response", capture.record_response)
+    return capture
+
+
+def merge_events(*groups: Iterable[RuntimeErrorEvent]) -> List[RuntimeErrorEvent]:
+    """Fusiona varios grupos de eventos preservando el orden de llegada."""
+    merged: List[RuntimeErrorEvent] = []
+    for group in groups:
+        merged.extend(group or [])
+    return merged

app/adapters/browser/network_guard.py

@@ -0,0 +1,229 @@
+"""Firewall Anti-SSRF para contextos efimeros de Playwright.
+
+El dominio de este modulo es puro: recibe un host y decide si es enrutable en
+Internet o si pertenece a loopback / rangos privados / metadata de nube. El
+adaptador de navegador instala el interceptor ``context.route("**/*")``.
+"""
+
+from __future__ import annotations
+
+import ipaddress
+import logging
+from typing import Any, Iterable, Optional
+from urllib.parse import urlparse
+import inspect
+
+logger = logging.getLogger(__name__)
+
+BLOCKED_ABORT_REASON = "accessdenied"
+
+#: Hostnames bloqueados de forma explicita (loopback, wildcards y metadata cloud).
+BLOCKED_HOSTNAMES: frozenset[str] = frozenset(
+    {
+        "localhost",
+        "localhost.localdomain",
+        "ip6-localhost",
+        "ip6-loopback",
+        "metadata",
+        "metadata.google.internal",
+        "metadata.goog",
+        "instance-data",
+        "0.0.0.0",
+        "::",
+        "::1",
+    }
+)
+#: Hostnames de loopback/local permitidos en modo desarrollador local.
+LOCAL_HOSTNAMES: frozenset[str] = frozenset(
+    {
+        "localhost",
+        "localhost.localdomain",
+        "ip6-localhost",
+        "ip6-loopback",
+        "0.0.0.0",
+        "::",
+        "::1",
+    }
+)
+
+#: Hostnames de metadata cloud: bloqueo incondicional (nunca es un sitio web).
+METADATA_HOSTNAMES: frozenset[str] = frozenset(
+    {
+        "metadata",
+        "metadata.google.internal",
+        "metadata.goog",
+        "instance-data",
+    }
+)
+
+#: Redes privadas, de loopback, link-local y de metadata (RFC 1918/5735/6890).
+BLOCKED_NETWORKS: tuple[Any, ...] = tuple(
+    ipaddress.ip_network(cidr)
+    for cidr in (
+        "0.0.0.0/8",
+        "10.0.0.0/8",
+        "100.64.0.0/10",
+        "127.0.0.0/8",
+        "169.254.0.0/16",
+        "172.16.0.0/12",
+        "192.0.0.0/24",
+        "192.168.0.0/16",
+        "198.18.0.0/15",
+        "::1/128",
+        "fc00::/7",
+        "fe80::/10",
+    )
+)
+
+#: Redes de infraestructura privada permitidas cuando VFA_ALLOW_LOCAL_HOST=true.
+LOCAL_INFRA_NETWORKS: tuple[Any, ...] = tuple(
+    ipaddress.ip_network(cidr)
+    for cidr in ("10.0.0.0/8", "172.16.0.0/12", "192.168.0.0/16")
+)
+
+#: Endpoints de metadata cloud: SIEMPRE bloqueados, incluso en modo local.
+METADATA_NETWORKS: tuple[Any, ...] = (ipaddress.ip_network("169.254.0.0/16"),)
+
+#: Esquemas sin host enrutable que jamas deben salir por la red.
+BLOCKED_SCHEMES: frozenset[str] = frozenset({"file", "about", "data", "blob", "chrome"})
+
+
+def _normalize_host(host: str) -> str:
+    """Normaliza un host: minusculas, sin corchetes IPv6 ni punto final."""
+    value = (host or "").strip().lower()
+    if value.startswith("[") and value.endswith("]"):
+        value = value[1:-1]
+    return value.rstrip(".")
+
+
+def _as_address(value: str) -> Optional[Any]:
+    """Parsea ``value`` como direccion IP o devuelve None si es un dominio."""
+    try:
+        return ipaddress.ip_address(value)
+    except ValueError:
+        return None
+
+
+def is_local_host(host: str) -> bool:
+    """Indica si el host es loopback, ``localhost`` o un dominio ``*.local``."""
+    value = _normalize_host(host)
+    if not value:
+        return False
+    if value in LOCAL_HOSTNAMES:
+        return True
+    if value.endswith(".localhost") or value.endswith(".local"):
+        return True
+    address = _as_address(value)
+    if address is None:
+        return False
+    return bool(address.is_loopback or address.is_unspecified)
+
+
+def is_metadata_host(host: str) -> bool:
+    """Indica si el host apunta a metadata cloud (bloqueo incondicional)."""
+    value = _normalize_host(host)
+    if not value:
+        return False
+    if value in METADATA_HOSTNAMES:
+        return True
+    address = _as_address(value)
+    if address is None:
+        return False
+    return any(address in network for network in METADATA_NETWORKS)
+
+
+def is_private_infra_host(host: str) -> bool:
+    """Indica si el host pertenece a una red privada RFC 1918 (intranet)."""
+    address = _as_address(_normalize_host(host))
+    if address is None:
+        return False
+    return any(address in network for network in LOCAL_INFRA_NETWORKS)
+
+
+def is_blocked_host(host: str, allow_local: bool = False) -> bool:
+    """Indica si ``host`` (nombre o IP) apunta a la intranet o al propio host.
+
+    Con ``allow_local=True`` (modo desarrollador local) se permite loopback,
+    ``localhost``, dominios ``*.local`` y redes privadas RFC 1918, pero se
+    mantiene el bloqueo de los endpoints de metadata cloud.
+    """
+    value = _normalize_host(host)
+    if not value:
+        # Un host vacio no es enrutable: se trata como bloqueado.
+        return True
+    if is_metadata_host(value):
+        return True
+    if allow_local and (is_local_host(value) or is_private_infra_host(value)):
+        return False
+    if value in BLOCKED_HOSTNAMES:
+        return True
+    if value.endswith(".localhost") or value.endswith(".internal"):
+        return True
+    address = _as_address(value)
+    if address is None:
+        return False  # Dominio publico: se permite el intento.
+    if any(address in network for network in BLOCKED_NETWORKS):
+        return True
+    return bool(
+        address.is_private
+        or address.is_loopback
+        or address.is_link_local
+        or address.is_reserved
+        or address.is_multicast
+    )
+
+
+def is_blocked_url(url: str, allow_local: bool = False) -> bool:
+    """Indica si la URL es insegura (SSRF) y debe abortarse antes de salir."""
+    try:
+        parsed = urlparse(url or "")
+    except ValueError:
+        return True
+    scheme = (parsed.scheme or "").lower()
+    if scheme in BLOCKED_SCHEMES:
+        return True
+    if scheme not in ("http", "https", "ws", "wss"):
+        return True
+    return is_blocked_host(parsed.hostname or "", allow_local=allow_local)
+
+
+def blocked_urls(urls: Iterable[str], allow_local: bool = False) -> list[str]:
+    """Utilidad de diagnostico: retorna el subconjunto de URLs bloqueadas."""
+    return [url for url in urls if is_blocked_url(url, allow_local=allow_local)]
+
+
+def _guard_route(allow_local: bool = False) -> Any:
+    """Construye el handler de ``context.route`` con la politica Anti-SSRF dada."""
+
+    async def handler(route: Any, request: Any) -> None:
+        try:
+            url = str(getattr(request, "url", "") or "")
+        except Exception:  # pragma: no cover - driver opcional
+            url = ""
+        if is_blocked_url(url, allow_local=allow_local):
+            logger.warning("SSRF bloqueado: %s", url or "<url desconocida>")
+            await route.abort(BLOCKED_ABORT_REASON)
+            return
+        await route.continue_()
+
+    return handler
+
+
+async def attach_ssrf_guard(context: Any, allow_local: bool = False) -> Optional[Any]:
+    """Instala el interceptor Anti-SSRF en el contexto (si soporta routing)."""
+    registrar = getattr(context, "route", None)
+    if not callable(registrar):
+        return None
+    try:
+        res = registrar("**/*", _guard_route(allow_local=allow_local))
+        if inspect.isawaitable(res):
+            await res
+        return res
+    except Exception:  # pragma: no cover - contexto ya cerrado
+        logger.debug("No se pudo instalar el firewall Anti-SSRF", exc_info=True)
+        return None
+
+
+def route_handler(allow_local: bool = False) -> Any:
+    """Expone el handler para pruebas unitarias sin I/O real."""
+    return _guard_route(allow_local=allow_local)

app/adapters/browser/playwright_adapter.py

@@ -0,0 +1,329 @@
+"""Adaptador Playwright: Chromium local sandboxed (motor unico, sin Docker).
+
+Cada sesion se ejecuta en un ``BrowserContext`` efimero en memoria con firewall
+Anti-SSRF instalado; no se persiste cache, cookies ni almacenamiento en disco.
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Any, Dict, List, Optional, Tuple
+
+from app import config
+from app.adapters.browser.capture import ErrorCapture, attach_capture
+from app.adapters.browser.network_guard import attach_ssrf_guard
+from app.adapters.browser.visual_primitives import VisualPrimitivesMixin
+from app.domain.models import RuntimeErrorEvent
+
+logger = logging.getLogger(__name__)
+
+_VIEWPORT = {"width": 1280, "height": 720}
+
+TIMEOUT_ACTIONS = config.get_action_timeout_ms()
+
+#: Flags de aislamiento estricto aplicadas al arranque de Chromium.
+SECURE_LAUNCH_FLAGS: Tuple[str, ...] = (
+    "--disable-background-networking",
+    "--disable-default-apps",
+    "--disable-sync",
+    "--no-first-run",
+    "--hide-scrollbars",
+    "--disable-component-update",
+    "--disable-domain-reliability",
+    "--no-default-browser-check",
+    "--disable-dev-shm-usage",
+)
+
+#: Opciones del contexto efimero: sin persistencia ni permisos implicitos.
+EPHEMERAL_CONTEXT_OPTIONS: Dict[str, Any] = {
+    "viewport": dict(_VIEWPORT),
+    "ignore_https_errors": False,
+    "bypass_csp": False,
+    "accept_downloads": False,
+    "java_script_enabled": True,
+}
+
+
+class BrowserLaunchError(RuntimeError):
+    """Error irrecuperable al inicializar el navegador."""
+
+
+def is_session_dead(browser: Any, page: Any) -> bool:
+    """Detecta si la pagina o el navegador se cerraron (defensivo ante fakes)."""
+    try:
+        is_closed = getattr(page, "is_closed", None)
+        if callable(is_closed) and is_closed():
+            return True
+        is_connected = getattr(browser, "is_connected", None)
+        if callable(is_connected) and not is_connected():
+            return True
+    except Exception:  # pragma: no cover - defensivo
+        return True
+    return False
+
+
+class PlaywrightSession(VisualPrimitivesMixin):
+    """Sesion activa que implementa `BrowserSessionPort` sobre Playwright."""
+
+    def __init__(
+        self,
+        browser: Any,
+        page: Any,
+        playwright: Any = None,
+        capture: Optional[ErrorCapture] = None,
+        mode: str = "local",
+        context: Any = None,
+    ) -> None:
+        self.browser = browser
+        self.page = page
+        self.playwright = playwright
+        self.mode = mode
+        self.context = context
+        self.capture = attach_capture(page, capture or ErrorCapture())
+
+    # ------------------------------------------------------------- navegacion
+    async def goto(self, url: str, timeout: int = 30000) -> None:
+        await self.page.goto(url, wait_until="domcontentloaded", timeout=timeout)
+
+    async def url(self) -> str:
+        value = getattr(self.page, "url", "")
+        return value() if callable(value) else str(value or "")
+
+    async def title(self) -> str:
+        getter = getattr(self.page, "title", None)
+        if callable(getter):
+            return str(await getter())
+        return ""
+
+    async def screenshot_b64(self, full_page: bool = True) -> str:
+        import base64
+
+        data = await self.page.screenshot(full_page=full_page)
+        if isinstance(data, str):
+            return data
+        return base64.b64encode(data).decode("utf-8")
+
+    async def accessibility_snapshot(self) -> Any:
+        snapshot = getattr(self.page, "accessibility", None)
+        if snapshot is not None and hasattr(snapshot, "snapshot"):
+            try:
+                return await snapshot.snapshot()
+            except Exception:  # pragma: no cover - driver opcional
+                return None
+        try:
+            return await self.page.locator("body").aria_snapshot()
+        except Exception:  # pragma: no cover - driver opcional
+            return None
+
+    # --------------------------------------------------------------- acciones
+    async def click(
+        self, selector: str, timeout: int = TIMEOUT_ACTIONS
+    ) -> Dict[str, Any]:
+        await self.page.click(selector, timeout=timeout)
+        return {"action": "click", "selector": selector, "ok": True}
+
+    async def fill(
+        self, selector: str, value: str, timeout: int = TIMEOUT_ACTIONS
+    ) -> Dict[str, Any]:
+        await self.page.fill(selector, value, timeout=timeout)
+        return {"action": "fill", "selector": selector, "value": value, "ok": True}
+
+    async def press(self, key: str) -> Dict[str, Any]:
+        await self.page.keyboard.press(key)
+        return {"action": "press", "value": key, "ok": True}
+
+    async def scroll(self, direction: str = "down") -> Dict[str, Any]:
+        delta = 900 if str(direction).lower() != "up" else -900
+        await self.page.mouse.wheel(0, delta)
+        return {"action": "scroll", "value": direction, "ok": True}
+
+    async def wait(self, seconds: float) -> Dict[str, Any]:
+        await self.page.wait_for_timeout(max(int(float(seconds) * 1000), 0))
+        return {"action": "wait", "value": seconds, "ok": True}
+
+    async def text_content(self) -> str:
+        try:
+            return str(await self.page.inner_text("body"))
+        except Exception:  # pragma: no cover - pagina sin body
+            return ""
+
+    # --------------------------------------------------------------- cookies
+    async def cookies(self) -> List[Dict[str, Any]]:
+        for holder in (self.context, self.browser):
+            provider = getattr(holder, "cookies", None)
+            if callable(provider):
+                try:
+                    return list(await provider())
+                except Exception:  # pragma: no cover
+                    return []
+        return []
+
+    async def restore(self, cookies: List[Dict[str, Any]], url: str = "") -> None:
+        for holder in (self.context, self.browser):
+            adder = getattr(holder, "add_cookies", None)
+            if callable(adder) and cookies:
+                try:
+                    await adder(cookies)
+                except Exception:  # pragma: no cover
+                    logger.debug("No se pudieron restaurar cookies", exc_info=True)
+                break
+        if url:
+            await self.goto(url)
+
+    async def close(self) -> None:
+        """Destruye la pagina y el contexto efimero (nada persiste en disco)."""
+        closer = getattr(self.page, "close", None)
+        if callable(closer):
+            try:
+                await closer()
+            except Exception:  # pragma: no cover - pagina ya cerrada
+                pass
+        context_closer = getattr(self.context, "close", None)
+        if callable(context_closer):
+            try:
+                await context_closer()
+            except Exception:  # pragma: no cover - contexto ya cerrado
+                pass
+        self.context = None
+
+    def is_dead(self) -> bool:
+        return is_session_dead(self.browser, self.page)
+
+
+class PlaywrightBrowserAdapter:
+    """Gestor del navegador: Chromium local sandboxed y CDP opcional generico."""
+
+    def __init__(self, playwright_manager: Any = None) -> None:
+        self._manager = playwright_manager
+        self._playwright: Any = None
+        self._browser: Any = None
+        self._capture = ErrorCapture()
+        self._orphan_contexts: List[Any] = []
+        self.mode = "local"
+
+    # ------------------------------------------------------------- internos
+    async def _ensure_playwright(self) -> Any:
+        if self._playwright is None:
+            if self._manager is None:
+                from playwright.async_api import async_playwright
+
+                self._manager = async_playwright()
+            self._playwright = await self._manager.start()
+        return self._playwright
+
+    def _launch_args(self) -> Dict[str, Any]:
+        """Argumentos de arranque: siempre con flags de aislamiento estricto."""
+        headless = config.get_headless()
+        args = {"headless": headless, "args": list(SECURE_LAUNCH_FLAGS)}
+        if not headless:
+            args["args"].append("--start-maximized")
+        return args
+
+    async def connect(self) -> Any:
+        """Arranca Chromium local o intenta un CDP generico configurado."""
+        playwright = await self._ensure_playwright()
+        remote_url = config.get_browser_cdp_url()
+        if remote_url:
+            timeout = config.get_cdp_timeout_ms()
+            try:
+                self._browser = await playwright.chromium.connect_over_cdp(
+                    remote_url, timeout=timeout
+                )
+                self.mode = "cdp"
+                logger.info("Navegador conectado via CDP: %s", remote_url)
+                return self._browser
+            except Exception as exc:
+                logger.warning(
+                    "Conexion CDP fallida (%s); fallback a Chromium local", exc
+                )
+        self._browser = await playwright.chromium.launch(**self._launch_args())
+        self.mode = "local"
+        return self._browser
+
+    async def _ensure_browser(self) -> None:
+        if self._browser is None or is_session_dead(self._browser, None):
+            await self.connect()
+
+    async def _new_context(self) -> Any:
+        """Crea un contexto efimero en memoria con firewall Anti-SSRF.
+
+        La politica Anti-SSRF respeta ``VFA_ALLOW_LOCAL_HOST``: en modo
+        desarrollador local se permite auditar ``localhost`` y ``*.local``.
+        """
+        await self._ensure_browser()
+        creator = getattr(self._browser, "new_context", None)
+        if not callable(creator):
+            return None
+        try:
+            context = await creator(**EPHEMERAL_CONTEXT_OPTIONS)
+        except TypeError:  # pragma: no cover - implementaciones parciales
+            context = await creator()
+        await attach_ssrf_guard(context, allow_local=config.get_allow_local_host())
+        return context
+
+    async def _new_page(self) -> Any:
+        context = await self._new_context()
+        if context is not None:
+            self._orphan_contexts.append(context)
+            return await context.new_page()
+        await self._ensure_browser()
+        return await self._browser.new_page(viewport=dict(_VIEWPORT))
+
+    # --------------------------------------------------------------- publicos
+    async def new_page(self) -> Any:
+        """Pagina suelta en su propio contexto efimero (cerrado en `reset`)."""
+        return await self._new_page()
+
+    async def open_session(self) -> PlaywrightSession:
+        context = await self._new_context()
+        if context is not None:
+            page = await context.new_page()
+        else:  # pragma: no cover - fallback defensivo
+            await self._ensure_browser()
+            page = await self._browser.new_page(viewport=dict(_VIEWPORT))
+        return PlaywrightSession(
+            browser=self._browser,
+            page=page,
+            playwright=self._playwright,
+            capture=self._capture,
+            mode=self.mode,
+            context=context,
+        )
+
+    async def close_session(self, session: Optional[PlaywrightSession] = None) -> None:
+        if session is not None:
+            await session.close()
+
+    def drain_errors(self) -> List[RuntimeErrorEvent]:
+        return self._capture.drain()
+
+    def peek_errors(self) -> List[RuntimeErrorEvent]:
+        return self._capture.events()
+
+    async def reset(self) -> None:
+        """Fuerza la reconexion en el siguiente `open_session`."""
+        for context in self._orphan_contexts:
+            closer = getattr(context, "close", None)
+            if callable(closer):
+                try:
+                    await closer()
+                except Exception:  # pragma: no cover - contexto ya cerrado
+                    pass
+        self._orphan_contexts.clear()
+        if self._browser is not None:
+            try:
+                await self._browser.close()
+            except Exception:  # pragma: no cover - navegador ya muerto
+                pass
+        self._browser = None
+
+    async def shutdown(self) -> None:
+        await self.reset()
+        if self._playwright is not None:
+            stopper = getattr(self._playwright, "stop", None)
+            if callable(stopper):
+                try:
+                    await stopper()
+                except Exception:  # pragma: no cover
+                    pass
+        self._playwright = None