utils

package
v1.2.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Oct 6, 2026 License: Apache-2.0 Imports: 20 Imported by: 0

Documentation

Overview

Package utils provides shared helpers for the MCP server: TheHive query building, entity-scope permission checks, filter normalization, and result date/untrusted-data processing.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func AddPermissionsToContext 

func AddPermissionsToContext(ctx context.Context, perms *permissions.Config) context.Context

AddPermissionsToContext adds permissions configuration to the context

func CreateFilterFromJSONString 

func CreateFilterFromJSONString(filterString string) (thehive.InputQueryNamedOperation, error)

CreateFilterFromJSONString parses a JSON object string into a TheHive named filter operation.

func DescribeHTTPResponse added in v1.1.0 

func DescribeHTTPResponse(resp *http.Response) string

DescribeHTTPResponse renders the part of an API response worth showing a caller: the status line, and whatever the body still holds.

It exists because `fmt.Errorf("API response: %v", resp)` formats the whole *http.Response struct — pointer addresses, the transport's headers, the server's identity and version. None of that helps the caller diagnose a bad field name, all of it is noise in the model's context, and the header block leaks deployment detail into an error a client may surface verbatim.

The body is usually empty here: thehive4go reads it while building its own error, and a body can only be read once. That is fine — the status line alone beats a struct dump, and thehive4go's error (carried separately as the cause) already holds what it managed to parse.

func ExpandEntitiesWithQueries 

func ExpandEntitiesWithQueries(
	ctx context.Context,
	entityType string,
	entities []map[string]any,
	additionalQueries []string,
	permFilters map[string]any,
) ([]map[string]any, error)

ExpandEntitiesWithQueries expands each entity with its related data inline. When permission filters are configured for the calling tool, every parent entity must be within the filtered scope before its children are fetched.

func FilterOperation added in v1.2.0 

func FilterOperation(filters map[string]any) map[string]any

FilterOperation builds a query's filter operation from filters without touching them: keys are repaired and dates translated on a deep copy, since filters may hold the permission config's own maps, which every request of a session shares.

func GetActionsFromAlertID added in v1.1.0 

func GetActionsFromAlertID(ctx context.Context, client *thehive.APIClient, alertID string) ([]map[string]any, error)

GetActionsFromAlertID returns the Cortex responder runs of the given alert.

func GetActionsFromCaseID added in v1.1.0 

func GetActionsFromCaseID(ctx context.Context, client *thehive.APIClient, caseID string) ([]map[string]any, error)

GetActionsFromCaseID returns the Cortex responder runs of the given case.

func GetActionsFromObservableID added in v1.1.0 

func GetActionsFromObservableID(ctx context.Context, client *thehive.APIClient, observableID string) ([]map[string]any, error)

GetActionsFromObservableID returns the Cortex responder runs of the given observable.

func GetActionsFromTaskID added in v1.1.0 

func GetActionsFromTaskID(ctx context.Context, client *thehive.APIClient, taskID string) ([]map[string]any, error)

GetActionsFromTaskID returns the Cortex responder runs of the given task.

func GetAttachmentsFromAlertID 

func GetAttachmentsFromAlertID(ctx context.Context, client *thehive.APIClient, alertID string) ([]map[string]any, error)

GetAttachmentsFromAlertID returns the attachments of the given alert.

func GetAttachmentsFromCaseID 

func GetAttachmentsFromCaseID(ctx context.Context, client *thehive.APIClient, caseID string) ([]map[string]any, error)

GetAttachmentsFromCaseID returns the attachments of the given case.

func GetCommentsFromAlertID 

func GetCommentsFromAlertID(ctx context.Context, client *thehive.APIClient, alertID string) ([]map[string]any, error)

GetCommentsFromAlertID returns the comments of the given alert.

func GetCommentsFromCaseID 

func GetCommentsFromCaseID(ctx context.Context, client *thehive.APIClient, caseID string) ([]map[string]any, error)

GetCommentsFromCaseID returns the comments of the given case.

func GetDefaultCortexIDFromContext added in v0.3.4 

func GetDefaultCortexIDFromContext(ctx context.Context) string

GetDefaultCortexIDFromContext retrieves the default Cortex ID from the context

func GetEntityIDsInScope added in v1.0.0 

func GetEntityIDsInScope(ctx context.Context, entityType string, entityIDs []string, permFilters map[string]any) (map[string]bool, error)

GetEntityIDsInScope reports which entity IDs match permFilters for the given type, resolved server-side in one list query. With no filters every ID is in scope. See scopedEntityIDsBatch for the query shape.

