Latest Updates: CB ThreatHunter App for Splunk 1.0.0 Released

Process Search API for CB ThreatHunter

WARNING: This is a legacy document, please view the latest version here.

Endpoints

All process searches are asynchronous. This means that in order to get results for some search, you must start a search by calling POST /start and then get results by calling POST /results with query_id as a parameter.

Start

This endpoint starts a process search with the given query parameters.

Request

POST /pscr/query/v2/start

Body Parameters

All body params must live inside of a search_params object.

Parameter Required Default Type Description
q Yes N/A string Solr query to run
cb.min_device_timestamp No 0 int Earliest device timestamp to include in search results
cb.max_device_timestamp No Now int Latest device timestamp to include in search results
cb.min_backend_timestamp No 0 int Earliest backend timestamp to include in search results
cb.max_backend_timestamp No Now int Latest backend timestamp to include in search results
sort No N/A string Solr sort
start No 0 int Solr start for pagination
rows No 500 int Solr rows for pagination
fq No N/A string Solr filter query
timeAllowed No N/A int Solr timeAllowed
facet No N/A bool Solr facets
facet.field No N/A []string Solr facet fields
facet.range No N/A []string Solr fields on which to range facet
facet.range.start No N/A int Solr start time for range faceting
facet.range.end No N/A int Solr end time for range faceting
facet.range.gap No N/A string Solr gap time for range faceting
facet.query No N/A []string Solr query faceting
facet.interval No N/A []string Solr interval faceting
cache No N/A bool Solr caching

start and rows are a bit of a special case here. Since the search is distributed using lucene workers, these parameters apply on a per lucene worker basis. That means the actual number of results could be as many as rows * number_of_workers.

If you supply a sort parameter, the endpoint will default the results’ sort parameters.

For more information on Solr search syntax, check out this page. You can find more information on search here.

Example Request Payload

{
    "search_params": {
        "q": "process_name: chrome.exe"
    }
}

Example Response

This is an example response for a successful /start request.

{
    "message": "Successfully submitted query",
    "query": {
        "cb.index_path_filters": null,
        "cb.org_id": "47979",
        "cb.query_id": "47979/18fcd69d-9391-422d-97b0-6d182f34a1ba",
        "search_params": {
            "cb.max_backend_timestamp": 1533646010000,
            "cb.max_device_timestamp": 1533646010000,
            "cb.min_backend_timestamp": 0,
            "cb.min_device_timestamp": 0,
            "q": "process_name: chrome.exe",
            "rows": 500,
            "start": 0
        }
    },
    "query_id": "47979/18fcd69d-9391-422d-97b0-6d182f34a1ba"
}

Error Response

An error could be caused by a number of things. In general, an error response will have a body like this:

{
    "errorMessage": string,
    "errorType": "errorString"
}

Cancel

This endpoint cancels a search with the given query_id, if that search has not already finished.

HTTP Request

POST /pscr/query/v1/cancel

Body Parameters

Parameter Required Default Description
query_id Yes N/A Query ID to cancel

Example Response

This is an example response for a successful /cancel request.

{
    "query_id": "47979/18fcd69d-9391-422d-97b0-6d182f34a1ba",
    "message": "Successfully cancelled search"
}

Error Response

An error could be caused by a number of things. In general, an error response will have a body like this:

{
    "errorMessage": string,
    "errorType": "errorString"
}

Results

This endpoint retrieves results from the given query_id.

HTTP Request

POST /pscr/query/v1/results

Query Parameters

Parameter Required Default Description
query_id Yes N/A Query ID you received when you started the search to find results for
sort_by No No sort The key in the schema to sort by
sort_direction No ASC The direction to sort
start_row No 0 The start row for pagination over just this result set
row_count No Inf the row count for pagination over just this result set

Retrieving results will be faster if there is no sort requested. In that case, we will simply concatenate the results return them back.

Example Response

This is an example response for a successful /results request.

