BloodHound MCP

Permite que los modelos de lenguaje grandes interactúen con los datos de BloodHound Community Edition.

Documentación

BloodHound MCP

Un servidor de Model Context Protocol (MCP) que conecta LLMs con BloodHound Community Edition y BloodHound Enterprise. Haz preguntas en lenguaje natural, obtén análisis de rutas de ataque, ejecuta consultas Cypher y explora entornos de Active Directory, Azure/Entra ID y OpenGraph, todo desde tu asistente de IA.

Demo

Mira el video de demostración

Cómo Funciona

El servidor expone la API REST de BloodHound CE y el grafo de Neo4j a través de un conjunto de 13 herramientas MCP compuestas, 10 recursos de referencia y un prompt de sistema ajustado para análisis de seguridad ofensiva.

Herramientas Compuestas

Cada herramienta utiliza un parámetro info_type para seleccionar qué datos se devuelven, manteniendo la superficie de herramientas pequeña y eficiente en tokens:

Herramienta	Opciones de `info_type`
`domain_info`	`list`, `info`, `users`, `groups`, `computers`, `ous`, `gpos`, `dc_syncers`, `foreign_admins`, `foreign_group_members`, `linked_gpos`, `search`
`user_info`	`info`, `sessions`, `memberships`, `admin_rights`, `rdp_rights`, `dcom_rights`, `ps_remote_rights`, `sql_admin_rights`, `constrained_delegation`, `controllables`, `controllers`
`group_info`	`info`, `members`, `memberships`, `admin_rights`, `rdp_rights`, `dcom_rights`, `ps_remote_rights`, `controllers`, `controllables`
`computer_info`	`info`, `sessions`, `local_admins`, `rdp_rights`, `dcom_rights`, `ps_remote_rights`, `sql_admins`, `constrained_delegation`, `controllables`, `controllers`
`ou_info`	`info`, `users`, `groups`, `computers`, `gpos`
`gpo_info`	`info`, `controllers`
`graph_analysis`	`shortest_path`, `edge_composition`, `search`
`adcs_info`	`templates`, `esc_paths`
`cypher_query`	`run`, `saved_list`, `saved_get`
`data_quality`	`stats`, `platform_list`, `platform_info`
`asset_groups`	`list`, `members`, `custom_selectors`
`custom_nodes`	`list`, `get`, `create`, `update`, `delete`, `validate_icon`, `extension_list`, `extension_upsert`, `extension_delete`, `extension_edges`
`file_upload`	`upload`, `start_job`, `upload_to_job`, `upload_bytes`, `upload_bytes_to_job`, `end_job`

Recursos

Material de referencia que el LLM carga bajo demanda, sin llamadas API adicionales:

URI del Recurso	Contenido
`bloodhound://cypher/reference`	Sintaxis de Cypher, esquema, nombres de propiedades, patrones
`bloodhound://cypher/offensive-queries`	Plantillas probadas en batalla: DCSync, Kerberoasting, abuso de GPO, delegación, ADCS, credenciales sombra, relay NTLM y más
`bloodhound://guides/ad`	Referencia rápida de tipos de nodos y relaciones de AD
`bloodhound://guides/ad-methodology`	Metodología y flujo de trabajo completo de ataques a AD
`bloodhound://guides/azure`	Referencia rápida de análisis de Azure/Entra ID
`bloodhound://guides/azure-methodology`	Cadenas de ataque completas de Azure
`bloodhound://guides/adcs`	Referencia rápida de ADCS ESC1–ESC13
`bloodhound://guides/adcs-methodology`	Análisis detallado de ESC y explotación
`bloodhound://opengraph/guide`	Diseño de esquemas de nodos personalizados y mejores prácticas
`bloodhound://opengraph/examples`	Ejemplos de OpenGraph para SQL Server y aplicaciones web

Prompt de Sistema

El prompt bloodhound_assistant incluye reglas de comportamiento que guían al LLM:

Cargar la biblioteca de consultas ofensivas antes de escribir Cypher para cualquier escenario de ataque
Nunca sacar conclusiones de privilegios sin verificar membresías de grupos y admincount
Respetar las convenciones de nombres de propiedades de BloodHound (hasspn, enabled, admincount — todo en minúsculas)
Manejar correctamente el almacenamiento de nombres en mayúsculas (DOMAIN ADMINS@CORP.LOCAL) en los filtros
Seguir los patrones adecuados de recorrido de bordes DCSync y GPO

