uploader

Documentation

Overview

Package uploader implements the BloodHound CE file upload client for MSSQLHound. It supports two-phase uploads (start job → upload file), HMAC-SHA256 and JWT Bearer authentication, retry with exponential backoff, and progress reporting.

Index

• type Authenticator
• type BearerAuth
  • func (b *BearerAuth) Authenticate(req *http.Request, _ []byte) error
• type Client
  • func NewClient(baseURL string, auth Authenticator) *Client
  • func (c *Client) EndUpload(ctx context.Context, jobID string) error
  • func (c *Client) StartUpload(ctx context.Context) (string, error)
  • func (c *Client) UploadFile(ctx context.Context, jobID, filePath string) error
  • func (c *Client) UploadSchema(ctx context.Context, data []byte) error
• type HMACAuth
  • func (h *HMACAuth) Authenticate(req *http.Request, body []byte) error
• type UploadSummary
• type Uploader
  • func NewUploader(url, tokenID, tokenKey string, logger *slog.Logger) *Uploader
  • func (u *Uploader) UploadFiles(ctx context.Context, files []string) UploadSummary

Types

type Authenticator

type Authenticator interface {
	Authenticate(req *http.Request, body []byte) error
}

Authenticator signs an outgoing HTTP request for the BloodHound CE API. The body parameter contains the raw request body bytes (needed for HMAC body hashing). Implementations must not modify the request body.

type BearerAuth

type BearerAuth struct {
	// Token is the JWT Bearer token.
	Token string
}

BearerAuth implements Authenticator using a JWT Bearer token. This is the simpler of the two BloodHound CE authentication methods.

func (*BearerAuth) Authenticate

func (b *BearerAuth) Authenticate(req *http.Request, _ []byte) error

Authenticate sets the Authorization header with a Bearer token.

type Client

type Client struct {
	// BaseURL is the BloodHound CE instance URL (e.g. "https://bloodhound.corp.local").
	// Must not have a trailing slash.
	BaseURL string

	// Auth signs outgoing requests.
	Auth Authenticator

	// HTTPClient is the underlying HTTP client. If nil, a default client with
	// a 60-second timeout is used.
	HTTPClient *http.Client

	// MaxRetries is the number of retry attempts on transient errors (429, 5xx).
	// Defaults to 3.
	MaxRetries int

	// RetryDelay is the initial delay between retries. Doubled on each attempt.
	// Defaults to 2 seconds.
	RetryDelay time.Duration
}

Client communicates with the BloodHound CE file upload API.

func NewClient

func NewClient(baseURL string, auth Authenticator) *Client

NewClient creates a Client for the given BloodHound CE instance. It uses the system (cgo) DNS resolver to avoid inheriting any overridden net.DefaultResolver (e.g. when --dc redirects DNS to a domain controller).

func (*Client) EndUpload

func (c *Client) EndUpload(ctx context.Context, jobID string) error

EndUpload signals that all files for the given job have been uploaded. POST /api/v2/file-upload/{job_id}/end

func (*Client) StartUpload

func (c *Client) StartUpload(ctx context.Context) (string, error)

StartUpload initiates a new file upload job on the BloodHound CE instance. Returns the job ID as a string or an error.

func (*Client) UploadFile

func (c *Client) UploadFile(ctx context.Context, jobID, filePath string) error

UploadFile uploads a single file to an existing upload job. The file is sent as raw content (application/json or application/zip) to POST /api/v2/file-upload/{job_id}.

func (*Client) UploadSchema

func (c *Client) UploadSchema(ctx context.Context, data []byte) error

UploadSchema uploads custom schema/type definitions to BloodHound CE. PUT /api/v2/extensions

type HMACAuth

type HMACAuth struct {
	// TokenID is the public identifier of the API key pair (apiKeyId).
	TokenID string
	// TokenKey is the secret portion of the API key pair (decrypted apiKey).
	TokenKey string
	// NowFunc returns the current time. If nil, time.Now is used.
	// Exposed for deterministic testing.
	NowFunc func() time.Time
}

HMACAuth implements Authenticator using BloodHound's chained HMAC-SHA256 request signing scheme. Each request is signed with a token ID and secret key using a three-step HMAC chain:

1. OperationKey = HMAC-SHA256(tokenKey, method + uri)
2. DateKey = HMAC-SHA256(OperationKey, datetimeToHour)
3. Signature = HMAC-SHA256(DateKey, requestBody)

The final signature is base64-encoded and sent in the Signature header.

func (*HMACAuth) Authenticate

func (h *HMACAuth) Authenticate(req *http.Request, body []byte) error

Authenticate signs req using the BloodHound CE chained HMAC-SHA256 scheme. It sets the Authorization, RequestDate, and Signature headers.

type UploadSummary

type UploadSummary struct {
	// FilesUploaded is the total number of files successfully uploaded.
	FilesUploaded int
	// FilesFailed is the total number of files that failed to upload.
	FilesFailed int
	// Errors contains any errors encountered during upload.
	Errors []error
}

UploadSummary holds the aggregate result of uploading files.

type Uploader

type Uploader struct {
	// Client is the BloodHound CE API client.
	Client *Client

	// Logger is the structured logger for all output.
	Logger *slog.Logger
}

Uploader manages uploading collector output files to BloodHound CE.

func NewUploader

func NewUploader(url, tokenID, tokenKey string, logger *slog.Logger) *Uploader

NewUploader creates an Uploader for the given BloodHound CE instance. Returns nil if url is empty.

func (*Uploader) UploadFiles

func (u *Uploader) UploadFiles(ctx context.Context, files []string) UploadSummary

UploadFiles uploads the given files to BloodHound CE. It starts a single upload job, uploads all files, and signals job completion.