Help us improve your experience.

Let us know what you think.

Do you have time for a two-minute survey?

 

Forensics Endpoints

 

Use the references for REST API V8.0 forensics endpoints.

GET /forensics/capture/recoveries

Retrieves a list of capture recoveries.

Retrieves a list of recoveries.

Table 1: GET /forensics/capture/recoveries Resource Details

MIME Type

application/json

Table 2: GET /forensics/capture/recoveries Request Parameter Details

Parameter

Type

Optionality

Data Type

MIME Type

Description

Range

header

Optional

String

text/plain

Optional - Use this parameter to restrict the number of elements that are returned in the list to a specified range. The list is indexed starting at zero.

filter

query

Optional

String

text/plain

Optional - This parameter is used to restrict the elements in a list base on the contents of various fields.

fields

query

Optional

String

text/plain

Optional - Use this parameter to specify which fields you would like to get back in the response. Fields that are not named are excluded. Specify subfields in brackets and multiple fields in the same object are separated by commas.

Table 3: GET /forensics/capture/recoveries Response Codes

HTTP Response Code

Unique Code

Description

200

 

The Workflow Recovery Jobs were retrieved.

500

1020

An error occurred while the recovery job list was being retrieved.

Response Description

A list of recoveries. A recovery contains the following fields:

  • assigned_to - String - The username of the user the recovery is assigned to.

  • bpf - String - The Berkeley Packet Filter to pass to the capture device.

  • case_id - String - ID of the case where the collection(s) are created.

  • collection_name_suffix - String - Suffix that is used to name the collection(s) to store the recovered data in.

  • id - Long - ID for the recovery.

  • recovery_task_ids - Long Array - IDs for all recovery tasks belonging to this recovery.

  • recovery_window_end_time - Long - End of time range for data recovery.

  • recovery_window_start_time - Long - Start of time range for data recovery.

  • tags - String - Identifiers applied to recovered data to assist with grouping when searching. These are user supplied string identifiers that are used to mark the data so the user can easily look up the data later.

Response Sample

[ { "assigned_to": "String", "bpf": "String", "case_id": 42, "collection_name_suffix": "String", "id": 42, "recovery_task_ids": [ 42 ], "recovery_window_end_time": 42, "recovery_window_start_time": 42, "session_ids": [ "String" ], "tags": [ "String" ] } ]

POST /forensics/capture/recoveries

Creates a new capture recovery.

Creates a new recovery.

Table 4: POST /forensics/capture/recoveries Resource Details

MIME Type

application/json

Table 5: POST /forensics/capture/recoveries Request Parameter Details

Parameter

Type

Optionality

Data Type

MIME Type

Description

fields

header

Optional

String

text/plain

Optional - Use this parameter to specify which fields you would like to get back in the response. Fields that are not named are excluded. Specify subfields in brackets and multiple fields in the same object are separated by commas.

Table 6: POST /forensics/capture/recoveries Request Body Details

Parameter

Data Type

MIME Type

Description

Sample

recovery

Object

application/json

null

{ "assigned_to": "String", "bpf": "String", "case_id": 42, "collection_name_suffix": "String", "recovery_window_end_time": 42, "recovery_window_start_time": 42, "session_ids": [ "String" ], "tags": [ "String" ] }

Table 7: POST /forensics/capture/recoveries Response Codes

HTTP Response Code

Unique Code

Description

201

 

The workflow recovery job was created.

403

1009

The user or targeted user does not have the capability to perform this request.

409

1000

null

422

1005

A request parameter is not valid.

500

1020

An error occurred during the creation of the recovery job.

Response Description

