Help us improve your experience.

Let us know what you think.

Do you have time for a two-minute survey?

 

REST API V9.2 References

 

Each API reference provides information about the parameters, mime type, stability, and responses for each endpoint.

Analytics Endpoints

Use the references for REST API V9.2 analytics endpoints.

GET /analytics/ade_rules

Retrieves a list of ADE rules.

Table 1: GET /analytics/ade_rules Resource Details

MIME Type

application/json

Table 2: GET /analytics/ade_rules Request Parameter Details

Parameter

Type

Optionality

Data Type

MIME Type

Description

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.

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.

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 /analytics/ade_rules Response Codes

HTTP Response Code

Unique Code

Description

200

 

The ADE rules were retrieved.

422

1010

A request parameter is not valid.

500

1020

An error occurred during the attempt to retrieve the ADE rules.

Response Description

An array of ADE Rule objects. An ADE Rule object contains the following fields:

  • id - Long - The sequence ID of the ADE rule.

  • name - String - The name of the ADE rule.

  • ade_rule_type - String - The type of ADE rule: ANOMALY, BEHAVIORAL, THRESHOLD.

  • enabled - Boolean - True if the ADE rule is enabled.

  • owner - String - The owner of the ADE rule.

  • identifier - String - The unique ID of the rule. This value is typically in the form of a UUID, with the exception of legacy system rules.

  • linked_rule_identifier - String - The linked ID of the rule. This value is typically in the form of a UUID, with the exception of legacy system rules, and varies depending on the rule's origin as follows:

    • SYSTEM - The identifier value of the override rule, if one exists. If the system rule has not been overridden, the value will be null.

    • OVERRIDE - The identifier value of the system rule being overridden.

    • USER - The value will be null.

  • creation_date - Long - The number of milliseconds since epoch when the rule was created.

  • modification_date - Long - The number of milliseconds since epoch when the rule was last modified.

Response Sample

[ { "creation_date": 42, "enabled": true, "id": 42, "identifier": "String", "linked_rule_identifier": "String", "modification_date": 42, "name": "String", "owner": "String", "type": "String <one of: ANOMALY, BEHAVIORAL, THRESHOLD>" } ]

GET /analytics/ade_rules/{id}

Retrieves an ADE rule.

Table 4: GET /analytics/ade_rules/{id} Resource Details

MIME Type

application/json

Table 5: GET /analytics/ade_rules/{id} Request Parameter Details

Parameter

Type

Optionality

Data Type

MIME Type

Description

id

path

Required

Number (Integer)

text/plain

null

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 6: GET /analytics/ade_rules/{id} Response Codes

HTTP Response Code

Unique Code

Description

200

 

The ADE rule was retrieved.

404

1002

The ADE rule does not exist.

500

1020

An error occurred during the attempt to retrieve the ADE rule.

Response Description

The ADE rule after it is retrieved. An ADE Rule object contains the following fields:

  • id - Long - The sequence ID of the ADE rule.

  • name - String - The name of the ADE rule.

  • ade_rule_type - String - The type of ADE rule: ANOMALY, BEHAVIORAL, THRESHOLD.

  • enabled - Boolean - True if the ADE rule is enabled.

  • owner - String - The owner of the ADE rule.

  • identifier - String - The unique ID of the rule. This value is typically in the form of a UUID, with the exception of legacy system rules.

  • linked_rule_identifier - String - The linked ID of the rule. This value is typically in the form of a UUID, with the exception of legacy system rules, and varies depending on the rule's origin as follows:

    • SYSTEM - The identifier value of the override rule, if one exists. If the system rule has not been overridden, the value will be null.

    • OVERRIDE - The identifier value of the system rule being overridden.

    • USER - The value will be null.

  • creation_date - Long - The number of milliseconds since epoch when the rule was created.

  • modification_date - Long - The number of milliseconds since epoch when the rule was last modified.

Response Sample

{ "creation_date": 42, "enabled": true, "id": 42, "identifier": "String", "linked_rule_identifier": "String", "modification_date": 42, "name": "String", "owner": "String", "type": "String <one of: ANOMALY, BEHAVIORAL, THRESHOLD>" }

POST /analytics/ade_rules/{id}

Updates the ADE rule owner or enabled/disabled only.

Table 7: POST /analytics/ade_rules/{id} Resource Details

MIME Type

application/json

Table 8: POST /analytics/ade_rules/{id} Request Parameter Details

Parameter

Type

Optionality

Data Type

MIME Type

Description

id

path

Required

Number (Integer)

text/plain

null

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 9: POST /analytics/ade_rules/{id} Request Body Details

Parameter

Data Type

MIME Type

Description

Sample

ade_rule

Object

application/json

null

{ "id": "1", "name": "String", "type": "String", "owner": "String" }

Table 10: POST /analytics/ade_rules/{id} Response Codes

HTTP Response Code

Unique Code

Description

200

 

The ADE rule was updated.

403

1009

You do not have the required capabilities to update the ADE rule.

404

1002

The ADE rule does not exist.

409

1004

The provided user does not have the required capabilities to own the ADE rule.

422

1005

A request parameter is not valid.

500

1020

An error occurred during the attempt to update the ADE rule.

Response Description

The ADE rule after it is updated. An ADE Rule object contains the following fields:

  • id - Long - The sequence ID of the ADE rule.

  • name - String - The name of the ADE rule.

  • ade_rule_type - String - The type of ADE rule: ANOMALY, BEHAVIORAL, THRESHOLD.

  • enabled - Boolean - True if the ADE rule is enabled.

  • owner - String - The owner of the ADE rule.

  • identifier - String - The unique ID of the rule. This value is typically in the form of a UUID, with the exception of legacy system rules.

  • linked_rule_identifier - String - The linked ID of the rule. This value is typically in the form of a UUID, with the exception of legacy system rules, and varies depending on the rule's origin as follows:

    • SYSTEM - The identifier value of the override rule, if one exists. If the system rule has not been overridden, the value will be null.

    • OVERRIDE - The identifier value of the system rule being overridden.

    • USER - The value will be null.

  • creation_date - Long - The number of milliseconds since epoch when the rule was created.

  • modification_date - Long - The number of milliseconds since epoch when the rule was last modified.

Response Sample

{ "creation_date": 42, "enabled": true, "id": 42, "identifier": "String", "linked_rule_identifier": "String", "modification_date": 42, "name": "String", "owner": "String", "type": "String <one of: ANOMALY, BEHAVIORAL, THRESHOLD>" }

DELETE /analytics/ade_rules/{id}

Deletes an ADE rule. To ensure safe deletion, a dependency check is carried out. The check might take some time. An asynchronous task is started to do this check.

Table 11: DELETE /analytics/ade_rules/{id} Resource Details

MIME Type

application/json

Table 12: DELETE /analytics/ade_rules/{id} Request Parameter Details

Parameter

Type

Optionality

Data Type

MIME Type

Description

id

path

Required

Number (Integer)

text/plain

null

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: DELETE /analytics/ade_rules/{id} Response Codes

HTTP Response Code

Unique Code

Description

202

 

The ADE rule delete command was accepted and is in progress.

403

1009

You do not have the required capabilities to delete the ADE rule.

404

1002

The ADE rule does not exist.

500

1020

An error occurred during the attempt to delete the ADE rule.

Response Description

A Delete Task Status object and the location header set to the task status url "/api/analytics/ade_rules/ade_rule_delete_tasks/{task_id}". A Delete Task Status object contains the following fields:

  • id - Long - The ID of the task.

  • message - String - The localized task message.

  • status - String - The current state that the task is in.

  • name - String - The name of the task.

  • created_by - String - The name of the user who started the task.

  • created - Long - The time in milliseconds since epoch since the task was created.

  • started - Long - The time in milliseconds since epoch since the task was started.

  • modified - Long - The time in milliseconds since epoch since the task was modified.

  • completed - Long - The time in milliseconds since epoch since the task was completed.

Response Sample

{ "completed": 42, "created": 42, "created_by": "String", "id": 42, "message": "String", "modified": 42, "name": "String", "started": 42, "status": "String <one of: CANCELLED, CANCELING, CANCEL_REQUESTED, COMPLETED, CONFLICT, EXCEPTION, INITIALIZING, INTERRUPTED, PAUSED, PROCESSING, QUEUED, RESUMING>" }

GET /analytics/ade_rules/{id}/dependents

Retrieves the objects that depend on the ADE rule.

Table 14: GET /analytics/ade_rules/{id}/dependents Resource Details

MIME Type

application/json

Table 15: GET /analytics/ade_rules/{id}/dependents Request Parameter Details

Parameter

Type

Optionality

Data Type

MIME Type

Description

id

path

Required

Number (Integer)

text/plain

null

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 /analytics/ade_rules/{id}/dependents Response Codes

HTTP Response Code

Unique Code

Description

202

 

The ADE rule dependents retrieval was accepted and is in progress.

404

1002

The ADE rule does not exist.

500

1020

An error occurred during the attempt to initiate the ADE rule dependents retrieval task.

Response Description

A Dependents Task Status object and the location header set to the task status url "/api/analytics/ade_rules/ade_rule_dependents_tasks/{task_id}". A Dependent Task Status object contains the following fields:

  • id - Long - The ID of the task.

  • message - String - The localized task message.

  • status - String - The current state of the task.

  • name - String - The name of the task.

  • created_by - String - The name of the user who started the task.

  • cancelled_by - String - The name of the user who requested to cancel the task.

  • created - Long - The time in milliseconds since epoch since the task was created.

  • started - Long - The time in milliseconds since epoch since the task was started.

  • modified - Long - The time in milliseconds since epoch since the task was modified.

  • completed - Long - The time in milliseconds since epoch since the task was completed.

  • number_of_dependents - Long - The number of dependents found. the value is null until the task completes.

  • maximum - Long - The maximum number of objects to check for dependency.

  • progress - Long - The number of objects that were checked for dependency.

  • task_components - Array - An array of task component objects. A task component object contains the following fields

    • message - String - The localized sub-task status message.

    • status - String - The current state of the sub-task.

    • sub_task_type - String - The type of the sub-task.

    • maximum - Long - The maximum number of objects to check for dependency.

    • progress - Long - The number of objects that were checked for dependency.

    • created - Long - The time in milliseconds since epoch since the sub-task was created.

    • started - Long - The time in milliseconds since epoch since the sub-task was started.

    • modified - Long - The time in milliseconds since epoch since the sub-task was modified.

    • completed - Long - The time in milliseconds since epoch since the sub-task was completed.

Response Sample

{ "cancelled_by": "String", "completed": 42, "created": 42, "created_by": "String", "id": 42, "maximum": 42, "message": "String", "modified": 42, "name": "String", "number_of_dependents": 42, "progress": 42, "started": 42, "status": "String <one of: CANCELLED, CANCELING, CANCEL_REQUESTED, COMPLETED, CONFLICT, EXCEPTION, INITIALIZING, INTERRUPTED, PAUSED, PROCESSING, QUEUED, RESUMING>", "task_components": [ { "completed": 42, "created": 42, "maximum": 42, "message": "String", "modified": 42, "number_of_dependents": 42, "progress": 42, "started": 42, "status": "String <one of: CANCELLED, CANCELING, CANCEL_REQUESTED, COMPLETED, CONFLICT, EXCEPTION, INITIALIZING, INTERRUPTED, PAUSED, PROCESSING, QUEUED, RESUMING>", "task_sub_type": "String <one of: FIND_DEPENDENT_ARIEL_SAVED_SEARCHES, FIND_DEPENDENT_OFFENSE_SAVED_SEARCHES, FIND_DEPENDENT_ASSET_SAVED_SEARCHES, FIND_DEPENDENT_VULNERABILITY_SAVED_SEARCHES, FIND_DEPENDENT_ADE_RULES, FIND_DEPENDENT_RULES, FIND_DEPENDENT_CALCULATED_PROPERTIES, FIND_DEPENDENT_LOG_SOURCE_GROUPS, FIND_DEPENDENT_CUSTOM_PROPERTIES, FIND_DEPENDENT_REPORTS, FIND_DEPENDENT_DASHBOARDS, FIND_DEPENDENT_STORE_AND_FORWARD_POLICIES, FIND_DEPENDENT_AUTHORIZED_SERVICES, FIND_DEPENDENT_OFFENSE_TYPES, FIND_DEPENDENT_ASSIGNED_OFFENSES, FIND_DEPENDENT_VULNERABILITIES, FIND_DEPENDENT_GROUPS, FIND_DEPENDENT_HISTORICAL_CORRELATION_PROFILES>" } ] }

GET /analytics/ade_rules/ade_rule_delete_tasks/{task_id}

Retrieves the delete the ADE rule task status.

Table 17: GET /analytics/ade_rules/ade_rule_delete_tasks/{task_id} Resource Details

MIME Type

application/json

Table 18: GET /analytics/ade_rules/ade_rule_delete_tasks/{task_id} Request Parameter Details

Parameter

Type

Optionality

Data Type

MIME Type

Description

task_id

path

Required

Number (Integer)

text/plain

null

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 /analytics/ade_rules/ade_rule_delete_tasks/{task_id} Response Codes

HTTP Response Code

Unique Code

Description

200

 

The Delete Task Status was retrieved.

404

1002

The Delete Task Status does not exist.

500

1020

An error occurred during the attempt to retrieve the Delete Task Status.

Response Description

A Delete Task Status object and the location header set to the task status url "/api/analytics/ade_rules/ade_rule_delete_tasks/{task_id}". A Delete Task Status object contains the following fields:

  • id - Long - The ID of the task.

  • message - String - The localized task message.

  • status - String - The current state of the task.

  • name - String - The name of the task.

  • created_by - String - The name of the user who started the task.

  • created - Long - The time in milliseconds since epoch since the task was created.

  • started - Long - The time in milliseconds since epoch since the task was started.

  • modified - Long - The time in milliseconds since epoch since the task was modified.

  • completed - Long - The time in milliseconds since epoch since the task was completed.

Response Sample

{ "completed": 42, "created": 42, "created_by": "String", "id": 42, "message": "String", "modified": 42, "name": "String", "started": 42, "status": "String <one of: CANCELLED, CANCELING, CANCEL_REQUESTED, COMPLETED, CONFLICT, EXCEPTION, INITIALIZING, INTERRUPTED, PAUSED, PROCESSING, QUEUED, RESUMING>" }

GET /analytics/ade_rules/ade_rule_dependent_tasks/{task_id}

Retrieves the dependent the ADE rule task status.

Table 20: GET /analytics/ade_rules/ade_rule_dependent_tasks/{task_id} Resource Details

MIME Type

application/json

Table 21: GET /analytics/ade_rules/ade_rule_dependent_tasks/{task_id} Request Parameter Details

Parameter

Type

Optionality

Data Type

MIME Type

Description

task_id

path

Required

Number (Integer)

text/plain

null

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 /analytics/ade_rules/ade_rule_dependent_tasks/{task_id} Response Codes

HTTP Response Code

Unique Code

Description

200

 

The Delete Task Status was retrieved.

404

1002

The Delete Task Status does not exist.

500

1020

An error occurred during the attempt to retrieve the Delete Task Status.

Response Description

A Dependent Task Status object and the location header set to the task status url "/api/analytics/ade_rules/ade_rule_dependent_tasks/{task_id}". A Dependent Task Status object contains the following fields:

  • id - Long - The ID of the task.

  • message - String - The localized task message.

  • status - String - The current state of the task.

  • name - String - The name of the task.

  • created_by - String - The name of the user who started the task.

  • cancelled_by - String - The name of the user who requested to cancel the task.

  • created - Long - The time in milliseconds since epoch since the task was created.

  • started - Long - The time in milliseconds since epoch since the task was started.

  • modified - Long - The time in milliseconds since epoch since the task was modified.

  • completed - Long - The time in milliseconds since epoch since the task was completed.

  • number_of_dependents - Long - The number of dependents found. The value is null until task completes.

  • maximum - Long - The maximum number of objects to check for dependency.

  • progress - Long - The number of objects tha were checked for dependency.

  • task_components - Array - An array of task component objects. A task component object contains the following fields

    • message - String - The localized sub-task status message.

    • status - String - The current state of the sub-task.

    • sub_task_type - String - The type of the sub-task.

    • maximum - Long - The maximum number of objects to check for dependency.

    • progress - Long - The number of objects checked for dependency.

    • created - Long - The time in milliseconds since epoch since the sub-task was created.

    • started - Long - The time in milliseconds since epoch since the sub-task was started.

    • modified - Long - The time in milliseconds since epoch since the sub-task was modified.

    • completed - Long - The time in milliseconds since epoch since the sub-task was completed.

Response Sample

{ "cancelled_by": "String", "completed": 42, "created": 42, "created_by": "String", "id": 42, "maximum": 42, "message": "String", "modified": 42, "name": "String", "number_of_dependents": 42, "progress": 42, "started": 42, "status": "String <one of: CANCELLED, CANCELING, CANCEL_REQUESTED, COMPLETED, CONFLICT, EXCEPTION, INITIALIZING, INTERRUPTED, PAUSED, PROCESSING, QUEUED, RESUMING>", "task_components": [ { "completed": 42, "created": 42, "maximum": 42, "message": "String", "modified": 42, "number_of_dependents": 42, "progress": 42, "started": 42, "status": "String <one of: CANCELLED, CANCELING, CANCEL_REQUESTED, COMPLETED, CONFLICT, EXCEPTION, INITIALIZING, INTERRUPTED, PAUSED, PROCESSING, QUEUED, RESUMING>", "task_sub_type": "String <one of: FIND_DEPENDENT_ARIEL_SAVED_SEARCHES, FIND_DEPENDENT_OFFENSE_SAVED_SEARCHES, FIND_DEPENDENT_ASSET_SAVED_SEARCHES, FIND_DEPENDENT_VULNERABILITY_SAVED_SEARCHES, FIND_DEPENDENT_ADE_RULES, FIND_DEPENDENT_RULES, FIND_DEPENDENT_CALCULATED_PROPERTIES, FIND_DEPENDENT_LOG_SOURCE_GROUPS, FIND_DEPENDENT_CUSTOM_PROPERTIES, FIND_DEPENDENT_REPORTS, FIND_DEPENDENT_DASHBOARDS, FIND_DEPENDENT_STORE_AND_FORWARD_POLICIES, FIND_DEPENDENT_AUTHORIZED_SERVICES, FIND_DEPENDENT_OFFENSE_TYPES, FIND_DEPENDENT_ASSIGNED_OFFENSES, FIND_DEPENDENT_VULNERABILITIES, FIND_DEPENDENT_GROUPS, FIND_DEPENDENT_HISTORICAL_CORRELATION_PROFILES>" } ] }

POST /analytics/ade_rules/ade_rule_dependent_tasks/{task_id}

Cancels a dependent ADE rule task.

Table 23: POST /analytics/ade_rules/ade_rule_dependent_tasks/{task_id} Resource Details

MIME Type

application/json

Table 24: POST /analytics/ade_rules/ade_rule_dependent_tasks/{task_id} Request Parameter Details

Parameter

Type

Optionality

Data Type

MIME Type

Description

task_id

path

Required

Number (Integer)

text/plain

null

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 /analytics/ade_rules/ade_rule_dependent_tasks/{task_id} Request Body Details

Parameter

Data Type

MIME Type

Description

Sample

task

Object

application/json

null

{ "status": "String <one of: CANCELLED, CANCELING, CANCEL_REQUESTED, COMPLETED, CONFLICT, EXCEPTION, INITIALIZING, INTERRUPTED, PAUSED, PROCESSING, QUEUED, RESUMING>" }

Table 26: POST /analytics/ade_rules/ade_rule_dependent_tasks/{task_id} Response Codes

HTTP Response Code

Unique Code

Description

200

 

The Delete Task Status was retrieved.

404

1002

The Dependent Task Status does not exist.

409

1004

The task is in a completed state.

422

1005

A request parameter is not valid.

500

1020

An error occurred during the attempt to update the Dependent Task Status.

Response Description

A Dependent Task Status object and the location header set to the task status url "/api/analytics/ade_rules/ade_rule_dependent_tasks/{task_id}". A Dependent Task Status object contains the following fields:

  • id - Long - The ID of the task.

  • message - String - The localized task message.

  • status - String - The current state of the task.

  • name - String - The name of the task.

  • created_by - String - The name of the user who started the task.

  • cancelled_by - String - The name of the user who requested to cancel the task.

  • created - Long - The time in milliseconds since epoch since the task was created.

  • started - Long - The time in milliseconds since epoch since the task was started.

  • modified - Long - The time in milliseconds since epoch since the task was modified.

  • completed - Long - The time in milliseconds since epoch since the task was completed.

  • number_of_dependents - Long - The number of dependents found. The value is null until the task completes.

  • maximum - Long - The maximum number of objects to check for dependency.

  • progress - Long - The number of objects that were checked for dependency.

  • task_components - Array - An array of task component objects. A task component object contains the following fields:

    • message - String - The localized sub-task status message.

    • status - String - The current state of the sub-task.

    • sub_task_type - String - The type of the sub-task.

    • maximum - Long - The maximum number of objects to check for dependency.

    • progress - Long - The number of objects that were checked for dependency.

    • created - Long - The time in milliseconds since epoch since the sub-task was created.

    • started - Long - The time in milliseconds since epoch since the sub-task was started.

    • modified - Long - The time in milliseconds since epoch since the sub-task was modified.

    • completed - Long - The time in milliseconds since epoch since the sub-task was completed.

Response Sample

{ "cancelled_by": "String", "completed": 42, "created": 42, "created_by": "String", "id": 42, "maximum": 42, "message": "String", "modified": 42, "name": "String", "number_of_dependents": 42, "progress": 42, "started": 42, "status": "String <one of: CANCELLED, CANCELING, CANCEL_REQUESTED, COMPLETED, CONFLICT, EXCEPTION, INITIALIZING, INTERRUPTED, PAUSED, PROCESSING, QUEUED, RESUMING>", "task_components": [ { "completed": 42, "created": 42, "maximum": 42, "message": "String", "modified": 42, "number_of_dependents": 42, "progress": 42, "started": 42, "status": "String <one of: CANCELLED, CANCELING, CANCEL_REQUESTED, COMPLETED, CONFLICT, EXCEPTION, INITIALIZING, INTERRUPTED, PAUSED, PROCESSING, QUEUED, RESUMING>", "task_sub_type": "String <one of: FIND_DEPENDENT_ARIEL_SAVED_SEARCHES, FIND_DEPENDENT_OFFENSE_SAVED_SEARCHES, FIND_DEPENDENT_ASSET_SAVED_SEARCHES, FIND_DEPENDENT_VULNERABILITY_SAVED_SEARCHES, FIND_DEPENDENT_ADE_RULES, FIND_DEPENDENT_RULES, FIND_DEPENDENT_CALCULATED_PROPERTIES, FIND_DEPENDENT_LOG_SOURCE_GROUPS, FIND_DEPENDENT_CUSTOM_PROPERTIES, FIND_DEPENDENT_REPORTS, FIND_DEPENDENT_DASHBOARDS, FIND_DEPENDENT_STORE_AND_FORWARD_POLICIES, FIND_DEPENDENT_AUTHORIZED_SERVICES, FIND_DEPENDENT_OFFENSE_TYPES, FIND_DEPENDENT_ASSIGNED_OFFENSES, FIND_DEPENDENT_VULNERABILITIES, FIND_DEPENDENT_GROUPS, FIND_DEPENDENT_HISTORICAL_CORRELATION_PROFILES>" } ] }

GET /analytics/ade_rules/ade_rule_dependent_tasks/{task_id}/results

Retrieves the ADE rule dependent task results.

Table 27: GET /analytics/ade_rules/ade_rule_dependent_tasks/{task_id}/results Resource Details

MIME Type

application/json

Table 28: GET /analytics/ade_rules/ade_rule_dependent_tasks/{task_id}/results Request Parameter Details

Parameter

Type

Optionality

Data Type

MIME Type

Description

task_id

path

Required

Number (Integer)

text/plain

null

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 /analytics/ade_rules/ade_rule_dependent_tasks/{task_id}/results Response Codes

HTTP Response Code

Unique Code

Description

200

 

The ADE rule dependents were retrieved.

404

1002

The dependent task dtatus does not exist.

500

1020

An error occurred during the attempt to retrieve the ADE rules.

Response Description

An list of Dependent objects. A Dependent object contains the following fields:

  • dependent_id - String - The ID of the dependent resource.

  • dependent_name - String - The name of the dependent resource (default resources can have localized names).

  • dependent_owner - String - The owner of the dependent resource

  • dependent_type - String - The type of the dependent resource

  • dependent_database - String - The database of the dependent resource.

  • dependent_group_ids - Array of Longs - List of groups that the dependent resource belongs to.

  • user_has_edit_permissions - Boolean - The true if the user who created the task has permission to edit this dependent resource.

Response Sample

[ { "blocking": true, "dependent_database": "String <one of: EVENTS, FLOWS>", "dependent_group_ids": [ 42 ], "dependent_id": "String", "dependent_name": "String", "dependent_owner": "String", "dependent_type": "String <one of: ARIEL_SAVED_SEARCH, ASSET_SAVED_SEARCH, OFFENSE_SAVED_SEARCH, VULNERABILITY_SAVED_SEARCH, QRM_SAVED_SEARCH_GROUP, ASSET_SAVED_SEARCH_GROUP, CUSTOM_RULE_GROUP, EVENT_ARIEL_SAVED_SEARCH_GROUP, FLOW_ARIEL_SAVED_SEARCH_GROUP, LOG_SOURCE_GROUP, MODEL_GROUP, OFFENSE_SAVED_SEARCH_GROUP, QUESTION_GROUP, REPORT_GROUP, SIMULATION_GROUP, TOPOLOGY_SAVED_SEARCH_GROUP, VULNERABILITY_SAVED_SEARCH_GROUP, ASSIGNED_OFFENSE, ASSIGNED_VULNERABILITY, AUTHORIZED_SERVICE, BUILDING_BLOCK, CRE_RULE, CRE_ADE_RULE, EVENT_REGEX_PROPERTY, EVENT_CALCULATED_PROPERTY, FLOW_REGEX_PROPERTY, FLOW_CALCULATED_PROPERTY, DASHBOARD, GV_REFERENCE, REPORT, REFERENCE_DATA, REFERENCE_DATA_MAP_OF_SETS, REFERENCE_DATA_MAPS, REFERENCE_DATA_SETS, REFERENCE_DATA_TABLES, REFERENCE_DATA_RESPONSE, REFERENCE_SET_RESPONSE, EVENT_RETENTION_BUCKET, FLOW_RETENTION_BUCKET, ROUTING_RULE, STORE_AND_FORWARD_POLICY, USER, HISTORICAL_PROFILE, OFFENSE_TYPE>", "user_has_edit_permissions": true } ]

GET /analytics/building_blocks

Retrieves a list of building block rules.

Table 30: GET /analytics/building_blocks Resource Details

MIME Type

application/json

Table 31: GET /analytics/building_blocks Request Parameter Details

Parameter

Type

Optionality

Data Type

MIME Type

Description

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.

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.

Table 32: GET /analytics/building_blocks Response Codes

HTTP Response Code

Unique Code

Description

200

 

The building block rules were retrieved.

422

1010

A request parameter is not valid.

500

1020

An error occurred during the attempt to retrieve the building block rules.

Response Description

An array of Building Block Rule objects. An Building Block Rule object contains the following fields:

  • id - Long - The sequence ID of the building block rule.

  • name - String - The name of the building block rule.

  • building_block_type - String - The type of building block rule: EVENT, FLOW, COMMON, USER.

  • enabled - Boolean - True if the building block rule is enabled.

  • owner - String - The owner of the building block rule.

  • origin - String - The origin of the building block rule: SYSTEM, OVERRIDE, USER.

  • base_capacity - Long - The base capacity of the building block rule in events per second.

  • base_host_id - Long - The ID of the host from which the building block rule's base capacity was determined

  • average_capacity - Long - The moving average capacity, in EPS, of the building block rule across all hosts.

  • capacity_timestamp - Long - The epoch timestamp, in milliseconds, since the building block's capacity values were last updated.

  • identifier - String - The unique ID of the rule. This value is typically in the form of a UUID, with the exception of legacy system rules.

  • linked_rule_identifier - String - The linked ID of the rule. This value is typically in the form of a UUID, with the exception of legacy system rules, and varies depending on the rule's origin as follows:

    • SYSTEM - The identifier value of the override rule, if one exists. If the system rule has not been overridden, the value will be null.

    • OVERRIDE - The identifier value of the system rule being overridden.

    • USER - The value will be null.

  • creation_date - Long - The number of milliseconds since epoch when the rule was created.

  • modification_date - Long - The number of milliseconds since epoch when the rule was last modified.

Response Sample

[ { "average_capacity": 42, "base_capacity": 42, "base_host_id": 42, "capacity_timestamp": 42, "creation_date": 42, "enabled": true, "id": 42, "identifier": "String", "linked_rule_identifier": "String", "modification_date": 42, "name": "String", "origin": "String <one of: SYSTEM, OVERRIDE, USER>", "owner": "String", "type": "String <one of: EVENT, FLOW, COMMON, OFFENSE>" } ]

GET /analytics/building_blocks/building_block_delete_tasks/{task_id}

Retrieves the delete the building block rule task status.

Table 33: GET /analytics/building_blocks/building_block_delete_tasks/{task_id} Resource Details

MIME Type

application/json

Table 34: GET /analytics/building_blocks/building_block_delete_tasks/{task_id} Request Parameter Details

Parameter

Type

Optionality

Data Type

MIME Type

Description

task_id

path

Required

Number (Integer)

text/plain

null

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 35: GET /analytics/building_blocks/building_block_delete_tasks/{task_id} Response Codes

HTTP Response Code

Unique Code

Description

200

 

The Delete Task Status was retrieved.

404

1002

The Delete Task Status does not exist.

500

1020

An error occurred during the attempt to retrieve the Delete Task Status.

Response Description

A Delete Task Status object and the location header set to the task status url "/api/analytics/building_blocks/building_block_delete_tasks/{task_id}". A Delete Task Status object contains the following fields:

  • id - Long - The ID of the task.

  • message - String - The localized task message.

  • status - String - The current state of the task.

  • name - String - The name of the task.

  • created_by - String - The name of the user who started the task.

  • created - Long - The time in milliseconds since epoch since the task was created.

  • started - Long - The time in milliseconds since epoch since the task was started.

  • modified - Long - The time in milliseconds since epoch since the task was modified.

  • completed - Long - The time in milliseconds since epoch since the task was completed.

