BloodHound Community Edition

https://github.com/specterops/bloodhound
Admin
BloodHound Community Edition is a security analysis tool that leverages graph theory to reveal...
Tokens:97,222
Snippets:754
Trust Score:9.5
License:Apache-2.0
Update:4 weeks ago
Show doc for...
Tokens:
Raw
### Install Dependencies and Start Dev Server

Source: https://github.com/specterops/bloodhound/blob/main/packages/javascript/doodle-ui/README.md

Navigate to the directory, install dependencies, and start the development server.

```bash
cd DoodleUI
yarn
```

```bash
yarn dev
```

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

### GitHub CLI Authentication Setup

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

Install the GitHub CLI, authenticate with GitHub, and verify authentication status. The tool automatically uses the GitHub CLI token when available.

```bash
# Install gh CLI (if not already installed)
# macOS: brew install gh
# Linux: See https://github.com/cli/cli/blob/trunk/docs/install_linux.md
# Windows: See https://github.com/cli/cli#installation

# Authenticate with GitHub
gh auth login

# Verify authentication
stbernard dora auth --status
```

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

### Install LikeC4 and serve/export architecture diagrams

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

Install LikeC4 globally with npm, then serve interactive diagrams locally or export to PNG. Requires Node.js ≥ 22; run `node --version` to confirm before installing.

```bash
# Install LikeC4 (if not already installed)
npm install -g likec4

# Serve interactive diagrams locally
cd bhce/server/docs/architecture
likec4 serve

# Or export to PNG
likec4 export png -o ./diagrams
```

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

### Get subcommand help

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

Shows how to get help for a specific subcommand, using `test` as an example. Pass `-h` or `-help` after the subcommand.

```text
$ go tool stbernard test -h
```

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

### Install all project dependencies with Yarn

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

Run this command to install all project dependencies using Yarn 3.

```bash
$ yarn
```

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

### Configure environment for a11y tests

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

Copy the example environment file and set the required login credentials. With A11Y_TEST_SERVE="true" (the default in .env.example), Playwright starts the Vite dev server itself.

```sh
cp cmd/ui/.env.example cmd/ui/.env
# then edit cmd/ui/.env and set A11Y_TEST_USERNAME / A11Y_TEST_PASSWORD
```

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

### Overview section example

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

Shows the required second-level heading '1. Overview' followed by a succinct summary of the RFC.

```markdown
## 1. Overview

This document outlines how to write, structure, and maintain BloodHound RFC documents. It covers best practices for clarity, consistency, and completeness so that new RFCs can be easily drafted, reviewed, accepted, and referenced by the BloodHound team.
```

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

### PUT /pg-migration/start/

Source: https://github.com/specterops/bloodhound/blob/main/cmd/api/src/api/tools/PG_MIGRATE.md

Starts the migration process from Neo4j to Postgres. The migration runs asynchronously.

```APIDOC
## PUT /pg-migration/start/

### Description
Kicks off the migration process from Neo4j to Postgres. The migration runs asynchronously.

### Method
PUT

### Endpoint
/pg-migration/start/

### Response
#### Success Response (202 Accepted)
No response body is specified.
```

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

### Start authentik services with just bh-sso

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

Run this command to spin up the authentik Docker services for local development. Initial bootstrapping may take some time.

```bash
just bh-sso
```

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

### Install Fontsource Dependencies

Source: https://github.com/specterops/bloodhound/blob/main/packages/javascript/doodle-ui/README.md

Install the required Figtree and Nunito Sans fonts via Fontsource.

```sh
yarn add @fontsource/figtree @fontsource/nunito-sans
```

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

### Install Allure CLI

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

One-time installation of the Allure command-line tool, either via Homebrew on macOS or npm for cross-platform use. The npm version requires Java on PATH.

```sh
brew install allure              # macOS, recommended (brings the JRE)
# or:
npm i -g allure-commandline      # cross-platform, requires Java on PATH
```

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

### Detailed commit message example

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

A comprehensive example showing a commit with a scope, body, and footer, including a ticket reference.

```text
docs(bh-rfc-2): Address PR feedback BED-5475

- 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

```

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

### Simple commit message example

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

A minimal example of a conventional commit message with a type and description.

```text
feat: Adds table view to Explore page BED-5555

```

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

### Install BloodHound CE Helm chart

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

Run this command from the repository root to install the chart into your Kubernetes cluster. Ensure helm is configured to point at the correct cluster before running.

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

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

### Bootstrap auth for themes in global.setup.ts

Source: https://github.com/specterops/bloodhound/blob/main/packages/javascript/bh-playwright-testing/README.md

A global.setup.ts that bootstraps auth for both themes. It installs a graph data stub and logs in, caching auth state per theme.