{
    "query_id": "de555bb8-c75a-4d0e-857f-a8297c43e773",
    "response_header": {
        "num_found": 363554,
        "searchers_meta": {
        "completed": 2,
        "contacted": 0
    },
    "facets": {
        "facet_fields": {}
    },
    "data": [
        {
            "_s3_file": "documents/org=2000000/partition=5/tstamp=1525433/1632af2e36d-6fd80b91-c859-4219-b6f1-b1ec7127405d",
            "_s3_offset": 0,
            "_s3_size": 5680,
            "backend_timestamp": "2018-05-04T11:39:11.085Z",
            "childproc_count": 0,
            "crossproc_count": 0,
            "device_group": "GROUP_3",
            "device_id": 613,
            "device_name": "HOST_613",
            "device_os": "WINDOWS",
            "device_timestamp": "2018-01-01T14:44:57.520Z",
            "document_guid": "00000265-0000-09f2-0000-0160b22ec430-01632af2580b",
            "filemod_count": 9,
            "modload_count": 133,
            "netconn_count": 3,
            "org_id": "2000000",
            "parent_guid": "00000265-0000-0002-0000-0160af049000",
            "parent_name": "C:/Windows/System32/ראשי noemi.exe",
            "parent_pid": 2,
            "process_guid": "00000265-0000-09f2-0000-0160b22ec430",
            "process_hash": [
                "922216c1ced87de8d1bee2f57d4e274e"
            ],
            "process_name": "C:/Windows/System32/sarky somer.exe",
            "process_pid": [
                2546
            ],
            "process_terminated": true,
            "process_username": [
                "llousberg"
            ],
            "regmod_count": 30
        },
        ...
    ],
    "message": "Successfully retrieved results"
}

Error Response

An error could be caused by a number of things. In general, an error response will have a body like this:

{
    "errorMessage": string,
    "errorType": "errorString"
}

Status

This endpoint retrieves the status of a search for the given query_id.

HTTP Request

GET /pscr/query/v1/status

Query Parameters

Parameter Required Default Description
query_id Yes N/A Query ID to find status for

Example Response

This is an example response for a successful /status request.

{
    "completed": 2,
    "contacted": 2
}

Error Response

An error could be caused by a number of things. In general, an error response will have a body like this:

{
    "errorMessage": string,
    "errorType": "errorString"
}

List

This endpoint retrieves a list of all query IDs, both for queries that are in progress and those that have completed.

HTTP Request

GET /pscr/query/v1/list

Query Parameters

None needed

Example Response

This is an example response for a successful /list request.

{
    "query_ids": [
        "04d9d376-f4c3-4ac8-b158-572883ab0ea3",
        "05269fb4-e85f-4091-816a-9e5f80e29ab6",
    ],
    "success": true
}

Error Response

An error could be caused by a number of things. In general, an error response will have a body like this:

{
    "errorMessage": string,
    "errorType": "errorString"
}

Validate

This endpoint determines whether a query is valid.

HTTP Request

GET /pscr/query/v1/validate

Query Parameters

Parameter Required Default Description
q Yes N/A Solr query to validate
start_time No 0 The start time for the query
end_time No Now The end time for the query

Example Response

This is an example response for a successful /validate request.

{
    "valid": false,
    "invalid_trigger_offset": 12,
    "invalid_message": "Something bad happened here"
}

Error Response

An error could be caused by a number of things. In general, an error response will have a body like this:

{
    "errorMessage": string,
    "errorType": "errorString"
}

Validate Events

This endpoint determines whether a complete events query is valid.

HTTP Request

GET /pscr/query/v1/events/validate

Query Parameters

Parameter Required Default Description
q Yes N/A Solr query to validate
start_time No 0 The start time for the query
end_time No Now The end time for the query

Example Response

This is an example response for a successful /events/validate request.

{
    "valid": false,
    "invalid_trigger_offset": 12,
    "invalid_message": "Something bad happened here"
}

Error Response

An error could be caused by a number of things. In general, an error response will have a body like this:

{
    "errorMessage": string,
    "errorType": "errorString"
}

Tree

This endpoint returns data in the tree format for the Process Analysis tree. This endpoint uses complete event data to construct the tree.

HTTP Request

GET /pscr/query/v1/tree

Query Parameters

Parameter Required Default Description
process_guid Yes N/A The process GUID the tree is focused on
parent_guid No None The parent GUID for the currently selected process, if it has a parent

Example Response

This is an example response for a successful /v1/tree request.

{
    "root_node": {
        "process_guid": "something",
        "process_name": "chrome.exe",
        "children: [
            {
                "children": [ /* childproc protobuf data corresponding to the supplied process_guid */ ],
                "childproc_count": 1,
                "crossproc_count": 1,
                "modload_count": 1,
                "filemod_count": 1,
                "netconn_count": 1,
                "process_guid": "something else",
                "process_name": "someProcess.exe"
            },
            {
                /* childproc protobuf data corresponding to the supplied parent_guid */
            }
        ]
    },
    "edges": [] // currently not implemented, will always be empty array
}

