Skip to content

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

feat: wire neutral plugin image/compose/config + disabled-parity test + docs (FEAT-004)

irraz92d72ce26569
diff --git a/agent-ooda/profile/config.yaml b/agent-ooda/profile/config.yaml
index 52aef10..2c3aa1a 100644
--- a/agent-ooda/profile/config.yaml
+++ b/agent-ooda/profile/config.yaml
@@ -88,23 +88,17 @@ mcp_servers:
# aislamiento de la red interna de docker.
url: "http://kali:8900"
tools:
- # WHITELIST EXACTA (en orden) de las tools REALES del servidor kali-mcp, con el nombre TAL
- # COMO lo expone el servidor. Nombre efectivo que vera el modelo = `mcp_kali_<tool>`.
- # OBSERVE : server_info, prowler_scan, iam_enum
- # ORIENT : iam_simulate (AWS read-only), get_scan_status, read_tool_logs
- # ACT : kali_run (bloqueante, una llamada) / kali_exec (async + poll)
- # REGISTRO: record_finding / read_findings (store de hallazgos por engagement)
- include:
- - kali_run
- - kali_exec
- - iam_enum
- - iam_simulate
- - get_scan_status
- - read_tool_logs
- - prowler_scan
- - record_finding
- - read_findings
- - server_info
+ # POSTURA (el SERVIDOR MCP es la FUENTE DE VERDAD: "lo que el servidor expone = lo que
+ # Hermes ve"). Se RETIRA la `tools.include` que antes hacia whitelist exacta de las tools
+ # de la Kali. Consecuencias deliberadas (decision del usuario):
+ # - La superficie VISIBLE pasa de 10 tools a las 15 nativas que el servidor publica por
+ # introspeccion (server_info ya deriva su lista del registro de FastMCP).
+ # - Cualquier tool que el servidor anada MAS ADELANTE (incluidas las aportadas por un
+ # plugin de terceros) entra en la superficie de Hermes SIN pasar por un gate aqui: no
+ # hay revision caso por caso en este archivo.
+ # Si se quisiera volver a revisar tool por tool, la via es REANADIR una `include:` con la
+ # whitelist exacta de nombres (tal como los expone el servidor) bajo esta misma clave
+ # `tools:`. NO se hace ahora: la fuente de verdad es el servidor.
# Desactiva los wrappers de utilidad que Hermes anadiria (list_prompts/get_prompt,
# list_resources/read_resource). Verificado en mcp.md ("Filter utility tools too").
prompts: false
diff --git a/docker-compose.yml b/docker-compose.yml
index f8f5469..e1039ee 100644
--- a/docker-compose.yml
+++ b/docker-compose.yml
@@ -68,11 +68,16 @@ services:
SCOPE_FILE: "${SCOPE_FILE:-/scope/scope.json}"
SCOPE_ENFORCE: "${SCOPE_ENFORCE:-}"
# Scope-guard mount (OPT-IN): to turn the guard ON, create a `scope.json` at the repo
- # root (copy scope.example.json), set `enabled: true`, and UNCOMMENT the volume below,
- # then recreate the kali service. Keep it commented for the default "no gate" behavior.
- # Create the file BEFORE `docker compose up` so Docker bind-mounts a file (not a dir).
- # volumes:
- # - ./scope.json:/scope/scope.json:ro
+ # root (copy scope.example.json), set `enabled: true`, and UNCOMMENT the mount line
+ # below (under this same volumes: block), then recreate the kali service. Keep it
+ # commented for the default "no gate" behavior. Create the file BEFORE `docker compose up`
+ # so Docker bind-mounts a file (not a dir).
+ volumes:
+ # Artifacts plane: /artifacts holds the staged raw output served over the data channel
+ # (KALI_ARTIFACTS_DIR). A NAMED volume makes it persist across container recreations;
+ # additive, nothing else changes. A plugin can declare it needs this via needs_volume().
+ - kali-artifacts:/artifacts
+ # - ./scope.json:/scope/scope.json:ro
# kali-mcp server port (exposed for direct inspection from the host if
# needed; ooda-agent reaches it over the internal network as kali:8900). The host
# port is configurable with KALI_MCP_HOST_PORT (default 8900) without editing this file;
@@ -109,6 +114,13 @@ services:
cp /opt/profile-src/profile/config.yaml "$$DEF/config.yaml"
cp /opt/profile-src/profile/SOUL.md "$$DEF/SOUL.md"
cp -r /opt/profile-src/skills/. "$$DEF/skills/" 2>/dev/null || true
+ # (a2) PLUGIN SKILLS (SHIELDED). Copy each live plugin's skill/ (bind-mounted at
+ # /opt/plugins) into the default profile's skills/, under a dir named after the plugin.
+ # INVARIANT: nothing here may trip `set -e` or abort Hermes startup — the whole block
+ # is gated on the dir existing and runs inside a `set +e` subshell with per-statement
+ # guards. A plugin dir ending in .disabled is skipped (SAME suffix as the Python loader,
+ # plugin_api.DISABLED_SUFFIX = ".disabled"; kept in sync by test_disabled_parity.py).
+ if [ -d /opt/plugins ]; then ( set +e; for d in /opt/plugins/*/; do [ -d "$$d" ] || continue; [ -d "$${d}skill" ] || continue; name="$$(basename "$$d")"; case "$$name" in *.disabled) continue ;; esac; mkdir -p "$$DEF/skills/$$name" 2>/dev/null || { echo "[plugins] skip $$name (mkdir)"; continue; }; cp -r "$${d}skill/." "$$DEF/skills/$$name/" 2>/dev/null || echo "[plugins] skip $$name (cp)"; done ); fi
# Copy custom skin(s) so Hermes skin_engine finds them under <hermes_home>/skins/.
cp -r /opt/profile-src/profile/skins/. "$$DEF/skins/" 2>/dev/null || true
# (b) inject the API server KEY (secret, not versioned) BEFORE starting.
@@ -198,6 +210,11 @@ services:
- hermes-data:/opt/data
# Declarative profile template, READ-ONLY and OUTSIDE /opt/data (does not touch the WAL).
- ./agent-ooda:/opt/profile-src:ro
+ # LIVE plugins tree, READ-ONLY, at /opt/plugins (DISTINCT from the Kali image's frozen
+ # /opt/kali-mcp/plugins). The command's shielded loop below copies each plugin's skill/
+ # into the Hermes profile, so activating a plugin's skill only needs an ooda-agent
+ # restart (no rebuild). See docs/plugins/discovery.md for the two-paths rule.
+ - ./plugins:/opt/plugins:ro
# Interactive TUI: 'docker compose exec -it ooda-agent hermes chat' needs stdin+tty.
stdin_open: true
tty: true
@@ -345,3 +362,6 @@ volumes:
# Hermes state (profile + SQLite WAL). NAMED on purpose: avoids the bind-mount
# that corrupts the SQLite WAL on macOS virtiofs.
hermes-data:
+ # Kali artifacts plane (/artifacts). NAMED so the staged raw output persists across
+ # container recreations.
+ kali-artifacts:
diff --git a/docker/kali/Dockerfile b/docker/kali/Dockerfile
index c8eadf6..6bea4f6 100644
--- a/docker/kali/Dockerfile
+++ b/docker/kali/Dockerfile
@@ -190,8 +190,22 @@ COPY docker/kali/report_gen.py ./report_gen.py
# DEBE estar en la imagen aunque el guard esté desactivado por defecto; sin este COPY el
# servidor aborta al arrancar con ModuleNotFoundError: No module named 'scope_guard'.
COPY docker/kali/scope_guard.py ./scope_guard.py
+# Subsistema de PLUGINS (CORE). plugin_api.py (contrato: PluginContext, DISABLED_SUFFIX,
+# tipos del reporte) y plugin_loader.py (descubrimiento + load_plugins + LAST_REPORT) son
+# STDLIB PURA pero los importa kali_mcp_server (import plugin_loader dentro de __main__ y
+# el bloque de plugins de server_info). Se copian SIEMPRE, con el mismo patrón per-file que
+# los módulos nativos; sin estos COPY el servidor abortaría al cargar el reporte de plugins.
+COPY docker/kali/plugin_api.py ./plugin_api.py
+COPY docker/kali/plugin_loader.py ./plugin_loader.py
COPY docker/kali/kali_mcp_server.py ./kali_mcp_server.py
+# Árbol de plugins versionado (SOLO plugins). Se congela DENTRO de la imagen en
+# /opt/kali-mcp/plugins (WORKDIR): es la ruta que lee load_plugins (PLUGINS_DIR default
+# "plugins"). Activar/desactivar un plugin aquí exige REBUILD de la Kali. Esta ruta es
+# DISTINTA del bind-mount vivo /opt/plugins de Hermes (ver docs/plugins/discovery.md).
+# No hay .dockerignore, así que el árbol versionado plugins/ DEBE existir o el build falla.
+COPY plugins/ ./plugins/
+
# Puerto del servidor kali-mcp. Overridable por entorno (KALI_MCP_PORT) sin
# reconstruir, pero el default del contrato es 8900 (KALI_MCP_URL=http://kali:8900).
ENV KALI_MCP_HOST=0.0.0.0 \
diff --git a/docker/kali/tests/test_disabled_parity.py b/docker/kali/tests/test_disabled_parity.py
new file mode 100644
index 0000000..84529b1
--- /dev/null
+++ b/docker/kali/tests/test_disabled_parity.py
@@ -0,0 +1,53 @@
+"""Test de PARIDAD del sufijo .disabled entre las dos capas (NIT-6).
+
+El sufijo que apaga un plugin vive en DOS sitios que NO deben divergir:
+ - la capa Python: ``plugin_api.DISABLED_SUFFIX`` (lo usa ``plugin_loader`` para ignorar el
+ directorio en el servidor kali-mcp);
+ - la capa shell: el ``for`` de skills de plugins del ``command`` de ``ooda-agent`` en
+ ``docker-compose.yml``, que salta los directorios ``*.disabled`` antes de copiar su skill.
+
+Si una capa cambiara el sufijo y la otra no, un plugin quedaría "medio apagado" (apagado en
+una capa y vivo en la otra). Este test fija que:
+ 1. ``plugin_api.DISABLED_SUFFIX == '.disabled'`` (fuente única del lado Python);
+ 2. el ``command`` de ``ooda-agent`` contiene la regla shell que salta ``*.disabled``,
+ por INSPECCIÓN del texto fuente del compose (no se levanta el stack).
+
+Restricción de entorno (igual que el resto del core): STDLIB PURA, sin importar el SDK
+``mcp`` ni el servidor; ``plugin_api`` es STDLIB PURA y sí se puede importar.
+"""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+_PARENT = Path(__file__).resolve().parent.parent
+sys.path.insert(0, str(_PARENT))
+
+import plugin_api # noqa: E402
+
+# Raíz del worktree = dos niveles por encima de docker/kali/.
+_COMPOSE_PATH = _PARENT.parent.parent / "docker-compose.yml"
+
+
+def test_disabled_suffix_es_punto_disabled():
+ """La fuente única del lado Python es exactamente '.disabled'."""
+ assert plugin_api.DISABLED_SUFFIX == ".disabled"
+
+
+def test_compose_salta_disabled_en_el_bucle_de_skills():
+ """El command de ooda-agent salta los plugins *.disabled con el MISMO sufijo."""
+ source = _COMPOSE_PATH.read_text(encoding="utf-8")
+ # La regla shell que apaga un plugin por nombre de directorio. Comparte el sufijo
+ # '.disabled' con plugin_api.DISABLED_SUFFIX: ambas capas deben usar el mismo.
+ assert 'case "$$name" in *.disabled) continue' in source
+ # El sufijo del compose coincide literalmente con la constante del lado Python.
+ assert f"*{plugin_api.DISABLED_SUFFIX})" in source
+
+
+def test_bucle_de_skills_blindado():
+ """El bucle de skills de plugins está blindado (no puede abortar el arranque)."""
+ source = _COMPOSE_PATH.read_text(encoding="utf-8")
+ # Gateado en que el directorio exista y ejecutado en un subshell con `set +e`.
+ assert "if [ -d /opt/plugins ]; then (" in source
+ assert "set +e;" in source
diff --git a/docs/plugins/developing-plugins.md b/docs/plugins/developing-plugins.md
new file mode 100644
index 0000000..60ad688
--- /dev/null
+++ b/docs/plugins/developing-plugins.md
@@ -0,0 +1,136 @@
+# Escribir un plugin de kali-mcp
+
+Guía para autores de plugins. Para el detalle del descubrimiento/carga y de las dos rutas
+del árbol `plugins/`, consulta [discovery.md](discovery.md).
+
+## Estructura de un plugin
+
+Un plugin es un **subdirectorio inmediato** de `plugins/` con, al menos, un `plugin.py`:
+
+```
+plugins/
+ mi-plugin/
+ plugin.py # obligatorio: PLUGIN_API, PLUGIN_NAME, register(ctx)
+ vendor/ # opcional: dependencias de terceros empaquetadas
+ skill/ # opcional: la skill que se copia al perfil de Hermes
+ SKILL.md
+ README.md # recomendado
+```
+
+`plugin.py` debe exponer:
+
+- `PLUGIN_API = 1` — versión del contrato que el plugin implementa. El cargador exige
+ **igualdad exacta** con `plugin_api.SUPPORTED_PLUGIN_API`; si no casan, el plugin se
+ rechaza en fase `api`.
+- `PLUGIN_NAME = "mi-plugin"` — nombre del plugin (para logs y `server_info`).
+- `register(ctx)` — función que recibe un `PluginContext` y declara tools, skill y
+ volúmenes a través de él.
+
+## `register(ctx)`
+
+Es el **único punto** por el que el plugin toca el servidor. Recibe un `PluginContext` ya
+configurado para el directorio del plugin. Ejemplo mínimo:
+
+```python
+from __future__ import annotations
+
+PLUGIN_API = 1
+PLUGIN_NAME = "mi-plugin"
+
+
+def register(ctx):
+ @ctx.tool()
+ def hello(name: str = "world") -> dict:
+ """Tool de ejemplo inocua."""
+ return {"status": "done", "greeting": f"hello, {name}"}
+
+ ctx.skill(path="skill")
+ ctx.needs_volume("kali-artifacts")
+```
+
+El plugin de ejemplo `plugins/example-hello.disabled/` demuestra el contrato completo y
+sirve de plantilla.
+
+## API de `PluginContext`
+
+Firmas fijas, versionadas con `PLUGIN_API = 1`:
+
+- `ctx.tool(*args, **kwargs)` — **decorador de tool con detección de colisión**. Resuelve el
+ nombre objetivo (kwarg `name=` o `fn.__name__`) y consulta las tools ya registradas. Si el
+ nombre ya existe, **no** delega: anota la colisión (el plugin queda `degraded`) y devuelve
+ la función intacta. Si no existe, delega literalmente en `mcp.tool(*a, **k)` y anota el
+ nombre. Si no puede obtener la lista fiable de nombres, el registro **falla** (no delega a
+ ciegas).
+- `ctx.skill(path)` — declara la **única** skill del plugin (ruta relativa al directorio del
+ plugin). Valida con `realpath` que la ruta resuelta queda **bajo** el directorio del
+ plugin; si escapa, se ignora con un warning no fatal. Una segunda llamada es un error de
+ contrato (máximo una skill): se ignora.
+- `ctx.needs_volume(name)` — **solo anota** que el plugin necesita un volumen. **No monta ni
+ habilita nada**; es declarativo para `server_info`.
+- `ctx.plugin_dir()` — ruta absoluta del directorio del plugin (siempre devuelve ruta,
+ exista o no).
+- `ctx.vendor_dir()` — ruta absoluta de `<plugin_dir>/vendor` (siempre devuelve ruta, exista
+ o no). **Contrato**: devuelve la ruta a `vendor/`; tú decides si existe y si la insertas en
+ `sys.path`. No crea el directorio ni verifica su contenido.
+
+## Regla de PREFIJAR módulos (sombra en `sys.modules`)
+
+El cargador importa cada `plugin.py` bajo un nombre namespaced (`vuln_plugin_<dir>`) e
+inserta el directorio del plugin en `sys.path` **solo** mientras ejecuta su cuerpo, para que
+`import <hermano>` resuelva contra el propio directorio del plugin.
+
+Aun así, los módulos hermanos que importes (y cualquier dependencia de `vendor/`) entran en
+`sys.modules` por su **nombre tal cual**. Si dos plugins (o un plugin y el core) usan el
+mismo nombre de módulo, el segundo **sombrea** al primero en `sys.modules`. Para evitarlo,
+**prefija** los nombres de tus módulos y paquetes vendorizados con algo propio del plugin
+(p. ej. `miplugin_utils` en vez de `utils`). No asumas que tu `utils` es el que se importa.
+
+## La skill = nombre del directorio
+
+La skill del plugin se copia al perfil de Hermes bajo un directorio **con el nombre del
+plugin** (el nombre de su directorio). Es el bucle de skills del `command` de `ooda-agent`
+en `docker-compose.yml` quien hace la copia desde el bind-mount `/opt/plugins`. Nombra el
+directorio del plugin con cuidado: es también el nombre de su skill en Hermes.
+
+## Cómo entregar `vendor/` y `skill/`
+
+- **`vendor/`**: empaqueta aquí las dependencias de terceros del plugin. Si necesitas que
+ Python las encuentre, inserta `ctx.vendor_dir()` en `sys.path` **dentro de `register`** y
+ recuerda la regla de prefijos. `vendor_dir()` no añade nada por sí solo.
+- **`skill/`**: deja aquí el `SKILL.md` (y recursos) de la skill. Declárala con
+ `ctx.skill(path="skill")`. Se copia a Hermes como se describe arriba; recuerda que esa capa
+ es **viva** (bind-mount) y solo necesita reinicio de `ooda-agent`, mientras que las tools
+ viajan en la imagen **congelada** de la Kali y necesitan rebuild (ver
+ [discovery.md](discovery.md)).
+
+## Postura de seguridad (NIT-7)
+
+El código de un plugin se ejecuta con **confianza plena**: corre en el **mismo proceso** del
+servidor kali-mcp, con sus mismos privilegios, **sin sandbox** y **sin aislamiento** entre
+el plugin y el servidor. Un plugin puede hacer lo que haga el core.
+
+Además, el perfil de Hermes **ya no hace whitelist** de las tools de la Kali (se retiró
+`mcp_servers.kali.tools.include` de `agent-ooda/profile/config.yaml`): el **servidor MCP es
+la fuente de verdad** y lo que el servidor expone es lo que Hermes ve. Por tanto, una tool
+aportada por un plugin de terceros entra en la superficie de Hermes **sin pasar por un
+gate**. Instala únicamente plugins de **origen conocido y revisado**.
+
+Si quisieras volver a revisar tool por tool, la vía es **reañadir manualmente** una
+`include:` con la whitelist exacta de nombres (tal como los expone el servidor) bajo
+`mcp_servers.kali.tools` en el `config.yaml`. No está puesta por defecto.
+
+## `.disabled` como constante única (NIT-6)
+
+El sufijo que apaga un plugin es `.disabled`, definido **una sola vez** en el código Python
+como `plugin_api.DISABLED_SUFFIX`. Lo comparten el cargador (capa de tools) y el bucle de
+skills del compose (capa de Hermes), y un test de paridad fija que no diverjan. Para apagar
+un plugin, renombra su directorio añadiendo `.disabled`; para encenderlo, quítalo.
+
+## Cómo testear con un `ctx` doble
+
+Los tests del core **no** importan el SDK `mcp` ni el servidor: usan un **doble** de `mcp`
+que imita la parte de la API interna de FastMCP que `PluginContext` toca —`mcp.tool(*a, **k)`
+(decorador) y `mcp._tool_manager.list_tools()` (nombres existentes)—. Sigue el mismo patrón
+para tu plugin: construye un `PluginContext` con ese doble y llama a tu `register(ctx)`,
+luego afirma sobre `ctx.tools`, `ctx.skill_path`, `ctx.volumes` y `ctx.collisions`.
+Consulta `docker/kali/tests/test_plugin_api.py` y `test_example_hello.py` como ejemplos.
diff --git a/docs/plugins/discovery.md b/docs/plugins/discovery.md
new file mode 100644
index 0000000..cc07b44
--- /dev/null
+++ b/docs/plugins/discovery.md
@@ -0,0 +1,107 @@
+# Descubrimiento y carga de plugins
+
+Este documento describe **cómo** el servidor kali-mcp descubre y carga los plugins, y las
+**dos rutas** por las que el árbol `plugins/` entra en el stack. Para escribir un plugin,
+consulta [developing-plugins.md](developing-plugins.md).
+
+## Cuándo se cargan
+
+La carga ocurre **una sola vez, en el arranque del servidor**, dentro del guard
+`if __name__ == "__main__":` de `docker/kali/kali_mcp_server.py`, ANTES de abrir ningún
+plano (datos ni control). Nunca se invoca a nivel de módulo: así `load_plugins` no corre en
+cada `import` del servidor ni en los tests (que no tienen el SDK `mcp`). La llamada es:
+
+```python
+plugin_loader.load_plugins(mcp, os.environ.get("PLUGINS_DIR", "plugins"))
+```
+
+Es decir, la raíz de plugins por defecto es `plugins` **relativa al WORKDIR**
+(`/opt/kali-mcp/plugins` dentro de la imagen), configurable con la variable de entorno
+`PLUGINS_DIR`.
+
+## Orden de descubrimiento
+
+El cargador enumera los **subdirectorios inmediatos** de la raíz de plugins en **orden
+alfabético determinista** (`sorted(os.listdir(...))`). Un directorio es candidato solo si:
+
+- no empieza por `.` (ocultos ignorados);
+- no termina en `.disabled` (ver abajo);
+- es un directorio;
+- contiene un fichero `plugin.py`.
+
+El orden alfabético es estable entre arranques: dos plugins que registren tools en un orden
+reproducible verán siempre la misma secuencia.
+
+## El sufijo `.disabled`
+
+Un directorio cuyo nombre termina en `.disabled` se **ignora por completo**. El sufijo es
+una **constante única** en el código Python: `plugin_api.DISABLED_SUFFIX = ".disabled"`
+(NIT-6). Esa MISMA cadena la comparte el bucle de skills de plugins del `command` de
+`ooda-agent` en `docker-compose.yml`, que salta los directorios `*.disabled` antes de
+copiar su skill. El test `docker/kali/tests/test_disabled_parity.py` fija que ambas capas
+usan el mismo sufijo, de modo que no pueden divergir (un plugin nunca queda "apagado en una
+capa y vivo en la otra").
+
+Para activar un plugin entregado deshabilitado, se quita el sufijo del nombre del
+directorio; para volver a apagarlo, se reañade. (El impacto de un rename sobre cada ruta se
+detalla en «Las dos rutas» más abajo.)
+
+## Errores no fatales (aislamiento)
+
+Cada plugin se procesa dentro de su propio `try/except`: **un plugin roto no tumba a los
+demás ni al arranque del servidor**. El cargador aplica un micro-algoritmo por fases y, en
+cada fallo, registra hasta dónde llegó sin propagar la excepción:
+
+- `name` — el nombre del directorio no casa el regex permitido.
+- `import` — el cuerpo de `plugin.py` (o un `import` de un módulo hermano) lanzó.
+- `api` — el `PLUGIN_API` del plugin no es compatible (se exige igualdad exacta con
+ `SUPPORTED_PLUGIN_API`).
+- `register-missing` — el plugin no expone un `register(ctx)` invocable.
+- `register` — `register(ctx)` lanzó durante su ejecución.
+
+El traceback completo va a stdout/stderr; el reporte solo guarda `str(exc)` (una línea).
+
+## Reversión en fallo de `register` (NIT-8)
+
+Si `register(ctx)` lanza **después** de haber registrado una o más tools, el cargador
+**revierte** esas tools ya montadas (`mcp._tool_manager.remove_tool(name)`, best-effort)
+para no dejar tools huérfanas visibles de un plugin que falló a medias. El plugin se reporta
+como `failed` en fase `register`.
+
+## Introspección síncrona y esquema `server_info['plugins']`
+
+`server_info` **no** lleva una lista estática de plugins: lee el singleton de módulo
+`plugin_loader.LAST_REPORT`, que `load_plugins` publica al terminar su pasada (HIGH-1). La
+introspección es **síncrona**: el reporte ya está calculado en el arranque, así que
+`server_info` solo lo clasifica. Si nunca se cargaron plugins (p. ej. en un `import` suelto
+del módulo), `LAST_REPORT` arranca vacío y el bloque es coherente y vacío — comportamiento
+idéntico al de hoy.
+
+El bloque `plugins` de `server_info` tiene un **esquema cerrado** derivado del reporte: por
+cada plugin descubierto se expone su nombre, su `status` (`loaded` / `degraded` / `failed`),
+la fase alcanzada, las tools que registró, la skill declarada, los volúmenes anotados y las
+colisiones detectadas.
+
+## Las dos rutas del árbol `plugins/` (NIT-5)
+
+El mismo árbol versionado `plugins/` del repo entra en el stack por **dos rutas
+DISTINTAS**, que **no son la misma y no deben unificarse**:
+
+1. **Congelada en la imagen de Kali — `/opt/kali-mcp/plugins`.**
+ El `Dockerfile` hace `COPY plugins/ ./plugins/` (sobre el WORKDIR `/opt/kali-mcp`). Es la
+ ruta que lee `load_plugins` para descubrir y cargar las **tools** del plugin en el
+ servidor kali-mcp. Al copiarse en **build**, queda **congelada**: activar o desactivar un
+ plugin (añadirlo, quitarlo o renombrar su `.disabled`) exige **reconstruir la imagen de
+ Kali** para que el cambio tenga efecto en las tools.
+
+2. **Viva por bind-mount en Hermes — `/opt/plugins`.**
+ `docker-compose.yml` monta `./plugins:/opt/plugins:ro` en el contenedor `ooda-agent`. El
+ `command` de ese servicio recorre esa ruta y copia la `skill/` de cada plugin a la carpeta
+ de skills del perfil de Hermes. Al ser un bind-mount **vivo**, basta un **reinicio de
+ `ooda-agent`** (sin rebuild) para que la **skill** de un plugin se recoja o deje de
+ recogerse.
+
+Consecuencia práctica: la capa de **tools** (Kali, congelada) y la capa de **skills**
+(Hermes, viva) se activan por mecanismos diferentes. No unifiques las rutas ni asumas que un
+solo cambio basta para ambas: una tool nueva necesita rebuild de la Kali, y una skill nueva
+necesita reinicio de `ooda-agent`.