BloodHound Community Edition Custom Installation

Learn how to install and customize BloodHound Community Edition (BHCE).

The recommended installation method for most users is the BloodHound CLI. However, if you need more control over the installation process or want to customize specific aspects of your BHCE environment, this guide provides alternative installation methods and customization options.

Use cases for custom installation include:

• Switch between PostgreSQL and Neo4j backends
• Run multiple BHCE instances on a single machine

Prerequisites

BloodHound CE deploys in a traditional multi-tier container architecture consisting of database, application, and UI layers.

To complete installation, ensure your system meets the following requirements:

Minimum specifications	For large environments (>50K users)
8GB of RAM	96GB of RAM
4 processor cores	12 processor cores
10GB hard disk space	50GB hard disk space

During startup, BloodHound CE runs initial graph analysis that may continue for about the first minute after launch. On low-memory hosts, sending API requests immediately after container startup can cause the bloodhound container to terminate with exit code 137 (out of memory).

To avoid this behavior, allocate at least 8GB of RAM or wait for startup processing to complete before running API automation tasks such as user creation.

Install with Docker Compose

BloodHound Community Edition is a security auditing tool that was written to test the resilience of networks against attackers. Because this tool can equally be used for evil, some anti-malware and endpoint detection and response (EDR) solutions flag BloodHound and its components as malware.

If you encounter issues with downloads being blocked and files being prohibited from execution, create targeted allow-list entries for the specific BloodHound binaries, supporting libraries, and installation paths required for your deployment. We recommend that you set up BloodHound on a dedicated machine so that your regular work environment remains protected. If you are planning to use BloodHound on a corporate network, notify your Security Operations Center (SOC) or Chief Information Security Officer (CISO) ahead of time and ensure you have the required permissions to audit the network.

For legal and ethical reasons, you must never use BloodHound on systems you do not own or lack explicit permission to audit.

This installation method provides more control over each configuration file and works well for running multiple BHCE instances on a single machine.

1. Install Docker Desktop

   Follow the instructions in the Docker documentation to install Docker Desktop for your operating system.

   Docker Desktop must be running to build and test BHCE. Start Docker Desktop on your machine.
2. Create installation directory

   Create a new directory on your machine to hold the BHCE configuration files.

   mkdir bhce
   cd bhce
   
3. Download configuration files

   Download the following configuration files:

   • docker-compose.yml
   • bloodhound.config.json