Requisitos Previos

Python 3.11+
uv
Instancia de BloodHound Community Edition con datos cargados
Credenciales de API de BloodHound (Token ID + Token Key)

Instalación

Ejecuta el servidor MCP directamente desde Git sin clonarlo primero:

export BLOODHOUND_DOMAIN=your-bloodhound-instance.domain.com
export BLOODHOUND_TOKEN_ID=your-token-id
export BLOODHOUND_TOKEN_KEY=your-token-key
uvx --from git+https://github.com/mwnickerson/bloodhound_mcp bloodhound-mcp

Para una integración reproducible, agrega un commit después de la URL del repositorio, por ejemplo git+https://github.com/mwnickerson/bloodhound_mcp@<commit>. Una instalación con uvx no lee el .env de un checkout separado, por lo que el proceso que lanza el cliente MCP debe proporcionar las variables de credenciales.

Para desarrollo, clona el repositorio e instala su entorno:

git clone https://github.com/mwnickerson/bloodhound_mcp.git
cd bloodhound-mcp
uv sync

Crea un archivo .env en la raíz del proyecto:

BLOODHOUND_DOMAIN=your-bloodhound-instance.domain.com
BLOODHOUND_TOKEN_ID=your-token-id
BLOODHOUND_TOKEN_KEY=your-token-key

Al iniciar, el servidor MCP realiza una solicitud firmada de solo lectura a /api/v2/self. Las credenciales inválidas, fallos de conectividad y fallos de TLS detienen el servidor antes de que acepte llamadas a herramientas MCP. La solicitud de inicio expira después de 10 segundos.

El servidor usa por defecto https en el puerto 443. Anula si es necesario:

BLOODHOUND_PORT=8080
BLOODHOUND_SCHEME=http

La verificación de certificados TLS permanece habilitada cuando no se proporciona una configuración adicional. Para un despliegue de laboratorio de confianza que usa un certificado autofirmado, la verificación se puede deshabilitar explícitamente:

BLOODHOUND_VERIFY_TLS=false

Deshabilitar la verificación debilita la seguridad del transporte y registra una advertencia. No uses esta opción en redes no confiables.

Configuración

Claude Desktop

Agrega a claude_desktop_config.json:

{
  "mcpServers": {
    "bloodhound_mcp": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/mwnickerson/bloodhound_mcp",
        "bloodhound-mcp"
      ]
    }
  }
}

Claude Code

Agrega a ~/.claude/mcp.json:

{
  "mcpServers": {
    "bloodhound_mcp": {
      "type": "stdio",
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/mwnickerson/bloodhound_mcp",
        "bloodhound-mcp"
      ]
    }
  }
}

OpenAI Codex CLI

Agrega a ~/.codex/config.toml (o .codex/config.toml para configuración a nivel de proyecto):

[mcp_servers.bloodhound_mcp]
command = "uvx"
args = ["--from", "git+https://github.com/mwnickerson/bloodhound_mcp", "bloodhound-mcp"]

El servidor hereda las credenciales del proceso que lanza Codex. Para mantenerlas en la configuración de MCP en su lugar, pásalas explícitamente:

[mcp_servers.bloodhound_mcp]
command = "uvx"
args = ["--from", "git+https://github.com/mwnickerson/bloodhound_mcp", "bloodhound-mcp"]

[mcp_servers.bloodhound_mcp.env]
BLOODHOUND_DOMAIN = "your-bloodhound-instance.domain.com"
BLOODHOUND_TOKEN_ID = "your-token-id"
BLOODHOUND_TOKEN_KEY = "your-token-key"

MCP Inspector

Comando: uvx
Argumentos: --from git+https://github.com/mwnickerson/bloodhound_mcp bloodhound-mcp

Token de API de BloodHound

Inicia sesión en BloodHound CE o BloodHound Enterprise
Navega a Administración → Tokens de API
Crea un nuevo token y copia el Token ID y el Token Key en tu .env

Uso

Consultas de Ejemplo

Reconocimiento:

What domains are in BloodHound?
Show me all Domain Admins in CORP.LOCAL
Find all kerberoastable users
Which computers have unconstrained delegation?