The newly created recovery that contains the following fields:

  • assigned_to - String - The username of the user the recovery is assigned to. If not supplied the recovery will be assigned to the user making the request. Requires a valid user with Forensics role. Not an authorized service.

  • bpf - String - The Berkeley Packet Filter to pass to the capture device. A simplified Berkley Packet Filter expression to pass to the capture device to apply when recovering network data. Maximum length is 250 characters

  • case_id - String - ID of the case where the collection(s) are created.

  • collection_name_suffix - String - Suffix that is used to name the collection(s) to store the recovered data in. Collection name(s) for recovery tasks are derived from this value and capture devices where network data originates as a recovery task is created for each device. (e.g. A collection name suffix of "mycollection" and data recovered from capture device IP "10.0.0.2" results in a collection that is named "10.0.0.2_mycollection"). NOTE: If the collection name already exists in the case the existing collection is deleted. Maximum length is 100 characters. Alphanumeric and period characters are permitted only.

  • id - Long - ID for the recovery.

  • recovery_task_ids - Long Array - IDs for all recovery tasks belonging to this recovery.

  • recovery_window_end_time - Long - End of time range for data recovery.

  • recovery_window_start_time - Long - Start of time range for data recovery.

  • tags - String - Identifiers applied to recovered data to assist with grouping when searching. These are user supplied string identifiers that are used to mark the data so the user can easily look up the data later. Maximum length 255 alphanumeric characters (all values converted to space separated string)

Response Sample

{ "assigned_to": "String", "bpf": "String", "case_id": 42, "collection_name_suffix": "String", "id": 42, "recovery_task_ids": [ 42 ], "recovery_window_end_time": 42, "recovery_window_start_time": 42, "session_ids": [ "String" ], "tags": [ "String" ] }

GET /forensics/capture/recoveries/{id}

Retrieves a recovery based on the supplied ID.

Retrieves a recovery based on the supplied ID.

Table 8: GET /forensics/capture/recoveries/{id} Resource Details

MIME Type

application/json

Table 9: GET /forensics/capture/recoveries/{id} Request Parameter Details

Parameter

Type

Optionality

Data Type

MIME Type

Description

id

path

Required

Number (Integer)

text/plain

Required - The ID of the workflow job to retrieve.

fields

query

Optional

String

text/plain

Optional - Use this parameter to specify which fields you would like to get back in the response. Fields that are not named are excluded. Specify subfields in brackets and multiple fields in the same object are separated by commas.

Table 10: GET /forensics/capture/recoveries/{id} Response Codes

HTTP Response Code

Unique Code

Description

404

1002

No recovery job was found for the provided ID.

500

1020

An error occurred during the retrieval of the recovery job.

Response Description

A recovery that contains the following fields:

  • assigned_to - String - The username of the user the recovery is assigned to.

  • bpf - String - The Berkeley Packet Filter to pass to the capture device.

  • case_id - String - ID of the case where the collection(s) are created.

  • collection_name_suffix - String - Suffix that is used to name the collection(s) to store the recovered data in.

  • id - Long - ID for the recovery.

  • recovery_task_ids - Long Array - IDs for all recovery tasks belonging to this recovery.

  • recovery_window_end_time - Long - End of time range for data recovery.

  • recovery_window_start_time - Long - Start of time range for data recovery.

  • tags - String - Identifiers applied to recovered data to assist with grouping when searching. These are user supplied string identifiers that are used to mark the data so the user can easily look up the data later.

Response Sample

{ "assigned_to": "String", "bpf": "String", "case_id": 42, "collection_name_suffix": "String", "id": 42, "recovery_task_ids": [ 42 ], "recovery_window_end_time": 42, "recovery_window_start_time": 42, "session_ids": [ "String" ], "tags": [ "String" ] }

GET /forensics/capture/recovery_tasks

Retrieves a list of recovery tasks.

Retrieves a list of recovery tasks.

Table 11: GET /forensics/capture/recovery_tasks Resource Details

MIME Type

application/json

Table 12: GET /forensics/capture/recovery_tasks Request Parameter Details

Parameter

Type

Optionality

Data Type

MIME Type

Description

Range

header

Optional

String

text/plain

Optional - Use this parameter to restrict the number of elements that are returned in the list to a specified range. The list is indexed starting at zero.

filter

query

Optional

String

text/plain

Optional - This parameter is used to restrict the elements in a list base on the contents of various fields.

fields

query

Optional

String

text/plain

Optional - Use this parameter to specify which fields you would like to get back in the response. Fields that are not named are excluded. Specify subfields in brackets and multiple fields in the same object are separated by commas.

Table 13: GET /forensics/capture/recovery_tasks Response Codes

HTTP Response Code

Unique Code

Description

200

 

The workflow recovery job tasks were retrieved.

500

1020

An error occurred while the recovery job task list was being retrieved.

