### BloodHound CE Development Environment Quick Start

Source: https://github.com/specterops/bloodhound/wiki/Development

Commands to quickly initialize and start the BloodHound CE development environment using the `just` task runner. This includes setting up the environment and launching the main development stack.

```shell
just init
just bh-dev
```

--------------------------------

### Environment Variable Example

Source: https://github.com/specterops/bloodhound/wiki/Local-Development-with-Docker-Compose

An example file enumerating environment variables supported by BloodHound CE Docker Compose services. It allows customization of ports, hostnames, build configurations, and database credentials.

```env
.env.example
```

--------------------------------

### Beagle Extension Plan Setup Example

Source: https://github.com/specterops/bloodhound/blob/main/packages/python/beagle/README.md

An example Python snippet showing how a Beagle extension can import the global 'plans' module to add to a registry of prepared test and build plans. This is crucial for defining custom execution strategies.

```python
# Import global plans so that beagle extensions can add to a registry of prepared plans available to run
import plans
```

--------------------------------

### BloodHound Development Setup and Migration Testing Commands (Shell)

Source: https://github.com/specterops/bloodhound/wiki/Application-Database-Migrations

Commands for setting up the BloodHound development environment and performing migration testing. This includes starting the development server, managing database volumes, and checking out specific branches.

```Shell
just bh-dev
git checkout main
just bh-dev down -v
just bh-dev
just bh-dev stop
```

--------------------------------

### Manage BloodHound Docker Services

Source: https://github.com/specterops/bloodhound/blob/main/examples/docker-compose/README.md

Shows common Docker Compose commands for managing BloodHound services, including starting in the background, viewing logs, and stopping the services.

```docker
docker compose up -d
docker compose logs -f
docker compose down
```

--------------------------------

### Starting BloodHound with Imported Neo4j Data

Source: https://github.com/specterops/bloodhound/wiki/Importing-Data-From-External-Neo4J-Source

Instructions on how to start BloodHound services after copying the Neo4j data, covering both local development and Docker Compose scenarios.

```bash
# For local development:
just bh-dev

# For Docker Compose:
docker compose up
```

--------------------------------

### Start and Stop BloodHound CE with Docker Compose

Source: https://github.com/specterops/bloodhound/blob/main/examples/docker-compose/README.md

Commands to initiate and terminate the BloodHound Community Edition services managed by Docker Compose. Ensure you are in the directory containing the docker-compose.yml file before executing.

```bash
docker compose up
docker compose down
```

--------------------------------

### Graphify Usage Example

Source: https://github.com/specterops/bloodhound/blob/main/packages/go/graphify/README.md

Demonstrates how to run the Graphify tool, specifying the input directory for consumed files and the output directory for graph files.

```shell
just bh-graphify cmd/api/src/test/fixtures/fixtures/v6/ingest /tmp/
```

--------------------------------

### Accessing BloodHound CE UI

Source: https://github.com/specterops/bloodhound/wiki/Development

Instructions on how to access the BloodHound CE user interface after starting the development environment. It specifies the default URL and default login credentials.

```shell
# Navigate to http://bloodhound.localhost
# Login with user: admin
# Password can be found in the app's log output.
```

--------------------------------

### JSON Configuration Example

Source: https://github.com/specterops/bloodhound/wiki/Using-Environment-Variables-For-Sensitive-Configuration

An example of a BloodHound JSON configuration file, demonstrating the structure for default admin settings.

```json
{
    "default_admin": {
        "principal_name": "admin",
        "first_name": "BloodHound",
        "last_name": "Admin",
        "email_address": "spam@example.com"
    }
}
```

--------------------------------

### Development Environment Setup

Source: https://github.com/specterops/bloodhound/blob/main/packages/python/beagle/README.md

Commands to set up a Python virtual environment for Beagle development and install essential development tools like pip, black, and mypy. This ensures a consistent and isolated development environment.

```bash
python3 -m venv ~/beagle_venv
~/beagle_venv/bin/pip install --upgrade pip black mypy
```