4. Add configuration files

   Move the configuration files into the directory you created.

   mv /path/to/downloaded/files/* .
   

   Continue to the Customizations section below to modify your installation as needed.
5. Start BloodHound

   Now that your files are ready, you can bring the containers up using the following command:

   docker compose up
   

   You only need to perform this step once. In the future, you can use the Docker Desktop application to start and turn off BloodHound. You can still use the CLI to bring the containers up or down if you prefer.

Build from source

You can also build the BHCE code from source if you plan on contributing to the project or customizing the application beyond what is possible with configuration files.

Prerequisite

The following table lists the minimum requirements to build BHCE from source:

These requirements are higher than the minimum specifications needed to run BHCE.

Requirement	Version/Specification
RAM	16GB
Processor cores	8
Just	---
Python	3.10
Go	1.24
Node.js	22
Yarn	3.6
Docker Desktop	---

Set up your environment

The code repository contains all the necessary files to build BHCE. Follow these steps to set up your development environment:

1. Clone the repository

   Clone the BloodHound repository from GitHub:

   git clone https://github.com/SpecterOps/BloodHound.git
   
2. Start Docker Desktop

   Docker Desktop must be running to build and test BHCE. Start Docker Desktop on your machine.

3. Navigate to repository directory

   Change to the cloned BloodHound repository directory:

   cd BloodHound
   
4. Install dependencies

   Use the following command to install project dependencies and initialize the environment:

   just init
   
5. Start development environment

   Use the following command to start the development environment:

   just bh-dev
   
6. Compile BHCE

   The BloodHound team maintains a Python tool called stbernard for building and testing the project.

   To build locally, run the following command:

   just build
   

   The build process generates all artifacts in the dist/ directory.

   See the following resources for next steps:

   • Source code wiki on GitHub for testing and debugging details.

   • Customizations section below to modify your installation as needed.

Customizations

This section describes common customizations you can make to your BHCE installation.

Change backend database

PostgreSQL provides significant advantages over Neo4j as a backend database, particularly in terms of query performance and speed.

For information on supported Cypher syntax in PostgreSQL, see Supported Cypher Syntax.

PostgreSQL

If you are currently using a Neo4j backend database and want to change to PostgreSQL, follow these steps.

1. Add the PostgreSQL graph driver

   Modify the bloodhound.config.json file and add a line in the main section to use PostgreSQL as the graph driver:

   ...
   "graph_driver": "pg",
   ...
   

   This is an example of adding the line between default_password and log_level, but it can be anywhere at the top level.

   {
     "bind_addr": "127.0.0.1:8080",
     "collectors_base_path": "/etc/bloodhound/collectors",
     "default_admin": {
       "password": "<SOMETHING>",
       "principal_name": "admin"
     },
     "default_password": "<SOMETHING>",
     "graph_driver": "pg", 
     "log_level": "INFO",
     "log_path": "bloodhound.log",
     "metrics_port": ":2112",
     "recreatedefaultadmin": "false",
     "root_url": "http://127.0.0.1:8080",
     "tls": {
       "cert_file": "",
       "key_file": ""
     },
     "version": 1,
     "work_dir": "/opt/bloodhound/work"
   }                        
   
2. Remove the Neo4j service

   Modify the docker-compose.yml file to remove the Neo4j service and its dependencies.

   • Delete the graph_db section:

       graph-db: 
         labels:
           name: "bhce_neo4j"
         image: docker.io/library/neo4j:4.4
         environment:
           - NEO4J_AUTH=${NEO4J_USER:-neo4j}/${NEO4J_SECRET:-bloodhoundcommunityedition}
           - NEO4J_dbms_allow__upgrade=${NEO4J_ALLOW_UPGRADE:-true}
         # Database ports are disabled by default. Please change your database password to something secure before uncommenting
         ports:
           - 127.0.0.1:${NEO4J_DB_PORT:-7687}:7687
           - 127.0.0.1:${NEO4J_WEB_PORT:-7474}:7474
         volumes:
           - ${NEO4J_DATA_MOUNT:-neo4j-data}:/data
         healthcheck:
           test:
             [
               "CMD-SHELL",
               "wget -O /dev/null -q http://localhost:7474 || exit 1"
             ]
           interval: 10s
           timeout: 5s
           retries: 5
           start_period: 30s
     

   • Delete the two lines at the end of the bloodhound section:

           graph-db: 
             condition: service_healthy
     

   • Delete the following line from the volumes section:

       neo4j-data: 
     

     The following is the complete modified docker-compose.yml file for PostgreSQL:

     Show full file example

     # Copyright 2023 Specter Ops, Inc.
     #
     # Licensed under the Apache License, Version 2.0
     # you may not use this file except in compliance with the License.
     # You may obtain a copy of the License at
     #
     #     http://www.apache.org/licenses/LICENSE-2.0
     #
     # Unless required by applicable law or agreed to in writing, software
     # distributed under the License is distributed on an "AS IS" BASIS,
     # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
     # See the License for the specific language governing permissions and
     # limitations under the License.
     #
     # SPDX-License-Identifier: Apache-2.0
     
     services:
       app-db:
         image: docker.io/library/postgres:16
         environment:
           - PGUSER=${POSTGRES_USER:-bloodhound}
           - POSTGRES_USER=${POSTGRES_USER:-bloodhound}
           - POSTGRES_PASSWORD=${POSTGRES_PASSWORD:-bloodhoundcommunityedition}
           - POSTGRES_DB=${POSTGRES_DB:-bloodhound}
         # Database ports are disabled by default. Please change your database password to something secure before uncommenting
         # ports:
         #   - 127.0.0.1:${POSTGRES_PORT:-5432}:5432
         volumes:
           - postgres-data:/var/lib/postgresql/data
         healthcheck:
           test:
             [
               "CMD-SHELL",
               "pg_isready -U ${POSTGRES_USER:-bloodhound} -d ${POSTGRES_DB:-bloodhound} -h 127.0.0.1 -p 5432"
             ]
           interval: 10s
           timeout: 5s
           retries: 5
           start_period: 30s
     
       bloodhound:
         image: docker.io/specterops/bloodhound:${BLOODHOUND_TAG:-latest}
         environment:
           - bhe_disable_cypher_complexity_limit=${bhe_disable_cypher_complexity_limit:-false}
           - bhe_enable_cypher_mutations=${bhe_enable_cypher_mutations:-false}
           - bhe_graph_query_memory_limit=${bhe_graph_query_memory_limit:-2}
           - bhe_database_connection=user=${POSTGRES_USER:-bloodhound} password=${POSTGRES_PASSWORD:-bloodhoundcommunityedition} dbname=${POSTGRES_DB:-bloodhound} host=app-db
           - bhe_neo4j_connection=neo4j://${NEO4J_USER:-neo4j}:${NEO4J_SECRET:-bloodhoundcommunityedition}@graph-db:7687/
           - bhe_recreate_default_admin=${bhe_recreate_default_admin:-false}
           - bhe_graph_driver=${GRAPH_DRIVER:-neo4j}
           ### Add additional environment variables you wish to use here.
           ### For common configuration options that you might want to use environment variables for, see `.env.example`
           ### example: bhe_database_connection=${bhe_database_connection}
           ### The left side is the environment variable you're setting for bloodhound, the variable on the right in `${}`
           ### is the variable available outside of Docker
         ports:
           ### Default to localhost to prevent accidental publishing of the service to your outer networks
           ### These can be modified by your .env file or by setting the environment variables in your Docker host OS
           - ${BLOODHOUND_HOST:-127.0.0.1}:${BLOODHOUND_PORT:-8080}:8080
         ### Uncomment to use your own bloodhound.config.json to configure the application
         # volumes:
         #   - ./bloodhound.config.json:/bloodhound.config.json:ro
         depends_on:
           app-db:
             condition: service_healthy
     
     volumes:
       postgres-data:
     

Neo4j

If you are currently using a PostgreSQL backend database and want to change to Neo4j, follow these steps.

1. Add the Neo4j service

   Replace your docker-compose.yml file with the following:

   # Copyright 2023 Specter Ops, Inc.
   #
   # Licensed under the Apache License, Version 2.0
   # you may not use this file except in compliance with the License.
   # You may obtain a copy of the License at
   #
   #     http://www.apache.org/licenses/LICENSE-2.0
   #
   # Unless required by applicable law or agreed to in writing, software
   # distributed under the License is distributed on an "AS IS" BASIS,
   # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
   # See the License for the specific language governing permissions and
   # limitations under the License.
   #
   # SPDX-License-Identifier: Apache-2.0
   
   services:
     app-db:
       labels:
         name: "bhce_postgres"
       image: docker.io/library/postgres:16
       environment:
         - PGUSER=${POSTGRES_USER:-bloodhound}
         - POSTGRES_USER=${POSTGRES_USER:-bloodhound}
         - POSTGRES_PASSWORD=${POSTGRES_PASSWORD:-bloodhoundcommunityedition}
         - POSTGRES_DB=${POSTGRES_DB:-bloodhound}
       # Database ports are disabled by default. Please change your database password to something secure before uncommenting
       # ports:
       #   - 127.0.0.1:${POSTGRES_PORT:-5432}:5432
       volumes:
         - postgres-data:/var/lib/postgresql/data
       healthcheck:
         test:
           [
             "CMD-SHELL",
             "pg_isready -U ${POSTGRES_USER:-bloodhound} -d ${POSTGRES_DB:-bloodhound} -h 127.0.0.1 -p 5432"
           ]
         interval: 10s
         timeout: 5s
         retries: 5
         start_period: 30s
   
     graph-db:
       labels:
         name: "bhce_neo4j"
       image: docker.io/library/neo4j:4.4
       environment:
         - NEO4J_AUTH=${NEO4J_USER:-neo4j}/${NEO4J_SECRET:-bloodhoundcommunityedition}
         - NEO4J_dbms_allow__upgrade=${NEO4J_ALLOW_UPGRADE:-true}
       # Database ports are disabled by default. Please change your database password to something secure before uncommenting
       ports:
         - 127.0.0.1:${NEO4J_DB_PORT:-7687}:7687
         - 127.0.0.1:${NEO4J_WEB_PORT:-7474}:7474
       volumes:
         - ${NEO4J_DATA_MOUNT:-neo4j-data}:/data
       healthcheck:
         test:
           [
             "CMD-SHELL",
             "wget -O /dev/null -q http://localhost:7474 || exit 1"
           ]
         interval: 10s
         timeout: 5s
         retries: 5
         start_period: 30s
   
     bloodhound:
       labels:
         name: bhce_bloodhound
       image: docker.io/specterops/bloodhound:${BLOODHOUND_TAG:-latest}
       environment:
         - bhe_disable_cypher_complexity_limit=${bhe_disable_cypher_complexity_limit:-false}
         - bhe_enable_cypher_mutations=${bhe_enable_cypher_mutations:-true}
         - bhe_graph_query_memory_limit=${bhe_graph_query_memory_limit:-2}
         - bhe_database_connection=user=${POSTGRES_USER:-bloodhound} password=${POSTGRES_PASSWORD:-bloodhoundcommunityedition} dbname=${POSTGRES_DB:-bloodhound} host=app-db
         - bhe_neo4j_connection=neo4j://${NEO4J_USER:-neo4j}:${NEO4J_SECRET:-bloodhoundcommunityedition}@graph-db:7687/
         - bhe_recreate_default_admin=${bhe_recreate_default_admin:-false}
         - bhe_enable_text_logger=${bhe_enable_text_logger:-true}
         ### Add additional environment variables you wish to use here.
         ### For common configuration options that you might want to use environment variables for, see `.env.example`
         ### example: bhe_database_connection=${bhe_database_connection}
         ### The left side is the environment variable you're setting for bloodhound, the variable on the right in `${}`
         ### is the variable available outside of Docker
       ports:
         ### Default to localhost to prevent accidental publishing of the service to your outer networks
         ### These can be modified by your .env file or by setting the environment variables in your Docker host OS
         - ${BLOODHOUND_HOST:-127.0.0.1}:${BLOODHOUND_PORT:-8080}:8080
       ### Uncomment to use your own bloodhound.config.json to configure the application
       volumes:
         - ./bloodhound.config.json:/bloodhound.config.json:ro
       depends_on:
         app-db:
           condition: service_healthy
         graph-db:
           condition: service_healthy
   
   volumes:
     neo4j-data:
     postgres-data:
   
2. Remove the PostgreSQL graph driver

   Delete the following line from the bloodhound.config.json file:

   "graph_driver": "pg", 
   

Run multiple instances simultaneously

You might want to run multiple BHCE instances to:

• Test a Neo4j backend alongside a PostgreSQL backend
• Evaluate a new version of BHCE without affecting your current installation
• Isolate data for different engagements

You must bind each instance to a different port on your machine. The steps below show you which settings to edit.

Follow these steps to run multiple BHCE instances on a single machine.

1. Change default BHCE port

   In the docker-compose.yml file, update the BloodHound service port binding to use a different port.

   The following example uses port 8585 instead of the default 8080 port:

   - ${BLOODHOUND_HOST:-127.0.0.1}:${BLOODHOUND_PORT:-8585}:8080
   
2. Change Neo4j web console port

   If you are running multiple Neo4j databases, update the Neo4j web console port binding in the docker-compose.yml file to use a different port.

   The following example uses port 7575 instead of the default 7474 port:

   - 127.0.0.1:${NEO4J_WEB_PORT:-7575}:7474
   

   You must also update the health check to use the new port:

   "wget -O /dev/null -q http://localhost:7575 || exit 1"
   

   The Neo4j database port 7687 runs only inside the Docker container, so you do not need to change it.

Expose BHCE outside of localhost

You might need to access your BHCE instance from another computer than the one it is installed on. The default installation does not expose the port outside of localhost. To do it, you will need to change the IP Address the BloodHound UI.

In the docker-compose.yml file, update the BloodHound service port binding to use a different IP Address.

The following example uses IP 0.0.0.0 to bind the port 8080 to all interfaces and IP Addresses on the machine. If the machine has multiple IP Addresses, you can set that specific IP Address.

- ${BLOODHOUND_HOST:-0.0.0.0}:${BLOODHOUND_PORT:-8080}:8080