```ts
import path from 'path';
import { test as setup } from 'bh-playwright-testing';
import { loginAndSnapshotThemes } from 'bh-playwright-testing/auth';
import { installGraphHasDataStub } from 'bh-playwright-testing/stubs';
import { authStorageStateFor, type Theme } from 'bh-playwright-testing/themes';

setup('Generate and cache auth state', async ({ page }) => {
    await installGraphHasDataStub(page);
    await loginAndSnapshotThemes({
        page,
        username: process.env.TEST_USERNAME!,
        password: process.env.TEST_PASSWORD!,
        storageStatePathFor: (theme: Theme) => path.resolve(__dirname, '..', authStorageStateFor(theme)),
    });
});
```

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

### Restore Postgres database after upgrade (commands 7-10)

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

Restore the dumped database after the upgrade and bring the full stack back up. Starts the database container, restores from dump.sql, stops it, and then starts all containers.

```bash
# 7. Start only the database container
docker compose up app-db

# 8. Restore the database from the dump file
docker compose exec -T app-db psql < dump.sql

# 9. Stop the database container with Ctrl+C

# 10. Finally, start all containers
docker compose up
```

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

### Install build dependencies in Kali container

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

Installs the required packages for building the Debian package: devscripts, sed, jq, wget, dh-golang, golang-any, and yarnpkg.

```bash
apt update && apt install devscripts sed jq wget dh-golang golang-any yarnpkg
```

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

### View the Allure report

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

Install the Allure CLI once (brew on macOS) and then build and serve the Allure report HTML, opening a browser. The run writes raw Allure results but not HTML.

```sh
brew install allure    # one-time; see Allure Report section for non-macOS
yarn report:a11y       # builds and serves report HTML and opens a browser
```

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

### Use New SKU Flag in Code

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

Usage example for the new flag. The service handles defaults, so error checking is not needed.

```go
if s.DogTags.GetFlagAsBool(dogtags.MY_NEW_FEATURE) {
    // feature enabled
}
```

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

### Dogtags API Response Example

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

Example response from the GET /api/v2/dog-tags endpoint. Always a flat map with dot notation keys for namespacing, but no nested objects.

```json
{
    "data": {
        "auth.environment_targeted_access_control": false,
        "privilege_zones.tier_limit": 3,
        "privilege_zones.label_limit": 10,
        "privilege_zones.multi_tier_analysis": false
    }
}
```

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

### Clone DoodleUI Repository

Source: https://github.com/specterops/bloodhound/blob/main/packages/javascript/doodle-ui/README.md

Clone the repository to start local development.

```bash
git clone git@github.com:SpecterOps/DoodleUI.git
```

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

### Run Kali Docker container for build

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

Starts an interactive Docker container using the Kali Linux last release image, mounting the current directory to /src/BloodHound.

```bash
podman run -it -v .:/src/BloodHound docker.io/kalilinux/kali-last-release
```

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

### Goose migration file with Up and Down annotations

Source: https://github.com/specterops/bloodhound/blob/main/cmd/api/src/database/migration/migration.md

Required structure for all migration files. The -- +goose Up section applies a change, and -- +goose Down rolls it back. The example creates and drops a table named 'example'.

```sql
-- +goose Up
CREATE TABLE example (id INT);
-- +goose Down
DROP TABLE IF EXISTS example;
```

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

### Test directory layout tree

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

Shows the directory structure for the tests folder, including the global setup file and the a11y subdirectory where accessibility specs live.

```text
tests/
├── global.setup.ts   # Logs in once and snapshots auth storage state
└── a11y/             # Accessibility regression suite
    └── *.a11y.spec.ts

```

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

### Path file name examples

Source: https://github.com/specterops/bloodhound/wiki/OpenAPI-Spec-Guide

Illustrates how path file names are derived from tag group and URL path. Each entry shows the endpoint, its tag, URL, and resulting filename.

```yaml
/api/v2/spec:
  tag: API Info (api-info)
  url: spec
  filename: api-info.spec.yaml
/api/v2/version:
  tag: API Info (api-info)
  url: version
  filename: api-info.version.yaml
/api/v2/bloodhound-users/{user_id}:
  tag: BloodHound Users (bh-users)
  url: bloodhound-users/{user_id}
  filename: bh-users.bloodhound-user.id.yaml
/api/v2/bloodhound-users/{user_id}/mfa:
  tag: BloodHound Users (bh-users)
  url: bloodhound-users/{user_id}/mfa
  filename: bh-users.bloodhound-users.id.mfa.yaml
```

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

### package.json scripts section for dev dependency

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

Add a script entry to package.json to use a dev dependency without global install or relative paths. The example shows a 'cool-tools' script that runs the 'cool-tools' binary.

