npm package: @modular-intelligence/bloodhound
Description: MCP server for BloodHound CE API — Active Directory attack path analysis
Latest version: 1.0.2

# BloodHound MCP Server

MCP server for BloodHound CE (Community Edition) API integration — Active Directory attack path analysis and security assessment.

## Overview

This server provides read-only access to BloodHound CE's graph database for Active Directory security analysis. It enables automated queries for attack paths, privilege escalation routes, and vulnerable configurations without requiring direct BloodHound UI interaction.

**IMPORTANT**: This is an API integration tool, not a CLI wrapper. It communicates directly with the BloodHound CE REST API.

## Features

- **Attack Path Analysis**: Find shortest paths between AD principals
- **Privilege Escalation**: Identify paths from compromised accounts to high-value targets
- **Vulnerability Detection**: Discover Kerberoastable and ASREPRoastable users
- **Domain Enumeration**: List Domain Admins and high-value targets
- **Search**: Query AD principals by name and type
- **Read-Only**: No data modification or upload capabilities
- **Security**: HTTPS enforcement, input validation, rate limiting awareness

## Prerequisites

### 1. BloodHound CE Instance

You need a running BloodHound Community Edition instance with:
- REST API enabled and accessible
- API authentication configured
- Active Directory data already ingested

### 2. API Credentials

Obtain an API key from your BloodHound CE instance:

```bash
# Navigate to BloodHound CE web interface
# Go to: Administration → API Keys → Generate New Key
# Save the generated key securely
```

### 3. Environment Variables

Set the following environment variables:

```bash
export BLOODHOUND_API_URL="https://bloodhound.corp.example.com"
export BLOODHOUND_API_KEY="your-api-key-here"
```

**Security Notes**:
- API URL MUST use HTTPS (except for localhost/127.0.0.1)
- API keys should be stored securely (e.g., in `.env` files, secrets manager)
- Never commit API keys to version control

## Installation

```bash
cd bloodhound
bun install
bun run build
```

## Usage

### Running the Server

```bash
bun run start
```

Or use with MCP clients that support stdio transport.

### Available Tools

#### 1. `bloodhound_shortest_path`

Find the shortest attack path between two AD principals.

**Parameters**:
- `source` (string, required): Source principal name (e.g., `"JOHN@CORP.LOCAL"`)
- `target` (string, required): Target principal name (e.g., `"ADMIN@CORP.LOCAL"`)
- `edge_types` (array, optional): Edge types to include (e.g., `["MemberOf", "AdminTo", "HasSession"]`)
- `depth` (number, optional): Maximum path depth (default: 10, max: 20)

**Example**:
```json
{
  "source": "JOHN@CORP.LOCAL",
  "target": "DOMAIN ADMINS@CORP.LOCAL",
  "depth": 10
}
```

**Response**:
```json
{
  "source": "JOHN@CORP.LOCAL",
  "target": "DOMAIN ADMINS@CORP.LOCAL",
  "path": [
    {
      "node_name": "JOHN@CORP.LOCAL",
      "node_type": "User",
      "edge_to_next": "MemberOf"
    },
    {
      "node_name": "IT-SUPPORT@CORP.LOCAL",
      "node_type": "Group",
      "edge_to_next": "AdminTo"
    },
    {
      "node_name": "DC01.CORP.LOCAL",
      "node_type": "Computer",
      "edge_to_next": "HasSession"
    },
    {
      "node_name": "DOMAIN ADMINS@CORP.LOCAL",
      "node_type": "Group"
    }
  ],
  "path_length": 4,
  "risk_score": 0.85
}
```

---

#### 2. `bloodhound_domain_admins`

Enumerate Domain Admin users in the environment.

**Parameters**:
- `domain` (string, optional): Domain SID or name to filter by
- `limit` (number, optional): Maximum results (default: 50, max: 500)

**Example**:
```json
{
  "domain": "CORP.LOCAL",
  "limit": 50
}
```