--------------------------------

### Initialize Development Environment

Source: https://github.com/specterops/bloodhound/wiki/Local-Development-with-Docker-Compose

Initializes the BloodHound CE development environment by setting up default configuration files. This command is crucial for first-time setup or resetting configurations.

```bash
just init
```

--------------------------------

### Markdown Reference Link Example

Source: https://github.com/specterops/bloodhound/blob/main/rfc/bh-rfc-0.md

Demonstrates how to create inline and reference-style links in Markdown, including linking to external resources and using numbered references for clarity and maintainability.

```markdown
This is an inline link to [this repository](https://github.com/SpecterOps/BloodHound).

This is a reference link to [this repository][1] and another link to the [SpecterOps website][2].

[1]: https://github.com/SpecterOps/BloodHound
[2]: https://specterops.io
```

--------------------------------

### Just Commands for BloodHound Development

Source: https://github.com/specterops/bloodhound/wiki/Development

The 'just' command-line tool simplifies BloodHound development tasks. It manages environment initialization, service startup, debugging, and testing container orchestration.

```bash
# Initialize BloodHound environment, creating default config files
just init

# Run services in development mode with hot reloading
# Access at bloodhound.localhost, Neo4j at neo4j.localhost (neo4j:bloodhoundcommunityedition)
just bh-dev

# Run services in debug mode with hot reloading and dlv debugger
# API debug port: 3456. Attach debugger in VS Code using 'Docker Compose Debug'.
# Note: Hot reloading may cause debugger detachment.
just bh-debug

# Run integration testing containers (defaults to 'up -d')
just bh-testing

# Clear volumes and reset databases (use with any 'just' command ending in 'down')
# Example: just bh-dev down -v
```

--------------------------------

### Install BloodHound CE Helm Chart

Source: https://github.com/specterops/bloodhound/blob/main/examples/helm/README.md

Installs the BloodHound Community Edition Helm chart into a Kubernetes cluster. Ensure Helm is configured correctly for your cluster before execution. The `$BH_ROOT` variable should point to the root of the cloned repository.

```bash
helm install bhce $BH_ROOT/examples/helm/.
```

--------------------------------

### Build and Dependency Management

Source: https://github.com/specterops/bloodhound/wiki/Local-Development-with-Docker-Compose

Commands related to building the project, managing Go module dependencies, and updating UI container dependencies.

```APIDOC
just build -v
  - Description: Performs a local build of the system and updates the `go.work.sum` file. This is crucial for ensuring consistency between local development and containerized environments, especially when encountering `go.work.sum` write errors.
  - Parameters: `-v` (verbose output)
  - Returns: Build artifacts and updated `go.work.sum`.

just yarn
  - Description: Executes yarn commands and, by default, rebuilds the UI container. This ensures that changes made to yarn dependencies, configuration, or Vite are reflected in the UI.
  - Parameters: Yarn arguments (e.g., `install`, `build`)
  - Returns: Yarn operation completion and potentially rebuilt UI container.

just bh-dev build bh-ui
  - Description: Specifically rebuilds the UI container within the development environment. This is useful if changes were made without using `just yarn` and requires a container restart to take effect.
  - Parameters: None
  - Returns: Rebuilt UI container image.
```

--------------------------------

### Install Project Dependencies with Yarn

Source: https://github.com/specterops/bloodhound/wiki/Code

This command installs all project dependencies as defined in the package.json file using Yarn 3. It fetches and sets up all necessary packages for the project to run.

```bash
$ yarn
```

--------------------------------

### Run BloodHound SSO Docker Services

Source: https://github.com/specterops/bloodhound/wiki/Configuring-SSO

Starts the authentik Docker services required for SAML SSO setup. This command initiates the necessary backend services for the identity provider.

```bash
just bh-sso
```

--------------------------------

### Yarn Development and Build Commands

Source: https://github.com/specterops/bloodhound/blob/main/cmd/ui/README.md

