Autonomous OODA-loop pentesting agent. Hermes brain, Kali + Playwright tools over MCP, ATT&CK as the Orient language.
Python ai-agentsautonomous-agentskali-linuxllm-agentsoffensive-securityooda-looppentestingplaywrightsecurity
"""Scope-guard OPT-IN de `kali-mcp` (STDLIB PURA) — valida el destino antes de ejecutar.
Capa DETERMINISTA (código, no prompt) que valida el destino de cada acción ofensiva de
``kali_run``/``kali_exec`` ANTES de ejecutarla. Es OPT-IN: sin un ``scope.json`` presente
y ``enabled: true``, el comportamiento actual no cambia en absoluto (passthrough). Cuando
está activo es FAIL-CLOSED: si el destino no está permitido —o si Hermes no declara
destinos— la tool falla con un error estructurado y NO ejecuta el comando.
Por qué un módulo aparte, igual que ``shell_exec.py``/``finding_store.py``:
``kali_mcp_server.py`` importa ``mcp``/``anyio`` (no están en el venv de dev). Esta
mecánica usa SOLO la librería estándar (``os``/``json``/``ipaddress``/``urllib.parse``/
``re``), así su lógica se cubre con tests unitarios sin el SDK. CERO dependencias nuevas
(ni YAML/pyyaml): el archivo de scope es ``scope.json`` y se parsea con ``json``.
Diseño (decisiones cerradas con el operador):
- Activación SOLO si el archivo (``SCOPE_FILE``, default ``/scope/scope.json``) existe y
contiene ``enabled: true``. ``SCOPE_ENFORCE=0`` es un kill-switch que fuerza desactivar.
Las env vars son SOLO interruptores booleanos; la ÚNICA fuente de datos (allow/deny/
ports) es el archivo.
- Extracción de destinos HÍBRIDA: Hermes declara ``targets`` (fuente de verdad del gate)
y, además, un parsing best-effort del comando como CINTURÓN EXTRA que solo puede
BLOQUEAR destinos obvios fuera de scope, NUNCA aprobar por sí solo.
- ESTRICTO: con scope activo y SIN ``targets`` declarados -> se bloquea (no se ejecuta).
- Validación v1: IP contra CIDRs de allow (``ipaddress``); hostname por match LITERAL
(SIN DNS; un sufijo NO coincide); puertos opcionales. deny tiene PRIORIDAD sobre allow.
La carga del archivo (I/O + parse) se separa de la validación (lógica pura sobre dicts)
para poder testear la decisión con dicts en memoria sin tocar el filesystem.
Disciplina de seguridad: el ``command`` y los ``targets`` son DATO NO CONFIABLE. El
cinturón best-effort es deliberadamente conservador (ver notas en ``evaluate``): nunca
aprueba, solo endurece. Una config corrupta con el guard activándose es un fallo de
configuración fail-closed (``ScopeError``), no un passthrough silencioso.
"""
from __future__ import annotations
import ipaddress
import json
import os
import re
from dataclasses import dataclass, field
from typing import Any, Optional, Union
from urllib.parse import urlsplit
# Ruta canónica del archivo de scope dentro del contenedor Kali (overridable por env).
DEFAULT_SCOPE_FILE = "/scope/scope.json"
# Objetos de red de la stdlib (IPv4/IPv6) devueltos por ``ipaddress.ip_network``.
_Network = Union[ipaddress.IPv4Network, ipaddress.IPv6Network]
_Address = Union[ipaddress.IPv4Address, ipaddress.IPv6Address]
class ScopeError(ValueError):
"""Config de scope inválida/corrupta (fail-closed: con el guard activo, no se ejecuta)."""
@dataclass
class Target:
"""Destino normalizado a partir de una entrada de ``targets`` o del comando.
``ip`` es un objeto ``ipaddress`` si ``host`` parsea como IP literal, o ``None`` si es
un hostname. ``port`` es el puerto explícito/inferido, o ``None`` si no hay.
"""
raw: str
host: str
ip: Optional[_Address] = None
port: Optional[int] = None
@dataclass
class ScopeConfig:
"""Configuración de scope ya compilada (redes como objetos, hosts normalizados)."""
enabled: bool
allow_cidrs: list[_Network] = field(default_factory=list)
allow_hosts: set[str] = field(default_factory=set)
deny_cidrs: list[_Network] = field(default_factory=list)
deny_hosts: set[str] = field(default_factory=set)
ports: Optional[set[int]] = None
@dataclass
class ScopeDecision:
"""Veredicto del gate. ``enforced`` es True si el guard estaba activo."""
allowed: bool
violations: list[dict[str, Any]] = field(default_factory=list)
enforced: bool = False
# ---------------------------------------------------------------- activación / carga
def is_enforcing(config: Optional[ScopeConfig]) -> bool:
"""True si el guard debe aplicar el gate.
Regla centralizada de activación: hay ``config``, está ``enabled`` y el kill-switch
``SCOPE_ENFORCE`` no es ``"0"``. Así el operador puede desactivar el guard en caliente
(``SCOPE_ENFORCE=0``) aunque el archivo diga ``enabled: true``, sin tocar el archivo.
"""
if config is None or not config.enabled:
return False
if os.environ.get("SCOPE_ENFORCE", "").strip() == "0":
return False
return True
def load_scope(path: Optional[str] = None) -> Optional[ScopeConfig]:
"""Carga el archivo de scope (I/O + parse AISLADOS de la validación de destinos).
Lee ``path`` o, si no se pasa, ``SCOPE_FILE`` (default ``/scope/scope.json``).
- Si el archivo NO existe -> devuelve ``None`` (sin gate; comportamiento actual).
- Si existe -> lo parsea con ``json.loads`` y delega en ``parse_scope``.
- Si existe pero es ilegible/JSON inválido -> ``ScopeError`` (fail-closed de config).
"""
scope_path = path or os.environ.get("SCOPE_FILE", DEFAULT_SCOPE_FILE)
if not os.path.isfile(scope_path):
return None
try:
with open(scope_path, "r", encoding="utf-8") as handle:
raw = handle.read()
data = json.loads(raw)
except (OSError, json.JSONDecodeError) as exc:
raise ScopeError(
"scope file %r ilegible o JSON inválido: %s" % (scope_path, exc)
) from exc
return parse_scope(data)
def _compile_entries(
entries: Any, where: str
) -> tuple[list[_Network], set[str]]:
"""Compila una lista de ``{cidr: ...}``/``{host: ...}`` a (redes, hosts).
Lógica PURA (sin filesystem). Entradas malformadas -> ``ScopeError`` (fail-closed de
config): un CIDR no parseable o una entrada sin ``cidr``/``host`` detiene la carga en
vez de ignorarse en silencio (una config corrupta con el guard activo no debe ejecutar).
"""
cidrs: list[_Network] = []
hosts: set[str] = set()
if entries is None:
return cidrs, hosts
if not isinstance(entries, list):
raise ScopeError("'%s' debe ser una lista de entradas {cidr}/{host}." % where)
for entry in entries:
if not isinstance(entry, dict):
raise ScopeError(
"'%s' contiene una entrada que no es objeto {cidr}/{host}: %r"
% (where, entry)
)
if "cidr" in entry:
value = entry["cidr"]
if not isinstance(value, str) or not value.strip():
raise ScopeError("'%s' tiene un 'cidr' vacío o no-string." % where)
try:
cidrs.append(ipaddress.ip_network(value.strip(), strict=False))
except ValueError as exc:
raise ScopeError(
"'%s' tiene un CIDR inválido %r: %s" % (where, value, exc)
) from exc
elif "host" in entry:
value = entry["host"]
if not isinstance(value, str) or not value.strip():
raise ScopeError("'%s' tiene un 'host' vacío o no-string." % where)
hosts.add(value.strip())
else:
raise ScopeError(
"'%s' tiene una entrada sin 'cidr' ni 'host': %r" % (where, entry)
)
return cidrs, hosts
def parse_scope(data: Any) -> ScopeConfig:
"""Valida y compila un dict de scope a ``ScopeConfig`` (lógica PURA, testeable).
Reglas (fail-closed de configuración):
- ``data`` es un objeto JSON (dict).
- ``enabled`` es bool (default ``False`` si falta).
- ``allow``/``deny`` son listas de ``{cidr}``/``{host}`` (compiladas con ``ipaddress``).
- ``ports``, si viene, es una lista de enteros (puertos permitidos). Lista vacía o
ausente -> ``None`` (cualquier puerto permitido para un host permitido).
"""
if not isinstance(data, dict):
raise ScopeError("scope inválido: se espera un objeto JSON en la raíz.")
enabled = data.get("enabled", False)
if not isinstance(enabled, bool):
raise ScopeError("scope inválido: 'enabled' debe ser booleano.")
allow_cidrs, allow_hosts = _compile_entries(data.get("allow"), "allow")
deny_cidrs, deny_hosts = _compile_entries(data.get("deny"), "deny")
ports_raw = data.get("ports")
ports: Optional[set[int]] = None
if ports_raw is not None:
if not isinstance(ports_raw, list):
raise ScopeError("scope inválido: 'ports' debe ser una lista de enteros.")
compiled_ports: set[int] = set()
for port in ports_raw:
# bool es subclase de int; se excluye explícitamente para no aceptar True/False.
if isinstance(port, bool) or not isinstance(port, int) or not (0 <= port <= 65535):
raise ScopeError(
"scope inválido: 'ports' contiene un valor que no es puerto: %r" % (port,)
)
compiled_ports.add(port)
if compiled_ports:
ports = compiled_ports
return ScopeConfig(
enabled=enabled,
allow_cidrs=allow_cidrs,
allow_hosts=allow_hosts,
deny_cidrs=deny_cidrs,
deny_hosts=deny_hosts,
ports=ports,
)
# ---------------------------------------------------------------- normalización destinos
_SCHEME_DEFAULT_PORTS = {"http": 80, "https": 443}
# host:port sin esquema (host es dominio/IPv4; IPv6 se maneja con la forma [..]:port).
_HOSTPORT_RE = re.compile(r"^(?P<host>[^\s/:]+):(?P<port>\d{1,5})$")
_IPV6_HOSTPORT_RE = re.compile(r"^\[(?P<host>[0-9A-Fa-f:]+)\](?::(?P<port>\d{1,5}))?$")
def _as_ip(host: str) -> Optional[_Address]:
"""Devuelve el objeto IP si ``host`` parsea como IP literal, o ``None`` (hostname)."""
try:
return ipaddress.ip_address(host)
except ValueError:
return None
def normalize_target(raw: str) -> Target:
"""Normaliza una entrada (IP/host/URL/host:port) a ``Target``. Pura y testeable.
Acepta:
- IP literal: ``"8.8.8.8"``, ``"::1"``.
- Hostname: ``"juice-shop"`` (match LITERAL contra allow hosts).
- URL: ``"http://juice-shop:3000/x"``, ``"https://10.0.0.5"`` (puerto del ``:port``
explícito o inferido del esquema solo a efectos de la comprobación de ``ports``).
- host:port sin esquema: ``"10.0.0.5:8080"``, ``"juice-shop:3000"``, ``"[::1]:8080"``.
"""
token = (raw or "").strip()
host = token
port: Optional[int] = None
# URL con esquema (http/https/...): usar urlsplit para separar host/puerto.
if "://" in token:
parts = urlsplit(token)
if parts.hostname:
host = parts.hostname
if parts.port is not None:
port = parts.port
elif parts.scheme in _SCHEME_DEFAULT_PORTS:
port = _SCHEME_DEFAULT_PORTS[parts.scheme]
return Target(raw=raw, host=host, ip=_as_ip(host), port=port)
# IPv6 con/ sin puerto en forma [..]:port.
m6 = _IPV6_HOSTPORT_RE.match(token)
if m6:
host = m6.group("host")
if m6.group("port"):
port = int(m6.group("port"))
return Target(raw=raw, host=host, ip=_as_ip(host), port=port)
# IP literal directa (IPv4 o IPv6 sin corchetes): no partir por ':' (rompería IPv6).
direct_ip = _as_ip(token)
if direct_ip is not None:
return Target(raw=raw, host=token, ip=direct_ip, port=None)
# host:port sin esquema (host no-IPv6).
mhp = _HOSTPORT_RE.match(token)
if mhp:
host = mhp.group("host")
port = int(mhp.group("port"))
return Target(raw=raw, host=host, ip=_as_ip(host), port=port)
# Hostname literal (o lo que quede): sin puerto.
return Target(raw=raw, host=host, ip=None, port=port)
# Tokens candidatos a IP/URL/host:port en el comando (cinturón best-effort, conservador).
_CMD_IPV4_RE = re.compile(r"\b(?:\d{1,3}\.){3}\d{1,3}\b")
_CMD_URL_RE = re.compile(r"\bhttps?://[^\s'\"]+", re.IGNORECASE)
def extract_targets_from_command(command: str) -> list[Target]:
"""Parsing BEST-EFFORT del comando -> lista de ``Target`` (posiblemente vacía).
CINTURÓN EXTRA (decisión 3): su salida solo se usa para BLOQUEAR destinos obvios fuera
de scope, NUNCA para aprobar. Deliberadamente conservador: extrae URLs ``http(s)://`` y
tokens que parezcan IPv4 literales. No intenta un parser de shell completo (una IP
ofuscada/construida por el comando puede no detectarse -> falso negativo; por eso la
fuente de verdad es ``targets``, que Hermes DEBE declarar con scope activo).
"""
if not isinstance(command, str) or not command:
return []
found: list[Target] = []
seen: set[str] = set()
for match in _CMD_URL_RE.findall(command):
token = match.rstrip(".,;)")
if token not in seen:
seen.add(token)
found.append(normalize_target(token))
for match in _CMD_IPV4_RE.findall(command):
if match in seen:
continue
# Solo IPv4 bien formadas (descarta "1.2.3.4" que no sea IP válida, p. ej. 999.*).
ip = _as_ip(match)
if ip is None:
continue
seen.add(match)
found.append(Target(raw=match, host=match, ip=ip, port=None))
return found
# ---------------------------------------------------------------- decisión del gate
def _in_cidrs(ip: _Address, cidrs: list[_Network]) -> bool:
for net in cidrs:
try:
if ip in net:
return True
except TypeError:
# Comparación IPv4 vs IPv6: no aplica, se ignora.
continue
return False
def _check_target(config: ScopeConfig, target: Target) -> Optional[dict[str, Any]]:
"""Evalúa un target contra el scope. Devuelve una violación (dict) o ``None`` si pasa.
Orden: deny PRIMERO (prioridad); luego allow (IP en cidr O host literal); luego ports
(solo si el target trae puerto y hay ``ports`` definido).
"""
# deny tiene prioridad: si cae en deny -> fuera de scope.
if target.ip is not None and _in_cidrs(target.ip, config.deny_cidrs):
return {"target": target.raw, "reason": "target en deny (CIDR)"}
if target.host in config.deny_hosts:
return {"target": target.raw, "reason": "target en deny (host)"}
# allow: IP en algún cidr permitido O host literal en allow.
in_allow = False
if target.ip is not None and _in_cidrs(target.ip, config.allow_cidrs):
in_allow = True
elif target.host in config.allow_hosts:
in_allow = True
if not in_allow:
return {"target": target.raw, "reason": "target fuera de allow"}
# ports (opcional): solo se exige si el target trae puerto y hay ports definido.
if config.ports is not None and target.port is not None and target.port not in config.ports:
return {
"target": target.raw,
"reason": "puerto %d fuera de ports permitidos" % target.port,
}
return None
def evaluate(
config: Optional[ScopeConfig],
declared_targets: Optional[list[str]],
command: str,
) -> ScopeDecision:
"""Núcleo del gate. Decide si la ejecución puede proceder.
Reglas, en orden:
1. Si el guard no está activo (``is_enforcing`` False) -> passthrough
(``allowed=True, enforced=False``). Compat total con el comportamiento actual.
2. Scope activo y SIN ``targets`` declarados -> bloquea (decisión estricta): Hermes
DEBE declarar los destinos del comando.
3. Cada target declarado se normaliza y evalúa (``_check_target``). Cualquier target
fuera de scope añade una violación.
4. CINTURÓN EXTRA: destinos extraídos del comando que caigan en deny, o que sean IP y
no caigan en ningún allow, añaden violación. Nunca aprueban por sí solos.
5. Si hay cualquier violación -> ``allowed=False``.
"""
if not is_enforcing(config):
return ScopeDecision(allowed=True, violations=[], enforced=False)
assert config is not None # is_enforcing garantiza config no-None
violations: list[dict[str, Any]] = []
if not declared_targets:
violations.append(
{
"target": None,
"reason": (
"scope activo pero no se declararon 'targets'; declara las "
"IP/host/URL destino de este comando"
),
}
)
return ScopeDecision(allowed=False, violations=violations, enforced=True)
# (3) Validar los targets declarados (fuente de verdad del gate).
for raw in declared_targets:
target = normalize_target(raw)
violation = _check_target(config, target)
if violation is not None:
violations.append(violation)
# (4) Cinturón extra: solo BLOQUEA destinos obvios del comando, nunca aprueba.
for extracted in extract_targets_from_command(command):
if extracted.ip is not None and _in_cidrs(extracted.ip, config.deny_cidrs):
violations.append(
{
"target": extracted.raw,
"reason": "destino detectado en el comando cae en deny (CIDR)",
}
)
continue
if extracted.ip is not None and not _in_cidrs(extracted.ip, config.allow_cidrs):
violations.append(
{
"target": extracted.raw,
"reason": (
"IP detectada en el comando fuera de allow (declárala en "
"'targets' si es intencionada)"
),
}
)
return ScopeDecision(
allowed=not violations, violations=violations, enforced=True
)
def _allowed_summary(config: ScopeConfig) -> str:
"""Resumen legible de lo permitido (cidrs + hosts) para el mensaje de violación."""
parts: list[str] = [str(net) for net in config.allow_cidrs]
parts.extend(sorted(config.allow_hosts))
summary = ", ".join(parts) if parts else "(nada)"
if config.ports is not None:
summary += " | ports: %s" % ", ".join(str(p) for p in sorted(config.ports))
return summary
def format_violation_message(decision: ScopeDecision, config: ScopeConfig) -> str:
"""Construye el texto ``SCOPE_VIOLATION: ...`` del error estructurado.
Para "sin targets" produce el mensaje pidiendo declarar ``targets``; para targets fuera
de scope lista el/los destino(s) rechazado(s) y el resumen de lo permitido.
"""
no_targets = any(v.get("target") is None for v in decision.violations)
if no_targets:
return (
"SCOPE_VIOLATION: scope is active but no 'targets' were declared; "
"declare the IP/host/URL targets of this command"
)
seen: list[str] = []
for v in decision.violations:
target = v.get("target")
if target is not None and str(target) not in seen:
seen.append(str(target))
rejected = ", ".join(seen)
return (
"SCOPE_VIOLATION: target %s is outside allowed scope (allowed: %s)"
% (rejected, _allowed_summary(config))
)