**Response**:
```json
{
  "domain": "CORP.LOCAL",
  "admins": [
    {
      "name": "ADMINISTRATOR@CORP.LOCAL",
      "type": "User",
      "enabled": true,
      "last_logon": "2026-02-09T10:30:00Z",
      "paths_to_da": 0
    },
    {
      "name": "DA-BACKUP@CORP.LOCAL",
      "type": "User",
      "enabled": true,
      "last_logon": "2026-01-15T08:00:00Z",
      "paths_to_da": 0
    }
  ],
  "total": 2
}
```

---

#### 3. `bloodhound_kerberoastable`

Find Kerberoastable users (vulnerable to offline password cracking).

**Parameters**:
- `domain` (string, optional): Domain SID or name to filter by
- `limit` (number, optional): Maximum results (default: 50, max: 500)

**Example**:
```json
{
  "domain": "CORP.LOCAL",
  "limit": 50
}
```

**Response**:
```json
{
  "domain": "CORP.LOCAL",
  "users": [
    {
      "name": "SVC-SQL@CORP.LOCAL",
      "spn": "MSSQLSvc/sql01.corp.local:1433",
      "enabled": true,
      "admin_count": 1,
      "last_logon": "2026-02-08T12:00:00Z",
      "password_last_set": "2024-06-01T10:00:00Z"
    }
  ],
  "total": 1
}
```

**Security Context**: Kerberoastable users with old passwords are high-priority targets.

---

#### 4. `bloodhound_asreproastable`

Find ASREPRoastable users (no Kerberos preauthentication required).

**Parameters**:
- `domain` (string, optional): Domain SID or name to filter by
- `limit` (number, optional): Maximum results (default: 50, max: 500)

**Example**:
```json
{
  "domain": "CORP.LOCAL",
  "limit": 50
}
```

**Response**:
```json
{
  "domain": "CORP.LOCAL",
  "users": [
    {
      "name": "LEGACY-USER@CORP.LOCAL",
      "enabled": true,
      "admin_count": 0,
      "last_logon": "2025-12-01T09:00:00Z"
    }
  ],
  "total": 1
}
```

**Security Context**: ASREPRoastable users are vulnerable to offline password attacks without authentication.

---

#### 5. `bloodhound_owned_paths`

Find attack paths from compromised principals to targets.

**Parameters**:
- `owned_principal` (string, required): Already-compromised principal
- `target_type` (enum, optional): `"domain_admin"` | `"high_value"` | `"specific"` (default: `"domain_admin"`)
- `specific_target` (string, optional): Specific target principal (required if `target_type` is `"specific"`)
- `depth` (number, optional): Maximum path depth (default: 10, max: 20)

**Example**:
```json
{
  "owned_principal": "JOHN@CORP.LOCAL",
  "target_type": "domain_admin",
  "depth": 10
}
```

**Response**:
```json
{
  "source": "JOHN@CORP.LOCAL",
  "paths": [
    {
      "nodes": ["JOHN@CORP.LOCAL", "IT-SUPPORT@CORP.LOCAL", "DC01.CORP.LOCAL", "DOMAIN ADMINS@CORP.LOCAL"],
      "edges": ["MemberOf", "AdminTo", "HasSession"],
      "length": 4
    }
  ],
  "total_paths": 1
}
```

**Use Case**: Post-exploitation privilege escalation planning.

---

#### 6. `bloodhound_high_value_targets`

List principals marked as high-value targets.

**Parameters**:
- `domain` (string, optional): Domain SID or name to filter by
- `limit` (number, optional): Maximum results (default: 50, max: 500)

**Example**:
```json
{
  "domain": "CORP.LOCAL",
  "limit": 50
}
```

**Response**:
```json
{
  "domain": "CORP.LOCAL",
  "targets": [
    {
      "name": "DOMAIN ADMINS@CORP.LOCAL",
      "type": "Group",
      "description": "Domain Admins",
      "incoming_paths_count": 145
    },
    {
      "name": "DC01.CORP.LOCAL",
      "type": "Computer",
      "description": "Primary Domain Controller",
      "incoming_paths_count": 89
    }
  ],
  "total": 2
}
```

