This article aims to provide pointers on how to utilize the Cribl.Cloud API to perform Cribl Search queries in a systematic manner. This can be used 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. To do this, you must generate a Client ID and a Client Secret.
This can be done on the Cribl.Cloud console's Organization page. 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
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 the following:
{
"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
Two separate endpoints are used to create searches and obtain results. The first endpoint will create the search, which will look something like https://main-incredible-swift-abc13ts.cribl.cloud/api/v1/m/default_search/search/jobs
.
The payload body sent 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 its ID, which is 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
To retrieve the result set, we must wait for the search to complete. 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 job's status 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"}
...