Error Response

An error could be caused by a number of things. In general, an error response will have a body like this:

{
    "errorMessage": string,
    "errorType": "errorString"
}

Tree V2

This endpoint returns data in the tree format for the Process Analysis tree. The endpoint uses process information to construct the tree.

HTTP Request

GET /pscr/query/v2/tree

Query Parameters

Parameter Required Default Description
process_guid Yes N/A The process GUID the tree is focused on
parent_guid No None The parent GUID for the currently selected process, if it has a parent

Example Response

This is an example response for a successful /v2/tree request.

{
    "incomplete_results": false,
    "nodes": {
        "children": [
            {
                "backend_timestamp": "2018-09-04T15:30:55.344Z",
                "childproc_count": 403,
                "children": [
                    {
                        "backend_timestamp": "2018-09-04T14:47:10.809Z",
                        "childproc_count": 0,
                        "crossproc_count": 0,
                        "device_group": "GROUP_5",
                        "device_id": 1125,
                        "device_name": "HOST_1125",
                        "device_os": "WINDOWS",
                        "device_timestamp": "2018-01-01T00:09:57.655Z",
                        "document_guid": "00000465-0000-0018-0000-0160af0d9406-0165a50ba1d1",
                        "filemod_count": 1,
                        "kinesis_partition_id": "2000000:5",
                        "modload_count": 0,
                        "netconn_count": 3,
                        "org_id": "2000000",
                        "org_size_perc": 100,
                        "parent_guid": "00000465-0000-0002-0000-0160af049000",
                        "parent_path": "C:/runed leslie/acidic kora/ptotic allen.exe",
                        "parent_pid": 2,
                        "partition_id": 5,
                        "process_guid": "00000465-0000-0018-0000-0160af0d9406",
                        "process_hash": [
                        "52cf880fa3819f2ceaa2004dd1476f55"
                        ],
                        "process_path": "C:/Windows/System32/geodic jimena.exe",
                        "process_pid": [
                        24
                        ],
                        "process_terminated": false,
                        "process_username": [
                        "bmunsen"
                        ],
                        "regmod_count": 0,
                        "segment_id": 1536072327633
                    },
                    {
                        "backend_timestamp": "2018-09-04T14:47:10.809Z",
                        "childproc_count": 0,
                        "crossproc_count": 0,
                        "device_group": "GROUP_5",
                        "device_id": 1125,
                        "device_name": "HOST_1125",
                        "device_os": "WINDOWS",
                        "device_timestamp": "2018-01-01T00:09:58.439Z",
                        "document_guid": "00000465-0000-000c-0000-0160af0a8904-0165a50ba17a",
                        "filemod_count": 9,
                        "kinesis_partition_id": "2000000:5",
                        "modload_count": 109,
                        "netconn_count": 3,
                        "org_id": "2000000",
                        "org_size_perc": 100,
                        "parent_guid": "00000465-0000-0002-0000-0160af049000",
                        "parent_path": "C:/runed leslie/acidic kora/ptotic allen.exe",
                        "parent_pid": 2,
                        "partition_id": 5,
                        "process_guid": "00000465-0000-000c-0000-0160af0a8904",
                        "process_hash": [
                        "b81c9fe32ef5b75c3446df7f2b4a6d23"
                        ],
                        "process_path": "C:/Filter20Percent/hilly dax.exe",
                        "process_pid": [
                        12
                        ],
                        "process_terminated": false,
                        "process_username": [
                        "bmunsen"
                        ],
                        "regmod_count": 24,
                        "segment_id": 1536072327546
                    }
                ],
                "crossproc_count": 0,
                "device_group": "GROUP_5",
                "device_id": 1125,
                "device_name": "HOST_1125",
                "device_os": "WINDOWS",
                "device_timestamp": "2018-01-01T00:29:51.972Z",
                "document_guid": "00000465-0000-0002-0000-0160af049000-0165a533d991",
                "filemod_count": 0,
                "kinesis_partition_id": "2000000:5",
                "modload_count": 0,
                "netconn_count": 0,
                "org_id": "2000000",
                "org_size_perc": 100,
                "parent_guid": "00000465-0000-0001-0000-0160af049000",
                "parent_path": "C:/Filter20Percent/calced उपलब्ध.exe",
                "parent_pid": 1,
                "partition_id": 5,
                "process_cmdline": [
                "C:\\Windows\\Θαθιων evon.exe",
                "C:\\Windows\\System32\\nitric kate.exe",
                "C:\\Windows\\burry verdie.exe",
                "C:\\Windows\\fluffy marina.exe",
                "C:\\Windows\\Μαζιμ louisa.exe",
                "C:\\Windows\\System32\\חופשית tiesha.exe",
                "C:\\joyous louis\\الأجل mandi\\ropier maude\\lytic leonel\\سياسة kamari\\surest camilo.exe",
                "C:\\Windows\\verus विभाग\\gnarly manda.exe",
                "C:\\Windows\\System32\\craggy lanie\\beechy nettie\\pyoid mya\\brashy सभिसमज.exe",
                "C:\\Windows\\γραεσω leah\\armed बाटते\\brut lino.exe",
                "C:\\Windows\\System32\\כלשהו, rossie.exe",
                "C:\\lofty chuck\\gooey rickey\\sandy belia.exe",
                "C:\\jiggly ciara.exe",
                "C:\\Filter20Percent\\cagier shanon\\بوابة. dorian.exe",
                "C:\\Windows\\System32\\Εξερσι corine.exe",
                "C:\\Windows\\System32\\anomic जिम्मे\\Σιμυλ daina\\syrupy dana\\corny flo.exe",
                "C:\\Windows\\System32\\elvish tomas\\backed rima\\downy brant\\בגרסה. flynn.exe",
                "C:\\Filter20Percent\\blae प्रति.exe",
                "C:\\Windows\\barbed arleen\\ويعزى, reta.exe",
                "C:\\winded elicia\\wiry ruby\\verus heath\\تطوير lonna\\undewy andre\\gory velda\\dorsal sharon.exe",
                "C:\\Windows\\finger betsy\\מיזמי randee.exe",
                "C:\\Windows\\התוכן, valrie\\סדר. arnold.exe"
                ],
                "process_guid": "00000465-0000-0002-0000-0160af049000",
                "process_hash": [
                "51271939c5a02b88f5e5c91f7ad4244f"
                ],
                "process_path": "C:/runed leslie/acidic kora/ptotic allen.exe",
                "process_pid": [
                2
                ],
                "process_terminated": false,
                "process_username": [
                "bmunsen"
                ],
                "regmod_count": 0,
                "segment_id": 1536074963345
            }
        ]
    }
}

