AzureHound

https://github.com/specterops/azurehound
Admin
AzureHound is the BloodHound data collector for Microsoft Azure that enables security teams to...
Tokens:53,461
Snippets:291
Trust Score:9.5
License:GPL-3.0
Update:4 weeks ago
Show doc for...
Tokens:
Raw
### Usage example: create client, fetch and start jobs

Source: https://github.com/specterops/azurehound/blob/main/_autodocs/api-reference/client-bloodhound.md

Shows how to create a BHE client, fetch available jobs, and start ready jobs that are due. Uses a timeout of 10 seconds, 3 retries, and a proxy; logs an error if fetching jobs fails.

```go
bhe, err := bloodhound.NewBHEClient(*bheInstance, tokenId, token, proxy, 10_000, 3, log)
if err != nil { exit(err) }
jobs, err := bhe.GetAvailableJobs(ctx)
if err != nil {
    log.Error(err, "unable to fetch available jobs for azurehound")
} else {
    for _, job := range jobs {
        if job.Status == models.JobStatusReady && job.ExecutionTime.Before(now) {
            bhe.StartJob(ctx, job.ID)
            defer bhe.EndJob(ctx, models.JobStatusComplete, "Collection completed successfully")
        }
    }
}
```

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

### Ingest usage example

Source: https://github.com/specterops/azurehound/blob/main/_autodocs/api-reference/client-bloodhound.md

Example usage from cmd/start.go: batches the collection stream and ingests it. Logs a warning if any errors occurred during ingestion.

```go
// Usage example (as in cmd/start.go): batch the collection stream and ingest
batches := pipeline.Batch(ctx.Done(), listAll(ctx, azClient), config.ColBatchSize.Value().(int), 10*time.Second)
hasErrors := bheClient.Ingest(ctx, batches)
if hasErrors {
    log.Warn("ingest completed with errors")
}
```

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

### WriteToConsole usage example

Source: https://github.com/specterops/azurehound/blob/main/_autodocs/api-reference/sinks.md

Usage example of `WriteToConsole` as the default path in `cmd/outputStream`.

```go
// Usage (default path in cmd/outputStream)
sinks.WriteToConsole(ctx, formatted)
```

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

### WriteToFile usage example

Source: https://github.com/specterops/azurehound/blob/main/_autodocs/api-reference/sinks.md

Usage example of `WriteToFile` as called by `cmd/outputStream` when `--output` is set, showing error handling with `exit`.

```go
// Usage (as called by cmd/outputStream when --output is set)
if err := sinks.WriteToFile(ctx, config.OutputFile.Value().(string), formatted); err != nil {
    exit(fmt.Errorf("failed to write stream to file: %w", err))
}
```

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

### Custom sink consumer example

Source: https://github.com/specterops/azurehound/blob/main/_autodocs/api-reference/sinks.md

Example of a hand-rolled file writer with error handling as an alternative to `WriteToFile`, using `os.OpenFile` and `pipeline.OrDone`.

```go
// Hand-rolled file writer with error handling (an alternative to WriteToFile)
stream := pipeline.FormatJson(ctx.Done(), azureStream)
if file, err := os.OpenFile("out.json", os.O_CREATE|os.O_WRONLY|os.O_TRUNC, 0666); err != nil {
    exit(err)
} else {
    defer file.Close()
    for line := range pipeline.OrDone(ctx.Done(), stream) {
        if _, err := file.WriteString(line + "\n"); err != nil {
            exit(fmt.Errorf("write failed: %w", err))
        }
    }
}
```

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

### main_windows.go (Windows) - banner, then start service or execute

Source: https://github.com/specterops/azurehound/blob/main/_autodocs/api-reference/main-and-cli.md