Response Description

A list of recovery tasks. A recovery task contains the following fields:

  • assigned_to - String - The username of the user the recovery task is assigned to.

  • bpf - String - Berkeley Packet Filter sent to capture device when recovering.

  • capture_device_id - String - Capture device where this task collected its data. The IP address of the capture device at time of recovery.

  • case_id - String - ID of case where the collection is created.

  • collection_name - String - Name of collection where recovered data is stored. Derived from device recovery collection name suffix. NOTE: This is used as part of the collection_name to uniquely identify and index the data at time of recovery and is not updated if the capture device IP address is changed.

  • id - Long - ID for the recovery task.

  • managed_host_hostname - String - The managed host the recovery task is running on.

  • recovery_id - Long - ID of the recovery this task belongs to.

  • recovery_window_end_time - Long - End of time range for data recovery window sent to capture device. Data recovered is from before this time.

  • recovery_window_start_time - Long - Start of time range for data recovery window sent to capture device. Data recovered is from after this time.

  • status - String - Current status of this task. Possible values are:

    • CANCELED - Recovery from capture device canceled. Any documents recovered before cancellation remain in the system.

    • CANCELLING - Recovery from capture device in process of cancellation

    • FAILED - Something went wrong with the recovery.

    • IN_PROGRESS - The capture device is processing the recovery.

    • NEW - The recovery task was created and is waiting to be picked up by the system.

    • PENDING - The recovery task was picked up by the system and is waiting for the capture device to start processing the recovery.

    • SUCCESS - Recovery from capture device successfully completed

  • tags - String Array - Identifiers that are applied to recovered data to assist with grouping when searching. These are user-supplied string identifiers that are used to mark the data so the user can easily look up the data later.

  • task_end_time - Long - Timestamp the recovery task completed.

  • task_start_time - Long - Timestamp the recovery task started.

Response Sample

[ { "assignee": "String", "bpf": "String", "capture_device_ip": "String", "case_id": 42, "collection_name": "String", "id": 42, "managed_host_hostname": "String", "recovery_id": 42, "recovery_window_end_time": 42, "recovery_window_start_time": 42, "status": "String <one of: CANCELED, CANCELING, FAILED, IN_PROGRESS, NEW, PENDING, SUCCESS>", "tags": [ "String" ], "task_end_time": 42, "task_start_time": 42 } ]

GET /forensics/capture/recovery_tasks/{id}

Retrieves a recovery task based on the supplied ID.

Retrieves a recovery task based on the supplied ID.

Table 14: GET /forensics/capture/recovery_tasks/{id} Resource Details

MIME Type

application/json

Table 15: GET /forensics/capture/recovery_tasks/{id} Request Parameter Details

Parameter

Type

Optionality

Data Type

MIME Type

Description

id

path

Required

Number (Integer)

text/plain

Required - The ID of the workflow job to retrieve.

fields

query

Optional

String

text/plain

Optional - Use this parameter to specify which fields you would like to get back in the response. Fields that are not named are excluded. Specify subfields in brackets and multiple fields in the same object are separated by commas.

Table 16: GET /forensics/capture/recovery_tasks/{id} Response Codes

HTTP Response Code

Unique Code

Description

200

 

The Workflow Recovery Job was retrieved.

404

1002

No recovery job was found for the provided ID.

500

1020

An error occurred while the recovery job was being retrieved.

Response Description