PRECONDITION: every id must be the ~-prefixed internal _id form. The single _in{_id} query does NOT match a bare id (a plain case number or a name), even one that get-by-idOrName would resolve — TheHive only honours _in on _id for the ~-prefixed form (DL-5764). This is safe for the similarity-expansion path, whose ids come straight from a prior search's _id field. Callers that accept user/LLM-supplied ids (which may be bare) must use ScopedEntityIDsTolerant instead, which resolves each id through the more forgiving get-by-idOrName path.

func GetHiveClientFromContext 

func GetHiveClientFromContext(ctx context.Context) (*thehive.APIClient, error)

GetHiveClientFromContext returns the TheHive API client stored in the context, or an error when none is present.

func GetJSONFields 

func GetJSONFields(v any) []string

GetJSONFields returns the json tag names of the exported fields of v (a struct or pointer to struct), skipping fields with no json tag or a "-" tag.

func GetJobsFromObservableID added in v1.1.0 

func GetJobsFromObservableID(ctx context.Context, client *thehive.APIClient, observableID string) ([]map[string]any, error)

GetJobsFromObservableID returns the Cortex analyzer runs of the given observable. Requires TheHive's Cortex connector to be enabled.

func GetObservablesFromAlertID 

func GetObservablesFromAlertID(ctx context.Context, client *thehive.APIClient, alertID string) ([]map[string]any, error)

GetObservablesFromAlertID returns the observables of the given alert.

func GetObservablesFromCaseID 

func GetObservablesFromCaseID(ctx context.Context, client *thehive.APIClient, caseID string) ([]map[string]any, error)

GetObservablesFromCaseID returns the observables of the given case.

func GetPagesFromAlertID 

func GetPagesFromAlertID(ctx context.Context, client *thehive.APIClient, alertID string) ([]map[string]any, error)

GetPagesFromAlertID returns the pages of the given alert.

func GetPagesFromCaseID 

func GetPagesFromCaseID(ctx context.Context, client *thehive.APIClient, caseID string) ([]map[string]any, error)

GetPagesFromCaseID returns the pages of the given case.

func GetPermissionsFromContext 

func GetPermissionsFromContext(ctx context.Context) (*permissions.Config, error)

GetPermissionsFromContext retrieves permissions configuration from the context

func GetProceduresFromAlertID added in v0.3.3 

func GetProceduresFromAlertID(ctx context.Context, client *thehive.APIClient, alertID string) ([]map[string]any, error)

GetProceduresFromAlertID returns the procedures of the given alert.

func GetProceduresFromCaseID added in v0.3.3 

func GetProceduresFromCaseID(ctx context.Context, client *thehive.APIClient, caseID string) ([]map[string]any, error)

GetProceduresFromCaseID returns the procedures of the given case.

func GetScopedEntityIDsBatch added in v1.0.0 

func GetScopedEntityIDsBatch(ctx context.Context, entityType string, entityIDs []string, permFilters map[string]any) (map[string]bool, error)

GetScopedEntityIDsBatch is an alias of GetEntityIDsInScope: both resolve the in-scope set with the same single list query (DL-5764). The distinct name is kept because callers document intent as a batch re-check on the similarity-expansion path.

func GetSimilarAlertsFromAlertID added in v1.0.0 

func GetSimilarAlertsFromAlertID(ctx context.Context, client *thehive.APIClient, alertID string) ([]map[string]any, error)

GetSimilarAlertsFromAlertID returns other alerts that share observables with this alert (alert-to-alert correlation / deduplication).

func GetSimilarAlertsFromCaseID added in v1.0.0 

func GetSimilarAlertsFromCaseID(ctx context.Context, client *thehive.APIClient, caseID string) ([]map[string]any, error)

GetSimilarAlertsFromCaseID returns alerts that share observables with the given case.

func GetSimilarCasesFromAlertID added in v1.0.0 

func GetSimilarCasesFromAlertID(ctx context.Context, client *thehive.APIClient, alertID string) ([]map[string]any, error)

GetSimilarCasesFromAlertID returns cases that share observables with the given alert.

func GetSimilarCasesFromCaseID added in v1.0.0 

func GetSimilarCasesFromCaseID(ctx context.Context, client *thehive.APIClient, caseID string) ([]map[string]any, error)

GetSimilarCasesFromCaseID is the classic "Similar Cases": other cases that share observables with this case.

func GetSupportedQueries 

func GetSupportedQueries(entityType string) []string

