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.
This endpoint starts a process search with the given query parameters.
POST /pscr/query/v2/start
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.
{
"search_params": {
"q": "process_name: chrome.exe"
}
}
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"
}
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"
}
This endpoint cancels a search with the given query_id, if that search has not already finished.
POST /pscr/query/v1/cancel
| Parameter | Required | Default | Description |
|---|---|---|---|
| query_id | Yes | N/A | Query ID to cancel |
This is an example response for a successful /cancel request.
{
"query_id": "47979/18fcd69d-9391-422d-97b0-6d182f34a1ba",
"message": "Successfully cancelled search"
}
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"
}
This endpoint retrieves results from the given query_id.
POST /pscr/query/v1/results
| 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.
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"
}
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"
}
This endpoint retrieves the status of a search for the given query_id.
GET /pscr/query/v1/status
| Parameter | Required | Default | Description |
|---|---|---|---|
| query_id | Yes | N/A | Query ID to find status for |
This is an example response for a successful /status request.
{
"completed": 2,
"contacted": 2
}
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"
}
This endpoint retrieves a list of all query IDs, both for queries that are in progress and those that have completed.
GET /pscr/query/v1/list
None needed
This is an example response for a successful /list request.
{
"query_ids": [
"04d9d376-f4c3-4ac8-b158-572883ab0ea3",
"05269fb4-e85f-4091-816a-9e5f80e29ab6",
],
"success": true
}
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"
}
This endpoint determines whether a query is valid.
GET /pscr/query/v1/validate
| 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 |
This is an example response for a successful /validate request.
{
"valid": false,
"invalid_trigger_offset": 12,
"invalid_message": "Something bad happened here"
}
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"
}
This endpoint determines whether a complete events query is valid.
GET /pscr/query/v1/events/validate
| 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 |
This is an example response for a successful /events/validate request.
{
"valid": false,
"invalid_trigger_offset": 12,
"invalid_message": "Something bad happened here"
}
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"
}
This endpoint returns data in the tree format for the Process Analysis tree. This endpoint uses complete event data to construct the tree.
GET /pscr/query/v1/tree
| 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 |
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
}
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"
}
This endpoint returns data in the tree format for the Process Analysis tree. The endpoint uses process information to construct the tree.
GET /pscr/query/v2/tree
| 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 |
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
}
]
}
}
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"
}
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.
GET /pscr/query/v1/suggest
| 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 |
This is an example response for a successful /suggest request.
{
"suggestions": [
{ "term": "hi", "weight": 12 },
{ "term": "high", "weight": 9 }
]
}
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"
}
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.
GET /pscr/query/v1/events/suggest
| 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 |
This is an example response for a successful /suggest request.
{
"suggestions": [
{ "term": "hi", "weight": 12 },
{ "term": "high", "weight": 9 }
]
}
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"
}
This endpoint returns the times for the earliest and latest events in the Organization’s events.
GET /pscr/query/v1/limits
None
This is an example response for a successful /limits request.
{
"time_bounds": {
"lower": 0,
"upper": 10
}
}
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"
}
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.
GET /pscr/query/v1/report_hits
| Parameter | Required | Default | Description |
|---|---|---|---|
| process_guid | Yes | N/A | The process guid for which to request report hit info |
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"
}
}
]
}
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"
}
This endpoint requests results for the given query_id and returns them in CSV format.
GET /pscr/query/v1/export
| 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.
This is an example response for a successful /export request.
{
"query_id": "de555bb8-c75a-4d0e-857f-a8297c43e773",
"data": "CSV here"
}
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"
}
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.
POST /pscr/query/v1/events
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.
{
"search_params": {
"q": "process_guid:5 AND event_type:netconn",
"cb.process_guid": "5",
"cb.start_row": 10,
"cb.row_count": 100,
}
}
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
}
}
}
}
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"
}
This endpoint adds tags to documents that are appropriate to the watchlist/report/IOC.
POST /pscr/query/v1/evaluate
| 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 |
A successful response will have empty body.
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"
}