Commands for running the BloodHound UI and managing the project using Yarn. Includes starting the development server, running tests, and building the application for production.

```bash
yarn start
```

```bash
yarn test
```

```bash
yarn build
```

--------------------------------

### BloodHound CE Configuration Example

Source: https://github.com/specterops/bloodhound/blob/main/DEVREADME.md

An example of a configuration file used within the BloodHound CE development environment. This file, typically located at `local-harnesses/build.config.json`, allows for customization of settings like the default administrator user.

```json
{
  "default_admin": "your_admin_username"
}
# If 'default_admin' is omitted, a random user 'admin' with a generated password will be created on first startup.
```

--------------------------------

### Configure Neo4j Environment Variables

Source: https://github.com/specterops/bloodhound/blob/main/examples/docker-compose/README.md

Illustrates how to configure Neo4j settings by prefixing parameters with NEO4J_ and adding them to the docker-compose.yml file. This allows for easy customization of Neo4j behavior.

```docker
services:
  graph-db:
    image: neo4j:latest
    environment:
      - NEO4J_AUTH=neo4j/your_password
      - NEO4J_PLUGINS=graph_data_science
      # ... other NEO4J_ parameters
```

--------------------------------

### Docker Compose Volume for BloodHound Configuration

Source: https://github.com/specterops/bloodhound/blob/main/examples/docker-compose/README.md

Example snippet from a docker-compose.yml file demonstrating how to mount a custom BloodHound configuration file into the container. This allows for external configuration of the BloodHound API server.

```yaml
volumes:
    - ./bloodhound.config.json:/bloodhound.config.json:ro
```

--------------------------------

### API Debugging Configuration (Air)

Source: https://github.com/specterops/bloodhound/wiki/Local-Development-with-Docker-Compose

Configuration file for `cosmtrek/air` specifically for debugging the Go API. It enables hot reloading and sets up debugging ports, often requiring a debugger to connect before the API starts.

```toml
.air.debug.toml
```

--------------------------------

### Reset Neo4j Database Volume

Source: https://github.com/specterops/bloodhound/blob/main/examples/docker-compose/README.md

Provides commands to remove the Neo4j Docker volume, effectively resetting the database without affecting other application states. It includes examples for Bash and PowerShell.

```bash
docker volume rm $(docker volume ls -q | grep neo4j-data)
```

```powershell
docker volume rm @(docker volume ls -q | Select-String neo4j-data)
```

--------------------------------

### Initializing BloodHound CE Configuration

Source: https://github.com/specterops/bloodhound/wiki/Development

Command to initialize or reset BloodHound CE configuration files to their default settings. This is useful for first-time setup or when needing to revert configuration changes.

```shell
just init
```

--------------------------------

### VS Code ANTLR Grammar Setup

Source: https://github.com/specterops/bloodhound/wiki/ANTLR-Development

Instructions for setting up the ANTLR4 grammar syntax support extension in VS Code. This allows for visualization of grammar call graphs and parsing of cypher statements.

```plaintext
1. Ensure Java is installed locally (e.g., openjdk-21-jre).
2. Install the "ANTLR4 grammar syntax support" extension from the VS Code Marketplace.
3. Open the grammar file located at `packages/go/cypher/grammar`.
4. Use the command `ANTLR: Show Grammar Call Graph` (Ctrl+Shift+P) to visualize the grammar structure.
5. Create a text file (scratchpad) anywhere on your filesystem.
6. Write a cypher statement in the scratch file.
7. Open the Debug charm and select `Debug Cypher Grammar` to parse the statement and view the parsing graph.
```

--------------------------------

### Build System Locally

Source: https://github.com/specterops/bloodhound/wiki/Development

Executes a local build of the system using the `just` build tool. This command is useful for updating the `go.work.sum` file, which is necessary for local development and container synchronization.

```shell
just build -v
```

--------------------------------

### JetBrains ANTLR Grammar Setup

Source: https://github.com/specterops/bloodhound/wiki/ANTLR-Development