Entry point for Windows builds (//go:build windows). Prints the same banner, then if the first argument is exactly "svc", runs cmd.StartWindowsService(); otherwise runs cmd.Execute().

```go
func main() {
    fmt.Fprintf(os.Stderr, "%s %s\n%s\n\n", constants.DisplayName, constants.Version, constants.AuthorRef)
    if len(os.Args) > 1 && os.Args[1] == "svc" {
        cmd.StartWindowsService()
    } else {
        cmd.Execute()
    }
}
```

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

### Configure and start data collection service

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

Initialize the configuration via prompts and start the data collection service for BloodHound Enterprise.

```sh
❯ azurehound configure
(follow prompts)

❯ azurehound start
```

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

### Usage examples for GraphParams and RMParams

Source: https://github.com/specterops/azurehound/blob/main/_autodocs/api-reference/client-query.md

Usage examples for GraphParams and RMParams. The first selects user fields with a top limit; the second paginates tenants with a specific API version; the third shows how to trigger the eventual consistency header.

```go
// Graph: select a subset of user fields
params := query.GraphParams{
    Select: []string{"accountEnabled", "displayName", "mail", "userPrincipalName", "id"},
    Top:    999,
}

// RM: paginated tenant list
params := query.RMParams{ApiVersion: "2020-01-01", IncludeAllTenantCategories: true}

// Advanced: count + orderby forces eventual consistency header on GET
params := query.GraphParams{Count: true, OrderBy: "displayName"}
if params.NeedsEventualConsistencyHeaderFlag() {
    // restClient.Get adds: ConsistencyLevel: eventual
}
```

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

### Basic GET with OData params and decode

Source: https://github.com/specterops/azurehound/blob/main/_autodocs/api-reference/client-rest.md

Performs a GET request to /tenants with OData parameters (ApiVersion, IncludeAllTenantCategories) and decodes the response body into an azure.TenantList. On error, calls exit(err); otherwise prints each tenant ID.

```go
// Basic GET with OData params, then decode into a typed value
params := query.RMParams{ApiVersion: "2020-01-01", IncludeAllTenantCategories: true}
if res, err := rmClient.Get(ctx, "/tenants", params, nil); err != nil {
    exit(err)
} else {
    var list azure.TenantList
    if err := rest.Decode(res.Body, &list); err != nil {
        exit(err)
    }
    for _, t := range list.Value { fmt.Println(t.TenantId) }
}
```

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

### Cobra command definition for 'start'

Source: https://github.com/specterops/azurehound/blob/main/_autodocs/api-reference/main-and-cli.md

Defines the `startCmd` Cobra command with its `Use`, `Short`, `Run`, `PersistentPreRunE`, and `SilenceUsage` fields, plus the signatures of `startCmdImpl` and `start`.

```go
var startCmd = &cobra.Command{
    Use:               "start",
    Short:             "Start Azure data collection service for BloodHound Enterprise",
    Run:               startCmdImpl,
    PersistentPreRunE: persistentPreRunE,
    SilenceUsage:      true,
}
func startCmdImpl(cmd *cobra.Command, args []string)
func start(ctx context.Context)
```

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

### POST /api/v2/jobs/start

Source: https://github.com/specterops/azurehound/blob/main/_autodocs/api-reference/client-bloodhound.md

Starts a job with the given job ID.

```APIDOC
## POST /api/v2/jobs/start

### Description
Starts a job with the given job ID.

### Method
POST

### Endpoint
`/api/v2/jobs/start`

### Parameters
#### Request Body
- **id** (string) - Required - The job ID to start.

### Request Example
```json
{
  "id": "jobId"
}
```

### Response
#### Success Response (2xx)
- No body content specified.

### Notes
- Returns nil error on success.
```

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

### Example: custom sink consumer

Source: https://github.com/specterops/azurehound/blob/main/_autodocs/api-reference/sinks.md

An example of a hand-rolled file writer with error handling, as an alternative to `WriteToFile`. It opens a file, iterates over the stream, and writes each line with error checking.

```APIDOC
## Example: custom sink consumer

### Description
An example of a hand-rolled file writer with error handling, as an alternative to `WriteToFile`. It opens a file, iterates over the stream, and writes each line with error checking.

### Code Example
```go
// Hand-rolled file writer with error handling (an alternative to WriteToFile)
stream := pipeline.FormatJson(ctx.Done(), azureStream)
if file, err := os.OpenFile("out.json", os.O_CREATE|os.O_WRONLY|os.O_TRUNC, 0666); err != nil {
    exit(err)
} else {
    defer file.Close()
    for line := range pipeline.OrDone(ctx.Done(), stream) {
        if _, err := file.WriteString(line + "\n"); err != nil {
            exit(fmt.Errorf("write failed: %w", err))
        }
    }
}
```
```

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

### cmd/root.go - root cobra command and exported functions

Source: https://github.com/specterops/azurehound/blob/main/_autodocs/api-reference/main-and-cli.md

Defines the root cobra command with Use "azurehound", Long description, and Version. init() registers config.GlobalConfig flags. Execute() runs the root command tree; StartService() executes just the start command. Callers must run every submodule's init() before Execute().

```go
var (
    rootCmd = &cobra.Command{
        Use:     constants.Name,          // "azurehound"
        Long:    constants.Description,   // "The official tool for collecting Azure data for BloodHound and BloodHound Enterprise"
        Version: constants.Version,
    }
    log logr.Logger
)

func init() {
    config.Init(rootCmd, config.GlobalConfig)
}

func Execute() error {
    return rootCmd.Execute()
}

func StartService() error {
    return startCmd.Execute()
}
```

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

### roles.go: built-in role ID constants (examples)

Source: https://github.com/specterops/azurehound/blob/main/_autodocs/api-reference/constants-environments.md

Shows two example constants from roles.go: ApplicationAdministratorRoleID and ContributorRoleID. These are part of 448 constants defining Azure AD and Azure ARM built-in role IDs used by attack-path/edge logic.

```go
// Can create and manage all aspects of app registrations and enterprise apps.
ApplicationAdministratorRoleID string = "9b895d92-2cd3-44c7-9d02-a6ac2d5ea5c3"

// Lets you manage all resources, but does not allow you to assign roles in Azure RBAC ...
ContributorRoleID string = "b24988ac-6180-42a0-ab88-20f7382dd24c"
```

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

### UpdateClient and EndOrphanedJob error handling

Source: https://github.com/specterops/azurehound/blob/main/_autodocs/api-reference/client-bloodhound.md

Example error handling for UpdateClient and EndOrphanedJob. Exits with a formatted error if either call fails.

```go
// Error-handling example
updated, err := bheClient.UpdateClient(ctx)
if err != nil {
    exit(fmt.Errorf("failed to update client: %w", err))
}
if err := bheClient.EndOrphanedJob(ctx, updated); err != nil {
    exit(fmt.Errorf("failed to end orphaned job: %w", err))
}
```

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

### Parallel fan-out with Demux

Source: https://github.com/specterops/azurehound/blob/main/_autodocs/api-reference/pipeline.md

Distributes subscription IDs across multiple streams using `pipeline.Demux` to parallelize work. The example mirrors `cmd/list-virtual-machines.go` and uses `pipeline.OrDone` and `pipeline.Send` to feed the input channel.

```go
// Parallel fan-out over subscriptions (as in cmd/list-virtual-machines.go)
ids := make(chan string)
streams := pipeline.Demux(ctx.Done(), ids, 4 /* config.ColStreamCount */)

go func() {
    defer close(ids)
    for result := range pipeline.OrDone(ctx.Done(), subscriptions) {
        pipeline.Send(ctx.Done(), ids, result.(AzureWrapper).Data.(models.Subscription).SubscriptionId)
    }
}()

for _, stream := range streams {
    go func() {
        for id := range stream {
            for item := range client.ListAzureVirtualMachines(ctx, id, query.RMParams{}) {
                ...
            }
        }
    }()
}
```

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

### Params interface

Source: https://github.com/specterops/azurehound/blob/main/_autodocs/api-reference/client-query.md

Interface that all parameter structs implement. AsMap() returns query parameters; NeedsEventualConsistencyHeaderFlag() triggers the ConsistencyLevel: eventual header on GET.

```go
type Params interface {
    AsMap() map[string]string
    NeedsEventualConsistencyHeaderFlag() bool
}
```

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

### Consuming AzureResult from ListAzureADUsers

Source: https://github.com/specterops/azurehound/blob/main/_autodocs/api-reference/client.md

Example of iterating over a channel-based enumerator, checking for errors, and logging found users. Uses log.Error and log.V(2).Info.

```go
for item := range client.ListAzureADUsers(ctx, query.GraphParams{}) {
    if item.Error != nil {
        log.Error(item.Error, "unable to continue processing users")
        return
    }
    log.V(2).Info("found user", "id", item.Ok.Id)
}
```

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

### WriteToFile output JSON structure

Source: https://github.com/specterops/azurehound/blob/main/_autodocs/api-reference/sinks.md

Example of the JSON structure written by `WriteToFile`, showing the `data` array and `meta` object with type, version, and count.

```json
{
    "data": [ ... ],
    "meta": {"type": "azure", "version": 5, "count": N}
}
```

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

### StorageAccount wrapper struct

Source: https://github.com/specterops/azurehound/blob/main/_autodocs/api-reference/models.md

Example of an RM resource wrapper struct that embeds an azure type and adds subscription, resource group, and tenant provenance fields. Follows the same MarshalJSON pattern as other wrappers, uppercasing identifier fields for BloodHound's normalized-node convention.

```go
type StorageAccount struct {
    StorageAccount    azure.StorageAccount `json:"storageAccount,omitempty"`
    SubscriptionId    string               `json:"subscriptionId"`
    ResourceGroupId   string               `json:"resourceGroupId"`
    ResourceGroupName string               `json:"resourceGroupName"`
    TenantId          string               `json:"tenantId"`
}
```

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

### GET /api/v2/jobs/available

Source: https://github.com/specterops/azurehound/blob/main/_autodocs/api-reference/client-bloodhound.md

Retrieves available jobs from the BloodHound Enterprise server.

```APIDOC
## GET /api/v2/jobs/available

### Description
Retrieves available jobs from the BloodHound Enterprise server.

### Method
GET

### Endpoint
`/api/v2/jobs/available`

### Response
#### Success Response (200)
- **Data** (array of `models.ClientJob`) - The list of available jobs.

### Notes
- Decodes `bloodhoundResponse[[]models.ClientJob]` and returns `response.Data`.
```

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

### JobStatus, CompleteJobRequest, ClientJob, ClientTask types

Source: https://github.com/specterops/azurehound/blob/main/_autodocs/api-reference/models.md

Defines job status constants and related request/response types. CompleteJobRequest.Status must be JobStatus.String() output; StatusEnum is JSON-skipped. ClientJob is returned by BHE GET /api/v2/jobs/available; ClientTask models the legacy task record with all fields optional.

```go
type JobStatus int

const (
    JobStatusInvalid   JobStatus = -1
    JobStatusReady     JobStatus = 0
    JobStatusRunning   JobStatus = 1
    JobStatusComplete  JobStatus = 2
    JobStatusCanceled  JobStatus = 3
    JobStatusTimedOut  JobStatus = 4
    JobStatusFailed    JobStatus = 5
    JobStatusIngesting JobStatus = 6
)

func (s JobStatus) String() string
// READY | RUNNING | COMPLETE | CANCELED | TIMEDOUT | FAILED | INGESTING | INVALIDSTATUS

type CompleteJobRequest struct {
    Status     string    `json:"status"`
    StatusEnum JobStatus `json:"-"`
    Message    string    `json:"message"`
}

type ClientJob struct {
    ID               int       `json:"id"`
    ClientID         string    `json:"client_id"`
    ClientName       string    `json:"client_name"`
    ClientScheduleID int       `json:"event_id"`
    ExecutionTime    time.Time `json:"execution_time"`
    StartTime        time.Time `json:"start_time"`
    EndTime          time.Time `json:"end_time"`
    Status           JobStatus `json:"status"`
    StatusMessage    string    `json:"status_message"`
}

type ClientTask struct {
    ADStructureCollection bool      `json:"ad_structure_collection"`
    ClientId              string    `json:"client_id"`
    CreatedAt             time.Time `json:"created_at"`
    DomainController      string    `json:"domain_controller"`
    EndTime               time.Time `json:"end_time"`
    EventId               int       `json:"event_id"`
    EventTitle            string    `json:"event_title"`
    ExectionTime          time.Time `json:"exection_time"`
    Id                    int       `json:"id"`
    LocalGroupCollection  bool      `json:"local_group_collection"`
    LogPath               string    `json:"log_path"`
    SessionCollection     bool      `json:"session_collection"`
    StartTime             time.Time `json:"start_time"`
    Status                int       `json:"status"`
    UpdatedAt             time.Time `json:"updated_at"`
}
```

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

### pipeline.Batch

Source: https://github.com/specterops/azurehound/blob/main/_autodocs/api-reference/pipeline.md

Groups consecutive values from a channel into batches of up to maxItems, or flushes after a period of inactivity. This is used before ingesting data in AzureHound's start command.

```APIDOC
## Batch[D, T any](done <-chan D, in <-chan T, maxItems int, maxTimeout time.Duration) <-chan []T

### Description
Accumulates values from `in` into slices of at most `maxItems` items. When `maxItems` is reached, the batch is emitted. If no new values arrive within `maxTimeout`, the current partial batch is flushed. When `in` closes, any remaining partial batch is flushed. The output channel closes when `in` closes or `done` fires.

### Signature
```go
func Batch[D, T any](done <-chan D, in <-chan T, maxItems int, maxTimeout time.Duration) <-chan []T
```

### Parameters
- `done` (`<-chan D`) - Cancellation channel.
- `in` (`<-chan T`) - Input channel.
- `maxItems` (`int`) - Maximum number of items per batch.
- `maxTimeout` (`time.Duration`) - Maximum idle time before a partial batch is flushed.

### Returns
- `<-chan []T` - Output channel of batches.

```

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

### Error-tolerant work queue with Result and SendAny

Source: https://github.com/specterops/azurehound/blob/main/_autodocs/api-reference/pipeline.md

Drains results from a source, sending errors to a separate channel via `pipeline.SendAny` and successful values wrapped in `pipeline.Result` via `pipeline.Send`. The example uses `client.ListAzureADTenants` and closes both output channels when done.

```go
// Error-tolerant work queue: drain results, per-item error channel
var (
    results = make(chan pipeline.Result[azure.Tenant])
    errs    = make(chan error)
)
go func() {
    defer close(results); defer close(errs)
    for item := range client.ListAzureADTenants(ctx, true) {
        if item.Error != nil {
            pipeline.SendAny(ctx.Done(), errs, item.Error) // SendAny accepts any
        } else {
            pipeline.Send(ctx.Done(), results, pipeline.Result[azure.Tenant]{Ok: item.Ok})
        }
    }
}()
```

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

### Bootstrap a command with configuration initialization and validation

Source: https://github.com/specterops/azurehound/blob/main/_autodocs/api-reference/config.md

Shows how to initialize configuration, load values, apply Azure defaults, and validate logging configuration, as done in persistentPreRunE. Returns an error if logging configuration is invalid.

```go
// Bootstrap a command: register flags, load values, apply defaults (as persistentPreRunE does)
config.Init(cmd, config.GlobalConfig)
config.LoadValues(cmd, config.Options())
config.SetAzureDefaults()
if err := config.ValidateLoggingConfig(); err != nil {
    return fmt.Errorf("invalid logging configuration: %w", err)
}
```

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

### GET /api/v2/jobs/current

Source: https://github.com/specterops/azurehound/blob/main/_autodocs/api-reference/client-bloodhound.md

Checks in with the BloodHound Enterprise server to get the current job.

```APIDOC
## GET /api/v2/jobs/current

### Description
Checks in with the BloodHound Enterprise server to get the current job.

### Method
GET

### Endpoint
`/api/v2/jobs/current`

### Response
#### Success Response (2xx)
- No body content specified; body is drained.

### Notes
- Returns nil error on 2xx.
```

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

### Wire config values into the client (client.NewClient)

Source: https://github.com/specterops/azurehound/blob/main/_autodocs/api-reference/client-config.md

Shows how to construct a config.Config with explicit URLs and a region, then create a client with client.NewClient. Equivalent to cmd/utils.newAzureClient. Exits on error.

```go
// Wire config values into the client (equivalent of cmd/utils.newAzureClient)
cfg := config.Config{
    ApplicationId:           "my-app-guid",
    Authority:               "https://login.microsoftonline.com",
    ClientSecret:            "s3cr3t",
    Graph:                   "https://graph.microsoft.com",
    Management:              "https://management.azure.com",
    Region:                  constants.Cloud,
    SubscriptionId:          []string{},
    Tenant:                  "example.onmicrosoft.com",
}
azClient, err := client.NewClient(cfg)
if err != nil { exit(err) }
```

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

### main.go (non-Windows) - print banner and execute root command

Source: https://github.com/specterops/azurehound/blob/main/_autodocs/api-reference/main-and-cli.md

Entry point for non-Windows builds (//go:build !windows). Prints the AzureHound banner (name, version, author) to stderr, then runs cmd.Execute().

```go
func main() {
    fmt.Fprintf(os.Stderr, "%s %s\n%s\n\n", constants.DisplayName, constants.Version, constants.AuthorRef)
    cmd.Execute()
}
```

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

### Manual configuration with viper

Source: https://github.com/specterops/azurehound/blob/main/_autodocs/api-reference/main-and-cli.md

Non-interactive equivalent of the configure() function, showing how to manually set the same configuration values and write the config file.

```go
// equivalent manual configuration written by configure()
viper.Set("region", "cloud"); viper.Set("tenant", "<tenant-guid>"); viper.Set("app", "<app-guid>")
viper.Set("secret", "<client-secret>"); viper.Set("instance", "https://bloodhound.example.com")
viper.Set("tokenId", "<token-id-guid>"); viper.Set("token", "<bhe-token>")
viper.WriteConfigAs("/home/user/.config/azurehound/config.json")
```

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

### Programmatic read/write of a configuration option

Source: https://github.com/specterops/azurehound/blob/main/_autodocs/api-reference/config.md

Demonstrates reading the Proxy option and setting it if empty, then printing the config file used.

```go
// Programmatic read/write of an option
proxy := config.Proxy.Value().(string)
if proxy == "" {
    config.Proxy.Set("http://corporate-proxy:8080")
}
fmt.Println(config.ConfigFileUsed())
```

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

### View AzureHound CLI help

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

Display the help menu for the AzureHound CLI, including available commands and flags.

```sh
❯ azurehound --help
AzureHound vx.x.x
Created by the BloodHound Enterprise team at SpecterOps - [https://bloodhoundenterprise.io](https://specterops.io/bloodhound-overview/)

The official tool for collecting Azure data for BloodHound Community Edition and BloodHound Enterprise

Usage:
  azurehound [command]

Available Commands:
  completion  Generate the autocompletion script for the specified shell
  configure   Configure AzureHound
  help        Help about any command
  list        Lists Azure Objects
  start       Start Azure data collection service for BloodHound Enterprise

Flags:
  -c, --config string          AzureHound configuration file (default: /Users/dlees/.config/azurehound/config.json)
  -h, --help                   help for azurehound
      --json                   Output logs as json
  -j, --jwt string             Use an acquired JWT to authenticate into Azure
      --log-compress           Compress rotated logs with gzip (default: true)
      --log-file string        Output logs to this file
      --log-max-age int        Maximum age in days for rotated logs (default: 14; 0 disables age pruning)
      --log-max-backups int    Maximum number of rotated logs to retain (default: 20; 0 disables count pruning)
      --log-max-size int       Maximum active log size in MiB before rotation (default: 100)
      --proxy string           Sets the proxy URL for the AzureHound service
  -r, --refresh-token string   Use an acquired refresh token to authenticate into Azure
  -v, --verbosity int          AzureHound verbosity level (defaults to 0) [Min: -1, Max: 2]
      --version                version for azurehound

Use "azurehound [command] --help" for more information about a command.
```

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

### Error handling for Microsoft Graph GET request

Source: https://github.com/specterops/azurehound/blob/main/_autodocs/api-reference/client-rest.md

Shows error handling for a GET request to /v1.0/users. Retry semantics are internal; 4xx bodies surface as errors. The error text contains the decoded Azure error object (e.g., code/message fields). Logs the error and closes the response body on success.

```go
// Error handling: retry semantics are internal; 4xx bodies surface as errors
if res, err := msgraph.Get(ctx, "/v1.0/users", graphParams, nil); err != nil {
    // err text contains the decoded Azure error object (e.g. code/message fields)
    log.Error(err, "graph request failed")
} else {
    res.Body.Close()
}
```

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

### Helpers exported from config/utils.go

Source: https://github.com/specterops/azurehound/blob/main/_autodocs/api-reference/config.md

Shows re-exported Init and LoadValues functions, plus helper functions for setting Azure defaults, checking collection config sanity, validating logging and URLs, and retrieving options.

```go
var Init = config.Init                // re-export
var LoadValues = config.LoadValues    // re-export

func SetAzureDefaults()
func CheckCollectionConfigSanity(log logr.Logger)
func ValidateLoggingConfig() error
func ValidateURL(input string) error
func Options() config.Options
func ConfigFileUsed() string          // re-export from internal
```

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

### Go list command implementation pattern

Source: https://github.com/specterops/azurehound/blob/main/_autodocs/api-reference/cli-commands.md

Shows the standard structure for AzureHound list commands, including signal handling, client creation, and output streaming. This pattern is used in files like cmd/list-tenants.go.

```go
func listTenantsCmdImpl(cmd *cobra.Command, args []string) {
    ctx, stop := signal.NotifyContext(cmd.Context(), os.Interrupt, os.Kill)
    defer gracefulShutdown(stop)
    if len(args) > 0 { exit(fmt.Errorf("unsupported subcommand: %v", args)) } // az-ad/az-rm/list only
    azClient := connectAndCreateClient()
    stream := listTenants(ctx, azClient)
    panicrecovery.HandleBubbledPanic(ctx, stop, log)
    outputStream(ctx, stream)
}
```

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

### Print Azure Tenant data to file

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

List all Azure Tenant data and save the output to a specified JSON file.

```sh
❯ azurehound list -u "$USERNAME" -p "$PASSWORD" -t "$TENANT" -o "mytenant.json"
```

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

### Print Azure Tenant data to stdout

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

List all Azure Tenant data and output directly to the standard output.

```sh
❯ azurehound list -u "$USERNAME" -p "$PASSWORD" -t "$TENANT"
```

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

### Compile AzureHound from source

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

Build the project from source using the Go compiler. Requires Go 1.25 or later.

```sh
go build -o azurehound -ldflags="-s -w -X github.com/SpecterOps/AzureHound/v2/constants.Version=`git describe tags --exact-match 2> /dev/null || git rev-parse HEAD`"
```

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

### Config and Options structs and function signatures

Source: https://github.com/specterops/azurehound/blob/main/_autodocs/api-reference/config.md

Defines the Config struct with fields for flag metadata and the Options struct for viper configuration. Includes method signatures for Config.Value, Config.Set, and the Init, LoadValues, and ConfigFileUsed functions.

```go
type Config struct {
    Name       string
    Shorthand  string
    Usage      string
    Required   bool
    Persistent bool
    Default    interface{}
    MinValue   int
    MaxValue   int
}

func (s Config) Value() interface{}
func (s Config) Set(value interface{})

type Options struct {
    ConfigFile  string
    ConfigName  string
    ConfigType  string
    ConfigPaths []string
    EnvPrefix   string
}

func Init(cmd *cobra.Command, configs []Config)
func LoadValues(cmd *cobra.Command, options Options)
func ConfigFileUsed() string
```

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

### Run azurehound list with credentials, output file, or JWT

Source: https://github.com/specterops/azurehound/blob/main/_autodocs/api-reference/cli-commands.md

Run the `list` command with no subcommand to enumerate both Azure AD and ARM resources concurrently. The first form prints everything to stdout; the second writes the same `{"data": [...], "meta": {...}}` document as `sinks.WriteToFile` to `mytenant.json`; the third reuses an existing Graph access token via `--jwt`.

```sh
# print everything to stdout
azurehound list -u "$USERNAME" -p "$PASSWORD" -t "$TENANT"

# write to a file (writes the same {"data": [...], "meta": {...}} document as sinks.WriteToFile)
azurehound list -u "$USERNAME" -p "$PASSWORD" -t "$TENANT" -o mytenant.json

# reuse an existing Graph access token
azurehound list --jwt "$JWT"
```

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

### Multiplex and format with Mux and FormatJson

Source: https://github.com/specterops/azurehound/blob/main/_autodocs/api-reference/pipeline.md

Combines two sources into one stream with `pipeline.Mux` and serializes each value to JSON with `pipeline.FormatJson`, then prints each line. This follows the `listAll/listCmdImpl` pattern.

```go
// Multiplex two sources and pretty-print (listAll/listCmdImpl pattern)
combined := pipeline.Mux(ctx.Done(), listAllAD(ctx, client), listAllRM(ctx, client))
formatted := pipeline.FormatJson(ctx.Done(), combined)
for line := range formatted {
    fmt.Println(line)
}
```

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

### Usage: User-Agent and environment resolution

Source: https://github.com/specterops/azurehound/blob/main/_autodocs/api-reference/constants-environments.md

Shows how to stamp the default User-Agent header and resolve an environment from a region string. The User-Agent is formatted as 'azurehound/v2.x.x'.

```go
// stamp the default User-Agent
req.Header.Set("User-Agent", constants.UserAgent()) // "azurehound/v2.x.x"

// region → environment resolution
region := "usgovl4"
env := constants.AzureUSGovernment()
graph := client.GraphUrl(region, env.MicrosoftGraphUrl)
```

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

### Region-only config leaves URLs to the helpers

Source: https://github.com/specterops/azurehound/blob/main/_autodocs/api-reference/client-config.md

Shows a Config with only Region and Tenant set, relying on the instance method GraphUrl() to derive the URL from the region. The comment shows the expected result for USGovL4: https://graph.microsoft.us.

```go
// Region-only config leaves URLs to the helpers
cfg := Config{Region: constants.USGovL4, Tenant: "gov-tenant-guid"}
url := cfg.GraphUrl() // https://graph.microsoft.us
```

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

### List Azure AD Users with AzureHound Client

Source: https://github.com/specterops/azurehound/blob/main/_autodocs/api-reference/client.md

Creates a new AzureHound client, lists Azure AD users with selected properties, and prints their IDs. Errors are logged and break the loop. Closes idle connections after processing.

```go
azClient, err := client.NewClient(cfg)
if err != nil { exit(err) }

ctx := context.Background()
stream := azClient.ListAzureADUsers(ctx, query.GraphParams{Select: []string{"id", "displayName", "userPrincipalName"}})
for item := range pipeline.OrDone(ctx.Done(), stream) {
    if item.Error != nil {
        log.Error(item.Error, "unable to continue processing users")
        break
    }
    fmt.Println(item.Ok.Id)
}
azClient.CloseIdleConnections()
```

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

### environments.go: Azure deployment region constants and Environment struct

Source: https://github.com/specterops/azurehound/blob/main/_autodocs/api-reference/constants-environments.md

Defines region constants and the Environment struct with ActiveDirectoryAuthority, MicrosoftGraphUrl, and ResourceManagerUrl fields. Functions like AzureCloud() return preconfigured environments for each region.

```go
// Azure deployment regions
const (
    China   string = "china"
    Cloud   string = "cloud"
    USGovL4 string = "usgovl4"
    USGovL5 string = "usgovl5"
)

type Environment struct {
    ActiveDirectoryAuthority string
    MicrosoftGraphUrl        string
    ResourceManagerUrl       string
}

func AzureCloud() Environment
func AzureUSGovernment() Environment
func AzureUSGovernmentL5() Environment
func AzureChina() Environment
```

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

### URL helper function signatures (AuthorityUrl, GraphUrl, ResourceManagerUrl)

Source: https://github.com/specterops/azurehound/blob/main/_autodocs/api-reference/client-config.md

Declares the static and instance methods for region-aware URL helpers. Static helpers switch on region against constants.China/Cloud/USGovL4/USGovL5 and return the built-in environment URL; default returns defaultUrl. Instance methods derive from s.Region and fall back to the configured explicit field. GraphUrl() and ResourceManagerUrl() trim a trailing slash.

```go
func AuthorityUrl(region string, defaultUrl string) string
func (s Config) AuthorityUrl() string

func GraphUrl(region string, defaultUrl string) string
func (s Config) GraphUrl() string

func ResourceManagerUrl(region string, defaultUrl string) string
func (s Config) ResourceManagerUrl() string
```

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

### NewClient function signature

Source: https://github.com/specterops/azurehound/blob/main/_autodocs/api-reference/client.md

Constructor for AzureClient. Takes a config.Config and returns an AzureClient or error. Builds Graph and RM REST clients, and handles JWT-based bootstrap via RM or Graph.

```go
func NewClient(config config.Config) (AzureClient, error)
```

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

### Resource group scope helpers (ResourceGroupName, ResourceGroupId)

Source: https://github.com/specterops/azurehound/blob/main/_autodocs/api-reference/models-azure.md

Shows the ResourceGroupName and ResourceGroupId scope helpers derived from the resource ID. The same pair is implemented identically on KeyVault, VirtualMachine, StorageAccount, StorageContainer, WebApp, FunctionApp, LogicApp, AutomationAccount, ContainerRegistry, ManagedCluster, and VMScaleSet.

```go
func (s KeyVault) ResourceGroupName() string    // Id.split("/")[4] or ""
func (s KeyVault) ResourceGroupId() string      // Id.split("/")[:5].join("/") or ""
```

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

### Public declarations in config/config.go

Source: https://github.com/specterops/azurehound/blob/main/_autodocs/api-reference/config.md

Shows the re-exported Config type, default config file path, environment prefix, logging defaults, and region/managed identity lists.

```go
type Config = config.Config                          // re-export of config/internal.Config

var DefaultConfigFile = filepath.Join(homeDir, ".config", "azurehound", "config.json")
  // Unix/Darwin: $HOME/.config/azurehound/config.json
  // Windows:     %USERPROFILE%\.config\azurehound\config.json

func SystemConfigDirs() []string
const EnvPrefix string = "AZUREHOUND"
const (
    DefaultLogMaxSize    = 100
    DefaultLogMaxAge     = 14
    DefaultLogMaxBackups = 20
)
var AzRegions = []string{constants.China, constants.Cloud, constants.USGovL4, constants.USGovL5}
var ManagedIdentityTypes = []string{"System-Assigned Identity", "User-Assigned Identity"}
```

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

### getAzureObjectList pagination helper signature

Source: https://github.com/specterops/azurehound/blob/main/_autodocs/api-reference/client.md

Module-private helper that defines the observable behavior of every enumerator. Loops pages using @odata.nextLink (Graph) or nextLink (RM), decodes each page into a local struct with fields @odata.count, @odata.nextLink, @odata.context, nextLink, value via rest.Decode, and pushes AzureResult[T]{Ok: u} per item or AzureResult[T]{Error: err} on failure. Each page runs under context.WithTimeout(ctx, pageRequestTimeout) where var pageRequestTimeout = 2 * time.Minute, wrapped in panicrecovery.PanicRecovery().

```go
func getAzureObjectList[T any](client rest.RestClient, ctx context.Context, path string, params query.Params, out chan AzureResult[T])
```

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

### Configure command function signatures

Source: https://github.com/specterops/azurehound/blob/main/_autodocs/api-reference/main-and-cli.md

Function signatures for the interactive configuration command. The command prompts for Azure region, tenant ID, app ID, auth method, and optional BHE connection, proxy, and logging settings, then writes config.json.

```go
var configureCmd = &cobra.Command{ Use: "configure", Short: "Configure AzureHound", Run: configureCmdImpl, SilenceUsage: true }
func configureCmdImpl(cmd *cobra.Command, args []string)
func configure() error
func prompt(label string, validator func(string) error, isSensitive bool, defaultValue string) (string, error)
func validateMinInt(minimum int) func(string) error
func choose(label string, items []string, pos int) (int, string, error)
func confirm(label string, defaultYes bool) bool
func validateGuid(input string) error
func validatePem(input string) error
func validateUserPrincipalName(input string) error
func generateCert(passphrase string) ([]byte, []byte, error)
```

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

### Factory and BHEClient struct for BHE client

Source: https://github.com/specterops/azurehound/blob/main/_autodocs/api-reference/client-bloodhound.md

Shows the package-level constants, error variable, factory function signature, and the concrete BHEClient struct. The factory builds an HTTP client with rest.NewHTTPClient(proxy) and wraps its transport in a signingTransport; retryDelay is fixed at 5 internally.

```go
const BHEAuthSignature string = "bhesignature"
var ErrExceededRetryLimit = errors.New("exceeded max retry limit for ingest batch, proceeding with next batch...")

func NewBHEClient(bheUrl url.URL, tokenId, token, proxy string, maxReqPerConn, maxRetries int, logger logr.Logger) (BloodHoundClient, error)

type BHEClient struct {
    httpClient          *http.Client
    bheUrl              url.URL
    log                 logr.Logger
    requestLimit        int
    currentRequestCount int
    maxRetries          int
    retryDelay          int
    proxy               string
    token               string
    tokenId             string
    mu                  sync.Mutex
}
```

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

### Usage: route role assignment by definition ID

Source: https://github.com/specterops/azurehound/blob/main/_autodocs/api-reference/constants-environments.md

Shows how to compare the basename of a role assignment's RoleDefinitionId against a constant role ID, e.g., KeyVaultOwnerRoleID.

```go
// route a role assignment by its definition ID
ok := path.Base(ra.RoleAssignment.Properties.RoleDefinitionId) == constants.KeyVaultOwnerRoleID
```

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

### pipeline.TeeFixed

Source: https://github.com/specterops/azurehound/blob/main/_autodocs/api-reference/pipeline.md

Creates a fixed number of new output channels and tees the input into them, preserving the channel handles for the caller. Unlike Tee, it returns the created channels.

```APIDOC
## TeeFixed[D, T any](done <-chan D, in <-chan T, size int) []<-chan T

### Description
Creates `size` new output channels and feeds a copy of each input value to all of them. Returns the slice of output channels so the caller can consume from them. Cancellation via `done` stops the copying.

### Signature
```go
func TeeFixed[D, T any](done <-chan D, in <-chan T, size int) []<-chan T
```

### Parameters
- `done` (`<-chan D`) - Cancellation channel.
- `in` (`<-chan T`) - Input channel.
- `size` (`int`) - Number of output channels to create.

### Returns
- `[]<-chan T` - Slice of `size` output channels.

```

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

### Tenant and TenantList structs

Source: https://github.com/specterops/azurehound/blob/main/_autodocs/api-reference/models-azure.md

Defines the Tenant struct with JSON tags for Azure AD tenant properties and the TenantList wrapper containing a nextLink and a slice of Tenant values. Used to represent tenant information returned by AzureHound.

```go
type Tenant struct {
    Country               string               `json:"country,omitempty"`
    CountryCode           string               `json:"countryCode,omitempty"`
    DefaultDomain         string               `json:"defaultDomain,omitempty"`
    DisplayName           string               `json:"displayName,omitempty"`
    Domains               []string             `json:"domains,omitempty"`
    Id                    string               `json:"id,omitempty"`
    TenantBrandingLogoUrl string               `json:"tenantBrandingLogoUrl,omitempty"`
    TenantCategory        enums.TenantCategory `json:"tenantCategory,omitempty"`
    TenantId              string               `json:"tenantId,omitempty"`
    TenantType            string               `json:"tenantType,omitempty"`
}

type TenantList struct {
    NextLink string   `json:"nextLink,omitempty"`
    Value    []Tenant `json:"value"`
}
```

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

### UpdateClientRequest and UpdateClientResponse structs

Source: https://github.com/specterops/azurehound/blob/main/_autodocs/api-reference/models.md

Defines the request and response types for updating a client. The response includes the current job as a ClientJob.

```go
type UpdateClientRequest struct {
    Address  string `json:"address"`
    Username string `json:"username"`
    Hostname string `json:"hostname"`
    Version  string `json:"version"`
    UserSid  string `json:"usersid"`
}

type UpdateClientResponse struct {
    ID           string    `json:"id"`
    Name         string    `json:"name"`
    IPAddress    string    `json:"ip_address"`
    Hostname     string    `json:"hostname"`
    CurrentJobID int       `json:"current_job_id"`
    CurrentJob   ClientJob `json:"current_job"`
}
```

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

### Send and internal send method signatures

Source: https://github.com/specterops/azurehound/blob/main/_autodocs/api-reference/client-rest.md

Shows the exported Send method and the internal send method that bypasses authentication. Send adds authentication then calls the internal send, which handles retries.

```go
func (s *restClient) Send(req *http.Request) (*http.Response, error)
func (s *restClient) send(req *http.Request) (*http.Response, error) // internal, bypasses auth
```

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

### IngestRequest and Meta structs

Source: https://github.com/specterops/azurehound/blob/main/_autodocs/api-reference/models.md

Defines the per-batch body sent by BHEClient.Ingest, gzip-compressed. Meta.Type is always "azure" and the file sink writes Meta{Type: "azure", Version: 5, Count: <n>}.

```go
type IngestRequest struct {
    Meta Meta        `json:"meta"`
    Data interface{} `json:"data"`
}

type Meta struct {
    Type    string `json:"type"`
    Version int    `json:"version"`
    Count   int    `json:"count"`
}
```

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

### WriteToConsole

Source: https://github.com/specterops/azurehound/blob/main/_autodocs/api-reference/sinks.md

Prints each value from a stream to the console using `fmt.Println`. Values are expected to be JSON strings produced by `pipeline.FormatJson`.

```APIDOC
## WriteToConsole

### Description
Prints each value from a stream to the console using `fmt.Println`. Values are expected to be JSON strings produced by `pipeline.FormatJson`.

### Function Signature
```go
func WriteToConsole[T any](ctx context.Context, stream <-chan T)
```

### Parameters
- **ctx** (context.Context) - Required - Cancellation source
- **stream** (`<-chan T`) - Required - Values to print

### Behavior
Prints each value with `fmt.Println` (values are the JSON strings produced by `pipeline.FormatJson`).

### Usage Example
```go
// Usage (default path in cmd/outputStream)
sinks.WriteToConsole(ctx, formatted)
```
```

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

### Switch on Azure resource kind

Source: https://github.com/specterops/azurehound/blob/main/_autodocs/api-reference/enums.md

Iterates over a stream of Azure wrapper items and switches on the Kind field to type-assert the underlying data into specific model types (User or Group).

```go
// switch on kind
for item := range stream {
    wrapper := item.(azureWrapper)
    switch wrapper.Kind {
    case enums.KindAZUser:
        user := wrapper.Data.(models.User)
    case enums.KindAZGroup:
        group := wrapper.Data.(models.Group)
    }
}
```

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

### Config struct definition

Source: https://github.com/specterops/azurehound/blob/main/_autodocs/api-reference/client-config.md

Defines the Config struct with fields for Azure authentication and API endpoints. Fields map to CLI flags and global configuration options.

```go
type Config struct {
    ApplicationId           string   // The Application Id that the  Azure app registration portal assigned when the app was registered.
    Authority               string   // The Azure ActiveDirectory Authority URL
    ClientSecret            string   // The Application Secret that was generated for the app in the app registration portal.
    ClientCert              string   // The certificate uploaded to the app registration portal."
    ClientKey               string   // The key for a certificate uploaded to the app registration portal."
    ClientKeyPass           string   // The passphrase to use in conjuction with the associated key of a certificate uploaded to the app registration portal."
    Graph                   string   // The Microsoft Graph URL
    JWT                     string   // The JSON web token that will be used to authenticate requests sent to Azure APIs
    Management              string   // The Azure ResourceManager URL
    MgmtGroupId             []string // The Management Group Id to use as a filter
    ManagedIdentity         bool     // If true then the client will use a managed identity to authenticate to Azure APIs
    ManagedIdentityClientId string   // Client ID of user-assigned managed idenity used to authenticate via managed identity SDK
    Password                string   // The password associated with the user principal name associated with the Azure portal.
    ProxyUrl                string   // The forward proxy url
    RefreshToken            string   // The refresh token that will be used to authenticate requests sent to Azure APIs
    Region                  string   // The region of the Azure Cloud deployment.
    SubscriptionId          []string // The Subscription Id(s) to use as a filter
    Tenant                  string   // The directory tenant that you want to request permission from. This can be in GUID or friendly name format
    Username                string   // The user principal name associated with the Azure portal.
}
```

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

### NewRestClient

Source: https://github.com/specterops/azurehound/blob/main/_autodocs/api-reference/client-rest.md

Factory function to create a new RestClient instance.

```APIDOC
## NewRestClient

### Description
Creates a new RestClient instance with the given API URL and configuration. It parses the authority and API URLs, creates an HTTP client, and selects an authenticator based on the configuration.

### Parameters
- **apiUrl** (string) - Required - Base URL for all requests; every `Get(Path...)` resolves relative to it.
- **config** (client/config.Config) - Required - Authentication and tenant settings.

### Returns
- **RestClient** - The configured REST client.
- **error** - An error if URL parsing, HTTP client creation, or managed identity credential creation fails.
```

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

### Print Azure Tenant data using Azure CLI authentication

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

Authenticate using an existing Azure CLI session by acquiring a JWT and passing it to the list command.

```sh
❯ JWT=$(az account get-access-token --resource https://graph.microsoft.com | jq -r .accessToken)
❯ azurehound list --jwt "$JWT"
```

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

### WriteToConsole function signature

Source: https://github.com/specterops/azurehound/blob/main/_autodocs/api-reference/sinks.md

Function signature for `WriteToConsole`, which prints each value from a stream to the console using `fmt.Println`.

```go
func WriteToConsole[T any](ctx context.Context, stream <-chan T)
```

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

### Organization ToTenant method

Source: https://github.com/specterops/azurehound/blob/main/_autodocs/api-reference/models-azure.md

Declares the ToTenant method on the Organization type, which converts an organization to a Tenant. The method builds a Tenant from the organization's verified domains and sets the Id to '/tenants/<orgId>'. This is used by Graph-bootstrap clients to obtain TenantInfo().

```go
func (s Organization) ToTenant() Tenant
```
Tokens:
Raw