```json
{
    ...
    "scripts": {
        "cool-tools": "cool-tools",
        ...
    }
    ...
}
```

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

### Markdown example for '3. Considerations' section

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

Shows the optional '3. Considerations' section with subsections using third-level headings. The example includes subsections for '3.1 Impact on Existing Systems', '3.2 Security & Compliance', and '3.3 Implementation Plan', with placeholder text.

```markdown
## 3. Considerations

### 3.1 Impact on Existing Systems

I'm a little teapot.

### 3.2 Security & Compliance

#### 3.2.1 Risks

I am short and stout.

### 3.3 Implementation Plan

#### 3.3.1 Stages

- Here is my ladle.
- Here is my spout.
```

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

### Markdown inline and reference links example

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

Shows how to create inline links and reference links in Markdown. Reference links use numbered placeholders defined at the bottom of the document. This example is from section 8.4.1.1.

```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
```

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

### Install dependencies for Playwright a11y suite

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

Run from the root to install workspace packages and the Playwright browsers (chromium and firefox) needed by the a11y suite.

```sh
yarn install
yarn workspace bloodhound-ui playwright install chromium firefox
```

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

### Check GitHub Authentication Status

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

Check authentication status or get guided authentication prompts. The second command prompts to run gh auth login.

```bash
# Check authentication status
stbernard dora auth --status

# Guide to authenticate (prompts to run gh auth login)
stbernard dora auth
```

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

### Markdown example for '2. Motivation & Goals' section

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

Shows the required second-level heading and a bulleted list of goals. The heading must be exactly '## 2. Motivation & Goals'. The example includes three goals: Consistency, Clarity, and Completeness.

```markdown
## 2. Motivation & Goals

RFCs should invite respectful discussion and serve as a means to encode, review, and reach decisions by consensus. As such, a set of standards is required to describe how to properly author a RFC with the following goals:

- **Consistency** - Ensure all RFCs follow a standard structure and style, making them easy to read, maintain, and discover.
- **Clarity** - Provide clear guidelines for vocabulary, phrasing, and structuring a RFC.
- **Completeness** - Ensure each RFC includes all necessary contextual information, references, and supporting materials for readers and decision makers.
```

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

### Title section example with image

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

Shows the first-level heading for the proposal title and an optional image or diagram placed immediately after the title.

```markdown
# BloodHound RFC Structure & Style Guide

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

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

### Markdown example of proposal sections

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

Shows the markdown structure for a proposal's detailed sections, including second-level headings (##) and third-level headings (###) with sequential numbering. The example covers versioning, release schedule, and support topics.

```markdown
## 4. Versioning

All releases conform to the [Semantic Versioning Specification](semver.org).

### 4.1 Release Candidates

Release candidates are published with the pre-release suffix `-rc` and a non-zero number corresponding to the number of attempts made to produce a stable release. For example, `v1.2.0-rc1`, `v1.2.0-rc2`, etc..

## 5. Release Schedule & Support

### 5.1 Major and Minor Releases

Major and minor releases are delivered semi-continuously on a schedule internally managed by the BloodHound Product and Engineering teams. However, end-users can anticipate a new release at the end of a given release iteration. For example, at the time of this writing a release iteration is considered three weeks; therefore, at the end of a three-week release iteration a new major or minor version will be generally available.

### 5.2 Hotfix/Patch Releases

Hotfix or patched versions are released off-schedule at the discretion of the BloodHound Product and Engineering teams. Hotfix or patched versions are published to address critical defects that can be fixed and sufficiently tested ahead of the next major or minor release.

### 5.3 Support

Due to the nature of the product's continuous delivery cycle, only the latest release is actively supported during a given release iteration. For example, if a critical defect has been identified and the BloodHound Product and Engineering teams agree to author a hotfix/patch release, the fix will exist in the patched version and subsequent versions, however, the fix will not get backported to any earlier version that has the same defect.
```

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

### Footer examples for ticket references

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

Examples of footer items that relate a ticket or issue number. These show various formats for referencing issues, including 'Closes #1111', 'Fixes BED-5555', 'resolves: #777', and a combined example with multiple references.

```text
Closes #1111

Fixes BED-5555

resolves: #777