Instructions for setting up the ANTLR v4 plugin in JetBrains IDEs. This enables previewing the parse tree, hierarchy, and profiler for cypher statements against the grammar.

```plaintext
1. Install the "ANTLR v4" plugin from the JetBrains plugin repository.
2. Open the grammar file located at `packages/go/cypher/grammar`.
3. Open the ANTLR Preview window via the ANTLR icon or `View` -> `Tool Windows` -> `ANTLR Preview`.
4. Select the "Input" radio button and type your cypher statement.
5. View the parsed output in the `Parse Tree`, `Hierarchy`, or `Profiler` tabs.
```

--------------------------------

### BloodHound Testing Commands

Source: https://github.com/specterops/bloodhound/wiki/Development

BloodHound encourages automated testing. This includes Go unit/integration tests and React unit tests. Specific commands are provided to run these test suites.

```bash
# Run all Go and UI unit tests
just test

# Run all tests, including those that haven't changed since last run
just test -a

# Run tests in verbose mode, showing output during execution
just test -v

# Run integration tests (ensure testing databases are running with 'just bh-testing')
just test -i

# Run Cypress UI integration tests
npx cypress run

# Open Cypress UI testing GUI for interactive test execution
npx cypress open
```

--------------------------------

### Environment Variable Mapping Example

Source: https://github.com/specterops/bloodhound/wiki/Using-Environment-Variables-For-Sensitive-Configuration

Demonstrates how JSON configuration options are mapped to environment variables for BloodHound, using underscores to denote nested structures.

```shell
bhe_default_admin_principal_name=admin
bhe_default_admin_first_name=BloodHound
bhe_default_admin_last_name=Admin
bhe_default_admin_principal_email=spam@example.com
```

--------------------------------

### Integration Test Configuration

Source: https://github.com/specterops/bloodhound/wiki/Local-Development-with-Docker-Compose

The default configuration file used for integration and E2E tests. It points to specific databases and is generated from a template during the `just init` process.

```json
local-harnesses/integration.config.json
```

--------------------------------

### Run BloodHound SSO Setup

Source: https://github.com/specterops/bloodhound/wiki/Configuring-SSO

Executes the necessary Docker commands to spin up the authentik identity provider services for BloodHound SSO. This command initiates the backend services required for OIDC authentication.

```shell
just bh-sso

```

--------------------------------

### RFC Title Section Example

Source: https://github.com/specterops/bloodhound/blob/main/rfc/bh-rfc-0.md

Illustrates the required structure for the main title of a BloodHound RFC, appearing below the YAML frontmatter, and the optional placement of an image.

```markdown
# BloodHound RFC Structure & Style Guide

![xkcd comic - standards](https://imgs.xkcd.com/comics/standards.png)

```

--------------------------------

### Conventional Commit: Simple Example

Source: https://github.com/specterops/bloodhound/blob/main/rfc/bh-rfc-2.md

A basic conventional commit message format. It includes the commit type and a concise description of the change. This format is suitable for straightforward updates.

```conventional-commits
feat: Adds table view to Explore page

Closes BED-5555
```

--------------------------------

### Conventional Commit: With Multiple Footers

Source: https://github.com/specterops/bloodhound/blob/main/rfc/bh-rfc-2.md

An example of a commit message with multiple footer entries, allowing for tracking multiple issues or providing additional metadata. Footers are separated by newlines.

```conventional-commits
chore(deps): Update dependencies to latest versions

Fixes BED-5555
Resolves #777
```

--------------------------------

### Conventional Commit: Detailed Example

Source: https://github.com/specterops/bloodhound/blob/main/rfc/bh-rfc-2.md

A detailed conventional commit message format, including scope, body, and footer. This format allows for more context, explaining the changes and linking to related issues or tickets.

```conventional-commits
docs(bh-rfc-2): Address PR feedback

- fixes 'Adherance' typo
- removes superfluous types
- adds `chore` and `wip` types
- updates ticket/issue linking to be required
- updates examples for ticket/issue linking and adds reference

fixes: BED-5475
```

