BloodHound MCP

Permite que Modelos de Linguagem de Grande Escala interajam com dados do BloodHound Community Edition.

Documentação

BloodHound MCP

Um servidor Model Context Protocol (MCP) que conecta LLMs ao BloodHound Community Edition e ao BloodHound Enterprise. Faça perguntas em linguagem natural, obtenha análise de caminhos de ataque, execute consultas Cypher e explore ambientes Active Directory, Azure/Entra ID e OpenGraph — tudo a partir do seu assistente de IA.

Demonstração

Assista ao vídeo de demonstração

Como Funciona

O servidor expõe a API REST do BloodHound CE e o grafo Neo4j por meio de um conjunto de 13 ferramentas MCP compostas, 10 recursos de referência e um prompt de sistema ajustado para análise de segurança ofensiva.

Ferramentas Compostas

Cada ferramenta usa um parâmetro info_type para selecionar quais dados são retornados, mantendo a superfície de ferramentas pequena e eficiente em tokens:

Ferramenta	Opções 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 referência que o LLM carrega sob demanda — sem chamadas extras de API:

URI do Recurso	Conteúdo
`bloodhound://cypher/reference`	Sintaxe Cypher, esquema, nomes de propriedades, padrões
`bloodhound://cypher/offensive-queries`	Modelos testados em batalha: DCSync, Kerberoasting, abuso de GPO, delegação, ADCS, credenciais sombra, relay NTLM e mais
`bloodhound://guides/ad`	Referência rápida de tipos de nós e relacionamentos do AD
`bloodhound://guides/ad-methodology`	Metodologia e fluxo de trabalho completos de ataque ao AD
`bloodhound://guides/azure`	Referência rápida de análise do Azure/Entra ID
`bloodhound://guides/azure-methodology`	Cadeias completas de ataque ao Azure
`bloodhound://guides/adcs`	Referência rápida de ADCS ESC1–ESC13
`bloodhound://guides/adcs-methodology`	Análise detalhada de ESC e exploração
`bloodhound://opengraph/guide`	Design de esquema de nós personalizados e melhores práticas
`bloodhound://opengraph/examples`	Exemplos de OpenGraph para SQL Server e Aplicativos Web

Prompt de Sistema

O prompt bloodhound_assistant inclui regras comportamentais que orientam o LLM:

Carregue a biblioteca de consultas ofensivas antes de escrever Cypher para qualquer cenário de ataque
Nunca tire conclusões de privilégios sem verificar associações de grupos e admincount
Respeite as convenções de nomenclatura de propriedades do BloodHound (hasspn, enabled, admincount — tudo em minúsculas)
Lide corretamente com o armazenamento de nomes em maiúsculas (DOMAIN ADMINS@CORP.LOCAL) em filtros
Siga os padrões adequados de travessia de bordas DCSync e GPO

Pré-requisitos

Python 3.11+
uv
Instância do BloodHound Community Edition com dados carregados
Credenciais da API do BloodHound (Token ID + Token Key)

Instalação

Execute o servidor MCP diretamente do Git sem cloná-lo primeiro:

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 uma integração reproduzível, acrescente um commit após a URL do repositório, por exemplo git+https://github.com/mwnickerson/bloodhound_mcp@<commit>. Uma instalação uvx não lê o .env de um checkout separado, portanto o processo que inicia o cliente MCP deve fornecer as variáveis de credenciais.

Para desenvolvimento, clone o repositório e instale seu ambiente:

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

Crie um arquivo .env na raiz do projeto:

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

Na inicialização, o servidor MCP faz uma solicitação assinada e somente leitura para /api/v2/self. Credenciais inválidas, falhas de conectividade e falhas de TLS interrompem o servidor antes que ele aceite chamadas de ferramentas MCP. A solicitação de inicialização expira após 10 segundos.

O servidor usa como padrão https na porta 443. Substitua se necessário:

BLOODHOUND_PORT=8080
BLOODHOUND_SCHEME=http