---

#### 7. `bloodhound_search`

Search for AD principals by name or properties.

**Parameters**:
- `query` (string, required): Search query (1-256 characters)
- `type` (enum, optional): `"user"` | `"group"` | `"computer"` | `"ou"` | `"gpo"` | `"domain"` | `"all"` (default: `"all"`)
- `limit` (number, optional): Maximum results (default: 50, max: 500)

**Example**:
```json
{
  "query": "admin",
  "type": "user",
  "limit": 50
}
```

**Response**:
```json
{
  "results": [
    {
      "name": "ADMINISTRATOR@CORP.LOCAL",
      "type": "User",
      "objectid": "S-1-5-21-...",
      "domain": "CORP.LOCAL",
      "properties": {
        "enabled": true,
        "admincount": 1
      }
    }
  ],
  "total": 1
}
```

---

## Security Considerations

### Input Validation

All inputs are validated:
- Principal names: 1-256 characters, alphanumeric + `._-\@` only
- Path depth: 1-20 hops
- Limits: 1-500 results

### Network Security

- **HTTPS Required**: API URL must use HTTPS (except localhost)
- **Authentication**: Bearer token authentication with API keys
- **No Data Upload**: Server is read-only, no data modification

### Rate Limiting

BloodHound CE APIs may have rate limits. This server does not implement client-side rate limiting. Monitor your BloodHound instance for `429 Too Many Requests` responses.

### API Key Management

```bash
# Store in .env file (DO NOT commit)
echo "BLOODHOUND_API_URL=https://bloodhound.corp.example.com" >> .env
echo "BLOODHOUND_API_KEY=your-api-key-here" >> .env

# Or use environment variable management tools
export BLOODHOUND_API_URL="https://bloodhound.corp.example.com"
export BLOODHOUND_API_KEY="$(cat /secure/path/to/key.txt)"
```

### Least Privilege

The API key should have:
- Read-only access to graph data
- No administrative privileges
- No data upload/modification permissions

## BloodHound CE Setup

### Installation