Error Response

An error could be caused by a number of things. In general, an error response will have a body like this:

{
    "errorMessage": string,
    "errorType": "errorString"
}

Suggest

This endpoint returns suggestions based on a query. It only operates on one term in a query at a time and will not work if you pass in a complex query with multiple conditions. If the term does not contain a semicolon yet, this endpoint will return suggestions for indexed field names. If the term contains a semicolon, this endpoint will suggest values for the given field name.

HTTP Request

GET /pscr/query/v1/suggest

Query Parameters

Parameter Required Default Description
suggest.q Yes N/A The query to suggest on
suggest.count No 50 The parent GUID for the currently selected process, if it has a parent

Example Response

This is an example response for a successful /suggest request.

{
    "suggestions": [
        { "term": "hi", "weight": 12 },
        { "term": "high", "weight": 9 }
    ]
}

Error Response

An error could be caused by a number of things. In general, an error response will have a body like this:

{
    "errorMessage": string,
    "errorType": "errorString"
}

Suggest Events

This endpoint returns suggestions for event queries based on a supplied query. It only operates on one term in a query at a time and will not work if you pass in a complex query with multiple conditions. If the term does not contain a semicolon yet, this endpoint will return suggestions for indexed field names. If the term contains a semicolon, this endpoint will suggest values for the given field name.

