Cribl Search - Searching using the API
The goal of this article is to give pointers on how to utilize the Cribl Cloud API to perform Cribl Search queries in a systematic manner. This can be utilized for integrations with automation platforms or other external tools.
Creating Credentials
Cribl Cloud’s login process over the API is a bit different than self-hosting. For this, you will have to generate an Client ID and a Client Secret.
This can be done in the Organization page of the Cribl Cloud console. Once logged in, open the API Credentials section under the organization tab. From there, click Add Credential with the needed permissions.
More Info: Cribl Docs
Logging into Cribl Cloud
The login url is the same for everyone: https://login.cribl.cloud/oauth/token.
The body of your request should be URL form encoded, containing the following fields and values
| Parameter | Value |
|---|---|
| grant_type | client_credentials |
| client_id | « Client ID from Cribl Cloud » |
| client_secret | « Client Secret from Cribl Cloud » |
| audience | https://api.cribl.cloud |
Example curl request: (the credentials below are not real in case anyone gets any funny ideas)
curl -X POST 'https://login.cribl.cloud/oauth/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data 'grant_type=client_credentials' \
--data 'client_id=ir5YRk2rHq7KvgwrDgaLMuMg3zLDKUxQ' \
--data 'client_secret=2VyZYXbLNzZtaBckZ7aA0fFR6bx59LRk8vn8nFmBUc5y4QDdtH2E4WJ8eVr44tvg' \
--data 'audience=https://api.cribl.cloud'The response will look something similar to:
{
"access_token": "<<ACCESS_TOKEN>>",
"scope": "<<SCOPES>>",
"expires_in": 86400,
"token_type": "Bearer"
}We will utilize the access token attribute in this response to authenticate further calls. Authentication is provided as a Header. The name of the header is Authorization and the value will be Bearer <<ACCESS TOKEN FROM LOGIN REQUEST>>
Creating a Search
There are two seperate endpoints used to create searches and obtain results. The first endpoint will be to create the search, and it will look something like: https://main-incredible-swift-abc13ts.cribl.cloud/api/v1/m/default_search/search/jobs.
The body of the payload send to this endpoint will be a JSON object.
Note: that the query contains the cribl operator at the start, an operator is required at the beginning of the query.
{
"query": "cribl dataset=\"cribl_search_sample\" | limit 1000",
"earliest": "-1h",
"latest": "now",
"sampleRate": 1
}Example curl request:
curl -X POST 'https://main-incredible-swift-abc13ts.cribl.cloud/api/v1/m/default_search/search/jobs' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer << ACCESS TOKEN >>' \
--data-raw '{
"query": "cribl dataset=\"cribl_search_sample\" | limit 1000",
"earliest": "-1h",
"latest": "now",
"sampleRate": 1
}'The returning payload will contain a lot of information about the search created, including it’s id which will be required to obtain results.
{
"items": [
{
"query": "cribl dataset=\"cribl_search_sample\" | limit 1000",
...
"group": "default_search",
"id": "1732566655829.Z6s9KD",
"timeCreated": 1732566655887,
...
}
],
"count": 1
}Waiting for the Search to complete
We must wait for the search to complete to retrieve the result set. A GET request against the status endpoint will provide information on the search.
Example curl request:
curl -X GET 'https://main-incredible-swift-abc13ts.cribl.cloud/api/v1/m/default_search/search/jobs/<< JOB ID >>/status' \
--header 'accept: application/x-ndjson' \
--header 'Authorization: Bearer << ACCESS TOKEN >>'The response will contain a JSON object with an items array. Inside the array, an object with status information on the search is included. A status of completed indicates the search is complete.
{
"items": [
{
"status": "completed",
...
}
],
"count": 1
}Obtaining Results
Once the status of the job is completed, passing offset and limit as query string parameters will return the results in newline-delimited JSON format. offset and limit values can be changed to make multiple requests to obtain the entire result set. Note that the first item returned is a status message with information about the search.
Example curl request:
curl -X GET 'https://main-incredible-swift-abc13ts.cribl.cloud/api/v1/m/default_search/search/jobs/<< JOB ID >>/results' \
--url-query 'offset=0' \
--url-query 'limit=100' \
--header 'accept: application/x-ndjson' \
--header 'Authorization: Bearer << ACCESS TOKEN >>'Example Response:
{"isFinished":true,"limit":100,"offset":0,"persistedEventCount":1000,"totalEventCount":1000,"job":{"id":"1732566655829.Z6s9KD","query":"cribl dataset=\"cribl_search_sample\" | limit 1000","earliest":"-1h","latest":"now","timeCreated":1732566655887,"timeStarted":1732566656017,"timeCompleted":1732566670600,"status":"completed"}}
{"dataset":"cribl_search_sample","_raw":"2 602320997947 eni-0bf22c72ebe087ac9 172.16.2.199 10.0.0.33 1863 53 6 2 1684 1732566565 1732566601 ACCEPT OK","source":"s3://cribl-search-example/data/vpcflowlogs/2024/11/25/20/CriblOut-M3n9p5.1.raw.gz","dataSource":"vpcflowlogs","version":"2","account_id":"602320997947","interface_id":"eni-0bf22c72ebe087ac9","srcaddr":"172.16.2.199","dstaddr":"10.0.0.33","srcport":"1863","dstport":"53","protocol":"6","packets":"2","bytes":"1684","start":"1732566565","end":"1732566601","action":"ACCEPT","log_status":"OK","_time":1732566565,"datatype":"aws_vpcflow"}
{"dataset":"cribl_search_sample","_raw":"2 602320997947 eni-aay7nep03kqbijah0 10.0.0.164 10.8.90.201 5060 3389 6 20 26540 1732566559 1732566573 ACCEPT OK","source":"s3://cribl-search-example/data/vpcflowlogs/2024/11/25/20/CriblOut-DjmRA8.0.raw.gz","dataSource":"vpcflowlogs","version":"2","account_id":"602320997947","interface_id":"eni-aay7nep03kqbijah0","srcaddr":"10.0.0.164","dstaddr":"10.8.90.201","srcport":"5060","dstport":"3389","protocol":"6","packets":"20","bytes":"26540","start":"1732566559","end":"1732566573","action":"ACCEPT","log_status":"OK","_time":1732566559,"datatype":"aws_vpcflow"}
...