refactor(filters): add filter pkg and middleware for slice architecture BED-8594

cmd/api/src/api/constant.go

@@ -53,6 +53,7 @@ const (
 
 	// URI path parameters
 	URIPathVariableApplicationConfigurationParameter = "parameter"
+	URIPathVariableAlertWebhookID                    = "alert_webhook_id"
 	URIPathVariableAssetGroupID                      = "asset_group_id"
 	URIPathVariableAssetGroupSelectorID              = "asset_group_selector_id"
 	URIPathVariableAssetGroupTagID                   = "asset_group_tag_id"

cmd/api/src/api/middleware/filters.go

@@ -0,0 +1,76 @@
+// 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 middleware
+
+import (
+	"errors"
+	"fmt"
+	"net/http"
+
+	"github.com/gorilla/mux"
+
+	"github.com/specterops/bloodhound/cmd/api/src/api"
+	"github.com/specterops/bloodhound/cmd/api/src/bhctx"
+	"github.com/specterops/bloodhound/cmd/api/src/model"
+	"github.com/specterops/bloodhound/packages/go/filters"
+)
+
+// FilterMiddleware parses query parameter filters from the request, validates them against the supplied
+// filters.Filterable definition, and enriches the BloodHound context with the resulting filters.Filters map.
+//
+// When filterable is nil the middleware performs no parsing and passes the request through unchanged. If
+// the filters are malformed, reference a column that cannot be filtered, or use an operator the column
+// does not support, the middleware writes a 400 response and halts the chain.
+func FilterMiddleware(filterable filters.Filterable) mux.MiddlewareFunc {
+	return func(next http.Handler) http.Handler {
+		return http.HandlerFunc(func(response http.ResponseWriter, request *http.Request) {
+			if filterable == nil {
+				next.ServeHTTP(response, request)
+				return
+			}
+
+			parser := filters.NewQueryParameterFilterParser(append(model.IgnoreFilters(), model.AllPaginationQueryParameters()...)...)
+			if parsedFilters, err := parser.ParseAndValidate(request.URL.Query(), filterable); err != nil {
+				api.WriteErrorResponse(request.Context(), api.BuildErrorResponse(http.StatusBadRequest, filterErrorMessage(err), request), response)
+				return
+			} else {
+				bhCtx := bhctx.Get(request.Context())
+				bhCtx.Filters = parsedFilters
+			}
+
+			next.ServeHTTP(response, request)
+		})
+	}
+}
+
+// filterErrorMessage maps a filter validation failure to the appropriate API error response detail,
+// preserving the offending field and operator in the message where available.
+func filterErrorMessage(err error) string {
+	var validationErr *filters.ValidationError
+	if !errors.As(err, &validationErr) {
+		return api.ErrorResponseDetailsBadQueryParameterFilters
+	}
+
+	switch {
+	case errors.Is(validationErr, filters.ErrFieldNotFilterable):
+		return fmt.Sprintf("%s: %s", api.ErrorResponseDetailsColumnNotFilterable, validationErr.Field)
+	case errors.Is(validationErr, filters.ErrOperatorNotSupported):
+		return fmt.Sprintf("%s: %s %s", api.ErrorResponseDetailsFilterPredicateNotSupported, validationErr.Field, validationErr.Operator)
+	default:
+		return api.ErrorResponseDetailsBadQueryParameterFilters
+	}
+}

cmd/api/src/api/router/router.go

@@ -27,6 +27,7 @@ import (
 	"github.com/specterops/bloodhound/cmd/api/src/database"
 	"github.com/specterops/bloodhound/cmd/api/src/model"
 	"github.com/specterops/bloodhound/cmd/api/src/services/dogtags"
+	"github.com/specterops/bloodhound/packages/go/filters"
 )
 
 // With takes a function returning a mux.MiddlewareFunc type and applies it the to variadic list of routes
@@ -113,6 +114,13 @@ func (s *Route) CheckFeatureFlag(ff featureFlag, flagKey string) *Route {
 	return s
 }
 
+// WithFilters wires the query parameter filter middleware onto the route, validating any filters against
+// the supplied filters.Filterable definition and enriching the request context with the parsed filters.
+func (s *Route) WithFilters(filterable filters.Filterable) *Route {
+	s.handler.Use(middleware.FilterMiddleware(filterable))
+	return s
+}
+
 func NewRouter(cfg config.Configuration, authorizer auth.Authorizer, contentSecurityPolicy string) Router {
 	muxRouter := mux.NewRouter()
 	muxRouter.Use(middleware.EnsureRequestBodyClosed())

cmd/api/src/bhctx/bhctx.go

@@ -25,6 +25,7 @@ import (
 
 	"github.com/specterops/bloodhound/cmd/api/src/auth"
 	"github.com/specterops/bloodhound/cmd/api/src/model"
+	"github.com/specterops/bloodhound/packages/go/filters"
 )
 
 // Use our own type rather than a primitive to avoid collisions
@@ -43,6 +44,7 @@ type Context struct {
 	RequestedURL model.AuditableURL
 	RequestIP    string
 	RemoteAddr   string
+	Filters      filters.Filters
 }
 
 func (s *Context) ConstructGoContext() context.Context {

packages/go/filters/filter.go

@@ -0,0 +1,116 @@
+// 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 filters provides a storage-agnostic model for parsing and validating query parameter filters.
+// It intentionally carries no knowledge of how filters are ultimately applied (SQL, graph, etc.) so that
+// it can be reused across the API without coupling to any particular persistence layer.
+package filters
+
+import (
+	"errors"
+	"fmt"
+)
+
+// FilterOperator identifies the comparison predicate applied to a filtered column.
+type FilterOperator string
+
+const (
+	GreaterThan         FilterOperator = "gt"
+	GreaterThanOrEquals FilterOperator = "gte"
+	LessThan            FilterOperator = "lt"
+	LessThanOrEquals    FilterOperator = "lte"
+	Equals              FilterOperator = "eq"
+	NotEquals           FilterOperator = "neq"
+	ApproximatelyEquals FilterOperator = "~eq"
+)
+
+// Validation sentinels classify why a set of query parameter filters failed validation. Callers should
+// classify failures with errors.Is and may extract the offending field/operator via a *ValidationError
+// using errors.As. These are intentionally free of any transport- or presentation-specific wording.
+var (
+	ErrMalformedFilter      = errors.New("query parameter filter is malformed")
+	ErrFieldNotFilterable   = errors.New("column cannot be filtered")
+	ErrOperatorNotSupported = errors.New("filter operator is not supported for column")
+)
+
+// ValidationError describes a filter validation failure. It wraps one of the validation sentinels so it
+// can be classified with errors.Is, while also carrying the offending field and operator so callers can
+// build their own messaging without parsing strings.
+type ValidationError struct {
+	Err      error
+	Field    string
+	Operator FilterOperator
+}
+
+func (s *ValidationError) Error() string {
+	switch {
+	case s.Field != "" && s.Operator != "":
+		return fmt.Sprintf("%s: %s %s", s.Err, s.Field, s.Operator)
+	case s.Field != "":
+		return fmt.Sprintf("%s: %s", s.Err, s.Field)
+	default:
+		return s.Err.Error()
+	}
+}
+
+func (s *ValidationError) Unwrap() error {
+	return s.Err
+}
+
+// ParseFilterOperator validates a raw operator string and returns the corresponding FilterOperator.
+func ParseFilterOperator(raw string) (FilterOperator, error) {
+	switch operator := FilterOperator(raw); operator {
+	case GreaterThan, GreaterThanOrEquals, LessThan, LessThanOrEquals, Equals, NotEquals, ApproximatelyEquals:
+		return operator, nil
+	default:
+		return "", fmt.Errorf("%w: unknown predicate %q", ErrMalformedFilter, raw)
+	}
+}
+
+// FilterSetOperator describes how multiple filters on the same column are combined.
+type FilterSetOperator string
+
+const (
+	FilterAnd FilterSetOperator = "AND"
+	FilterOr  FilterSetOperator = "OR"
+)
+
+// Filter is a single validated filter applied to a field.
+type Filter struct {
+	Field        string
+	Operator     FilterOperator
+	Value        string
+	SetOperator  FilterSetOperator
+	IsStringData bool
+}
+
+// Filters maps a field name to the set of filters applied to it.
+type Filters map[string][]Filter
+
+// FilterableField describes a single field that may be filtered on. It carries the set of operators the
+// field supports, IsStringData (whether the field holds string data), and SetOperator (how multiple
+// filters applied to the field are combined). An empty SetOperator defaults to FilterAnd.
+type FilterableField struct {
+	Operators    []FilterOperator
+	IsStringData bool
+	SetOperator  FilterSetOperator
+}
+
+// Filterable is implemented by types that expose the fields that may be filtered along with each
+// field's supported operators and data typing.
+type Filterable interface {
+	ValidFilters() map[string]FilterableField
+}

packages/go/filters/parser.go

@@ -0,0 +1,83 @@
+// 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 filters
+
+import (
+	"net/url"
+	"regexp"
+	"slices"
+)
+
+// QueryParameterFilterParser extracts filters from request query parameters. Parameters whose names are
+// listed in ignoredParameters are skipped, allowing callers to exclude application-specific concerns such
+// as pagination parameters without coupling this package to them.
+type QueryParameterFilterParser struct {
+	valuePattern      *regexp.Regexp
+	ignoredParameters []string
+}
+
+// NewQueryParameterFilterParser returns a parser that ignores the supplied query parameter names.
+func NewQueryParameterFilterParser(ignoredParameters ...string) QueryParameterFilterParser {
+	return QueryParameterFilterParser{
+		valuePattern:      regexp.MustCompile(`([~\w]+):([\w\--_ ]+)`),
+		ignoredParameters: ignoredParameters,
+	}
+}
+
+// ParseAndValidate parses the supplied query parameters and validates them against the Filterable schema
+// in a single pass, returning a fully-enriched Filters value. Every returned Filter has its SetOperator
+// and IsStringData populated from the column definition. On failure it returns a *ValidationError wrapping
+// one of the validation sentinels.
+func (s QueryParameterFilterParser) ParseAndValidate(values url.Values, filterable Filterable) (Filters, error) {
+	var (
+		validFields   = filterable.ValidFilters()
+		parsedFilters = Filters{}
+	)
+
+	for name, fieldValues := range values {
+		if slices.Contains(s.ignoredParameters, name) {
+			continue
+		}
+
+		for _, value := range fieldValues {
+			if subgroups := s.valuePattern.FindStringSubmatch(value); len(subgroups) == 0 {
+				continue
+			} else if operator, err := ParseFilterOperator(subgroups[1]); err != nil {
+				return nil, &ValidationError{Err: err}
+			} else if field, isFilterable := validFields[name]; !isFilterable {
+				return nil, &ValidationError{Err: ErrFieldNotFilterable, Field: name}
+			} else if !slices.Contains(field.Operators, operator) {
+				return nil, &ValidationError{Err: ErrOperatorNotSupported, Field: name, Operator: operator}
+			} else {
+				setOperator := field.SetOperator
+				if setOperator == "" {
+					setOperator = FilterAnd
+				}
+
+				parsedFilters[name] = append(parsedFilters[name], Filter{
+					Field:        name,
+					Operator:     operator,
+					Value:        subgroups[2],
+					SetOperator:  setOperator,
+					IsStringData: field.IsStringData,
+				})
+			}
+		}
+	}
+
+	return parsedFilters, nil
+}