GetSupportedQueries returns the list of supported queries for an entity type

func GetTaskLogsFromTaskID 

func GetTaskLogsFromTaskID(ctx context.Context, client *thehive.APIClient, taskID string) ([]map[string]any, error)

GetTaskLogsFromTaskID returns the logs of the given task.

func GetTasksFromCaseID 

func GetTasksFromCaseID(ctx context.Context, client *thehive.APIClient, caseID string) ([]map[string]any, error)

GetTasksFromCaseID returns the tasks of the given case.

func IsClientError added in v1.2.0 

func IsClientError(resp *http.Response) bool

IsClientError reports whether resp is a 4xx other than 429: a refusal that asking again will not change, unlike a network error or a 5xx.

func IsDateField added in v1.1.0 

func IsDateField(fieldName string) bool

IsDateField reports whether a field name carries an epoch timestamp that ProcessDatesRecursive rewrites into a formatted string.

Exported so a tool's advertised output schema can be derived from the same list that drives the rewrite: the Go field is an integer, the value on the wire is a string, and a schema inferred from the struct alone would declare the type the client never receives.

func IsEntityInScope added in v1.0.0 

func IsEntityInScope(ctx context.Context, entityType, entityID string, permFilters map[string]any) (bool, error)

IsEntityInScope is the single-ID form of GetEntityIDsInScope and shares its ~-prefixed-id precondition. For a possibly-bare user/LLM id use IsEntityInScopeTolerant.

func IsEntityInScopeTolerant added in v1.0.0 

func IsEntityInScopeTolerant(ctx context.Context, entityType, entityID string, permFilters map[string]any) (bool, error)

IsEntityInScopeTolerant is the single-ID form of ScopedEntityIDsTolerant: it resolves the id through the bare-id-tolerant get-by-idOrName path.

func IsJobObservableInScope added in v1.0.0 

func IsJobObservableInScope(ctx context.Context, jobID string, permFilters map[string]any) (bool, error)

IsJobObservableInScope reports whether a Cortex job's target observable matches permFilters, resolved server-side (getJob -> observable -> filter). No filters: every job is in scope.

func ListOperationName added in v1.0.0 

func ListOperationName(entityType string) string

ListOperationName returns the TheHive list operation for a type ("case" -> "listCase").

func MarkTrustedSubtree added in v1.2.0 

func MarkTrustedSubtree(value any) any

MarkTrustedSubtree returns value with every string beneath it re-typed as TrustedString, so no value in the subtree is [UNTRUSTED_DATA]-wrapped whatever its field name.

It is the mirror of UntrustedSubtree, for the opposite problem: the boundary allowlist classifies by field NAME, so a subtree that is trusted as a whole but reuses generic key names ("name", "description", "url") cannot be exempted by adding those names — they mean free user text everywhere else. The MITRE ATT&CK catalog (the "pattern" entity) is such a subtree: it is admin-imported reference data, above the trust boundary described on trustedFields, and tagging a technique's name or platform list teaches the model to ignore the tag where it actually matters (DL-6703).

Use it ONLY on a whole entity that is admin-tier reference data, never on a row that merely contains one such field: an analyst-written description sitting next to a catalog reference (a procedure) must keep its tags.

Numbers, booleans and nulls pass through untouched, so the epoch-to-string rewrite of date fields still happens downstream. An UntrustedSubtree nested beneath a marked value keeps its type — it is a named map type, which the type switch below does not match — so third-party JSON stays fenced even inside a catalog row.

func NewToolResultJSONUnescaped 

func NewToolResultJSONUnescaped(data any) *mcp.CallToolResult

NewToolResultJSONUnescaped builds an MCP tool result without escaping non-ASCII characters, so Unicode stays literal, not \uXXXX-escaped.

func NormalizeFilterKeys added in v1.0.0 

func NormalizeFilterKeys(filterMap map[string]any) map[string]any

NormalizeFilterKeys recursively repairs malformed keys in a filter map (see normalizeFilterKey), walking nested maps/slices like TranslateDatesToTimestamps. Unrecoverable keys fall through so TheHive returns its field-listing 400. Mutates and returns filterMap.

Apply only to FILTER maps, never to entity-write payloads — a created entity may legitimately carry a field whose name needs no repair.

func ParseURIParameters added in v0.3.1 

func ParseURIParameters(uri string) (string, map[string]any, error)

ParseURIParameters extracts query parameters from a parameters string

func ProcessDatesRecursive added in v0.3.1 

func ProcessDatesRecursive(value any, wrapUntrusted bool) (any, error)