CLOSES: #1, resolves #2, Fix: BED-4444
```

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

### Run Cypress UI tests with npx cypress run

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

Executes Cypress UI integration tests in a headless/CLI mode. Requires Cypress to be installed.

```bash
npx cypress run
```

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

### Run Docker Compose services in background

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

Start the services in the background using docker compose up -d. Use docker compose logs -f to follow logs, and docker compose down to stop services.

```bash
docker compose up -d
```

```bash
docker compose logs -f
```

```bash
docker compose down
```

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

### Combined Node Usage Example

Source: https://github.com/specterops/bloodhound/blob/main/cmd/ui/src/rendering/RENDERING.md

Example of adding a node with the custom 'combined' type, which combines the 'image' and 'border' node types. The node requires x, y, size, type, borderColor, and image properties.

```javascript
graph.addNode(key, {
    x: 10,
    y: 20,
    size: 30,
    type: 'combined',
    borderColor: '#000000',
    image: './icons/computer.svg'
});
```

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

### Default Admin JSON Configuration

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

Example JSON configuration for the default admin user. This is the base configuration that can be overridden using environment variables.

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

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

### Install MFA Enrollment Stub in Playwright Test

Source: https://github.com/specterops/bloodhound/blob/main/packages/javascript/bh-playwright-testing/README.md

Installs the MFA enrollment stub in a Playwright test to control the API response for the MFA dialog. The stub falls through for requests it doesn't own, so test-local overrides win under Playwright's LIFO routing.

```typescript
import { installMFAEnrollmentStub } from 'bh-playwright-testing/stubs';

test('MFA dialog', async ({ page }) => {
    await installMFAEnrollmentStub(page);
    // Click the MFA toggle and walk the dialog steps.
});
```

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

### Glyph Nodes Usage Example

Source: https://github.com/specterops/bloodhound/blob/main/cmd/ui/src/rendering/RENDERING.md

Example of adding a node with the custom 'glyphs' type, which extends 'combined' to render up to 4 glyphs around the node edge. The glyphs array uses GlyphLocation and GLYPHS constants. Only one glyph per GlyphLocation value is rendered; later elements take precedence.

```javascript
graph.addNode(key, {
    x: 10,
    y: 20,
    size: 30,
    type: 'glyphs',
    borderColor: '#000000',
    image: './icons/computer.svg',
    glyphs: [
        {
            location: GlyphLocation.TOP_RIGHT,
            image: `./icons/${GLYPHS.tierZero.icon.iconName}.svg`,
            backgroundColor: GLYPHS.tierZero.background,
        },
    ]
});
```

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

### Install DoodleUI via Yarn

Source: https://github.com/specterops/bloodhound/blob/main/packages/javascript/doodle-ui/README.md

Use this command to add the DoodleUI package to your project dependencies.

```bash
$ yarn add @bloodhoundenterprise/DoodleUI
```

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

### Curved Edges Usage Example

Source: https://github.com/specterops/bloodhound/blob/main/cmd/ui/src/rendering/RENDERING.md

Example of adding an edge with the custom 'curved' type, which renders groups of edges as quadratic bezier curves. Requires groupPosition and groupSize; optional direction can be EdgeDirection.BACKWARDS to flip the curve.

```javascript
graph.addEdgeWithKey(key, edge.source, edge.target, {
    size: 3,
    type: 'curved',
    label: edge.label,
    color: '#406F8E',
    groupPosition: 5,
    groupSize: 10,
    direction: EdgeDirection.BACKWARDS
});
```

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

### User model in Go

Source: https://github.com/specterops/bloodhound/wiki/OpenAPI-Spec-Guide

Example Go struct for a User model. Used to illustrate how to define application models in OpenAPI schemas, with fields like ID, UpdatedAt, Deleted, Name, Password, and Email.

```go
type User struct {
    ID int
    UpdatedAt time.Time
    Deleted bool
    Name string
    Password string
    Email string
}
```

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

### Route registration with permission requirement

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

Registers the GET endpoint for the feature, requiring the AppReadApplicationConfiguration permission. Uses the router and handlers container.

```go
package routes

import (
    "github.com/specterops/bloodhound/cmd/api/src/api/router"
    "github.com/specterops/bloodhound/cmd/api/src/auth"
    "github.com/specterops/bloodhound/server/myfeature/internal/handlers"
)

func Register(routerInst *router.Router, handlers *handlers.Handlers) {
    permissions := auth.Permissions()
    routerInst.GET("/api/v2/myfeature/:id", handlers.GetMyRecord).
        RequirePermissions(permissions.AppReadApplicationConfiguration)
}
```

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

### Create dogtags service with overrides using NewTestService and TestOverrides

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

Use this snippet in tests that need specific flag values. Values not in the overrides map fall back to defaults. The example sets PZ_MULTI_TIER_ANALYSIS to true, PZ_TIER_LIMIT to 5, and PZ_LABEL_LIMIT to 3.

```go
dogtagsService := dogtags.NewTestService(dogtags.TestOverrides{
    Bools: map[dogtags.BoolDogTag]bool{dogtags.PZ_MULTI_TIER_ANALYSIS: true},
    Ints:  map[dogtags.IntDogTag]int64{dogtags.PZ_TIER_LIMIT: 5, dogtags.PZ_LABEL_LIMIT: 3},
})
```

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

### E2E Test Pattern for server/<feature>/<feature>_e2e_test.go

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

Uses the servertest.NewHarness to provision an isolated database and test server for feature routing. Includes examples for testing unauthenticated access and authenticated requests with a minted JWT.

```go
// Copyright 2026 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

