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:
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)
4GB of RAM
96GB of RAM
4 processor cores
12 processor cores
10GB hard disk space
50GB hard disk space
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, you may have to shut off these protections. 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, please notify your Security Operations Center (SOC) 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.
Move the configuration files into the directory you created.
Copy
Ask AI
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:
Copy
Ask AI
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:
Copy
Ask AI
graph-db: condition: service_healthy
Delete the following line from the volumes section:
Copy
Ask AI
neo4j-data:
The following is the complete modified docker-compose.yml file for PostgreSQL:
Show full file example
Copy
Ask AI
# 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:
Copy
Ask AI
# 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:
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:
Copy
Ask AI
- 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 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.