HTTP Request

GET /pscr/query/v1/events/suggest

Query Parameters

Parameter Required Default Description
suggest.q Yes N/A The query to suggest on
suggest.count No 50 The parent GUID for the currently selected process, if it has a parent

Example Response

This is an example response for a successful /suggest request.

{
    "suggestions": [
        { "term": "hi", "weight": 12 },
        { "term": "high", "weight": 9 }
    ]
}

Error Response

An error could be caused by a number of things. In general, an error response will have a body like this:

{
    "errorMessage": string,
    "errorType": "errorString"
}

Limits

This endpoint returns the times for the earliest and latest events in the Organization’s events.

HTTP Request

GET /pscr/query/v1/limits

Query Parameters

None

Example Response

This is an example response for a successful /limits request.

{
    "time_bounds": {
        "lower": 0,
        "upper": 10
    }
}

Error Response

An error could be caused by a number of things. In general, an error response will have a body like this:

{
    "errorMessage": string,
    "errorType": "errorString"
}

Report Hits

This endpoint returns all the report hits for a given process_guid, where report hits are instances where a report triggered an alert on the given process.

HTTP Request

GET /pscr/query/v1/report_hits

Query Parameters

Parameter Required Default Description
process_guid Yes N/A The process guid for which to request report hit info

Example Response

This is an example of a response to a successful /report_hits request.

{
    "report_hits": [
        {
            "f24fb2d6-0cc6-4190-a476-ab461f11a1de":{
                "iocs_id":"query_calc_ioc",
                "report_id":"report3",
                "report_score":75,
                "hit_segment_ids":[
                    1531141163366,
                    1531141094783,
                    1531140968977,
                    1531141028370
                ],
                "report_timestamp":"1970-01-01T00:00:00.000Z",
                "report_link":"https://test.feed.com/report3"
            }
        }
    ]
}

Error Response

An error could be caused by a number of things. In general, an error response will have a body like this:

{
    "errorMessage": string,
    "errorType": "errorString"
}

Export

This endpoint requests results for the given query_id and returns them in CSV format.

HTTP Request

GET /pscr/query/v1/export

Query Parameters

Parameter Required Default Description
query_id Yes N/A Query ID for which to request results
sort_by No No sort The key in the schema to sort by
sort_direction No ASC The direction in which to sort, either ASC for ascending or DESC for descending
start_row No 0 The start row for pagination over just this result set
row_count No Inf the row count for pagination over just this result set

Retrieving results will be faster if there is no sort requested. In that case, the endpoint will simply concatenate the returned results.

Example Response

This is an example response for a successful /export request.

{
    "query_id": "de555bb8-c75a-4d0e-857f-a8297c43e773",
    "data": "CSV here"
}

Error Response

An error could be caused by a number of things. In general, an error response will have a body like this:

{
    "errorMessage": string,
    "errorType": "errorString"
}