//go:build integration

package appcfg_test

import (
    "context"
    "encoding/json"
    "fmt"
    "net/http"
    "testing"

    "github.com/specterops/bloodhound/cmd/api/src/api/router"
    "github.com/specterops/bloodhound/cmd/api/src/database"
    "github.com/specterops/bloodhound/cmd/api/src/database/types/null"
    "github.com/specterops/bloodhound/cmd/api/src/model"
    "github.com/specterops/bloodhound/server/appcfg"
    "github.com/specterops/bloodhound/server/internal/servertest"
    "github.com/stretchr/testify/require"
)

func TestGetMyEndpoint_WithRouting(t *testing.T) {
    var (
        ctx = context.Background()
        // NewHarness provisions an isolated database, wires the production router
        // with the FOSS global middleware, registers your feature's routes, and
        // starts a test server. All resources are torn down automatically.
        harness = servertest.NewHarness(t, func(routerInst *router.Router, db *database.BloodhoundDB) {
            appcfg.Register(routerInst, db.Pool())
        })
        db     = harness.DB
        server = harness.Server
        user   = model.User{
            PrincipalName: "test-user@example.com",
            EmailAddress:  null.StringFrom("test-user@example.com"),
            EULAAccepted:  true, // Required for permission checks to work
            Roles:         model.Roles{servertest.AdminRole(t, ctx, db)},
        }
        // MintJWT persists the user with an auth secret and returns a valid bearer token.
        token = servertest.MintJWT(t, ctx, db, harness.Auther, user)
    )
    _ = db // available for seeding data inside subtests

    t.Run("returns 401 when unauthenticated", func(t *testing.T) {
        req, err := http.NewRequest(http.MethodGet, server.URL+"/api/v2/my-endpoint", nil)
        require.NoError(t, err)

        resp, err := http.DefaultClient.Do(req)
        require.NoError(t, err)
        defer resp.Body.Close()

        require.Equal(t, http.StatusUnauthorized, resp.StatusCode)
    })

    t.Run("returns 200 with valid data", func(t *testing.T) {
        req, err := http.NewRequest(http.MethodGet, server.URL+"/api/v2/my-endpoint", nil)
        require.NoError(t, err)
        req.Header.Set("Authorization", fmt.Sprintf("Bearer %s", token))

        resp, err := http.DefaultClient.Do(req)
        require.NoError(t, err)
        defer resp.Body.Close()

        require.Equal(t, http.StatusOK, resp.StatusCode)

        var result MyResponseView
        err = json.NewDecoder(resp.Body).Decode(&result)
        require.NoError(t, err)
        require.NotEmpty(t, result.ID)
    })
}
```

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

### GET /pg-migration/status/

Source: https://github.com/specterops/bloodhound/blob/main/cmd/api/src/api/tools/PG_MIGRATE.md

Returns the current migration status, indicating whether the migrator is idle, migrating, or canceling.

```APIDOC
## GET /pg-migration/status/

### Description
Returns a status indicating whether the migrator is currently running.

### Method
GET

### Endpoint
/pg-migration/status/

### Response
#### Success Response (200)
- **state** (string) - The current migration state: "idle", "migrating", or "canceling".

#### Response Example
{
  "state": "idle"
}
```

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

### Test Debian package with QEMU

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

Boots a Kali Linux live ISO in QEMU with KVM enabled, attaching a USB tablet and a FAT drive containing the built Debian package for testing.

```bash
qemu-system-x86_64 -cdrom Downloads/kali-linux-2025.2-live-amd64.iso -m 8G --enable-kvm -usb -device usb-tablet \
  -drive file=fat:rw:(PATH_TO_DEB)
```

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

### GC daemon integration in startup entrypoint

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

Integration of the AuditMaintainer into the GC daemon constructor during startup.

```go
// After modules.Register returns services
bhceServices, err := modules.Register(bhceDeps)
if err != nil {
	return err
}

// Pass AuditMaintainer to GC daemon constructor
gcDaemon := gc.NewDaemon(
	connections.RDMS,
	bhceServices.AuditMaintainer, // New dependency
	retentionConfig,
)
```

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

### Test route registration and authentication in routes_test.go

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

Provides a test for the Register function, verifying that the GET /api/v2/<feature>/:id route is registered and that unauthenticated requests return a 401 status. The file is located at server/<feature>/internal/routes/routes_test.go.

```Go
// Copyright 2026 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

package routes_test