Response Sample

{ "completed": 42, "created": 42, "created_by": "String", "id": 42, "message": "String", "modified": 42, "name": "String", "started": 42, "status": "String <one of: CANCELLED, CANCELING, CANCEL_REQUESTED, COMPLETED, CONFLICT, EXCEPTION, INITIALIZING, INTERRUPTED, PAUSED, PROCESSING, QUEUED, RESUMING>" }

GET /analytics/building_blocks/building_block_dependent_tasks/{task_id}

Retrieves the dependent the building block rule task status.

Table 36: GET /analytics/building_blocks/building_block_dependent_tasks/{task_id} Resource Details

MIME Type

application/json

Table 37: GET /analytics/building_blocks/building_block_dependent_tasks/{task_id} Request Parameter Details

Parameter

Type

Optionality

Data Type

MIME Type

Description

task_id

path

Required

Number (Integer)

text/plain

null

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 38: GET /analytics/building_blocks/building_block_dependent_tasks/{task_id} Response Codes

HTTP Response Code

Unique Code

Description

200

 

The Delete Task Status was retrieved.

404

1002

The Delete Task Status does not exist.

500

1020

An error occurred during the attempt to retrieve the Delete Task Status.

Response Description

A Dependent Task Status object and the location header set to the task status url "/api/analytics/building_blocks/building_block_dependent_tasks/{task_id}". A Dependent Task Status object contains the following fields:

  • id - Long - The ID of the task.

  • message - String - The localized task message.

  • status - String - The current state of the task.

  • name - String - The name of the task.

  • created_by - String - The name of the user who started the task.

  • cancelled_by - String - The name of the user who requested to cancel the task.

  • created - Long - The time in milliseconds since epoch since the task was created.

  • started - Long - The time in milliseconds since epoch since the task was started.

  • modified - Long - The time in milliseconds since epoch since the task was modified.

  • completed - Long - The time in milliseconds since epoch since the task was completed.

  • number_of_dependents - Long - The number of dependents found. The value is null until the task completes.

  • maximum - Long - The maximum number of objects to check for dependency.

  • progress - Long - The number of objects that were checked for dependency.

  • task_components - Array - An array of task component objects. A task component object contains the following fields

    • message - String - The localized sub-task status message.

    • status - String - The current state of the sub-task.

    • sub_task_type - String - The type of the sub-task

    • maximum - Long - The maximum number of objects to check for dependency.

    • progress - Long - The number of objects that were checked for dependency.

    • created - Long - The time in milliseconds since epoch since the sub-task was created.

    • started - Long - The time in milliseconds since epoch since the sub-task was started.

    • modified - Long - The time in milliseconds since epoch since the sub-task was modified.

    • completed - Long - The time in milliseconds since epoch since the sub-task was completed.

Response Sample

{ "cancelled_by": "String", "completed": 42, "created": 42, "created_by": "String", "id": 42, "maximum": 42, "message": "String", "modified": 42, "name": "String", "number_of_dependents": 42, "progress": 42, "started": 42, "status": "String <one of: CANCELLED, CANCELING, CANCEL_REQUESTED, COMPLETED, CONFLICT, EXCEPTION, INITIALIZING, INTERRUPTED, PAUSED, PROCESSING, QUEUED, RESUMING>", "task_components": [ { "completed": 42, "created": 42, "maximum": 42, "message": "String", "modified": 42, "number_of_dependents": 42, "progress": 42, "started": 42, "status": "String <one of: CANCELLED, CANCELING, CANCEL_REQUESTED, COMPLETED, CONFLICT, EXCEPTION, INITIALIZING, INTERRUPTED, PAUSED, PROCESSING, QUEUED, RESUMING>", "task_sub_type": "String <one of: FIND_DEPENDENT_ARIEL_SAVED_SEARCHES, FIND_DEPENDENT_OFFENSE_SAVED_SEARCHES, FIND_DEPENDENT_ASSET_SAVED_SEARCHES, FIND_DEPENDENT_VULNERABILITY_SAVED_SEARCHES, FIND_DEPENDENT_ADE_RULES, FIND_DEPENDENT_RULES, FIND_DEPENDENT_CALCULATED_PROPERTIES, FIND_DEPENDENT_LOG_SOURCE_GROUPS, FIND_DEPENDENT_CUSTOM_PROPERTIES, FIND_DEPENDENT_REPORTS, FIND_DEPENDENT_DASHBOARDS, FIND_DEPENDENT_STORE_AND_FORWARD_POLICIES, FIND_DEPENDENT_AUTHORIZED_SERVICES, FIND_DEPENDENT_OFFENSE_TYPES, FIND_DEPENDENT_ASSIGNED_OFFENSES, FIND_DEPENDENT_VULNERABILITIES, FIND_DEPENDENT_GROUPS, FIND_DEPENDENT_HISTORICAL_CORRELATION_PROFILES>" } ] }

POST /analytics/building_blocks/building_block_dependent_tasks/{task_id}

Cancels the dependent the building block rule task.

Table 39: POST /analytics/building_blocks/building_block_dependent_tasks/{task_id} Resource Details

MIME Type

application/json

Table 40: POST /analytics/building_blocks/building_block_dependent_tasks/{task_id} Request Parameter Details

Parameter

Type

Optionality

Data Type

MIME Type

Description

task_id

path

Required

Number (Integer)

text/plain

null

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 41: POST /analytics/building_blocks/building_block_dependent_tasks/{task_id} Request Body Details

Parameter

Data Type

MIME Type

Description

Sample

task

Object

application/json

null

{ "status": "String <one of: CANCELLED, CANCELING, CANCEL_REQUESTED, COMPLETED, CONFLICT, EXCEPTION, INITIALIZING, INTERRUPTED, PAUSED, PROCESSING, QUEUED, RESUMING>" }

Table 42: POST /analytics/building_blocks/building_block_dependent_tasks/{task_id} Response Codes

HTTP Response Code

Unique Code

Description

200

 

The Delete Task Status has been retrieved.

404

1002

The Dependent Task Status does not exist.

409

1004

The task is in a completed state

422

1005

A request parameter is not valid

500

1020

An error occurred during the attempt to update the Dependent Task Status.

Response Description

A Dependent Task Status object and the location header set to the task status url "/api/analytics/building_blocks/building_block_dependent_tasks/{task_id}". A Dependent Task Status object contains the following fields:

  • id - Long - The ID of the task.

  • message - String - The localized task message.

  • status - String - The current state of the task.

  • name - String - The name of the task.

  • created_by - String - The name of the user who started the task.

  • cancelled_by - String - The name of the user who requested the cancellation of the task.

  • created - Long - The time in milliseconds since epoch since the task was created.

  • started - Long - The time in milliseconds since epoch since the task was started.

  • modified - Long - The time in milliseconds since epoch since the task was modified.

  • completed - Long - The time in milliseconds since epoch since the task was completed.

  • number_of_dependents - Long - The number of dependents found. The value is null until the task completes.

  • maximum - Long - The maximum number of objects to check for dependency.

  • progress - Long - The number of objects that were checked for dependency.

  • task_components - Array - An array of task component objects. A task component object contains the following fields

    • message - String - The localized sub-task status message.

    • status - String - The current state of the the sub-task.

    • sub_task_type - String - The type of the sub-task

    • maximum - Long - The maximum number of objects to check for dependency.

    • progress - Long - The number of objects that were checked for dependency.

    • created - Long - The time in milliseconds since epoch since the sub-task was created.

    • started - Long - The time in milliseconds since epoch since the sub-task was started.

    • modified - Long - The time in milliseconds since epoch since the sub-task was modified.

    • completed - Long - The time in milliseconds since epoch since the sub-task was completed.

Response Sample

{ "cancelled_by": "String", "completed": 42, "created": 42, "created_by": "String", "id": 42, "maximum": 42, "message": "String", "modified": 42, "name": "String", "number_of_dependents": 42, "progress": 42, "started": 42, "status": "String <one of: CANCELLED, CANCELING, CANCEL_REQUESTED, COMPLETED, CONFLICT, EXCEPTION, INITIALIZING, INTERRUPTED, PAUSED, PROCESSING, QUEUED, RESUMING>", "task_components": [ { "completed": 42, "created": 42, "maximum": 42, "message": "String", "modified": 42, "number_of_dependents": 42, "progress": 42, "started": 42, "status": "String <one of: CANCELLED, CANCELING, CANCEL_REQUESTED, COMPLETED, CONFLICT, EXCEPTION, INITIALIZING, INTERRUPTED, PAUSED, PROCESSING, QUEUED, RESUMING>", "task_sub_type": "String <one of: FIND_DEPENDENT_ARIEL_SAVED_SEARCHES, FIND_DEPENDENT_OFFENSE_SAVED_SEARCHES, FIND_DEPENDENT_ASSET_SAVED_SEARCHES, FIND_DEPENDENT_VULNERABILITY_SAVED_SEARCHES, FIND_DEPENDENT_ADE_RULES, FIND_DEPENDENT_RULES, FIND_DEPENDENT_CALCULATED_PROPERTIES, FIND_DEPENDENT_LOG_SOURCE_GROUPS, FIND_DEPENDENT_CUSTOM_PROPERTIES, FIND_DEPENDENT_REPORTS, FIND_DEPENDENT_DASHBOARDS, FIND_DEPENDENT_STORE_AND_FORWARD_POLICIES, FIND_DEPENDENT_AUTHORIZED_SERVICES, FIND_DEPENDENT_OFFENSE_TYPES, FIND_DEPENDENT_ASSIGNED_OFFENSES, FIND_DEPENDENT_VULNERABILITIES, FIND_DEPENDENT_GROUPS, FIND_DEPENDENT_HISTORICAL_CORRELATION_PROFILES>" } ] }

GET /analytics/building_blocks/building_block_dependent_tasks/{task_id}/results

Retrieves the building block rule dependent task results.

Table 43: GET /analytics/building_blocks/building_block_dependent_tasks/{task_id}/results Resource Details

MIME Type

application/json

Table 44: GET /analytics/building_blocks/building_block_dependent_tasks/{task_id}/results Request Parameter Details

Parameter

Type

Optionality

Data Type

MIME Type

Description

task_id

path

Required

Number (Integer)

text/plain

null

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 45: GET /analytics/building_blocks/building_block_dependent_tasks/{task_id}/results Response Codes

HTTP Response Code

Unique Code

Description

200

 

The building block rule dependents were retrieved.

404

1002

The Dependent Task Status does not exist.

500

1020

An error occurred during the attempt to retrieve the building block rules.

Response Description

An list of Dependent objects. A Dependent object contains the following fields:

  • dependent_id - String - The ID of the dependent resource.

  • dependent_name - String - The name of the dependent resource (default resources can have localized names).

  • dependent_owner - String - The owner of the dependent resource.

  • dependent_type - String - The type of the dependent resource.

  • dependent_database - String - The database of the dependent resource.

  • dependent_group_ids - Array of Longs - List of groups that the dependent resource belongs to.

  • user_has_edit_permissions - Boolean - The true if the user who created the task has permission to edit this dependent resource.

Response Sample

[ { "blocking": true, "dependent_database": "String <one of: EVENTS, FLOWS>", "dependent_group_ids": [ 42 ], "dependent_id": "String", "dependent_name": "String", "dependent_owner": "String", "dependent_type": "String <one of: ARIEL_SAVED_SEARCH, ASSET_SAVED_SEARCH, OFFENSE_SAVED_SEARCH, VULNERABILITY_SAVED_SEARCH, QRM_SAVED_SEARCH_GROUP, ASSET_SAVED_SEARCH_GROUP, CUSTOM_RULE_GROUP, EVENT_ARIEL_SAVED_SEARCH_GROUP, FLOW_ARIEL_SAVED_SEARCH_GROUP, LOG_SOURCE_GROUP, MODEL_GROUP, OFFENSE_SAVED_SEARCH_GROUP, QUESTION_GROUP, REPORT_GROUP, SIMULATION_GROUP, TOPOLOGY_SAVED_SEARCH_GROUP, VULNERABILITY_SAVED_SEARCH_GROUP, ASSIGNED_OFFENSE, ASSIGNED_VULNERABILITY, AUTHORIZED_SERVICE, BUILDING_BLOCK, CRE_RULE, CRE_ADE_RULE, EVENT_REGEX_PROPERTY, EVENT_CALCULATED_PROPERTY, FLOW_REGEX_PROPERTY, FLOW_CALCULATED_PROPERTY, DASHBOARD, GV_REFERENCE, REPORT, REFERENCE_DATA, REFERENCE_DATA_MAP_OF_SETS, REFERENCE_DATA_MAPS, REFERENCE_DATA_SETS, REFERENCE_DATA_TABLES, REFERENCE_DATA_RESPONSE, REFERENCE_SET_RESPONSE, EVENT_RETENTION_BUCKET, FLOW_RETENTION_BUCKET, ROUTING_RULE, STORE_AND_FORWARD_POLICY, USER, HISTORICAL_PROFILE, OFFENSE_TYPE>", "user_has_edit_permissions": true } ]

GET /analytics/building_blocks/{id}

Retrieves a building block rule.

Table 46: GET /analytics/building_blocks/{id} Resource Details

MIME Type

application/json

Table 47: GET /analytics/building_blocks/{id} Request Parameter Details

Parameter

Type

Optionality

Data Type

MIME Type

Description

id

path

Required

Number (Integer)

text/plain

null

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 48: GET /analytics/building_blocks/{id} Response Codes

HTTP Response Code

Unique Code

Description

200

 

The building block rule was retrieved.

404

1002

The building block rule does not exist.

500

1020

An error occurred during the attempt to retrieve the building block rule.

Response Description

The building block rule after it is retrieved. An Building Block Rule object contains the following fields:

  • id - Long - The sequence ID of the building block rule.

  • name - String - The name of the building block rule.

  • building_block_type - String - The type of building block rule: EVENT, FLOW, COMMON, USER.

  • enabled - Boolean - True if the building block rule is enabled.

  • owner - String - The owner of the building block rule.

  • origin - String - The origin of the building block rule: SYSTEM, OVERRIDE, USER.

  • base_capacity - Long - The base capacity of the building block rule in events per second.

  • base_host_id - Long - The ID of the host from which the building block rule's base capacity was determined

  • average_capacity - Long - The moving average capacity, in EPS, of the building block rule across all hosts.

  • capacity_timestamp - Long - The epoch timestamp, in milliseconds, since the building block's capacity values were last updated.

  • identifier - String - The unique ID of the rule. This value is typically in the form of a UUID, with the exception of legacy system rules.

  • linked_rule_identifier - String - The linked ID of the rule. This value is typically in the form of a UUID, with the exception of legacy system rules, and varies depending on the rule's origin as follows:

    • SYSTEM - The identifier value of the override rule, if one exists. If the system rule has not been overridden, the value will be null.

    • OVERRIDE - The identifier value of the system rule being overridden.

    • USER - The value will be null.

  • creation_date - Long - The number of milliseconds since epoch when the rule was created.

  • modification_date - Long - The number of milliseconds since epoch when the rule was last modified.

Response Sample

{ "average_capacity": 42, "base_capacity": 42, "base_host_id": 42, "capacity_timestamp": 42, "creation_date": 42, "enabled": true, "id": 42, "identifier": "String", "linked_rule_identifier": "String", "modification_date": 42, "name": "String", "origin": "String <one of: SYSTEM, OVERRIDE, USER>", "owner": "String", "type": "String <one of: EVENT, FLOW, COMMON, OFFENSE>" }

POST /analytics/building_blocks/{id}

Updates the building block rule owner or enabled/disabled only.

Table 49: POST /analytics/building_blocks/{id} Resource Details

MIME Type

application/json

Table 50: POST /analytics/building_blocks/{id} Request Parameter Details

Parameter

Type

Optionality

Data Type

MIME Type

Description

id

path

Required

Number (Integer)

text/plain

null

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 51: POST /analytics/building_blocks/{id} Request Body Details

Parameter

Data Type

MIME Type

Description

Sample

building_block

Object

application/json

null

{ "id": "1", "name": "String", "type": "String", "owner": "String" }

Table 52: POST /analytics/building_blocks/{id} Response Codes

HTTP Response Code

Unique Code

Description

200

 

The building block rule was updated.

403

1009

You do not have the required capabilities to update the building block rule.

404

1002

The building block rule does not exist.

409

1004

The provided user does not have the required capabilities to own the building block rule.

422

1005

A request parameter is not valid.

500

1020

An error occurred during the attempt to update the building block rule.

Response Description

The building block rule after it is updated. A building block rule object contains the following fields:

  • id - Long - The sequence ID of the building block rule.

  • name - String - The name of the building block rule.

  • building_block_type - String - The type of building block rule: EVENT, FLOW, COMMON, USER.

  • enabled - Boolean - True if the building block rule is enabled.

  • owner - String - The owner of the building block rule.

  • origin - String - The origin of the building block rule: SYSTEM, OVERRIDE, USER.

  • base_capacity - Long - The base capacity of the building block rule in events per second.

  • base_host_id - Long - The ID of the host from which the building block rule's base capacity was determined

  • average_capacity - Long - The moving average capacity, in EPS, of the building block rule across all hosts.

  • capacity_timestamp - Long - The epoch timestamp, in milliseconds, since the building block's capacity values were last updated.

  • identifier - String - The unique ID of the rule. This value is typically in the form of a UUID, with the exception of legacy system rules.

  • linked_rule_identifier - String - The linked ID of the rule. This value is typically in the form of a UUID, with the exception of legacy system rules, and varies depending on the rule's origin as follows:

    • SYSTEM - The identifier value of the override rule, if one exists. If the system rule has not been overridden, the value will be null.

    • OVERRIDE - The identifier value of the system rule being overridden.

    • USER - The value will be null.

  • creation_date - Long - The number of milliseconds since epoch when the rule was created.

  • modification_date - Long - The number of milliseconds since epoch when the rule was last modified.

Response Sample

{ "average_capacity": 42, "base_capacity": 42, "base_host_id": 42, "capacity_timestamp": 42, "creation_date": 42, "enabled": true, "id": 42, "identifier": "String", "linked_rule_identifier": "String", "modification_date": 42, "name": "String", "origin": "String <one of: SYSTEM, OVERRIDE, USER>", "owner": "String", "type": "String <one of: EVENT, FLOW, COMMON, OFFENSE>" }

DELETE /analytics/building_blocks/{id}

Deletes the building block rule. To ensure safe deletion, a dependency check is carried out. This check might take some time. An asynchronous task to do is started for this check.

Table 53: DELETE /analytics/building_blocks/{id} Resource Details

MIME Type

application/json

Table 54: DELETE /analytics/building_blocks/{id} Request Parameter Details

Parameter

Type

Optionality

Data Type

MIME Type

Description

id

path

Required

Number (Integer)

text/plain

null

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 55: DELETE /analytics/building_blocks/{id} Response Codes

HTTP Response Code

Unique Code

Description

202

 

The building block rule delete command was accepted and is in progress.

403

1009

You do not have the required capabilities to delete the building block rule.

404

1002

The building block rule does not exist.

409

1004

null

500

1020

An error occurred during the attempt to delete the building block rule.

Response Description

A Delete Task Status object and the location header set to the task status url "/api/analytics/building_blocks/building_block_delete_tasks/{task_id}". A Delete Task Status object contains the following fields:

  • id - Long - The ID of the task.

  • message - String - The localized task message.

  • status - String - The current state that the task is in.

  • name - String - The name of the task.

  • created_by - String - The name of the user who started the task.

  • created - Long - The time in milliseconds since epoch since the task was created.

  • started - Long - The time in milliseconds since epoch since the task was started.

  • modified - Long - The time in milliseconds since epoch since the task was modified.

  • completed - Long - The time in milliseconds since epoch since the task was completed.

Response Sample

{ "completed": 42, "created": 42, "created_by": "String", "id": 42, "message": "String", "modified": 42, "name": "String", "started": 42, "status": "String <one of: CANCELLED, CANCELING, CANCEL_REQUESTED, COMPLETED, CONFLICT, EXCEPTION, INITIALIZING, INTERRUPTED, PAUSED, PROCESSING, QUEUED, RESUMING>" }

GET /analytics/building_blocks/{id}/dependents

Retrieves the objects that depend on the building block rule.

Table 56: GET /analytics/building_blocks/{id}/dependents Resource Details

MIME Type

application/json

Table 57: GET /analytics/building_blocks/{id}/dependents Request Parameter Details

Parameter

Type

Optionality

Data Type

MIME Type

Description

id

path

Required

Number (Integer)

text/plain

null

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 58: GET /analytics/building_blocks/{id}/dependents Response Codes

HTTP Response Code

Unique Code

Description

202

 

The building block rule dependents retrieval was accepted and is in progress.

404

1002

The building block rule does not exist.

500

1020

An error occurred during the attempt to initiate the building block rule dependents retrieval task.

Response Description

A Dependents Task Status object and the location header set to the task status url "/api/analytics/building_blocks/building_block_dependents_tasks/{task_id}". A Dependent Task Status object contains the following fields:

  • id - Long - The ID of the task.

  • message - String - The localized task message.

  • status - String - The current state of the task.

  • name - String - The name of the task.

  • created_by - String - The name of the user who started the task.

  • cancelled_by - String - The name of the user who requested to cancel the task.

  • created - Long - The time in milliseconds since epoch since the task was created.

  • started - Long - The time in milliseconds since epoch since the task was started.

  • modified - Long - The time in milliseconds since epoch since the task was modified.

  • completed - Long - The time in milliseconds since epoch since the task was completed.

  • number_of_dependents - Long - The number of dependents found. the value is null until the task completes.

  • maximum - Long - The maximum number of objects to check for dependency.

  • progress - Long - The number of objects that were checked for dependency.

  • task_components - Array - An array of task component objects. A task component object contains the following fields

    • message - String - The localized sub-task status message.

    • status - String - The current state of the sub-task.

    • sub_task_type - String - The type of the sub-task

    • maximum - Long - The maximum number of objects to check for dependency.

    • progress - Long - The number of objects that were checked for dependency.

    • created - Long - The time in milliseconds since epoch since the sub-task was created.

    • started - Long - The time in milliseconds since epoch since the sub-task was started.

    • modified - Long - The time in milliseconds since epoch since the sub-task was modified.

    • completed - Long - The time in milliseconds since epoch since the sub-task was completed.

Response Sample

{ "cancelled_by": "String", "completed": 42, "created": 42, "created_by": "String", "id": 42, "maximum": 42, "message": "String", "modified": 42, "name": "String", "number_of_dependents": 42, "progress": 42, "started": 42, "status": "String <one of: CANCELLED, CANCELING, CANCEL_REQUESTED, COMPLETED, CONFLICT, EXCEPTION, INITIALIZING, INTERRUPTED, PAUSED, PROCESSING, QUEUED, RESUMING>", "task_components": [ { "completed": 42, "created": 42, "maximum": 42, "message": "String", "modified": 42, "number_of_dependents": 42, "progress": 42, "started": 42, "status": "String <one of: CANCELLED, CANCELING, CANCEL_REQUESTED, COMPLETED, CONFLICT, EXCEPTION, INITIALIZING, INTERRUPTED, PAUSED, PROCESSING, QUEUED, RESUMING>", "task_sub_type": "String <one of: FIND_DEPENDENT_ARIEL_SAVED_SEARCHES, FIND_DEPENDENT_OFFENSE_SAVED_SEARCHES, FIND_DEPENDENT_ASSET_SAVED_SEARCHES, FIND_DEPENDENT_VULNERABILITY_SAVED_SEARCHES, FIND_DEPENDENT_ADE_RULES, FIND_DEPENDENT_RULES, FIND_DEPENDENT_CALCULATED_PROPERTIES, FIND_DEPENDENT_LOG_SOURCE_GROUPS, FIND_DEPENDENT_CUSTOM_PROPERTIES, FIND_DEPENDENT_REPORTS, FIND_DEPENDENT_DASHBOARDS, FIND_DEPENDENT_STORE_AND_FORWARD_POLICIES, FIND_DEPENDENT_AUTHORIZED_SERVICES, FIND_DEPENDENT_OFFENSE_TYPES, FIND_DEPENDENT_ASSIGNED_OFFENSES, FIND_DEPENDENT_VULNERABILITIES, FIND_DEPENDENT_GROUPS, FIND_DEPENDENT_HISTORICAL_CORRELATION_PROFILES>" } ] }

GET /analytics/custom_actions/actions

Retrieves a list of available custom actions.

Table 59: GET /analytics/custom_actions/actions Resource Details

MIME Type

application/json

Table 60: GET /analytics/custom_actions/actions 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 61: GET /analytics/custom_actions/actions Response Codes

HTTP Response Code

Unique Code

Description

200

 

The requested list of custom actions have been successfully retrieved.

500

1020

An internal server error occurred while retrieving custom actions.

Response Description

Array of available custom actions which in turn contain the following fields:

  • id - Number - Unique ID of the custom action within the JSA deployment.

  • name - String - Unique name of the custom action within the JSA deployment.

  • description - String - Optional description attached to the custom action.

  • interpreter - Number - Unique ID of the custom action interpreter used by the custom action.

  • script - Number - Unique ID of the custom action script used by the custom action.

  • parameters - Array - Array of custom action parameters contained within the custom action. Each Custom action parameter has the following fields:

    • name - String - Name of the custom action parameter. Unique in the context of the parent custom action.

    • parameter_type - String - Custom action parameter type. Can be either fixed or dynamic.

    • encrypted - Boolean - Designates whether the custom action parameter value field is stored in an encrypted state.True if encrypted, false otherwise.

    • value - String - Value of the custom action parameter.

Response Sample

[ { "description": "String", "id": 42, "interpreter": 42, "name": "String", "parameters": [ { "encrypted": true, "name": "String", "parameter_type": "String", "value": "String" } ], "script": 42 } ]

POST /analytics/custom_actions/actions

Creates a new custom action with the supplied fields. The custom action must contain the following fields:

  • name - Required - String - Unique name of the custom action within the JSA deployment.

  • description - Optional - String - Description of the custom action.

  • interpreter - Required - Number - Unique ID of the custom action interpreter used by the custom action.

  • script - Required - Number - Unique ID of the custom action script used by the custom action.

  • parameters - Required - Array - Array of custom action parameters contained within the custom action. Each Custom action parameter must have the following fields:

    • name - Required - String - Name of the custom action parameter. Unique in the context of the parent custom action.

    • parameter_type - Required - String - Custom action parameter type. Can be either fixed or dynamic.

    • encrypted - Required - Boolean - Designates whether the custom action parameter value field is stored in an encrypted state.True if encrypted, false otherwise.

    • value - Required - String - Value of the custom action parameter. Custom action parameters with parameter_type fixed can have any value. Custom action parameters with parameter_type dynamic must have values corresponding to column names in an Ariel database, for example sourceip. Ariel database column names are available through the /api/ariel/databases/{database_name} endpoint.

Table 62: POST /analytics/custom_actions/actions Resource Details

MIME Type

application/json

Table 63: POST /analytics/custom_actions/actions 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 64: POST /analytics/custom_actions/actions Request Body Details

Parameter

Data Type

MIME Type

Description

Sample

custom_action

Object

application/json

Custom action JSON object containing the supplied fields (see above for more details).

{ "description": "String", "interpreter": 42, "name": "String", "parameters": [ { "encrypted": true, "name": "String", "parameter_type": "String", "value": "String" } ], "script": 42 }

Table 65: POST /analytics/custom_actions/actions Response Codes

HTTP Response Code

Unique Code

Description

201

 

A new custom action has been successfully created.

422

1005

One or more parameters are invalid in request.

500

1020

An internal server error occurred while posting custom action.

Response Description

The newly created custom action with the following fields:

  • id - Number - Unique ID of the custom action within the JSA deployment.

  • name - String - Unique name of the custom action within the JSA deployment.

  • description - String - Optional description attached to the custom action.

  • interpreter - Number - Unique ID of the custom action interpreter used by the custom action.

  • script - Number - Unique ID of the custom action script used by the custom action.

  • parameters - Array - Array of custom action parameters contained within the custom action. Each Custom action parameter has the following fields:

    • name - String - Name of the custom action parameter. Unique in the context of the parent custom action.

    • parameter_type - String - Custom action parameter type. Can be either fixed or dynamic.

    • encrypted - Boolean - Designates whether the custom action parameter value field is stored in an encrypted state.True if encrypted, false otherwise.

    • value - String - Value of the custom action parameter.

Response Sample

{ "description": "String", "id": 42, "interpreter": 42, "name": "String", "parameters": [ { "encrypted": true, "name": "String", "parameter_type": "String", "value": "String" } ], "script": 42 }

GET /analytics/custom_actions/actions/{action_id}

Retrieves a custom action based on the supplied action_id.

Table 66: GET /analytics/custom_actions/actions/{action_id} Resource Details

MIME Type

application/json

Table 67: GET /analytics/custom_actions/actions/{action_id} Request Parameter Details

Parameter

Type

Optionality

Data Type

MIME Type

Description

action_id

path

Required

Number (Integer)

text/plain

Long id of the custom action to be retrieved.

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 68: GET /analytics/custom_actions/actions/{action_id} Response Codes

HTTP Response Code

Unique Code

Description

200

 

The requested custom action has been successfully retrieved.

404

1002

The requested custom action could not be found.

500

1020

An internal server error occurred while retrieving custom action with supplied action_id.

Response Description

A custom action with containing following fields:

  • id - Number - Unique ID of the custom action within the JSA deployment.

  • name - String - Unique name of the custom action within the JSA deployment.

  • description - String - Optional description attached to the custom action.

  • interpreter - Number - Unique ID of the custom action interpreter used by the custom action.

  • script - Number - Unique ID of the custom action script used by the custom action.

  • parameters - Array - Array of custom action parameters contained within the custom action. Each Custom action parameter has the following fields:

    • name - String - Name of the custom action parameter. Unique in the context of the parent custom action.

    • parameter_type - String - Custom action parameter type. Can be either fixed or dynamic.

    • encrypted - Boolean - Designates whether the custom action parameter value field is stored in an encrypted state.True if encrypted, false otherwise.

    • value - String - Value of the custom action parameter.