A verificação do certificado TLS permanece habilitada quando nenhuma configuração adicional é fornecida. Para uma implantação confiável em laboratório que usa um certificado autoassinado, a verificação pode ser explicitamente desabilitada:

BLOODHOUND_VERIFY_TLS=false

Desabilitar a verificação enfraquece a segurança do transporte e registra um aviso. Não use esta opção em redes não confiáveis.

Configuração

Claude Desktop

Adicione ao claude_desktop_config.json:

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

Claude Code

Adicione ao ~/.claude/mcp.json:

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

OpenAI Codex CLI

Adicione ao ~/.codex/config.toml (ou .codex/config.toml para configuração no escopo do projeto):

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

O servidor herda as credenciais do processo que inicia o Codex. Para mantê-las na configuração MCP, passe-as explicitamente:

[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 da API do BloodHound

Entre no BloodHound CE ou BloodHound Enterprise
Navegue até Administração → Tokens de API
Crie um novo token e copie o Token ID e o Token Key para o seu .env

Uso

Exemplos de Consultas

Reconhecimento:

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

Análise de Usuários e 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álise de Caminhos 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

Uploads de Coleta:

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

Agentes que já possuem uma coleta SharpHound ou AzureHound em memória devem codificar os bytes da coleta em base64 e chamar:

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

Para trabalhos com vários arquivos, chame start_job, depois upload_bytes_to_job para cada payload base64 e, em seguida, end_job.

Suporte a OpenGraph

O BloodHound 8.0+ suporta tipos de nós personalizados via OpenGraph, permitindo modelar infraestrutura não-AD (recursos em nuvem, bancos de dados, ativos personalizados) no mesmo grafo do Active Directory.

A ferramenta custom_nodes lida com operações CRUD legadas em configurações de exibição de tipos de nós por meio de /api/v2/custom-nodes. Para instâncias BloodHound v9.0.0+ com gerenciamento de extensões OpenGraph habilitado, a mesma ferramenta composta também suporta /api/v2/extensions e /api/v2/extensions-edges via extension_list, extension_upsert, extension_delete e extension_edges.

Use os recursos bloodhound://opengraph/guide e bloodhound://opengraph/examples para design de esquema e padrões Cypher. Para esquemas OpenGraph estruturados, faça upsert do esquema de extensão primeiro e depois ingira os dados de coleta com file_upload.

Requer BloodHound Enterprise ou BloodHound CE 8.0 ou posterior. O gerenciamento de extensões OpenGraph requer BloodHound 9.0.0+ e o sinalizador de recurso correspondente habilitado.

Considerações de Segurança

Os dados do BloodHound processados por esta ferramenta são transmitidos aos servidores do seu provedor de LLM. Não use isso com dados de AD de produção, a menos que você tenha avaliado esse risco.

Casos de uso recomendados:

Ambientes de laboratório (GOAD, DetectionLab, faixas personalizadas)
Preparação para treinamento e certificação
Pesquisa e desenvolvimento de ferramentas
Análise de domínios não produtivos

Melhores práticas:

Gire os tokens da API do BloodHound regularmente
Use um token de API somente leitura quando possível
Considere uma ponte LLM local para ambientes sensíveis

Testes

# 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

Roadmap

Modo de acesso direto ao Neo4j (ignorar a API REST para travessia complexa de grafos)
Ferramentas aprimoradas para Azure/Entra ID
Melhor cobertura de caminhos de ataque ADCS
Exemplos e modelos adicionais de OpenGraph

Contribuições

Contribuições são bem-vindas. Abra uma issue para discutir mudanças significativas antes de enviar um PR.

Faça um fork do repositório
Crie um branch de funcionalidade
Adicione testes para novas funcionalidades
Execute uv run pytest e confirme que tudo passa
Envie um pull request

Agradecimentos

SpecterOps pelo BloodHound Community Edition
Orange Cyberdefense pelo GOAD (usado para testes)
@jlowin pelo FastMCP
@xpn pela inspiração MCP via o projeto Mythic MCP

Licença

GNU General Public License v3.0 — veja LICENSE para detalhes.