Análisis de Usuarios y Grupos:

What admin rights does jsmith@corp.local have?
Show me all sessions for the administrator account
What groups is this user a member of?
Who controls the IT ADMINS group?

Análisis de Rutas de Ataque:

Find the shortest path from jsmith@corp.local to Domain Admins
Who has DCSync rights in the domain?
Show me all GPO abuse paths
Find ADCS ESC1 paths in the domain

Cypher Personalizado:

Run a Cypher query to find all users with SPN set and admincount=1
Find all computers where DOMAIN USERS can RDP

Cargas de Colección:

Upload this SharpHound ZIP from /tmp/sharphound.zip into BloodHound
Upload these base64-encoded SharpHound ZIP bytes as sharphound.zip
Start an upload job, upload these base64 JSON bytes as users.json, then end the job

Los agentes que ya tengan una colección de SharpHound o AzureHound en memoria deben codificar en base64 los bytes de la colección y llamar a:

file_upload(
    info_type="upload_bytes",
    file_name="sharphound.zip",
    file_bytes_base64="<base64-encoded zip bytes>"
)

Para trabajos de múltiples archivos, llama a start_job, luego upload_bytes_to_job para cada payload en base64, y luego end_job.

Soporte de OpenGraph

BloodHound 8.0+ admite tipos de nodos personalizados mediante OpenGraph, lo que te permite modelar infraestructura no-AD (recursos en la nube, bases de datos, activos personalizados) en el mismo grafo que Active Directory.

La herramienta custom_nodes maneja operaciones CRUD heredadas en configuraciones de visualización de tipos de nodos a través de /api/v2/custom-nodes. Para instancias de BloodHound v9.0.0+ con gestión de extensiones OpenGraph habilitada, la misma herramienta compuesta también admite /api/v2/extensions y /api/v2/extensions-edges mediante extension_list, extension_upsert, extension_delete y extension_edges.

Usa los recursos bloodhound://opengraph/guide y bloodhound://opengraph/examples para el diseño de esquemas y patrones de Cypher. Para esquemas OpenGraph estructurados, haz upsert del esquema de extensión primero, luego ingiere los datos de colección con file_upload.

Requiere BloodHound Enterprise o BloodHound CE 8.0 o posterior. La gestión de extensiones OpenGraph requiere BloodHound 9.0.0+ y la bandera de funcionalidad correspondiente habilitada.

Consideraciones de Seguridad

Los datos de BloodHound procesados a través de esta herramienta se transmiten a los servidores de tu proveedor de LLM. No uses esto con datos de AD de producción a menos que hayas evaluado ese riesgo.

Casos de uso recomendados:

Entornos de laboratorio (GOAD, DetectionLab, rangos personalizados)
Preparación para entrenamiento y certificación
Investigación y desarrollo de herramientas
Análisis de dominios no productivos

Mejores prácticas:

Rota los tokens de API de BloodHound regularmente
Usa un token de API de solo lectura cuando sea posible
Considera un puente LLM local para entornos sensibles

Pruebas

# Full test suite
uv run pytest

# Specific modules
uv run pytest tests/test_main_mcp_tools.py -v
uv run pytest tests/test_bloodhound_api.py -v

# Integration tests (requires a live BloodHound instance)
BLOODHOUND_INTEGRATION_TESTS=1 uv run pytest tests/test_integration.py -v

Hoja de Ruta

Modo de acceso directo a Neo4j (omite la API REST para recorridos complejos de grafos)
Mejora de herramientas para Azure/Entra ID
Mejor cobertura de rutas de ataque ADCS
Ejemplos y plantillas adicionales de OpenGraph

Contribuciones

Las contribuciones son bienvenidas. Abre un issue para discutir cambios significativos antes de enviar un PR.

Haz un fork del repositorio
Crea una rama de funcionalidad
Agrega pruebas para la nueva funcionalidad
Ejecuta uv run pytest y confirma que todo pasa
Envía un pull request

Agradecimientos

SpecterOps por BloodHound Community Edition
Orange Cyberdefense por GOAD (usado para pruebas)
@jlowin por FastMCP
@xpn por la inspiración de MCP a través del proyecto Mythic MCP

Licencia

GNU General Public License v3.0 — consulta LICENSE para más detalles.