A recovery task containing the following fields:

  • assigned_to - String - The username of the user the recovery task is assigned to.

  • bpf - String - Berkeley Packet Filter sent to capture device when recovering.

  • capture_device_id - String - Capture device where this task collected its data. The IP address of the capture device at time of recovery.

  • case_id - String - Id of case where the collection is created.

  • collection_name - String - Name of collection where recovered data is stored. Derived from device recovery collection name suffix. NOTE: This is used as part of the collection_name to uniquely identify and index the data at time of recovery and is not updated if the capture device ip address is changed.

  • id - Long - ID for the recovery task.

  • managed_host_hostname - String - The managed host where the recovery task runs.

  • recovery_id - Long - ID of the recovery this task belongs to.

  • recovery_window_end_time - Long - End of time range for data recovery window sent to capture device. Data recovered is from before this time.

  • recovery_window_start_time - Long - Start of time range for data recovery window sent to capture device. Data recovered is from after this time.

  • status - String - Current status of this task. Possible values are:

    • CANCELED - Recovery from capture device canceled. Any documents recovered before cancellation remain in the system.

    • CANCELLING - Recovery from capture device in process of cancellation.

    • FAILED - Something went wrong with the recovery.

    • IN_PROGRESS - The capture device is processing the recovery.

    • NEW - The recovery task was created and is waiting to be picked up by the system.

    • PENDING - The recovery task was picked up by the system and is waiting for the capture device to start processing the recovery.

    • SUCCESS - Recovery from capture device successfully completed

  • tags - String Array - Identifiers that are applied to recovered data to assist with grouping when searching. These are user-supplied string identifiers that are used to mark the data so the user can easily look up the data later.

  • task_end_time - Long - Timestamp the recovery task completed.

  • task_start_time - Long - Timestamp the recovery task started.

Response Sample

{ "assignee": "String", "bpf": "String", "capture_device_ip": "String", "case_id": 42, "collection_name": "String", "id": 42, "managed_host_hostname": "String", "recovery_id": 42, "recovery_window_end_time": 42, "recovery_window_start_time": 42, "status": "String <one of: CANCELED, CANCELING, FAILED, IN_PROGRESS, NEW, PENDING, SUCCESS>", "tags": [ "String" ], "task_end_time": 42, "task_start_time": 42 }

GET /forensics/case_management/case_create_tasks/{id}

Retrieves a case create task based on the supplied id.

Retrieves a case create task based on the supplied id.

Table 17: GET /forensics/case_management/case_create_tasks/{id} Resource Details

MIME Type

application/json

Table 18: GET /forensics/case_management/case_create_tasks/{id} Request Parameter Details

Parameter

Type

Optionality

Data Type

MIME Type

Description

id

path

Required

Number (Integer)

text/plain

Required - The id of the case create task to retrieve.

fields

query

Optional

String

text/plain

Optional - Use this parameter to specify which fields you would like to get back in the response. Fields that are not named are excluded. Specify subfields in brackets and multiple fields in the same object are separated by commas.

Table 19: GET /forensics/case_management/case_create_tasks/{id} Response Codes

HTTP Response Code

Unique Code

Description

200

 

The case create task was retrieved.

404

1002

No case create task was found for the provided ID.

500

1020

An error occurred during the retrieval of the case create task.

Response Description

A case create task containing the following fields:

  • assigned_to - String Array - Usernames of users to give access to the case once it is created. Users must have the FORENSICS role. Authorized services are not allowed.

  • case_id - Long - ID for the created case .

  • case_name - String - Name to give the created case.

  • id - Long - ID for the case create task.

  • status - String - Possible values are:

    • COMPLETE - The case has been created across all managed hosts.

    • PARTIALLY_COMPLETE - The case was created on at least one managed host, but not all of them. The case is considered to be usable, but functionality might be limited. This usually means one or more managed hosts are down and the case is not created yet. The task completes after all offending managed hosts either complete the task, or are removed from the deployment.

    • PROCESSING - The task has been picked up by QRadar and is actively being processed. Cases are being created on the managed hosts.

    • WAITING - The task is waiting for its time to be processed. Nothing is being done at this time.

Response Sample

{ "assigned_to": [ "String" ], "case_id": 42, "id": 42, "name": "String", "state": "String <one of: COMPLETE, PARTIALLY_COMPLETE, PROCESSING, WAITING>" }

GET /forensics/case_management/cases

Retrieves a list of cases.

Retrieves a list of cases.

Table 20: GET /forensics/case_management/cases Resource Details

MIME Type

application/json

Table 21: GET /forensics/case_management/cases Request Parameter Details

Parameter

Type

Optionality

Data Type

MIME Type

Description

Range

header

Optional

String

text/plain

Optional - Use this parameter to restrict the number of elements that are returned in the list to a specified range. The list is indexed starting at zero.

filter

query

Optional

String

text/plain

Optional - This parameter is used to restrict the elements in a list base on the contents of various fields.

fields

query

Optional

String

text/plain