ProcessDatesRecursive recursively converts date fields in any Go value (structs, maps, slices, arrays, and nesting thereof). When wrapUntrusted is true, non-trusted fields are wrapped with [UNTRUSTED_DATA] boundary tags.

func ReferencedFilterFields added in v1.2.0 

func ReferencedFilterFields(filterMap map[string]any) []string

ReferencedFilterFields returns every field name a filter tests, at any depth: the `_field` of a comparison and the bare name `_contains` takes. Keys are matched after normalizeFilterKey, so a malformed `"_field"` key still counts — it is repaired before the filter reaches TheHive.

func ResponderObjectType added in v1.2.0 

func ResponderObjectType(entityType string) string

ResponderObjectType is the entity type TheHive's responder catalog and action creation endpoints take for one the tools name. They resolve case_task, case_artifact and case_task_log (v0 Conversion.toObjectType) but not task, observable or log, which reached no entity. The action status endpoint lowercases the type and takes the tools' names as they are.

func ScopedEntityIDsByGetOneByOne added in v1.0.0 

func ScopedEntityIDsByGetOneByOne(ctx context.Context, entityType string, entityIDs []string, permFilters map[string]any) (map[string]bool, error)

ScopedEntityIDsByGetOneByOne resolves scope per id through the canonical getX idOrName=<id> -> filter(permFilters) path. get-by-idOrName tolerates bare ids (a plain case number or a name), where the batched _in{_id} query matches only the ~-prefixed internal _id (DL-5764).

It is the implementation behind ScopedEntityIDsTolerant (the CRUD/manage and execute-automation paths) and also the independent differential oracle for TestGetScopedEntityIDsBatchHonorsIDFilter, which diffs the _in path against this one. Prefer the ScopedEntityIDsTolerant / IsEntityInScopeTolerant wrappers in callers so intent reads at the call site; this stays exported for the test.

func ScopedEntityIDsTolerant added in v1.0.0 

func ScopedEntityIDsTolerant(ctx context.Context, entityType string, entityIDs []string, permFilters map[string]any) (map[string]bool, error)

ScopedEntityIDsTolerant reports which entity IDs match permFilters for the given type, resolving each id through the get-by-idOrName path (getX idOrName=<id> -> filter(permFilters)). Unlike GetEntityIDsInScope's single _in{_id} query, this tolerates BARE ids — a plain case number or a name that get-by-idOrName accepts, not only the ~-prefixed internal _id (DL-5764 regression).

Use this on the CRUD/manage and execute-automation paths, where entity ids are supplied by the user/LLM and may be bare. It costs N round-trips (one per id) instead of one; those paths address only a handful of ids, so the tolerance is worth the extra queries. The batched _in path stays on the similarity-expansion fan-out, where ids are provably ~-prefixed and the N-hit round-trip saving matters.

func StatusCause added in v1.2.0 

func StatusCause(err error, resp *http.Response) error