Follow the official BloodHound CE documentation:
- [BloodHound CE GitHub](https://github.com/SpecterOps/BloodHound)
- [Installation Guide](https://support.bloodhoundenterprise.io/hc/en-us/articles/17468450058267)

### Data Collection

Before using this server, you need AD data in BloodHound:

```bash
# Using SharpHound (Windows)
SharpHound.exe --CollectionMethods All --Domain corp.local

# Using azurehound (Azure AD)
azurehound -u "user@domain.com" -p "password" list --tenant "tenant-id"

# Import into BloodHound CE via UI
# Upload the generated ZIP files
```

### API Configuration

1. Navigate to BloodHound CE web interface
2. Go to **Administration** → **API Keys**
3. Click **Generate New Key**
4. Copy the key immediately (it won't be shown again)
5. Set appropriate permissions (read-only recommended)

## Error Handling

The server returns errors in this format:

```json
{
  "content": [
    {
      "type": "text",
      "text": "Error: Principal name contains invalid characters"
    }
  ],
  "isError": true
}
```

Common errors:
- `BLOODHOUND_API_URL environment variable is required`: Set the API URL
- `BLOODHOUND_API_KEY environment variable is required`: Set the API key
- `BloodHound API URL must use HTTPS or localhost`: Use HTTPS
- `BloodHound API error (401)`: Invalid API key or expired token
- `BloodHound API error (404)`: Principal or resource not found
- `BloodHound API error (429)`: Rate limit exceeded
- `Principal name contains invalid characters`: Invalid principal format

## Development

### Building

```bash
bun run build
```

### Testing

```bash
# Set test environment variables
export BLOODHOUND_API_URL="https://bloodhound-test.corp.local"
export BLOODHOUND_API_KEY="test-api-key"

# Run the server
bun run start
```

### TypeScript Configuration

The project uses:
- **Target**: ES2022
- **Module**: ES2022 with bundler resolution
- **Strict mode**: Enabled
- **Runtime**: Bun

## Architecture

```
bloodhound/
├── package.json          # Dependencies and scripts
├── tsconfig.json         # TypeScript configuration
├── README.md             # This file
└── src/
    ├── index.ts          # Main MCP server
    ├── schemas.ts        # Zod validation schemas
    ├── security.ts       # Security utilities
    └── tools/
        ├── bloodhound-shortest-path.ts
        ├── bloodhound-domain-admins.ts
        ├── bloodhound-kerberoastable.ts
        ├── bloodhound-asreproastable.ts
        ├── bloodhound-owned-paths.ts
        ├── bloodhound-high-value-targets.ts
        └── bloodhound-search.ts
```

## Use Cases

### Red Team Operations

- **Initial Access**: Find ASREPRoastable/Kerberoastable users for credential access
- **Privilege Escalation**: Map paths from compromised accounts to Domain Admin
- **Lateral Movement**: Identify intermediate targets in attack paths

### Blue Team / Defense

- **Attack Surface Analysis**: Identify exposures and misconfigurations
- **Hardening**: Find and fix privilege escalation paths
- **Monitoring**: Track changes in high-value target exposure

### Security Audits

- **Compliance**: Document AD security posture
- **Reporting**: Automated extraction of security metrics
- **Trend Analysis**: Track remediation progress over time

## Limitations

- **Read-Only**: Cannot modify BloodHound data or upload new collections
- **API Dependent**: Requires BloodHound CE API (not compatible with legacy BloodHound)
- **No GraphQL**: Uses REST API endpoints, not raw Neo4j queries
- **Rate Limits**: Subject to BloodHound CE API rate limiting
- **Network Required**: Requires network access to BloodHound instance

## BloodHound CE API Endpoints

This server uses the following API endpoints:

- `POST /api/v2/graphs/shortest-path` - Shortest path queries
- `POST /api/v2/graphs/cypher` - Custom Cypher queries
- `GET /api/v2/search` - Principal search

Refer to the BloodHound CE API documentation for endpoint details.

## Troubleshooting

### Connection Refused

```
Error: fetch failed
```

**Solution**: Verify `BLOODHOUND_API_URL` is correct and BloodHound CE is running.

### Unauthorized

```
BloodHound API error (401): Unauthorized
```

**Solution**: Check `BLOODHOUND_API_KEY` is valid and not expired.

### No Results

```json
{
  "results": [],
  "total": 0
}
```

**Solution**:
- Verify AD data is ingested in BloodHound
- Check query parameters (domain name, principal format)
- Ensure principals exist in the database

### HTTPS Error

```
BloodHound API URL must use HTTPS or localhost
```

**Solution**: Use `https://` in `BLOODHOUND_API_URL` or use `localhost`/`127.0.0.1` for testing.

## Contributing

This is a security tool. Contributions should:
- Maintain read-only behavior
- Preserve input validation
- Include error handling
- Follow TypeScript strict mode
- Document security implications

## License

[Specify license]

## Disclaimer

This tool is for authorized security testing and analysis only. Unauthorized access to Active Directory environments is illegal. Users are responsible for:
- Obtaining proper authorization
- Complying with applicable laws and policies
- Securing API credentials
- Monitoring and logging usage

## References

- [BloodHound CE GitHub](https://github.com/SpecterOps/BloodHound)
- [BloodHound Documentation](https://bloodhound.readthedocs.io/)
- [Active Directory Attack Paths](https://adsecurity.org/)
- [Kerberoasting](https://attack.mitre.org/techniques/T1558/003/)
- [AS-REP Roasting](https://attack.mitre.org/techniques/T1558/004/)

## Support

For issues related to:
- **This MCP Server**: Open an issue in this repository
- **BloodHound CE**: Refer to [SpecterOps Support](https://support.bloodhoundenterprise.io/)
- **Active Directory**: Consult Microsoft documentation

---

**Last Updated**: 2026-02-09
**Version**: 1.0.0
**Compatibility**: BloodHound CE API v2