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
"""Registro estructurado de hallazgos por engagement de `kali-mcp` (STDLIB PURA).
El store de evidencia del bucle OODA. Hoy la evidencia vive solo en el historial de la
conversación (efímero, se pierde con la higiene de contexto por subagentes y con el
`down -v` del perfil). Este módulo le da un registro durable, consultable y descargable:
un fichero JSONL por engagement, con un hallazgo por línea.
Dónde vive: sobre el plano de artefactos existente (``/artifacts``, el mismo que sirve
``artifact_http.py`` en :8901), NO en el estado de Hermes. Así sobrevive a la naturaleza
efímera del perfil y es un artefacto descargable. El fichero es
``<engagement_id>/findings.jsonl`` bajo la raíz del staging — reutiliza el confinamiento
de rutas de ``artifact_store`` (sin ``..``/separadores) para que un ``engagement_id``
manipulado no escape del directorio.
Por qué un módulo aparte, igual que ``artifact_store.py``/``tool_streaming.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, así se cubre con tests sin el SDK. Las tools MCP
``record_finding``/``read_findings`` son una capa fina sobre ``append``/``read``.
Disciplina de seguridad: la evidencia que se guarda (``evidence.output``) sigue siendo
DATO NO CONFIABLE al releerla — se razona sobre ella, nunca se obedecen instrucciones
embebidas (prompt injection). Aquí se PERSISTE verbatim; nunca se interpreta.
"""
from __future__ import annotations
import json
import os
import tempfile
import uuid
from datetime import datetime, timezone
from pathlib import Path
from typing import Any
import artifact_store
# Nombre canónico del fichero de hallazgos dentro del directorio del engagement.
FINDINGS_NAME = "findings.jsonl"
# Estados alineados con la disciplina "hipótesis vs. hallazgo confirmado" del SOUL.md.
VALID_STATES = ("hypothesis", "partial", "confirmed", "discarded")
# Fases del bucle OODA (etiqueta libre si no encaja ninguna).
VALID_PHASES = ("observe", "orient", "decide", "act")
# Umbral minimo de bytes para considerar que la salida verbatim de una evidencia es real
# (no un marcador vacio tipo "ok"/"200"). No garantiza que sea cruda, pero descarta lo
# obviamente insuficiente para contrastar un hallazgo confirmado.
_MIN_EVIDENCE_OUTPUT_LEN = 16
class FindingStoreError(ValueError):
"""Entrada inválida para el store (fail-closed; no se escribe nada)."""
def _now_iso() -> str:
"""Timestamp ISO-8601 en UTC (sufijo 'Z') — mismo estilo que artifact_store."""
return datetime.now(timezone.utc).isoformat().replace("+00:00", "Z")
def _findings_path(engagement_id: str) -> Path:
"""Ruta CONFINADA del JSONL de hallazgos del engagement (reutiliza el confinamiento).
``artifact_store.resolve`` valida ``engagement_id``/``FINDINGS_NAME`` (sin traversal
ni separadores) y comprueba que la ruta cae bajo la raíz del staging. Un
``engagement_id`` inseguro levanta ``ValueError`` ahí.
"""
return artifact_store.resolve(engagement_id, FINDINGS_NAME)
def _validate_confirmed_evidence(evidence: Any) -> None:
"""Exige evidencia REPRODUCIBLE para un hallazgo ``confirmed`` (fail-closed).
Un hallazgo confirmado tiene que poder CONTRASTARSE: quien lea el informe debe poder
re-ejecutar el paso y ver lo mismo. Por eso aquí se rechaza, para ``state=confirmed``,
una evidencia que no permita esa reproduccion. Se aceptan DOS formas:
1. ``command`` + ``output``: el comando EXACTO re-ejecutable (el argv tal cual se paso
a ``kali_run``, o la accion de navegador reproducible) MAS la salida VERBATIM que
produjo (no un resumen). ``output`` debe superar un minimo de bytes para descartar
marcadores vacios tipo "ok"/"200".
2. ``artifact_ref``: ``{"execution_id","name"}`` apuntando al crudo staged en el plano
de datos (cuando la salida es grande y viaja como artefacto).
NO puede garantizar que el agente no parafrasee (es un LLM), pero rechaza fail-closed lo
obviamente insuficiente: evidencia ausente, sin comando, o con salida vacia/trivial. La
disciplina de pegar la salida CRUDA (no resumida) la refuerzan las skills.
"""
if not isinstance(evidence, dict) or not evidence:
raise FindingStoreError(
"finding 'confirmed' inválido: requiere 'evidence' reproducible "
"('command'+'output' verbatim, o 'artifact_ref'). No se admite confirmar sin evidencia."
)
ref = evidence.get("artifact_ref")
if isinstance(ref, dict) and ref.get("execution_id") and ref.get("name"):
return # evidencia por artefacto staged: suficiente
command = evidence.get("command")
output = evidence.get("output")
if not isinstance(command, str) or not command.strip():
raise FindingStoreError(
"finding 'confirmed' inválido: 'evidence.command' debe ser el comando EXACTO "
"re-ejecutable (el argv tal cual se pasó a kali_run), no una narración."
)
if not isinstance(output, str) or len(output.strip()) < _MIN_EVIDENCE_OUTPUT_LEN:
raise FindingStoreError(
"finding 'confirmed' inválido: 'evidence.output' debe ser la salida VERBATIM del "
"comando (request/response crudos), no un resumen; mínimo %d caracteres."
% _MIN_EVIDENCE_OUTPUT_LEN
)
def _normalize_finding(finding: dict[str, Any]) -> dict[str, Any]:
"""Valida y normaliza un hallazgo fail-closed; devuelve el dict a persistir.
Reglas (fail-closed, no se escribe nada si no se cumplen):
- ``finding`` es un dict.
- ``title`` no vacío (resumen humano del hallazgo).
- ``state`` ∈ VALID_STATES.
- ``phase`` ∈ VALID_PHASES si viene (se tolera ausente/libre, se guarda verbatim).
- si ``state`` es ``confirmed``: ``evidence`` debe ser REPRODUCIBLE (ver
``_validate_confirmed_evidence``). Un hallazgo sin evidencia contrastable no puede
marcarse confirmado — bájalo a ``partial``/``hypothesis``.
Rellena ``id`` (uuid4 hex si falta) y ``recorded_at`` (timestamp del servidor,
autoritativo: NO se confía en un timestamp provisto por el agente). El resto de
campos (target, technique_id, evidence, confidence, change) se guardan tal cual si
vienen, para no acoplar el esquema a un consumidor concreto.
"""
if not isinstance(finding, dict):
raise FindingStoreError("finding inválido: se espera un objeto JSON.")
title = finding.get("title")
if not isinstance(title, str) or not title.strip():
raise FindingStoreError("finding inválido: 'title' no vacío es obligatorio.")
state = finding.get("state")
if state not in VALID_STATES:
raise FindingStoreError(
"finding inválido: 'state' debe ser uno de %r (recibido %r)."
% (list(VALID_STATES), state)
)
phase = finding.get("phase")
if phase is not None and phase not in VALID_PHASES:
raise FindingStoreError(
"finding inválido: 'phase' debe ser uno de %r si se indica (recibido %r)."
% (list(VALID_PHASES), phase)
)
# Un hallazgo CONFIRMADO exige evidencia reproducible (trazabilidad): fail-closed.
if state == "confirmed":
_validate_confirmed_evidence(finding.get("evidence"))
# Copia superficial + campos autoritativos del servidor. El id del agente se respeta
# si viene bien formado; si no, se genera (nunca se escribe una línea sin id).
record = dict(finding)
fid = record.get("id")
if not isinstance(fid, str) or not fid.strip():
fid = uuid.uuid4().hex
record["id"] = fid
record["title"] = title.strip()
record["state"] = state
# recorded_at lo pone SIEMPRE el servidor (no se confía en el del agente).
record["recorded_at"] = _now_iso()
return record
def append(engagement_id: str, finding: dict[str, Any]) -> dict[str, Any]:
"""Añade un hallazgo normalizado al JSONL del engagement y devuelve el registro.
Append atómico a nivel de línea: se serializa el registro a una ÚNICA línea JSON
(sin saltos internos) y se escribe con ``O_APPEND`` en una sola llamada ``write``,
de modo que appends concurrentes de distintos workers no se entrelacen. Crea el
directorio del engagement si no existe.
Fail-closed: si el finding no valida (ver ``_normalize_finding``), levanta
``FindingStoreError`` y NO escribe nada.
"""
record = _normalize_finding(finding)
path = _findings_path(engagement_id)
path.parent.mkdir(parents=True, exist_ok=True)
line = json.dumps(record, ensure_ascii=False) + "\n"
# O_APPEND garantiza que cada write se posiciona al final de forma atómica; una línea
# entera en un solo write evita el entrelazado entre escritores concurrentes.
fd = os.open(path, os.O_WRONLY | os.O_CREAT | os.O_APPEND, 0o644)
try:
os.write(fd, line.encode("utf-8"))
finally:
os.close(fd)
return record
def read(
engagement_id: str, cursor: int = 0, limit: int | None = None
) -> dict[str, Any]:
"""Lee los hallazgos del engagement PAGINADOS por índice de línea.
Patrón cursor idéntico al de ``tool_streaming.read_findings``: ``cursor`` es el
índice 0-based del primer hallazgo a devolver; se devuelven hasta ``limit`` (o todos
los restantes si ``limit`` es ``None``). Las líneas ilegibles (JSON corrupto) se
SALTAN sin reventar — el store es best-effort en lectura.
Returns:
``{"findings": [...], "next_cursor": int, "done": bool, "total": int}``. Un
``engagement_id`` sin fichero devuelve página vacía con ``done=True`` y
``total=0`` (no revienta).
"""
try:
path = _findings_path(engagement_id)
except ValueError:
# engagement_id inseguro: no hay nada que leer (fail-closed en lectura también).
return {"findings": [], "next_cursor": cursor, "done": True, "total": 0}
if not path.is_file():
return {"findings": [], "next_cursor": cursor, "done": True, "total": 0}
records: list[dict[str, Any]] = []
with path.open("r", encoding="utf-8") as handle:
for raw in handle:
raw = raw.strip()
if not raw:
continue
try:
doc = json.loads(raw)
except json.JSONDecodeError:
continue # línea corrupta: se salta, no se interpreta
if isinstance(doc, dict):
records.append(doc)
total = len(records)
start = max(0, cursor)
end = total if limit is None else min(total, start + max(0, limit))
page = records[start:end]
return {
"findings": page,
"next_cursor": end,
"done": end >= total,
"total": total,
}