StatusCause returns err, unless it is thehive4go failing to decode TheHive's error body: an error answer holding a field the client's model does not declare (a 400's "errors") makes the client report its own decoding error, `json: unknown field "errors"`, ahead of what TheHive said. The returned error then reads as TheHive's status line and points at the body, which the caller shows where it already did (the API response). It still unwraps to err.

Only an error status is rewritten: a 2xx the client cannot decode is a schema drift worth naming, and its body is entity data. Only err itself is looked at, not what it wraps: a caller's message around the client's error carries guidance this must not replace.

func TranslateDatesToTimestamps 

func TranslateDatesToTimestamps(filterMap map[string]any) map[string]any

TranslateDatesToTimestamps recursively converts date strings in a filter map to epoch millis.

func UnwrapUnion added in v0.3.1 

func UnwrapUnion(v any) any

UnwrapUnion returns the first non-nil pointer field of a union struct, or v itself if none. Union types opt in with a one-liner: 

func (r T) Unwrap() any { return utils.UnwrapUnion(r) }

func ValidateQuery 

func ValidateQuery(entityType, queryName string) error

ValidateQuery checks if a query is supported for an entity type

Types

type EntityQueryConfig 

type EntityQueryConfig map[string]QueryDescriptor

EntityQueryConfig maps query names to their descriptors.

type QueryDescriptor added in v1.0.0 

type QueryDescriptor struct {
	Func QueryFunc
	// EntityType is the type of the RESULTS (e.g. similarCases returns cases),
	// used to project default fields and scope independent results.
	EntityType string
	// ResultsAreIndependent: re-scope these against permFilters (see above).
	ResultsAreIndependent bool
	// MetaFields are match-context fields (e.g. similarObservableCount) carried
	// FLAT alongside the entity by the *Light ops. Empty for queries with none.
	MetaFields []string
}

QueryDescriptor is the single source of truth for one additional query.

ResultsAreIndependent is security-critical: results TheHive returns as top-level entities (e.g. similar cases/alerts) get its .visible org/profile filter but NOT the MCP permFilters, so each hit must be re-checked against permFilters before surfacing or it leaks past the analyst's search scope (DL-6004). Child queries traverse from an already-scoped parent, so no re-check. Declaring it per-query (vs an out-of-band set) means a new independent query that forgets ResultsAreIndependent:true fails review at the registry / TestEveryRegisteredQueryDeclaresScopeIntent instead of failing open.

type QueryFunc 

type QueryFunc func(ctx context.Context, client *thehive.APIClient, entityID string) ([]map[string]any, error)

QueryFunc queries data for a single entity.

type TheHiveTimeoutError added in v1.2.0 

type TheHiveTimeoutError struct {
	Method  string
	Path    string
	Timeout time.Duration
	Err     error
}

TheHiveTimeoutError reports a request to TheHive that got no complete answer within the configured limit, so the server stopped waiting for it.

func AsTheHiveTimeout added in v1.2.0 

func AsTheHiveTimeout(err error) (*TheHiveTimeoutError, bool)

AsTheHiveTimeout returns the TheHive timeout carried anywhere in err's chain.

func (*TheHiveTimeoutError) Error added in v1.2.0 

func (e *TheHiveTimeoutError) Error() string

func (*TheHiveTimeoutError) Hints added in v1.2.0 

func (e *TheHiveTimeoutError) Hints() []string

Hints tells the caller what the timeout means and what is safe to do next. The second one matters most: an abandoned write may still land in TheHive, and a blind retry is how duplicates get created.

func (*TheHiveTimeoutError) Summary added in v1.2.0 

func (e *TheHiveTimeoutError) Summary() string

Summary is the one-line statement a tool error leads with.

func (*TheHiveTimeoutError) Unwrap added in v1.2.0 

func (e *TheHiveTimeoutError) Unwrap() error

type TimeoutTransport added in v1.2.0 

type TimeoutTransport struct {
	Transport http.RoundTripper
	Timeout   time.Duration
}

TimeoutTransport bounds every request, response body included, to Timeout, and reports an expiry as a *TheHiveTimeoutError.

It is a transport rather than http.Client.Timeout so the error can carry the limit and the request that hit it, which is what makes the tool error useful.

func (*TimeoutTransport) RoundTrip added in v1.2.0 

func (t *TimeoutTransport) RoundTrip(req *http.Request) (*http.Response, error)

RoundTrip implements http.RoundTripper.

type TrustedString added in v1.1.0 

type TrustedString string

TrustedString marks a string as trusted regardless of its field name, for keys whose JSON name collides with a genuinely untrusted entity field ("message" is adversarial on comments and task logs but MCP-authored on tool result envelopes; same for the comment envelope's "result" vs a responder's report "result"). Use only for values built from static text and trusted fields (ids, statuses) — never interpolate entity data into one (DL-6703). Prefer building one with Trustedf, and note the exemption composes through slices ([]TrustedString elements also pass unwrapped).

The other source of these is MarkTrustedSubtree, which re-types a whole admin-tier reference subtree; it is the only case where the string is not MCP-authored.

func Trustedf added in v1.1.0 

func Trustedf(format string, args ...any) TrustedString

Trustedf builds a TrustedString envelope message. The format string and every argument must be static text or trusted values (ids, statuses) — never entity free text such as titles, descriptions or names (see TrustedString).

type UntrustedSubtree added in v1.1.0 

type UntrustedSubtree map[string]any

UntrustedSubtree marks a decoded-JSON map whose entire contents are third-party data — e.g. a Cortex analyzer/responder report built from attacker-controlled observables and external feeds. Inside it every string is wrapped regardless of key name: trustedFields classifies TheHive's own schema fields and must not leak into arbitrary JSON that can reuse the same key names ("hashes", "tactics", "status", …). Date keys are not converted either; report keys only coincidentally share names with TheHive date fields (DL-6703 review).

type Unwrapper added in v0.3.1 

type Unwrapper interface {
	Unwrap() any
}

Unwrapper is implemented by union/sum types wrapping a single active variant, so only that variant serializes instead of a struct full of nil siblings.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.