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
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.pynew file mode 100644index 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.mdnew file mode 100644index 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.mdnew file mode 100644index 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.pynew file mode 100644index 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.mdnew file mode 100644index 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.