--------------------------------

### Format Go Code with gofmt

Source: https://github.com/specterops/bloodhound/wiki/Contributing

Ensures Go code adheres to standard formatting practices. Run this command from the root directory before pushing your changes to apply consistent styling and simplify code reviews.

```bash
gofmt -s -w
```

--------------------------------

### BloodHound CE Environment File Configuration

Source: https://github.com/specterops/bloodhound/wiki/Development

Details on using the `.env.example` file to configure BloodHound CE's Docker Compose services. This file allows customization of port forwards, hostnames, build configurations, and database credentials by copying and modifying it to `.env`.

```shell
# Copy .env.example to .env
# cp .env.example .env
# Modify .env to customize environment variables like:
# - Service port forwards
# - Service hostnames
# - Build configuration file selection
# - Database credentials
```

--------------------------------

### Building BloodHound CE Locally

Source: https://github.com/specterops/bloodhound/wiki/Development

Command to build the BloodHound CE project locally. The build process uses a Python tool called `beagle` and outputs artifacts to the `dist` directory.

```shell
just build
```

--------------------------------

### JetBrains IDE Go Remote Debug Configuration

Source: https://github.com/specterops/bloodhound/wiki/Development

Configuration settings for establishing a remote debugging connection for Go applications within JetBrains IDEs. This setup requires specifying the host, port, and the desired behavior upon disconnection.

```APIDOC
JetBrains IDE Go Remote Debug Configuration:
  Host: localhost
  Port: 3456
  On disconnect: Leave it running
```

--------------------------------

### Golang Mock Generation with mockgen

Source: https://github.com/specterops/bloodhound/wiki/Code

Explains the process and conventions for generating mocks using the mockgen framework in Golang. It includes instructions for generating mocks for package interfaces and third-party dependencies.

```golang
//go:generate go run go.uber.org/mock/mockgen -destination=./mocks/filename.go -package=mocks . Comma,Separated,List,Of,Interfaces
//go:generate go run go.uber.org/mock/mockgen -destination=./{package path}/mock.go -package={package basename} {package} Comma,Separated,List,Of,Interfaces
```

--------------------------------

### BloodHound Docker Image Tagging

Source: https://github.com/specterops/bloodhound/blob/main/examples/docker-compose/README.md

Explains the different tags available for BloodHound Docker images, ranging from stable releases to development builds. These tags are used to specify the desired version when pulling or running the Docker image.

```docker
docker pull specterops/bloodhound:latest
docker pull specterops/bloodhound:5
docker pull specterops/bloodhound:5.0
docker pull specterops/bloodhound:5.0.0
docker pull specterops/bloodhound:5.0.0-rc1
docker pull specterops/bloodhound:edge
```

--------------------------------

### RFC YAML Frontmatter Structure

Source: https://github.com/specterops/bloodhound/blob/main/rfc/bh-rfc-0.md

Defines the mandatory and optional metadata fields required at the beginning of each BloodHound RFC document, formatted in YAML.

```yaml
---
# Mandatory fields
bh-rfc: 0
title: BloodHound RFC Structure & Style Guide
authors: |
    [Lees, Dillon](dlees@specterops.io)
status: ACCEPTED
created: 2025-01-21
---

```

--------------------------------

### Bloodhound Development Environment Commands

Source: https://github.com/specterops/bloodhound/wiki/Local-Development-with-Docker-Compose

Commands for initializing, running, and debugging the Bloodhound development environment. These commands abstract complex Docker Compose operations and provide convenient shortcuts for common development workflows.