Optional - Use this parameter to specify which fields you would like to get back in the response. Fields that are not named are excluded. Specify subfields in brackets and multiple fields in the same object are separated by commas.

Table 22: GET /forensics/case_management/cases Response Codes

HTTP Response Code

Unique Code

Description

200

 

The cases were retrieved.

500

1020

An error occurred during the retrieval of the case list.

Response Description

A list of cases. A case contains the following fields:

  • assigned_to - String Array - Usernames of the users who have access to the case. Users must have the FORENSICS role. Authorized services are not allowed.

  • id - Long - ID for the case.

  • name - String - The name of the case.

Response Sample

[ { "assigned_to": [ "String" ], "id": 42, "name": "String" } ]

POST /forensics/case_management/cases

Creates a new case.

Creates a new case.

Table 23: POST /forensics/case_management/cases Resource Details

MIME Type

application/json

Table 24: POST /forensics/case_management/cases Request Parameter Details

Parameter

Type

Optionality

Data Type

MIME Type

Description

fields

header

Optional

String

text/plain

Optional - Use this parameter to specify which fields you would like to get back in the response. Fields that are not named are excluded. Specify subfields in brackets and multiple fields in the same object are separated by commas.

Table 25: POST /forensics/case_management/cases Request Body Details

Parameter

Data Type

MIME Type

Description

Sample

case

Object

application/json

null

{ "assigned_to": [ "String" ], "name": "String" }

Table 26: POST /forensics/case_management/cases Response Codes

HTTP Response Code

Unique Code

Description

201

 

The case was created.

403

1009

The user or targeted user does not have the capability to perform this request.

422

1005

A request parameter is not valid.

500

1020

An error occurred during the creation of the case.

Response Description

The case create status contains the following fields:

  • assigned_to - String Array - Usernames of users to give access to the case once it is created. Users must have the FORENSICS role. Authorized services are not allowed. If the case is not assign to anyone, it is assigned to the creator if they are a user (not authorized service). Otherwise, it is only accessible by an administrator. NOTE: During creation the assigned_to list can contain at most one username.

  • case_id - Long - ID for the created case.

  • case_name - String - Name to give the created case. The case name must include alphanumeric characters only, and be 1-15 characters long with no spaces. Case names are unique.

  • id - Long - ID for the case create task.

  • status - String - Possible values are:

    • COMPLETE - The case has been created across all managed hosts.

    • PARTIALLY_COMPLETE - The case has been created on at least one managed host, but not all of them. The case is considered to be usable, but functionality might be limited. This usually means one or more managed hosts are down and the case is not created yet. The task completes after all offending managed hosts either complete the task or are removed from the deployment.

    • PROCESSING - The task was picked up by QRadar and is actively being processed. Cases are being created on the managed hosts.

    • WAITING - The task is waiting for its time to be processed. Nothing is being done at this time.

Response Sample

{ "assigned_to": [ "String" ], "case_id": 42, "id": 42, "name": "String", "state": "String <one of: COMPLETE, PARTIALLY_COMPLETE, PROCESSING, WAITING>" }

GET /forensics/case_management/cases/{id}

Retrieves a case based on the supplied id.

Retrieves a case based on the supplied ID.

Table 27: GET /forensics/case_management/cases/{id} Resource Details

MIME Type

application/json

Table 28: GET /forensics/case_management/cases/{id} Request Parameter Details

Parameter

Type

Optionality

Data Type

MIME Type

Description

id

path

Required

Number (Integer)

text/plain

Required - The ID of the workflow job to retrieve.

fields

query

Optional

String

text/plain

Optional - Use this parameter to specify which fields you would like to get back in the response. Fields that are not named are excluded. Specify subfields in brackets and multiple fields in the same object are separated by commas.

Table 29: GET /forensics/case_management/cases/{id} Response Codes

HTTP Response Code

Unique Code

Description

404

1002

No case was found for the provided ID.

500

1020

An error occurred during the retrieval of the case.

Response Description

A case that contains the following fields:

  • assigned_to - String Array - Usernames of the users who have access to the case. Users must have the FORENSICS role. Authorized services are not allowed.

  • id - Long - ID for the case.

  • name - String - The name of the case.

Response Sample

{ "assigned_to": [ "String" ], "id": 42, "name": "String" }