Help us improve your experience.

Let us know what you think.

Do you have time for a two-minute survey?

 

REST API V10.0 References

 

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

Access Endpoints

Use the references for REST API V10.0 access endpoints.

GET /access/login_attempts

Gets the list of login attempts. For SAAS and single sign on authentication modules, failed login attempts will not be tracked. The successful login attempts will be created when the JSA session is created, not necessarily when the user entered their credentials on the single sign on login page. Any users or authorized service can call this endpoint. If the caller has the ADMIN capability, login attempts for all users will be returned. For all other callers, only login attempts for the current caller will be returned.

Table 1: GET /access/login_attempts Resource Details

MIME Type

application/json

Table 2: GET /access/login_attempts 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.

sort

query

Optional

String

text/plain

Optional - This parameter is used to sort the elements in a list.

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 /access/login_attempts Response Codes

HTTP Response Code

Unique Code

Description

200

 

An array of login attempts. The attempt_time is used as the default sort input in descending order.

422

1005

A request parameter is not valid.

422

1010

Invalid filter criteria supplied.

422

1030

The sort field or order is not valid

500

1020

An error occurred while retiriving login attempts.

Response Description

An array of login attempts. The attempt_time is used as the default sort input in descending order.

  • attempt_time - Long - The time the login attempt happens. This time is in milliseconds since epoch.

  • user_id - Long - ID of user who tried login attempt. Users are accessible through the /api/config/access/users APIs.

  • remote_ip - String - The remote IP address that made the login attempt.

  • attempt_result - Enum - The result of login attempt.

  • attempt_method - Enum - The method of the login attempt. HTTP_BASIC is for API based HTTP basic, and LOGIN_PAGE is for UI login attempt.

Response Sample

[{"attempt_result": "String <one of: SUCCESS, FAILURE>", "attempt_time": 42, "remote_ip": "String", "user_id": 42, "attempt_method": "String <one of: LOGIN_PAGE, HTTP_BASIC>"}]

Analytics Endpoints

Use the references for REST API V10.0 analytics endpoints.

GET /analytics/ade_rules

Retrieves a list of ADE rules.

Table 4: GET /analytics/ade_rules Resource Details

MIME Type

application/json

Table 5: GET /analytics/ade_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 6: 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 7: GET /analytics/ade_rules/{id} Resource Details

MIME Type

application/json

Table 8: 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 9: 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 10: POST /analytics/ade_rules/{id} Resource Details

MIME Type

application/json

Table 11: 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 12: 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 13: 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 14: DELETE /analytics/ade_rules/{id} Resource Details

MIME Type

application/json

Table 15: 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 16: 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 17: GET /analytics/ade_rules/{id}/dependents Resource Details

MIME Type

application/json

Table 18: 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 19: 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_AQL_PROPERTIES, FIND_DEPENDENT_LOG_SOURCE_GROUPS, FIND_DEPENDENT_CUSTOM_PROPERTIES, FIND_DEPENDENT_REPORTS, FIND_DEPENDENT_DASHBOARDS, FIND_DEPENDENT_STORE_AND_FORWARD_POLOCIES, FIND_DEPENDENT_AUTHORIZED_SERVICES, FIND_DEPENDENT_OFFENSE_TYPES, FIND_DEPENDENT_ASSIGNED_OFFENSES, FIND_DEPENDENT_VULNERABILITIES, FIND_DEPENDENT_GROUPS, FIND_DEPENDENT_HISTORICAL_CORRELATION_PROFILES, FIND_DEPENDENT_SECURITY_PROFILES, FIND_DEPENDENT_ARIEL_INDEXING, FIND_DEPENDENT_DOMAIN, FIND_DEPENDENT_NAMED_SERVICES, FIND_DEPENDENT_FORWARDING_PROFILE>" } ] }

GET /analytics/ade_rules/ade_rule_delete_tasks/{task_id}

Retrieves the delete ADE rule task status.

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

MIME Type

application/json

Table 21: 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 22: 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 ADE rule task status.

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

MIME Type

application/json

Table 24: 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 25: 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_AQL_PROPERTIES, FIND_DEPENDENT_LOG_SOURCE_GROUPS, FIND_DEPENDENT_CUSTOM_PROPERTIES, FIND_DEPENDENT_REPORTS, FIND_DEPENDENT_DASHBOARDS, FIND_DEPENDENT_STORE_AND_FORWARD_POLOCIES, FIND_DEPENDENT_AUTHORIZED_SERVICES, FIND_DEPENDENT_OFFENSE_TYPES, FIND_DEPENDENT_ASSIGNED_OFFENSES, FIND_DEPENDENT_VULNERABILITIES, FIND_DEPENDENT_GROUPS, FIND_DEPENDENT_HISTORICAL_CORRELATION_PROFILES, FIND_DEPENDENT_SECURITY_PROFILES, FIND_DEPENDENT_ARIEL_INDEXING, FIND_DEPENDENT_DOMAIN, FIND_DEPENDENT_NAMED_SERVICES, FIND_DEPENDENT_FORWARDING_PROFILE>" } ] }

POST /analytics/ade_rules/ade_rule_dependent_tasks/{task_id}

Cancels a dependent ADE rule task.

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

MIME Type

application/json

Table 27: 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 28: 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 29: 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_AQL_PROPERTIES, FIND_DEPENDENT_LOG_SOURCE_GROUPS, FIND_DEPENDENT_CUSTOM_PROPERTIES, FIND_DEPENDENT_REPORTS, FIND_DEPENDENT_DASHBOARDS, FIND_DEPENDENT_STORE_AND_FORWARD_POLOCIES, FIND_DEPENDENT_AUTHORIZED_SERVICES, FIND_DEPENDENT_OFFENSE_TYPES, FIND_DEPENDENT_ASSIGNED_OFFENSES, FIND_DEPENDENT_VULNERABILITIES, FIND_DEPENDENT_GROUPS, FIND_DEPENDENT_HISTORICAL_CORRELATION_PROFILES, FIND_DEPENDENT_SECURITY_PROFILES, FIND_DEPENDENT_ARIEL_INDEXING, FIND_DEPENDENT_DOMAIN, FIND_DEPENDENT_NAMED_SERVICES, FIND_DEPENDENT_FORWARDING_PROFILE>" } ] }

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

Retrieves the ADE rule dependent task results.

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

MIME Type

application/json

Table 31: 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 32: 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: APP, NAMED_SERVICE, ARIEL_SAVED_SEARCH, ASSET_SAVED_SEARCH, OFFENSE_SAVED_SEARCH, VULNERABILITY_SAVED_SEARCH, QRM_SAVED_SEARCH_GROUP, ASSET_SAVED_SEARCH_GROUP, CUSTOM_RULE_GROUP, EVENT_ARIEL_SAVED_SEARCH_GROUP, FLOW_ARIEL_SAVED_SEARCH_GROUP, LOG_SOURCE_GROUP, MODEL_GROUP, OFFENSE_SAVED_SEARCH_GROUP, QUESTION_GROUP, REPORT_GROUP, SIMULATION_GROUP, TOPOLOGY_SAVED_SEARCH_GROUP, VULNERABILITY_SAVED_SEARCH_GROUP, ASSIGNED_OFFENSE, ASSIGNED_VULNERABILITY, AUTHORIZED_SERVICE, BUILDING_BLOCK, CRE_RULE, CRE_ADE_RULE, EVENT_REGEX_PROPERTY, EVENT_REGEX_PROPERTY_DEPENDENCY, EVENT_CALCULATED_PROPERTY, FLOW_REGEX_PROPERTY, FLOW_REGEX_PROPERTY_DEPENDENCY, FLOW_CALCULATED_PROPERTY, DASHBOARD, GV_REFERENCE, REPORT, REFERENCE_DATA, REFERENCE_DATA_MAP_OF_SETS, REFERENCE_DATA_MAPS, REFERENCE_DATA_SETS, REFERENCE_DATA_TABLES, REFERENCE_DATA_RESPONSE, REFERENCE_SET_RESPONSE, EVENT_RETENTION_BUCKET, FLOW_RETENTION_BUCKET, ROUTING_RULE, STORE_AND_FORWARD_POLICY, USER, HISTORICAL_PROFILE, OFFENSE, EVENT_AQL_PROPERTY, FLOW_AQL_PROPERTY, OFFENSE_TYPE, SECURITY_PROFILE, ARIEL_INDEX, DOMAIN_MAPPING, FORWARDING_PROFILE, REGEX_EXPRESSION, JSON_EXPRESSION, LEEF_EXPRESSION, CEF_EXPRESSION>", "user_has_edit_permissions": true } ]

GET /analytics/building_blocks

Retrieves a list of building block rules.

Table 33: GET /analytics/building_blocks Resource Details

MIME Type

application/json

Table 34: GET /analytics/building_blocks 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 35: 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 36: GET /analytics/building_blocks/building_block_delete_tasks/{task_id} Resource Details

MIME Type

application/json

Table 37: 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 38: 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 39: GET /analytics/building_blocks/building_block_dependent_tasks/{task_id} Resource Details

MIME Type

application/json

Table 40: 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 41: 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_AQL_PROPERTIES, FIND_DEPENDENT_LOG_SOURCE_GROUPS, FIND_DEPENDENT_CUSTOM_PROPERTIES, FIND_DEPENDENT_REPORTS, FIND_DEPENDENT_DASHBOARDS, FIND_DEPENDENT_STORE_AND_FORWARD_POLOCIES, FIND_DEPENDENT_AUTHORIZED_SERVICES, FIND_DEPENDENT_OFFENSE_TYPES, FIND_DEPENDENT_ASSIGNED_OFFENSES, FIND_DEPENDENT_VULNERABILITIES, FIND_DEPENDENT_GROUPS, FIND_DEPENDENT_HISTORICAL_CORRELATION_PROFILES, FIND_DEPENDENT_SECURITY_PROFILES, FIND_DEPENDENT_ARIEL_INDEXING, FIND_DEPENDENT_DOMAIN, FIND_DEPENDENT_NAMED_SERVICES, FIND_DEPENDENT_FORWARDING_PROFILE>" } ] }

POST /analytics/building_blocks/building_block_dependent_tasks/{task_id}

Cancels the dependent the building block rule task.

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

MIME Type

application/json

Table 43: 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 44: 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 45: 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_AQL_PROPERTIES, FIND_DEPENDENT_LOG_SOURCE_GROUPS, FIND_DEPENDENT_CUSTOM_PROPERTIES, FIND_DEPENDENT_REPORTS, FIND_DEPENDENT_DASHBOARDS, FIND_DEPENDENT_STORE_AND_FORWARD_POLOCIES, FIND_DEPENDENT_AUTHORIZED_SERVICES, FIND_DEPENDENT_OFFENSE_TYPES, FIND_DEPENDENT_ASSIGNED_OFFENSES, FIND_DEPENDENT_VULNERABILITIES, FIND_DEPENDENT_GROUPS, FIND_DEPENDENT_HISTORICAL_CORRELATION_PROFILES, FIND_DEPENDENT_SECURITY_PROFILES, FIND_DEPENDENT_ARIEL_INDEXING, FIND_DEPENDENT_DOMAIN, FIND_DEPENDENT_NAMED_SERVICES, FIND_DEPENDENT_FORWARDING_PROFILE>" } ] }

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

Retrieves the building block rule dependent task results.

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

MIME Type

application/json

Table 47: 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 48: 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: APP, NAMED_SERVICE, ARIEL_SAVED_SEARCH, ASSET_SAVED_SEARCH, OFFENSE_SAVED_SEARCH, VULNERABILITY_SAVED_SEARCH, QRM_SAVED_SEARCH_GROUP, ASSET_SAVED_SEARCH_GROUP, CUSTOM_RULE_GROUP, EVENT_ARIEL_SAVED_SEARCH_GROUP, FLOW_ARIEL_SAVED_SEARCH_GROUP, LOG_SOURCE_GROUP, MODEL_GROUP, OFFENSE_SAVED_SEARCH_GROUP, QUESTION_GROUP, REPORT_GROUP, SIMULATION_GROUP, TOPOLOGY_SAVED_SEARCH_GROUP, VULNERABILITY_SAVED_SEARCH_GROUP, ASSIGNED_OFFENSE, ASSIGNED_VULNERABILITY, AUTHORIZED_SERVICE, BUILDING_BLOCK, CRE_RULE, CRE_ADE_RULE, EVENT_REGEX_PROPERTY, EVENT_REGEX_PROPERTY_DEPENDENCY, EVENT_CALCULATED_PROPERTY, FLOW_REGEX_PROPERTY, FLOW_REGEX_PROPERTY_DEPENDENCY, FLOW_CALCULATED_PROPERTY, DASHBOARD, GV_REFERENCE, REPORT, REFERENCE_DATA, REFERENCE_DATA_MAP_OF_SETS, REFERENCE_DATA_MAPS, REFERENCE_DATA_SETS, REFERENCE_DATA_TABLES, REFERENCE_DATA_RESPONSE, REFERENCE_SET_RESPONSE, EVENT_RETENTION_BUCKET, FLOW_RETENTION_BUCKET, ROUTING_RULE, STORE_AND_FORWARD_POLICY, USER, HISTORICAL_PROFILE, OFFENSE, EVENT_AQL_PROPERTY, FLOW_AQL_PROPERTY, OFFENSE_TYPE, SECURITY_PROFILE, ARIEL_INDEX, DOMAIN_MAPPING, FORWARDING_PROFILE, REGEX_EXPRESSION, JSON_EXPRESSION, LEEF_EXPRESSION, CEF_EXPRESSION>", "user_has_edit_permissions": true } ]

GET /analytics/building_blocks/{id}

Retrieves a building block rule.

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

MIME Type

application/json

Table 50: 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 51: 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 52: POST /analytics/building_blocks/{id} Resource Details

MIME Type

application/json