```APIDOC
just init
  - Description: Initializes the development environment, creating default configuration files like `build.config.json` and `integration.config.json`.
  - Parameters: None
  - Returns: Environment initialization status.

just bh-dev
  - Description: Runs services in development mode with hot reloading enabled. The application is typically available at `bloodhound.localhost`, and Neo4j's web interface at `neo4j.localhost` (default credentials: `neo4j:bloodhoundcommunityedition`). This command manages Docker Compose profiles and should be used instead of direct `docker compose` invocation for development.
  - Parameters: None
  - Returns: Running development services.

just bh-debug
  - Description: Runs services in debug mode with hot reloading. The API container is launched with `dlv` (Delve debugger) and pauses execution until a debugger is attached. The debug port is `3456`. A VS Code configuration named `Docker Compose Debug` is provided. Note: Hot reloading may cause the debugger to detach, requiring reattachment.
  - Parameters: None
  - Returns: Debugging session for the API container.

just bh-testing
  - Description: Executes integration testing containers. Defaults to `up -d` to run tests in the background. This command also manages Docker Compose profiles for testing environments.
  - Parameters: None
  - Returns: Running integration test containers.
```

--------------------------------

### Conventional Commit: Breaking Change (Inline)

Source: https://github.com/specterops/bloodhound/blob/main/rfc/bh-rfc-2.md

Demonstrates an alternative way to denote a breaking change by appending an exclamation mark '!' after the type and scope, before the description.

```conventional-commits
fix!(v1-api): Remove deprecated user endpoint

This change removes the /v1/users endpoint as it has been deprecated for
over a year. Clients should migrate to the /v2/users endpoint.
```

--------------------------------

### Run Dev Tool with GOBIN

Source: https://github.com/specterops/bloodhound/wiki/Code

This bash script demonstrates how to temporarily set the GOBIN environment variable to a project-specific bin directory. This ensures that development tools are executed from the correct location, preventing conflicts and ensuring consistent versions are used without needing to vendor them.

```bash
#!/usr/bin/env bash

readonly PROJECT_ROOT_PATH="$(dirname $(realpath ${0}))/path/to/project/root"

export GOBIN="$PROJECT_ROOT_PATH/bin"
$GOBIN/myDevTool "$@"
```

--------------------------------

### Beagle CLI Help Output

Source: https://github.com/specterops/bloodhound/blob/main/packages/python/beagle/README.md

The detailed help output from the Beagle CLI, showing positional arguments like 'test' and options such as --ci, --all-tests, --verbose, and --integration. This describes the command-line interface's functionality.

```text
usage: beagle [-h] [-c] [-a] [-v] [-i] {test}

Beagle: the BloodHound build, test and packaging automation framework.

positional arguments:
  {test}             action for beagle to pursue

options:
  -h, --help         show this help message and exit
  -c, --ci           informs beagle that it is running in a CI container
  -a, --all-tests    run all tests regardless of staged changes
  -v, --verbose      enable extra output
  -i, --integration  enable integration tests
```

--------------------------------

### Testing Docker Compose Configuration

Source: https://github.com/specterops/bloodhound/wiki/Local-Development-with-Docker-Compose

Docker Compose configuration used specifically for running testing databases. These databases are typically set to autorestart for continuous testing.

```yaml
docker-compose.testing.yml
```

--------------------------------

### Build Configuration Template

Source: https://github.com/specterops/bloodhound/wiki/Local-Development-with-Docker-Compose

A template for the build configuration JSON file, providing default settings for BloodHound CE. It includes development-friendly options like disabling password resets and setting static passwords.

```json
local-harnesses/build.config.json.template
```

--------------------------------

### Bloodhound Volume and Data Management

Source: https://github.com/specterops/bloodhound/wiki/Local-Development-with-Docker-Compose

Commands for managing persistent data volumes used by the development and testing environments. These are useful for resetting the state or cleaning up old data.

```APIDOC
just bh-clear-volumes
  - Description: Clears development environment data by running `docker compose down -v`. This removes all data from database and caching volumes, providing a clean slate.
  - Parameters: None
  - Returns: Development containers stopped and volumes removed.

just bh-testing-clear-volumes
  - Description: Clears testing environment data by running `docker compose down -v` against testing containers. This specifically removes data from testing database volumes.
  - Parameters: None
  - Returns: Testing containers stopped and volumes removed.
```