Events

This endpoint returns detailed data for a search across event records. While the /events results are similar to /start endpoint results, the main difference is that /events returns more detailed data than /start, including details about netconns, regmods, crossprocs, childprocs and filemods. This endpoint is also synchronous.

Request

POST /pscr/query/v1/events

Body Parameters

All body params must live inside of a search_params object.

Parameter Required Default Type Description
q Yes N/A string Solr query to run, must contain a term for process_guid
cb.process_guid Yes N/A string The process GUID to match complete events on
cb.min_device_timestamp No 0 int Earliest device timestamp to include in search results
cb.max_device_timestamp No Now int Latest device timestamp to include in search results
cb.min_backend_timestamp No 0 int Earliest backend timestamp to include in search results
cb.max_backend_timestamp No Now int Latest backend timestamp to include in search results
cb.start_row No 0 int The start row used for pagination
cb.row_count No 500 int The number of rows to return used for pagination
sort No N/A string Solr sort
start No 0 int Solr start for pagination
rows No 500 int Solr rows for pagination
fq No N/A string Solr filter query
timeAllowed No N/A int Solr timeAllowed
facet No N/A bool Solr facets
facet.field No N/A []string Solr facet fields
facet.range No N/A []string Solr fields on which to range facet
facet.range.start No N/A int Solr start time for range faceting
facet.range.end No N/A int Solr end time for range faceting
facet.range.gap No N/A string Solr gap time for range faceting
facet.query No N/A []string Solr query faceting
facet.interval No N/A []string Solr interval faceting
cache No N/A bool Solr caching

start and rows are a bit of a special case here. Since the search is distributed using lucene workers, these parameters apply on a per lucene worker basis. That means the actual number of results could be as many as rows * number_of_workers.

If you supply a sort parameter, we will default the results’ sort parameters to what was specified here.

For more information on Solr search syntax, check out this page. You can find more information on search here.

Example Request Payload

{
    "search_params": {
        "q": "process_guid:5 AND event_type:netconn",
        "cb.process_guid": "5",
        "cb.start_row": 10,
        "cb.row_count": 100,
    }
}

Example Response

This is an example response for a successful /events request.

{
    "response_header": {
        "num_found": 1
    },
    "docs": [
        {
            "backend_timestamp": "2018-08-03T14:38:29.493Z", 
            "created_timestamp": "2018-08-14T16:51:16.113Z", 
            "event_guid": "688c3678-d112-42c6-9a23-676ffdfad290", 
            "event_timestamp": "2018-08-03T14:08:08.915Z", 
            "event_type": "modload", 
            "modload_md5": "8e6958813b6faaff8a6ee9f2a7040299", 
            "modload_name": "c:\\windows\\syswow64\\mswsock.dll", 
            "modload_sha256": "175930d44d23013b40848b0c3748595991b3d96c72cdad7d71b204207aa44e3b", 
            "process_guid": "47979-0002e939-00000cf0-00000000-1d42b335b36601e"
        }
    ],
    "facet_counts": {
        facet_fields: {
            event_type: {
                "modload": 1
            }
        }
    }
}

Error Response

An error could be caused by a number of things. In general, an error response will have a body like this:

{
    "errorMessage": string,
    "errorType": "errorString"
}

Evaluate

This endpoint adds tags to documents that are appropriate to the watchlist/report/IOC.

Request

POST /pscr/query/v1/evaluate

Body Parameters

Parameter Required Default Type Description
watchlist_id Yes N/A string The watchlist id to evaluate
report_id Yes N/A string The report id to evaluate
ioc_id No N/A string the IOC id to evaluate
cb.min_backend_timestamp No 0 int The start time for the evaluation
cb.max_backend_timestamp No Now int The end time for the evaluation

Example Response

A successful response will have empty body.

Error Response

An error could be caused by a number of things. In general, an error response will have a body like this:

{
    "errorMessage": string,
    "errorType": "errorString"
}
Last modified on December 7, 2018