Cribl Search
Integrate with Cribl Search's federated search
TL;DR
To integrate the Cribl Search with Query:
- Generate an API Token and retrieve the Client ID and Client Secret.
- Retrieve your Cribl Organization ID and Cribl Search target name (e.g., Cribl Lake, Cribl Stream).
- Map the schema of data available in Cribl Search into the Open Cybersecurity Schema Framework (OCSF) format using Configure Schema.
- Use Query Federated Search to parallelize search and surface details about entities (observables) and events across Cribl Search for incident response (IR), threat hunting, investigations, and other security and observability use cases.
Overview
Cribl Search is a Cribl product that allows IT Ops, Observability, and Security teams to search their data in-motion and at-rest from several third party sources and other Cribl products such as Cribl Edge and Cribl Stream. Cribl Search uses KQL to query this data and can be used for searching, aggregations, and/or visualizations. Cribl Search comes out-of-the-box with several Datasets such as internal Cribl audit logs and the ability to read directly from Amazon S3 buckets as well.
Cribl Search can extend to read data from other data lakes, data warehouses, direct APIs, and object stores which are detailed in the Connect to Data section of the Cribl Search documentation. For more information on the concepts see the Basic Concepts section of the Cribl Search documentation. At a high-level, there are Dataset Providers which are where the data is stored such as in Cribl Edge or direct APIs and contain parsing and connectivity data. The Dataset is akin to an "index" or "table" or "target" from the Dataset Provider to perform searches. Query integrates at the Dataset layer by directly interfacing with the Search API to submit and process queries.
Query's entire data model is built around the Open Cybersecurity Schema Framework (OCSF) - named the Query Data Model (QDM) - which expresses all search intents with OCSF/QDM concepts such as Entities/Observables used to represent facts and indicators whereas Event Classes represent things that have happened and are normalized against network, application, file system, identity, and 1st party security findings.
When using the Query integration with Cribl Search, you can parallelize across a nearly limitless (pursuant to rate limits in your Cribl tenant) amount of Datasets and have all the data returned normalized in OCSF/QDM format regardless of the downstream data format. Each configured Connector that can fulfill the query plan from the Query Federated Search is queried in parallel and results are re-used for up to 20 minutes per search in Cribl Search. On average, results should return in 15-35 seconds depending on the size of the data and amount of normalization.
Query integrates with Cribl Search by translating searches into specific Cribl Search KQL queries, setting limits for time, data scanned, and results returned, and transforming the data into OCSF/QDM following the mappings set by customers in our Configure Schema no-code mapping utility for mapping OCSF from any Cribl Search Dataset.
Some details on searches
Query cannot account for what is going on downstream of a Cribl Search dataset - for instance, if you have non-partitioned or non-optimized/non-accelerated datasets - and uses the
SET
statements to limit potential cost overruns by terminating searches when they reach a certain timeout (45 seconds) or data size (5.5MB).Always ensure you Cribl Search Datasets are accelerated or well-optimized or are searching against optimal sources such as Cribl Edge, Cribl Lake, or well-constructed Data Warehouse tables for the optimal searching experience!
Prerequisites
To connect a Cribl Search Dataset with Query Federated Search you'll need to have your Organization ID, Dataset Name, and the Client ID and Client Secret from an API Token. You'll need access as an Owner, Admin, or other similar permission set as a user within your Cribl tenant and specific Organization to fulfill the following prerequisite steps.
-
To retrieve you Organization ID hover your cursor over the Organization Details icon on the bottom-left of the navigation pane from the Cribl console and copy it as shown below (FIG. 1).
-
To create an API Credential, from the Cribl console of your workspace (e.g.,
https://manage[.]cribl.cloud/organizations/{YOUR_ORG_ID}/workspaces/main
) in the Navigation Pane select Organization --> API Credentials --> Add Credential as shown below (FIG. 2). -
Enter a descriptive Name, a Description and ensure that the Credential is Enabled. Select the
User
option for Organization Permissions,Member
permission for Workspace Access and grant Admin for Cribl Search as shown below (FIG. 3) and then Save the Credential.
Some details on permissions and searches
As of 12 NOV 2024 there is not a Read Only scope for Cribl Search. Query Federated Search only uses GET and POST methods against the
api/v1/m/default_search/search/jobs
Cribl Search API to submit queries and process the results.
- After creating your API Credential, ensure you copy the Client ID and Client Secret, these will be exchanged for a bearer token from the OAuth2 API.
- To retrieve one or more Cribl Search Datasets, hover over the Products menu at the top-left of your Cribl console, and select Data under the Search product. The Dataset Name corresponds to any values in the ID column as shown below (FIG. 4). Query's Configure Schema will introspect the schema using a limited "select all" search and provide you the mechanism to map the columns into OCSF/QDM.
To learn how to configure a Cribl Search Connector, proceed to the next section.
On NHI security
NHI - or, Non-Human Identities - such as your Cribl API Credential are extremely sensitive, especially with that Cribl Search Admin scope. Query securely stores the Client Secret in a dedicated AWS Secrets Manager Secret per Connector per Tenant.
While this requires you to configure Connectors per Dataset and continue to enter in your credentials, every copy is stored as securely as each other with minimum necessary permissions that only allows the specific piece of serverless infrastructure to retrieve the secret, it is never cached or persisted outside of the Secret.
Setting up the Cribl Search Connector
Use the following steps to create a new Query Federated Search Connector for Cribl Search.
-
Navigate to the Connectors page, select Add Connector, and selectCribl Search from the
SIEM and Log Management
category as shown below (FIG. 4). You can also search for Cribl Search using the search bar in the Add Connector page. -
In the Configure Connector tab, add the following detail as shown below (FIG. 5):
-
Connector Alias Name: The human-readable name you want to give to this connector, you can provide the name of the datasets for numerous Workspaces or Cribl Tenants, or use any other naming convention that makes sense for your end users.
-
Default Login: Leave the default value:
Default Login
. -
Cribl Cloud Organization ID: Your Cribl Organization ID, copied in Step 1 of the Prerequisites section.
-
Audience URL: Leave the default value:
https://api.cribl.cloud
. This is only used for theaudience
argument for the OAuth2 API to exchange your API Credential Client ID and Client Secret for a bearer authorization token. -
Client ID: The Client ID of your API Credential. copied in Step 4 of the Prerequisites section.
-
Table Name: The name of your Cribl Search Dataset, it does not need to be a downstream table.
-
Client Secret: The Client Secret of your API Credential. copied in Step 4 of the Prerequisites section.
-
-
Select Save to save and activate the Connector.
-
Select Test Connection from the bottom-right of the connection pane to ensure that your API Credential Client ID and Client Secret are valid, that your Dataset is valid, and that Query can successfully dispatch a search against it.
-
Finally, proceed to the Preview Data section to begin the Configure Schema process. Refer to the hyperlink to learn how to use the Configure Schema no-code workflow, it is HIGHLY recommended for first time users.
You will now see Tégo added as an available Platform within the Query Search and Query Summary Insights UI, the "platform" term is synonymous with Connector.
Querying Cribl Search Connectors
Within the Query Search UI, all Connectors are enabled by default. To check that your specified Connector(s) for Cribl Search are enabled, navigate to the SIEM and Log Management section of the Selected Connectors dropdown and ensure that your specified Cribl Search Connector(s) are are selected (denoted by a checkbox) before running your searches as shown below (FIG. 6).
The Entities (Observables) and Events you will be able to search determine on how you mapped your data in Configure Schema against a given Cribl Search Dataset. For more information about the QDM/OCSF schema itself refer to the About the Query Data Model section of the Query docs, you can also view the Categories, Events, and Objects themselves.
Example Cribl Search cribl_logs
Mapping
cribl_logs
MappingAs an example, consider mapping one of the Cribl Search Datasets that are automatically configured, such as cribl_logs
, which contain internal audit logs agains the API Activity or Web Resources Activity Event Class. For an example mapping, consider the following.
- Event Class: Select API Activity from the dropdown.
- Event Time: Select the
_time
field, which is the default Epoch seconds (Unix time) within the Dataset. This is used to prune searches by setting the upper and lower bounds for start and end withSET
statements. - Entities: These are multi-selection fields that correspond to all scalar OCSF Observables (see the
Type ID
section of the table.- Account ID:
accountId
- Account Name:
tenantId
, this is your Cribl Organization ID, typically. - Hostname:
instance
andsaas_domain
, these are typically Cribl Edge hosts andcribl.cloud
, respectively. - IP Address:
src
, this is the IP address where a request originated from. - URL:
url
, this is the URL string of the specific endpoint that was requested such as/api/v1/health
or otherwise.
- Account ID:
- Attributes: These are the individual key-value pairs that make up the OCSF/QDM schema, you do not need to actually map any of these if you do not wish to. The following IS NOT an exhaustive list, it will populate most important elements to display in the Results and Summary Insights visualizations.
activity_id
: Choosemethod
and map the following enums to constant values- 1 CREATE:
POST
- 2 READ:
GET
- 3 UPDATE:
PUT
- 4 DELETE:
DELETE
- 1 CREATE:
count
:events
message
:message
severity_id
:datatype
and enter the constant value ofcribl_json
for 1 INFORMATIONAL to have every event populate as informational.status_detail
:parseErrors
status_id
Choosestatus
and map the following enums to constant values- 1 SUCCESS:
200
- 2 FAILURE:
400
,403
,500
,502
- 1 SUCCESS:
actor.user.name
:user
api.operation
:method
api.request.uid
:requestId
api.response.message
:message
metadata.log_level
:level
metadata.log_name
:data_source
metadata.original_time
:_time
metadata.tenant_uid
:tenantId
metadata.uid
:requestId
, this will not populate all of the time.src_endpoint.domain
:saas_domain
, this is almost always cribl[.]cloudsrc_endpoint.ip
:src
, this is not always present.
Entity-based Search
To conduct an Entity-based search, ensure that all of the data points you will be searching for are mapped within the Configure Schema wizard as demonstrated in the previous section.
In the Federated Search console, select the search dropdown, ensure the Entities radio button is selected and search for your desired Entity as shown below (FIG. 7). For instance, you can search for an IP Address of a specific Cribl Edge node or an external user, these can be further correlated against other Cribl Search and different Query Connectors.
After selecting an Entity, most allow you to specify an Operator. This allows you to perform simple equality searches or to perform more generalized searches using Contains, Starts With, or Ends With Operators. These are mapped against its appropriate Cribl string operator.
When you search for multiple values that may be present across different tables, the Query Federated Search query planner inspects the Configure Schema metadata to ensure searches are sent to the appropriate Datasets - as well as other applicable Query Connectors - these will not use potential expensive Data Operators such as join or union, and operate more as a collated window function within Query.
Additionally, you can specify case-sensitivity for the entire search criteria. An example of a multi-value "Hostname contains" search is shown below (FIG. 8).
Event-based Search
To conduct an Event-based search, ensure that all of the data points you will be searching for are mapped within the Configure Schema wizard as demonstrated in the mapping section. Within the Federated Search console, only mapped Events per the Select Connectors are populated, unlike Entities which has every potential value shown in the list.
In the Federated Search console, select the search dropdown, ensure the Events radio button is selected and search for your desired Event as shown below (FIG. 9). For instance, you can search for all API Activity events which you normalized cribl_logs
, in addition you can also search across all Connectors normalized to API Activity such as AWS CloudTrail Management Events stored in AWS Security Lake, System Event logs in Okta, and Audit Events in Microsoft Intune.
Searching from the Event will pull a sample (up to 1000) of all matching events per Connectors that are mapped to it. For more specific filtering within an Event, you can choose one or more conditions to refine a search. Selecting the plus-sign (+
) dropdown next to the Event menu allows you to choose from any specific OCSF/QDM attribute in the event.
For instance, when searching for API Activity events, you can specify a specific Username by filtering for Actor
--> User
--> Name
(which is mapped in Configure Schema as actor.user.name
) as shown below (FIG. 10).
When adding two or more Conditions, you can further change the behavior by specifying ANY
or ALL
quantifiers over the filters for greater levels of specificity or more narrow-but-generalized searches, respectively, as shown below (FIG. 11).
Resources
Updated 2 days ago