yads-mcp

MCP-сервер, который позволяет любому MCP-совместимому LLM-агенту (Claude Code или другому процессу агента, доступному через ту же сеть, что и YADS) управлять очередью, тегами, выполнением сканирования и управлением целями/активами через собственный API YADS /api/v1, без участия человека в панели управления.

Это тонкая обёртка stdio вокруг существующего HTTP API YADS (/api/v1/queue/*, /api/v1/tags*, /api/v1/targets/*) — без отдельного пути выполнения, без обхода ограничений тенанта или пути кода диспетчера сканирования. Каждое действие, выполняемое здесь, подчиняется той же изоляции тенантов, ограничениям одновременных сканирований и логике обнаружения изменений, что и панель управления.

1. Создание API-ключа

С машины, уже вошедшей в YADS (cookie сессии), через /developer или конечную точку /api-keys/, создайте ключ с областями, которые нужны этому агенту:

• read — операции статуса/списка (queue_status, tags_list, scan_get_findings, list_targets, get_target, get_target_changes, get_scan_status, get_network_context, ...)

• write — мутации тегов и мутации целей (add_target, undo_bulk_delete_targets, bulk_archive_targets, archive_dead_targets, restore_target)

• scan_execute — запуск сканирований (одиночных или массовых)

• destructive — queue_purge, tags_delete_globally, bulk_delete_targets, bulk_blocklist_targets (также требует confirm=True при самом вызове)

Скопируйте возвращённый токен сейчас — он больше никогда не будет показан.

Related MCP server: agentguard

2. Установка

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

Тесты

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

tests/conftest.py запускает YADS в процессе (Starlette TestClient) против того же тестового стека Postgres/Redis, что и собственные тесты репозитория yads (docker-compose.test.yml в этом репозитории, порты 5433/6380) — запустите этот стек сначала, если эти тесты не проходят.

3. Настройка клиента

Переменные окружения, необходимые серверу:

• YADS_URL — например, https://yads.example.com

• YADS_API_KEY — токен из шага 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

или добавьте в .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>"
      }
    }
  }
}

Инструменты

Управление очередью и сканированием

• queue_status()

• queue_list_rate_limited_modules()

• queue_pause() / queue_resume() — для всего парка, не ограничено тенантом

• queue_cancel_task(task_id)

• queue_purge(confirm) — разрушительное, ограничено тенантом, окно отмены 60 секунд

• queue_undo_purge(undo_batch)

Тегирование и организация

• 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) — разрушительное, без отмены

Выполнение сканирования

• 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()

Управление целями и активами (Волна 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) — разрушительное, окно отмены 60 секунд

• undo_bulk_delete_targets(undo_batch)

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

• bulk_blocklist_targets(target_ids, confirm) — разрушительное, без отмены

• get_target_changes(target_id, limit=30)

• get_scan_status(target_id)

• get_network_context(target_id)

Волны 3–10 (Отчёты и экспорт, Находки и соответствие, OSINT/Разведка/Интеллект, Интеграции/Вебхуки/Уведомления) отслеживаются отдельно, каждая со своей спецификацией дизайна.

Журнал изменений

См. CHANGELOG.md.

Лицензия

MIT — см. LICENSE.