import (
    "net/http"
    "net/http/httptest"
    "testing"

    "github.com/gorilla/mux"
    "github.com/specterops/bloodhound/cmd/api/src/api/router"
    "github.com/specterops/bloodhound/cmd/api/src/auth"
    "github.com/specterops/bloodhound/cmd/api/src/config"
    "github.com/specterops/bloodhound/server/<feature>/internal/handlers"
    "github.com/specterops/bloodhound/server/<feature>/internal/handlers/mocks"
    "github.com/specterops/bloodhound/server/<feature>/internal/routes"
    "github.com/stretchr/testify/require"
)

func TestRegister(t *testing.T) {
    var (
        cfg        = config.Configuration{}
        authorizer = auth.NewAuthorizer(nil)
        routerInst = router.NewRouter(cfg, authorizer, "")
        mockSvc    = mocks.NewMockMyFeature(t)
        h          = handlers.NewHandlersContainer(mockSvc)
    )

    routes.Register(&routerInst, h)

    t.Run("GET /api/v2/<feature>/:id is registered", func(t *testing.T) {
        req := httptest.NewRequest(http.MethodGet, "/api/v2/<feature>/123", nil)
        var routeMatch mux.RouteMatch

        matched := routerInst.Match(req, &routeMatch)
        require.True(t, matched, "Route should be registered")
    })

    t.Run("returns 401 when unauthenticated", func(t *testing.T) {
        req := httptest.NewRequest(http.MethodGet, "/api/v2/<feature>/123", nil)
        rec := httptest.NewRecorder()

        routerInst.ServeHTTP(rec, req)

        require.Equal(t, http.StatusUnauthorized, rec.Code)
    })
}
```

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

### Repository directory tree

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

Shows the top-level directory layout of the BloodHound repository, including cmd, dist, dockerfiles, examples, packages, and tools. Use it to understand where source code, built artifacts, and tooling live.

```text
.
├── cmd                                // Artifact source code and their integration tests
|   |                                  // Partitioned By: Utility
│   ├── api
│   ├── ui
|   └── ...
|
├── dist                               // Built artifacts (git ignored)
|
├── dockerfiles                        // Misc. Dockerfiles
|
├── examples                           // Examples for Deploying BloodHound
|
├── packages                           // Libraries/Modules/Packages/Plugins (a.k.a. re-useable do-dads) and their UNIT tests
|   |                                  // Partitioned By: Language/Runtime
│   ├── go
│   |   └── ...
|   |
│   └── javascript
│       └── ...
|
└── tools                              // Misc. tooling (docker compose related files, etc)
```

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

### YAML frontmatter example for bh-rfc-0

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

Required YAML frontmatter at the beginning of every RFC. Includes bh-rfc, title, authors, status, and created fields. The authors field uses literal block scalar style.

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

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

### Register feature routes in routes.go

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

Defines the Register function that attaches a GET endpoint for /api/v2/<feature>/:id to the router, requiring the AppReadApplicationConfiguration permission. The file is located at server/<feature>/internal/routes/routes.go.

```Go
// Copyright 2026 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

package routes

import (
    "github.com/specterops/bloodhound/cmd/api/src/api/router"
    "github.com/specterops/bloodhound/cmd/api/src/auth"
    "github.com/specterops/bloodhound/server/<feature>/internal/handlers"
)

// Register attaches the <feature> endpoints to the given router instance.
func Register(routerInst *router.Router, handlers *handlers.Handlers) {
    var permissions = auth.Permissions()

    routerInst.GET("/api/v2/<feature>/:id", handlers.GetMyRecord).
        RequirePermissions(permissions.AppReadApplicationConfiguration)
}
```

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

### Audit module Register function and Maintainer interface (Go)

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

Defines the Maintainer interface for partition lifecycle operations and the Register function that wires the audit service to its PostgreSQL store, starts the buffered result-writer worker, and returns both the service and maintainer. Called by the BHCE module registry during startup.

```go
// Maintainer provides partition lifecycle operations for the GC daemon.
type Maintainer interface {
	PreCreateNextPartition(ctx context.Context) error
	DropExpiredPartitions(ctx context.Context, retentionMonths int) error
}

// Register wires the audit service to its PostgreSQL store, starts the
// buffered result-writer worker, and returns both the service (for middleware
// and handlers) and the maintainer (for the GC daemon).
// This is called by the BHCE module registry during startup.
func Register(pool *pgxpool.Pool) (Service, Maintainer, error)
```

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

### Generate mocks for a package file

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

Place this //go:generate comment in each file that contains interfaces to generate mocks for that file. Run `just go generate ./...` to keep mocks in sync.

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

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

### Run St Bernard with go tool

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

Shows the simplest way to run St Bernard using `go tool`. This is the primary invocation method.

```text
$ go tool stbernard
```

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

### Create Partitions Covering Legacy Range and Future Months

Source: https://github.com/specterops/bloodhound/blob/main/server/docs/design/audit/migration-procedure.md

Creates partitions for the legacy data range plus the current and next month. The DO block iterates month by month and creates a partition for each month using dynamic SQL.

```sql
-- Example: Legacy data spans 2024-01 to 2026-05, current month is 2026-06

