Documentation
¶
Overview ¶
Copyright 2025 SGNL.ai, Inc.
Copyright 2025 SGNL.ai, Inc.
Copyright 2025 SGNL.ai, Inc.
Copyright 2025 SGNL.ai, Inc.
Copyright 2025 SGNL.ai, Inc.
Copyright 2025 SGNL.ai, Inc.
Copyright 2025 SGNL.ai, Inc.
Copyright 2025 SGNL.ai, Inc.
TODO: The contents of this file are unused at the moment. Do not remove. We need it for future improvements.
Copyright 2025 SGNL.ai, Inc.
Index ¶
- Constants
- Variables
- func ConstructRESTEndpoint(request *Request, path string) (*string, *framework.Error)
- func GetAttributePath(input string) []string
- func GetPageInfoAfter(pageInfo *PageInfo, n int) *string
- func NewAdapter(client Client) framework.Adapter[Config]
- func ParseError(errors []ErrorItem) *framework.Error
- func SetAfterParameter(value *string) string
- type Adapter
- func (a *Adapter) GetPage(ctx context.Context, request *framework.Request[Config]) framework.Response
- func (a *Adapter) RequestPageFromDatasource(ctx context.Context, request *framework.Request[Config]) framework.Response
- func (a *Adapter) ValidateGetPageRequest(ctx context.Context, request *framework.Request[Config]) *framework.Error
- type AlertsMeta
- type AlertsPagination
- type AlertsRequestBody
- type AlertsResponse
- type AttributeNode
- type Client
- type Config
- type Datasource
- type DatasourceResponse
- type DetailedResourceRequestBody
- type DetailedResourceResponse
- type EndpointInfo
- type EndpointQueryBuilder
- type Entity
- type ErrorItem
- type FragmentType
- type IncidentQueryBuilder
- type ListResourceResponse
- type ListScrollResourceResponse
- type MetaFields
- type PageInfo
- type PaginationInfo
- type QueryBuilder
- type Request
- type Response
- type ResponseItems
- type ScrollMetaFields
- type ScrollPaginationInfo
- type UserQueryBuilder
Constants ¶
const ( User string = "user" Incident string = "incident" Endpoint string = "endpoint" Device string = "endpoint_protection_device" EndpointIncident string = "endpoint_protection_incident" Alerts string = "endpoint_protection_alert" )
const (
// MaxPageSize is the maximum page size allowed in a GetPage request.
MaxPageSize = 1000
)
Variables ¶
var ( // ValidGraphQLEntityExternalIDs is a map of valid external IDs of entities that can be queried. // The map value is the Entity struct which contains the unique ID attribute. ValidGraphQLEntityExternalIDs = map[string]Entity{ User: { UniqueIDAttrExternalID: "entityId", OrderByAttribute: "RISK_SCORE", }, Incident: { UniqueIDAttrExternalID: "incidentId", OrderByAttribute: "END_TIME", }, Endpoint: { UniqueIDAttrExternalID: "entityId", OrderByAttribute: "RISK_SCORE", }, } ValidRESTEntityExternalIDs = map[string]Entity{ Device: {}, EndpointIncident: {UseIntCursor: true}, Alerts: {}, } )
var (
EntityExternalIDToEndpoint = map[string]EndpointInfo{
Device: {
ListEndpoint: "devices/queries/devices-scroll/v1",
GetEndpoint: "devices/entities/devices/v2",
},
EndpointIncident: {
ListEndpoint: "incidents/queries/incidents/v1",
GetEndpoint: "incidents/entities/incidents/GET/v1",
},
Alerts: {
GetEndpoint: "alerts/combined/alerts/v1",
},
}
)
var (
SupportedAPIVersions = map[string]struct{}{
"v1": {},
}
)
Functions ¶
func ConstructRESTEndpoint ¶
func GetAttributePath ¶
func GetPageInfoAfter ¶
This returns the PageInfo struct of the n deep layer, where 0 is the outermost layer. If n > number of layers or the pageInfo is nil, the function returns nil. If n < 0, the function returns the PageInfo of the outermost layer.
func NewAdapter ¶
NewAdapter instantiates a new Adapter.
func ParseError ¶
func SetAfterParameter ¶
Types ¶
type Adapter ¶
type Adapter struct {
// Client provides access to the datasource.
Client Client
}
Adapter implements the framework.Adapter interface to query pages of objects from datasources.
func (*Adapter) GetPage ¶
func (a *Adapter) GetPage(ctx context.Context, request *framework.Request[Config]) framework.Response
GetPage is called by SGNL's ingestion service to query a page of objects from a datasource.
type AlertsMeta ¶ added in v1.50.0
type AlertsMeta struct {
Pagination AlertsPagination `json:"pagination"`
}
type AlertsPagination ¶ added in v1.50.0
type AlertsRequestBody ¶ added in v1.50.0
type AlertsResponse ¶ added in v1.50.0
type AlertsResponse struct {
Meta AlertsMeta `json:"meta"`
Resources []map[string]any `json:"resources"`
Errors []ErrorItem `json:"errors"`
}
type AttributeNode ¶
type AttributeNode struct {
Name string
Children map[string]*AttributeNode
IsFragment bool
FragmentType *FragmentType
}
AttributeNode stores the metadata required to build the inner part of the query for an entity.
func AttributeQueryBuilder ¶
func AttributeQueryBuilder( entityConfig *framework.EntityConfig, rootName string, ) (*AttributeNode, *framework.Error)
func (*AttributeNode) AddChild ¶
func (node *AttributeNode) AddChild(path []string, isFragment bool, fragmentType *FragmentType) *AttributeNode
AddChild adds a child to the current node and returns the child node.
func (*AttributeNode) BuildQuery ¶
func (node *AttributeNode) BuildQuery() string
type Client ¶
type Client interface {
// GetPage returns a page of JSON objects from the datasource for the
// requested entity.
// Returns a (possibly empty) list of JSON objects, each object being
// unmarshaled into a map by Golang's JSON unmarshaler.
GetPage(ctx context.Context, request *Request) (*Response, *framework.Error)
}
Client is a client that allows querying the datasource which contains JSON objects.
type Config ¶
type Config struct {
// Common configuration
*config.CommonConfig
APIVersion string `json:"apiVersion,omitempty"`
Archived bool `json:"archived,omitempty"`
Enabled bool `json:"enabled,omitempty"`
Filters map[string]string `json:"filters,omitempty"`
}
Example Config:
{
"apiVersion": "v1",
"archived": false,
"enabled": true,
"filters": {
"endpoint_protection_device": "platform:'Windows'"
}
}
Config is the optional configuration passed in each GetPage calls to the adapter.
type Datasource ¶
Datasource directly implements a Client interface to allow querying an external datasource.
type DatasourceResponse ¶
type DatasourceResponse struct {
Entities ResponseItems `json:"entities"`
Incidents ResponseItems `json:"incidents"`
}
type DetailedResourceRequestBody ¶
type DetailedResourceRequestBody struct {
Identifiers []string `json:"ids"`
}
type DetailedResourceResponse ¶
type DetailedResourceResponse struct {
Meta MetaFields `json:"meta"`
Resources []map[string]any `json:"resources"`
Errors []ErrorItem `json:"errors"`
}
type EndpointInfo ¶
The REST APIs of CrowdStrike are two level. A list endpoint is used to list entity IDs. A get endpoint is used to get detailed metadata of a specific entity. If a REST API has only one endpoint, it is considered as a get endpoint.
type EndpointQueryBuilder ¶
type Entity ¶
type Entity struct {
// UniqueIDAttrExternalID is the external ID of the entity's uniqueId attribute.
UniqueIDAttrExternalID string
// OrderByAttribute is the attribute to order the results by.
OrderByAttribute string
// UseIntCursor
UseIntCursor bool
}
Entity contains entity specific information, such as the entity's unique ID attribute.
type FragmentType ¶
type IncidentQueryBuilder ¶
type ListResourceResponse ¶
type ListResourceResponse struct {
Meta MetaFields `json:"meta"`
Resources []string `json:"resources"`
Errors []ErrorItem `json:"errors"`
}
type ListScrollResourceResponse ¶
type ListScrollResourceResponse struct {
Meta ScrollMetaFields `json:"meta"`
Resources []string `json:"resources"`
Errors []ErrorItem `json:"errors"`
}
type MetaFields ¶
type MetaFields struct {
PaginationInfo PaginationInfo `json:"pagination"`
}
type PageInfo ¶
type PaginationInfo ¶
type QueryBuilder ¶
QueryBuilder is an interface that defines the method for building a query. Each entity has its own builder struct that contains the query parameters required to retrieve the entity.
func GetQueryBuilder ¶
func GetQueryBuilder(request *Request, _ *PageInfo) (QueryBuilder, *framework.Error)
type Request ¶
type Request struct {
// BaseURL is the Base URL of the datasource to query.
BaseURL string
// Token is the Authorization token to use to authentication with the datasource.
Token string
// PageSize is the maximum number of objects to return from the entity.
PageSize int64
// EntityExternalID is the external ID of the entity.
// The external ID should match the API's resource name.
EntityExternalID string
// A Falcon Query Language filter applicable for REST API based entities.
// See more at https://falconpy.io/Usage/Falcon-Query-Language.html#operators
Filter *string
// GraphQLCursor identifies the first object of the page to return, as returned by
// the last request for the entity. This field is used to paginate entities from GraphQL APIs.
// Optional. If not set, return the first page for this entity.
GraphQLCursor *pagination.CompositeCursor[string]
// RESTCursor identifies the first object of the page to return, as returned by
// the last request for the entity. This field is used to paginate entities from REST APIs.
// Optional. If not set, return the first page for this entity.
RESTCursor *pagination.CompositeCursor[string]
// EntityConfig contains entity metadata and a list of attributes to request along with the current request.
EntityConfig *framework.EntityConfig
// Ordered is a boolean that indicates whether the results should be ordered.
Ordered bool
Config *Config
// RequestTimeoutSeconds is the timeout duration for requests made to datasources.
// This should be set to the number of seconds to wait before timing out.
RequestTimeoutSeconds int
}
Request is a request to the datasource.
type Response ¶
type Response struct {
// StatusCode is an HTTP status code.
StatusCode int
// RetryAfterHeader is the Retry-After response HTTP header, if set.
RetryAfterHeader string
// Objects is the list of parsed entity objects returned from the datasource. // May be empty.
Objects []map[string]any
// NextGraphQLCursor is the cursor that identifies the first object of the next
// page for GraphQL APIs.
// May be empty.
NextGraphQLCursor *pagination.CompositeCursor[string]
// NextRESTCursor is the cursor that identifies the first object of the next
// page for REST APIs.
// May be empty.
NextRESTCursor *pagination.CompositeCursor[string]
}
type ResponseItems ¶
type ScrollMetaFields ¶
type ScrollMetaFields struct {
PaginationInfo ScrollPaginationInfo `json:"pagination"`
}
type ScrollPaginationInfo ¶
type ScrollPaginationInfo struct {
Offset string `json:"offset"`
Limit int `json:"limit"`
Total int `json:"total"`
}
"devices/queries/devices-scroll/v1" endpoint has a string offset.