diff --git a/README.md b/README.md index 9307bbc4b..f1f7ef5e7 100644 --- a/README.md +++ b/README.md @@ -14,36 +14,40 @@ BloodHound uses graph theory to reveal the hidden and often unintended relations BloodHound CE is created and maintained by the [BloodHound Enterprise Team](https://bloodhoundenterprise.io). The original BloodHound was created by [@\_wald0](https://www.twitter.com/_wald0), [@CptJesus](https://twitter.com/CptJesus), and [@harmj0y](https://twitter.com/harmj0y). ## Running BloodHound Community Edition + Docker Compose is the easiest way to get up and running with BloodHound CE. Instructions below describe how to install and upgrade your deployment. ### System Requirements -BloodHound CE deploys in a traditional multi-tier container architecture consisting of databases, application, and UI layers. + +BloodHound CE deploys in a traditional multi-tier container architecture consisting of databases, application, and UI layers. **Minimum specifications:** -- 4GB of RAM -- 4 processor cores -- 10GB hard disk space +- 4GB of RAM +- 4 processor cores +- 10GB hard disk space **For large environments (>50,000 users):** -- 96GB of RAM -- 12 processor cores -- 50GB hard disk space +- 96GB of RAM +- 12 processor cores +- 50GB hard disk space ### Deploy BloodHound CE + Deploying BloodHound CE quickly with the following steps: 1. Install [Docker Desktop](https://www.docker.com/products/docker-desktop/). Docker Desktop includes Docker Compose as part of the installation. 2. Download the [Docker Compose YAML file](examples/docker-compose/docker-compose.yml) and save it to a directory where you'd like to run BloodHound. You can do this from a terminal application with `curl -L https://ghst.ly/getbhce`. - > On Windows: Execute the command in CMD, or use `curl.exe` instead of `curl` in PowerShell. + > On Windows: Execute the command in CMD, or use `curl.exe` instead of `curl` in PowerShell. 3. Navigate to the folder with the saved `docker-compose.yml` file and run `docker compose pull && docker compose up`. 4. Locate the randomly generated password in the terminal output of Docker Compose. 5. In a browser, navigate to `http://localhost:8080/ui/login`. Login with a username of `admin` and the randomly generated password from the logs. -*NOTE: The default `docker-compose.yml` example binds only to localhost (127.0.0.1). If you want to access BloodHound outside of localhost, you'll need to follow the instructions in [examples/docker-compose/README.md](examples/docker-compose/README.md) to configure the host binding for the container.* +_NOTE: The default `docker-compose.yml` example binds only to localhost (127.0.0.1). If you want to access BloodHound outside of localhost, you'll need to follow the instructions in [examples/docker-compose/README.md](examples/docker-compose/README.md) to configure the host binding for the container._ ### Upgrade BloodHound CE + Once installed, upgrade BloodHound CE to the latest version with the following steps: 1. Navigate to the folder with the saved `docker-compose.yml` file and run `docker compose pull && docker compose up`. @@ -55,13 +59,13 @@ The BloodHound team has provided some sample data for testing BloodHound without ## Installation Error Handling -- If you encounter a "failed to get console mode for stdin: The handle is invalid." ensure Docker Desktop (and associated Engine is running). Docker Desktop does not automatically register as a startup entry. +- If you encounter a "failed to get console mode for stdin: The handle is invalid." ensure Docker Desktop (and associated Engine is running). Docker Desktop does not automatically register as a startup entry.

Docker Engine Running

-- If you encounter an "Error response from daemon: Ports are not available: exposing port TCP 127.0.0.1:7474 -> 0.0.0.0:0: listen tcp 127.0.0.1:7474: bind: Only one usage of each socket address (protocol/network address/port) is normally permitted." this is normally attributed to the "Neo4J Graph Database - neo4j" service already running on your local system. Please stop or delete the service to continue. +- If you encounter an "Error response from daemon: Ports are not available: exposing port TCP 127.0.0.1:7474 -> 0.0.0.0:0: listen tcp 127.0.0.1:7474: bind: Only one usage of each socket address (protocol/network address/port) is normally permitted." this is normally attributed to the "Neo4J Graph Database - neo4j" service already running on your local system. Please stop or delete the service to continue. ``` # Verify if Docker Engine is Running @@ -71,19 +75,46 @@ docker info Stop-Service "Neo4j" -ErrorAction SilentlyContinue ``` -- A successful installation of BloodHound CE would look like the below: +- A successful installation of BloodHound CE would look like the below: https://github.com/SpecterOps/BloodHound/assets/12970156/ea9dc042-1866-4ccb-9839-933140cc38b9 +## Development Tools + +### Dozzle - Container Log Viewer + +The development environment includes [Dozzle](https://github.com/amir20/dozzle), a real-time log viewer for Docker containers that provides a clean web interface for monitoring container logs. + +#### Accessing Dozzle + +When running the development environment with `docker-compose -f docker-compose.dev.yml up` or `just bh-dev up -d`, Dozzle is available at: + +- URL: http://dozzle.localhost +- Default port: 18080 (bound to 127.0.0.1) + +#### Configuration + +Dozzle can be configured using environment variables: + +- `BH_DOZZLE_HOSTNAME`: Hostname for accessing Dozzle (default: `dozzle.localhost`) +- `BH_DOZZLE_PORT`: Port binding for Dozzle (default: `127.0.0.1:18080`) + +#### Features + +- View logs from all containers in real-time +- Filter logs by container +- Search within logs using text search +- Download logs for sharing or offline analysis + ## Useful Links -- [BloodHound Slack](https://ghst.ly/BHSlack) -- [Wiki](https://github.com/SpecterOps/BloodHound/wiki) -- [Contributors](./CONTRIBUTORS.md) -- [Docker Compose Example](./examples/docker-compose/README.md) -- [BloodHound Docs](https://support.bloodhoundenterprise.io/) -- [Developer Quick Start Guide](https://github.com/SpecterOps/BloodHound/wiki/Development) -- [Contributing Guide](https://github.com/SpecterOps/BloodHound/wiki/Contributing) +- [BloodHound Slack](https://ghst.ly/BHSlack) +- [Wiki](https://github.com/SpecterOps/BloodHound/wiki) +- [Contributors](./CONTRIBUTORS.md) +- [Docker Compose Example](./examples/docker-compose/README.md) +- [BloodHound Docs](https://support.bloodhoundenterprise.io/) +- [Developer Quick Start Guide](https://github.com/SpecterOps/BloodHound/wiki/Development) +- [Contributing Guide](https://github.com/SpecterOps/BloodHound/wiki/Contributing) ## Contact