-- +goose StatementBegin
DO $$
DECLARE
    start_date DATE := '2024-01-01';
    end_date DATE := '2026-08-01';  -- Current + next month
    current_month DATE;
BEGIN
    current_month := start_date;
    WHILE current_month < end_date LOOP
        EXECUTE format(
            'CREATE TABLE IF NOT EXISTS audit_logs_%s PARTITION OF audit_logs
             FOR VALUES FROM (%L) TO (%L)',
            to_char(current_month, 'YYYY_MM'),
            current_month,
            current_month + interval '1 month'
        );
        current_month := current_month + interval '1 month';
    END LOOP;
END $$;
-- +goose StatementEnd
```

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

### Register modules with dependencies

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

At startup, both entry points call modules.Register with a Deps struct containing the router and database pool. This is the central dispatcher that passes dependencies to each feature module.

```go
modules.Register(modules.Deps{
    Router: &routerInst,
    Pool:   connections.RDMS.Pool(),
})
```

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

### Package tree structure for server/myfeature

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

Shows the directory layout for a new feature module, including the entry point and internal packages for appdb, handlers, routes, and services.

```text
server/myfeature/
├── myfeature.go         # Register entry point
└── internal/            # Internal implementation packages
    ├── appdb/
    │   ├── appdb.go         # Store struct + methods
    │   └── appdb_test.go    # Unit tests (pgxmock)
    ├── handlers/
    │   ├── handlers.go      # Handlers struct + MyFeature interface
    │   ├── handlers_test.go # Unit tests (httptest)
    │   └── views.go         # JSON view types
    ├── routes/
    │   ├── routes.go        # Register(router, handlers)
    │   └── routes_test.go   # Route registration tests
    └── services/
        ├── services.go      # Service struct + domain types + Database interface
        └── services_test.go # Unit tests (mock)
```

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

### Register audit middleware in entrypoint

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

Shows how to construct and register the audit middleware in the startup entrypoint. It requires the BHCE services, router instance, identity resolver, and an exclusion list (e.g., '/health'). The middleware is added via UsePostrouting after module registration.

```go
// Register BHCE modules and obtain cross-cutting services
bhceDeps := modules.Deps{
	Router: &routerInst,
	Pool:   connections.RDMS.Pool(),
}
bhceServices, err := modules.Register(bhceDeps)
if err != nil {
	return fmt.Errorf("failed to register BHCE modules: %w", err)
}

// Construct and register audit middleware with the service
auditMiddleware := middleware.NewAuditMiddleware(
	bhceServices.Audit,
	routerInst.MuxRouter(),
	identityResolver,
	[]string{"/health"}, // exclusion list
)
routerInst.UsePostrouting(auditMiddleware)
```

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

### Bash script to set GOBIN and run a Go dev tool

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

Use this script to temporarily set GOBIN to the project's bin directory and run a Go dev tool, ensuring everyone uses the same version without vendoring. The script sets GOBIN and then executes the tool from that path.

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

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

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

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

### Persistence Layer Unit Testing in appdb_test.go

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

Demonstrates how to test the Store implementation using pgxmock to simulate database queries and verify expected behavior.

```go
// Copyright 2026 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

package appdb_test

import (
    "context"
    "testing"

    "github.com/pashagolub/pgxmock/v3"
    "github.com/specterops/bloodhound/server/<feature>/internal/appdb"
    "github.com/stretchr/testify/require"
)

func TestStore_GetMyRecord(t *testing.T) {
    mock, err := pgxmock.NewPool()
    require.NoError(t, err)
    defer mock.Close()

    store := appdb.NewStore(mock)

    t.Run("returns record when found", func(t *testing.T) {
        rows := pgxmock.NewRows([]string{"id", "name"}).
            AddRow("abc123", "test-name")

        mock.ExpectQuery(`SELECT id, name FROM my_table WHERE id = \$1`).
            WithArgs("abc123").
            WillReturnRows(rows)

        record, err := store.GetMyRecord(context.Background(), "abc123")
        require.NoError(t, err)
        require.Equal(t, "abc123", record.ID)
        require.Equal(t, "test-name", record.Name)
        require.NoError(t, mock.ExpectationsWereMet())
    })
}
```

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

### Skaffold commands for local development

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

Commands to build, run in continuous development mode, deploy one-off, and tear down the local profile using Skaffold.

```bash
$ skaffold build
```

```bash
$ skaffold dev -p local
```

```bash
$ skaffold run -p local
```

```bash
$ skaffold delete -p local
```

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

### Run unit tests with just test

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

Runs both Go and UI unit tests. Results are cached until related files change; use -a to run all tests regardless of changes and -v for verbose output.

```bash
just test
```

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

### Build Debian package with debuild

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

Changes to the source directory and runs debuild to build the Debian package. The resulting .deb files are copied out from /src/.

```bash
cd /src/BloodHound && debuild -uc -b
```

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

### Wireup Pattern in server/<feature>/<feature>.go

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

This pattern defines a Register function that initializes the feature's store, service, and handler chain, then attaches routes to the provided router.

```go
// Copyright 2026 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

