yads-mcp

Servidor MCP que permite que cualquier agente LLM compatible con MCP (Claude Code, u otro proceso de agente accesible a través de la misma red que YADS) controle la cola, el etiquetado, la ejecución de escaneos y la gestión de objetivos/activos a través de la propia API /api/v1 de YADS, sin necesidad de un humano en el panel de control.

Es un envoltorio delgado de stdio alrededor de la API HTTP existente de YADS (/api/v1/queue/*, /api/v1/tags*, /api/v1/targets/*) — sin ruta de ejecución separada, sin omitir el alcance del tenant ni la ruta de código de despacho de escaneos. Cada acción realizada a través de aquí está sujeta al mismo aislamiento de tenant, límites de escaneos concurrentes y lógica de detección de cambios que el panel de control.

1. Crear una clave de API

Desde una máquina ya conectada a YADS (cookie de sesión), a través de /developer o del endpoint /api-keys/, crea una clave con los alcances que este agente necesita:

• read — operaciones de estado/listado (queue_status, tags_list, scan_get_findings, list_targets, get_target, get_target_changes, get_scan_status, get_network_context, ...)

• write — mutaciones de etiquetas y mutaciones de objetivos (add_target, undo_bulk_delete_targets, bulk_archive_targets, archive_dead_targets, restore_target)

• scan_execute — activación de escaneos (individuales o masivos)

• destructive — queue_purge, tags_delete_globally, bulk_delete_targets, bulk_blocklist_targets (también requiere confirm=True en la propia llamada)

Copia el token devuelto ahora — nunca se vuelve a mostrar.

Related MCP server: agentguard

2. Instalación

cd yads-mcp
python -m venv .venv
.venv/bin/pip install -e .

Pruebas

.venv/bin/pip install -e ".[test]"
.venv/bin/pytest tests/ -q

tests/conftest.py ejecuta YADS en proceso (Starlette TestClient) contra la misma pila de Postgres/Redis de prueba que las pruebas del propio repositorio yads (docker-compose.test.yml en ese repositorio, puertos 5433/6380) — inicia esa pila primero si estas pruebas no están pasando.

3. Configurar un cliente

Variables de entorno que el servidor necesita:

• YADS_URL — p. ej. https://yads.example.com

• YADS_API_KEY — el token del paso 1

Claude Code

claude mcp add yads \
  --env YADS_URL=https://yads.example.com \
  --env YADS_API_KEY=<token> \
  -- /path/to/yads-mcp/.venv/bin/python -m yads_mcp.server

o añade a .mcp.json:

{
  "mcpServers": {
    "yads": {
      "command": "/path/to/yads-mcp/.venv/bin/python",
      "args": ["-m", "yads_mcp.server"],
      "env": {
        "YADS_URL": "https://yads.example.com",
        "YADS_API_KEY": "<token>"
      }
    }
  }
}

Herramientas

Control de cola y escaneo

• queue_status()

• queue_list_rate_limited_modules()

• queue_pause() / queue_resume() — a nivel de flota, no limitado al tenant

• queue_cancel_task(task_id)

• queue_purge(confirm) — destructivo, limitado al tenant, ventana de deshacer de 60s

• queue_undo_purge(undo_batch)

Etiquetado y organización

• tags_list()

• tags_add_to_target(target_id, tag) / tags_remove_from_target(target_id, tag)

• tags_bulk_assign(target_ids, tags, action="add"|"remove"|"replace")

• tags_bulk_add_by_ids(target_ids, tag)

• tags_delete_globally(tag_name, confirm) — destructivo, sin deshacer

Ejecución de escaneos

• scan_trigger(target_url, profile="standard")

• scan_trigger_by_target_id(target_id, scan_types, scan_priority=None)

• scan_bulk_preview_count(only_roots=False, online_only=False, scanned_before=None)

• scan_bulk_by_criteria(scan_types, only_roots=False, online_only=False, scanned_before=None)

• scan_bulk_selected(target_ids, scan_types)

• scan_get_findings()

Gestión de objetivos y activos (Wave 2)

• list_targets(tag=None, online=None, scan_status=None, domain_search=None, archived=False, last_scanned_before=None, page=1, limit=20)

• get_target(target_id)

• add_target(domain)

• bulk_delete_targets(target_ids, confirm) — destructivo, ventana de deshacer de 60s

• undo_bulk_delete_targets(undo_batch)

• bulk_archive_targets(target_ids) / archive_dead_targets() / restore_target(target_id)

• bulk_blocklist_targets(target_ids, confirm) — destructivo, sin deshacer

• get_target_changes(target_id, limit=30)

• get_scan_status(target_id)

• get_network_context(target_id)

Las Waves 3–10 (Informes y exportación, Hallazgos y cumplimiento, OSINT/Descubrimiento/Inteligencia, Integraciones/Webhooks/Notificaciones) se gestionan por separado, cada una con su propia especificación de diseño.

Historial de cambios

Ver CHANGELOG.md.

Licencia

MIT — ver LICENSE.