Table 53: 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 54: 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 55: 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 56: DELETE /analytics/building_blocks/{id} Resource Details

MIME Type

application/json

Table 57: 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 58: 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 59: GET /analytics/building_blocks/{id}/dependents Resource Details

MIME Type

application/json

Table 60: 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 61: 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_AQL_PROPERTIES, FIND_DEPENDENT_LOG_SOURCE_GROUPS, FIND_DEPENDENT_CUSTOM_PROPERTIES, FIND_DEPENDENT_REPORTS, FIND_DEPENDENT_DASHBOARDS, FIND_DEPENDENT_STORE_AND_FORWARD_POLOCIES, FIND_DEPENDENT_AUTHORIZED_SERVICES, FIND_DEPENDENT_OFFENSE_TYPES, FIND_DEPENDENT_ASSIGNED_OFFENSES, FIND_DEPENDENT_VULNERABILITIES, FIND_DEPENDENT_GROUPS, FIND_DEPENDENT_HISTORICAL_CORRELATION_PROFILES, FIND_DEPENDENT_SECURITY_PROFILES, FIND_DEPENDENT_ARIEL_INDEXING, FIND_DEPENDENT_DOMAIN, FIND_DEPENDENT_NAMED_SERVICES, FIND_DEPENDENT_FORWARDING_PROFILE>" } ] }

GET /analytics/custom_actions/actions

Retrieves a list of available custom actions.

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

MIME Type

application/json

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

MIME Type

application/json

Table 66: 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 67: 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 68: 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 69: GET /analytics/custom_actions/actions/{action_id} Resource Details

MIME Type

application/json

Table 70: 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 71: 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 72: POST /analytics/custom_actions/actions/{action_id} Resource Details

MIME Type

application/json

Table 73: 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 74: 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 75: 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 76: DELETE /analytics/custom_actions/actions/{action_id} Resource Details

MIME Type

text/plain

Table 77: 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 78: 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 79: GET /analytics/custom_actions/interpreters Resource Details

MIME Type

application/json

Table 80: 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 81: 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 82: GET /analytics/custom_actions/interpreters/{interpreter_id} Resource Details

MIME Type

application/json

Table 83: 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 84: 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 85: GET /analytics/custom_actions/scripts Resource Details

MIME Type

application/json

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

MIME Type

application/json

Table 89: 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 90: 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 91: 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 92: GET /analytics/custom_actions/scripts/{script_id} Resource Details

MIME Type

application/json

Table 93: 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 94: 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 95: POST /analytics/custom_actions/scripts/{script_id} Resource Details

MIME Type

application/json

Table 96: 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 97: 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 98: 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 99: DELETE /analytics/custom_actions/scripts/{script_id} Resource Details

MIME Type

text/plain

Table 100: 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 101: 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 102: GET /analytics/rule_groups Resource Details

MIME Type

application/json

Table 103: 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 104: 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 105: GET /analytics/rule_groups/{group_id} Resource Details

MIME Type

application/json

Table 106: 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 107: 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 108: POST /analytics/rule_groups/{group_id} Resource Details

MIME Type

application/json

Table 109: 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 110: 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 111: 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 112: DELETE /analytics/rule_groups/{group_id} Resource Details

MIME Type

text/plain

Table 113: 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 114: 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 115: GET /analytics/rules Resource Details

MIME Type

application/json

Table 116: GET /analytics/rules 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 117: 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 rule task status.

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

MIME Type

application/json

Table 119: 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 120: 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 121: GET /analytics/rules/rule_dependent_tasks/{task_id} Resource Details

MIME Type

application/json

Table 122: 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 123: 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_AQL_PROPERTIES, FIND_DEPENDENT_LOG_SOURCE_GROUPS, FIND_DEPENDENT_CUSTOM_PROPERTIES, FIND_DEPENDENT_REPORTS, FIND_DEPENDENT_DASHBOARDS, FIND_DEPENDENT_STORE_AND_FORWARD_POLOCIES, FIND_DEPENDENT_AUTHORIZED_SERVICES, FIND_DEPENDENT_OFFENSE_TYPES, FIND_DEPENDENT_ASSIGNED_OFFENSES, FIND_DEPENDENT_VULNERABILITIES, FIND_DEPENDENT_GROUPS, FIND_DEPENDENT_HISTORICAL_CORRELATION_PROFILES, FIND_DEPENDENT_SECURITY_PROFILES, FIND_DEPENDENT_ARIEL_INDEXING, FIND_DEPENDENT_DOMAIN, FIND_DEPENDENT_NAMED_SERVICES, FIND_DEPENDENT_FORWARDING_PROFILE>" } ] }

POST /analytics/rules/rule_dependent_tasks/{task_id}

Cancels the dependent rule task.

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

MIME Type

application/json

Table 125: 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 126: 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 127: 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_AQL_PROPERTIES, FIND_DEPENDENT_LOG_SOURCE_GROUPS, FIND_DEPENDENT_CUSTOM_PROPERTIES, FIND_DEPENDENT_REPORTS, FIND_DEPENDENT_DASHBOARDS, FIND_DEPENDENT_STORE_AND_FORWARD_POLOCIES, FIND_DEPENDENT_AUTHORIZED_SERVICES, FIND_DEPENDENT_OFFENSE_TYPES, FIND_DEPENDENT_ASSIGNED_OFFENSES, FIND_DEPENDENT_VULNERABILITIES, FIND_DEPENDENT_GROUPS, FIND_DEPENDENT_HISTORICAL_CORRELATION_PROFILES, FIND_DEPENDENT_SECURITY_PROFILES, FIND_DEPENDENT_ARIEL_INDEXING, FIND_DEPENDENT_DOMAIN, FIND_DEPENDENT_NAMED_SERVICES, FIND_DEPENDENT_FORWARDING_PROFILE>" } ] }

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

Retrieves the rule dependent task results.

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

MIME Type

application/json

Table 129: 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 130: 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: APP, NAMED_SERVICE, ARIEL_SAVED_SEARCH, ASSET_SAVED_SEARCH, OFFENSE_SAVED_SEARCH, VULNERABILITY_SAVED_SEARCH, QRM_SAVED_SEARCH_GROUP, ASSET_SAVED_SEARCH_GROUP, CUSTOM_RULE_GROUP, EVENT_ARIEL_SAVED_SEARCH_GROUP, FLOW_ARIEL_SAVED_SEARCH_GROUP, LOG_SOURCE_GROUP, MODEL_GROUP, OFFENSE_SAVED_SEARCH_GROUP, QUESTION_GROUP, REPORT_GROUP, SIMULATION_GROUP, TOPOLOGY_SAVED_SEARCH_GROUP, VULNERABILITY_SAVED_SEARCH_GROUP, ASSIGNED_OFFENSE, ASSIGNED_VULNERABILITY, AUTHORIZED_SERVICE, BUILDING_BLOCK, CRE_RULE, CRE_ADE_RULE, EVENT_REGEX_PROPERTY, EVENT_REGEX_PROPERTY_DEPENDENCY, EVENT_CALCULATED_PROPERTY, FLOW_REGEX_PROPERTY, FLOW_REGEX_PROPERTY_DEPENDENCY, FLOW_CALCULATED_PROPERTY, DASHBOARD, GV_REFERENCE, REPORT, REFERENCE_DATA, REFERENCE_DATA_MAP_OF_SETS, REFERENCE_DATA_MAPS, REFERENCE_DATA_SETS, REFERENCE_DATA_TABLES, REFERENCE_DATA_RESPONSE, REFERENCE_SET_RESPONSE, EVENT_RETENTION_BUCKET, FLOW_RETENTION_BUCKET, ROUTING_RULE, STORE_AND_FORWARD_POLICY, USER, HISTORICAL_PROFILE, OFFENSE, EVENT_AQL_PROPERTY, FLOW_AQL_PROPERTY, OFFENSE_TYPE, SECURITY_PROFILE, ARIEL_INDEX, DOMAIN_MAPPING, FORWARDING_PROFILE, REGEX_EXPRESSION, JSON_EXPRESSION, LEEF_EXPRESSION, CEF_EXPRESSION>", "user_has_edit_permissions": true } ]

GET /analytics/rules/{id}

Retrieves a rule.

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

MIME Type

application/json

Table 132: 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 133: 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 134: POST /analytics/rules/{id} Resource Details

MIME Type

application/json

Table 135: 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 136: 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 137: 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 138: DELETE /analytics/rules/{id} Resource Details

MIME Type

application/json

Table 139: 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 140: 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 141: GET /analytics/rules/{id}/dependents Resource Details

MIME Type

application/json

Table 142: 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 143: 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_AQL_PROPERTIES, FIND_DEPENDENT_LOG_SOURCE_GROUPS, FIND_DEPENDENT_CUSTOM_PROPERTIES, FIND_DEPENDENT_REPORTS, FIND_DEPENDENT_DASHBOARDS, FIND_DEPENDENT_STORE_AND_FORWARD_POLOCIES, FIND_DEPENDENT_AUTHORIZED_SERVICES, FIND_DEPENDENT_OFFENSE_TYPES, FIND_DEPENDENT_ASSIGNED_OFFENSES, FIND_DEPENDENT_VULNERABILITIES, FIND_DEPENDENT_GROUPS, FIND_DEPENDENT_HISTORICAL_CORRELATION_PROFILES, FIND_DEPENDENT_SECURITY_PROFILES, FIND_DEPENDENT_ARIEL_INDEXING, FIND_DEPENDENT_DOMAIN, FIND_DEPENDENT_NAMED_SERVICES, FIND_DEPENDENT_FORWARDING_PROFILE>" } ] }

Ariel Endpoints

Use the references for REST API V10.0 Ariel endpoints.

GET /ariel/databases

Retrieves a list of available Ariel database names

Table 144: GET /ariel/databases Resource Details

MIME Type

application/json

Table 145: GET /ariel/databases Request Parameter Details

Parameter

Type

Optionality

Data Type

MIME Type

Description

filter

query

Optional

String

text/plain

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

Range

header

Optional

String

text/plain

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

Table 146: GET /ariel/databases Response Codes

HTTP Response Code

Unique Code

Description

200

 

The database list was retrieved.

Response Description

The names of the available Ariel databases.

Response Sample

[ "String" ]

GET /ariel/databases/{database_name}

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

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

MIME Type

application/json

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

Parameter

Type

Optionality

Data Type

MIME Type

Description

database_name

path

Required

String

text/plain

Required. The name of the Ariel database that contains the columns that you want to retrieve.

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.

Range

header

Optional

String

text/plain

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

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

HTTP Response Code

Unique Code

Description

200

 

The database columns were retrieved.

404

1002

The database does not exist.

Response Description

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

Response Sample

{ "columns": [ { "argument_type": "String", "indexable": true, "name": "String", "nullable": true, "object_value_type": "String <one of: NULL, STRUCT, Byte, Short, Integer, Long, UnsignedByte, UnsignedShort, UnsignedInt, UnsignedLong, BigInteger, Double, Float, Port, Host, HostV4V6, HostV6, MACAddress, String, ByteArray, UnsignedIntHex, Boolean, Binary>", "provider_name": "String" } ] }

GET /ariel/event_saved_search_groups

Retrieves a list the event Ariel saved search groups.

Table 150: GET /ariel/event_saved_search_groups Resource Details

MIME Type

application/json

Table 151: GET /ariel/event_saved_search_groups Request Parameter Details

Parameter

Type

Optionality

Data Type

MIME Type

Description

fields

query

Optional

String

text/plain

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

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

HTTP Response Code

Unique Code

Description

200

 

The event Ariel saved search groups were returned.

500

1020

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

Response Description

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

  • id - Long - The ID of the group.

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

  • type - String - The type of the group.

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

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

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

  • owner - String - The owner of the group.

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

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

Response Sample

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

GET /ariel/event_saved_search_groups/{group_id}

Retrieves an event Ariel saved search group.

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

MIME Type

application/json

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

Parameter

Type

Optionality

Data Type

MIME Type

Description

group_id

path

Required

Number (Integer)

text/plain

null

fields

query

Optional

String

text/plain

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

Table 155: GET /ariel/event_saved_search_groups/{group_id} Response Codes

HTTP Response Code

Unique Code

Description

200

 

The event Ariel saved search group was retrieved.

404

1002

The vent Ariel saved search group does not exist.

500

1020

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

Response Description

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

  • id - Long - The ID of the group.

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

  • type - String - The type of the group.

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

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

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

  • owner - String - The owner of the group.

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

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

Response Sample

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

POST /ariel/event_saved_search_groups/{group_id}

Updates the owner of an event Ariel saved search group.

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

MIME Type

application/json

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

Parameter

Type

Optionality

Data Type

MIME Type

Description

group_id

path

Required

Number (Integer)

text/plain

null

fields

header

Optional

String

text/plain

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

Table 158: POST /ariel/event_saved_search_groups/{group_id} Request Body Details

Parameter

Data Type

MIME Type

Description

Sample

group

Object

application

/json

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

