Skip to content

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

feat: add versioned plugins tree with disabled example-hello plugin

irrazfee4167a814a
diff --git a/docker/kali/tests/test_example_hello.py b/docker/kali/tests/test_example_hello.py
new file mode 100644
index 0000000..b4fbbdd
--- /dev/null
+++ b/docker/kali/tests/test_example_hello.py
@@ -0,0 +1,104 @@
+"""Test del plugin de EJEMPLO ``example-hello`` (STDLIB PURA, con doble de ``mcp``).
+
+El directorio del plugin termina en ``.disabled``, por lo que NO es importable por nombre:
+se carga su ``plugin.py`` POR RUTA con ``importlib.util.spec_from_file_location`` (igual que
+hace el cargador real). Se ejecuta ``register(ctx)`` con un ``PluginContext`` real sobre un
+doble de ``mcp`` (el SDK no está en el venv de dev), siguiendo el patrón de ``test_plugin_api``.
+
+Verifica que el plugin monta la tool ``hello``, declara la skill y el volumen, y que la tool
+capturada devuelve el saludo inocuo esperado.
+"""
+
+from __future__ import annotations
+
+import importlib.util
+import os
+import sys
+from pathlib import Path
+
+_PARENT = Path(__file__).resolve().parent.parent
+sys.path.insert(0, str(_PARENT))
+
+import plugin_api # noqa: E402
+
+# Ruta al plugin.py del ejemplo (directorio .disabled -> solo cargable por ruta).
+_PLUGIN_DIR = _PARENT.parent.parent / "plugins" / "example-hello.disabled"
+_PLUGIN_PY = _PLUGIN_DIR / "plugin.py"
+
+
+class _FakeTool:
+ def __init__(self, name: str) -> None:
+ self.name = name
+
+
+class _FakeToolManager:
+ def __init__(self, names=None) -> None:
+ self._names = list(names or [])
+
+ def list_tools(self):
+ return [_FakeTool(n) for n in self._names]
+
+ def remove_tool(self, name: str) -> None:
+ self._names.remove(name)
+
+
+class _FakeMcp:
+ """Doble de FastMCP que CAPTURA la función decorada por ``tool()`` para invocarla."""
+
+ def __init__(self, existing=None) -> None:
+ self._tool_manager = _FakeToolManager(existing)
+ self.registered: dict = {}
+
+ def tool(self, *args, **kwargs):
+ def _decorator(fn):
+ name = kwargs.get("name") or fn.__name__
+ self._tool_manager._names.append(name)
+ self.registered[name] = fn
+ return fn
+
+ return _decorator
+
+
+def _load_example_plugin():
+ spec = importlib.util.spec_from_file_location("ph_example_hello", str(_PLUGIN_PY))
+ module = importlib.util.module_from_spec(spec)
+ spec.loader.exec_module(module)
+ return module
+
+
+def test_plugin_declara_contrato_basico():
+ module = _load_example_plugin()
+ assert module.PLUGIN_API == plugin_api.SUPPORTED_PLUGIN_API
+ assert module.PLUGIN_NAME == "example-hello"
+ assert callable(module.register)
+
+
+def test_register_monta_hello_skill_y_volumen():
+ module = _load_example_plugin()
+ mcp = _FakeMcp()
+ ctx = plugin_api.PluginContext(mcp, str(_PLUGIN_DIR))
+
+ module.register(ctx)
+
+ # Monta la tool 'hello'.
+ assert ctx.tools == ["hello"]
+ assert ctx.collisions == []
+ assert "hello" in mcp.registered
+
+ # Declara la skill (directorio skill/ bajo el plugin).
+ assert ctx.skill_path == os.path.realpath(str(_PLUGIN_DIR / "skill"))
+
+ # Declara (anota) el volumen de artefactos.
+ assert ctx.volumes == ["kali-artifacts"]
+
+
+def test_tool_hello_devuelve_saludo_inocuo():
+ module = _load_example_plugin()
+ mcp = _FakeMcp()
+ ctx = plugin_api.PluginContext(mcp, str(_PLUGIN_DIR))
+
+ module.register(ctx)
+ hello = mcp.registered["hello"]
+
+ assert hello() == {"status": "done", "greeting": "hello, world"}
+ assert hello("kiro") == {"status": "done", "greeting": "hello, kiro"}
diff --git a/plugins/README.md b/plugins/README.md
new file mode 100644
index 0000000..33bc074
--- /dev/null
+++ b/plugins/README.md
@@ -0,0 +1,47 @@
+# plugins/
+
+Árbol versionado de plugins del servidor kali-mcp. Este directorio **siempre debe
+existir** en el repo: el `Dockerfile` hace `COPY plugins/ ./plugins/` y, sin un árbol
+versionado, el build fallaría. Por eso este `README.md` lo mantiene presente aunque no
+haya ningún plugin activo.
+
+## Qué es un plugin
+
+Un plugin es un subdirectorio inmediato de `plugins/` con, al menos, un `plugin.py` que
+expone:
+
+- `PLUGIN_API = 1` — versión del contrato que el plugin implementa.
+- `PLUGIN_NAME = "<nombre>"` — nombre del plugin.
+- `register(ctx)` — función que recibe un `PluginContext` y declara tools, skill y
+ volúmenes a través de él.
+
+El cargador descubre los subdirectorios en orden alfabético y, por cada uno con
+`plugin.py`, ejecuta su `register(ctx)`. Consulta `docs/plugins/` para el detalle del
+contrato y del descubrimiento.
+
+## Postura de confianza
+
+El código de un plugin se ejecuta **con la misma confianza que el core**: corre en el
+mismo proceso del servidor, con sus mismos privilegios, sin sandbox. Añade aquí solo
+plugins de origen conocido y revisado. No hay aislamiento entre un plugin y el servidor.
+
+## Habilitar / deshabilitar un plugin
+
+Un directorio cuyo nombre termina en `.disabled` se **ignora** por completo (ni el
+cargador ni el resto del sistema lo montan). Para activar un plugin entregado
+deshabilitado, **renombra el directorio quitando el sufijo `.disabled`**:
+
+```sh
+mv plugins/example-hello.disabled plugins/example-hello
+```
+
+Para deshabilitarlo de nuevo, vuelve a añadir el sufijo. Tras activar o desactivar un
+plugin hay que reconstruir la imagen de Kali (el árbol `plugins/` se copia en build);
+consulta el `README.md` del propio plugin de ejemplo para el recordatorio completo.
+
+## Ejemplo entregado
+
+`example-hello.disabled/` es un plugin de ejemplo entregado **deshabilitado**. Demuestra
+el contrato completo (una tool inocua, una skill y la declaración de un volumen) sin
+cambiar el comportamiento por defecto del servidor. Léelo como plantilla para escribir
+plugins propios.
diff --git a/plugins/example-hello.disabled/README.md b/plugins/example-hello.disabled/README.md
new file mode 100644
index 0000000..c900032
--- /dev/null
+++ b/plugins/example-hello.disabled/README.md
@@ -0,0 +1,30 @@
+# example-hello (plugin de ejemplo, entregado DESHABILITADO)
+
+Plugin de ejemplo que demuestra el contrato de plugins de kali-mcp de principio a fin:
+
+- Registra la tool **`hello`**, inocua: devuelve `{"status": "done", "greeting":
+ "hello, <name>"}` y no toca red, filesystem ni target.
+- Declara una **skill** (`skill/SKILL.md`).
+- Declara (solo anota) que necesita el volumen **`kali-artifacts`**.
+
+Se entrega dentro de un directorio terminado en `.disabled`, por lo que **por defecto no
+se carga**: ni el cargador de plugins ni el bucle de skills lo montan. El comportamiento
+del servidor es idéntico a no tener este plugin.
+
+## Cómo activarlo
+
+Renombra el directorio quitando el sufijo `.disabled`:
+
+```sh
+mv plugins/example-hello.disabled plugins/example-hello
+```
+
+Para deshabilitarlo de nuevo, vuelve a añadir el sufijo.
+
+## Importante tras activar/desactivar
+
+El árbol `plugins/` se copia dentro de la imagen de Kali en **tiempo de build**, de modo
+que para que un cambio de activación surta efecto hay que **reconstruir la imagen de
+Kali**. El contenedor del agente (ooda-agent) monta el árbol y recarga las skills al
+**reiniciarse**. El detalle de este flujo (bind-mount `./plugins:/opt/plugins:ro` y el
+bucle de skills) se documenta junto a la integración de runtime.
diff --git a/plugins/example-hello.disabled/plugin.py b/plugins/example-hello.disabled/plugin.py
new file mode 100644
index 0000000..4114c68
--- /dev/null
+++ b/plugins/example-hello.disabled/plugin.py
@@ -0,0 +1,39 @@
+"""Plugin de EJEMPLO entregado DESHABILITADO (directorio ``*.disabled``).
+
+Demuestra el contrato completo de ``PluginContext`` sin cambiar el comportamiento del
+servidor: al vivir en un directorio ``.disabled`` ni el cargador ni el bucle de skills lo
+montan, así que el default es idéntico a hoy. Para activarlo, renombra el directorio
+quitando el sufijo ``.disabled`` (ver ``README.md`` de este plugin).
+
+Registra una tool INOCUA (``hello``) que no toca red, filesystem ni target: solo devuelve
+un saludo. Además declara una skill y un volumen para ejercitar el contrato entero.
+"""
+
+from __future__ import annotations
+
+# Versión del contrato de plugin que este ejemplo implementa (debe casar con
+# ``plugin_api.SUPPORTED_PLUGIN_API`` del core).
+PLUGIN_API = 1
+
+# Nombre del plugin, usado por el cargador y por ``server_info``.
+PLUGIN_NAME = "example-hello"
+
+
+def register(ctx):
+ """Declara la tool, la skill y el volumen del plugin a través del ``ctx``.
+
+ ``ctx`` es un ``PluginContext``: ``ctx.tool`` es un decorador con detección de
+ colisión; ``ctx.skill`` declara la (única) skill; ``ctx.needs_volume`` anota un
+ volumen (solo declarativo).
+ """
+
+ @ctx.tool()
+ def hello(name: str = "world") -> dict:
+ """Tool de ejemplo INOCUA: devuelve un saludo, sin efectos secundarios."""
+ return {"status": "done", "greeting": f"hello, {name}"}
+
+ # Declara la skill de ejemplo (directorio ``skill/`` relativo a este plugin).
+ ctx.skill(path="skill")
+
+ # Declara (solo anota) que el plugin usaría el volumen de artefactos de Kali.
+ ctx.needs_volume("kali-artifacts")
diff --git a/plugins/example-hello.disabled/skill/SKILL.md b/plugins/example-hello.disabled/skill/SKILL.md
new file mode 100644
index 0000000..f1da2bc
--- /dev/null
+++ b/plugins/example-hello.disabled/skill/SKILL.md
@@ -0,0 +1,8 @@
+# Skill: example-hello
+
+Skill de ejemplo del plugin `example-hello`. Es trivial y neutral: existe solo para
+demostrar que un plugin puede entregar una skill junto a su `plugin.py`.
+
+La tool `hello` que acompaña a esta skill devuelve un saludo inocuo y no realiza ninguna
+acción sobre la red, el sistema de ficheros ni el objetivo. Úsala como punto de partida
+para escribir skills propias en tus plugins.