yads-mcp

MCP 지원 LLM 에이전트(Claude Code 또는 YADS와 동일한 네트워크에서 접근 가능한 다른 에이전트 프로세스)가 대시보드에서 사람 없이 YADS 자체 /api/v1 API를 통해 큐 제어, 태깅, 스캔 실행, 대상/자산 관리를 수행할 수 있게 해주는 MCP 서버입니다.

이는 YADS의 기존 HTTP API(/api/v1/queue/*, /api/v1/tags*, /api/v1/targets/*)를 감싸는 얇은 stdio 래퍼입니다. 별도의 실행 경로가 없으며, 테넌트 범위 지정이나 스캔 디스패치 코드 경로를 우회하지 않습니다. 여기를 통해 수행되는 모든 작업은 대시보드와 동일한 테넌트 격리, 동시 스캔 제한, 변경 감지 로직을 따릅니다.

1. API 키 생성

YADS에 이미 로그인된 머신(세션 쿠키)에서 /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 저장소의 자체 테스트와 동일한 테스트 Postgres/Redis 스택(docker-compose.test.yml, 포트 5433/6380)을 대상으로 YADS를 프로세스 내에서(Starlette TestClient) 실행합니다. 이 테스트가 통과하지 않으면 먼저 해당 스택을 시작하세요.

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

대상 및 자산 관리 (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) — 파괴적, 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)

Wave 3–10(Reports & Export, Findings & Compliance, OSINT/Discovery/Intelligence, Integrations/Webhooks/Notifications)은 각각 별도의 설계 사양과 함께 별도로 추적됩니다.

변경 로그

CHANGELOG.md를 참조하세요.

라이선스

MIT — LICENSE를 참조하세요.