// Package <feature> is the wireup module for the <feature> feature. It is the
// single place where the <feature> store, service, handlers and routes are
// composed; the layered subpackages themselves remain unaware of each other.
package <feature>

import (
    "github.com/jackc/pgx/v5/pgxpool"
    "github.com/specterops/bloodhound/cmd/api/src/api/router"
    "github.com/specterops/bloodhound/server/<feature>/internal/appdb"
    "github.com/specterops/bloodhound/server/<feature>/internal/handlers"
    "github.com/specterops/bloodhound/server/<feature>/internal/routes"
    "github.com/specterops/bloodhound/server/<feature>/internal/services"
)

// Register builds the <feature> store -> service -> handler chain and attaches
// the <feature> routes to the provided router. It is called from the modules
// registry and receives only the infrastructure it directly needs.
func Register(routerInst *router.Router, pool *pgxpool.Pool) {
    var (
        store      = appdb.NewStore(pool)
        svc        = services.NewService(store)
        handlerSet = handlers.NewHandlersContainer(svc)
    )

    routes.Register(routerInst, handlerSet)
}
```

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

### Application configuration parameters

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

Fill out these parameters when creating the Application in authentik. The Launch URL points to BloodHound's login page.

```text
Name: bhce
Slug: bhce
Provider: authentik 
Launch URL: http://bloodhound.localhost/ui/login
Check mark toggle to: Open in new tab
```

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

### E2E Test Swap Pattern - After (new module registration)

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

Shows the new route registration using modules.Register with a Deps struct containing the router and database pool. This replaces the old v2.NewResources call in tests.

```go
// Register all modules including the new feature
modules.Register(modules.Deps{
    Router: &routerInst,
    Pool:   db.Pool(),
})
```

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

### Feature layer wireup with dependency injection

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

Registers the feature by constructing the store, service, and handler container, then passing them to the routes. Only depends on the router and pgx pool.

```go
package myfeature

import (
    "github.com/jackc/pgx/v5/pgxpool"
    "github.com/specterops/bloodhound/cmd/api/src/api/router"
    "github.com/specterops/bloodhound/server/myfeature/internal/appdb"
    "github.com/specterops/bloodhound/server/myfeature/internal/handlers"
    "github.com/specterops/bloodhound/server/myfeature/internal/routes"
    "github.com/specterops/bloodhound/server/myfeature/internal/services"
)

func Register(routerInst *router.Router, pool *pgxpool.Pool) {
    var (
        store      = appdb.NewStore(pool)
        svc        = services.NewService(store)
        handlerSet = handlers.NewHandlersContainer(svc)
    )

    routes.Register(routerInst, handlerSet)
}
```

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

### Server directory structure

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

Shows the layout of the server directory, with a modules folder for shared dependencies, a docs folder for architecture diagrams, and feature-specific directories containing internal packages for persistence, HTTP handlers, routes, and services.

```text
server/
├── modules/        # Shared Deps container and module registry
├── docs/
│   └── architecture/   # LikeC4 (C4 model) source for the diagrams above
└── <feature>/      # One directory per vertical feature slice
    ├── <feature>.go        # Register entry point
    └── internal/           # Internal implementation packages
        ├── appdb/          # Persistence layer (SQL via go-sqlbuilder + pgx)
        ├── handlers/       # HTTP layer (handlers, JSON views)
        ├── routes/         # Route registration
        └── services/       # Business-logic layer (domain types, interfaces)
```

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

### Run Go Tests

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

Run all tests, specific tests, or tests with coverage. Use -run to filter by test name and -cover to generate coverage reports.

```bash
# Run all tests
go test ./... -v

# Run specific tests
go test -v -run TestToken

# Test with coverage
go test -cover ./...
```

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

### Open Cypress UI test GUI with npx cypress open

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

Opens the interactive Cypress testing GUI for viewing and running tests manually.

```bash
npx cypress open
```
Tokens:
Raw