{

  • "child_groups": [ 42 ],

  • "child_items": [ "String" ],

  • "description": "String",

  • "id": 42,

  • "level": 42,

  • "name": "String",

  • "owner": "String",

  • "parent_id": 42,

  • "type": "String <one of:

  • LOG_SOURCE_GROUP,

  • REPORT_GROUP,

  • RULE_GROUP,

  • EVENT_SAVED_SEARCH _GROUP,

  • FLOW_SAVED_SEARCH _GROUP,

  • OFFENSE_SAVED_SEARCH _GROUP,

  • QRM_SAVED_SEARCH _GROUP,

  • MODEL_SAVED_SEARCH_GROUP,

  • QUESTION_SAVED_SEARCH _GROUP,

  • SIMULATION_SAVED_SEARCH _GROUP,

  • TOPOLOGY_SAVED_SEARCH _GROUP,

  • ASSET_SAVED_SEARCH_GROUP,

  • VULNERABILITY_SAVED _SEARCH _GROUP>" }

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

HTTP Response Code

Unique Code

Description

200

 

The event Ariel saved search group was updated.

404

1002

The event Ariel saved search group does not exist.

409

1004

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

422

1005

A request parameter is not valid.

500

1020

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

Response Description

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

  • id - Long - The ID of the group.

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

  • type - String - The type of the group.

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

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

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

  • owner - String - The owner of the group.

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

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

Response Sample

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

DELETE /ariel/event_saved_search_groups/{group_id}

Deletes an event Ariel saved search group.

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

MIME Type

text/plain

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

Parameter

Type

Optionality

Data Type

MIME Type

Description

group_id

path

Required

Number (Integer)

text/plain

null

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

HTTP Response Code

Unique Code

Description

204

 

The event Ariel saved search group was deleted.

404

1002

The event Ariel saved search group does not exist.

409

1004

null

500

1020

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

Response Description

Response Sample

GET /ariel/flow_saved_search_groups

Retrieves a list of flow Ariel saved search groups.

Table 163: GET /ariel/flow_saved_search_groups Resource Details

MIME Type

application/json

Table 164: GET /ariel/flow_saved_search_groups Request Parameter Details

Parameter

Type

Optionality

Data Type

MIME Type

Description

fields

query

Optional

String

text/plain

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

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

HTTP Response Code

Unique Code

Description

200

 

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

500

1020

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

Response Description

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

  • id - Long - The ID of the group.

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

  • type - String - The type of the group.

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

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

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

  • owner - String - The owner of the group.

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

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

Response Sample

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

GET /ariel/flow_saved_search_groups/{group_id}

Retrieves a flow Ariel saved search group.

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

MIME Type

application/json

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

Parameter

Type

Optionality

Data Type

MIME Type

Description

group_id

path

Required

Number (Integer)

text/plain

null

fields

query

Optional

String

text/plain

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

Table 168: GET /ariel/flow_saved_search_groups/{group_id} Response Codes

HTTP Response Code

Unique Code

Description

200

 

The flow Ariel saved search group was retrieved.

404

1002

The flow Ariel saved search group does not exist.

500

1020

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

Response Description

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

  • id - Long - The ID of the group.

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

  • type - String - The type of the group.

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

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

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

  • owner - String - The owner of the group.

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

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

Response Sample

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

POST /ariel/flow_saved_search_groups/{group_id}

Updates the owner of a flow Ariel saved search group.

Table 169: POST /ariel/flow_saved_search_groups/{group_id} Resource Details

MIME Type

application/json

Table 170: POST /ariel/flow_saved_search_groups/{group_id} Request Parameter Details

Parameter

Type

Optionality

Data Type

MIME Type

Description

group_id

path

Required

Number (Integer)

text/plain

null

fields

header

Optional

String

text/plain

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

Table 171: POST /ariel/flow_saved_search_groups/{group_id} Request Body Details

Parameter

Data Type

MIME Type

Description

Sample

group

Object

application/

json

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

{

  • "child_groups": [ 42 ],

  • "child_items": [ "String" ],

  • "description": "String",

  • "id": 42,

  • "level": 42,

  • "name": "String",

  • "owner": "String",

  • "parent_id": 42,

  • "type": "String <one of:

  • LOG_SOURCE_GROUP,

  • REPORT_GROUP,

  • RULE_GROUP,

  • EVENT_SAVED_SEARCH _GROUP,

  • FLOW_SAVED_SEARCH _GROUP,

  • OFFENSE_SAVED_SEARCH _GROUP,

  • QRM_SAVED_SEARCH _GROUP,

  • MODEL_SAVED_SEARCH_GROUP,

  • QUESTION_SAVED_SEARCH _GROUP,

  • SIMULATION_SAVED_SEARCH _GROUP,

  • TOPOLOGY_SAVED_SEARCH _GROUP,

  • ASSET_SAVED_SEARCH_GROUP,

  • VULNERABILITY_SAVED _SEARCH _GROUP>" }

Table 172: POST /ariel/flow_saved_search_groups/{group_id} Response Codes

HTTP Response Code

Unique Code

Description

200

 

The flow Ariel saved search group was updated.

404

1002

The flow Ariel saved search group does not exist.

409

1004

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

422

1005

A request parameter is not valid.

500

1020

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

Response Description

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

  • id - Long - The ID of the group.

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

  • type - String - The type of the group.

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

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

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

  • owner - String - The owner of the group.

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

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

Response Sample

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

DELETE /ariel/flow_saved_search_groups/{group_id}

Deletes a flow Ariel saved search group.

Table 173: DELETE /ariel/flow_saved_search_groups/{group_id} Resource Details

MIME Type

text/plain

Table 174: DELETE /ariel/flow_saved_search_groups/{group_id} Request Parameter Details

Parameter

Type

Optionality

Data Type

MIME Type

Description

group_id

path

Required

Number (Integer)

text/plain

null

Table 175: DELETE /ariel/flow_saved_search_groups/{group_id} Response Codes

HTTP Response Code

Unique Code

Description

204

 

The flow Ariel saved search group was deleted.

404

1002

The flow Ariel saved search group does not exist.

409

1004

null

500

1020

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

Response Description

Response Sample

GET /ariel/flow_vlans

Retrieves a list of available flow VLAN IDs in the Ariel database.

Table 176: GET /ariel/flow_vlans Resource Details

MIME Type

application/json

Table 177: GET /ariel/flow_vlans 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 178: GET /ariel/flow_vlans Response Codes

HTTP Response Code

Unique Code

Description

200

 

The flow VLAN ID list was retrieved.

500

1000

An error occurred while the flow VLAN ID list was being retrieved.

Response Description

An array of flow VLAN ID objects. A flow VLAN ID object contains the following fields:

  • id - Long - The ID of the flow VLAN field.

  • enterprise_vlan_id - Short - The enterprise VLAN ID.

  • customer_vlan_id - Short - The customer VLAN ID.

Response Sample

[ { "customer_vlan_id": 42, "enterprise_vlan_id": 42, "id": 42 } ]

DELETE /ariel/flow_vlans/{id}

Deletes a flow VLAN ID with specified enterprise and customer VLAN ID's and removes any associated domain mappings.

Table 179: DELETE /ariel/flow_vlans/{id} Resource Details

MIME Type

text/plain

Table 180: DELETE /ariel/flow_vlans/{id} Request Parameter Details

Parameter

Type

Optionality

Data Type

MIME Type

Description

id

path

Required

Number (Integer)

text/plain

Required - The ID of the flow VLAN ID object to be deleted. Note that this is also the concatenation of the customer VLAN ID to the enterprise VLAN ID.

Table 181: DELETE /ariel/flow_vlans/{id} Response Codes

HTTP Response Code

Unique Code

Description

204

 

The flow VLAN ID has been successfully deleted.

404

1031

The flow VLAN ID specified could not be found.

500

1030

An error occurred while the flow VLAN ID was being deleted.

Response Description

The deleted flow VLAN ID object. A flow VLAN ID object contains the following fields:

  • id - Long - The ID of the flow VLAN field.

  • enterprise_vlan_id - Short - The enterprise VLAN ID.

  • customer_vlan_id - Short - The customer VLAN ID.

Response Sample

GET /ariel/flow_vlans/{id}

Retrieves a flow VLAN ID object by VLAN ID.

Table 182: GET /ariel/flow_vlans/{id} Resource Details

MIME Type

application/json

Table 183: GET /ariel/flow_vlans/{id} Request Parameter Details

Parameter

Type

Optionality

Data Type

MIME Type

Description

id

path

Required

Number (Integer)

text/plain

Required - The ID of the flow VLAN to retrieve.

fields

query

Optional

String

text/plain

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

Table 184: GET /ariel/flow_vlans/{id} Response Codes

HTTP Response Code

Unique Code

Description

200

 

The flow VLAN id object was retrieved.

404

1010

No flow VLAN was found for the provided flow VLAN ID.

500

1011

An error occurred while the flow VLAN field was being retrieved.

Response Description

The flow VLAN ID after it is retrieved. A flow VLAN ID object contains the following fields:

  • id - Long - The ID of the flow VLAN field.

  • enterprise_vlan_id - Short - The enterprise VLAN ID.

  • customer_vlan_id - Short - The customer VLAN ID.

Response Sample

{ "customer_vlan_id": 42, "enterprise_vlan_id": 42, "id": 42 }

POST /ariel/flow_vlans

Creates a new flow VLAN field as specified by input parameters.

Table 185: POST /ariel/flow_vlans Resource Details

MIME Type

application/json

Table 186: POST /ariel/flow_vlans 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 187: POST /ariel/flow_vlans Request Body Details

Parameter

Data Type

MIME Type

Description

Sample

body

Object

application/

json

Only the enterprise VLAN ID and customer VLAN ID can be set when creating a new flow VLAN field. All other fields are ignored.

  • id - Int - The ID of the flow VLAN field. Cannot be updated by POST.

  • enterprise_vlan_id - Short - The enterprise VLAN ID for the flow VLAN domain configuration field. The value must be in the range 0 - 4095, where 0 indicates the enterprise VLAN field is non-existent.

  • customer_vlan_id - Short - The customer VLAN ID for the flow VLAN domain configuration field. The value must be in the range 1 - 4095.

{ "customer_vlan_id": 42, "enterprise_vlan_id": 42, "id": 42 }

Table 188: POST /ariel/flow_vlans Response Codes

HTTP Response Code

Unique Code

Description

201

 

The flow VLAN field has been successfully created.

409

1020

A flow VLAN ID object parameter already exists and belongs to a domain.

422

1022

The VLAN provided was invalid. Customer VLAN ID must be between 1 and 4095.

422

1023

The VLAN provided was invalid. Enterprise VLAN ID must be between 0 and 4095 and customer VLAN ID must be between 1 and 4095.

422

1024

The VLAN provided was invalid. Enterprise VLAN ID must be between 0 and 4095.

500

1025

An error occurred while the flow VLAN field was being created.

Response Description

New flow VLAN ID object. A flow VLAN ID object contains the following fields:

  • id - Int - The ID of the flow VLAN field.

  • enterprise_vlan_id - Short - The enterprise VLAN ID.

  • customer_vlan_id - Short - The customer VLAN ID.

Response Sample

{ "customer_vlan_id": 42, "enterprise_vlan_id": 42, "id": 42 }

GET /ariel/functions/{function_name}

Retrieves AQL Function with given name for a given database.

Table 189: GET /ariel/functions/{function_name} Resource Details

MIME Type

application/json

Table 190: GET /ariel/functions/{function_name} Request Parameter Details

Parameter

Type

Optionality

Data Type

MIME Type

Description

database

query

Required

String

text/plain

Required - Name of DB to retrieve functions for.

function_name

path

Required

String

text/plain

Required - The name of function to retrieve.

fields

query

Optional

String

text/plain

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

Table 191: GET /ariel/functions/{function_name} Response Codes

HTTP Response Code

Unique Code

Description

200

 

Function is retrieved

Response Description

List of AQL Functions.

Response Sample

{ "args_types": [ "String" ], "catalog": "String", "class_name": "String", "info": "String", "name": "String", "required_args": 42, "required_capabilities": "String", "return_type": "String", "var_args": true }

GET /ariel/functions

Retrieves AQL Functions for given.

Table 192: GET /ariel/functions Resource Details

MIME Type

application/json

Table 193: GET /ariel/functions Request Parameter Details

Parameter

Type

Optionality

Data Type

MIME Type

Description

database

query

Required

String

text/plain

Name of DB to retrieve functions for.

fields

query

Optional

String

text/plain

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

Table 194: GET /ariel/functions Response Codes

HTTP Response Code

Unique Code

Description

200

 

Functions are retrieved

Response Description

List of AQL Functions.

Response Sample

[ { "args_types": [ "String" ], "catalog": "String", "class_name": "String", "info": "String", "name": "String", "required_args": 42, "required_capabilities": "String", "return_type": "String", "var_args": true } ]

GET /ariel/lookups

Retrieves a list of all tagged field lookups.

Table 195: GET /ariel/lookups Resource Details

MIME Type

application/json

Table 196: GET /ariel/lookups Request Parameter Details

Parameter

Type

Optionality

Data Type

MIME Type

Description

fields

query

Optional

String

text/plain

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

Table 197: GET /ariel/lookups Response Codes

HTTP Response Code

Unique Code

Description

200

 

The lookup list was retrieved.

500

1020

Internal server error

Response Description

The list of available tagged field lookups.

Response Sample

[ { "default_value": "String", "map": { "String": "String" }, "name": "String", "type": "String <one of: NULL, STRUCT, Byte, Short, Integer, Long, UnsignedByte, UnsignedShort, UnsignedInt, UnsignedLong, BigInteger, Double, Float, Port, Host, HostV4V6, HostV6, MACAddress, String, ByteArray, UnsignedIntHex, Boolean, Binary>" } ]

DELETE /ariel/lookups/{name}

Deletes a tagged field lookup with particular name.

Table 198: DELETE /ariel/lookups/{name} Resource Details

MIME Type

application/json

Table 199: DELETE /ariel/lookups/{name} Request Parameter Details

Parameter

Type

Optionality

Data Type

MIME Type

Description

name

path

Required

String

text/plain

The name of this lookup entry

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 200: DELETE /ariel/lookups/{name} Response Codes

HTTP Response Code

Unique Code

Description

202

 

The lookup was deleted.

404

1002

Lookup doesn't exist

500

1020

Internal server error

Response Description

The deleted field lookup.

Response Sample

{ "default_value": "String", "map": { "String": "String" }, "name": "String", "type": "String <one of: NULL, STRUCT, Byte, Short, Integer, Long, UnsignedByte, UnsignedShort, UnsignedInt, UnsignedLong, BigInteger, Double, Float, Port, Host, HostV4V6, HostV6, MACAddress, String, ByteArray, UnsignedIntHex, Boolean, Binary>" }

GET /ariel/lookups/{name}

Retrieves a tagged field lookup by name.

Table 201: GET /ariel/lookups/{name} Resource Details

MIME Type

application/json

Table 202: GET /ariel/lookups/{name} Request Parameter Details

Parameter

Type

Optionality

Data Type

MIME Type

Description

name

path

Required

String

text/plain

The name of lookup entry 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 203: GET /ariel/lookups/{name} Response Codes

HTTP Response Code

Unique Code

Description

200

 

The lookup was retrieved.

404

1002

Lookup with this name does not exist

500

1020

Internal server error

Response Description

The lookup associated with particular name.

Response Sample

{ "default_value": "String", "map": { "String": "String" }, "name": "String", "type": "String <one of: NULL, STRUCT, Byte, Short, Integer, Long, UnsignedByte, UnsignedShort, UnsignedInt, UnsignedLong, BigInteger, Double, Float, Port, Host, HostV4V6, HostV6, MACAddress, String, ByteArray, UnsignedIntHex, Boolean, Binary>" }

POST /ariel/lookups/{name}

Updates a tagged field lookup with particular name.

Table 204: POST /ariel/lookups/{name} Resource Details

MIME Type

application/json

Table 205: POST /ariel/lookups/{name} Request Parameter Details

Parameter

Type

Optionality

Data Type

MIME Type

Description

name

path

Required

String

text/plain

The name of this lookup entry

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 206: POST /ariel/lookups/{name} Request Body Details

Parameter

Data Type

MIME Type

Description

Sample

data

Object

application

/json

Json structure representing all changeable fields for this lookup entry

{ "default_value": "String", "map": { "String": "String" } }

Table 207: POST /ariel/lookups/{name} Response Codes

HTTP Response Code

Unique Code

Description

200

 

The lookup was created.

404

1002

Lookup doesn't exist

500

1020

Internal server error

Response Description

The updated field lookup.

Response Sample

{ "default_value": "String", "map": { "String": "String" }, "name": "String", "type": "String <one of: NULL, STRUCT, Byte, Short, Integer, Long, UnsignedByte, UnsignedShort, UnsignedInt, UnsignedLong, BigInteger, Double, Float, Port, Host, HostV4V6, HostV6, MACAddress, String, ByteArray, UnsignedIntHex, Boolean, Binary>" }

POST /ariel/lookups

Creates a new tagged field lookup.

Table 208: POST /ariel/lookups Resource Details

MIME Type

application/json

Table 209: POST /ariel/lookups 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 210: POST /ariel/lookups Request Body Details

Parameter

Data Type

MIME Type

Description

Sample

data

Object

application

/json

Json structure representing all fields for new lookup entry

{ "default_value": "String", "map": { "String": "String" }, "name": "String", "type": "String <one of: NULL, STRUCT, Byte, Short, Integer, Long, UnsignedByte, UnsignedShort, UnsignedInt, UnsignedLong, BigInteger, Double, Float, Port, Host, HostV4V6, HostV6, MACAddress, String, ByteArray, UnsignedIntHex, Boolean, Binary>" }

Table 211: POST /ariel/lookups Response Codes

HTTP Response Code

Unique Code

Description

201

 

The lookup was created.

500

1020

Internal server error

Response Description

The newly created field lookup.

Response Sample

{ "default_value": "String", "map": { "String": "String" }, "name": "String", "type": "String <one of: NULL, STRUCT, Byte, Short, Integer, Long, UnsignedByte, UnsignedShort, UnsignedInt, UnsignedLong, BigInteger, Double, Float, Port, Host, HostV4V6, HostV6, MACAddress, String, ByteArray, UnsignedIntHex, Boolean, Binary>" }

GET /ariel/parser_keywords

Retrieves keywords applicable to AQL Parser.

Table 212: GET /ariel/parser_keywords Resource Details

MIME Type

application/json

Table 213: GET /ariel/parser_keywords Request Parameter Details

Parameter

Type

Optionality

Data Type

MIME Type

Description

fields

query

Optional

String

text/plain

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

Table 214: GET /ariel/parser_keywords Response Codes

HTTP Response Code

Unique Code

Description

200

 

AQL Parser information retrieved

Response Description

Information about the AQL Parser.

Response Sample

{ "keywords": [ "String" ], "where_clause_keywords": [ "String" ] }

POST /ariel/processors/aql_metadata

Parses the Ariel Query Language (AQL) query expression and returns expected metadata without execution of the query.

This endpoint only accepts SELECT query expressions.

Table 215: POST /ariel/processors/aql_metadata Resource Details

MIME Type

application/json

Table 216: POST /ariel/processors/aql_metadata Request Parameter Details

Parameter

Type

Optionality

Data Type

MIME Type

Description

query_ expression

query

Required

String

text/plain

Required - The AQL query for metadata.

fields

query

Optional

String

text/plain

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

Table 217: POST /ariel/processors/aql_metadata Response Codes

HTTP Response Code

Unique Code

Description

200

 

An AQL query expression was successfully validated.

422

2000

The query_expression contains invalid AQL syntax.

500

1020

An error occurred during the attempt to validate AQL.

503

1010

The Ariel server might be temporarily unavailable or offline. Please try again later.

Response Description

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

Response Sample

{ "columns": [ { "argument_type": "String", "indexable": true, "name": "String", "nullable": true, "object_value_type": "String <one of: NULL, STRUCT, Byte, Short, Integer, Long, UnsignedByte, UnsignedShort, UnsignedInt, UnsignedLong, BigInteger, Double, Float, Port, Host, HostV4V6, HostV6, MACAddress, String, ByteArray, UnsignedIntHex, Boolean, Binary>", "provider_name": "String" } ] }

GET /ariel/saved_search_delete_tasks/{task_id}

Retrieves the delete the Ariel saved search task status.

Table 218: GET /ariel/saved_search_delete_tasks/{task_id} Resource Details

MIME Type

application/json

Table 219: GET /ariel/saved_search_delete_tasks/{task_id} Request Parameter Details

Parameter

Type

Optionality

Data Type

MIME Type

Description

task_id

path

Required

Number (Integer)

text/plain

null

fields

query

Optional

String

text/plain

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

Table 220: GET /ariel/saved_search_delete_tasks/{task_id} Response Codes

HTTP Response Code

Unique Code

Description

200

 

The delete task status was retrieved.

404

1002

The delete task status was exist.

500

1020

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

Response Description

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

  • id - Long - The ID of the task.

  • message - String - The localized task message.

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

  • name - String - The name of the task.

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

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

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

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

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

Response Sample

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

GET /ariel/saved_search_dependent_tasks/{task_id}

Retrieves the dependent Ariel saved search task status.

Table 221: GET /ariel/saved_search_dependent_tasks/{task_id} Resource Details

MIME Type

application/json

Table 222: GET /ariel/saved_search_dependent_tasks/{task_id} Request Parameter Details

Parameter

Type

Optionality

Data Type

MIME Type

Description

task_id

path

Required

Number (Integer)

text/plain

null

fields

query

Optional

String

text/plain

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

Table 223: GET /ariel/saved_search_dependent_tasks/{task_id} Response Codes

HTTP Response Code

Unique Code

Description

200

 

The dependent task status was retrieved.

404

1002

The dependent task status does not exist.

500

1020

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

Response Description

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

  • id - Long - The ID of the task.

  • message - String - The localized task message.

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

  • name - String - The name of the task.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Response Sample

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

POST /ariel/saved_search_dependent_tasks/{task_id}

Cancels the dependent Ariel saved search task.

Table 224: POST /ariel/saved_search_dependent_tasks/{task_id} Resource Details

MIME Type

application/json

Table 225: POST /ariel/saved_search_dependent_tasks/{task_id} Request Parameter Details

Parameter

Type

Optionality

Data Type

MIME Type

Description

task_id

path

Required

Number (Integer)

text/plain

null

fields

header

Optional

String

text/plain

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

Table 226: POST /ariel/saved_search_dependent_tasks/{task_id} Request Body Details

Parameter

Data Type

MIME Type

Description

Sample

task

Object

application/json

null

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

Table 227: POST /ariel/saved_search_dependent_tasks/{task_id} Response Codes

HTTP Response Code

Unique Code

Description

200

 

The delete task status was retrieved.

404

1002

The dependent task status does not exist.

409

1004

The task is in a completed state.

422

1005

A request parameter is not valid.

500

1020

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

Response Description

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

  • id - Long - The ID of the task.

  • message - String - The localized task message.

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

  • name - String - The name of the task.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Response Sample

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

GET /ariel/saved_search_dependent_tasks/{task_id}/results

Retrieves the Ariel saved search dependent task results.

Table 228: GET /ariel/saved_search_dependent_tasks/{task_id}/results Resource Details

MIME Type

application/json

Table 229: GET /ariel/saved_search_dependent_tasks/{task_id}/results Request Parameter Details

Parameter

Type

Optionality

Data Type

MIME Type

Description

task_id

path

Required

Number (Integer)

text/plain

null

fields

query

Optional

String

text/plain

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

Table 230: GET /ariel/saved_search_dependent_tasks/{task_id}/results Response Codes

HTTP Response Code

Unique Code

Description

200

 

The Ariel saved search dependents were retrieved.

404

1002

The Dependent Task Status does not exist.

500

1020

An error occurred during the attempt to retrieve the Ariel saved searches.

Response Description

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

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

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

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

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

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

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

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

Response Sample

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

GET /ariel/saved_searches

Retrieves a list of Ariel saved searches.

Table 231: GET /ariel/saved_searches Resource Details

MIME Type

application/json

Table 232: GET /ariel/saved_searches Request Parameter Details

Parameter

Type

Optionality

Data Type

MIME Type

Description

fields

query

Optional

String

text/plain

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

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 233: GET /ariel/saved_searches Response Codes

HTTP Response Code

Unique Code

Description

200

 

The Ariel saved searches were retrieved.

422

1010

A request parameter is not valid.

500

1020

An error occurred during the attempt to retrieve the Ariel Saved Searches.

Response Description

An array of Ariel Saved Search objects. An Ariel Saved Search object contains the following fields:

  • id - Long - The ID of the Ariel saved search.

  • uuid - String - The uuid of the Ariel saved search.

  • name - String - The name of the Ariel saved search.

  • database - String - The database of the Ariel saved search, events or flows.

  • isShared - Boolean - True if the Ariel saved search is shared with other users.

  • owner - String - The owner of the Ariel saved search.

  • aql - String - The AQL query.

  • description - String - The description of the Ariel saved search.

  • isAggregate - Boolean - True if the Ariel saved search is an aggregate search.

  • isDashboard - Boolean - True if the Ariel saved search is in the dashboard.

  • isDefault - Boolean - True if the Ariel saved search is default search.

  • isQuickSearch - Boolean - True if the Ariel saved search is default search.

Response Sample

[ { "aql": "String", "database": "String <one of: EVENTS, FLOWS>", "description": "String", "id": 42, "is_aggregate": true, "is_dashboard": true, "is_default": true, "is_quick_search": true, "is_shared": true, "name": "String", "owner": "String", "uid": "String" } ]

GET /ariel/saved_searches/{id}

Retrieves an Ariel saved search.

Table 234: GET /ariel/saved_searches/{id} Resource Details

MIME Type

application/json

Table 235: GET /ariel/saved_searches/{id} Request Parameter Details

Parameter

Type

Optionality

Data Type

MIME Type

Description

id

path

Required

Number (Integer)

text/plain

Required - The ID of the Ariel Saved Search to retrieve.

fields

query

Optional

String

text/plain

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

Table 236: GET /ariel/saved_searches/{id} Response Codes

HTTP Response Code

Unique Code

Description

200

 

The Ariel saved search was retrieved.

404

1002

The Ariel saved search does not exist.

500

1020

An error occurred during the attempt to retrieve the Ariel Saved Search.

Response Description

The Ariel saved search after it is retrieved. An Ariel Saved Search object contains the following fields:

  • id - Long - The ID of the Ariel saved search.

  • uuid - String - The uuid of the Ariel saved search.

  • name - String - The name of the Ariel saved search.

  • database - String - The database of the Ariel saved search, events or flows.

  • isShared - Boolean - True if the Ariel saved search is shared with other users.

  • owner - String - The owner of the Ariel saved search.

  • aql - String - The AQL query.

  • description - String - The description of the Ariel saved search.

  • isAggregate - Boolean - True if the Ariel saved search is an aggregate search.

  • isDashboard - Boolean - True if the Ariel saved search is in the dashboard.

  • isDefault - Boolean - True if the Ariel saved search is default search.

  • isQuickSearch - Boolean - True if the Ariel saved search is default search.

Response Sample

{ "aql": "String", "database": "String <one of: EVENTS, FLOWS>", "description": "String", "id": 42, "is_aggregate": true, "is_dashboard": true, "is_default": true, "is_quick_search": true, "is_shared": true, "name": "String", "owner": "String", "uid": "String" }

POST /ariel/saved_searches/{id}

Updates the Ariel saved search.

Table 237: POST /ariel/saved_searches/{id} Resource Details

MIME Type

application/json

Table 238: POST /ariel/saved_searches/{id} Request Parameter Details

Parameter

Type

Optionality

Data Type

MIME Type

Description

id

path

Required

Number (Integer)

text/plain

Required - The ID of the Ariel saved search to edit.

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 239: POST /ariel/saved_searches/{id} Request Body Details

Parameter

Data Type

MIME Type

Description

Sample

saved_search

Object

application/json

Required - Ariel Saved Search object.

{ "is_shared": true, "owner": "String", "is_quick_search": true, "is_default": true, "is_dashboard": true, }

Table 240: POST /ariel/saved_searches/{id} Response Codes

HTTP Response Code

Unique Code

Description

200

 

The Ariel saved search was updated.

403

1009

You do not have the required capabilities to update the Ariel Saved Search.

403

1012

You are not allowed to update the owner field

404

1002

The Ariel saved search does not exist.

409

1007

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

422

2000

null

422

1006

Non group by searches cannot be added to the dashboard.

422

1011

The provided new owner is not an existing user

500

1020

An error occurred during the attempt to update the Ariel Saved Search.

Response Description

The Ariel saved search after it has been updated. An Ariel Saved Search object contains the following fields:

  • id - Long - The Id of the saved search.

  • uuid - String - The uid string of the saved search. There are two formats of uid strings: one is rfc4122 pseudo randomly generated UUID format; the other is a string-digit format, e.g. SEARCH-250.

  • name - String - The name of the Ariel saved search.

  • database - String - The database of the Ariel saved search, events or flows.

  • isShared - Boolean - True if the saved search is shared with everyone.

  • owner - String - Owner of the saved search. Only the admin user can change the owner from one to another. Even the owner itself cannot reassign it to another user.

  • aql - String - The AQL string or a null value. If it is an AQL string, the saved search is an AQL based search. If it is a null value, the saved search is a baisc search that is based on query parameters instead of an AQL.

  • description - String - The description of the Ariel saved search.

  • isAggregate - Boolean - True if the saved search is aggregated, so it could be in dashboard.

  • isDashboard - Boolean - True if the Ariel saved search is in the dashboard.

  • isDefault - Boolean - True if this saved search is the default saved search to the user who calls this endpoint. A user can have only one default saved search.

  • isQuickSearch - Boolean - True if the saved search should be in quick search.

Response Sample

{ "aql": "String", "database": "String <one of: EVENTS, FLOWS>", "description": "String", "id": 42, "is_aggregate": true, "is_dashboard": true, "is_default": true, "is_quick_search": true, "is_shared": true, "name": "String", "owner": "String", "uid": "String" }

DELETE /ariel/saved_searches/{id}

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

Table 241: DELETE /ariel/saved_searches/{id} Resource Details

MIME Type

application/json

Table 242: DELETE /ariel/saved_searches/{id} Request Parameter Details

Parameter

Type

Optionality

Data Type

MIME Type

Description

id

path

Required

Number (Integer)

text/plain

null

fields

query

Optional

String

text/plain

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

Table 243: DELETE /ariel/saved_searches/{id} Response Codes

HTTP Response Code

Unique Code

Description

202

 

The Ariel saved search delete command was accepted and is in progress.

403

1009

You do not have the required capabilities to delete the Ariel saved search.

404

1002

The Ariel saved search does not exist.

500

1020

An error occurred during the attempt to delete the Ariel Saved Search.

Response Description

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

  • id - Long - The ID of the task.

  • message - String - The localized task message.

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

  • name - String - The name of the task.

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

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

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

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

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

Response Sample

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

GET /ariel/saved_searches/{id}/dependents

Retrieves the objects that depend on the Ariel saved search.

Table 244: GET /ariel/saved_searches/{id}/dependents Resource Details

MIME Type

application/json

Table 245: GET /ariel/saved_searches/{id}/dependents Request Parameter Details

Parameter

Type

Optionality

Data Type

MIME Type

Description

id

path

Required

Number (Integer)

text/plain

null

fields

query

Optional

String

text/plain

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

Table 246: GET /ariel/saved_searches/{id}/dependents Response Codes

HTTP Response Code

Unique Code

Description

202

 

The Ariel saved search dependents retrieval was accepted and is in progress

404

1002

The Ariel saved search does not exist

500

1020

An error occurred during the attempt to initiate the Ariel Saved Search dependents retrieval task

Response Description

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

  • id - Long - The ID of the task.

  • message - String - The localized task message.

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

  • name - String - The name of the task.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Response Sample

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

GET /ariel/searches

Retrieves the list of Ariel searches. Search IDs for completed and active searches are returned.

Table 247: GET /ariel/searches Resource Details

MIME Type

application/json

Table 248: GET /ariel/searches Request Parameter Details

Parameter

Type

Optionality

Data Type

MIME Type

Description

db_name

query

Optional

String

text/plain

Optional - The name of the Ariel database to retrieve the list of Ariel searches.

filter

query

Optional

String

text/plain

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

Range

header

Optional

String

text/plain

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

Table 249: GET /ariel/searches Response Codes

HTTP Response Code

Unique Code

Description

200

 

The search list was retrieved.

500

1020

An error occurred during the attempt to retrieve the list of searches.

503

1010

The ariel server might be temporarily unavailable or offline. Please try again later.

Response Description

A list of search IDs.

Response Sample

[ "String" ]

POST /ariel/searches

Create a new asynchronous Ariel search.

Creates a new Ariel search as specified by the Ariel Query Language (AQL) query expression. Searches are executed asynchronously. A reference to the search ID is returned and should be used in subsequent API calls to determine the status of the search and retrieve the results once it is complete.

This endpoint only accepts SELECT query expressions.

Queries are applied to the range of data in a certain time interval. By default this time interval is the last 60 seconds. An alternative time interval can be specified by specifying them as part of the query expression. For further information, see the AQL reference guide.

Table 250: POST /ariel/searches Resource Details

MIME Type

application/json

Table 251: POST /ariel/searches Request Parameter Details

Parameter

Type

Optionality

Data Type

MIME Type

Description

query_expression

query

Optional

String

text/plain

Optional - The AQL query to execute. Mutually exclusive with saved_search_id

saved_search_id

query

Optional

Number (Integer)

text/plain

Optional - Saved search ID to execute. Mutually exclusive with queryExpression

Table 252: POST /ariel/searches Response Codes

HTTP Response Code

Unique Code

Description

201

 

A new Ariel search was successfully created.

404

1002

The Ariel saved search does not exist.

409

1004

The search cannot be created. The requested search ID that was provided in the query expression is already in use. Please use a unique search ID (or allow one to be generated).

422

2000

The query_expression contains invalid AQL syntax.

422

1005

A request parameter is not valid.

500

1020

An error occurred during the attempt to create a new search.

503

1010

The Ariel server might be temporarily unavailable or offline. Please try again later.

Response Description

Information about the specified search, including the search ID. Use the search ID to access or manipulate the search with the other API endpoints.

If the exact search being created was already recently created, the response message will return a reference to the original search ID rather than creating a new search.

Response Sample

SearchStatus { "cursor_id": "s16", "compressed_data_file_count": 0, "compressed_data_total_size": 0, "data_file_count": 5470, "data_total_size": 67183115, "index_file_count": 0, "index_total_size": 0, "processed_record_count": 1256462, "error_messages": [ { "code": "String", "contexts": [ "String" ], "message": "String", "severity": "String <one of: INFO, WARN, ERROR>" } ], "desired_retention_time_msec": 86400000, "progress": 46, "progress_details": [ 0, 0, 0, 0, 66957, 652657, 76594, 89809, 86032, 107729 ], "query_execution_time": 1480, "query_string": "SELECT sourceip, starttime, qid, sourceport from events into s16 where sourceip in (select destinationip from events) parameters snapshotsize=2, PROGRESSDETAILSRESOLUTION=10", "record_count": 1240923, "save_results": false, "status": "String <one of: WAIT, EXECUTE, SORTING, COMPLETED, CANCELED, ERROR>", "snapshot": { "events": [ { "sourceip": "10.100.65.20", "starttime": 1467049610018, "qid": 10034, "sourceport": 13675 }, { "sourceip": "10.100.100.121", "starttime": 1467049610019, "qid": 20034, "sourceport": 80 } ] }, "subsearch_ids": [ "sub_id_1" ], "search_id": "s16" }

DELETE /ariel/searches/{search_id}

Deletes an Ariel search. This discards any results that were collected and stops the search if it is in progress. This search is deleted regardless of whether the results were saved.

Table 253: DELETE /ariel/searches/{search_id} Resource Details

MIME Type

application/json

Table 254: DELETE /ariel/searches/{search_id} Request Parameter Details

Parameter

Type

Optionality

Data Type

MIME Type

Description

search_id

path

Required

String

text/plain

Required - The search ID of the search to delete.

Table 255: DELETE /ariel/searches/{search_id} Response Codes

HTTP Response Code

Unique Code

Description

202

 

The delete request has been accepted.

404

1002

The search does not exist.

422

1005

A request parameter is not valid.

500

1020

An error occurred during the attempt to delete the search.

503

1010

The ariel server might be temporarily unavailable or offline. Please try again later.

Response Description

Information about the deleted search.

Response Sample

{ "cursor_id": "s16", "compressed_data_file_count": 0, "compressed_data_total_size": 0, "data_file_count": 5470, "data_total_size": 67183115, "index_file_count": 0, "index_total_size": 0, "processed_record_count": 1256462, "error_messages": [ { "code": "String", "contexts": [ "String" ], "message": "String", "severity": "String <one of: INFO, WARN, ERROR>" } ], "desired_retention_time_msec": 86400000, "progress": 46, "progress_details": [ 0, 0, 0, 0, 66957, 652657, 76594, 89809, 86032, 107729 ], "query_execution_time": 1480, "query_string": "SELECT sourceip, starttime, qid, sourceport from events into s16 where sourceip in (select destinationip from events) parameters snapshotsize=2, PROGRESSDETAILSRESOLUTION=10", "record_count": 1240923, "save_results": false, "status": "String <one of: WAIT, EXECUTE, SORTING, COMPLETED, CANCELED, ERROR>", "snapshot": { "events": [ { "sourceip": "10.100.65.20", "starttime": 1467049610018, "qid": 10034, "sourceport": 13675 }, { "sourceip": "10.100.100.121", "starttime": 1467049610019, "qid": 20034, "sourceport": 80 } ] }, "subsearch_ids": [ "sub_id_1" ], "search_id": "s16" }

GET /ariel/searches/{search_id}

Retrieves information about an Ariel search.

Retrieve status information for a search, based on the search ID parameter. The same informational fields are returned regardless of whether the search is in progress or is complete.

Table 256: GET /ariel/searches/{search_id} Resource Details

MIME Type

application/json

Table 257: GET /ariel/searches/{search_id} Request Parameter Details

Parameter

Type

Optionality

Data Type

MIME Type

Description

search_id

path

Required

String

text/plain

Required. The identifier for an Ariel search.

Prefer

header

Optional

String

text/plain

Optional. Specify 'wait=N' where N is number of seconds to wait for COMPLETED status of the search.

Table 258: GET /ariel/searches/{search_id} Response Codes

HTTP Response Code

Unique Code

Description

200

 

The search information was retrieved.

206

 

The search information was retrieved with 'Prefer: wait=N' timeout(sec) expired before the search is completed

404

1002

The search does not exist.

422

1005

A request parameter is not valid.

500

1020

An error occurred during the attempt to retrieve the search information.

503

1010

The Ariel server might be temporarily unavailable or offline. Please try again later.

Response Description

Information about the specified search, including the search status.

Response Sample

{ "cursor_id": "s16", "compressed_data_file_count": 0, "compressed_data_total_size": 0, "data_file_count": 5470, "data_total_size": 67183115, "index_file_count": 0, "index_total_size": 0, "processed_record_count": 1256462, "error_messages": [ { "code": "String", "contexts": [ "String" ], "message": "String", "severity": "String <one of: INFO, WARN, ERROR>" } ], "desired_retention_time_msec": 86400000, "progress": 46, "progress_details": [ 0, 0, 0, 0, 66957, 652657, 76594, 89809, 86032, 107729 ], "query_execution_time": 1480, "query_string": "SELECT sourceip, starttime, qid, sourceport from events into s16 where sourceip in (select destinationip from events) parameters snapshotsize=2, PROGRESSDETAILSRESOLUTION=10", "record_count": 1240923, "save_results": false, "status": "String <one of: WAIT, EXECUTE, SORTING, COMPLETED, CANCELED, ERROR>", "snapshot": { "events": [ { "sourceip": "10.100.65.20", "starttime": 1467049610018, "qid": 10034, "sourceport": 13675 }, { "sourceip": "10.100.100.121", "starttime": 1467049610019, "qid": 20034, "sourceport": 80 } ] }, "subsearch_ids": [ "sub_id_1" ], "search_id": "s16" }

GET /ariel/searches/{search_id}/metadata

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

Table 259: GET /ariel/searches/{search_id}/metadata Resource Details

MIME Type

application/json

Table 260: GET /ariel/searches/{search_id}/metadata Request Parameter Details

Parameter

Type

Optionality

Data Type

MIME Type

Description

search_id

path

Required

String

text/plain

null

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.

Range

header

Optional

String

text/plain

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

Table 261: GET /ariel/searches/{search_id}/metadata Response Codes

HTTP Response Code

Unique Code

Description

200

 

Columns were successfully retrieved.

404

1002

The search does not exist.

503

1010

The Ariel server might be temporarily unavailable or offline. Please try again later.

Response Description

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

Response Sample

{ "columns": [ { "argument_type": "String", "indexable": true, "name": "String", "nullable": true, "object_value_type": "String <one of: NULL, STRUCT, Byte, Short, Integer, Long, UnsignedByte, UnsignedShort, UnsignedInt, UnsignedLong, BigInteger, Double, Float, Port, Host, HostV4V6, HostV6, MACAddress, String, ByteArray, UnsignedIntHex, Boolean, Binary>", "provider_name": "String" } ] }

POST /ariel/searches/{search_id}

Updates details for an Ariel search. You can update searches in the following ways:

  • To cancel an active search, set the status parameter to CANCELED. This stops the search and keeps any search results that were collected before the search was canceled.

  • The results for a completed search can be saved by setting the save_results parameter to true. This ensures that the search is not automatically removed when it expires in accordance with the retention policy.

The Ariel server uses an internal retention policy to manage available disk space. Searches might be deleted automatically, according to the settings of the retention policy. Searches with saved results are not automatically reclaimed by the server and are therefore retained. A search can be explicitly deleted by using the DELETE /searches/{search_id} endpoint.

Note: Saving too many search results might result in insufficient disk space to process new searches.

Table 262: POST /ariel/searches/{search_id} Resource Details

MIME Type

application/json

Table 263: POST /ariel/searches/{search_id} Request Parameter Details

Parameter

Type

Optionality

Data Type

MIME Type

Description

search_id

path

Required

String

text/plain

Required. The ID of the search to update.

status

query

Optional

String

text/plain

Optional. The only accepted value is CANCELED. If this value is provided, the search is canceled.

save_results

query

Optional

String

text/plain

Optional. The only accepted value is true. If this value is provided, the search results are not deleted by the search expiration removal process. If status parameter was provided, this parameter is not checked and silently ignored.

Table 264: POST /ariel/searches/{search_id} Response Codes

HTTP Response Code

Unique Code

Description

200

 

The search was updated.

404

1002

The search does not exist.

422

1005

A request parameter is not valid.

500

1020

An error occurred during the attempt to update the search.

503

1010

The Ariel server might be temporarily unavailable or offline. Please try again later.

Response Description

Information about the specified search that was updated.

Response Sample

{ "cursor_id": "s16", "compressed_data_file_count": 0, "compressed_data_total_size": 0, "data_file_count": 5470, "data_total_size": 67183115, "index_file_count": 0, "index_total_size": 0, "processed_record_count": 1256462, "error_messages": [ { "code": "String", "contexts": [ "String" ], "message": "String", "severity": "String <one of: INFO, WARN, ERROR>" } ], "desired_retention_time_msec": 86400000, "progress": 46, "progress_details": [ 0, 0, 0, 0, 66957, 652657, 76594, 89809, 86032, 107729 ], "query_execution_time": 1480, "query_string": "SELECT sourceip, starttime from events into s16 where sourceip in (select destinationip from events) parameters snapshotsize=2, PROGRESSDETAILSRESOLUTION=10", "record_count": 1240923, "save_results": false, "status": "EXECUTE", "snapshot": { "events": [ { "sourceip": "10.100.65.20", "starttime": "1467049610018" }, { "sourceip": "10.100.100.121", "starttime": "1467049610019" } ] }, "subsearch_ids": [ "sub_id_1" ], "search_id": "s16" }

GET /ariel/searches/{search_id}/results

Retrieves search results in the requested format.

Retrieve the results of the Ariel search that is identified by the search ID. The Accepts request header indicates the format of the result. The formats are RFC compliant and can be JSON, CSV, XML, or tabular text.

By default, all query result records are returned. To restrict the results to a contiguous subset of the records, you can supply a Range header to specify the inclusive range of records to be returned.

This end-point works with query results that are generated by AQL query expressions. This endpoint might not work as expected for results that are generated by other means. Search results might not be retrievable for searches that are created on the Console.

The response samples are for the following query: Select sourceIP, destinationIP from events.

Table 265: GET /ariel/searches/{search_id}/results Resource Details

MIME Type

application/json application/csv text/table application/xml

Table 266: GET /ariel/searches/{search_id}/results Request Parameter Details

Parameter

Type

Optionality

Data Type

MIME Type

Description

search_id

path

Required

String

text/plain

The ID of the search criteria for the returned results.

Range

header

Optional

String

text/plain

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

Table 267: GET /ariel/searches/{search_id}/results Response Codes

HTTP Response Code

Unique Code

Description

200

 

The search results were retrieved.

404

1002

The search does not exist.

404

1003

Search results not found. The search is still in progress.

422

1005

A request parameter is not valid.

500

1020

An error occurred during the attempt to retrieve the search results.

503

1010

The Ariel server might be temporarily unavailable or offline. Please try again later.

Response Description

The search results for the specified search ID. The format that is used to encapsulate the data depends on the format specified in the Accept header for this request.

Response Sample

{ "events": [ { "sourceIP": "192.0.2.0", "destinationIP": "127.0.0.1" }, { "sourceIP": "192.0.2.0", "destinationIP": "127.0.0.1" } ] }

GET /ariel/taggedfields

Retrieves a list of available tagged fields for Ariel catalog.

Table 268: GET /ariel/taggedfields Resource Details

MIME Type

application/json

Table 269: GET /ariel/taggedfields Request Parameter Details

Parameter

Type

Optionality

Data Type

MIME Type

Description

catalog

query

Optional

String

text/plain

Optional. The name of the Ariel database that contains the tagged fields that you want to retrieve.

fields

query

Optional

String

text/plain

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

Table 270: GET /ariel/taggedfields Response Codes

HTTP Response Code

Unique Code

Description

200

 

The tagged field list was retrieved.

404

1002

The catalog does not exist

500

1020

Internal server error

Response Description

The list of available tagged fields.

Response Sample

[ { "array": true, "catalog": "String", "created": 42, "deleted": true, "description": "String", "format_class_name": "String", "format_params": [ "String" ], "modified": 42, "name": "String", "nullable": true, "tag": 42, "type": "String <one of: NULL, STRUCT, Byte, Short, Integer, Long, UnsignedByte, UnsignedShort, UnsignedInt, UnsignedLong, BigInteger, Double, Float, Port, Host, HostV4V6, HostV6, MACAddress, String, ByteArray, UnsignedIntHex, Boolean, Binary>" } ]

POST /ariel/taggedfields

Creates a new Tagged field as specified by input parameters.

Table 271: POST /ariel/taggedfields Resource Details

MIME Type

application/json

Table 272: POST /ariel/taggedfields Request Parameter Details

Parameter

Type

Optionality

Data Type

MIME Type

Description

tag

query

Required

String

text/plain

The number to be assigned to this tagged property

name

query

Required

String

text/plain

The name of this tagged property

catalog

query

Required

String

text/plain

The name of the Ariel database that will contain the new tagged field.

type

query

Required

String

text/plain

The type of this tagged field

array

query

Required

Boolean

text/plain

Is this field an array?

format_class_name

query

Optional

String

text/plain

Fully qualified name of formatter class

format_params

query

Optional

String

text/plain

Optional parameter for formatter

description

query

Optional

String

text/plain

Optional description of tagged property

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 273: POST /ariel/taggedfields Response Codes

HTTP Response Code

Unique Code

Description

201

 

A new tagged field was successfully created.

404

1002

null

500

1020

null

Response Description

New Tagged field

Response Sample

{ "array": true, "catalog": "String", "created": 42, "deleted": true, "description": "String", "format_class_name": "String", "format_params": [ "String" ], "modified": 42, "name": "String", "nullable": true, "tag": 42, "type": "String <one of: NULL, STRUCT, Byte, Short, Integer, Long, UnsignedByte, UnsignedShort, UnsignedInt, UnsignedLong, BigInteger, Double, Float, Port, Host, HostV4V6, HostV6, MACAddress, String, ByteArray, UnsignedIntHex, Boolean, Binary>" }

DELETE /ariel/taggedfields/{tag}

Deletes a Tagged field with specified tag.

Table 274: DELETE /ariel/taggedfields/{tag} Resource Details

MIME Type

application/json

Table 275: DELETE /ariel/taggedfields/{tag} Request Parameter Details

Parameter

Type

Optionality

Data Type

MIME Type

Description

tag

path

Required

String

text/plain

The number to be assigned to this tagged property

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 276: DELETE /ariel/taggedfields/{tag} Response Codes

HTTP Response Code

Unique Code

Description

202

 

Tagged field was successfully deleted.

404

1002

null

500

1020

null

Response Description

Deleted tagged field

Response Sample

{ "array": true, "catalog": "String", "created": 42, "deleted": true, "description": "String", "format_class_name": "String", "format_params": [ "String" ], "modified": 42, "name": "String", "nullable": true, "tag": 42, "type": "String <one of: NULL, STRUCT, Byte, Short, Integer, Long, UnsignedByte, UnsignedShort, UnsignedInt, UnsignedLong, BigInteger, Double, Float, Port, Host, HostV4V6, HostV6, MACAddress, String, ByteArray, UnsignedIntHex, Boolean, Binary>" }

GET /ariel/taggedfields/{tag}

Retrieves a tagged field with specified tag number.

Table 277: GET /ariel/taggedfields/{tag} Resource Details

MIME Type

application/json

Table 278: GET /ariel/taggedfields/{tag} Request Parameter Details

Parameter

Type

Optionality

Data Type

MIME Type

Description

tag

path

Required

String

text/plain

number, associated with this particular tag property

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 279: GET /ariel/taggedfields/{tag} Response Codes

HTTP Response Code

Unique Code

Description

200

 

The tagged field list was retrieved.

404

1002

The catalog does not exist

500

1020

Internal server error

Response Description

Tagged field, associated with this tag number

Response Sample

{ "array": true, "catalog": "String", "created": 42, "deleted": true, "description": "String", "format_class_name": "String", "format_params": [ "String" ], "modified": 42, "name": "String", "nullable": true, "tag": 42, "type": "String <one of: NULL, STRUCT, Byte, Short, Integer, Long, UnsignedByte, UnsignedShort, UnsignedInt, UnsignedLong, BigInteger, Double, Float, Port, Host, HostV4V6, HostV6, MACAddress, String, ByteArray, UnsignedIntHex, Boolean, Binary>" }

POST /ariel/taggedfields/{tag}

Updates a tagged field with specified tag number.

Table 280: POST /ariel/taggedfields/{tag} Resource Details

MIME Type

application/json

Table 281: POST /ariel/taggedfields/{tag} Request Parameter Details

Parameter

Type

Optionality

Data Type

MIME Type

Description

tag

path

Required

String

text/plain

The number to be assigned to this tagged property

format_class_name

query

Optional

String

text/plain

Fully qualified name of formatter class

format_params

query

Optional

String

text/plain

Optional parameter for formatter

description

query

Optional

String

text/plain

Optional description of tagged property

fields

query

Optional

String

text/plain

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

Table 282: POST /ariel/taggedfields/{tag} Response Codes

HTTP Response Code

Unique Code

Description

200

 

Tagged field was successfully updated.

404

1002

The catalog does not exist

500

1020

Internal server error

Response Description

Updated tagged field

Response Sample

{ "array": true, "catalog": "String", "created": 42, "deleted": true, "description": "String", "format_class_name": "String", "format_params": [ "String" ], "modified": 42, "name": "String", "nullable": true, "tag": 42, "type": "String <one of: NULL, STRUCT, Byte, Short, Integer, Long, UnsignedByte, UnsignedShort, UnsignedInt, UnsignedLong, BigInteger, Double, Float, Port, Host, HostV4V6, HostV6, MACAddress, String, ByteArray, UnsignedIntHex, Boolean, Binary>" }

POST /ariel/validators/aql

Validates the AQL query expression.

Validates the Ariel search as specified by the Ariel Query Language (AQL) query expression.

This endpoint only accepts SELECT query expressions.

Table 283: POST /ariel/validators/aql Resource Details

MIME Type

application/json

Table 284: POST /ariel/validators/aql Request Parameter Details

Parameter

Type

Optionality

Data Type

MIME Type

Description

query_ expression

query

Required

String

text/plain

Required - The AQL query to validate.

fields

query

Optional

String

text/plain

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

Table 285: POST /ariel/validators/aql Response Codes

HTTP Response Code

Unique Code

Description

200

 

An AQL query expression was successfully validated.

500

1020

An error occurred during the attempt to validate AQL.

503

1010

The Ariel server might be temporarily unavailable or offline. Please try again later.

Response Description

Array of errors/warnings encountered during AQL validation or null if validation was successful.

Response Sample

{ "error_messages": [ { "code": 42, "contexts": [ "String" ], "message": "String", "severity": "String <one of: INFO, WARN, ERROR>" } ] }

Asset Model Endpoints

Use the references for REST API V10.0 Asset Model endpoints.

GET /asset_model/assets

List all assets found in the model.

Table 286: GET /asset_model/assets Resource Details

MIME Type

application/json

Table 287: GET /asset_model/assets Request Parameter Details

Parameter

Type

Optionality

Data Type

MIME Type

Description

Range

header

Optional

String

text/plain

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

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 288: GET /asset_model/assets Response Codes

HTTP Response Code

Unique Code

Description

200

 

The request to retrieve assets completed successfully.

500

1020

The server encountered an error while trying to retrieve the assets.

Response Description

List of assets retrieved using the associated asset saved search.

Response Sample

[{"interfaces": [{"mac_address": "String", "last_seen_profiler": 42, "created": 42, "first_seen_scanner": 42, "last_seen_scanner": 42, "ip_addresses": [{"last_seen_profiler": 42, "created": 42, "first_seen_scanner": 42, "last_seen_scanner": 42, "network_id": 42, "id": 42, "type": "String", "first_seen_profiler": 42, "value": "String"}], "id": 42, "first_seen_profiler": 42}], "id": 42, "domain_id": 42, "properties": [{"last_reported": 42, "name": "String", "type_id": 42, "id": 42, "last_reported_by": "String", "value": "String"}]}]

POST /asset_model/assets/{asset_id}

Update an asset with several pertinent pieces of information.

The asset_id tag is mandatory, and is the unique identifier for an asset. This field is available through the /asset_model/assets or /asset_model/saved_searches/{saved_search_id}/results query. To update properties, the property type ID which is available through the /asset_model/properties query must be provided along with the new value. See the sample provided demonstrating an example asset update.

Table 289: POST /asset_model/assets/{asset_id} Resource Details

MIME Type

text/plain

Table 290: POST /asset_model/assets/{asset_id} Request Parameter Details

Parameter

Type

Optionality

Data Type

MIME Type

Description

asset_id

path

Required

String

text/plain

Unique identifier of the asset to update.

Table 291: POST /asset_model/assets/{asset_id} Request Body Details

Parameter

Data Type

MIME Type

Description

Sample

asset

JSON

application/json

JSON representation of an asset.

{ "properties": [ { "type_id": 1001, "value": "given name value" }, { "type_id": 1002, "value": "unified name value" } ] }

Table 292: POST /asset_model/assets/{asset_id} Response Codes

HTTP Response Code

Unique Code

Description

202

 

The request to update the asset was successful. The update will take place when the asset profile application receives the request.

422

1005

One or more of the requested property updates were invalid.

500

1020

The server encountered an error registering the update with the asset profile application.

Response Description

Information about the asset that was updated.

Response Sample

String

GET /asset_model/properties

Get a list of available asset property types that can be used.

Get a list of available asset property types that can be used or applied against the /asset_model/assets endpoint.

Table 293: GET /asset_model/properties Resource Details

MIME Type

application/json

Table 294: GET /asset_model/properties Request Parameter Details

Parameter

Type

Optionality

Data Type

MIME Type

Description

Range

header

Optional

String

text/plain

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

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 295: GET /asset_model/properties Response Codes

HTTP Response Code

Unique Code

Description

200

 

The request to retrieve the list of asset property types completed successfully.

500

1020

An error occurred while trying to retrieve the list of asset property types.

Response Description

List of asset properties. Per asset property type: id and name that make up this asset property type.

Response Sample

[ { "custom": true, "data_type": "String", "display": true, "id": 42, "name": "String", "state": 42 } ]

GET /asset_model/saved_search_groups

Retrieves a list the asset saved search groups.

Table 296: GET /asset_model/saved_search_groups Resource Details

MIME Type

application/json

Table 297: GET /asset_model/saved_search_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 298: GET /asset_model/saved_search_groups Response Codes

HTTP Response Code

Unique Code

Description

200

 

The asset saved search groups were returned.

500

1020

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

Response Description

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

  • id - Long - The ID of the group.

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

  • type - String - The type of the group.

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

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

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

  • owner - String - The owner of the group.

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

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

Response Sample

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

GET /asset_model/saved_search_groups/{group_id}

Retrieves an asset saved search group.

Table 299: GET /asset_model/saved_search_groups/{group_id} Resource Details

MIME Type

application/json

Table 300: GET /asset_model/saved_search_groups/{group_id} Request Parameter Details

Parameter

Type

Optionality

Data Type

MIME Type

Description

group_id

path

Required

Number (Integer)

text/plain

null

fields

query

Optional

String

text/plain

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

Table 301: GET /asset_model/saved_search_groups/{group_id} Response Codes

HTTP Response Code

Unique Code

Description

200

 

The asset saved search group was retrieved.

404

1002

The asset saved search group does not exist.

500

1020

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

Response Description

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

  • id - Long - The ID of the group.

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

  • type - String - The type of the group.

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

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

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

  • owner - String - The owner of the group.

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

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

Response Sample

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

POST /asset_model/saved_search_groups/{group_id}

Updates the owner of an asset saved search group.

Table 302: POST /asset_model/saved_search_groups/{group_id} Resource Details

MIME Type

application/json

Table 303: POST /asset_model/saved_search_groups/{group_id} Request Parameter Details

Parameter

Type

Optionality

Data Type

MIME Type

Description

group_id

path

Required

Number (Integer)

text/plain

null

fields

header

Optional

String

text/plain

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

Table 304: POST /asset_model/saved_search_groups/{group_id} Request Body Details

Parameter

Data Type

MIME Type

Description

Sample

group

Object

application/

json

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

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

Table 305: POST /asset_model/saved_search_groups/{group_id} Response Codes

HTTP Response Code

Unique Code

Description

200

 

The asset saved search group has been updated.

404

1002

The asset saved search group does not exist.

409

1004

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

422

1005

A request parameter is not valid.

500

1020

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

Response Description

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

  • id - Long - The ID of the group.

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

  • type - String - The type of the group.

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

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

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

  • owner - String - The owner of the group.

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

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

Response Sample

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

DELETE /asset_model/saved_search_groups/{group_id}

Deletes an asset saved search group.

Table 306: DELETE /asset_model/saved_search_groups/{group_id} Resource Details

MIME Type

text/plain

Table 307: DELETE /asset_model/saved_search_groups/{group_id} Request Parameter Details

Parameter

Type

Optionality

Data Type

MIME Type

Description

group_id

path

Required

Number (Integer)

text/plain

null

Table 308: DELETE /asset_model/saved_search_groups/{group_id} Response Codes

HTTP Response Code

Unique Code

Description

204

 

The asset saved search group was deleted.

404

1002

The asset saved search group does not exist.

409

1004

null

500

1020

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

Response Description

Response Sample

GET /asset_model/saved_searches

Retrieves a list of saved searches that can be used or applied against the /asset_model/saved_searches/{saved_search_id}/results query.

Table 309: GET /asset_model/saved_searches Resource Details

MIME Type

application/json

Table 310: GET /asset_model/saved_searches Request Parameter Details

Parameter

Type

Optionality

Data Type

MIME Type

Description

Range

header

Optional

String

text/plain

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

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 311: GET /asset_model/saved_searches Response Codes

HTTP Response Code

Unique Code

Description

200

 

The request to retrieve the list of saved searches completed successfully.

500

1020

The server encountered an error during the attempt to retrieve the list of saved searches.

Response Description

A list of saved searches. Each saved search contains an ID, name, and list of filters.

Response Sample

[ { "columns": [ { "name": "String", "type": "String" } ], "description": "String", "filters": [ { "operator": "String", "parameter": "String", "value": "String" } ], "id": 42, "is_shared": true, "name": "String", "owner": "String" } ]

GET /asset_model/saved_searches/{saved_search_id}

Retrieves an asset saved search.

Table 312: GET /asset_model/saved_searches/{saved_search_id} Resource Details

MIME Type

application/json

Table 313: GET /asset_model/saved_searches/{saved_search_id} Request Parameter Details

Parameter

Type

Optionality

Data Type

MIME Type

Description

saved_search_id

path

Required

Number (Integer)

text/plain

null

fields

query

Optional

String

text/plain

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

Table 314: GET /asset_model/saved_searches/{saved_search_id} Response Codes

HTTP Response Code

Unique Code

Description

200

 

The asset saved search was retrieved,

404

1002

The asset saved search does not exist,

500

1020

An error occurred during the attempt to retrieve the asset saved search,

Response Description

The asset saved search after it is retrieved. An Asset Saved Search object contains the following fields:

  • id - Long - The ID of the asset saved search.

  • name - String - The name of the asset saved search.

  • owner - String - The owner of the asset saved search.

  • isShared - Boolean - True if the asset saved search is shared with other users.

  • description - String - The description of the asset saved search.

  • filters - List of Strings - The asset saved search filters.

  • columns - List of Strings - The asset saved search columns.

Response Sample

{ "columns": [ { "name": "String", "type": "String" } ], "description": "String", "filters": [ { "operator": "String", "parameter": "String", "value": "String" } ], "id": 42, "is_shared": true, "name": "String", "owner": "String" }

POST /asset_model/saved_searches/{saved_search_id}

Updates the asset saved search owner only.

Table 315: POST /asset_model/saved_searches/{saved_search_id} Resource Details

MIME Type

application/json

Table 316: POST /asset_model/saved_searches/{saved_search_id} Request Parameter Details

Parameter

Type

Optionality

Data Type

MIME Type

Description

saved_search_id

path

Required

Number (Integer)

text/plain

null

fields

header

Optional

String

text/plain

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

Table 317: POST /asset_model/saved_searches/{saved_search_id} Request Body Details

Parameter

Data Type

MIME Type

Description

Sample

saved_search

Object

application/json

null

{ "columns": [ { "name": "String", "type": "String" } ], "description": "String", "filters": [ { "operator": "String", "parameter": "String", "value": "String" } ], "id": 42, "is_shared": true, "name": "String", "owner": "String" }

Table 318: POST /asset_model/saved_searches/{saved_search_id} Response Codes

HTTP Response Code

Unique Code

Description

200

 

The asset saved search was updated.

403

1009

You do not have the required capabilities to update the asset saved search.

404

1002

The asset saved search does not exist.

409

1004

The provided user does not have the required capabilities to own the asset saved search.

422

1005

A request parameter is not valid.

500

1020

An error occurred during the attempt to update the asset saved search.

Response Description

The asset saved search after it is updated. An Asset Saved Search object contains the following fields:

  • id - Long - The ID of the asset saved search.

  • name - String - The name of the asset saved search.

  • owner - String - The owner of the asset saved search.

  • isShared - Boolean - True if the asset saved search is shared with other users.

  • description - String - The description of the asset saved search.

  • filters - List of Strings - The asset saved search filters.

  • columns - List of Strings - The asset saved search columns.

Response Sample

{ "columns": [ { "name": "String", "type": "String" } ], "description": "String", "filters": [ { "operator": "String", "parameter": "String", "value": "String" } ], "id": 42, "is_shared": true, "name": "String", "owner": "String" }

DELETE /asset_model/saved_searches/{saved_search_id}

Deletes an asset saved search.

Table 319: DELETE /asset_model/saved_searches/{saved_search_id} Resource Details

MIME Type

text/plain

Table 320: DELETE /asset_model/saved_searches/{saved_search_id} Request Parameter Details

Parameter

Type

Optionality

Data Type

MIME Type

Description

saved_search_id

path

Required

Number (Integer)

text/plain

null

Table 321: DELETE /asset_model/saved_searches/{saved_search_id} Response Codes

HTTP Response Code

Unique Code

Description

204

 

The asset saved search was deleted.

403

1009

You do not have the required capabilities to delete the asset saved search.

404

1002

The asset saved search does not exist.

500

1020

An error occurred during the attempt to delete the asset saved search.

Response Description

Response Sample

GET /asset_model/saved_searches/{saved_search_id}/results

Retrieves a list of assets based on the results of an asset saved search.

Table 322: GET /asset_model/saved_searches/{saved_search_id}/results Resource Details

MIME Type

application/json

Table 323: GET /asset_model/saved_searches/{saved_search_id}/results Request Parameter Details

Parameter

Type

Optionality

Data Type

MIME Type

Description

saved_search_id

path

Required

String

text/plain

Unique identifier of the saved search used to retrieve assets.

Range

header

Optional

String

text/plain

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

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 324: GET /asset_model/saved_searches/{saved_search_id}/results Response Codes

HTTP Response Code

Unique Code

Description

200

 

The request to retrieve assets completed successfully.

404

1002

null

422

1005

The unique identifier of the saved search provided was invalid.

500

1003

The server encountered an error executing the saved search.

Response Description

List of assets retrieved using the associated asset saved search.

Response Sample

[ { "domain_id": 42, "id": 42, "interfaces": [ { "created": 42, "first_seen_profiler": 42, "first_seen_scanner": 42, "id": 42, "ip_addresses": [ { "created": 42, "first_seen_profiler": 42, "first_seen_scanner": 42, "id": 42, "last_seen_profiler": 42, "last_seen_scanner": 42, "network_id": 42, "type": "String", "value": "String" } ], "last_seen_profiler": 42, "last_seen_scanner": 42, "mac_address": "String" } ], "properties": [ { "id": 42, "last_reported": 42, "last_reported_by": "String", "name": "String", "type_id": 42, "value": "String" } ] } ]

Authentication Endpoints

Use the references for REST API V10.0 authentication endpoints.

POST /auth/logout

Invoke this method as an authorized user and your session will be invalidated.

Table 325: POST /auth/logout Resource Details

MIME Type

text/plain

There are no parameters for this endpoint.

Table 326: POST /auth/logout Response Codes

HTTP Response Code

Unique Code

Description

200

 

The session was invalidated.

Response Description

Returns true. Throws exception upon failure.

Response Sample

true

Configuration Endpoints

Use the references for REST API V10.0 configuration endpoints.

GET /config/access/security_profiles

Get the list of deployed security profiles available in the system. The ADMIN or SAASADMIN capabilities are required to call this endpoint.

Table 327: GET /config/access/security_profiles Resource Details

MIME Type

application/json

Table 328: GET /config/access/security_profiles Request Parameter Details

Parameter

Type

Optionality

Data Type

MIME Type

Description

tenant_id

query

Optional

Number (Integer)

text/plain

If this parameter is provided, the endpoint will return all security profiles associated with domains that are linked to this tenant

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 329: GET /config/access/security_profiles Response Codes

HTTP Response Code

Unique Code

Description

200

 

A list of the deployed Security profiles.

422

38330001

Tenant ID does not exist.

Response Description

Returns an array of security profile structures.

  • id - Long - The ID of the security profile. The ID of the staged and the ID of the same deployed user are the same.

  • name - String - The name of the security profile.

  • domain_ids - Array of Integers - The list of domain ids which are assigned to the security profiles. If there is no domain assigned to the security profile, the empty list will be returned.

Response Sample

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

GET /config/access/security_profiles/{id}

Get a deployed security profile by ID. The ADMIN or SAASADMIN capabilities are required to call this endpoint.

Table 330: GET /config/access/security_profiles/{id} Resource Details

MIME Type

application/json

Table 331: GET /config/access/security_profiles/{id} Request Parameter Details

Parameter

Type

Optionality

Data Type

MIME Type

Description

id

path

Required

Number (Integer)

text/plain

The ID of the security profile to get

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 332: GET /config/access/security_profiles/{id} Response Codes

HTTP Response Code

Unique Code

Description

200

 

The deployed security profile was retrieved.

404

38331001

The security profile id does not exist.

Response Description

A single deployed Security profile.

  • id - Long - The ID of the security profile. The ID of the staged and the ID of the same deployed security profile are the same.

  • name - String - The name of the security profile.

  • domain_ids - Array of Integers - The list of domain ids which are assigned to the security profiles. If there is no domain assigned to the security profile, the empty list will be returned.

Response Sample

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

GET /config/access/tenant_management/tenants

Retrieve the list of all tenants. The list is ordered by tenant id.

Table 333: GET /config/access/tenant_management/tenants Resource Details

MIME Type

application/json

Table 334: GET /config/access/tenant_management/tenants Request Parameter Details

Parameter

Type

Optionality

Data Type

MIME Type

Description

Range

header

Optional

String

text/plain

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

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 335: GET /config/access/tenant_management/tenants Response Codes

HTTP Response Code

Unique Code

Description

200

 

The tenant list was successfully retrieved.

500

1020

An error occurred while the tenant list was being retrieved.

Response Description

a list of all the tenants

Response Sample

[ { "deleted": true, "description": "String", "event_rate_limit": 42, "flow_rate_limit": 42, "id": 42, "name": "String" } ]

POST /config/access/tenant_management/tenants

Create a new tenant.

Table 336: POST /config/access/tenant_management/tenants Resource Details

MIME Type

application/json

Table 337: POST /config/access/tenant_management/tenants Request Parameter Details

Parameter

Type

Optionality

Data Type

MIME Type

Description

fields

header

Optional

String

text/plain

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

Table 338: POST /config/access/tenant_management/tenants Request Body Details

Parameter

Data Type

MIME Type

Description

Sample

tenant

Object

application/json

Required - Tenant - includes name, event_rate_limit (unit eps), flow_rate_limit (unit fpm) and description

{ "deleted": true, "description": "String", "event_rate_limit": 42, "flow_rate_limit": 42, "name": "String" }

Table 339: POST /config/access/tenant_management/tenants Response Codes

HTTP Response Code

Unique Code

Description

201

 

A new tenant was created successfully and returned the new tenant object.

409

1004

A tenant with the given name already exists.

422

1005

A request parameter is invalid.

500

1020

Failed to create the tenant.

Response Description

a created tenant object

Response Sample

{ "deleted": true, "description": "String", "event_rate_limit": 42, "flow_rate_limit": 42, "id": 42, "name": "String" }

GET /config/access/tenant_management/tenants/{tenant_id}

Retrieve a tenant by tenant id.

Table 340: GET /config/access/tenant_management/tenants/{tenant_id} Resource Details

MIME Type

application/json

Table 341: GET /config/access/tenant_management/tenants/{tenant_id} Request Parameter Details

Parameter

Type

Optionality

Data Type

MIME Type

Description

tenant_id

path

Required

Number (Integer)

text/plain

null

fields

query

Optional

String

text/plain

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

Table 342: GET /config/access/tenant_management/tenants/{tenant_id} Response Codes

HTTP Response Code

Unique Code

Description

200

 

The tenant was successfully retrieved.

404

1002

No tenant was found for the provided tenant id.

500

1020

An error occurred while the tenant was being retrieved.

Response Description

The associated tenants object.

Response Sample

{ "deleted": true, "description": "String", "event_rate_limit": 42, "flow_rate_limit": 42, "id": 42, "name": "String" }

POST /config/access/tenant_management/tenants/{tenant_id}

Update a tenant.

Table 343: POST /config/access/tenant_management/tenants/{tenant_id} Resource Details

MIME Type

application/json

Table 344: POST /config/access/tenant_management/tenants/{tenant_id} Request Parameter Details

Parameter

Type

Optionality

Data Type

MIME Type

Description

tenant_id

path

Required

Number (Integer)

text/plain

Required - Integer - the tenant id to modify

fields

header

Optional

String

text/plain

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

Table 345: POST /config/access/tenant_management/tenants/{tenant_id} Request Body Details

Parameter

Data Type

MIME Type

Description

Sample

tenant

Object

application/json

Required - Tenant - includes name, event_rate_limit (unit eps), flow_rate_limit (unit fpm) and description

{ "deleted": true, "description": "String", "event_rate_limit": 42, "flow_rate_limit": 42, "name": "String" }

Table 346: POST /config/access/tenant_management/tenants/{tenant_id} Response Codes

HTTP Response Code

Unique Code

Description

200

 

A tenant profile that was updated successfully and returned the updated tenant object.

404

1002

The tenant profile does not exist.

409

1004

A tenant with the given name already exists.

422

1005

A request parameter is invalid.

500

1020

Failed to retrieve/update the given tenant profile.

Response Description

The updated tenant object.

Response Sample

{ "deleted": true, "description": "String", "event_rate_limit": 42, "flow_rate_limit": 42, "id": 42, "name": "String" }

DELETE /config/access/tenant_management/tenants/{tenant_id}

Delete a tenant.

Deletes a tenant by tenant ID.

Table 347: DELETE /config/access/tenant_management/tenants/{tenant_id} Resource Details

MIME Type

application/json

Table 348: DELETE /config/access/tenant_management/tenants/{tenant_id} Request Parameter Details

Parameter

Type

Optionality

Data Type

MIME Type

Description

tenant_id

path

Required

Number (Integer)

text/plain

Required - String - id associated to a tenant

Table 349: DELETE /config/access/tenant_management/tenants/{tenant_id} Response Codes

HTTP Response Code

Unique Code

Description

200

 

The tenant was deleted successfully (soft delete).

404

1002

The tenant does not exists.

500

1020

An error occurred while deleting tenant.

Response Description

the deleted tenant object with its parameter deleted set to true

Response Sample

{ "deleted": true, "description": "String", "event_rate_limit": 42, "flow_rate_limit": 42, "id": 42, "name": "String" }

GET /config/access/user_dependent_tasks/{task_id}

Retrieves the dependent user task status.

Table 350: GET /config/access/user_dependent_tasks/{task_id} Resource Details

MIME Type

application/json

Table 351: GET /config/access/user_dependent_tasks/{task_id} Request Parameter Details

Parameter

Type

Optionality

Data Type

MIME Type

Description

task_id

path

Required

Number (Integer)

text/plain

null

fields

query

Optional

String

text/plain

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

Table 352: GET /config/access/user_dependent_tasks/{task_id} Response Codes

HTTP Response Code

Unique Code

Description

200

 

The Delete Task Status was retrieved.

404

1002

The Delete Task Status does not exist.

500

1020

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

Response Description

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

  • id - Long - The ID of the task.

  • message - String - The localized task message.

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

  • name - String - The name of the task.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Response Sample

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

POST /config/access/user_dependent_tasks/{task_id}

Cancels a dependent user task.

Table 353: POST /config/access/user_dependent_tasks/{task_id} Resource Details

MIME Type

application/json

Table 354: POST /config/access/user_dependent_tasks/{task_id} Request Parameter Details

Parameter

Type

Optionality

Data Type

MIME Type

Description

task_id

path

Required

Number (Integer)

text/plain

null

fields

header

Optional

String

text/plain

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

Table 355: POST /config/access/user_dependent_tasks/{task_id} Request Body Details

Parameter

Data Type

MIME Type

Description

Sample

task

Object

application/json

null

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

Table 356: POST /config/access/user_dependent_tasks/{task_id} Response Codes

HTTP Response Code

Unique Code

Description

200

 

The Dependent Task Status was retrieved.

404

1002

The Dependent Task Status does not exist.

409

1004

The task is in a completed state.

422

1005

A request parameter is not valid.

500

1020

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

Response Description

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

  • id - Long - The ID of the task.

  • message - String - The localized task message.

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

  • name - String - The name of the task.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Response Sample

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

GET /config/access/user_dependent_tasks/{task_id}/results

Retrieves the user dependent task results.

Table 357: GET /config/access/user_dependent_tasks/{task_id}/results Resource Details

MIME Type

application/json

Table 358: GET /config/access/user_dependent_tasks/{task_id}/results Request Parameter Details

Parameter

Type

Optionality

Data Type

MIME Type

Description

task_id

path

Required

Number (Integer)

text/plain

null

fields

query

Optional

String

text/plain

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

Table 359: GET /config/access/user_dependent_tasks/{task_id}/results Response Codes

HTTP Response Code

Unique Code

Description

200

 

The User Dependents were retrieved.

404

1002

The Dependent Task Status does not exist.

500

1020

An error occurred during the attempt to retrieve the Users.

Response Description

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

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

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

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

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

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

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

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

Response Sample

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

GET /config/access/user_roles

Get the list of deployed user roles available in the system. The ADMIN or SAASADMIN capabilities are required to call this endpoint.

Table 360: GET /config/access/user_roles Resource Details

MIME Type

application/json

Table 361: GET /config/access/user_roles Request Parameter Details

Parameter

Type

Optionality

Data Type

MIME Type

Description

contains

query

Optional

String

text/plain

null

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 362: GET /config/access/user_roles Response Codes

HTTP Response Code

Unique Code

Description

200

 

A list of the deployed user roles.

500

1020

An unexpected error has occurred.

Response Description

Returns an array of user roles.

  • id - Long - The ID of the User Role. The ID of the staged and the ID of the same deployed user are the same.

  • name - String - The name of the User Role.

Response Sample

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

GET /config/access/user_roles/{id}

Get a deployed user role by ID. The ADMIN or SAASADMIN capabilities are required to call this endpoint.

Table 363: GET /config/access/user_roles/{id} Resource Details

MIME Type

application/json

Table 364: GET /config/access/user_roles/{id} Request Parameter Details

Parameter

Type

Optionality

Data Type

MIME Type

Description

id

path

Required

Number (Integer)

text/plain

The ID of the staged user role to get.

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 365: GET /config/access/user_roles/{id} Response Codes

HTTP Response Code

Unique Code

Description

200

 

The staged user role was retrieved.

404

38341001

The user role id does not exist.

Response Description

A single deployed User Role.

  • id - Long - The ID of the user role.

  • name - String - The name of the user role.

Response Sample

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

GET /config/access/users

Retrieve Deployed Users.

Retrieves a list of all deployed users. The deployed configuration is the active configuration. This endpoint is available to be called by every user or authorized service. If called by a user or authorized service with the ADMIN capability, all deployed users will be returned. If called by a user or authorized service with the SAASADMIN capability, all deployed users without the ADMIN capability will be returned. If called by anyone else, only the deployed user for the current user will be returned.

Table 366: GET /config/access/users Resource Details

MIME Type

application/json

Table 367: GET /config/access/users Request Parameter Details

Parameter

Type

Optionality

Data Type

MIME Type

Description

current_user

query

Optional

Boolean

text/plain

Only return the caller's user. If called with an authorized service no user will be returned.

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.

sort

query

Optional

String

text/plain

Optional - This parameter is used to sort the elements in a list.

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 368: GET /config/access/users Response Codes

HTTP Response Code

Unique Code

Description

200

 

The deployed users were retrieved.

422

38314001

Field in sort parameter does not exist.

422

38314002

Sorting not supported on field in sort parameter.

Response Description

Returns an array of user structures.

  • id - Long - The ID of the user. The ID of the staged user and the ID of the same deployed user are the same. This field is read only.

  • username - String - The username of the user. This field is read only.

  • email - String - The email of the user.

  • description - String - The description of the user. This field is only modifiable in the staged configuration.

  • user_role_id - Long - The user_role_id of the user. This field is only modifiable in the staged configuration. Access staged user roles using /api/staged_config/user_roles API, and deployed user roles under /api/confg/user_roles API.

  • security_profile_id - Long - The security_profile_id of the user. This field is only modifiable in the staged configuration. Access staged security profiles using /api/staged_config/security_profiles API, and deployed user roles under /api/config/security_profiles API.

  • locale_id - String - The locale_id of the user. Access locales using /system/information/locales API.

  • enable_popup_notifications - Boolean - Indicates if popup system notifications are enabled for this user.

  • old_password - String - This field will always be null when returned in a response. Required to be set to the current password when a user is changing their own system password.

  • password - String - This field will always be null when returned in a response. Set to the new password when a user is changing their own system password.

  • password_creation_time - Long - The time in milliseconds since epoch when the current password was created. Combined with the password_expiry_interval from the /system/authorization/password_policies API to calculate when the password expires.

  • tenant_id - Long - The tenant_id of the current user. This field is only modifiable in the staged configuration. Access tenants using /config/access/tenant_management/tenants API.

  • allow_system_authentication_fallback - Boolean - Allow system authentication fallback for this user when external authentication is configured. Has no effect if system authentication is configured.

Response Sample

[ { "allow_system_authentication_fallback": true, "description": "String", "email": "String", "enable_popup_notifications": true, "id": 42, "locale_id": "String", "old_password": "String", "password": "String", "password_creation_time": 42, "security_profile_id": 42, "tenant_id": 42, "user_role_id": 42, "username": "String" } ]

GET /config/access/users/{id}/dependents

Retrieves the objects that depend on the user.

Table 369: GET /config/access/users/{id}/dependents Resource Details

MIME Type

application/json

Table 370: GET /config/access/users/{id}/dependents Request Parameter Details

Parameter

Type

Optionality

Data Type

MIME Type

Description

id

path

Required

Number (Integer)

text/plain

null

fields

query

Optional

String

text/plain

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

Table 371: GET /config/access/users/{id}/dependents Response Codes

HTTP Response Code

Unique Code

Description

202

 

The User dependents retrieval was accepted and is in progress.

404

1002

The User does not exist.

500

1020

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

Response Description

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

  • id - Long - The ID of the task.

  • message - String - The localized task message.

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

  • name - String - The name of the task.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Response Sample

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

GET /config/access/users/{id}

Retrieves a deployed user. The deployed configuration is the active configuration. This endpoint is available to be called by every user or authorized service. If called by a user or authorized service with the ADMIN capability, any deployed user could be returned. If called by a user or authorized service with the SAASADMIN capability, any deployed user without the ADMIN capability could be returned. If called by anyone else, only the deployed user for the current user could be returned.

Table 372: GET /config/access/users/{id} Resource Details

MIME Type

application/json

Table 373: GET /config/access/users/{id} Request Parameter Details

Parameter