Response Sample

{ "description": "String", "id": 42, "interpreter": 42, "name": "String", "parameters": [ { "encrypted": true, "name": "String", "parameter_type": "String", "value": "String" } ], "script": 42 }

POST /analytics/custom_actions/actions/{action_id}

Updates an existing custom action. The custom action should contain the following fields:

  • id - Required - Number - Unique ID of the custom action within the JSA deployment.

  • name - Optional - String - Unique name of the custom action within the JSA deployment.

  • description - Optional - String - Description of the custom action.

  • interpreter - Required - Number - Unique ID of the custom action interpreter used by the custom action.

  • script - Required - Number - Unique ID of the custom action script used by the custom action.

  • parameters - Required - Array - Array of custom action parameters contained within the custom action. Each Custom action parameter must have the following fields:

    • name - Required - String - Name of the custom action parameter. Unique in the context of the parent custom action.

    • parameter_type - Optional - String - Custom action parameter type. Can be either fixed or dynamic.

    • encrypted - Optional - Boolean - Designates whether the custom action parameter value field is stored in an encrypted state.True if encrypted, false otherwise.

    • value - Optional - String - Value of the custom action parameter. Custom action parameters with parameter_type fixed can have any value. Custom action parameters with parameter_type dynamic must have values corresponding to column names in an Ariel database, for example sourceip. Ariel database column names are available through the /api/ariel/databases/{database_name} endpoint.

Table 69: POST /analytics/custom_actions/actions/{action_id} Resource Details

MIME Type

application/json

Table 70: POST /analytics/custom_actions/actions/{action_id} Request Parameter Details

Parameter

Type

Optionality

Data Type

MIME Type

Description

action_id

path

Required

Number (Integer)

text/plain

Number id of the custom action to be updated.

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 71: POST /analytics/custom_actions/actions/{action_id} Request Body Details

Parameter

Data Type

MIME Type

Description

Sample

custom_action

Object

application/json

Custom action JSON object which can contain the supplied fields (see above for more details).

{ "description": "String", "id": 42, "interpreter": 42, "name": "String", "parameters": [ { "encrypted": true, "name": "String", "parameter_type": "String", "value": "String" } ], "script": 42 }

Table 72: POST /analytics/custom_actions/actions/{action_id} Response Codes

HTTP Response Code

Unique Code

Description

200

 

The custom action has been updated.

404

1002

The requested custom action could not be found.

422

1005

One or more parameters are invalid in request.

500

1020

An internal server error occurred while updating custom action with supplied action_id.

Response Description

The updated custom action with the following fields:

  • id - Number - Unique ID of the custom action within the JSA deployment.

  • name - String - Unique name of the custom action within the JSA deployment.

  • description - String - Optional description attached to the custom action.

  • interpreter - Number - Unique ID of the custom action interpreter used by the custom action.

  • script - Number - Unique ID of the custom action script used by the custom action.

  • parameters - Array - Array of custom action parameters contained within the custom action. Each Custom action parameter has the following fields:

    • name - String - Name of the custom action parameter. Unique in the context of the parent custom action.

    • parameter_type - String - Custom action parameter type. Can be either fixed or dynamic.

    • encrypted - Boolean - Designates whether the custom action parameter value field is stored in an encrypted state.True if encrypted, false otherwise.

    • value - String - Value of the custom action parameter.

Response Sample

{ "description": "String", "id": 42, "interpreter": 42, "name": "String", "parameters": [ { "encrypted": true, "name": "String", "parameter_type": "String", "value": "String" } ], "script": 42 }

DELETE /analytics/custom_actions/actions/{action_id}

Deletes an existing custom action.

Table 73: DELETE /analytics/custom_actions/actions/{action_id} Resource Details

MIME Type

text/plain

Table 74: DELETE /analytics/custom_actions/actions/{action_id} Request Parameter Details

Parameter

Type

Optionality

Data Type

MIME Type

Description

action_id

path

Required

Number (Integer)

text/plain

Number id of the custom action you wish to delete.

Table 75: DELETE /analytics/custom_actions/actions/{action_id} Response Codes

HTTP Response Code

Unique Code

Description

204

 

The custom action has been deleted.

404

1002

The requested custom action could not be found.

500

1020

An internal server error occurred while deleting custom action with supplied action_id.

Response Description

Empty response with 204 successful response code.

Response Sample

GET /analytics/custom_actions/interpreters

Retrieves a list of available custom action interpreters.

Table 76: GET /analytics/custom_actions/interpreters Resource Details

MIME Type

application/json

Table 77: GET /analytics/custom_actions/interpreters 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 78: GET /analytics/custom_actions/interpreters Response Codes

HTTP Response Code

Unique Code

Description

200

 

The requested list of custom action interpreters have been retrieved.

500

1020

An internal server error occurred while retrieving available custom action interpreters.

Response Description

Array of available custom action interpreters, each with the following fields:

  • id - Number - Unique ID of the custom action interpreter within the JSA deployment.

  • name - String - Name of the custom action interpreter.

Response Sample

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

GET /analytics/custom_actions/interpreters/{interpreter_id}

Retrieves a custom action interpreter based on supplied interpreter_id.

Table 79: GET /analytics/custom_actions/interpreters/{interpreter_id} Resource Details

MIME Type

application/json

Table 80: GET /analytics/custom_actions/interpreters/{interpreter_id} Request Parameter Details

Parameter

Type

Optionality

Data Type

MIME Type

Description

interpreter_id

path

Required

Number (Integer)

text/plain

Number id of custom action interpreter to be retrieved.

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 81: GET /analytics/custom_actions/interpreters/{interpreter_id} Response Codes

HTTP Response Code

Unique Code

Description

200

 

The requested custom action interpreter has been retrieved.

404

1002

The requested custom action interpreter could not be found.

500

1020

An internal server error occurred while retrieving custom action interpreter with supplied interpreter_id.

Response Description

A custom action interpreter with the following fields:

  • id - Number - Unique ID of the custom action interpreter within the JSA deployment.

  • name - String - Name of the custom action interpreter.

Response Sample

{ "id": 42, "name": "String" }

GET /analytics/custom_actions/scripts

Retrieves a list of meta-data for available custom action script files.

Table 82: GET /analytics/custom_actions/scripts Resource Details

MIME Type

application/json

Table 83: GET /analytics/custom_actions/scripts 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 84: GET /analytics/custom_actions/scripts Response Codes

HTTP Response Code

Unique Code

Description

200

 

The requested custom action script file has been retrieved.

500

1020

An internal server error occurred while retrieving available custom action script file meta-data.

Response Description

Array of available custom action script file meta-data, each with the following fields:

  • id - Number - Unique ID of the custom action script file within the JSA deployment.

  • name - String - Name of the custom action script file.

Response Sample

[ { "file_name": "String", "id": 42 } ]

POST /analytics/custom_actions/scripts

Creates a new custom action script file. Newly created custom action script files require a deployment before using. Users can include an optional HTTP header file_name containing the custom action script file name. If not specified this is defaulted to the script id of the uploaded file.

Table 85: POST /analytics/custom_actions/scripts Resource Details

MIME Type

application/json

Table 86: POST /analytics/custom_actions/scripts 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 87: POST /analytics/custom_actions/scripts Request Body Details

Parameter

Data Type

MIME Type

Description

Sample

file

File

application/

octet-stream

Required. The custom action script file. Must be supplied with MIME type application/octet-stream.

File

Table 88: POST /analytics/custom_actions/scripts Response Codes

HTTP Response Code

Unique Code

Description

201

 

A custom action script file has been created.

500

1020

An internal server error occurred while posting custom action script file.

Response Description

Custom action script file meta-data with the following fields:

  • id - Number - Unique ID of the custom action script within the JSA deployment.

  • name - String - Name of the custom action script.

Response Sample

{ "file_name": "String", "id": 42 }

GET /analytics/custom_actions/scripts/{script_id}

Retrieves meta-data of a custom action script file based on supplied script_id.

Table 89: GET /analytics/custom_actions/scripts/{script_id} Resource Details

MIME Type

application/json

Table 90: GET /analytics/custom_actions/scripts/{script_id} Request Parameter Details

Parameter

Type

Optionality

Data Type

MIME Type

Description

script_id

path

Required

Number (Integer)

text/plain

Number id of the custom action script file.

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 91: GET /analytics/custom_actions/scripts/{script_id} Response Codes

HTTP Response Code

Unique Code

Description

200

 

The requested custom action script file has been retrieved.

404

1002

The requested custom action script file could not be found.

500

1020

An internal server error occurred while retrieving custom action script file meta-data with supplied script_id.

Response Description

Custom action script file meta-data with the following fields:

  • id - Number - Unique ID of the custom action script file within the JSA deployment.

  • name - String - Name of the custom action script file.

Response Sample

{ "file_name": "String", "id": 42 }

POST /analytics/custom_actions/scripts/{script_id}

Updates an existing custom action script file. Updated custom action script files require a deployment before using. Users can include an optional HTTP header file_name containing the custom action script file name. If not specified this is defaulted to the script id of the uploaded file.

Table 92: POST /analytics/custom_actions/scripts/{script_id} Resource Details

MIME Type

application/json

Table 93: POST /analytics/custom_actions/scripts/{script_id} Request Parameter Details

Parameter

Type

Optionality

Data Type

MIME Type

Description

script_id

path

Required

Number (Integer)

text/plain

Number id of the custom action script file to be updated.

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 94: POST /analytics/custom_actions/scripts/{script_id} Request Body Details

Parameter

Data Type

MIME Type

Description

Sample

file

File

application/

octet-stream

Required. The custom action script file. Must be supplied with MIME type application/octet-stream.

File

Table 95: POST /analytics/custom_actions/scripts/{script_id} Response Codes

HTTP Response Code

Unique Code

Description

200

 

The custom action script file has been updated.

404

1002

The requested custom action script file could not be found.

500

1020

An internal server error occurred while updating custom action script file with supplied script_id.

Response Description

Custom action script file meta-data with the following fields:

  • id - Number - Unique ID of the custom action script file within the JSA deployment.

  • name - String - Name of the custom action script file.

Response Sample

{ "file_name": "String", "id": 42 }

DELETE /analytics/custom_actions/scripts/{script_id}

Deletes an existing custom action script file.

Table 96: DELETE /analytics/custom_actions/scripts/{script_id} Resource Details

MIME Type

text/plain

Table 97: DELETE /analytics/custom_actions/scripts/{script_id} Request Parameter Details

Parameter

Type

Optionality

Data Type

MIME Type

Description

script_id

path

Required

Number (Integer)

text/plain

Number id of the custom action script file to be deleted.

Table 98: DELETE /analytics/custom_actions/scripts/{script_id} Response Codes

HTTP Response Code

Unique Code

Description

204

 

The custom action script file has been deleted.

404

1002

The requested custom action script file could not be found.

422

1005

The requested custom action script file is tied to an existing custom action.

500

1020

An internal server error occurred while deleting custom action script file with supplied script_id.

Response Description

Empty response with a 204 successful response code.

Response Sample

GET /analytics/rule_groups

Retrieves a list of the rule groups.

Table 99: GET /analytics/rule_groups Resource Details

MIME Type

application/json

Table 100: GET /analytics/rule_groups 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 101: GET /analytics/rule_groups Response Codes

HTTP Response Code

Unique Code

Description

200

 

The rule rroups were returned.

500

1020

An error occurred during the attempt to retrieve the rule groups.

Response Description

List of the Group objects. A Group object contains the following fields:

  • id - Long - The ID of the group.

  • parent_id - Long - The ID of the parent group (default resources can have localized names).

  • type - String - The type of the group.

  • level - Long - The depth of the group in the group hierarchy.

  • name - String - The name of the group (default resources can have localized names).

  • description - String - The description of the group (default resources can have localized names).

  • owner - String - The owner of the group.

  • modified_time - Long - The time in milliseconds since epoch since the group was last modified.

  • child_group_ids - Array of Longs - List of the child group IDs.

Response Sample

[ { "child_groups": [ 42 ], "child_items": [ "String" ], "description": "String", "id": 42, "level": 42, "modified_time": 42, "name": "String", "owner": "String", "parent_id": 42, "type": "String <one of: LOG_SOURCE_GROUP, REPORT_GROUP, RULE_GROUP, EVENT_SAVED_SEARCH_GROUP, FLOW_SAVED_SEARCH_GROUP, OFFENSE_SAVED_SEARCH_GROUP, QRM_SAVED_SEARCH_GROUP, MODEL_SAVED_SEARCH_GROUP, QUESTION_SAVED_SEARCH_GROUP, SIMULATION_SAVED_SEARCH_GROUP, TOPOLOGY_SAVED_SEARCH_GROUP, ASSET_SAVED_SEARCH_GROUP, VULNERABILITY_SAVED_SEARCH_GROUP>" } ]

GET /analytics/rule_groups/{group_id}

Retrieves a rule group.

Table 102: GET /analytics/rule_groups/{group_id} Resource Details

MIME Type

application/json

Table 103: GET /analytics/rule_groups/{group_id} Request Parameter Details

Parameter

Type

Optionality

Data Type

MIME Type

Description

group_id

path

Required

Number (Integer)

text/plain

null

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 104: GET /analytics/rule_groups/{group_id} Response Codes

HTTP Response Code

Unique Code

Description

200

 

The rule group was retrieved.

404

1002

The rule group does not exist.

500

1020

An error occurred during the attempt to retrieve the rule group.

Response Description

A single Group object. A Group object contains the following fields:

  • id - Long - The ID of the group.

  • parent_id - Long - The ID of the parent group (default resources can have localized names).

  • type - String - The type of the group.

  • level - Long - The depth of the group in the group hierarchy.

  • name - String - The name of the group (default resources can have localized names).

  • description - String - The description of the group (default resources can have localized names).

  • owner - String - The owner of the group.

  • modified_time - Long - The time in milliseconds since epoch since the group was last modified.

  • child_group_ids - Array of Longs - List of the child group IDs.

Response Sample

{ "child_groups": [ 42 ], "child_items": [ "String" ], "description": "String", "id": 42, "level": 42, "modified_time": 42, "name": "String", "owner": "String", "parent_id": 42, "type": "String <one of: LOG_SOURCE_GROUP, REPORT_GROUP, RULE_GROUP, EVENT_SAVED_SEARCH_GROUP, FLOW_SAVED_SEARCH_GROUP, OFFENSE_SAVED_SEARCH_GROUP, QRM_SAVED_SEARCH_GROUP, MODEL_SAVED_SEARCH_GROUP, QUESTION_SAVED_SEARCH_GROUP, SIMULATION_SAVED_SEARCH_GROUP, TOPOLOGY_SAVED_SEARCH_GROUP, ASSET_SAVED_SEARCH_GROUP, VULNERABILITY_SAVED_SEARCH_GROUP>" }

POST /analytics/rule_groups/{group_id}

Updates the owner of a rule group.

Table 105: POST /analytics/rule_groups/{group_id} Resource Details

MIME Type

application/json

Table 106: POST /analytics/rule_groups/{group_id} Request Parameter Details

Parameter

Type

Optionality

Data Type

MIME Type

Description

group_id

path

Required

Number (Integer)

text/plain

null

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 107: POST /analytics/rule_groups/{group_id} Request Body Details

Parameter

Data Type

MIME Type

Description

Sample

group

Object

application/json

Required - Group object with the owner set to a valid deployed user.

{

  • "child_groups": [ 42 ],

  • "child_items": [ "String" ],

  • "description": "String",

  • "id": 42,

  • "level": 42,

  • "name": "String",

  • "owner": "String",

  • "parent_id": 42,

  • "type": "String <one of:

  • LOG_SOURCE_GROUP,

  • REPORT_GROUP,

  • RULE_GROUP,

  • EVENT_SAVED_SEARCH _GROUP,

  • FLOW_SAVED_SEARCH _GROUP,

  • OFFENSE_SAVED_SEARCH _GROUP,

  • QRM_SAVED_SEARCH _GROUP,

  • MODEL_SAVED_SEARCH_GROUP,

  • QUESTION_SAVED_SEARCH _GROUP,

  • SIMULATION_SAVED_SEARCH _GROUP,

  • TOPOLOGY_SAVED_SEARCH _GROUP,

  • ASSET_SAVED_SEARCH_GROUP,

  • VULNERABILITY_SAVED _SEARCH _GROUP>" }

Table 108: POST /analytics/rule_groups/{group_id} Response Codes

HTTP Response Code

Unique Code

Description

200

 

The rule group was updated.

404

1002

The rule group does not exist.

409

1004

The provided user does not have the required capabilities to own the rule group.

422

1005

A request parameter is not valid.

500

1020

An error occurred during the attempt to update the rule group.

Response Description

The updated Group object. A Group object contains the following fields:

  • id - Long - The ID of the group.

  • parent_id - Long - The ID of the parent group (default resources can have localized names).

  • type - String - The type of the group.

  • level - Long - The depth of the group in the group hierarchy.

  • name - String - The name of the group (default resources can have localized names).

  • description - String - The description of the group (default resources can have localized names).

  • owner - String - The owner of the group.

  • modified_time - Long - The time in milliseconds since epoch since the group was last modified.

  • child_group_ids - Array of Longs - List of the child group IDs.

Response Sample

{ "child_groups": [ 42 ], "child_items": [ "String" ], "description": "String", "id": 42, "level": 42, "modified_time": 42, "name": "String", "owner": "String", "parent_id": 42, "type": "String <one of: LOG_SOURCE_GROUP, REPORT_GROUP, RULE_GROUP, EVENT_SAVED_SEARCH_GROUP, FLOW_SAVED_SEARCH_GROUP, OFFENSE_SAVED_SEARCH_GROUP, QRM_SAVED_SEARCH_GROUP, MODEL_SAVED_SEARCH_GROUP, QUESTION_SAVED_SEARCH_GROUP, SIMULATION_SAVED_SEARCH_GROUP, TOPOLOGY_SAVED_SEARCH_GROUP, ASSET_SAVED_SEARCH_GROUP, VULNERABILITY_SAVED_SEARCH_GROUP>" }

DELETE /analytics/rule_groups/{group_id}

Deletes a rule. To ensure safe deletion, a dependency check is carried out. This check might take some time. An asynchronous task to do is started for this check.

Table 109: DELETE /analytics/rule_groups/{group_id} Resource Details

MIME Type

text/plain

Table 110: DELETE /analytics/rule_groups/{group_id} Request Parameter Details

Parameter

Type

Optionality

Data Type

MIME Type

Description

group_id

path

Required

Number (Integer)

text/plain

null

Table 111: DELETE /analytics/rule_groups/{group_id} Response Codes

HTTP Response Code

Unique Code

Description

202

 

The rule delete command was accepted and is in progress.

404

1002

The rule does not exist.

409

1004

null

500

1020

An error occurred during the attempt to delete the rule.

Response Description

A Delete Task Status object and the location header set to the task status url "/api/analytics/rules/rule_delete_tasks/{task_id}". A Delete Task Status object contains the following fields:

  • id - Long - The ID of the task.

  • message - String - The localized task message.

  • status - String - The current state of the task.

  • name - String - The name of the task.

  • created_by - String - The name of the user who started the task.

  • created - Long - The time in milliseconds since epoch since the task was created.

  • started - Long - The time in milliseconds since epoch since the task was started.

  • modified - Long - The time in milliseconds since epoch since the task was modified.

  • completed - Long - The time in milliseconds since epoch since the task was completed.

Response Sample

GET /analytics/rules

Retrieves a list of rules.

Table 112: GET /analytics/rules Resource Details

MIME Type

application/json

Table 113: GET /analytics/rules Request Parameter Details

Parameter

Type

Optionality

Data Type

MIME Type

Description

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.

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.

Table 114: GET /analytics/rules Response Codes

HTTP Response Code

Unique Code

Description

200

 

The rules were retrieved.

422

1010

A request parameter is not valid.

500

1020

An error occurred during the attempt to retrieve the rules.

Response Description

An array of rule objects. A rule object contains the following fields:

  • id - Long - The sequence ID of the rule.

  • name - String - The name of the rule.

  • type - String - The type of rule: EVENT, FLOW, COMMON, USER.

  • enabled - Boolean - True if the rule is enabled.

  • owner - String - The owner of the rule.

  • origin - String - The origin of the rule: SYSTEM, OVERRIDE, USER.

  • base_capacity - Long - The base capacity of the rule in events per second.

  • base_host_id - Long - The ID of the host from which the rule's base capacity was determined

  • average_capacity - Long - The moving average capacity, in EPS, of the rule across all hosts.

  • capacity_timestamp - Long - The epoch timestamp, in milliseconds, since the rule's capacity values were last updated.

  • identifier - String - The unique ID of the rule. This value is typically in the form of a UUID, with the exception of legacy system rules.

  • linked_rule_identifier - String - The linked ID of the rule. This value is typically in the form of a UUID, with the exception of legacy system rules, and varies depending on the rule's origin as follows:

    • SYSTEM - The identifier value of the override rule, if one exists. If the system rule has not been overridden, the value will be null.

    • OVERRIDE - The identifier value of the system rule being overridden.

    • USER - The value will be null.

  • creation_date - Long - The number of milliseconds since epoch when the rule was created.

  • modification_date - Long - The number of milliseconds since epoch when the rule was last modified.

Response Sample

[ { "average_capacity": 42, "base_capacity": 42, "base_host_id": 42, "capacity_timestamp": 42, "creation_date": 42, "enabled": true, "id": 42, "identifier": "String", "linked_rule_identifier": "String", "modification_date": 42, "name": "String", "origin": "String <one of: SYSTEM, OVERRIDE, USER>", "owner": "String", "type": "String <one of: EVENT, FLOW, COMMON, OFFENSE>" } ]

GET /analytics/rules/rule_delete_tasks/{task_id}

Retrieves the delete the rule task status.

Table 115: GET /analytics/rules/rule_delete_tasks/{task_id} Resource Details

MIME Type

application/json

Table 116: GET /analytics/rules/rule_delete_tasks/{task_id} Request Parameter Details

Parameter

Type

Optionality

Data Type

MIME Type

Description

task_id

path

Required

Number (Integer)

text/plain

null

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 117: GET /analytics/rules/rule_delete_tasks/{task_id} Response Codes

HTTP Response Code

Unique Code

Description

200

 

The delete task status was retrieved.

404

1002

The delete task status does not exist.

500

1020

An error occurred during the attempt to retrieve the delete task status.

Response Description

A Delete Task Status object and the location header set to the task status url "/api/analytics/rules/rule_delete_tasks/{task_id}". A Delete Task Status object contains the following fields:

  • id - Long - The ID of the task.

  • message - String - The localized task message.

  • status - String - The current state of the task.

  • name - String - The name of the task.

  • created_by - String - The name of the user who started the task.

  • created - Long - The time in milliseconds since epoch since the task was created.

  • started - Long - The time in milliseconds since epoch since the task was started.

  • modified - Long - The time in milliseconds since epoch since the task was modified.

  • completed - Long - The time in milliseconds since epoch since the task was completed.

Response Sample

{ "completed": 42, "created": 42, "created_by": "String", "id": 42, "message": "String", "modified": 42, "name": "String", "started": 42, "status": "String <one of: CANCELLED, CANCELING, CANCEL_REQUESTED, COMPLETED, CONFLICT, EXCEPTION, INITIALIZING, INTERRUPTED, PAUSED, PROCESSING, QUEUED, RESUMING>" }

GET /analytics/rules/rule_dependent_tasks/{task_id}

Retrieves the dependent rule task status.

Table 118: GET /analytics/rules/rule_dependent_tasks/{task_id} Resource Details

MIME Type

application/json

Table 119: GET /analytics/rules/rule_dependent_tasks/{task_id} Request Parameter Details

Parameter

Type

Optionality

Data Type

MIME Type

Description

task_id

path

Required

Number (Integer)

text/plain

null

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 120: GET /analytics/rules/rule_dependent_tasks/{task_id} Response Codes

HTTP Response Code

Unique Code

Description

200

 

The delete task status was retrieved.

404

1002

The delete task status does not exist.

500

1020

An error occurred during the attempt to retrieve the delete task status.

Response Description

A Dependent Task Status object and the location header set to the task status url "/api/analytics/rules/rule_dependent_tasks/{task_id}". A Dependent Task Status object contains the following fields:

  • id - Long - The ID of the task.

  • message - String - The localized task message.

  • status - String - The current state of the task.

  • name - String - The name of the task.

  • created_by - String - The name of the user who started the task.

  • cancelled_by - String - The name of the user who requested the cancellation of the task.

  • created - Long - The time in milliseconds since epoch since the task was created.

  • started - Long - The time in milliseconds since epoch since the task was started.

  • modified - Long - The time in milliseconds since epoch since the task was modified.

  • completed - Long - The time in milliseconds since epoch since the task was completed.

  • number_of_dependents - Long - The number of dependents found. the value is null until the task completes.

  • maximum - Long - The maximum number of objects to check for dependency.

  • progress - Long - The number of objects that were checked for dependency.

  • task_components - Array - An array of task component objects. A task component object contains the following fields:

    • message - String - The localized sub-task status message.

    • status - String - The current state of the sub-task.

    • sub_task_type - String - The type of the sub-task

    • maximum - Long - The maximum number of objects to check for dependency.

    • progress - Long - The number of objects that were checked for dependency.

    • created - Long - The time in milliseconds since epoch since the sub-task was created.

    • started - Long - The time in milliseconds since epoch since the sub-task was started.

    • modified - Long - The time in milliseconds since epoch since the sub-task was modified.

    • completed - Long - The time in milliseconds since epoch since the sub-task was completed.

Response Sample

{ "cancelled_by": "String", "completed": 42, "created": 42, "created_by": "String", "id": 42, "maximum": 42, "message": "String", "modified": 42, "name": "String", "number_of_dependents": 42, "progress": 42, "started": 42, "status": "String <one of: CANCELLED, CANCELING, CANCEL_REQUESTED, COMPLETED, CONFLICT, EXCEPTION, INITIALIZING, INTERRUPTED, PAUSED, PROCESSING, QUEUED, RESUMING>", "task_components": [ { "completed": 42, "created": 42, "maximum": 42, "message": "String", "modified": 42, "number_of_dependents": 42, "progress": 42, "started": 42, "status": "String <one of: CANCELLED, CANCELING, CANCEL_REQUESTED, COMPLETED, CONFLICT, EXCEPTION, INITIALIZING, INTERRUPTED, PAUSED, PROCESSING, QUEUED, RESUMING>", "task_sub_type": "String <one of: FIND_DEPENDENT_ARIEL_SAVED_SEARCHES, FIND_DEPENDENT_OFFENSE_SAVED_SEARCHES, FIND_DEPENDENT_ASSET_SAVED_SEARCHES, FIND_DEPENDENT_VULNERABILITY_SAVED_SEARCHES, FIND_DEPENDENT_ADE_RULES, FIND_DEPENDENT_RULES, FIND_DEPENDENT_CALCULATED_PROPERTIES, FIND_DEPENDENT_LOG_SOURCE_GROUPS, FIND_DEPENDENT_CUSTOM_PROPERTIES, FIND_DEPENDENT_REPORTS, FIND_DEPENDENT_DASHBOARDS, FIND_DEPENDENT_STORE_AND_FORWARD_POLICIES, FIND_DEPENDENT_AUTHORIZED_SERVICES, FIND_DEPENDENT_OFFENSE_TYPES, FIND_DEPENDENT_ASSIGNED_OFFENSES, FIND_DEPENDENT_VULNERABILITIES, FIND_DEPENDENT_GROUPS, FIND_DEPENDENT_HISTORICAL_CORRELATION_PROFILES>" } ] }

POST /analytics/rules/rule_dependent_tasks/{task_id}

Cancels the dependent the rule task.

Table 121: POST /analytics/rules/rule_dependent_tasks/{task_id} Resource Details

MIME Type

application/json

Table 122: POST /analytics/rules/rule_dependent_tasks/{task_id} Request Parameter Details

Parameter

Type

Optionality

Data Type

MIME Type

Description

task_id

path

Required

Number (Integer)

text/plain

null

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 123: POST /analytics/rules/rule_dependent_tasks/{task_id} Request Body Details

Parameter

Data Type

MIME Type

Description

Sample

task

Object

application/json

null

{ "status": "String <one of: CANCELLED, CANCELING, CANCEL_REQUESTED, COMPLETED, CONFLICT, EXCEPTION, INITIALIZING, INTERRUPTED, PAUSED, PROCESSING, QUEUED, RESUMING>" }

Table 124: POST /analytics/rules/rule_dependent_tasks/{task_id} Response Codes

HTTP Response Code

Unique Code

Description

200

 

The dependent task status was retrieved.

404

1002

The dependent task status does not exist.

409

1004

The task is in a completed state.

422

1005

A request parameter is not valid.

500

1020

An error occurred during the attempt to update the dependent task status.

Response Description

A Dependent Task Status object and the location header set to the task status url "/api/analytics/rules/rule_dependent_tasks/{task_id}". A Dependent Task Status object contains the following fields:

  • id - Long - The ID of the task.

  • message - String - The localized task message.

  • status - String - The current state of the task.

  • name - String - The name of the task.

  • created_by - String - The name of the user who started the task.

  • cancelled_by - String - The name of the user who requested cancellation of the task.

  • created - Long - The time in milliseconds since epoch since the task was created.

  • started - Long - The time in milliseconds since epoch since the task was started.

  • modified - Long - The time in milliseconds since epoch since the task was modified.

  • completed - Long - The time in milliseconds since epoch since the task was completed.

  • number_of_dependents - Long - The number of dependents found. The value is null until the task completes.

  • maximum - Long - The maximum number of objects to check for dependency.

  • progress - Long - The number of objects that were checked for dependency.

  • task_components - Array - An array of task component objects. A task component object contains the following fields:

    • message - String - The localized sub-task status message.

    • status - String - The current state of the sub-task.

    • sub_task_type - String - The type of the sub-task

    • maximum - Long - The maximum number of objects to check for dependency.

    • progress - Long - The number of objects that were checked for dependency.

    • created - Long - The time in milliseconds since epoch since the sub-task was created.

    • started - Long - The time in milliseconds since epoch since the sub-task was started.

    • modified - Long - The time in milliseconds since epoch since the sub-task was modified.

    • completed - Long - The time in milliseconds since epoch since the sub-task was completed.

Response Sample

{ "cancelled_by": "String", "completed": 42, "created": 42, "created_by": "String", "id": 42, "maximum": 42, "message": "String", "modified": 42, "name": "String", "number_of_dependents": 42, "progress": 42, "started": 42, "status": "String <one of: CANCELLED, CANCELING, CANCEL_REQUESTED, COMPLETED, CONFLICT, EXCEPTION, INITIALIZING, INTERRUPTED, PAUSED, PROCESSING, QUEUED, RESUMING>", "task_components": [ { "completed": 42, "created": 42, "maximum": 42, "message": "String", "modified": 42, "number_of_dependents": 42, "progress": 42, "started": 42, "status": "String <one of: CANCELLED, CANCELING, CANCEL_REQUESTED, COMPLETED, CONFLICT, EXCEPTION, INITIALIZING, INTERRUPTED, PAUSED, PROCESSING, QUEUED, RESUMING>", "task_sub_type": "String <one of: FIND_DEPENDENT_ARIEL_SAVED_SEARCHES, FIND_DEPENDENT_OFFENSE_SAVED_SEARCHES, FIND_DEPENDENT_ASSET_SAVED_SEARCHES, FIND_DEPENDENT_VULNERABILITY_SAVED_SEARCHES, FIND_DEPENDENT_ADE_RULES, FIND_DEPENDENT_RULES, FIND_DEPENDENT_CALCULATED_PROPERTIES, FIND_DEPENDENT_LOG_SOURCE_GROUPS, FIND_DEPENDENT_CUSTOM_PROPERTIES, FIND_DEPENDENT_REPORTS, FIND_DEPENDENT_DASHBOARDS, FIND_DEPENDENT_STORE_AND_FORWARD_POLICIES, FIND_DEPENDENT_AUTHORIZED_SERVICES, FIND_DEPENDENT_OFFENSE_TYPES, FIND_DEPENDENT_ASSIGNED_OFFENSES, FIND_DEPENDENT_VULNERABILITIES, FIND_DEPENDENT_GROUPS, FIND_DEPENDENT_HISTORICAL_CORRELATION_PROFILES>" } ] }

GET /analytics/rules/rule_dependent_tasks/{task_id}/results

Retrieves the rule dependent task results.

Table 125: GET /analytics/rules/rule_dependent_tasks/{task_id}/results Resource Details

MIME Type

application/json

Table 126: GET /analytics/rules/rule_dependent_tasks/{task_id}/results Request Parameter Details

Parameter

Type

Optionality

Data Type

MIME Type

Description

task_id

path

Required

Number (Integer)

text/plain

null

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 127: GET /analytics/rules/rule_dependent_tasks/{task_id}/results Response Codes

HTTP Response Code

Unique Code

Description

200

 

The rule dependents were retrieved.

404

1002

The dependent task status does not exist.

500

1020

An error occurred during the attempt to retrieve the rules.

Response Description

An list of Dependent objects. A Dependent object contains the following fields:

  • dependent_id - String - The ID of the dependent resource.

  • dependent_name - String - The name of the dependent resource (default resources can have localized names).

  • dependent_owner - String - The owner of the dependent resource.

  • dependent_type - String - The type of the dependent resource.

  • dependent_database - String - The database of the dependent resource.

  • dependent_group_ids - Array of Longs - List of groups that the dependent resource belongs to.

  • user_has_edit_permissions - Boolean - The true if the user who created the task has permission to edit this dependent resource.

Response Sample

[ { "blocking": true, "dependent_database": "String <one of: EVENTS, FLOWS>", "dependent_group_ids": [ 42 ], "dependent_id": "String", "dependent_name": "String", "dependent_owner": "String", "dependent_type": "String <one of: ARIEL_SAVED_SEARCH, ASSET_SAVED_SEARCH, OFFENSE_SAVED_SEARCH, VULNERABILITY_SAVED_SEARCH, QRM_SAVED_SEARCH_GROUP, ASSET_SAVED_SEARCH_GROUP, CUSTOM_RULE_GROUP, EVENT_ARIEL_SAVED_SEARCH_GROUP, FLOW_ARIEL_SAVED_SEARCH_GROUP, LOG_SOURCE_GROUP, MODEL_GROUP, OFFENSE_SAVED_SEARCH_GROUP, QUESTION_GROUP, REPORT_GROUP, SIMULATION_GROUP, TOPOLOGY_SAVED_SEARCH_GROUP, VULNERABILITY_SAVED_SEARCH_GROUP, ASSIGNED_OFFENSE, ASSIGNED_VULNERABILITY, AUTHORIZED_SERVICE, BUILDING_BLOCK, CRE_RULE, CRE_ADE_RULE, EVENT_REGEX_PROPERTY, EVENT_CALCULATED_PROPERTY, FLOW_REGEX_PROPERTY, FLOW_CALCULATED_PROPERTY, DASHBOARD, GV_REFERENCE, REPORT, REFERENCE_DATA, REFERENCE_DATA_MAP_OF_SETS, REFERENCE_DATA_MAPS, REFERENCE_DATA_SETS, REFERENCE_DATA_TABLES, REFERENCE_DATA_RESPONSE, REFERENCE_SET_RESPONSE, EVENT_RETENTION_BUCKET, FLOW_RETENTION_BUCKET, ROUTING_RULE, STORE_AND_FORWARD_POLICY, USER, HISTORICAL_PROFILE, OFFENSE_TYPE>", "user_has_edit_permissions": true } ]

GET /analytics/rules/{id}

Retrieves a rule.

Table 128: GET /analytics/rules/{id} Resource Details

MIME Type

application/json

Table 129: GET /analytics/rules/{id} Request Parameter Details

Parameter

Type

Optionality

Data Type

MIME Type

Description

id

path

Required

Number (Integer)

text/plain

null

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 130: GET /analytics/rules/{id} Response Codes

HTTP Response Code

Unique Code

Description

200

 

The rule was retrieved.

404

1002

The rule does not exist.

500

1020

An error occurred during the attempt to retrieve the rule.

Response Description

The rule after it is retrieved. A rule object contains the following fields:

  • id - Long - The sequence ID of the rule.

  • name - String - The name of the rule.

  • type - String - The type of rule: EVENT, FLOW, COMMON, USER.

  • enabled - Boolean - True if the rule is enabled.

  • owner - String - The owner of the rule.

  • origin - String - The origin of the rule: SYSTEM, OVERRIDE, USER.

  • base_capacity - Long - The base capacity of the rule in events per second.

  • base_host_id - Long - The ID of the host from which the rule's base capacity was determined

  • average_capacity - Long - The moving average capacity, in EPS, of the rule across all hosts.

  • capacity_timestamp - Long - The epoch timestamp, in milliseconds, since the rule's capacity values were last updated.

  • identifier - String - The unique ID of the rule. This value is typically in the form of a UUID, with the exception of legacy system rules.

  • linked_rule_identifier - String - The linked ID of the rule. This value is typically in the form of a UUID, with the exception of legacy system rules, and varies depending on the rule's origin as follows:

    • SYSTEM - The identifier value of the override rule, if one exists. If the system rule has not been overridden, the value will be null.

    • OVERRIDE - The identifier value of the system rule being overridden.

    • USER - The value will be null.

  • creation_date - Long - The number of milliseconds since epoch when the rule was created.

  • modification_date - Long - The number of milliseconds since epoch when the rule was last modified.

Response Sample

{ "average_capacity": 42, "base_capacity": 42, "base_host_id": 42, "capacity_timestamp": 42, "creation_date": 42, "enabled": true, "id": 42, "identifier": "String", "linked_rule_identifier": "String", "modification_date": 42, "name": "String", "origin": "String <one of: SYSTEM, OVERRIDE, USER>", "owner": "String", "type": "String <one of: EVENT, FLOW, COMMON, OFFENSE>" }

POST /analytics/rules/{id}

Updates the rule owner or enabled/disabled only.

Table 131: POST /analytics/rules/{id} Resource Details

MIME Type

application/json

Table 132: POST /analytics/rules/{id} Request Parameter Details

Parameter

Type

Optionality

Data Type

MIME Type

Description

id

path

Required

Number (Integer)

text/plain

null

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 133: POST /analytics/rules/{id} Request Body Details

Parameter

Data Type

MIME Type

Description

Sample

rule

Object

application/json

Required - Rule object.

{ "average_capacity": 42, "base_capacity": 42, "base_host_id": 42, "capacity_timestamp": 42, "creation_date": 42, "enabled": true, "id": 42, "identifier": "String", "linked_rule_identifier": "String", "modification_date": 42, "name": "String", "origin": "String <one of: SYSTEM, OVERRIDE, USER>", "owner": "String", "type": "String <one of: EVENT, FLOW, COMMON, OFFENSE>" }

Table 134: POST /analytics/rules/{id} Response Codes

HTTP Response Code

Unique Code

Description

200

 

The rule was updated.

403

1009

You do not have the required capabilities to update the rule.

404

1002

The rule does not exist.

409

1004

The provided user does not have the required capabilities to own the rule.

422

1005

A request parameter is not valid.

500

1020

An error occurred during the attempt to update the rule.

Response Description

The rule after it is updated. An Rule object contains the following fields:

  • id - Long - The sequence ID of the rule.

  • name - String - The name of the rule.

  • type - String - The type of rule: EVENT, FLOW, COMMON, USER.

  • enabled - Boolean - True if the rule is enabled.

  • owner - String - The owner of the rule.

  • origin - String - The origin of the rule: SYSTEM, OVERRIDE, USER.

  • base_capacity - Long - The base capacity of the rule in events per second.

  • base_host_id - Long - The ID of the host from which the rule's base capacity was determined

  • average_capacity - Long - The moving average capacity, in EPS, of the rule across all hosts.

  • capacity_timestamp - Long - The epoch timestamp, in milliseconds, since the rule's capacity values were last updated.

  • identifier - String - The unique ID of the rule. This value is typically in the form of a UUID, with the exception of legacy system rules.

  • linked_rule_identifier - String - The linked ID of the rule. This value is typically in the form of a UUID, with the exception of legacy system rules, and varies depending on the rule's origin as follows:

    • SYSTEM - The identifier value of the override rule, if one exists. If the system rule has not been overridden, the value will be null.

    • OVERRIDE - The identifier value of the system rule being overridden.

    • USER - The value will be null.

  • creation_date - Long - The number of milliseconds since epoch when the rule was created.

  • modification_date - Long - The number of milliseconds since epoch when the rule was last modified.

Response Sample

{ "average_capacity": 42, "base_capacity": 42, "base_host_id": 42, "capacity_timestamp": 42, "creation_date": 42, "enabled": true, "id": 42, "identifier": "String", "linked_rule_identifier": "String", "modification_date": 42, "name": "String", "origin": "String <one of: SYSTEM, OVERRIDE, USER>", "owner": "String", "type": "String <one of: EVENT, FLOW, COMMON, OFFENSE>" }

DELETE /analytics/rules/{id}

Delete the rule. To ensure safe deletion, a dependency check is carried out. This check might take some time. An asynchronous task to do is started for this check.

Table 135: DELETE /analytics/rules/{id} Resource Details

MIME Type

application/json

Table 136: DELETE /analytics/rules/{id} Request Parameter Details

Parameter

Type

Optionality

Data Type

MIME Type

Description

id

path

Required

Number (Integer)

text/plain

null

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 137: DELETE /analytics/rules/{id} Response Codes

HTTP Response Code

Unique Code

Description

202

 

The rule delete command was accepted and is in progress.

403

1009

You do not have the required capabilities to delete the rule.

404

1002

The rule does not exist.

409

1004

null

500

1020

An error occurred during the attempt to delete the rule.

Response Description

A Delete Task Status object and the location header set to the task status url "/api/analytics/rules/rule_delete_tasks/{task_id}". A Delete Task Status object contains the following fields:

  • id - Long - The ID of the task.

  • message - String - The localized task message.

  • status - String - The current state of the task.

  • name - String - The name of the task.

  • created_by - String - The name of the user who started the task.

  • created - Long - The time in milliseconds since epoch since the task was created.

  • started - Long - The time in milliseconds since epoch since the task was started.

  • modified - Long - The time in milliseconds since epoch since the task was modified.

  • completed - Long - The time in milliseconds since epoch since the task was completed.

Response Sample

{ "completed": 42, "created": 42, "created_by": "String", "id": 42, "message": "String", "modified": 42, "name": "String", "started": 42, "status": "String <one of: CANCELLED, CANCELING, CANCEL_REQUESTED, COMPLETED, CONFLICT, EXCEPTION, INITIALIZING, INTERRUPTED, PAUSED, PROCESSING, QUEUED, RESUMING>" }

GET /analytics/rules/{id}/dependents

Retrieves the objects that depend on the rule.

Table 138: GET /analytics/rules/{id}/dependents Resource Details

MIME Type

application/json

Table 139: GET /analytics/rules/{id}/dependents Request Parameter Details

Parameter

Type

Optionality

Data Type

MIME Type

Description

id

path

Required

Number (Integer)

text/plain

null

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 140: GET /analytics/rules/{id}/dependents Response Codes

HTTP Response Code

Unique Code

Description

202

 

The rule dependents retrieval was accepted and is in progress.

403

1009

null

404

1002

The rule does not exist.

500

1020

An error occurred during the attempt to initiate the rule dependents retrieval task.

Response Description

A Dependents Task Status object and the location header set to the task status url "/api/analytics/rules/rule_dependents_tasks/{task_id}". A Dependent Task Status object contains the following fields:

  • id - Long - The ID of the task.

  • message - String - The localized task message.

  • status - String - The current state of the task.

  • name - String - The name of the task.

  • created_by - String - The name of the user who started the task.

  • cancelled_by - String - The name of the user who requested the cancellation of the task.

  • created - Long - The time in milliseconds since epoch since the task was created.

  • started - Long - The time in milliseconds since epoch since the task was started.

  • modified - Long - The time in milliseconds since epoch since the task was modified.

  • completed - Long - The time in milliseconds since epoch since the task was completed.

  • number_of_dependents - Long - The number of dependents found. the value is null until the task completes.

  • maximum - Long - The maximum number of objects to check for dependency.

  • progress - Long - The number of objects that were checked for dependency.

  • task_components - Array - An array of Task Component objects. A Task Component object contains the following fields:

    • message - String - The localized sub-task status message.

    • status - String - The current state of the sub-task.

    • sub_task_type - String - The type of the sub-task

    • maximum - Long - The maximum number of objects to check for dependency.

    • progress - Long - The number of objects that were checked for dependency.

    • created - Long - The time in milliseconds since epoch since the sub-task was created.

    • started - Long - The time in milliseconds since epoch since the sub-task was started.

    • modified - Long - The time in milliseconds since epoch since the sub-task was modified.

    • completed - Long - The time in milliseconds since epoch since the sub-task was completed.

Response Sample

{ "cancelled_by": "String", "completed": 42, "created": 42, "created_by": "String", "id": 42, "maximum": 42, "message": "String", "modified": 42, "name": "String", "number_of_dependents": 42, "progress": 42, "started": 42, "status": "String <one of: CANCELLED, CANCELING, CANCEL_REQUESTED, COMPLETED, CONFLICT, EXCEPTION, INITIALIZING, INTERRUPTED, PAUSED, PROCESSING, QUEUED, RESUMING>", "task_components": [ { "completed": 42, "created": 42, "maximum": 42, "message": "String", "modified": 42, "number_of_dependents": 42, "progress": 42, "started": 42, "status": "String <one of: CANCELLED, CANCELING, CANCEL_REQUESTED, COMPLETED, CONFLICT, EXCEPTION, INITIALIZING, INTERRUPTED, PAUSED, PROCESSING, QUEUED, RESUMING>", "task_sub_type": "String <one of: FIND_DEPENDENT_ARIEL_SAVED_SEARCHES, FIND_DEPENDENT_OFFENSE_SAVED_SEARCHES, FIND_DEPENDENT_ASSET_SAVED_SEARCHES, FIND_DEPENDENT_VULNERABILITY_SAVED_SEARCHES, FIND_DEPENDENT_ADE_RULES, FIND_DEPENDENT_RULES, FIND_DEPENDENT_CALCULATED_PROPERTIES, FIND_DEPENDENT_LOG_SOURCE_GROUPS, FIND_DEPENDENT_CUSTOM_PROPERTIES, FIND_DEPENDENT_REPORTS, FIND_DEPENDENT_DASHBOARDS, FIND_DEPENDENT_STORE_AND_FORWARD_POLICIES, FIND_DEPENDENT_AUTHORIZED_SERVICES, FIND_DEPENDENT_OFFENSE_TYPES, FIND_DEPENDENT_ASSIGNED_OFFENSES, FIND_DEPENDENT_VULNERABILITIES, FIND_DEPENDENT_GROUPS, FIND_DEPENDENT_HISTORICAL_CORRELATION_PROFILES>" } ] }

Ariel Endpoints

Use the references for REST API V9.2 Ariel endpoints.

GET /ariel/databases

Retrieves a list of available Ariel database names

Table 141: GET /ariel/databases Resource Details

MIME Type

application/json

Table 142: GET /ariel/databases Request Parameter Details

Parameter

Type

Optionality

Data Type

MIME Type

Description

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.

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.

Table 143: GET /ariel/databases Response Codes

HTTP Response Code

Unique Code

Description

200

 

The database list was retrieved.

Response Description

The names of the available Ariel databases.

Response Sample

[ "String" ]

GET /ariel/databases/{database_name}

Retrieves the columns that are defined for the specified Ariel database. This is the set of columns that can be explicitly named in the column list of a SELECT query.

Table 144: GET /ariel/databases/{database_name} Resource Details

MIME Type

application/json

Table 145: GET /ariel/databases/{database_name} Request Parameter Details

Parameter

Type

Optionality

Data Type

MIME Type

Description

database_name

path

Required

String

text/plain

Required. The name of the Ariel database that contains the columns that you want 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.

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.

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.

Table 146: GET /ariel/databases/{database_name} Response Codes

HTTP Response Code

Unique Code

Description

200

 

The database columns were retrieved.

404

1002

The database does not exist.

Response Description

A list of columns that are defined for the specified database. Multiple properties of each column are returned. For example, the column name or an indication that the column is indexable.

Response Sample

{ "columns": [ { "argument_type": "String", "indexable": true, "name": "String" } ] }

GET /ariel/event_saved_search_groups

Retrieves a list the event Ariel saved search groups.

Table 147: GET /ariel/event_saved_search_groups Resource Details

MIME Type

application/json

Table 148: GET /ariel/event_saved_search_groups Request Parameter Details

Parameter

Type

Optionality

Data Type

MIME Type

Description

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.

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.

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.

Table 149: GET /ariel/event_saved_search_groups Response Codes

HTTP Response Code

Unique Code

Description

200

 

The event Ariel saved search groups were returned.

500

1020

An error occurred during the attempt to retrieve the event Ariel saved search groups.

Response Description

List of the Group objects. A Group object contains the following fields:

  • id - Long - The ID of the group.

  • parent_id - Long - The ID of the parent group (default resources can have localized names).

  • type - String - The type of the group.

  • level - Long - The depth of the group in the group hierarchy.

  • name - String - The name of the group (default groups can have localized names).

  • description - String - The description of the group (default groups can have localized names).

  • owner - String - The owner of the group.

  • modified_time - Long - The time in milliseconds since epoch since the group was last modified.

  • child_group_ids - Array of Longs - List of the child group ids.

Response Sample

[ { "child_groups": [ 42 ], "child_items": [ "String" ], "description": "String", "id": 42, "level": 42, "modified_time": 42, "name": "String", "owner": "String", "parent_id": 42, "type": "String <one of: LOG_SOURCE_GROUP, REPORT_GROUP, RULE_GROUP, EVENT_SAVED_SEARCH_GROUP, FLOW_SAVED_SEARCH_GROUP, OFFENSE_SAVED_SEARCH_GROUP, QRM_SAVED_SEARCH_GROUP, MODEL_SAVED_SEARCH_GROUP, QUESTION_SAVED_SEARCH_GROUP, SIMULATION_SAVED_SEARCH_GROUP, TOPOLOGY_SAVED_SEARCH_GROUP, ASSET_SAVED_SEARCH_GROUP, VULNERABILITY_SAVED_SEARCH_GROUP>" } ]

GET /ariel/event_saved_search_groups/{group_id}

Retrieves an event Ariel saved search group.

Table 150: GET /ariel/event_saved_search_groups/{group_id} Resource Details

MIME Type

application/json

Table 151: GET /ariel/event_saved_search_groups/{group_id} Request Parameter Details

Parameter

Type

Optionality

Data Type

MIME Type

Description

group_id

path

Required

Number (Integer)

text/plain

null

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 152: GET /ariel/event_saved_search_groups/{group_id} Response Codes

HTTP Response Code

Unique Code

Description

200

 

The event Ariel saved search group was retrieved.

404

1002

The vent Ariel saved search group does not exist.

500

1020

An error occurred during the attempt to retrieve the event Ariel saved search groups.

Response Description

A single Group object. A Group object contains the following fields:

  • id - Long - The ID of the group.

  • parent_id - Long - The ID of the parent group (default resources can have localized names).

  • type - String - The type of the group.

  • level - Long - The depth of the group in the group hierarchy.

  • name - String - The name of the group (default resources can have localized names).

  • description - String - The description of the group (default resources can have localized names).

  • owner - String - The owner of the group.

  • modified_time - Long - The time in milliseconds since epoch since the group was last modified.

  • child_group_ids - Array of Longs - List of the child group IDs.

Response Sample

{ "child_groups": [ 42 ], "child_items": [ "String" ], "description": "String", "id": 42, "level": 42, "modified_time": 42, "name": "String", "owner": "String", "parent_id": 42, "type": "String <one of: LOG_SOURCE_GROUP, REPORT_GROUP, RULE_GROUP, EVENT_SAVED_SEARCH_GROUP, FLOW_SAVED_SEARCH_GROUP, OFFENSE_SAVED_SEARCH_GROUP, QRM_SAVED_SEARCH_GROUP, MODEL_SAVED_SEARCH_GROUP, QUESTION_SAVED_SEARCH_GROUP, SIMULATION_SAVED_SEARCH_GROUP, TOPOLOGY_SAVED_SEARCH_GROUP, ASSET_SAVED_SEARCH_GROUP, VULNERABILITY_SAVED_SEARCH_GROUP>" }

POST /ariel/event_saved_search_groups/{group_id}

Updates the owner of an event Ariel saved search group.

Table 153: POST /ariel/event_saved_search_groups/{group_id} Resource Details

MIME Type

application/json

Table 154: POST /ariel/event_saved_search_groups/{group_id} Request Parameter Details

Parameter

Type

Optionality

Data Type

MIME Type

Description

group_id

path

Required

Number (Integer)

text/plain

null

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 155: POST /ariel/event_saved_search_groups/{group_id} Request Body Details

Parameter

Data Type

MIME Type

Description

Sample

group

Object

application

/json

Required - Group object with the owner set to a valid deployed user.

{

  • "child_groups": [ 42 ],

  • "child_items": [ "String" ],

  • "description": "String",

  • "id": 42,

  • "level": 42,

  • "name": "String",

  • "owner": "String",

  • "parent_id": 42,

  • "type": "String <one of:

  • LOG_SOURCE_GROUP,

  • REPORT_GROUP,

  • RULE_GROUP,

  • EVENT_SAVED_SEARCH _GROUP,

  • FLOW_SAVED_SEARCH _GROUP,

  • OFFENSE_SAVED_SEARCH _GROUP,

  • QRM_SAVED_SEARCH _GROUP,

  • MODEL_SAVED_SEARCH_GROUP,

  • QUESTION_SAVED_SEARCH _GROUP,

  • SIMULATION_SAVED_SEARCH _GROUP,

  • TOPOLOGY_SAVED_SEARCH _GROUP,

  • ASSET_SAVED_SEARCH_GROUP,

  • VULNERABILITY_SAVED _SEARCH _GROUP>" }

Table 156: POST /ariel/event_saved_search_groups/{group_id} Response Codes

HTTP Response Code

Unique Code

Description

200

 

The event Ariel saved search group was updated.

404

1002

The event Ariel saved search group does not exist.

409

1004

The provided user does not have the required capabilities to own the Eevent Ariel saved search group.

422

1005

A request parameter is not valid.

500

1020

An error occurred during the attempt to update the event Ariel saved search group.

Response Description

The updated Group object. A Group object contains the following fields:

  • id - Long - The ID of the group.

  • parent_id - Long - The id of the parent group (default resources can have localized names).

  • type - String - The type of the group.

  • level - Long - The depth of the group in the group hierarchy.

  • name - String - The name of the group (default resources can have localized names).

  • description - String - The description of the group (default resources can have localized names).

  • owner - String - The owner of the group.

  • modified_time - Long - The time in milliseconds since epoch since the group was last modified.

  • child_group_ids - Array of Longs - List of the child group ids.

Response Sample

{ "child_groups": [ 42 ], "child_items": [ "String" ], "description": "String", "id": 42, "level": 42, "modified_time": 42, "name": "String", "owner": "String", "parent_id": 42, "type": "String <one of: LOG_SOURCE_GROUP, REPORT_GROUP, RULE_GROUP, EVENT_SAVED_SEARCH_GROUP, FLOW_SAVED_SEARCH_GROUP, OFFENSE_SAVED_SEARCH_GROUP, QRM_SAVED_SEARCH_GROUP, MODEL_SAVED_SEARCH_GROUP, QUESTION_SAVED_SEARCH_GROUP, SIMULATION_SAVED_SEARCH_GROUP, TOPOLOGY_SAVED_SEARCH_GROUP, ASSET_SAVED_SEARCH_GROUP, VULNERABILITY_SAVED_SEARCH_GROUP>" }

DELETE /ariel/event_saved_search_groups/{group_id}

Deletes an event Ariel saved search group.

Table 157: DELETE /ariel/event_saved_search_groups/{group_id} Resource Details

MIME Type

text/plain

Table 158: DELETE /ariel/event_saved_search_groups/{group_id} Request Parameter Details

Parameter

Type

Optionality

Data Type

MIME Type

Description

group_id

path

Required

Number (Integer)

text/plain

null

Table 159: DELETE /ariel/event_saved_search_groups/{group_id} Response Codes

HTTP Response Code

Unique Code

Description

204

 

The event Ariel saved search group was deleted.

404

1002

The event Ariel saved search group does not exist.

409

1004

null

500

1020

An error occurred during the attempt to delete theevent Ariel saved search group.

Response Description

Response Sample

GET /ariel/flow_saved_search_groups

Retrieves a list of flow Ariel saved search groups.

Table 160: GET /ariel/flow_saved_search_groups Resource Details

MIME Type

application/json

Table 161: GET /ariel/flow_saved_search_groups Request Parameter Details

Parameter

Type

Optionality

Data Type

MIME Type

Description

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.

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.

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.

Table 162: GET /ariel/flow_saved_search_groups Response Codes

HTTP Response Code

Unique Code

Description

200

 

The Retrieves a list of flow Ariel saved search groups were returned.

500

1020

An error occurred during the attempt to retrieve the flow Ariel saved search groups.

Response Description

List of the Group objects. A Group object contains the following fields:

  • id - Long - The ID of the group.

  • parent_id - Long - The ID of the parent group (default resources can have localized names).

  • type - String - The type of the group.

  • level - Long - The depth of the group in the group hierarchy.

  • name - String - The name of the group (default resources can have localized names).

  • description - String - The description of the group (default resources can have localized names).

  • owner - String - The owner of the group.

  • modified_time - Long - The time in milliseconds since epoch since the group was last modified.

  • child_group_ids - Array of Longs - List of the child group IDs.

Response Sample

[ { "child_groups": [ 42 ], "child_items": [ "String" ], "description": "String", "id": 42, "level": 42, "modified_time": 42, "name": "String", "owner": "String", "parent_id": 42, "type": "String <one of: LOG_SOURCE_GROUP, REPORT_GROUP, RULE_GROUP, EVENT_SAVED_SEARCH_GROUP, FLOW_SAVED_SEARCH_GROUP, OFFENSE_SAVED_SEARCH_GROUP, QRM_SAVED_SEARCH_GROUP, MODEL_SAVED_SEARCH_GROUP, QUESTION_SAVED_SEARCH_GROUP, SIMULATION_SAVED_SEARCH_GROUP, TOPOLOGY_SAVED_SEARCH_GROUP, ASSET_SAVED_SEARCH_GROUP, VULNERABILITY_SAVED_SEARCH_GROUP>" } ]

GET /ariel/flow_saved_search_groups/{group_id}

Retrieves a flow Ariel saved search group.

Table 163: GET /ariel/flow_saved_search_groups/{group_id} Resource Details

MIME Type

application/json

Table 164: GET /ariel/flow_saved_search_groups/{group_id} Request Parameter Details

Parameter

Type

Optionality

Data Type

MIME Type

Description

group_id

path

Required

Number (Integer)

text/plain

null

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 165: GET /ariel/flow_saved_search_groups/{group_id} Response Codes

HTTP Response Code

Unique Code

Description

200

 

The flow Ariel saved search group was retrieved.

404

1002

The flow Ariel saved search group does not exist.

500

1020

An error occurred during the attempt to retrieve the flow Ariel saved search group.

Response Description

A single Group object. A Group object contains the following fields:

  • id - Long - The ID of the group.

  • parent_id - Long - The ID of the parent group (default resources can have localized names).

  • type - String - The type of the group.

  • level - Long - The depth of the group in the group hierarchy.

  • name - String - The name of the group (default resources can have localized names).

  • description - String - The description of the group (default resources can have localized names).

  • owner - String - The owner of the group.

  • modified_time - Long - The time in milliseconds since epoch since the group was last modified.

  • child_group_ids - Array of Longs - List of the child group IDs.

Response Sample

{ "child_groups": [ 42 ], "child_items": [ "String" ], "description": "String", "id": 42, "level": 42, "modified_time": 42, "name": "String", "owner": "String", "parent_id": 42, "type": "String <one of: LOG_SOURCE_GROUP, REPORT_GROUP, RULE_GROUP, EVENT_SAVED_SEARCH_GROUP, FLOW_SAVED_SEARCH_GROUP, OFFENSE_SAVED_SEARCH_GROUP, QRM_SAVED_SEARCH_GROUP, MODEL_SAVED_SEARCH_GROUP, QUESTION_SAVED_SEARCH_GROUP, SIMULATION_SAVED_SEARCH_GROUP, TOPOLOGY_SAVED_SEARCH_GROUP, ASSET_SAVED_SEARCH_GROUP, VULNERABILITY_SAVED_SEARCH_GROUP>" }

POST /ariel/flow_saved_search_groups/{group_id}

Updates the owner of a flow Ariel saved search group.

Table 166: POST /ariel/flow_saved_search_groups/{group_id} Resource Details

MIME Type

application/json

Table 167: POST /ariel/flow_saved_search_groups/{group_id} Request Parameter Details

Parameter

Type

Optionality

Data Type

MIME Type

Description

group_id

path

Required

Number (Integer)

text/plain

null

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 168: POST /ariel/flow_saved_search_groups/{group_id} Request Body Details

Parameter

Data Type

MIME Type

Description

Sample

group

Object

application

/json

Required - Group object with the owner set to a valid deployed user.

{

  • "child_groups": [ 42 ],

  • "child_items": [ "String" ],

  • "description": "String",

  • "id": 42,

  • "level": 42,

  • "name": "String",

  • "owner": "String",

  • "parent_id": 42,

  • "type": "String <one of:

  • LOG_SOURCE_GROUP,

  • REPORT_GROUP,

  • RULE_GROUP,

  • EVENT_SAVED_SEARCH _GROUP,

  • FLOW_SAVED_SEARCH _GROUP,

  • OFFENSE_SAVED_SEARCH _GROUP,

  • QRM_SAVED_SEARCH _GROUP,

  • MODEL_SAVED_SEARCH_GROUP,

  • QUESTION_SAVED_SEARCH _GROUP,

  • SIMULATION_SAVED_SEARCH _GROUP,

  • TOPOLOGY_SAVED_SEARCH _GROUP,

  • ASSET_SAVED_SEARCH_GROUP,

  • VULNERABILITY_SAVED _SEARCH _GROUP>" }

Table 169: POST /ariel/flow_saved_search_groups/{group_id} Response Codes

HTTP Response Code

Unique Code

Description

200

 

The flow Ariel saved search group was updated.

404

1002

The flow Ariel saved search group does not exist.

409

1004

The provided user does not have the required capabilities to own the flow Ariel saved search group.

422

1005

A request parameter is not valid.

500

1020

An error occurred during the attempt to update the flow Ariel saved search group.

Response Description

The updated Group object. A Group object contains the following fields:

  • id - Long - The ID of the group.

  • parent_id - Long - The ID of the parent group (default resources can have localized names).

  • type - String - The type of the group.

  • level - Long - The depth of the group in the group hierarchy.

  • name - String - The name of the group (default resources can have localized names).

  • description - String - The description of the group (default resources can have localized names).

  • owner - String - The owner of the group.

  • modified_time - Long - The time in milliseconds since epoch since the group was last modified.

  • child_group_ids - Array of Longs - List of the child group IDs.

Response Sample

{ "child_groups": [ 42 ], "child_items": [ "String" ], "description": "String", "id": 42, "level": 42, "modified_time": 42, "name": "String", "owner": "String", "parent_id": 42, "type": "String <one of: LOG_SOURCE_GROUP, REPORT_GROUP, RULE_GROUP, EVENT_SAVED_SEARCH_GROUP, FLOW_SAVED_SEARCH_GROUP, OFFENSE_SAVED_SEARCH_GROUP, QRM_SAVED_SEARCH_GROUP, MODEL_SAVED_SEARCH_GROUP, QUESTION_SAVED_SEARCH_GROUP, SIMULATION_SAVED_SEARCH_GROUP, TOPOLOGY_SAVED_SEARCH_GROUP, ASSET_SAVED_SEARCH_GROUP, VULNERABILITY_SAVED_SEARCH_GROUP>" }

DELETE /ariel/flow_saved_search_groups/{group_id}

Deletes a flow Ariel saved search group.

Table 170: DELETE /ariel/flow_saved_search_groups/{group_id} Resource Details

MIME Type

text/plain

Table 171: DELETE /ariel/flow_saved_search_groups/{group_id} Request Parameter Details

Parameter

Type

Optionality

Data Type

MIME Type

Description

group_id

path

Required

Number (Integer)

text/plain

null

Table 172: DELETE /ariel/flow_saved_search_groups/{group_id} Response Codes

HTTP Response Code

Unique Code

Description

204

 

The flow Ariel saved search group was deleted.

404

1002

The flow Ariel saved search group does not exist.

409

1004

null

500

1020

An error occurred during the attempt to delete the flow Ariel saved search group.

Response Description

Response Sample

GET /ariel/parser_keywords

Retrieves keywords applicable to AQL Parser.

Table 173: GET /ariel/parser_keywords Resource Details

MIME Type

application/json

Table 174: GET /ariel/parser_keywords Request Parameter Details

Parameter

Type

Optionality

Data Type

MIME Type

Description

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 175: GET /ariel/parser_keywords Response Codes

HTTP Response Code

Unique Code

Description

200

 

AQL Parser information retrieved

Response Description

Information about the AQL Parser.

Response Sample

{ "keywords": [ "String" ], "where_clause_keywords": [ "String" ] }

POST /ariel/processors/aql_metadata

Parses the Ariel Query Language (AQL) query expression and returns expected metadata without execution of the query.

This endpoint only accepts SELECT query expressions.

Table 176: POST /ariel/processors/aql_metadata Resource Details

MIME Type

application/json

Table 177: POST /ariel/processors/aql_metadata Request Parameter Details

Parameter

Type

Optionality

Data Type

MIME Type

Description

query_ expression

query

Required

String

text/plain

Required - The AQL query for metadata.

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 178: POST /ariel/processors/aql_metadata Response Codes

HTTP Response Code

Unique Code

Description

200

 

An AQL query expression was successfully validated.

422

2000

The query_expression contains invalid AQL syntax.

500

1020

An error occurred during the attempt to validate AQL.

503

1010

The Ariel server might be temporarily unavailable or offline. Please try again later.

Response Description

A list of columns that are defined for the specified AQL query. Multiple properties of each column are returned. For example, the column name or an indication that the column is indexable.

Response Sample

{ "columns": [ { "argument_type": "String", "indexable": true, "name": "String", "nullable": true, "object_value_type": "String <one of: NULL, STRUCT, Byte, Short, Integer, Long, UnsignedByte, UnsignedShort, UnsignedInt, UnsignedLong, BigInteger, Double, Float, Port, Host, HostV4V6, HostV6, MACAddress, String, ByteArray, UnsignedIntHex, Boolean, Binary>", "provider_name": "String" } ] }

GET /ariel/saved_search_delete_tasks/{task_id}

Retrieves the delete the Ariel saved search task status.

Table 179: GET /ariel/saved_search_delete_tasks/{task_id} Resource Details

MIME Type

application/json

Table 180: GET /ariel/saved_search_delete_tasks/{task_id} Request Parameter Details

Parameter

Type

Optionality

Data Type

MIME Type

Description

task_id

path

Required

Number (Integer)

text/plain

null

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 181: GET /ariel/saved_search_delete_tasks/{task_id} Response Codes

HTTP Response Code

Unique Code

Description

200

 

The delete task status was retrieved.

404

1002

The delete task status was exist.

500

1020

An error occurred during the attempt to retrieve the delete task status.

Response Description

A Delete Task Status object and the location header set to the task status url "/api/ariel/saved_search_delete_tasks/{task_id}". A Delete Task Status object contains the following fields:

  • id - Long - The ID of the task.

  • message - String - The localized task message.

  • status - String - The current state of the task.

  • name - String - The name of the task.

  • created_by - String - The name of the user who started the task.

  • created - Long - The time in milliseconds since epoch since the task was created.

  • started - Long - The time in milliseconds since epoch since the task was started.

  • modified - Long - The time in milliseconds since epoch since the task was modified.

  • completed - Long - The time in milliseconds since epoch since the task was completed.

Response Sample

{ "completed": 42, "created": 42, "created_by": "String", "id": 42, "message": "String", "modified": 42, "name": "String", "started": 42, "status": "String <one of: CANCELLED, CANCELING, CANCEL_REQUESTED, COMPLETED, CONFLICT, EXCEPTION, INITIALIZING, INTERRUPTED, PAUSED, PROCESSING, QUEUED, RESUMING>" }

GET /ariel/saved_search_dependent_tasks/{task_id}

Retrieves the dependent the Ariel saved search task status.

Table 182: GET /ariel/saved_search_dependent_tasks/{task_id} Resource Details

MIME Type

application/json

Table 183: GET /ariel/saved_search_dependent_tasks/{task_id} Request Parameter Details

Parameter

Type

Optionality

Data Type

MIME Type

Description

task_id

path

Required

Number (Integer)

text/plain

null

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 184: GET /ariel/saved_search_dependent_tasks/{task_id} Response Codes

HTTP Response Code

Unique Code

Description

200

 

The dependent task status was retrieved.

404

1002

The dependent task status does not exist.

500

1020

An error occurred during the attempt to retrieve the dependent task status.

Response Description

A Dependent Task Status object and the location header set to the task status url "/api/ariel/saved_search_dependent_tasks/{task_id}". A Dependent Task Status object contains the following fields:

  • id - Long - The ID of the task.

  • message - String - The localized task message.

  • status - String - The current state of the task.

  • name - String - The name of the task.

  • created_by - String - The name of the user who started the task.

  • cancelled_by - String - The name of the user who requested cancellation of the task.

  • created - Long - The time in milliseconds since epoch since the task was created.

  • started - Long - The time in milliseconds since epoch since the task was started.

  • modified - Long - The time in milliseconds since epoch since the task was modified.

  • completed - Long - The time in milliseconds since epoch since the task was completed.

  • number_of_dependents - Long - The number of dependents found. The value is null until the task completes.

  • maximum - Long - The maximum number of objects to check for dependency.

  • progress - Long - The number of objects that were checked for dependency.

  • task_components - Array - An array of task component objects. A task component object contains the following fields:

    • message - String - The localized sub-task status message.

    • status - String - The current state of the sub-task.

    • sub_task_type - String - The type of the sub-task.

    • maximum - Long - The maximum number of objects to check for dependency.

    • progress - Long - The number of objects that were checked for dependency.

    • created - Long - The time in milliseconds since epoch since the sub-task was created.

    • started - Long - The time in milliseconds since epoch since the sub-task was started.

    • modified - Long - The time in milliseconds since epoch since the sub-task was modified.

    • completed - Long - The time in milliseconds since epoch since the sub-task was completed.

Response Sample

{ "cancelled_by": "String", "completed": 42, "created": 42, "created_by": "String", "id": 42, "maximum": 42, "message": "String", "modified": 42, "name": "String", "number_of_dependents": 42, "progress": 42, "started": 42, "status": "String <one of: CANCELLED, CANCELING, CANCEL_REQUESTED, COMPLETED, CONFLICT, EXCEPTION, INITIALIZING, INTERRUPTED, PAUSED, PROCESSING, QUEUED, RESUMING>" "task_components": [ { "completed": 42, "created": 42, "maximum": 42, "message": "String", "modified": 42, "number_of_dependents": 42, "progress": 42, "started": 42, "status": "String <one of: CANCELLED, CANCELING, CANCEL_REQUESTED, COMPLETED, CONFLICT, EXCEPTION, INITIALIZING, INTERRUPTED, PAUSED, PROCESSING, QUEUED, RESUMING>" "task_sub_type": "String <one of: FIND_DEPENDENT_ARIEL_SAVED_SEARCHES, FIND_DEPENDENT_OFFENSE_SAVED_SEARCHES, FIND_DEPENDENT_ASSET_SAVED_SEARCHES, FIND_DEPENDENT_VULNERABILITY_SAVED_SEARCHES, FIND_DEPENDENT_ADE_RULES, FIND_DEPENDENT_RULES, FIND_DEPENDENT_CALCULATED_PROPERTIES, FIND_DEPENDENT_LOG_SOURCE_GROUPS, FIND_DEPENDENT_CUSTOM_PROPERTIES, FIND_DEPENDENT_REPORTS, FIND_DEPENDENT_DASHBOARDS, FIND_DEPENDENT_STORE_AND_FORWARD_POLICIES, FIND_DEPENDENT_AUTHORIZED_SERVICES, FIND_DEPENDENT_OFFENSE_TYPES, FIND_DEPENDENT_ASSIGNED_OFFENSES, FIND_DEPENDENT_VULNERABILITIES, FIND_DEPENDENT_GROUPS, FIND_DEPENDENT_HISTORICAL_CORRELATION_PROFILES>" } ] }

POST /ariel/saved_search_dependent_tasks/{task_id}

Cancels the dependent Ariel saved search task.

Table 185: POST /ariel/saved_search_dependent_tasks/{task_id} Resource Details

MIME Type

application/json

Table 186: POST /ariel/saved_search_dependent_tasks/{task_id} Request Parameter Details

Parameter

Type

Optionality

Data Type

MIME Type

Description

task_id

path

Required

Number (Integer)

text/plain

null

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 187: POST /ariel/saved_search_dependent_tasks/{task_id} Request Body Details

Parameter

Data Type

MIME Type

Description

Sample

task

Object

application/json

null

{ "status": "String <one of: CANCELLED, CANCELING, CANCEL_REQUESTED, COMPLETED, CONFLICT, EXCEPTION, INITIALIZING, INTERRUPTED, PAUSED, PROCESSING, QUEUED, RESUMING>" }

Table 188: POST /ariel/saved_search_dependent_tasks/{task_id} Response Codes

HTTP Response Code

Unique Code

Description

200

 

The delete task status was retrieved.

404

1002

The dependent task status does not exist.

409

1004

The task is in a completed state.

422

1005

A request parameter is not valid.

500

1020

An error occurred during the attempt to update the dependent task status.

Response Description

A Dependent Task Status object and the location header set to the task status url "/api/ariel/saved_search_dependent_tasks/{task_id}". A Dependent Task Status object contains the following fields:

  • id - Long - The ID of the task.

  • message - String - The localized task message.

  • status - String - The current state that the task is in.

  • name - String - The name of the task.

  • created_by - String - The name of the user who started the task.

  • cancelled_by - String - The name of the user who requested cancellation of the task.

  • created - Long - The time in milliseconds since epoch since the task was created.

  • started - Long - The time in milliseconds since epoch since the task was started.

  • modified - Long - The time in milliseconds since epoch since the task was modified.

  • completed - Long - The time in milliseconds since epoch since the task was completed.

  • number_of_dependents - Long - The number of dependents found. the vaalue is null until the task completes.

  • maximum - Long - The maximum number of objects to check for dependency.

  • progress - Long - The number of objects that were checked for dependency.

  • task_components - Array - An array of task component objects. A task component object contains the following fields:

    • message - String - The localized sub-task status message.

    • status - String - The current state of the sub-task.

    • sub_task_type - String - The type of the sub-task

    • maximum - Long - The maximum number of objects to check for dependency.

    • progress - Long - The number of objects that were checked for dependency.

    • created - Long - The time in milliseconds since epoch since the sub-task was created.

    • started - Long - The time in milliseconds since epoch since the sub-task was started.

    • modified - Long - The time in milliseconds since epoch since the sub-task was modified.

    • completed - Long - The time in milliseconds since epoch since the sub-task was completed.

Response Sample

{ "cancelled_by": "String", "completed": 42, "created": 42, "created_by": "String", "id": 42, "maximum": 42, "message": "String", "modified": 42, "name": "String", "number_of_dependents": 42, "progress": 42, "started": 42, "status": "String <one of: CANCELLED, CANCELING, CANCEL_REQUESTED, COMPLETED, CONFLICT, EXCEPTION, INITIALIZING, INTERRUPTED, PAUSED, PROCESSING, QUEUED, RESUMING>" "task_components": [ { "completed": 42, "created": 42, "maximum": 42, "message": "String", "modified": 42, "number_of_dependents": 42, "progress": 42, "started": 42, "status": "String <one of: CANCELLED, CANCELING, CANCEL_REQUESTED, COMPLETED, CONFLICT, EXCEPTION, INITIALIZING, INTERRUPTED, PAUSED, PROCESSING, QUEUED, RESUMING>" "task_sub_type": "String <one of: FIND_DEPENDENT_ARIEL_SAVED_SEARCHES, FIND_DEPENDENT_OFFENSE_SAVED_SEARCHES, FIND_DEPENDENT_ASSET_SAVED_SEARCHES, FIND_DEPENDENT_VULNERABILITY_SAVED_SEARCHES, FIND_DEPENDENT_ADE_RULES, FIND_DEPENDENT_RULES, FIND_DEPENDENT_CALCULATED_PROPERTIES, FIND_DEPENDENT_LOG_SOURCE_GROUPS, FIND_DEPENDENT_CUSTOM_PROPERTIES, FIND_DEPENDENT_REPORTS, FIND_DEPENDENT_DASHBOARDS, FIND_DEPENDENT_STORE_AND_FORWARD_POLICIES, FIND_DEPENDENT_AUTHORIZED_SERVICES, FIND_DEPENDENT_OFFENSE_TYPES, FIND_DEPENDENT_ASSIGNED_OFFENSES, FIND_DEPENDENT_VULNERABILITIES, FIND_DEPENDENT_GROUPS, FIND_DEPENDENT_HISTORICAL_CORRELATION_PROFILES>" } ] }

GET /ariel/saved_search_dependent_tasks/{task_id}/results

Retrieves the Ariel saved search dependent task results.

Table 189: GET /ariel/saved_search_dependent_tasks/{task_id}/results Resource Details

MIME Type

application/json

Table 190: GET /ariel/saved_search_dependent_tasks/{task_id}/results Request Parameter Details

Parameter

Type

Optionality

Data Type

MIME Type

Description

task_id

path

Required

Number (Integer)

text/plain

null

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 191: GET /ariel/saved_search_dependent_tasks/{task_id}/results Response Codes

HTTP Response Code

Unique Code

Description

200

 

The Ariel saved search dependents were retrieved.

404

1002

The Dependent Task Status does not exist.

500

1020

An error occurred during the attempt to retrieve the Ariel saved searches.

Response Description

An list of Dependent objects. A Dependent object contains the following fields:

  • dependent_id - String - The ID of the dependent resource.

  • dependent_name - String - The name of the dependent resource. ( Default resources can have localized names )

  • dependent_owner - String - The owner of the dependent resource.

  • dependent_type - String - The type of the dependent resource.

  • dependent_database - String - The database of the dependent resource.

  • dependent_group_ids - Array of Longs - List of groups that the dependent resource belongs to.

  • user_has_edit_permissions - Boolean - The true if the user who created the task has permission to edit this dependent resource.

Response Sample

[ { "blocking": true, "dependent_database": "String <one of: EVENTS, FLOWS>", "dependent_group_ids": [ 42 ], "dependent_id": "String", "dependent_name": "String", "dependent_owner": "String", "dependent_type": "String <one of: ARIEL_SAVED_SEARCH, ASSET_SAVED_SEARCH, OFFENSE_SAVED_SEARCH, VULNERABILITY_SAVED_SEARCH, QRM_SAVED_SEARCH_GROUP, ASSET_SAVED_SEARCH_GROUP, CUSTOM_RULE_GROUP, EVENT_ARIEL_SAVED_SEARCH_GROUP, FLOW_ARIEL_SAVED_SEARCH_GROUP, LOG_SOURCE_GROUP, MODEL_GROUP, OFFENSE_SAVED_SEARCH_GROUP, QUESTION_GROUP, REPORT_GROUP, SIMULATION_GROUP, TOPOLOGY_SAVED_SEARCH_GROUP, VULNERABILITY_SAVED_SEARCH_GROUP, ASSIGNED_OFFENSE, ASSIGNED_VULNERABILITY, AUTHORIZED_SERVICE, BUILDING_BLOCK, CRE_RULE, CRE_ADE_RULE, EVENT_REGEX_PROPERTY, EVENT_CALCULATED_PROPERTY, FLOW_REGEX_PROPERTY, FLOW_CALCULATED_PROPERTY, DASHBOARD, GV_REFERENCE, REPORT, REFERENCE_DATA, REFERENCE_DATA_MAP_OF_SETS, REFERENCE_DATA_MAPS, REFERENCE_DATA_SETS, REFERENCE_DATA_TABLES, REFERENCE_DATA_RESPONSE, REFERENCE_SET_RESPONSE, EVENT_RETENTION_BUCKET, FLOW_RETENTION_BUCKET, ROUTING_RULE, STORE_AND_FORWARD_POLICY, USER, HISTORICAL_PROFILE, OFFENSE_TYPE>", "user_has_edit_permissions": true } ]

GET /ariel/saved_searches

Retrieves a list of Ariel saved searches.

Table 192: GET /ariel/saved_searches Resource Details

MIME Type

application/json

Table 193: GET /ariel/saved_searches Request Parameter Details

Parameter

Type

Optionality

Data Type

MIME Type

Description

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.

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.

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.

Table 194: GET /ariel/saved_searches Response Codes

HTTP Response Code

Unique Code

Description

200

 

The Ariel saved searches were retrieved.

422

1010

A request parameter is not valid.

500

1020

An error occurred during the attempt to retrieve the Ariel Saved Searches.

Response Description

An array of Ariel Saved Search objects. An Ariel Saved Search object contains the following fields:

  • id - Long - The ID of the ariel saved search.

  • uuid - String - The uuid of the Ariel saved search.

  • name - String - The name of the Ariel saved search.

  • database - String - The database of the Ariel saved search, events or flows.

  • isShared - Boolean - True if the Ariel saved search is shared with other users.

  • owner - String - The owner of the Ariel saved search.

Response Sample

[ { "database": "String <one of: EVENTS, FLOWS>", "id": 42, "is_shared": true, "name": "String", "owner": "String", "uid": "String" } ]

GET /ariel/saved_searches/{id}

Retrieves an Ariel saved search.

Table 195: GET /ariel/saved_searches/{id} Resource Details

MIME Type

application/json

Table 196: GET /ariel/saved_searches/{id} Request Parameter Details

Parameter

Type

Optionality

Data Type

MIME Type

Description

id

path

Required

Number (Integer)

text/plain

null

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 197: GET /ariel/saved_searches/{id} Response Codes

HTTP Response Code

Unique Code

Description

200

 

The Ariel saved search was retrieved.

404

1002

The Ariel saved search does not exist.

500

1020

An error occurred during the attempt to retrieve the Ariel Saved Search.

Response Description

The Ariel saved search after it is retrieved. An Ariel Saved Search object contains the following fields:

  • id - Long - The ID of the Ariel saved search.

  • uuid - String - The uuid of the Ariel saved search.

  • name - String - The name of the Ariel saved search.

  • database - String - The database of the Ariel saved search, events or flows.

  • isShared - Boolean - True if the Ariel saved search is shared with other users.

  • owner - String - The owner of the Ariel saved search.

Response Sample

{ "database": "String <one of: EVENTS, FLOWS>", "id": 42, "is_shared": true, "name": "String", "owner": "String", "uid": "String" }

POST /ariel/saved_searches/{id}

Updates the Ariel saved search owner only.

Table 198: POST /ariel/saved_searches/{id} Resource Details

MIME Type

application/json

Table 199: POST /ariel/saved_searches/{id} Request Parameter Details

Parameter

Type

Optionality

Data Type

MIME Type

Description

id

path

Required

Number (Integer)

text/plain

null

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 200: POST /ariel/saved_searches/{id} Request Body Details

Parameter

Data Type

MIME Type

Description

Sample

saved_search

Object

application/json

null

{ "id": "1", "name": "String", "database": "String", "is_shared": true, "owner": "String" }

Table 201: POST /ariel/saved_searches/{id} Response Codes

HTTP Response Code

Unique Code

Description

200

 

The Ariel saved search was updated.

403

1009

You do not have the required capabilities to update the Ariel Saved Search.

404

1002

The Ariel saved search does not exist.

409

1004

The provided user does not have the required capabilities to own the Ariel saved search.

422

1005

A request parameter is not valid.

500

1020

An error occurred during the attempt to update the Ariel Saved Search.

Response Description

The Ariel saved search after it has been updated. An Ariel Saved Search object contains the following fields:

  • id - Long - The ID of the Ariel saved search.

  • uuid - String - The uuid of the Ariel saved search.

  • name - String - The name of the Ariel saved search.

  • database - String - The database of the Ariel saved search, events or flows.

  • isShared - Boolean - True if the Ariel saved search is shared with other users.

  • owner - String - The owner of the Ariel saved search.

Response Sample

{ "database": "String <one of: EVENTS, FLOWS>", "id": 42, "is_shared": true, "name": "String", "owner": "String", "uid": "String" }

DELETE /ariel/saved_searches/{id}

Deletes an Ariel saved search. To ensure safe deletion, a dependency check is carried out. The check might take some time. An asynchronous task is started to do this check.

Table 202: DELETE /ariel/saved_searches/{id} Resource Details

MIME Type

application/json

Table 203: DELETE /ariel/saved_searches/{id} Request Parameter Details

Parameter

Type

Optionality

Data Type

MIME Type

Description

id

path

Required

Number (Integer)

text/plain

null

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 204: DELETE /ariel/saved_searches/{id} Response Codes

HTTP Response Code

Unique Code

Description

202

 

The Ariel saved search delete command was accepted and is in progress.

403

1009

You do not have the required capabilities to delete the Ariel saved search.

404

1002

The Ariel saved search does not exist.

500

1020

An error occurred during the attempt to delete the Ariel Saved Search.

Response Description

A Delete Task Status object and the location header set to the task status url "/api/ariel/saved_search_delete_tasks/{task_id}". A Delete Task Status object contains the following fields:

  • id - Long - The ID of the task.

  • message - String - The localized task message.

  • status - String - The current state of the task.

  • name - String - The name of the task.

  • created_by - String - The name of the user who started the task.

  • created - Long - The time in milliseconds since epoch since the task was created.

  • started - Long - The time in milliseconds since epoch since the task was started.

  • modified - Long - The time in milliseconds since epoch since the task was modified.

  • completed - Long - The time in milliseconds since epoch since the task was completed.

Response Sample

{ "completed": 42, "created": 42, "created_by": "String", "id": 42, "message": "String", "modified": 42, "name": "String", "started": 42, "status": "String <one of: CANCELLED, CANCELING, CANCEL_REQUESTED, COMPLETED, CONFLICT, EXCEPTION, INITIALIZING, INTERRUPTED, PAUSED, PROCESSING, QUEUED, RESUMING>" }

GET /ariel/saved_searches/{id}/dependents

Retrieves the objects that depend on the Ariel saved search.

Table 205: GET /ariel/saved_searches/{id}/dependents Resource Details

MIME Type

application/json

Table 206: GET /ariel/saved_searches/{id}/dependents Request Parameter Details

Parameter

Type

Optionality

Data Type

MIME Type

Description

id

path

Required

Number (Integer)

text/plain

null

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 207: GET /ariel/saved_searches/{id}/dependents Response Codes

HTTP Response Code

Unique Code

Description

202

 

The Ariel saved search dependents retrieval was accepted and is in progress

404

1002

The Ariel saved search does not exist

500

1020

An error occurred during the attempt to initiate the Ariel Saved Search dependents retrieval task

Response Description

A Dependents Task Status object and the location header set to the task status url "/api/ariel/saved_search_dependents_tasks/{task_id}". A Dependent Task Status object contains the following fields:

  • id - Long - The ID of the task.

  • message - String - The localized task message.

  • status - String - The current state of the task.

  • name - String - The name of the task.

  • created_by - String - The name of the user who started the task.

  • cancelled_by - String - The name of the user who requested to cancel the task.

  • created - Long - The time in milliseconds since epoch since the task was created.

  • started - Long - The time in milliseconds since epoch since the task was started.

  • modified - Long - The time in milliseconds since epoch since the task was modified.

  • completed - Long - The time in milliseconds since epoch since the task was completed.

  • number_of_dependents - Long - The number of dependents found. The value is null until the task completes.

  • maximum - Long - The maximum number of objects to check for dependency.

  • progress - Long - The number of objects that were checked for dependency.

  • task_components - Array - An array of task component objects. A task component object contains the following fields:

    • message - String - The localized sub-task status message.

    • status - String - The current state of the sub-task.

    • sub_task_type - String - The type of the sub-task

    • maximum - Long - The maximum number of objects to check for dependency.

    • progress - Long - The number of objects that were checked for dependency.

    • created - Long - The time in milliseconds since epoch since the sub-task was created.

    • started - Long - The time in milliseconds since epoch since the sub-task was started.

    • modified - Long - The time in milliseconds since epoch since the sub-task was modified.

    • completed - Long - The time in milliseconds since epoch since the sub-task was completed.

Response Sample

{ "cancelled_by": "String", "completed": 42, "created": 42, "created_by": "String", "id": 42, "maximum": 42, "message": "String", "modified": 42, "name": "String", "number_of_dependents": 42, "progress": 42, "started": 42, "status": "String <one of: CANCELLED, CANCELING, CANCEL_REQUESTED, COMPLETED, CONFLICT, EXCEPTION, INITIALIZING, INTERRUPTED, PAUSED, PROCESSING, QUEUED, RESUMING>" "task_components": [ { "completed": 42, "created": 42, "maximum": 42, "message": "String", "modified": 42, "number_of_dependents": 42, "progress": 42, "started": 42, "status": "String <one of: CANCELLED, CANCELING, CANCEL_REQUESTED, COMPLETED, CONFLICT, EXCEPTION, INITIALIZING, INTERRUPTED, PAUSED, PROCESSING, QUEUED, RESUMING>" "task_sub_type": "String <one of: FIND_DEPENDENT_ARIEL_SAVED_SEARCHES, FIND_DEPENDENT_OFFENSE_SAVED_SEARCHES, FIND_DEPENDENT_ASSET_SAVED_SEARCHES, FIND_DEPENDENT_VULNERABILITY_SAVED_SEARCHES, FIND_DEPENDENT_ADE_RULES, FIND_DEPENDENT_RULES, FIND_DEPENDENT_CALCULATED_PROPERTIES, FIND_DEPENDENT_LOG_SOURCE_GROUPS, FIND_DEPENDENT_CUSTOM_PROPERTIES, FIND_DEPENDENT_REPORTS, FIND_DEPENDENT_DASHBOARDS, FIND_DEPENDENT_STORE_AND_FORWARD_POLICIES, FIND_DEPENDENT_AUTHORIZED_SERVICES, FIND_DEPENDENT_OFFENSE_TYPES, FIND_DEPENDENT_ASSIGNED_OFFENSES, FIND_DEPENDENT_VULNERABILITIES, FIND_DEPENDENT_GROUPS, FIND_DEPENDENT_HISTORICAL_CORRELATION_PROFILES>" } ] }

GET /ariel/searches

Retrieves the list of Ariel searches. Search IDs for completed and active searches are returned.

Table 208: GET /ariel/searches Resource Details

MIME Type

application/json

Table 209: GET /ariel/searches Request Parameter Details

Parameter

Type

Optionality

Data Type

MIME Type

Description

db_name

query

Optional

String

text/plain

Optional - The name of the Ariel database to retrieve the list of Ariel searches.

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.

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.

Table 210: GET /ariel/searches Response Codes

HTTP Response Code

Unique Code

Description

200

 

The search list was retrieved.

500

1020

An error occurred during the attempt to retrieve the list of searches.

503

1010

The ariel server might be temporarily unavailable or offline. Please try again later.

Response Description

A list of search IDs.

Response Sample

[ "String" ]

POST /ariel/searches

Creates a new asynchronous Ariel search.

Creates a new Ariel search as specified by the Ariel Query Language (AQL) query expression. Searches are executed asynchronously. A reference to the search ID is returned and should be used in subsequent API calls to determine the status of the search and retrieve the results once it is complete.

This endpoint only accepts SELECT query expressions.

Queries are applied to the range of data in a certain time interval. By default this time interval is the last 60 seconds. An alternative time interval can be specified by specifying them as part of the query expression. For further information, see the AQL reference guide.

Table 211: POST /ariel/searches Resource Details

MIME Type

application/json

Table 212: POST /ariel/searches Request Parameter Details

Parameter

Type

Optionality

Data Type

MIME Type

Description

query_expression

query

Required

String

text/plain

Required - The AQL query to execute.

Table 213: POST /ariel/searches Response Codes

HTTP Response Code

Unique Code

Description

201

 

A new Ariel search was successfully created.

409

1004

The search cannot be created. The requested search ID that was provided in the query expression is already in use. Please use a unique search ID (or allow one to be generated).

422

2000

The query_expression contains invalid AQL syntax.

422

1005

A request parameter is not valid.

500

1020

An error occurred during the attempt to create a new search.

503

1010

The Ariel server might be temporarily unavailable or offline. Please try again later.

Response Description

Information about the specified search, including the search ID. Use the search ID to access or manipulate the search with the other API endpoints. If the exact search being created was already recently created, the response message will return a reference to the original search ID rather than creating a new search.

Response Sample

{ "cursor_id": "s16", "compressed_data_file_count": 0, "compressed_data_total_size": 0, "data_file_count": 5470, "data_total_size": 67183115, "index_file_count": 0, "index_total_size": 0, "processed_record_count": 1256462, "error_messages": [ { "code": "String", "contexts": [ "String" ], "message": "String", "severity": "String <one of: INFO, WARN, ERROR>" } ], "desired_retention_time_msec": 86400000, "progress": 46, "progress_details": [ 0, 0, 0, 0, 66957, 652657, 76594, 89809, 86032, 107729 ], "query_execution_time": 1480, "query_string": "SELECT sourceip, starttime from events into s16 where sourceip in (select destinationip from events) parameters snapshotsize=2, PROGRESSDETAILSRESOLUTION=10", "record_count": 1240923, "save_results": false, "status": "EXECUTE", "snapshot": { "events": [ { "sourceip": "10.100.65.20", "starttime": "1467049610018" }, { "sourceip": "10.100.100.121", "starttime": "1467049610019" } ] }, "subsearch_ids": [ "sub_id_1" ], "search_id": "s16" }

DELETE /ariel/searches/{search_id}

Deletes an Ariel search. This discards any results that were collected and stops the search if it is in progress. This search is deleted regardless of whether the results were saved.

Table 214: DELETE /ariel/searches/{search_id} Resource Details

MIME Type

application/json

Table 215: DELETE /ariel/searches/{search_id} Request Parameter Details

Parameter

Type

Optionality

Data Type

MIME Type

Description

search_id

path

Required

String

text/plain

Required - The search ID of the search to delete.

Table 216: DELETE /ariel/searches/{search_id} Response Codes

HTTP Response Code

Unique Code

Description

202

 

The delete request has been accepted.

404

1002

The search does not exist.

422

1005

A request parameter is not valid.

500

1020

An error occurred during the attempt to delete the search.

503

1010

The ariel server might be temporarily unavailable or offline. Please try again later.

Response Description

Information about the deleted search.

Response Sample

{ "cursor_id": "s16", "compressed_data_file_count": 0, "compressed_data_total_size": 0, "data_file_count": 5470, "data_total_size": 67183115, "index_file_count": 0, "index_total_size": 0, "processed_record_count": 1256462, "error_messages": [ { "code": "String", "contexts": [ "String" ], "message": "String", "severity": "String <one of: INFO, WARN, ERROR>" } ], "desired_retention_time_msec": 86400000, "progress": 46, "progress_details": [ 0, 0, 0, 0, 66957, 652657, 76594, 89809, 86032, 107729 ], "query_execution_time": 1480, "query_string": "SELECT sourceip, starttime, qid, sourceport from events into s16 where sourceip in (select destinationip from events) parameters snapshotsize=2, PROGRESSDETAILSRESOLUTION=10", "record_count": 1240923, "save_results": false, "status": "String <one of: WAIT, EXECUTE, SORTING, COMPLETED, CANCELED, ERROR>", "snapshot": { "events": [ { "sourceip": "10.100.65.20", "starttime": 1467049610018, "qid": 10034, "sourceport": 13675 }, { "sourceip": "10.100.100.121", "starttime": 1467049610019, "qid": 20034, "sourceport": 80 } ] }, "subsearch_ids": [ "sub_id_1" ], "search_id": "s16" }

GET /ariel/searches/{search_id}

Retrieves information about an Ariel search.

Retrieve status information for a search, based on the search ID parameter. The same informational fields are returned regardless of whether the search is in progress or is complete.

Table 217: GET /ariel/searches/{search_id} Resource Details

MIME Type

application/json

Table 218: GET /ariel/searches/{search_id} Request Parameter Details

Parameter

Type

Optionality

Data Type

MIME Type

Description

search_id

path

Required

String

text/plain

Required. The identifier for an Ariel search.

Prefer

header

Optional

String

text/plain

Optional. Specify 'wait=N' where N is number of seconds to wait for COMPLETED status of the search.

Table 219: GET /ariel/searches/{search_id} Response Codes

HTTP Response Code

Unique Code

Description

200

 

The search information was retrieved.

206

 

The search information was retrieved with 'Prefer: wait=N' timeout(sec) expired before the search is completed

404

1002

The search does not exist.

422

1005

A request parameter is not valid.

500

1020

An error occurred during the attempt to retrieve the search information.

503

1010

The Ariel server might be temporarily unavailable or offline. Please try again later.

Response Description

Information about the specified search, including the search status.

Response Sample

{ "cursor_id": "s16", "compressed_data_file_count": 0, "compressed_data_total_size": 0, "data_file_count": 5470, "data_total_size": 67183115, "index_file_count": 0, "index_total_size": 0, "processed_record_count": 1256462, "error_messages": [ { "code": "String", "contexts": [ "String" ], "message": "String", "severity": "String <one of: INFO, WARN, ERROR>" } ], "desired_retention_time_msec": 86400000, "progress": 46, "progress_details": [ 0, 0, 0, 0, 66957, 652657, 76594, 89809, 86032, 107729 ], "query_execution_time": 1480, "query_string": "SELECT sourceip, starttime, qid, sourceport from events into s16 where sourceip in (select destinationip from events) parameters snapshotsize=2, PROGRESSDETAILSRESOLUTION=10", "record_count": 1240923, "save_results": false, "status": "String <one of: WAIT, EXECUTE, SORTING, COMPLETED, CANCELED, ERROR>", "snapshot": { "events": [ { "sourceip": "10.100.65.20", "starttime": 1467049610018, "qid": 10034, "sourceport": 13675 }, { "sourceip": "10.100.100.121", "starttime": 1467049610019, "qid": 20034, "sourceport": 80 } ] }, "subsearch_ids": [ "sub_id_1" ], "search_id": "s16" }

GET /ariel/searches/{search_id}/metadata

Retrieve the columns that are defined for the specified Ariel search id. This is the set of columns that can be explicitly named in the column list of a SELECT query.

Table 220: GET /ariel/searches/{search_id}/metadata Resource Details

MIME Type

application/json

Table 221: GET /ariel/searches/{search_id}/metadata Request Parameter Details

Parameter

Type

Optionality

Data Type

MIME Type

Description

search_id

path

Required

String

text/plain

null

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.

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.

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.

Table 222: GET /ariel/searches/{search_id}/metadata Response Codes

HTTP Response Code

Unique Code

Description

200

 

Columns were successfully retrieved.

404

1002

The search does not exist.

503

1010

The Ariel server might be temporarily unavailable or offline. Please try again later.

Response Description

A list of columns that are defined for the specified database. Multiple properties of each column are returned. For example, the column name or an indication that the column is indexable.

Response Sample

{ "columns": [ { "argument_type": "String", "indexable": true, "name": "String", "nullable": true, "object_value_type": "String <one of: NULL, STRUCT, Byte, Short, Integer, Long, UnsignedByte, UnsignedShort, UnsignedInt, UnsignedLong, BigInteger, Double, Float, Port, Host, HostV4V6, HostV6, MACAddress, String, ByteArray, UnsignedIntHex, Boolean, Binary>", "provider_name": "String" } ] }

POST /ariel/searches/{search_id}

Updates details for an Ariel search. You can update searches in the following ways:

  • To cancel an active search, set the status parameter to CANCELED. This stops the search and keeps any search results that were collected before the search was canceled.

  • The results for a completed search can be saved by setting the save_results parameter to true. This ensures that the search is not automatically removed when it expires in accordance with the retention policy.

The Ariel server uses an internal retention policy to manage available disk space. Searches might be deleted automatically, according to the settings of the retention policy. Searches with saved results are not automatically reclaimed by the server and are therefore retained. A search can be explicitly deleted by using the DELETE /searches/{search_id} endpoint.

Note: Saving too many search results might result in insufficient disk space to process new searches.

Table 223: POST /ariel/searches/{search_id} Resource Details

MIME Type

application/json

Table 224: POST /ariel/searches/{search_id} Request Parameter Details

Parameter

Type

Optionality

Data Type

MIME Type

Description

search_id

path

Required

String

text/plain

Required. The ID of the search to update.

status

query

Optional

String

text/plain

Optional. The only accepted value is CANCELED. If this value is provided, the search is canceled.

save_results

query

Optional

String

text/plain

Optional. The only accepted value is true. If this value is provided, the search results are not deleted by the search expiration removal process. If status parameter was provided, this parameter is not checked and silently ignored.

Table 225: POST /ariel/searches/{search_id} Response Codes

HTTP Response Code

Unique Code

Description

200

 

The search was updated.

404

1002

The search does not exist.

422

1005

A request parameter is not valid.

500

1020

An error occurred during the attempt to update the search.

503

1010

The Ariel server might be temporarily unavailable or offline. Please try again later.

Response Description

Information about the specified search that was updated.

Response Sample

{ "cursor_id": "s16", "compressed_data_file_count": 0, "compressed_data_total_size": 0, "data_file_count": 5470, "data_total_size": 67183115, "index_file_count": 0, "index_total_size": 0, "processed_record_count": 1256462, "error_messages": [ { "code": "String", "contexts": [ "String" ], "message": "String", "severity": "String <one of: INFO, WARN, ERROR>" } ], "desired_retention_time_msec": 86400000, "progress": 46, "progress_details": [ 0, 0, 0, 0, 66957, 652657, 76594, 89809, 86032, 107729 ], "query_execution_time": 1480, "query_string": "SELECT sourceip, starttime from events into s16 where sourceip in (select destinationip from events) parameters snapshotsize=2, PROGRESSDETAILSRESOLUTION=10", "record_count": 1240923, "save_results": false, "status": "EXECUTE", "snapshot": { "events": [ { "sourceip": "10.100.65.20", "starttime": "1467049610018" }, { "sourceip": "10.100.100.121", "starttime": "1467049610019" } ] }, "subsearch_ids": [ "sub_id_1" ], "search_id": "s16" }

GET /ariel/searches/{search_id}/results

Retrieves search results in the requested format.

Retrieve the results of the Ariel search that is identified by the search ID. The Accepts request header indicates the format of the result. The formats are RFC compliant and can be JSON, CSV, XML, or tabular text.

By default, all query result records are returned. To restrict the results to a contiguous subset of the records, you can supply a Range header to specify the inclusive range of records to be returned.

This end-point works with query results that are generated by AQL query expressions. This endpoint might not work as expected for results that are generated by other means. Search results might not be retrievable for searches that are created on the Console.

The response samples are for the following query: Select sourceIP, destinationIP from events.

Table 226: GET /ariel/searches/{search_id}/results Resource Details

MIME Type

application/json application/csv text/table application/xml

Table 227: GET /ariel/searches/{search_id}/results Request Parameter Details

Parameter

Type

Optionality

Data Type

MIME Type

Description

search_id

path

Required

String

text/plain

The ID of the search criteria for the returned results.

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.

Table 228: GET /ariel/searches/{search_id}/results Response Codes

HTTP Response Code

Unique Code

Description

200

 

The search results were retrieved.

404

1002

The search does not exist.

404

1003

Search results not found. The search is still in progress.

422

1005

A request parameter is not valid.

500

1020

An error occurred during the attempt to retrieve the search results.

503

1010

The Ariel server might be temporarily unavailable or offline. Please try again later.

Response Description

The search results for the specified search ID. The format that is used to encapsulate the data depends on the format specified in the Accept header for this request.

Response Sample

{ "events": [ { "sourceIP": "192.0.2.0", "destinationIP": "127.0.0.1" }, { "sourceIP": "192.0.2.0", "destinationIP": "127.0.0.1" } ] }

POST /ariel/validators/aql

Validates the AQL query expression.

Validates the Ariel search as specified by the Ariel Query Language (AQL) query expression.

This endpoint only accepts SELECT query expressions.

Table 229: POST /ariel/validators/aql Resource Details

MIME Type

application/json

Table 230: POST /ariel/validators/aql Request Parameter Details

Parameter

Type

Optionality

Data Type

MIME Type

Description

query_ expression

query

Required

String

text/plain

Required - The AQL query to validate.

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 231: POST /ariel/validators/aql Response Codes

HTTP Response Code

Unique Code

Description

200

 

An AQL query expression was successfully validated.

500

1020

An error occurred during the attempt to validate AQL.

503

1010

The Ariel server might be temporarily unavailable or offline. Please try again later.

Response Description

Array of errors/warnings encountered during AQL validation or null if validation was successful.

Response Sample

{ "error_messages": [ { "code": 42, "contexts": [ "String" ], "message": "String", "severity": "String <one of: INFO, WARN, ERROR>" } ] }

Asset Model Endpoints

Use the references for REST API V9.2 Asset Model endpoints.

GET /asset_model/assets

List all assets found in the model.

Table 232: GET /asset_model/assets Resource Details

MIME Type

application/json

Table 233: GET /asset_model/assets 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.

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.

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.

Table 234: GET /asset_model/assets Response Codes

HTTP Response Code

Unique Code

Description

200

 

The request to retrieve assets completed successfully.

500

1020

The server encountered an error while trying to retrieve the assets.

Response Description

List of assets retrieved using the associated asset saved search.

Response Sample

[{"id": 42, "domain_id": 42, "interfaces": [{"first_seen_scanner": 42, "id": 42, "first_seen_profiler": 42, "created": 42, "last_seen_profiler": 42, "last_seen_scanner": 42, "mac_address": "String", "ip_addresses": [{"first_seen_scanner": 42, "id": 42, "first_seen_profiler": 42, "created": 42, "network_id": 42, "value": "String", "last_seen_profiler": 42, "last_seen_scanner": 42, "type": "String"}] }], "properties": [{"id": 42, "name": "String", "value": "String", "last_reported": 42, "type_id": 42, "last_reported_by": "String"}] }]

POST /asset_model/assets/{asset_id}

Update an asset with several pertinent pieces of information.

The asset_id tag is mandatory, and is the unique identifier for an asset. This field is available through the /asset_model/assets or /asset_model/saved_searches/{saved_search_id}/results query. To update properties, the property type ID which is available through the /asset_model/properties query must be provided along with the new value. See the sample provided demonstrating an example asset update.

Table 235: POST /asset_model/assets/{asset_id} Resource Details

MIME Type

text/plain

Table 236: POST /asset_model/assets/{asset_id} Request Parameter Details

Parameter

Type

Optionality

Data Type

MIME Type

Description

asset_id

path

Required

String

text/plain

Unique identifier of the asset to update.

Table 237: POST /asset_model/assets/{asset_id} Request Body Details

Parameter

Data Type

MIME Type

Description

Sample

asset

JSON

application/json

JSON representation of an asset.

{ "properties": [ { "type_id": 1001, "value": "given name value" }, { "type_id": 1002, "value": "unified name value" } ] }

Table 238: POST /asset_model/assets/{asset_id} Response Codes

HTTP Response Code

Unique Code

Description

202

 

The request to update the asset was successful. The update will take place when the asset profile application receives the request.

422

1005

One or more of the requested property updates were invalid.

500

1020

The server encountered an error registering the update with the asset profile application.

Response Description

Information about the asset that was updated.

Response Sample

String

GET /asset_model/properties

Get a list of available asset property types that can be used or applied against the /asset_model/assets endpoint.

Table 239: GET /asset_model/properties Resource Details

MIME Type

application/json

Table 240: GET /asset_model/properties 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.

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.

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.

Table 241: GET /asset_model/properties Response Codes

HTTP Response Code

Unique Code

Description

200

 

The request to retrieve the list of asset property types completed successfully.

500

1020

An error occurred while trying to retrieve the list of asset property types.

Response Description

List of asset properties. Per asset property type: id and name that make up this asset property type.

Response Sample

[ { "custom": true, "data_type": "String", "display": true, "id": 42, "name": "String", "state": 42 } ]

GET /asset_model/saved_search_groups

Retrieves a list the asset saved search groups.

Table 242: GET /asset_model/saved_search_groups Resource Details

MIME Type

application/json

Table 243: GET /asset_model/saved_search_groups Request Parameter Details

Parameter

Type

Optionality

Data Type

MIME Type

Description

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.

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.

Table 244: GET /asset_model/saved_search_groups Response Codes

HTTP Response Code

Unique Code

Description

200

 

The asset saved search groups were returned.

500

1020

An error occurred during the attempt to retrieve the asset saved search groups.

Response Description

List of the Group objects. A Group object contains the following fields:

  • id - Long - The ID of the group.

  • parent_id - Long - The ID of the parent group (default resources can have localized names).

  • type - String - The type of the group.

  • level - Long - The depth of the group in the group hierarchy.

  • name - String - The name of the group (default resources can have localized names).

  • description - String - The description of the group (default resources can have localized names).

  • owner - String - The owner of the group.

  • modified_time - Long - The time in milliseconds since epoch since the group was last modified.

  • child_group_ids - Array of Longs - List of the child group IDs.

Response Sample

[ { "child_groups": [ 42 ], "child_items": [ "String" ], "description": "String", "id": 42, "level": 42, "modified_time": 42, "name": "String", "owner": "String", "parent_id": 42, "type": "String <one of: LOG_SOURCE_GROUP, REPORT_GROUP, RULE_GROUP, EVENT_SAVED_SEARCH_GROUP, FLOW_SAVED_SEARCH_GROUP, OFFENSE_SAVED_SEARCH_GROUP, QRM_SAVED_SEARCH_GROUP, MODEL_SAVED_SEARCH_GROUP, QUESTION_SAVED_SEARCH_GROUP, SIMULATION_SAVED_SEARCH_GROUP, TOPOLOGY_SAVED_SEARCH_GROUP, ASSET_SAVED_SEARCH_GROUP, VULNERABILITY_SAVED_SEARCH_GROUP>" } ]

GET /asset_model/saved_search_groups/{group_id}

Retrieves an asset saved search group.

Table 245: GET /asset_model/saved_search_groups/{group_id} Resource Details

MIME Type

application/json

Table 246: GET /asset_model/saved_search_groups/{group_id} Request Parameter Details

Parameter

Type

Optionality

Data Type

MIME Type

Description

group_id

path

Required

Number (Integer)

text/plain

null

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 247: GET /asset_model/saved_search_groups/{group_id} Response Codes

HTTP Response Code

Unique Code

Description

200

 

The asset saved search group was retrieved.

404

1002

The asset saved search group does not exist.

500

1020

An error occurred during the attempt to retrieve the asset saved search group.

Response Description

A single Group object. A Group object contains the following fields:

  • id - Long - The ID of the group.

  • parent_id - Long - The id of the parent group. ( Default resources can have localized names )

  • type - String - The type of the group.

  • level - Long - The depth of the group in the group hierarchy.

  • name - String - The name of the group. ( Default groups can have localized names )

  • description - String - The description of the group. ( Default groups can have localized names )

  • owner - String - The owner of the group.

  • modified_time - Long - The time in milliseconds since epoch since the group was last modified.

  • child_group_ids - Array of Longs - List of the child group IDs.

Response Sample

{ "child_groups": [ 42 ], "child_items": [ "String" ], "description": "String", "id": 42, "level": 42, "modified_time": 42, "name": "String", "owner": "String", "parent_id": 42, "type": "String <one of: LOG_SOURCE_GROUP, REPORT_GROUP, RULE_GROUP, EVENT_SAVED_SEARCH_GROUP, FLOW_SAVED_SEARCH_GROUP, OFFENSE_SAVED_SEARCH_GROUP, QRM_SAVED_SEARCH_GROUP, MODEL_SAVED_SEARCH_GROUP, QUESTION_SAVED_SEARCH_GROUP, SIMULATION_SAVED_SEARCH_GROUP, TOPOLOGY_SAVED_SEARCH_GROUP, ASSET_SAVED_SEARCH_GROUP, VULNERABILITY_SAVED_SEARCH_GROUP>" }

POST /asset_model/saved_search_groups/{group_id}

Updates the owner of an asset saved search group.

Table 248: POST /asset_model/saved_search_groups/{group_id} Resource Details

MIME Type

application/json

Table 249: POST /asset_model/saved_search_groups/{group_id} Request Parameter Details

Parameter

Type

Optionality

Data Type

MIME Type

Description

group_id

path

Required

Number (Integer)

text/plain

null

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 250: POST /asset_model/saved_search_groups/{group_id} Request Body Details

Parameter

Data Type

MIME Type

Description

Sample

group

Object

application

/json

Required - Group object with the owner set to a valid deployed user.

{ "child_groups": [ 42 ], "child_items": [ "String" ], "description": "String", "id": 42, "level": 42, "name": "String", "owner": "String", "parent_id": 42, "type": "String <one of: LOG_SOURCE_GROUP, REPORT_GROUP, RULE_GROUP, EVENT_SAVED_SEARCH_GROUP, FLOW_SAVED_SEARCH_GROUP, OFFENSE_SAVED_SEARCH_GROUP, QRM_SAVED_SEARCH_GROUP, MODEL_SAVED_SEARCH_GROUP, QUESTION_SAVED_SEARCH_GROUP, SIMULATION_SAVED_SEARCH_GROUP, TOPOLOGY_SAVED_SEARCH_GROUP, ASSET_SAVED_SEARCH_GROUP, VULNERABILITY_SAVED_SEARCH_GROUP>" }

Table 251: POST /asset_model/saved_search_groups/{group_id} Response Codes

HTTP Response Code

Unique Code

Description

200

 

The asset saved search group has been updated.

404

1002

The asset saved search group does not exist.

409

1004

The provided user does not have the required capabilities to own the asset saved search group.

422

1005

A request parameter is not valid.

500

1020

An error occurred during the attempt to update the asset saved search group.

Response Description

The updated Group object. A Group object contains the following fields:

  • id - Long - The ID of the group.

  • parent_id - Long - The ID of the parent group (default resources can have localized names).

  • type - String - The type of the group.

  • level - Long - The depth of the group in the group hierarchy.

  • name - String - The name of the group (default resources can have localized names).

  • description - String - The description of the group (default resources can have localized names).

  • owner - String - The owner of the group.

  • modified_time - Long - The time in milliseconds since epoch since the group was last modified.

  • child_group_ids - Array of Longs - List of the child group IDs.

Response Sample

{ "child_groups": [ 42 ], "child_items": [ "String" ], "description": "String", "id": 42, "level": 42, "modified_time": 42, "name": "String", "owner": "String", "parent_id": 42, "type": "String <one of: LOG_SOURCE_GROUP, REPORT_GROUP, RULE_GROUP, EVENT_SAVED_SEARCH_GROUP, FLOW_SAVED_SEARCH_GROUP, OFFENSE_SAVED_SEARCH_GROUP, QRM_SAVED_SEARCH_GROUP, MODEL_SAVED_SEARCH_GROUP, QUESTION_SAVED_SEARCH_GROUP, SIMULATION_SAVED_SEARCH_GROUP, TOPOLOGY_SAVED_SEARCH_GROUP, ASSET_SAVED_SEARCH_GROUP, VULNERABILITY_SAVED_SEARCH_GROUP>" }

DELETE /asset_model/saved_search_groups/{group_id}

Deletes an asset saved search group.

Table 252: DELETE /asset_model/saved_search_groups/{group_id} Resource Details

MIME Type

text/plain

Table 253: DELETE /asset_model/saved_search_groups/{group_id} Request Parameter Details

Parameter

Type

Optionality

Data Type

MIME Type

Description

group_id

path

Required

Number (Integer)

text/plain

null

Table 254: DELETE /asset_model/saved_search_groups/{group_id} Response Codes

HTTP Response Code

Unique Code

Description

204

 

The asset saved search group was deleted.

404

1002

The asset saved search group does not exist.

409

1004

null

500

1020

An error occurred during the attempt to delete the asset saved search group.

Response Description

Response Sample

GET /asset_model/saved_searches

Get a list of saved searches that can be used or applied against the /asset_model/saved_searches/{saved_search_id}/results query.

Table 255: GET /asset_model/saved_searches Resource Details

MIME Type

application/json

Table 256: GET /asset_model/saved_searches 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.

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.

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.

Table 257: GET /asset_model/saved_searches Response Codes

HTTP Response Code

Unique Code

Description

200

 

The request to retrieve the list of saved searches completed successfully.

500

1020

The server encountered an error while trying to retrieve the list of saved searches.

Response Description

List of saved searches. Per saved search: id, name and list of filters that make up this saved search

Response Sample

[ { "columns": [ { "name": "String", "type": "String" } ], "description": "String", "filters": [ { "operator": "String", "parameter": "String", "value": "String" } ], "id": 42, "name": "String" } ]

GET /asset_model/saved_searches/{saved_search_id}

Retrieves an asset saved search.

Table 258: GET /asset_model/saved_searches/{saved_search_id} Resource Details

MIME Type

application/json

Table 259: GET /asset_model/saved_searches/{saved_search_id} Request Parameter Details

Parameter

Type

Optionality

Data Type

MIME Type

Description

saved_search_id

path

Required

Number (Integer)

text/plain

null

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 260: GET /asset_model/saved_searches/{saved_search_id} Response Codes

HTTP Response Code

Unique Code

Description

200

 

The asset saved search was retrieved,

404

1002

The asset saved search does not exist,

500

1020

An error occurred during the attempt to retrieve the asset saved search,

Response Description

The asset saved search after it is retrieved. An Asset Saved Search object contains the following fields:

  • id - Long - The ID of the asset saved search.

  • name - String - The name of the asset saved search.

  • owner - String - The owner of the asset saved search.

  • isShared - Boolean - True if the asset saved search is shared with other users.

  • description - String - The description of the asset saved search.

  • filters - List of Strings - The asset saved search filters.

  • columns - List of Strings - The asset saved search columns.

Response Sample

{ "columns": [ { "name": "String", "type": "String" } ], "description": "String", "filters": [ { "operator": "String", "parameter": "String", "value": "String" } ], "id": 42, "is_shared": true, "name": "String", "owner": "String" }

POST /asset_model/saved_searches/{saved_search_id}

Updates the asset saved search owner only.

Table 261: POST /asset_model/saved_searches/{saved_search_id} Resource Details

MIME Type

application/json

Table 262: POST /asset_model/saved_searches/{saved_search_id} Request Parameter Details

Parameter

Type

Optionality

Data Type

MIME Type

Description

saved_search_id

path

Required

Number (Integer)

text/plain

null

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 263: POST /asset_model/saved_searches/{saved_search_id} Request Body Details

Parameter

Data Type

MIME Type

Description

Sample

saved_search

Object

application/json

null

{ "columns": [ { "name": "String", "type": "String" } ], "description": "String", "filters": [ { "operator": "String", "parameter": "String", "value": "String" } ], "id": 42, "is_shared": true, "name": "String", "owner": "String" }

Table 264: POST /asset_model/saved_searches/{saved_search_id} Response Codes

HTTP Response Code

Unique Code

Description

200

 

The asset saved search was updated.

403

1009

You do not have the required capabilities to update the asset saved search.

404

1002

The asset saved search does not exist.

409

1004

The provided user does not have the required capabilities to own the asset saved search.

422

1005

A request parameter is not valid.

500

1020

An error occurred during the attempt to update the asset saved search.

Response Description

The asset saved search after it is updated. An Asset Saved Search object contains the following fields:

  • id - Long - The ID of the asset saved search.

  • name - String - The name of the asset saved search.

  • owner - String - The owner of the asset saved search.

  • isShared - Boolean - True if the asset saved search is shared with other users.

  • description - String - The description of the asset saved search.

  • filters - List of Strings - The asset saved search filters.

  • columns - List of Strings - The asset saved search columns.

Response Sample

{ "columns": [ { "name": "String", "type": "String" } ], "description": "String", "filters": [ { "operator": "String", "parameter": "String", "value": "String" } ], "id": 42, "is_shared": true, "name": "String", "owner": "String" }

DELETE /asset_model/saved_searches/{saved_search_id}

Deletes an asset saved search.

Table 265: DELETE /asset_model/saved_searches/{saved_search_id} Resource Details

MIME Type

text/plain

Table 266: DELETE /asset_model/saved_searches/{saved_search_id} Request Parameter Details

Parameter

Type

Optionality

Data Type

MIME Type

Description

saved_search_id

path

Required

Number (Integer)

text/plain

null

Table 267: DELETE /asset_model/saved_searches/{saved_search_id} Response Codes

HTTP Response Code

Unique Code

Description

204

 

The asset saved searchh was deleted.

403

1009

You do not have the required capabilities to delete the asset saved search.

404

1002

The asset saved search does not exist.

500

1020

An error occurred during the attempt to delete the asset saved search.

Response Description

Response Sample

GET /asset_model/saved_searches/{saved_search_id}/results

Retrieves a list of assets based on the results of an asset saved search.

Table 268: GET /asset_model/saved_searches/{saved_search_id}/results Resource Details

MIME Type

application/json

Table 269: GET /asset_model/saved_searches/{saved_search_id}/results Request Parameter Details

Parameter

Type

Optionality

Data Type

MIME Type

Description

saved_search_id

path

Required

String

text/plain

Unique identifier of the saved search used to retrieve assets.

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.

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.

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.

Table 270: GET /asset_model/saved_searches/{saved_search_id}/results Response Codes

HTTP Response Code

Unique Code

Description

200

 

The request to retrieve assets completed successfully.

422

1005

The unique identifier of the saved search provided was invalid.

500

1003

The server encountered an error executing the saved search.

Response Description

List of assets retrieved using the associated asset saved search.

Response Sample

[ { "domain_id": 42, "id": 42, "interfaces": [ { "created": 42, "first_seen_profiler": 42, "first_seen_scanner": 42, "id": 42, "ip_addresses": [ { "created": 42, "first_seen_profiler": 42, "first_seen_scanner": 42, "id": 42, "last_seen_profiler": 42, "last_seen_scanner": 42, "network_id": 42, "type": "String", "value": "String" } ], "last_seen_profiler": 42, "last_seen_scanner": 42, "mac_address": "String" } ], "properties": [ { "id": 42, "last_reported": 42, "last_reported_by": "String", "name": "String", "type_id": 42, "value": "String" } ] } ]

Authentication Endpoints

Use the references for REST API V9.2 authentication endpoints.

POST /auth/logout

Invoke this method as an authorized user and your session will be invalidated.

Table 271: POST /auth/logout Resource Details

MIME Type

text/plain

There are no parameters for this endpoint.

Table 272: POST /auth/logout Response Codes

HTTP Response Code

Unique Code

Description

200

 

The session was invalidated.

Response Description

Returns true. Throws exception upon failure.

Response Sample

true

Configuration Endpoints

Use the references for REST API V9.2 configuration endpoints.

GET /config/access/tenant_management/tenants

Retrieve the list of all tenants. The list is ordered by tenant ID.

Table 273: GET /config/access/tenant_management/tenants Resource Details

MIME Type

application/json

Table 274: GET /config/access/tenant_management/tenants 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.

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.

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.

Table 275: GET /config/access/tenant_management/tenants Response Codes

HTTP Response Code

Unique Code

Description

200

 

The tenant list was successfully retrieved.

500

1020

An error occurred while the tenant list was being retrieved.

Response Description

a list of all the tenants

Response Sample

[ { "deleted": true, "description": "String", "event_rate_limit": 42, "flow_rate_limit": 42, "id": 42, "name": "String" } ]

POST /config/access/tenant_management/tenants

Create a new tenant.

Table 276: POST /config/access/tenant_management/tenants Resource Details

MIME Type

application/json

Table 277: POST /config/access/tenant_management/tenants 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 278: POST /config/access/tenant_management/tenants Request Body Details

Parameter

Data Type

MIME Type

Description

Sample

tenant

Object

application/json

Required - Tenant - includes name, event_rate_limit (unit eps), flow_rate_limit (unit fpm) and description

{ "deleted": true, "description": "String", "event_rate_limit": 42, "flow_rate_limit": 42, "name": "String" }

Table 279: POST /config/access/tenant_management/tenants Response Codes

HTTP Response Code

Unique Code

Description

201

 

A new tenant was created successfully and returned the new tenant object.

409

1004

A tenant with the given name already exists.

422

1005

A request parameter is invalid.

500

1020

Failed to create the tenant.

Response Description

a created tenant object

Response Sample

{ "deleted": true, "description": "String", "event_rate_limit": 42, "flow_rate_limit": 42, "id": 42, "name": "String" }

GET /config/access/tenant_management/tenants/{tenant_id}

Retrieve a tenant by tenant id.

Table 280: GET /config/access/tenant_management/tenants/{tenant_id} Resource Details

MIME Type

application/json

Table 281: GET /config/access/tenant_management/tenants/{tenant_id} Request Parameter Details

Parameter

Type

Optionality

Data Type

MIME Type

Description

tenant_id

path

Required

Number (Integer)

text/plain

null

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 282: GET /config/access/tenant_management/tenants/{tenant_id} Response Codes

HTTP Response Code

Unique Code

Description

200

 

The tenant was successfully retrieved.

404

1002

No tenant was found for the provided tenant id.

500

1020

An error occurred while the tenant was being retrieved.

Response Description

The associated tenants object.

Response Sample

{ "deleted": true, "description": "String", "event_rate_limit": 42, "flow_rate_limit": 42, "id": 42, "name": "String" }

POST /config/access/tenant_management/tenants/{tenant_id}

Update a tenant.

Table 283: POST /config/access/tenant_management/tenants/{tenant_id} Resource Details

MIME Type

application/json

Table 284: POST /config/access/tenant_management/tenants/{tenant_id} Request Parameter Details

Parameter

Type

Optionality

Data Type

MIME Type

Description

tenant_id

path

Required

Number (Integer)

text/plain

Required - Integer - the tenant id to modify

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 285: POST /config/access/tenant_management/tenants/{tenant_id} Request Body Details

Parameter

Data Type

MIME Type

Description

Sample

tenant

Object

application/json

Required - Tenant - includes name, event_rate_limit (unit eps), flow_rate_limit (unit fpm) and description

{ "deleted": true, "description": "String", "event_rate_limit": 42, "flow_rate_limit": 42, "name": "String" }

Table 286: POST /config/access/tenant_management/tenants/{tenant_id} Response Codes

HTTP Response Code

Unique Code

Description

200

 

A tenant profile that was updated successfully and returned the updated tenant object.

404

1002

The tenant profile does not exist.

409

1004

A tenant with the given name already exists.

422

1005

A request parameter is invalid.

500

1020

Failed to retrieve/update the given tenant profile.

Response Description

The updated tenant object.

Response Sample

{ "deleted": true, "description": "String", "event_rate_limit": 42, "flow_rate_limit": 42, "id": 42, "name": "String" }

DELETE /config/access/tenant_management/tenants/{tenant_id}

Delete a tenant.

Table 287: DELETE /config/access/tenant_management/tenants/{tenant_id} Resource Details

MIME Type

application/json

Table 288: DELETE /config/access/tenant_management/tenants/{tenant_id} Request Parameter Details

Parameter

Type

Optionality

Data Type

MIME Type

Description

tenant_id

path

Required

Number (Integer)

text/plain

Required - String - id associated to a tenant

Table 289: DELETE /config/access/tenant_management/tenants/{tenant_id} Response Codes

HTTP Response Code

Unique Code

Description

200

 

The tenant was deleted successfully (soft delete).

404

1002

The tenant does not exists.

500

1020

An error occurred while deleting tenant.

Response Description

the deleted tenant object with its parameter deleted set to true

Response Sample

{ "deleted": true, "description": "String", "event_rate_limit": 42, "flow_rate_limit": 42, "id": 42, "name": "String" }

GET /config/access/user_dependent_tasks/{task_id}

Retrieves the dependent user task status.

Table 290: GET /config/access/user_dependent_tasks/{task_id} Resource Details

MIME Type

application/json

Table 291: GET /config/access/user_dependent_tasks/{task_id} Request Parameter Details

Parameter

Type

Optionality

Data Type

MIME Type

Description

task_id

path

Required

Number (Integer)

text/plain

null

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 292: GET /config/access/user_dependent_tasks/{task_id} Response Codes

HTTP Response Code

Unique Code

Description

200

 

The Delete Task Status was retrieved.

404

1002

The Delete Task Status does not exist.

500

1020

An error occurred during the attempt to retrieve the Delete Task Status.

Response Description

A Dependent Task Status object and the location header set to the task status url "/api/config/access/user_dependent_tasks/{task_id}". A Dependent Task Status object contains the following fields:

  • id - Long - The ID of the task.

  • message - String - The localized task message.

  • status - String - The current state of the task.

  • name - String - The name of the task.

  • created_by - String - The name of the user who started the task.

  • cancelled_by - String - The name of the user who requested to cancel the task.

  • created - Long - The time in milliseconds since epoch since the task was created.

  • started - Long - The time in milliseconds since epoch since the task was started.

  • modified - Long - The time in milliseconds since epoch since the task was modified.

  • completed - Long - The time in milliseconds since epoch since the task was completed.

  • number_of_dependents - Long - The number of dependents found. Value is null until task completes.

  • maximum - Long - The maximum number of objects to check for dependency.

  • progress - Long - The number of objects checked for dependency.

  • task_components - Array - An array of task component objects. A task component object contains the following fields:

    • message - String - The localized sub-task status message.

    • status - String - The current state the sub-task is in.

    • sub_task_type - String - The type of the sub-task.

    • maximum - Long - The maximum number of objects to check for dependency.

    • progress - Long - The number of objects checked for dependency.

    • created - Long - The time in milliseconds since epoch since the sub-task was created.

    • started - Long - The time in milliseconds since epoch since the sub-task was started.

    • modified - Long - The time in milliseconds since epoch since the sub-task was modified.

    • completed - Long - The time in milliseconds since epoch since the sub-task was completed.

Response Sample

{ "cancelled_by": "String", "completed": 42, "created": 42, "created_by": "String", "id": 42, "maximum": 42, "message": "String", "modified": 42, "name": "String", "number_of_dependents": 42, "progress": 42, "started": 42, "status": "String <one of: CANCELLED, CANCELING, CANCEL_REQUESTED, COMPLETED, CONFLICT, EXCEPTION, INITIALIZING, INTERRUPTED, PAUSED, PROCESSING, QUEUED, RESUMING>", "task_components": [ { "completed": 42, "created": 42, "maximum": 42, "message": "String", "modified": 42, "number_of_dependents": 42, "progress": 42, "started": 42, "status": "String <one of: CANCELLED, CANCELING, CANCEL_REQUESTED, COMPLETED, CONFLICT, EXCEPTION, INITIALIZING, INTERRUPTED, PAUSED, PROCESSING, QUEUED, RESUMING>", "task_sub_type": "String <one of: FIND_DEPENDENT_ARIEL_SAVED_SEARCHES, FIND_DEPENDENT_OFFENSE_SAVED_SEARCHES, FIND_DEPENDENT_ASSET_SAVED_SEARCHES, FIND_DEPENDENT_VULNERABILITY_SAVED_SEARCHES, FIND_DEPENDENT_ADE_RULES, FIND_DEPENDENT_RULES, FIND_DEPENDENT_CALCULATED_PROPERTIES, FIND_DEPENDENT_AQL_PROPERTIES, FIND_DEPENDENT_LOG_SOURCE_GROUPS, FIND_DEPENDENT_CUSTOM_PROPERTIES, FIND_DEPENDENT_REPORTS, FIND_DEPENDENT_DASHBOARDS, FIND_DEPENDENT_STORE_AND_FORWARD_POLOCIES, FIND_DEPENDENT_AUTHORIZED_SERVICES, FIND_DEPENDENT_OFFENSE_TYPES, FIND_DEPENDENT_ASSIGNED_OFFENSES, FIND_DEPENDENT_VULNERABILITIES, FIND_DEPENDENT_GROUPS, FIND_DEPENDENT_HISTORICAL_CORRELATION_PROFILES, FIND_DEPENDENT_SECURITY_PROFILES, FIND_DEPENDENT_ARIEL_INDEXING>" } ] }

POST /config/access/user_dependent_tasks/{task_id}

Cancels a dependent user task.

Table 293: POST /config/access/user_dependent_tasks/{task_id} Resource Details

MIME Type

application/json

Table 294: POST /config/access/user_dependent_tasks/{task_id} Request Parameter Details

Parameter

Type

Optionality

Data Type

MIME Type

Description

task_id

path

Required

Number (Integer)

text/plain

null

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 295: POST /config/access/user_dependent_tasks/{task_id} Request Body Details

Parameter

Data Type

MIME Type

Description

Sample

task

Object

application/json

null

{ "status": "String <one of: CANCELLED, CANCELING, CANCEL_REQUESTED, COMPLETED, CONFLICT, EXCEPTION, INITIALIZING, INTERRUPTED, PAUSED, PROCESSING, QUEUED, RESUMING>" }

Table 296: POST /config/access/user_dependent_tasks/{task_id} Response Codes

HTTP Response Code

Unique Code

Description

200

 

The Dependent Task Status was retrieved.

404

1002

The Dependent Task Status does not exist.

409

1004

The task is in a completed state.

422

1005

A request parameter is not valid.

500

1020

An error occurred during the attempt to update the Dependent Task Status.

Response Description

A Dependent Task Status object and the location header set to the task status url "/api/config/access/user_dependent_tasks/{task_id}". A Dependent Task Status object contains the following fields:

  • id - Long - The ID of the task.

  • message - String - The localized task message.

  • status - String - The current state that the task is in.

  • name - String - The name of the task.

  • created_by - String - The name of the user who started the task.

  • cancelled_by - String - The name of the user who requested to cancel the task.

  • created - Long - The time in milliseconds since epoch since the task was created.

  • started - Long - The time in milliseconds since epoch since the task was started.

  • modified - Long - The time in milliseconds since epoch since the task was modified.

  • completed - Long - The time in milliseconds since epoch since the task was completed.

  • number_of_dependents - Long - The number of dependents found. The value is null until the task completes.

  • maximum - Long - The maximum number of objects to check for dependency.

  • progress - Long - The number of objects checked for dependency.

  • task_components - Array - An array of task component objects. A task component object contains the following fields:

    • message - String - The localized sub-task status message.

    • status - String - The current state the sub-task is in.

    • sub_task_type - String - The type of the sub-task.

    • maximum - Long - The maximum number of objects to check for dependency.

    • progress - Long - The number of objects checked for dependency.

    • created - Long - The time in milliseconds since epoch since the sub-task was created.

    • started - Long - The time in milliseconds since epoch since the sub-task was started.

    • modified - Long - The time in milliseconds since epoch since the sub-task was modified.

    • completed - Long - The time in milliseconds since epoch since the sub-task was completed.

Response Sample

{ "cancelled_by": "String", "completed": 42, "created": 42, "created_by": "String", "id": 42, "maximum": 42, "message": "String", "modified": 42, "name": "String", "number_of_dependents": 42, "progress": 42, "started": 42, "status": "String <one of: CANCELLED, CANCELING, CANCEL_REQUESTED, COMPLETED, CONFLICT, EXCEPTION, INITIALIZING, INTERRUPTED, PAUSED, PROCESSING, QUEUED, RESUMING>", "task_components": [ { "completed": 42, "created": 42, "maximum": 42, "message": "String", "modified": 42, "number_of_dependents": 42, "progress": 42, "started": 42, "status": "String <one of: CANCELLED, CANCELING, CANCEL_REQUESTED, COMPLETED, CONFLICT, EXCEPTION, INITIALIZING, INTERRUPTED, PAUSED, PROCESSING, QUEUED, RESUMING>", "task_sub_type": "String <one of: FIND_DEPENDENT_ARIEL_SAVED_SEARCHES, FIND_DEPENDENT_OFFENSE_SAVED_SEARCHES, FIND_DEPENDENT_ASSET_SAVED_SEARCHES, FIND_DEPENDENT_VULNERABILITY_SAVED_SEARCHES, FIND_DEPENDENT_ADE_RULES, FIND_DEPENDENT_RULES, FIND_DEPENDENT_CALCULATED_PROPERTIES, FIND_DEPENDENT_AQL_PROPERTIES, FIND_DEPENDENT_LOG_SOURCE_GROUPS, FIND_DEPENDENT_CUSTOM_PROPERTIES, FIND_DEPENDENT_REPORTS, FIND_DEPENDENT_DASHBOARDS, FIND_DEPENDENT_STORE_AND_FORWARD_POLOCIES, FIND_DEPENDENT_AUTHORIZED_SERVICES, FIND_DEPENDENT_OFFENSE_TYPES, FIND_DEPENDENT_ASSIGNED_OFFENSES, FIND_DEPENDENT_VULNERABILITIES, FIND_DEPENDENT_GROUPS, FIND_DEPENDENT_HISTORICAL_CORRELATION_PROFILES, FIND_DEPENDENT_SECURITY_PROFILES, FIND_DEPENDENT_ARIEL_INDEXING>" } ] }

GET /config/access/user_dependent_tasks/{task_id}/results

Retrieves the user dependent task results.

Table 297: GET /config/access/user_dependent_tasks/{task_id}/results Resource Details

MIME Type

application/json

Table 298: GET /config/access/user_dependent_tasks/{task_id}/results Request Parameter Details

Parameter

Type

Optionality

Data Type

MIME Type

Description

task_id

path

Required

Number (Integer)

text/plain

null

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 299: GET /config/access/user_dependent_tasks/{task_id}/results Response Codes

HTTP Response Code

Unique Code

Description

200

 

The User Dependents were retrieved.

404

1002

The Dependent Task Status does not exist.

500

1020

An error occurred during the attempt to retrieve the Users.

Response Description

An list of Dependent objects. A Dependent object contains the following fields:

  • dependent_id - String - The ID of the dependent resource.

  • dependent_name - String - The name of the dependent resource (default resources can have localized names).

  • dependent_owner - String - The owner of the dependent resource.

  • dependent_type - String - The type of the dependent resource.

  • dependent_database - String - The database of the dependent resource.

  • dependent_group_ids - Array of Longs - List of groups that the dependent resource belongs to.

  • user_has_edit_permissions - Boolean - True if the user who created the task has permission to edit this dependent resource.

Response Sample

[ { "blocking": true, "dependent_database": "String <one of: EVENTS, FLOWS>", "dependent_group_ids": [ 42 ], "dependent_id": "String", "dependent_name": "String", "dependent_owner": "String", "dependent_type": "String <one of: ARIEL_SAVED_SEARCH, ASSET_SAVED_SEARCH, OFFENSE_SAVED_SEARCH, VULNERABILITY_SAVED_SEARCH, QRM_SAVED_SEARCH_GROUP, ASSET_SAVED_SEARCH_GROUP, CUSTOM_RULE_GROUP, EVENT_ARIEL_SAVED_SEARCH_GROUP, FLOW_ARIEL_SAVED_SEARCH_GROUP, LOG_SOURCE_GROUP, MODEL_GROUP, OFFENSE_SAVED_SEARCH_GROUP, QUESTION_GROUP, REPORT_GROUP, SIMULATION_GROUP, TOPOLOGY_SAVED_SEARCH_GROUP, VULNERABILITY_SAVED_SEARCH_GROUP, ASSIGNED_OFFENSE, ASSIGNED_VULNERABILITY, AUTHORIZED_SERVICE, BUILDING_BLOCK, CRE_RULE, CRE_ADE_RULE, EVENT_REGEX_PROPERTY, EVENT_REGEX_PROPERTY_DEPENDENCY, EVENT_CALCULATED_PROPERTY, FLOW_REGEX_PROPERTY, FLOW_REGEX_PROPERTY_DEPENDENCY, FLOW_CALCULATED_PROPERTY, DASHBOARD, GV_REFERENCE, REPORT, REFERENCE_DATA, REFERENCE_DATA_MAP_OF_SETS, REFERENCE_DATA_MAPS, REFERENCE_DATA_SETS, REFERENCE_DATA_TABLES, REFERENCE_DATA_RESPONSE, REFERENCE_SET_RESPONSE, EVENT_RETENTION_BUCKET, FLOW_RETENTION_BUCKET, ROUTING_RULE, STORE_AND_FORWARD_POLICY, USER, HISTORICAL_PROFILE, OFFENSE, EVENT_AQL_PROPERTY, FLOW_AQL_PROPERTY, OFFENSE_TYPE, SECURITY_PROFILE, ARIEL_INDEX>", "user_has_edit_permissions": true } ]

GET /config/access/users

Retrieves a list of deployed users.

Table 300: GET /config/access/users Resource Details

MIME Type

application/json

Table 301: GET /config/access/users Request Parameter Details

Parameter

Type

Optionality

Data Type

MIME Type

Description

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.

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.

Table 302: GET /config/access/users Response Codes

HTTP Response Code

Unique Code

Description

200

 

The users were retrieved.

500

1020

An error occurred during the attempt to retrieve the Users.

Response Description

An array of User objects. An User object contains the following fields:

  • id - Long - The ID of the user.

  • name - String - The name of the user.

  • email - String - The email of the user.

Response Sample

[ { "email": "String", "id": 42, "username": "String" } ]

GET /config/access/users/{id}/dependents

Retrieves the objects that depend on the user.

Table 303: GET /config/access/users/{id}/dependents Resource Details

MIME Type

application/json

Table 304: GET /config/access/users/{id}/dependents Request Parameter Details

Parameter

Type

Optionality

Data Type

MIME Type

Description

id

path

Required

Number (Integer)

text/plain

null

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 305: GET /config/access/users/{id}/dependents Response Codes

HTTP Response Code

Unique Code

Description

202

 

The User dependents retrieval was accepted and is in progress.

404

1002

The User does not exist.

500

1020

An error occurred during the attempt to initiate the User dependents retrieval task.

Response Description

A Dependents Task Status object and the location header set to the task status url "/api/config/access/user_dependents_tasks/{task_id}". A Dependent Task Status object contains the following fields:

  • id - Long - The ID of the task.

  • message - String - The localized task message.

  • status - String - The current state of the task.

  • name - String - The name of the task.

  • created_by - String - The name of the user who started the task.

  • cancelled_by - String - The name of the user who requested cancellation of the task.

  • created - Long - The time in milliseconds since epoch since the task was created.

  • started - Long - The time in milliseconds since epoch since the task was started.

  • modified - Long - The time in milliseconds since epoch since the task was modified.

  • completed - Long - The time in milliseconds since epoch since the task was completed.

  • number_of_dependents - Long - The number of dependents found. Value is null until task completes.

  • maximum - Long - The maximum number of objects to check for dependency.

  • progress - Long - The number of objects checked for dependency.

  • task_components - Array - An array of task component objects. A task component object contains the following fields

    • message - String - The localized sub-task status message.

    • status - String - The current state of the sub-task.

    • sub_task_type - String - The type of the sub-task

    • maximum - Long - The maximum number of objects to check for dependency.

    • progress - Long - The number of objects checked for dependency.

    • created - Long - The time in milliseconds since epoch since the sub-task was created.

    • started - Long - The time in milliseconds since epoch since the sub-task was started.

    • modified - Long - The time in milliseconds since epoch since the sub-task was modified.

    • completed - Long - The time in milliseconds since epoch since the sub-task was completed.

Response Sample

{ "cancelled_by": "String", "completed": 42, "created": 42, "created_by": "String", "id": 42, "maximum": 42, "message": "String", "modified": 42, "name": "String", "number_of_dependents": 42, "progress": 42, "started": 42, "status": "String <one of: CANCELLED, CANCELING, CANCEL_REQUESTED, COMPLETED, CONFLICT, EXCEPTION, INITIALIZING, INTERRUPTED, PAUSED, PROCESSING, QUEUED, RESUMING>", "task_components": [ { "completed": 42, "created": 42, "maximum": 42, "message": "String", "modified": 42, "number_of_dependents": 42, "progress": 42, "started": 42, "status": "String <one of: CANCELLED, CANCELING, CANCEL_REQUESTED, COMPLETED, CONFLICT, EXCEPTION, INITIALIZING, INTERRUPTED, PAUSED, PROCESSING, QUEUED, RESUMING>", "task_sub_type": "String <one of: FIND_DEPENDENT_ARIEL_SAVED_SEARCHES, FIND_DEPENDENT_OFFENSE_SAVED_SEARCHES, FIND_DEPENDENT_ASSET_SAVED_SEARCHES, FIND_DEPENDENT_VULNERABILITY_SAVED_SEARCHES, FIND_DEPENDENT_ADE_RULES, FIND_DEPENDENT_RULES, FIND_DEPENDENT_CALCULATED_PROPERTIES, FIND_DEPENDENT_AQL_PROPERTIES, FIND_DEPENDENT_LOG_SOURCE_GROUPS, FIND_DEPENDENT_CUSTOM_PROPERTIES, FIND_DEPENDENT_REPORTS, FIND_DEPENDENT_DASHBOARDS, FIND_DEPENDENT_STORE_AND_FORWARD_POLOCIES, FIND_DEPENDENT_AUTHORIZED_SERVICES, FIND_DEPENDENT_OFFENSE_TYPES, FIND_DEPENDENT_ASSIGNED_OFFENSES, FIND_DEPENDENT_VULNERABILITIES, FIND_DEPENDENT_GROUPS, FIND_DEPENDENT_HISTORICAL_CORRELATION_PROFILES, FIND_DEPENDENT_SECURITY_PROFILES, FIND_DEPENDENT_ARIEL_INDEXING>" } ] }

GET /config/access/users/{id}

Retrieves a deployed user.

Table 306: GET /config/access/users/{id} Resource Details

MIME Type

application/json

Table 307: GET /config/access/users/{id} Request Parameter Details

Parameter

Type

Optionality

Data Type

MIME Type

Description

id

path

Required

Number (Integer)

text/plain

null

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 308: GET /config/access/users/{id} Response Codes

HTTP Response Code

Unique Code

Description

200

 

The user was retrieved

404

1002

The User does not exist

500

1020

An error occurred while attempting to retrieve the User

Response Description

The User after it is retrieved. A User object contains the following fields:

  • id - Long - The ID of the user.

  • name - String - The name of the user.

  • email - String - The email of the user.

Response Sample

{ "email": "String", "id": 42, "username": "String" }

GET /config/deployment/hosts

Retrieves a list of all deployed hosts.

Table 309: GET /config/deployment/hosts Resource Details

MIME Type

application/json

Table 310: GET /config/deployment/hosts Request Parameter Details

Parameter

Type

Optionality

Data Type

MIME Type

Description

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.

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.

Table 311: GET /config/deployment/hosts Response Codes

HTTP Response Code

Unique Code

Description

200

 

The host list was successfully retrieved.

500

1001

An error occurred during the attempt to retrieve the host list.

Response Description

A list of all the hosts. Each Host object has the following fields:

  • id - The ID of this managed host.

  • hostname - The host name of this managed host.

  • private_ip - The private IP of this managed host.

  • public_ip - The public IP of this managed host.

  • appliance - An object that represents the appliance type ID and description of this managed host.

  • version - The installed version on this managed host.

  • status - The status of this managed host.

  • eps_rate_hardware_limit - The upper limit for eps_allocation based on hardware constraints for this managed host.

  • eps_allocation - The allocated eps rate of this managed host.

  • average_eps - The average eps rate of this managed host over the previous month.

  • peak_eps - The peak eps rate that was experienced by this managed host over the previous month.

  • fpm_rate_hardware_limit - The upper limit for fpm_allocation based on hardware constraints for this managed host

  • fpm_allocation - The allocated fpm rate of this managed host.

  • average_fpm - The average fpm rate of this managed host over the previous month.

  • peak_fpm - The peak fpm rate that was experienced by this managed host over the previous month.

  • primary_server_id - The ID for the primary server host for this managed host.

  • secondary_server_id - If configured, the ID for the secondary server host for this managed host.

  • license_serial_number - The serial number that is associated with this managed host's license.

  • components - A list of components that are associated with this managed host.

  • compression_enabled - Whether or not compression is enabled for this managed host.

  • encryption_enabled - Whether or not encryption is enabled for this managed host.

Response Sample

[ { "appliance": { "id": "String", "type": "String" }, "average_eps": 42, "average_fpm": 42, "components": [ "String <one of: eventcollector, eventprocessor, dataNode, magistrate, ariel_query_server, ariel_proxy_server, vis, assetprofiler, qflow, hostcontext, tunnel, setuptunnel, ecs-ec, ecs-ep, resolveragent, resolver_manager, offsiteSource, offsiteTarget, accumulator, offline_forwarder, qvm, qvmprocessor, qvmscanner, qvmhostedscanner, qvmsiteprotector, arc_builder, tomcat-rm, ziptie-server, qrm, asset_change_publisher, forensicsnode, forensics_realtime, masterdaemon>" ], "compression_enabled": true, "encryption_enabled": true, "eps_allocation": 42, "eps_rate_hardware_limit": 42, "fpm_allocation": 42, "fpm_rate_hardware_limit": 42, "hostname": "String", "id": 42, "license_serial_number": "String", "peak_eps": 42, "peak_fpm": 42, "primary_server_id": 42, "private_ip": "String", "public_ip": "String", "secondary_server_id": 42, "status": "String <one of: Active, ADDING, Deleted, Deleting, ADD_FAILED, New, ADD_FAILED_VERSION_CHECK, ADD_FAILED_DEPLOY_IN_PROGRESS, ADD_FAILED_RETRY_CONNECTION, ADD_FAILED_HA, ADD_FAILED_CHECK_LOGS>", "version": "String" } ]

GET /config/deployment/hosts/{id}

Retrieves a deployed host by ID.

Table 312: GET /config/deployment/hosts/{id} Resource Details

MIME Type

application/json

Table 313: GET /config/deployment/hosts/{id} Request Parameter Details

Parameter

Type

Optionality

Data Type

MIME Type

Description

id

path

Required

Number (Integer)

text/plain

Required - The ID of the deployed host to be retrieved.

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 314: GET /config/deployment/hosts/{id} Response Codes

HTTP Response Code

Unique Code

Description

200

 

The host was successfully retrieved.

404

1002

No such host is deployed for the given ID

422

1003

The provided ID was a negative number or zero.

500

1004

An error occurred during the retrieval of the host.

Response Description

The associated deployed host object. The Host object has the following fields:

  • id - The ID of this managed host.

  • hostname - The host name of this managed host.

  • private_ip - The private IP of this managed host.

  • public_ip - The public IP of this managed host.

  • appliance - An object that represents the appliance type ID and description of this managed host.

  • version - The installed version on this managed host.

  • status - The status of this managed host.

  • eps_rate_hardware_limit - The upper limit for eps_allocation based on hardware constraints for this managed host.

  • eps_allocation - The allocated eps rate of this managed host.

  • average_eps - The average eps rate of this managed host over the previous month.

  • peak_eps - The peak eps rate that was experienced by this managed host over the previous month.

  • fpm_rate_hardware_limit - The upper limit for fpm_allocation based on hardware constraints for this managed host.

  • fpm_allocation - The allocated fpm rate of this managed host.

  • average_fpm - The average fpm rate of this managed host over the previous month.

  • peak_fpm - The peak fpm rate that was experienced by this managed host over the previous month.

  • primary_server_id - The ID for the primary server host for this managed host.

  • secondary_server_id - If configured, the ID for the secondary server host for this managed host.

  • license_serial_number - The serial number that is associated with this managed host's license.

  • components - A list of components that are associated with this managed host.

  • compression_enabled - Whether or not compression is enabled for this managed host.

  • encryption_enabled - Whether or not encryption is enabled for this managed host.

Response Sample

[ { "appliance": { "id": "String", "type": "String" }, "average_eps": 42, "average_fpm": 42, "components": [ "String <one of: eventcollector, eventprocessor, dataNode, magistrate, ariel_query_server, ariel_proxy_server, vis, assetprofiler, qflow, hostcontext, tunnel, setuptunnel, ecs-ec, ecs-ep, resolveragent, resolver_manager, offsiteSource, offsiteTarget, accumulator, offline_forwarder, qvm, qvmprocessor, qvmscanner, qvmhostedscanner, qvmsiteprotector, arc_builder, tomcat-rm, ziptie-server, qrm, asset_change_publisher, forensicsnode, forensics_realtime, masterdaemon>" ], "compression_enabled": true, "encryption_enabled": true, "eps_allocation": 42, "eps_rate_hardware_limit": 42, "fpm_allocation": 42, "fpm_rate_hardware_limit": 42, "hostname": "String", "id": 42, "license_serial_number": "String", "peak_eps": 42, "peak_fpm": 42, "primary_server_id": 42, "private_ip": "String", "public_ip": "String", "secondary_server_id": 42, "status": "String <one of: Active, ADDING, Deleted, Deleting, ADD_FAILED, New, ADD_FAILED_VERSION_CHECK, ADD_FAILED_DEPLOY_IN_PROGRESS, ADD_FAILED_RETRY_CONNECTION, ADD_FAILED_HA, ADD_FAILED_CHECK_LOGS>", "version": "String" } ]

POST /config/deployment/hosts/{id}

Updates a host by ID and sends a JMS message to update the pipeline.

Table 315: POST /config/deployment/hosts/{id} Resource Details

MIME Type

application/json

Table 316: POST /config/deployment/hosts/{id} Request Parameter Details

Parameter

Type

Optionality

Data Type

MIME Type

Description

id

path

Required

Number (Integer)

text/plain

Required - The ID of the staged host to be updated.

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 317: POST /config/deployment/hosts/{id} Request Body Details

Parameter

Data Type

MIME Type

Description

Sample

host

Object

application

/json

Required - The host values to be updated. At the moment, the only writable properties are eps_allocation and fpm_allocation.

{ "appliance": { "id": "String", "type": "String" }, "average_eps": 42, "average_fpm": 42, "components": [ "String <one of: eventcollector, eventprocessor, dataNode, magistrate, ariel_query_server, ariel_proxy_server, vis, assetprofiler, qflow, hostcontext, tunnel, setuptunnel, ecs-ec, ecs-ep, resolveragent, resolver_manager, offsiteSource, offsiteTarget, accumulator, offline_forwarder, qvm, qvmprocessor, qvmscanner, qvmhostedscanner, qvmsiteprotector, arc_builder, tomcat-rm, ziptie-server, qrm, asset_change_publisher, forensicsnode, forensics_realtime, masterdaemon>" ], "compression_enabled": true, "encryption_enabled": true, "eps_allocation": 42, "eps_rate_hardware_limit": 42, "fpm_allocation": 42, "fpm_rate_hardware_limit": 42, "hostname": "String", "id": 42, "license_serial_number": "String", "peak_eps": 42, "peak_fpm": 42, "primary_server_id": 42, "private_ip": "String", "public_ip": "String", "secondary_server_id": 42, "status": "String <one of: Active, ADDING, Deleted, Deleting, ADD_FAILED, New, ADD_FAILED_VERSION_CHECK, ADD_FAILED_DEPLOY_IN_PROGRESS, ADD_FAILED_RETRY_CONNECTION, ADD_FAILED_HA, ADD_FAILED_CHECK_LOGS, ADD_FAILED_QVMPROCESSOR_ALREADY_EXISTS>", "version": "String" }

Table 318: POST /config/deployment/hosts/{id} Response Codes

HTTP Response Code

Unique Code

Description

200

 

The host was successfully updated.

404

1010

Could not find the host to update.

417

1011

EPS values are expected to be a multiple of the set EPS block. By default the block size is 500.

417

1012

FPM values are expected to be a multiple of the set FPM block. By default the block size is 10000.

417

1013

The EPS value given does not meet the minimum required EPS 200.

417

1014

The FPM value given does not meet the minimum required FPM 200.

417

1016

Can't change EPS/FPM values for a host with a serialized license.

417

1017

EPS value exceeds hardware limit.

417

1018

FPM value exceeds hardware limit.

417

1019

EPS value is greater than that available in the license pool.

417

1020

FPM value is greater than that available in the license pool.

422

1009

null

500

1021

null

Response Description

The updated host object. The host object has the following fields:

  • id - The ID of this managed host.

  • hostname - The host name of this managed host.

  • private_ip - The private IP of this managed host.

  • public_ip - The public IP of this managed host.

  • appliance - An object that represents the appliance type ID and description of this managed host.

  • version - The installed version on this managed host.

  • status - The status of this managed host.

  • eps_rate_hardware_limit - The upper limit for eps_allocation based on hardware constraints for this managed host.

  • eps_allocation - The allocated eps rate of this managed host.

  • average_eps - The average eps rate of this managed host over the previous month.

  • peak_eps - The peak eps rate that was experienced by this managed host over the previous month.

  • fpm_rate_hardware_limit - The upper limit for fpm_allocation based on hardware constraints for this managed host.

  • fpm_allocation - The allocated fpm rate of this managed host.

  • average_fpm - The average fpm rate of this managed host over the previous month.

  • peak_fpm - The peak fpm rate that was experienced by this managed host over the previous month.

  • primary_server_id - The ID for the primary server host for this managed host.

  • secondary_server_id - If configured, the ID for the secondary server host for this managed host.

  • license_serial_number - The serial number associated with this managed host's license.

  • components - A list of components that are associated with this managed host.

  • compression_enabled - Whether or not compression is enabled for this managed host.

  • encryption_enabled - Whether or not encryption is enabled for this managed host.

* @throws ServerProcessingException An unexpected exception occurred during the updating of the host.

Response Sample

[ { "appliance": { "id": "String", "type": "String" }, "average_eps": 42, "average_fpm": 42, "components": [ "String <one of: eventcollector, eventprocessor, dataNode, magistrate, ariel_query_server, ariel_proxy_server, vis, assetprofiler, qflow, hostcontext, tunnel, setuptunnel, ecs-ec, ecs-ep, resolveragent, resolver_manager, offsiteSource, offsiteTarget, accumulator, offline_forwarder, qvm, qvmprocessor, qvmscanner, qvmhostedscanner, qvmsiteprotector, arc_builder, tomcat-rm, ziptie-server, qrm, asset_change_publisher, forensicsnode, forensics_realtime, masterdaemon>" ], "compression_enabled": true, "encryption_enabled": true, "eps_allocation": 42, "eps_rate_hardware_limit": 42, "fpm_allocation": 42, "fpm_rate_hardware_limit": 42, "hostname": "String", "id": 42, "license_serial_number": "String", "peak_eps": 42, "peak_fpm": 42, "primary_server_id": 42, "private_ip": "String", "public_ip": "String", "secondary_server_id": 42, "status": "String <one of: Active, ADDING, Deleted, Deleting, ADD_FAILED, New, ADD_FAILED_VERSION_CHECK, ADD_FAILED_DEPLOY_IN_PROGRESS, ADD_FAILED_RETRY_CONNECTION, ADD_FAILED_HA, ADD_FAILED_CHECK_LOGS>", "version": "String" } ]

GET /config/deployment/license_pool

Retrieves the deployed license pool information.

Table 319: GET /config/deployment/license_pool Resource Details

MIME Type

application/json

Table 320: GET /config/deployment/license_pool Request Parameter Details

Parameter

Type

Optionality

Data Type

MIME Type

Description

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 321: GET /config/deployment/license_pool Response Codes

HTTP Response Code

Unique Code

Description

200

 

The license pool was successfully retrieved.

500

1001

An error occurred during the retrieval of the license pool.

Response Description

The deployed license pool information.

  • eps(allocated) - The amount of EPS rate allocated from the pool.

  • eps(overallocated) - Whether EPS is overallocated or not in the pool.

  • eps(total) - The total EPS rate available in the pool.

  • fpm(allocated) - The amount of FPM rate allocated from the pool.

  • fpm(overallocated) - Whether FPM is overallocated or not in the pool.

  • fpm(total) - The total FPM rate available in the pool.

Response Sample

{ "eps": { "allocated": 42, "overallocated": true, "total": 42 }, "fpm": { "allocated": 42, "overallocated": true, "total": 42 } }

GET /config/domain_management/domains

Retrieves the list of all domains, active and deleted (including the default domain).

The list is ordered by domain ID. If domains were never configured, only the default domain is returned.

Table 322: GET /config/domain_management/domains Resource Details

MIME Type

application/json

Table 323: GET /config/domain_management/domains 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.

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.

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.

Table 324: GET /config/domain_management/domains Response Codes

HTTP Response Code

Unique Code

Description

200

 

The domain list has been successfully retrieved.

500

1020

An error occurred while the domain list was being retrieved.

Response Description

The list of domain objects.

Response Sample

[ { "asset_scanner_ids": [ 42 ], "custom_properties": [ { "capture_result": "String", "id": 42 } ], "deleted": true, "description": "String", "event_collector_ids": [ 42 ], "flow_collector_ids": [ 42 ], "flow_source_ids": [ 42 ], "id": 42, "log_source_group_ids": [ 42 ], "log_source_ids": [ 42 ], "name": "String", "qvm_scanner_ids": [ 42 ], "tenant_id": 42 } ]

POST /config/domain_management/domains

Creates a new domain.

Table 325: POST /config/domain_management/domains Resource Details

MIME Type

application/json

Table 326: POST /config/domain_management/domains 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 327: POST /config/domain_management/domains Request Body Details

Parameter

Data Type

MIME Type

Description

Sample

domain

Object

application/json

A domain JSON object (its id parameter is ignored).

{ "asset_scanner_ids": [42], "custom_properties": [{"capture_result": "String", "id": 42}], "deleted": true, "description": "String", "event_collector_ids": [42], "flow_collector_ids": [42], "flow_source_ids": [42], "log_source_group_ids": [42], "log_source_ids": [42], "name": "String", "qvm_scanner_ids": [42], "tenant_id": 42 }

Table 328: POST /config/domain_management/domains Response Codes

HTTP Response Code

Unique Code

Description

201

 

The domain has been successfully created.

409

1004

A domain object parameter already exists.

422

1005

A domain object parameter is invalid.

500

1020

An error occurred while the domain was being created.

Response Description

A created domain object.

Response Sample

{ "asset_scanner_ids": [ 42 ], "custom_properties": [ { "capture_result": "String", "id": 42 } ], "deleted": true, "description": "String", "event_collector_ids": [ 42 ], "flow_collector_ids": [ 42 ], "flow_source_ids": [ 42 ], "id": 42, "log_source_group_ids": [ 42 ], "log_source_ids": [ 42 ], "name": "String", "qvm_scanner_ids": [ 42 ], "tenant_id": 42 }

GET /config/domain_management/domains/{domain_id}

Retrieves a domain by domain ID.

Table 329: GET /config/domain_management/domains/{domain_id} Resource Details

MIME Type

application/json

Table 330: GET /config/domain_management/domains/{domain_id} Request Parameter Details

Parameter

Type

Optionality

Data Type

MIME Type

Description

domain_id

path

Required

Number (Integer)

text/plain

The ID of the domain object 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 331: GET /config/domain_management/domains/{domain_id} Response Codes

HTTP Response Code

Unique Code

Description

200

 

The domain has been successfully retrieved.

404

1002

No domain was found for the provided domain id.

500

1020

An error occurred while the domain was being retrieved.

Response Description

A domain object.

Response Sample

{ "asset_scanner_ids": [ 42 ], "custom_properties": [ { "capture_result": "String", "id": 42 } ], "deleted": true, "description": "String", "event_collector_ids": [ 42 ], "flow_collector_ids": [ 42 ], "flow_source_ids": [ 42 ], "id": 42, "log_source_group_ids": [ 42 ], "log_source_ids": [ 42 ], "name": "String", "qvm_scanner_ids": [ 42 ], "tenant_id": 42 }

POST /config/domain_management/domains/{domain_id}

Updates an existing domain.

Table 332: POST /config/domain_management/domains/{domain_id} Resource Details

MIME Type

application/json

Table 333: POST /config/domain_management/domains/{domain_id} Request Parameter Details

Parameter

Type

Optionality

Data Type

MIME Type

Description

domain_id

path

Required

Number (Integer)

text/plain

The ID of the domain object to update.

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 334: POST /config/domain_management/domains/{domain_id} Request Body Details

Parameter

Data Type

MIME Type

Description

Sample

domain

Object

application/json

A domain JSON object.

{ "asset_scanner_ids": [42], "custom_properties": [{"capture_result": "String", "id": 42}], "deleted": true, "description": "String", "event_collector_ids": [42], "flow_collector_ids": [42], "flow_source_ids": [42], "log_source_group_ids": [42], "log_source_ids": [42], "name": "String", "qvm_scanner_ids": [42], "tenant_id": 42 }

Table 335: POST /config/domain_management/domains/{domain_id} Response Codes

HTTP Response Code

Unique Code

Description

200

 

The domain has been successfully updated.

404

1002

No domain was found for the provided domain id.

409

1004

A domain object parameter already exists.

422

1005

A domain object parameter is invalid.

500

1020

An error occurred while the domain was being updated.

Response Description

The updated domain object.

Response Sample

{ "asset_scanner_ids": [ 42 ], "custom_properties": [ { "capture_result": "String", "id": 42 } ], "deleted": true, "description": "String", "event_collector_ids": [ 42 ], "flow_collector_ids": [ 42 ], "flow_source_ids": [ 42 ], "id": 42, "log_source_group_ids": [ 42 ], "log_source_ids": [ 42 ], "name": "String", "qvm_scanner_ids": [ 42 ], "tenant_id": 42 }

DELETE /config/domain_management/domains/{domain_id}

Deletes a domain by domain ID.

All domain mappings are also deleted

Table 336: DELETE /config/domain_management/domains/{domain_id} Resource Details

MIME Type

application/json

Table 337: DELETE /config/domain_management/domains/{domain_id} Request Parameter Details

Parameter

Type

Optionality

Data Type

MIME Type

Description

domain_id

path

Required

Number (Integer)

text/plain

The ID of the domain object to delete.

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 338: DELETE /config/domain_management/domains/{domain_id} Response Codes

HTTP Response Code

Unique Code

Description

200

 

The domain has been successfully deleted.

404

1002

No domain was found for the provided domain id.

422

1005

Default domain cannot be deleted.

500

1020

An error occurred while the domain was being deleted.

Response Description

The deleted domain object with its parameter deleted set to true.

Response Sample

{ "asset_scanner_ids": [ 42 ], "custom_properties": [ { "capture_result": "String", "id": 42 } ], "deleted": true, "description": "String", "event_collector_ids": [ 42 ], "flow_collector_ids": [ 42 ], "flow_source_ids": [ 42 ], "id": 42, "log_source_group_ids": [ 42 ], "log_source_ids": [ 42 ], "name": "String", "qvm_scanner_ids": [ 42 ], "tenant_id": 42 }

GET /config/event_retention_buckets

Retrieves a list of event retention buckets.

Table 339: GET /config/event_retention_buckets Resource Details

MIME Type

application/json

Table 340: GET /config/event_retention_buckets 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 341: GET /config/event_retention_buckets Response Codes

HTTP Response Code

Unique Code

Description

200

 

The event retention buckets were retrieved.

422

1010

A request parameter is not valid.

500

1020

An error occurred during the attempt to retrieve the event retention buckets.

Response Description

An array of Retention Bucket objects. An Retention Bucket object contains the following fields:

  • id - Integer - The ID of the retention bucket.

  • bucket_id - Integer - The Bucket ID of the retention bucket. ( 0 - 10 )

  • priority - Integer - The priority of the retention bucket. ( 0 - 10 ).

  • name - String - The name of the retention bucket.

  • database - String - The database of the retention bucket, EVENTS or FLOWS.

  • description - String - The description of the retention bucket.

  • period - Integer - The retention period in hours.

  • delete - String - The delete protocol of the retention bucket, IMMEDIATELY or ON_DEMAND.

  • created - Long - The time in milliseconds since epoch since the retention bucket was created.

  • modified - Long - The time in milliseconds since epoch since the retention bucket was last modified.

  • saved_search_id - String - The id of the saved search used by the retention bucket.

  • enabled - Boolean - True if the retention bucket is enabled.

Response Sample

[ { "bucket_id": 42, "created": 42, "database": "String", "deletion": "String <one of: ON_DEMAND, IMMEDIATELY>", "description": "String", "enabled": true, "id": 42, "modified": 42, "name": "String", "period": 42, "priority": 42, "saved_search_id": "String" } ]

GET /config/event_retention_buckets/{id}

Retrieves an event retention bucket.

Table 342: GET /config/event_retention_buckets/{id} Resource Details

MIME Type

application/json

Table 343: GET /config/event_retention_buckets/{id} Request Parameter Details

Parameter

Type

Optionality

Data Type

MIME Type

Description

id

path

Required

Number (Integer)

text/plain

null

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 344: GET /config/event_retention_buckets/{id} Response Codes

HTTP Response Code

Unique Code

Description

200

 

The event retention bucket was retrieved.

404

1002

The event retention bucket does not exist.

500

1020

An error occurred during the attempt to retrieve the event retention bucket.

Response Description

The retention bucket after it has been retrieved. An Retention Bucket object contains the following fields:

  • id - Integer - The ID of the retention bucket.

  • bucket_id - Integer - The Bucket ID of the retention bucket (0 - 10).

  • priority - Integer - The priority of the retention bucket (0 - 10).

  • name - String - The name of the retention bucket.

  • database - String - The database of the retention bucket, EVENTS or FLOWS.

  • description - String - The description of the retention bucket.

  • period - Integer - The retention period in hours.

  • delete - String - The delete protocol of the retention bucket, IMMEDIATELY or ON_DEMAND.

  • created - Long - The time in milliseconds since epoch since the retention bucket was created.

  • modified - Long - The time in milliseconds since epoch since the retention bucket was last modified.

  • saved_search_id - String - The ID of the saved search that is used by the retention bucket.

  • enabled - Boolean - True if the retention bucket is enabled.

Response Sample

{ "bucket_id": 42, "created": 42, "database": "String", "deletion": "String <one of: ON_DEMAND, IMMEDIATELY>", "description": "String", "enabled": true, "id": 42, "modified": 42, "name": "String", "period": 42, "priority": 42, "saved_search_id": "String" }

POST /config/event_retention_buckets/{id}

Updates the event retention bucket owner or enabled/disabled only.

Table 345: POST /config/event_retention_buckets/{id} Resource Details

MIME Type

application/json

Table 346: POST /config/event_retention_buckets/{id} Request Parameter Details

Parameter

Type

Optionality

Data Type

MIME Type

Description

id

path

Required

Number (Integer)

text/plain

null

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 347: POST /config/event_retention_buckets/{id} Request Body Details

Parameter

Data Type

MIME Type

Description

Sample

retention_bucket

Object

application/json

null

{ "id": 1, "name": "String", "description": "String", "priority": 1, "period": 1, "deletion": "String", "created": 123123, "modified": 123123, "saved_search_id": "String", "enabled": true }

Table 348: POST /config/event_retention_buckets/{id} Response Codes

HTTP Response Code

Unique Code

Description

200

 

The event retention bucket has been updated.

404

1002

The event retention bucket does not exist.

409

1004

The provided user does not have the required capabilities to own the event retention bucket.

422

1005

A request parameter is not valid.

500

1020

An error occurred during the attempt to update the event retention bucket.

Response Description

The Retention Bucket after it is updated. A Retention Bucket object contains the following fields:

  • id - Integer - The ID of the retention bucket.

  • bucket_id - Integer - The Bucket ID of the retention bucket (0 - 10).

  • priority - Integer - The priority of the retention bucket (0 - 10).

  • name - String - The name of the retention bucket.

  • database - String - The database of the retention bucket, EVENTS or FLOWS.

  • description - String - The description of the retention bucket.

  • period - Integer - The retention period in hours.

  • delete - String - The delete protocol of the retention bucket, IMMEDIATELY or ON_DEMAND.

  • created - Long - The time in milliseconds since epoch since the retention bucket was created.

  • modified - Long - The time in milliseconds since epoch since the retention bucket was last modified.

  • saved_search_id - String - The ID of the saved search that is used by the retention bucket.

  • enabled - Boolean - True if the retention bucket is enabled.

Response Sample

{ "bucket_id": 42, "created": 42, "database": "String", "deletion": "String <one of: ON_DEMAND, IMMEDIATELY>", "description": "String", "enabled": true, "id": 42, "modified": 42, "name": "String", "period": 42, "priority": 42, "saved_search_id": "String" }

DELETE /config/event_retention_buckets/{id}

Deletes an event retention bucket.

Table 349: DELETE /config/event_retention_buckets/{id} Resource Details

MIME Type

text/plain

Table 350: DELETE /config/event_retention_buckets/{id} Request Parameter Details

Parameter

Type

Optionality

Data Type

MIME Type

Description

id

path

Required

Number (Integer)

text/plain

null

Table 351: DELETE /config/event_retention_buckets/{id} Response Codes

HTTP Response Code

Unique Code

Description

204

 

The Event Retention Bucket was deleted.

403

1009

You do not have the proper capabilities to delete the event retention bucket.

404

1002

The Event Retention Bucket does not exist.

500

1020

An error occurred during the attempt to delete the event retention bucket.

Response Description

Response Sample

DELETE /config/event_sources/custom_properties/calculated_properties/{calculated_property_id}

Deletes the event calculated property. To ensure safe deletion, a dependency check is carried out. This check might take some time. An asynchronous task to do is started for this check.

Table 352: DELETE /config/event_sources/custom_properties/calculated_properties/{calculated_property_id} Resource Details

MIME Type

application/json

Table 353: DELETE /config/event_sources/custom_properties/calculated_properties/{calculated_property_id} Request Parameter Details

Parameter

Type

Optionality

Data Type

MIME Type

Description

calculated_ property_id

path

Required

Number (Integer)

text/plain

Required - String - The ID of the event calculated property to delete.

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 354: DELETE /config/event_sources/custom_properties/calculated_properties/{calculated_property_id} Response Codes

HTTP Response Code

Unique Code

Description

202

 

The calculated event property deletion task was accepted and is in progress.

403

1009

The requested delete action is unauthorized.

404

1002

The requested calculated event property cannot be found.

422

1005

One or more parameters are invalid in the request.

500

1020

An error occurred during the attempt to delete a calculated event property.

Response Description

A Delete Task Status object and the location header set to the task status URL "/api/config/event_sources/custom_properties/calculated_property_delete_tasks/{task_id}". A Delete Task Status object contains the following fields:

  • id - Long - The ID of the task.

  • message - String - The localized task message.

  • status - String - The current state of the task.

  • name - String - The name of the task.

  • created_by - String - The name of the user who started the task.

  • created - Long - The time in milliseconds since epoch since the task was created.

  • started - Long - The time in milliseconds since epoch since the task was started.

  • modified - Long - The time in milliseconds since epoch since the task was modified.

  • completed - Long - The time in milliseconds since epoch since the task was completed.

Response Sample

{ "completed": 42, "created": 42, "created_by": "String", "id": 42, "message": "String", "modified": 42, "name": "String", "started": 42, "status": "String <one of: CANCELLED, CANCELING, CANCEL_REQUESTED, COMPLETED, CONFLICT, EXCEPTION, INITIALIZING, INTERRUPTED, PAUSED, PROCESSING, QUEUED, RESUMING>" }

GET /config/event_sources/custom_properties/calculated_properties/{calculated_property_id}/dependents

Retrieves the objects that depend on the event calculated property.

Table 355: GET /config/event_sources/custom_properties/calculated_properties/{calculated_property_id}/dependents Resource Details

MIME Type

application/json

Table 356: GET /config/event_sources/custom_properties/calculated_properties/{calculated_property_id}/dependents Request Parameter Details

Parameter

Type

Optionality

Data Type

MIME Type

Description

calculated_ property_id

path

Required

Number (Integer)

text/plain

Required - The ID of the event calculated property to get the dependents for.

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 357: GET /config/event_sources/custom_properties/calculated_properties/{calculated_property_id}/dependents Response Codes

HTTP Response Code

Unique Code

Description

202

 

The calculated event property dependents retrieval was accepted and is in progress.

403

1009

The user does not have the required authorization to start the task for finding dependents of calculated event property.

404

1002

The requested calculated event property cannot be found.

422

1005

One or more parameters are invalid in the request.

500

1020

An error occurred during the attempt to initiate the calculated event property dependents retrieval task.

Response Description

A Dependents Task Status object and the location header set to the task status URL "/api/config/event_sources/custom_properties/calculated_property_dependents_tasks/{task_id}". A Dependent Task Status object contains the following fields:

  • id - Long - The ID of the task.

  • message - String - The localized task message.

  • status - String - The current state of the task.

  • name - String - The name of the task.

  • created_by - String - The name of the user who started the task.

  • cancelled_by - String - The name of the user who requested to cancel the task.

  • created - Long - The time in milliseconds since epoch since the task was created.

  • started - Long - The time in milliseconds since epoch since the task was started.

  • modified - Long - The time in milliseconds since epoch since the task was modified.

  • completed - Long - The time in milliseconds since epoch since the task was completed.

  • number_of_dependents - Long - The number of dependents found. The value is null until the task completes.

  • maximum - Long - The maximum number of objects to check for dependency.

  • progress - Long - The number of objects that were checked for dependency.

  • task_components - Array - An array of task component objects. A task component object contains the following fields:

    • message - String - The localized sub-task status message.

    • status - String - The current state of the sub-task.

    • sub_task_type - String - The type of the sub-task

    • maximum - Long - The maximum number of objects to check for dependency.

    • progress - Long - The number of objects that were checked for dependency.

    • created - Long - The time in milliseconds since epoch since the sub-task was created.

    • started - Long - The time in milliseconds since epoch since the sub-task was started.

    • modified - Long - The time in milliseconds since epoch since the sub-task was modified.

    • completed - Long - The time in milliseconds since epoch since the sub-task was completed.

Response Sample

{ "cancelled_by": "String", "completed": 42, "created": 42, "created_by": "String", "id": 42, "maximum": 42, "message": "String", "modified": 42, "name": "String", "number_of_dependents": 42, "progress": 42, "started": 42, "status": "String <one of: CANCELLED, CANCELING, CANCEL_REQUESTED, COMPLETED, CONFLICT, EXCEPTION, INITIALIZING, INTERRUPTED, PAUSED, PROCESSING, QUEUED, RESUMING>", "task_components": [ { "completed": 42, "created": 42, "maximum": 42, "message": "String", "modified": 42, "number_of_dependents": 42, "progress": 42, "started": 42, "status": "String <one of: CANCELLED, CANCELING, CANCEL_REQUESTED, COMPLETED, CONFLICT, EXCEPTION, INITIALIZING, INTERRUPTED, PAUSED, PROCESSING, QUEUED, RESUMING>", "task_sub_type": "String <one of: FIND_DEPENDENT_ARIEL_SAVED_SEARCHES, FIND_DEPENDENT_OFFENSE_SAVED_SEARCHES, FIND_DEPENDENT_ASSET_SAVED_SEARCHES, FIND_DEPENDENT_VULNERABILITY_SAVED_SEARCHES, FIND_DEPENDENT_ADE_RULES, FIND_DEPENDENT_RULES, FIND_DEPENDENT_CALCULATED_PROPERTIES, FIND_DEPENDENT_AQL_PROPERTIES, FIND_DEPENDENT_LOG_SOURCE_GROUPS, FIND_DEPENDENT_CUSTOM_PROPERTIES, FIND_DEPENDENT_REPORTS, FIND_DEPENDENT_DASHBOARDS, FIND_DEPENDENT_STORE_AND_FORWARD_POLOCIES, FIND_DEPENDENT_AUTHORIZED_SERVICES, FIND_DEPENDENT_OFFENSE_TYPES, FIND_DEPENDENT_ASSIGNED_OFFENSES, FIND_DEPENDENT_VULNERABILITIES, FIND_DEPENDENT_GROUPS, FIND_DEPENDENT_HISTORICAL_CORRELATION_PROFILES, FIND_DEPENDENT_SECURITY_PROFILES, FIND_DEPENDENT_ARIEL_INDEXING>" } ] }

GET /config/event_sources/custom_properties/calculated_properties/{calculated_property_id}

Retrieves a calculated event property based on the supplied calculated property ID.

Table 358: GET /config/event_sources/custom_properties/calculated_properties/{calculated_property_id} Resource Details