Help us improve your experience.

Let us know what you think.

Do you have time for a two-minute survey?

 

Analytics Endpoints

 

Use the references for REST API V9.0 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 the 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>" } ] }