Use this file to discover all available pages before exploring further.
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:
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.
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.
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.
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.
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.0services: 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_healthyvolumes: postgres-data:
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.0services: 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_healthyvolumes: neo4j-data: postgres-data:
2
Remove the PostgreSQL graph driver
Delete the following line from the bloodhound.config.json file:
To secure BHCE with HTTPS, add your certificate information to the tls block in the bloodhound.config.json file. Then, make the certificate files available in the BloodHound container with volume mounts in the docker-compose.yml file.
After you set both cert_file and key_file, BloodHound uses HTTPS on that port instead of HTTP.
1
Obtain a TLS certificate and key
For a local or testing deployment, generate a self-signed certificate and key with openssl:
Self-signed certificates are appropriate for local testing only. For any shared or production deployment, use a certificate issued by a trusted certificate authority (CA).
2
Move the certificate and key to a mountable directory
Create a directory next to your docker-compose.yml and bloodhound.config.json files and move the certificate and key into it. The examples on this page use a directory named cert:
In the bloodhound.config.json file, set cert_file and key_file to the paths where the certificate and key will be available inside the container.These values must match the container-side destination of the volume mount you add in the next step, not the location of the files on your host:
By default, the volume mount for the bloodhound service is commented out. Make sure to uncomment it before you continue. Otherwise, the container ignores your custom configuration and continues to serve plain HTTP.
5
Start BloodHound and verify HTTPS
Bring up (or recreate) the bloodhound container so the new volume mounts and configuration take effect:
docker compose up -d --force-recreate bloodhound
The --force-recreate option ensures the container picks up changes to volumes and configuration. A plain docker compose restart does not reapply volume mounts.
6
Verify HTTPS
Browse to https://127.0.0.1:8080 and confirm that BloodHound loads over HTTPS.The default URL is http://127.0.0.1:8080, so make sure to change the protocol to https:// in the address bar.The listening port is unchanged. TLS is negotiated on the same port that the BloodHound service binds to by default (8080).
Browsers display a certificate warning when you use a self-signed certificate; this is expected and does not occur with a CA-issued certificate.
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:
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:
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 that the BloodHound UI binds to.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.
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: