Help us improve your experience.

Let us know what you think.

Do you have time for a two-minute survey?

 

REST API V4.0 References

 

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

Ariel Endpoints

Use the references for REST API V4 Ariel endpoints.

GET /ariel/databases DEPRECATED

Retrieve Ariel database names.

Table 1: GET /ariel/databases Resource Details

MIME Type

application/json

Table 2: GET /ariel/databases 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.

Table 3: GET /ariel/databases Response Codes

HTTP Response Code

Unique Code

Description

200

 

The database list was retrieved.

500

1020

An error occurred while attempting to retrieve the list of Ariel databases.

Response Description

The names of the available Ariel databases.

Response Sample

[ "String" ]

GET /ariel/databases/{database_name} DEPRECATED

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

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

MIME Type

application/json

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

Parameter

Type

Optionality

Data Type

MIME Type

Description

database_name

path

Required

String

text/plain

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

fields

query

Optional

String

text/plain

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

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 /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.

422

1005

A request parameter is not valid.

500

1020

An error occurred while attempting to retrieve the database columns.

Response Description

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

Response Sample

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

GET /ariel/searches DEPRECATED

Retrieve the list of Ariel searches. This includes search_ids for completed and active searches.

Table 7: GET /ariel/searches Resource Details

MIME Type

application/json

Table 8: GET /ariel/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.

Table 9: GET /ariel/searches Response Codes

HTTP Response Code

Unique Code

Description

200

 

The search list was retrieved.

500

1020

An error occurred while attempting to retrieve the list of searches.

Response Description

A list of search IDs.

Response Sample

[ "String" ]

POST /ariel/searches DEPRECATED

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 and RUN 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.

Table 10: POST /ariel/searches Resource Details

MIME Type

application/json

Table 11: POST /ariel/searches Request Parameter Details

Parameter

Type

Optionality

Data Type

MIME Type

Description

query_expression

query

Required

String

text/plain

Required - The AQL query to execute.

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 12: POST /ariel/searches Response Codes

HTTP Response Code

Unique Code

Description

201

 

A new Ariel search was successfully created.

409

1004

The search could not be created, the requested search ID 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 while attempting to create a new search.

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

{ "compressed_data_file_count": 42, "compressed_data_total_size": 42, "cursor_id": "String", "data_file_count": 42, "data_total_size": 42, "desired_retention_time_msec": 42, "error_messages": [ { "code": "String", "contexts": [ "String" ], "message": "String", "severity": "String <one of: INFO, WARN, ERROR>" } ], "index_file_count": 42, "index_total_size": 42, "processed_record_count": 42, "progress": 42, "query_execution_time": 42, "record_count": 42, "save_results": true, "search_id": "String", "status": "String <one of: WAIT, EXECUTE, SORTING, COMPLETED, CANCELED, ERROR>" }

GET /ariel/searches/{search_id} DEPRECATED

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 13: GET /ariel/searches/{search_id} Resource Details

MIME Type

application/json

Table 14: 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.

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 15: GET /ariel/searches/{search_id} Response Codes

HTTP Response Code

Unique Code

Description

200

 

The search information was retrieved.

404

1002

The search does not exist.

422

1005

A request parameter is not valid.

500

1020

An error occurred while attempting to retrieve the search information.

Response Description

Information about the specified search, including the search status.

Response Sample

{ "compressed_data_file_count": 42, "compressed_data_total_size": 42, "cursor_id": "String", "data_file_count": 42, "data_total_size": 42, "desired_retention_time_msec": 42, "error_messages": [ { "code": "String", "contexts": [ "String" ], "message": "String", "severity": "String <one of: INFO, WARN, ERROR>" } ], "index_file_count": 42, "index_total_size": 42, "processed_record_count": 42, "progress": 42, "query_execution_time": 42, "record_count": 42, "save_results": true, "search_id": "String", "status": "String <one of: WAIT, EXECUTE, SORTING, COMPLETED, CANCELED, ERROR>" }

POST /ariel/searches/{search_id} DEPRECATED

Update 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 16: POST /ariel/searches/{search_id} Resource Details

MIME Type

application/json

Table 17: 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.

save_results

query

Optional

String

text/plain

Optional. The only accepted value is true. If this value is provided, the search results will not be deleted by the search expiration removal process.

status

query

Optional

String

text/plain

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

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 18: 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.

409

1008

The current status of the search prevented the search results from being saved.

422

1005

A request parameter is not valid.

500

1020

An error occurred while attempting to update the search.

Response Description

Information about the specified search that was updated.

Response Sample

{ "compressed_data_file_count": 42, "compressed_data_total_size": 42, "cursor_id": "String", "data_file_count": 42, "data_total_size": 42, "desired_retention_time_msec": 42, "error_messages": [ { "code": "String", "contexts": [ "String" ], "message": "String", "severity": "String <one of: INFO, WARN, ERROR>" } ], "index_file_count": 42, "index_total_size": 42, "processed_record_count": 42, "progress": 42, "query_execution_time": 42, "record_count": 42, "save_results": true, "search_id": "String", "status": "String <one of: WAIT, EXECUTE, SORTING, COMPLETED, CANCELED, ERROR>" }

DELETE /ariel/searches/{search_id} DEPRECATED

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

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

MIME Type

application/json

Table 20: 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.

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 21: 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 while attempting to delete the search.

Response Description

Information about the deleted search.

Response Sample

{ "compressed_data_file_count": 42, "compressed_data_total_size": 42, "cursor_id": "String", "data_file_count": 42, "data_total_size": 42, "desired_retention_time_msec": 42, "error_messages": [ { "code": "String", "contexts": [ "String" ], "message": "String", "severity": "String <one of: INFO, WARN, ERROR>" } ], "index_file_count": 42, "index_total_size": 42, "processed_record_count": 42, "progress": 42, "query_execution_time": 42, "record_count": 42, "save_results": true, "search_id": "String", "status": "String <one of: WAIT, EXECUTE, SORTING, COMPLETED, CANCELED, ERROR>" }

GET /ariel/searches/{search_id}/results DEPRECATED

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 format 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 22: GET /ariel/searches/{search_id}/results Resource Details

MIME Type

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

Table 23: 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 24: 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 while attempting to retrieve the search results.

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": "1.1.1.1", "destinationIP": "127.0.0.1" }, { "sourceIP": "1.1.1.1", "destinationIP": "127.0.0.1" } ] }

Asset Model Endpoints

Use the references for REST API V4 Asset Model endpoints.

GET /asset_model/assets DEPRECATED

List all assets found in the model.

Table 25: GET /asset_model/assets Resource Details

MIME Type

application/json

Table 26: GET /asset_model/assets Request Parameter Details

Parameter

Type

Optionality

Data Type

MIME Type

Description

Range

header

Optional

String

text/plain

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

fields

query

Optional

String

text/plain

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

filter

query

Optional

String

text/plain

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

Table 27: GET /asset_model/assets Response Codes

HTTP Response Code

Unique Code

Description

200

 

The request to retrieve assets completed successfully.

500

1020

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

Response Description

List of assets retrieved using the associated asset saved search.

Response Sample

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

POST /asset_model/assets/{asset_id} DEPRECATED

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 should be provided along with the new value. See the sample provided demonstrating an example asset update.

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

MIME Type

text/plain

Table 29: 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 30: 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 31: 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 DEPRECATED

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

Table 32: GET /asset_model/properties Resource Details

MIME Type

application/json

Table 33: GET /asset_model/properties Request Parameter Details

Parameter

Type

Optionality

Data Type

MIME Type

Description

Range

header

Optional

String

text/plain

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

fields

query

Optional

String

text/plain

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

filter

query

Optional

String

text/plain

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

Table 34: 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_searches DEPRECATED

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

Table 35: GET /asset_model/saved_searches Resource Details

MIME Type

application/json

Table 36: GET /asset_model/saved_searches Request Parameter Details

Parameter

Type

Optionality

Data Type

MIME Type

Description

Range

header

Optional

String

text/plain

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

fields

query

Optional

String

text/plain

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

filter

query

Optional

String

text/plain

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

Table 37: GET /asset_model/saved_searches Response Codes

HTTP Response Code

Unique Code

Description

200

 

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

500

1020

The server encountered an error while trying to retrieve the list of saved searches.

Response Description

List of saved searches. Per saved search: id, name and list of filters that make up this saved search

Response Sample

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

GET /asset_model/saved_searches/{saved_search_id}/results DEPRECATED

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

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

MIME Type

application/json

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

Parameter

Type

Optionality

Data Type

MIME Type

Description

saved_search_id

path

Required

String

text/plain

Unique identifier of the saved search used to retrieve assets.

Range

header

Optional

String

text/plain

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

fields

query

Optional

String

text/plain

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

filter

query

Optional

String

text/plain

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

Table 40: GET /asset_model/saved_searches/{saved_search_id}/results Response Codes

HTTP Response Code

Unique Code

Description

200

 

The request to retrieve assets completed successfully.

422

1005

The unique identifier of the saved search provided was invalid.

500

1003

The server encountered an error executing the saved search.

Response Description

List of assets retrieved using the associated asset saved search.

Response Sample

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

Authentication Endpoints

Use the references for REST API V4 authentication endpoints.

POST /auth/logout DEPRECATED

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

Table 41: POST /auth/logout Resource Details

MIME Type

text/plain

There are no parameters for this endpoint.

Table 42: 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

Help Endpoints

Use the references for REST API V4 Help endpoints.

GET /help/capabilities DEPRECATED

The response will contain all available RESTful resources. We allow every authenticated user to access this method, but restrict the output based on their user capabilities.

Table 43: GET /help/capabilities Resource Details

MIME Type

application/json

Table 44: GET /help/capabilities Request Parameter Details

Parameter

Type

Optionality

Data Type

MIME Type

Description

categories

query

Optional

Array<String>

application/json

Optional - Restrict your search to this list of capabilities

paths

query

Optional

Array<String>

application/json

Optional - Restrict your search to these paths only

httpMethods

query

Optional

Array<String>

application/json

Optional - Restrict your search to these HTTP methods

version

query

Optional

String

text/plain

Optional - Restrict your search to this version (or below)

showExperimental

query

Optional

Boolean

text/plain

Optional - If true, we include experimental endpoints (default is true)

Range

header

Optional

String

text/plain

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

fields

query

Optional

String

text/plain

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

Table 45: GET /help/capabilities Response Codes

HTTP Response Code

Unique Code

Description

200

 

The API capabilities list was retrieved.

422

1001

Invalid input

422

1002

Our internal mapping has an unexpected structure or contains an invalid element value

500

1003

A generic error has occurred while retrieving our capabilities

Response Description

Endpoints you are able to access, mapped against versions they belong to. If full content is not requested, values will be null.

Response Sample

{ "categories": [ { "apis": [ { "httpMethod": "String <one of: OPTIONS, GET, HEAD, POST, PUT, DELETE, TRACE, CONNECT, PATCH>", "operations": [ { "additionalFiltering": true, "deprecated": true, "description": "String", "errorResponses": [ { "code": 42, "description": "String", "uniqueCode": 42 } ], "httpMethod": "String", "lastSupportedVersion": "String", "parameters": [ { "allowMultiple": true, "defaultValue": "String", "description": "String", "name": "String", "pathIndex": 42, "required": true, "source": "String", "supportedContentTypes": [ { "dataType": "String", "mimeType": "String", "sample": "String" } ] } ], "removalTarget": "String", "removed": true, "responseClass": "String", "responseDescription": { "description": "String", "properties": [ { "description": "String", "name": "String" } ] }, "successResponses": [ { "code": 42, "description": "String" } ], "summary": "String", "supportedContentTypes": [ { "dataType": "String", "mimeType": "String", "sample": "String" } ], "version": "String", "visibility": "String" } ], "path": "String" } ], "path": "String" } ], "path": "String" }

JSA Vulnerability Manager Endpoints

Use the references for REST API V4 JSA Vulnerability Manager endpoints.

GET /qvm/assets DEPRECATED

List the assets with discovered vulnerabilities present in the asset model. The response contains all available RESTful resources

Table 46: GET /qvm/assets Resource Details

MIME Type

application/json

Table 47: GET /qvm/assets Request Parameter Details

Parameter

Type

Optionality

Data Type

MIME Type

Description

savedSearchId

query

Optional

String

text/plain

Id of saved search

savedSearchName

query

Optional

String

text/plain

Saved search name

filters

query

Optional

Array<Object>

application/json

List of JSON objects for application of bespoke query search dataset filter. Format [{"parameter":"<value>", "operator":"<value>", "value":"<value>"}] e.g. [{"parameter":"IPv4 Address", "operator":"Equals", "value":"10.100.85.111"}]

Table 48: GET /qvm/assets Response Codes

HTTP Response Code

Unique Code

Description

200

 

The request to retrieve vulnerabilities by asset completed successfully

420

9101

Invalid search parameters, search cannot be performed

Response Description

List of assets data.

GET /qvm/filters DEPRECATED

Get a list of the allowable filters that can be used or applied against /qvm endpoints.

  • /qvm/assets

  • /qvm/vulns

  • /qvm/vulninstances

  • /qvm/openservices

  • /qvm/networks

  • queries

Table 49: GET /qvm/filters Resource Details

MIME Type

application/json

There are no parameters for this endpoint.

Table 50: GET /qvm/filters Response Codes

HTTP Response Code

Unique Code

Description

200

 

The search executed successfully

420

9102

An error occurred while executing the search

Response Description

Llist of Filters.

GET /qvm/network DEPRECATED

List the networks present in the asset model with vulnerabilities present. The response contains all available RESTful resources.

Table 51: GET /qvm/network Resource Details

MIME Type

application/json

Table 52: GET /qvm/network Request Parameter Details

Parameter

Type

Optionality

Data Type

MIME Type

Description

savedSearchId

query

Optional

String

text/plain

Id of saved search

savedSearchName

query

Optional

String

text/plain

Saved search name

filters

query

Optional

Array<Object>

application/json

List of JSON objects for application of bespoke query search dataset filter. Format [{"parameter":"<value>", "operator":"<value>", "value":"<value>"}] e.g. [{"parameter":"IPv4 Address", "operator":"Equals", "value":"10.100.85.111"}]

Table 53: GET /qvm/network Response Codes

HTTP Response Code

Unique Code

Description

200

 

The request to retrieve vulnerabilities by network completed successfully

420

9101

Invalid search parameters, search cannot be performed

Response Description

List of network related data.

GET /qvm/openservices DEPRECATED

List the open services present in the asset model with vulnerabilities present. The response contains all available RESTful resources.

Table 54: GET /qvm/openservices Resource Details

MIME Type

application/json

Table 55: GET /qvm/openservices Request Parameter Details

Parameter

Type

Optionality

Data Type

MIME Type

Description

savedSearchId

query

Optional

String

text/plain

Id of saved search

savedSearchName

query

Optional

String

text/plain

Saved search name

filters

query

Optional

Array<Object>

application/json

List of JSON objects for application of bespoke query search dataset filter. Format [{"parameter":"<value>", "operator":"<value>", "value":"<value>"}] e.g. [{"parameter":"IPv4 Address", "operator":"Equals", "value":"10.100.85.111"}]

Table 56: GET /qvm/openservices Response Codes

HTTP Response Code

Unique Code

Description

200

 

The request to retrieve vulnerabilities by open service completed successfully

420

9101

Invalid search parameters, search cannot be performed

Response Description

List of open services related data.

GET /qvm/savedsearches DEPRECATED

Get a list of saved searches that can be applied against /qvm endpoints.

A list of saved searches that can be applied against the following endpoints:

  • /qvm/assets

  • /qvm/vulns

  • /qvm/vulninstances

  • /qvm/openservices

  • /qvm/networks

  • queries

Table 57: GET /qvm/savedsearches Resource Details

MIME Type

application/json

There are no parameters for this endpoint.

Table 58: GET /qvm/savedsearches Response Codes

HTTP Response Code

Unique Code

Description

200

 

The request to retrieve the list of saved searches completed successfully

420

9103

An error occurred while trying to retrieve the list of saved searches

Response Description

Llist of saved searches. Per saved search: id, name and list fo filters that make up this saved search.

POST /qvm/tickets/assign DEPRECATED

Update the remediation ticket for the assigned vulnerability

Table 59: POST /qvm/tickets/assign Resource Details

MIME Type

application/json

Table 60: POST /qvm/tickets/assign Request Body Details

Parameter

Data Type

MIME Type

Description

Sample

ticket

JSON

application/json

'ticketId': required.

'priority' one of required : Critical, Major, Minor, Warning, Informational.

'status' one of required : Opened, Fixed, Re-Opened, Closed .

'dueDate' Optional : yyyy-MM-dd HH:mm:ss.

'assignedUser' required : valid JSA user account name or a valid email.

'comment' Optional : text.

'commentUser' Optional : valid JSA user account name, if not included will default current API user.

[ { "ticketId":"1000", "status":"Opened", "priority":"Critical", "dueDate":"2015-01-04 12:00:00", "assignedUser":"admin", "comment":"testComment", "commentUser":"admin" } ]

Table 61: POST /qvm/tickets/assign Response Codes

HTTP Response Code

Unique Code

Description

200

 

The request to assign a ticket completed successfully

420

9104

An error occurred while trying to assign a ticket due to invalid arguments

Response Description

Success message if update succeed.

GET /qvm/vulninstances DEPRECATED

List the Vulnerability Instances present in the asset model. The response will contain all available RESTful resources.

Table 62: GET /qvm/vulninstances Resource Details

MIME Type

application/json

Table 63: GET /qvm/vulninstances Request Parameter Details

Parameter

Type

Optionality

Data Type

MIME Type

Description

savedSearchId

query

Optional

String

text/plain

Id of saved search

savedSearchName

query

Optional

String

text/plain

Saved search name

filters

query

Optional

Array<Object>

application/json

List of JSON objects for application of bespoke query search dataset filter. Format [{"parameter":"<value>", "operator":"<value>", "value":"<value>"}] e.g. [{"parameter":"IPv4 Address", "operator":"Equals", "value":"10.100.85.111"}]

Table 64: GET /qvm/vulninstances Response Codes

HTTP Response Code

Unique Code

Description

200

 

The request to retrieve vulnerabilities by instance completed successfully

420

9101

Invalid search parameters, search cannot be performed

Response Description

List of vulnerability instance data.

GET /qvm/vulns DEPRECATED

List the Vulnerabilities present in the asset model. The response will contain all available RESTful resources.

Table 65: GET /qvm/vulns Resource Details

MIME Type

application/json

Table 66: GET /qvm/vulns Request Parameter Details

Parameter

Type

Optionality

Data Type

MIME Type

Description

savedSearchId

query

Optional

String

text/plain

Id of saved search

savedSearchName

query

Optional

String

text/plain

Saved search name

filters

query

Optional

Array<Object>

application/json

List of JSON objects for application of bespoke query search dataset filter. Format [{"parameter":"<value>", "operator":"<value>", "value":"<value>"}] e.g. [{"parameter":"IPv4 Address", "operator":"Equals", "value":"10.100.85.111"}]

Table 67: GET /qvm/vulns Response Codes

HTTP Response Code

Unique Code

Description

200

 

The request to retrieve vulnerabilities completed successfully

420

9101

Invalid search parameters, search cannot be performed

Response Description

List of vulnerability data.

Reference Data Endpoints

Use the references for REST API V4 reference data endpoints.

GET /reference_data/map_of_sets DEPRECATED

Retrieve a list of all reference map of sets.

Table 68: GET /reference_data/map_of_sets Resource Details

MIME Type

application/json

Table 69: GET /reference_data/map_of_sets 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 70: GET /reference_data/map_of_sets Response Codes

HTTP Response Code

Unique Code

Description

200

 

The reference map of sets list has been retrieved

500

1020

An error occurred while attempting to retrieve all of the reference map of sets

Response Description

A list of all of the reference map of sets. This returns information about the map of sets but not the contained data.

Response Sample

[ { "creation_time": 42, "element_type": "String <one of: ALN, NUM, IP, PORT, ALNIC, DATE>", "key_label": "String", "name": "String", "number_of_elements": 42, "time_to_live": "String", "timeout_type": "String <one of: UNKNOWN, FIRST_SEEN, LAST_SEEN>", "value_label": "String" } ]

DELETE /reference_data/map_of_sets/{name} DEPRECATED

Remove a map of sets or purge its contents.

Table 71: DELETE /reference_data/map_of_sets/{name} Resource Details

MIME Type

application/json

Table 72: DELETE /reference_data/map_of_sets/{name} Request Parameter Details

Parameter

Type

Optionality

Data Type

MIME Type

Description

name

path

Required

String

text/plain

Required - The name of the reference map of sets to remove or purge

purge_only

query

Optional

String

text/plain

Optional - The allowed values are "false" or "true". The default value is false. This indicates if the reference map of sets should have its contents purged (true), keeping the reference map of sets structure. If the value is "false" or not specified the reference map of sets will be removed completely.

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 73: DELETE /reference_data/map_of_sets/{name} Response Codes

HTTP Response Code

Unique Code

Description

200

 

The reference map has had its contents purged

204

 

The reference map has been removed

404

1002

The reference map of sets does not exist

409

1004

The reference map of sets could not be deleted, it is being used by other objects.

422

1005

A request parameter is not valid

500

1020

An error occurred while attempting to remove or purge values from the reference map of sets

Response Description

If the reference map of sets was removed nothing is returned, otherwise information about the reference map of sets that had its contents purged is returned.

Response Sample

{ "creation_time": 42, "element_type": "String <one of: ALN, NUM, IP, PORT, ALNIC, DATE>", "key_label": "String", "name": "String", "number_of_elements": 42, "time_to_live": "String", "timeout_type": "String <one of: UNKNOWN, FIRST_SEEN, LAST_SEEN>", "value_label": "String" }

GET /reference_data/map_of_sets/{name} DEPRECATED

Return the reference map of sets identified by name. If provided, limit specifies the number of records to return that starts at the record specified by offset. If not specified, then the first 20 records are returned.

Table 74: GET /reference_data/map_of_sets/{name} Resource Details

MIME Type

application/json

Table 75: GET /reference_data/map_of_sets/{name} Request Parameter Details

Parameter

Type

Optionality

Data Type

MIME Type

Description

name

path

Required

String

text/plain

Required - The name of the reference map of sets 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.

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 76: GET /reference_data/map_of_sets/{name} Response Codes

HTTP Response Code

Unique Code

Description

200

 

The reference map of sets has been retrieved

404

1002

The reference map of sets does not exist

422

1005

A request parameter is not valid

500

1020

An error occurred while attempting to retrieve the reference map of sets

Response Description

The reference map of sets identified by the name specified in the request. The portion of the reference map of sets' data returned is dependent on the limit and offset specified in the request.

Response Sample

{ "creation_time": 42, "data": { "String": [ { "first_seen": 42, "last_seen": 42, "source": "String", "value": "String" } ] }, "element_type": "String <one of: ALN, NUM, IP, PORT, ALNIC, DATE>", "key_label": "String", "name": "String", "number_of_elements": 42, "time_to_live": "String", "timeout_type": "String <one of: UNKNOWN, FIRST_SEEN, LAST_SEEN>", "value_label": "String" }

DELETE /reference_data/map_of_sets/{name}/{key} DEPRECATED

Remove a value from a reference map of sets.

Table 77: DELETE /reference_data/map_of_sets/{name}/{key} Resource Details

MIME Type

application/json

Table 78: DELETE /reference_data/map_of_sets/{name}/{key} Request Parameter Details

Parameter

Type

Optionality

Data Type

MIME Type

Description

name

path

Required

String

text/plain

Required - The name of the reference map of sets to remove a value from

key

path

Required

String

text/plain

Required - The key of the value to remove

value

query

Required

String

text/plain

Required - The value to remove from the reference map of sets. Note: Date values must be represented in milliseconds since the Unix Epoch January 1st 1970.

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 79: DELETE /reference_data/map_of_sets/{name}/{key} Response Codes

HTTP Response Code

Unique Code

Description

200

 

The reference map of sets has had a value removed

404

1002

The reference map of sets does not exist

404

1003

The record does not exist in the reference map of sets

422

1005

A request parameter is not valid

500

1020

An error occurred while attempting to remove the reference map of sets value

Response Description

Information about the reference map of sets that had a value removed. This returns information about the reference map of sets but not the contained data.

Response Sample

{ "creation_time": 42, "element_type": "String <one of: ALN, NUM, IP, PORT, ALNIC, DATE>", "key_label": "String", "name": "String", "number_of_elements": 42, "time_to_live": "String", "timeout_type": "String <one of: UNKNOWN, FIRST_SEEN, LAST_SEEN>", "value_label": "String" }

POST /reference_data/map_of_sets/{name} DEPRECATED

Add or update an element in a reference map of sets.

Table 80: POST /reference_data/map_of_sets/{name} Resource Details

MIME Type

application/json

Table 81: POST /reference_data/map_of_sets/{name} Request Parameter Details

Parameter

Type

Optionality

Data Type

MIME Type

Description

name

path

Required

String

text/plain

Required - The name of the reference map of sets to add or update an element in

key

query

Required

String

text/plain

Required - The key of the set to add or update

value

query

Required

String

text/plain

Required - The value to add or update in the reference map of sets. Note: Date values must be represented in milliseconds since the Unix Epoch January 1st 1970.

source

query

Optional

String

text/plain

Optional - This indicates where the data originated. The default value is 'reference data api'

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 82: POST /reference_data/map_of_sets/{name} Response Codes

HTTP Response Code

Unique Code

Description

200

 

The reference map of sets has had an element added or updated

404

1002

The reference map of sets does not exist

422

1005

A request parameter is not valid

500

1020

An error occurred while attempting to add or update data in the reference map of sets

Response Description

Information about the reference map of sets that has had an element added or updated. This returns information about the reference map of sets but not the contained data.

Response Sample

{ "creation_time": 42, "element_type": "String <one of: ALN, NUM, IP, PORT, ALNIC, DATE>", "key_label": "String", "name": "String", "number_of_elements": 42, "time_to_live": "String", "timeout_type": "String <one of: UNKNOWN, FIRST_SEEN, LAST_SEEN>", "value_label": "String" }

POST /reference_data/map_of_sets DEPRECATED

Create a new reference map of sets.

Table 83: POST /reference_data/map_of_sets Resource Details

MIME Type

application/json

Table 84: POST /reference_data/map_of_sets Request Parameter Details

Parameter

Type

Optionality

Data Type

MIME Type

Description

name

query

Required

String

text/plain

Required - The name of the reference map of sets to create

element_type

query

Required

String

text/plain

Required - The element type for the values allowed in the reference map of sets. The allowed values are: ALN (alphanumeric), ALNIC (alphanumeric ignore case), IP (IP address), NUM (numeric), PORT (port number) or DATE. Note that date values need to be represented in milliseconds since the Unix Epoch January 1st 1970.

key_label

query

Optional

String

text/plain

Optional - The label to describe the keys

value_label

query

Optional

String

text/plain

Optional - The label to describe the data values

timeout_type

query

Optional

String

text/plain

Optional - The allowed values are "FIRST_SEEN", "LAST_SEEN" and "UNKNOWN". The default value is "UNKNOWN". This indicates if the time_to_live interval is based on when the data was first seen or last seen.

time_to_live

query

Optional

String

text/plain

Optional - The time to live interval, for example: "1 month" or "5 minutes"

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 85: POST /reference_data/map_of_sets Response Codes

HTTP Response Code

Unique Code

Description

201

 

A new reference map of sets was successfully created

409

1004

The reference map of sets could not be created, the name provided is already in use. Please change the name and try again.

422

1005

A request parameter is not valid

500

1020

An error occurred while attempting to create the reference map of sets

Response Description

Information about the newly created reference map of sets.

Response Sample

{ "creation_time": 42, "element_type": "String <one of: ALN, NUM, IP, PORT, ALNIC, DATE>", "key_label": "String", "name": "String", "number_of_elements": 42, "time_to_live": "String", "timeout_type": "String <one of: UNKNOWN, FIRST_SEEN, LAST_SEEN>", "value_label": "String" }

GET /reference_data/maps DEPRECATED

Retrieve a list of all reference maps.

Table 86: GET /reference_data/maps Resource Details

MIME Type

application/json

Table 87: GET /reference_data/maps 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 88: GET /reference_data/maps Response Codes

HTTP Response Code

Unique Code

Description

200

 

The reference map list has been retrieved

500

1020

An error occurred while attempting to retrieve all of the reference maps

Response Description

A list of all of the reference maps. This returns information about the maps but not the contained data.

Response Sample

[ { "creation_time": 42, "element_type": "String <one of: ALN, NUM, IP, PORT, ALNIC, DATE>", "key_label": "String", "name": "String", "number_of_elements": 42, "time_to_live": "String", "timeout_type": "String <one of: UNKNOWN, FIRST_SEEN, LAST_SEEN>", "value_label": "String" } ]

DELETE /reference_data/maps/{name} DEPRECATED

Remove a reference map or purge its contents.

Table 89: DELETE /reference_data/maps/{name} Resource Details

MIME Type

application/json

Table 90: DELETE /reference_data/maps/{name} Request Parameter Details

Parameter

Type

Optionality

Data Type

MIME Type

Description

name

path

Required

String

text/plain

Required - The name of the reference map to remove or purge

purge_only

query

Optional

String

text/plain

Optional - The allowed values are "false" or "true". The default value is false. This indicates if the reference map should have its contents purged (true), keeping the reference map structure. If the value is "false" or not specified the reference map will be removed completely.

fields

query

Optional

String

text/plain

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

Table 91: DELETE /reference_data/maps/{name} Response Codes

HTTP Response Code

Unique Code

Description

200

 

The reference map has had its contents purged

204

 

The reference map has been removed

404

1002

The reference map does not exist

409

1004

The reference map could not be deleted, it is being used by other objects.

422

1005

A request parameter is not valid

500

1020

An error occurred while attempting to remove or purge values from the reference map

Response Description

If the reference map was removed nothing is returned, otherwise information about the reference map that had its contents purged is returned.

Response Sample

{ "creation_time": 42, "element_type": "String <one of: ALN, NUM, IP, PORT, ALNIC, DATE>", "key_label": "String", "name": "String", "number_of_elements": 42, "time_to_live": "String", "timeout_type": "String <one of: UNKNOWN, FIRST_SEEN, LAST_SEEN>", "value_label": "String" }

GET /reference_data/maps/{name} DEPRECATED

Retrieve the reference map identified by name. If provided, limit specifies the number of records to return that start at the record specified by offset. If not specified, then the first 20 records are returned.

Table 92: GET /reference_data/maps/{name} Resource Details

MIME Type

application/json

Table 93: GET /reference_data/maps/{name} Request Parameter Details

Parameter

Type

Optionality

Data Type

MIME Type

Description

name

path

Required

String

text/plain

Required - The name of the reference map 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.

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 94: GET /reference_data/maps/{name} Response Codes

HTTP Response Code

Unique Code

Description

200

 

The reference map has been retrieved

404

1002

The reference map does not exist

422

1005

A request parameter is not valid

500

1020

An error occurred while attempting to retrieve the reference map

Response Description

The reference map identified by the name specified in the request. The portion of the reference map's data returned is dependent on the limit and offset specified in the request.

Response Sample

{ "creation_time": 42, "data": { "String": { "first_seen": 42, "last_seen": 42, "source": "String", "value": "String" } }, "element_type": "String <one of: ALN, NUM, IP, PORT, ALNIC, DATE>", "key_label": "String", "name": "String", "number_of_elements": 42, "time_to_live": "String", "timeout_type": "String <one of: UNKNOWN, FIRST_SEEN, LAST_SEEN>", "value_label": "String" }

DELETE /reference_data/maps/{name}/{key} DEPRECATED

Remove a value from a reference map.

Table 95: DELETE /reference_data/maps/{name}/{key} Resource Details

MIME Type

application/json

Table 96: DELETE /reference_data/maps/{name}/{key} Request Parameter Details

Parameter

Type

Optionality

Data Type

MIME Type

Description

name

path

Required

String

text/plain

Required - The name of the reference map to remove a value from

key

path

Required

String

text/plain

Required - The key of the value to remove

value

query

Required

String

text/plain

Required - The value to remove from the reference map. Note: Date values must be represented in milliseconds since the Unix Epoch January 1st 1970.

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 97: DELETE /reference_data/maps/{name}/{key} Response Codes

HTTP Response Code

Unique Code

Description

200

 

The reference map has had a value removed

404

1002

The reference map does not exist

404

1003

The record does not exist in the reference map

422

1005

A request parameter is not valid

500

1020

An error occurred while attempting to remove the value from the reference map

Response Description

Information about the reference map that had an element removed. This returns information about map but not the contained data.

Response Sample

{ "creation_time": 42, "element_type": "String <one of: ALN, NUM, IP, PORT, ALNIC, DATE>", "key_label": "String", "name": "String", "number_of_elements": 42, "time_to_live": "String", "timeout_type": "String <one of: UNKNOWN, FIRST_SEEN, LAST_SEEN>", "value_label": "String" }

POST /reference_data/maps/{name} DEPRECATED

Add or update an element in a reference map.

Table 98: POST /reference_data/maps/{name} Resource Details

MIME Type

application/json

Table 99: POST /reference_data/maps/{name} Request Parameter Details

Parameter

Type

Optionality

Data Type

MIME Type

Description

name

path

Required

String

text/plain

Required - The name of the reference map to add or update an element in

key

query

Required

String

text/plain

Required - The key who's value we want to add or update

value

query

Required

String

text/plain

Required - The value to add or update in the reference map. Note: Date values must be represented in milliseconds since the Unix Epoch January 1st 1970.

source

query

Optional

String

text/plain

Optional - An indication of where the data originated. The default value is 'reference data api'

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 100: POST /reference_data/maps/{name} Response Codes

HTTP Response Code

Unique Code

Description

200

 

The reference map has had an element added or updated

404

1002

The reference map does not exist

422

1005

A request parameter is not valid

500

1020

An error occurred while attempting to add or update data in the reference map

Response Description

Information about the reference map that had an element added or updated. This returns information about reference map but not the contained data.

Response Sample

{ "creation_time": 42, "element_type": "String <one of: ALN, NUM, IP, PORT, ALNIC, DATE>", "key_label": "String", "name": "String", "number_of_elements": 42, "time_to_live": "String", "timeout_type": "String <one of: UNKNOWN, FIRST_SEEN, LAST_SEEN>", "value_label": "String" }

POST /reference_data/maps DEPRECATED

Create a new reference map.

Table 101: POST /reference_data/maps Resource Details

MIME Type

application/json

Table 102: POST /reference_data/maps Request Parameter Details

Parameter

Type

Optionality

Data Type

MIME Type

Description

name

query

Required

String

text/plain

Required - The name of the reference map to create

key_label

query

Optional

String

text/plain

Optional - The label to describe the keys

value_label

query

Optional

String

text/plain

Optional - The label to describe the data values

element_type

query

Required

String

text/plain

Required - The element type for the values allowed in the reference map. The allowed values are: ALN (alphanumeric), ALNIC (alphanumeric ignore case), IP (IP address), NUM (numeric), PORT (port number) or DATE. Note that date values need to be represented in milliseconds since the Unix Epoch January 1st 1970.

timeout_type

query

Optional

String

text/plain

Optional - The allowed values are "FIRST_SEEN", "LAST_SEEN" and "UNKNOWN". The default value is "UNKNOWN". This indicates if the time_to_live interval is based on when the data was first seen or last seen.

time_to_live

query

Optional

String

text/plain

Optional - The time to live interval, for example: "1 month" or "5 minutes"

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 103: POST /reference_data/maps Response Codes

HTTP Response Code

Unique Code

Description

201

 

A new reference map was successfully created

409

1004

The reference map could not be created, the name provided is already in use. Please change the name and try again.

422

1005

A request parameter is not valid

500

1020

An error occurred while attempting to create the reference map

Response Description

Information about the newly created reference map.

Response Sample

{ "creation_time": 42, "element_type": "String <one of: ALN, NUM, IP, PORT, ALNIC, DATE>", "key_label": "String", "name": "String", "number_of_elements": 42, "time_to_live": "String", "timeout_type": "String <one of: UNKNOWN, FIRST_SEEN, LAST_SEEN>", "value_label": "String" }

POST /reference_data/sets/bulk_load/{name} DEPRECATED

Add or update data in a reference set.

Table 104: POST /reference_data/sets/bulk_load/{name} Resource Details

MIME Type

application/json

Table 105: POST /reference_data/sets/bulk_load/{name} Request Parameter Details

Parameter

Type

Optionality

Data Type

MIME Type

Description

name

path

Required

String

text/plain

Required - The name of set to add or update data in

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 106: POST /reference_data/sets/bulk_load/{name} Request Body Details

Parameter

Data Type

MIME Type

Description

Sample

data

Array

application/json

Required - The JSON formated data to add or update in the reference set

["String", "String", "String", "String", "String", "String", "String", "String", "String", "String", "String"]

Table 107: POST /reference_data/sets/bulk_load/{name} Response Codes

HTTP Response Code

Unique Code

Description

200

 

The reference set has had data added or updated

400

1001

An error occurred parsing the JSON formatted message body

404

1002

The reference set does not exist

422

1005

A request parameter is not valid

500

1020

An error occurred while attempting to add or update data in the reference set

Response Description

Information about the reference set that had data added or updated. This returns information about the reference set but not the contained data.

Response Sample

{ "creation_time": 42, "element_type": "String <one of: ALN, NUM, IP, PORT, ALNIC, DATE>", "name": "String", "number_of_elements": 42, "time_to_live": "String", "timeout_type": "String <one of: UNKNOWN, FIRST_SEEN, LAST_SEEN>" }

GET /reference_data/sets DEPRECATED

Retrieve a list of all reference sets.

Table 108: GET /reference_data/sets Resource Details

MIME Type

application/json

Table 109: GET /reference_data/sets 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 110: GET /reference_data/sets Response Codes

HTTP Response Code

Unique Code

Description

200

 

The reference set list has been retrieved

500

1020

An error occurred while attempting to retrieve all of the reference sets

Response Description

A list of all of the reference sets. This returns information about the sets but not the contained data.

Response Sample

[ { "creation_time": 42, "element_type": "String <one of: ALN, NUM, IP, PORT, ALNIC, DATE>", "name": "String", "number_of_elements": 42, "time_to_live": "String", "timeout_type": "String <one of: UNKNOWN, FIRST_SEEN, LAST_SEEN>" } ]

DELETE /reference_data/sets/{name} DEPRECATED

Remove a reference set or purge its contents.

Table 111: DELETE /reference_data/sets/{name} Resource Details

MIME Type

application/json

Table 112: DELETE /reference_data/sets/{name} Request Parameter Details

Parameter

Type

Optionality

Data Type

MIME Type

Description

name

path

Required

String

text/plain

Required - The name of the set to remove or purge

purge_only

query

Optional

String

text/plain

Optional - The allowed values are "false" or "true". The default value is false. This indicates if the reference set should have its contents purged (true), keeping the reference set structure. If the value is "false" or not specified the reference set will be removed completely.

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 113: DELETE /reference_data/sets/{name} Response Codes

HTTP Response Code

Unique Code

Description

200

 

The reference set has had its contents purged

204

 

The reference set has been removed

404

1002

The reference set does not exist

409

1004

The reference set could not be deleted, it is being used by other objects.

422

1005

A request parameter is not valid

500

1020

An error occurred while attempting to remove or purge values from the reference set

Response Description

If the reference set was removed nothing is returned, otherwise information about the reference set that had its contents purged is returned.

Response Sample

{ "creation_time": 42, "element_type": "String <one of: ALN, NUM, IP, PORT, ALNIC, DATE>", "name": "String", "number_of_elements": 42, "time_to_live": "String", "timeout_type": "String <one of: UNKNOWN, FIRST_SEEN, LAST_SEEN>" }

GET /reference_data/sets/{name} DEPRECATED

Retrieve the reference set identified by name. If provided, limit specifies the number of records to return that start at the record specified by offset. If not specified, then the first 20 records are returned.

Table 114: GET /reference_data/sets/{name} Resource Details

MIME Type

application/json

Table 115: GET /reference_data/sets/{name} Request Parameter Details

Parameter

Type

Optionality

Data Type

MIME Type

Description

name

path

Required

String

text/plain

Required - The name of the reference set 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.

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 116: GET /reference_data/sets/{name} Response Codes

HTTP Response Code

Unique Code

Description

200

 

The reference set has been retrieved

404

1002

The reference set does not exist.

422

1005

A request parameter is not valid

500

1020

An error occurred while attempting to retrieve the reference set

Response Description

The reference set identified by the name specified in the request. The portion of the set's data returned is dependent on the limit and offset specified in the request.

Response Sample

{ "creation_time": 42, "data": [ { "first_seen": 42, "last_seen": 42, "source": "String", "value": "String" } ], "element_type": "String <one of: ALN, NUM, IP, PORT, ALNIC, DATE>", "name": "String", "number_of_elements": 42, "time_to_live": "String", "timeout_type": "String <one of: UNKNOWN, FIRST_SEEN, LAST_SEEN>" }

POST /reference_data/sets/{name} DEPRECATED

Add or update an element in a reference set.

Table 117: POST /reference_data/sets/{name} Resource Details

MIME Type

application/json

Table 118: POST /reference_data/sets/{name} Request Parameter Details

Parameter

Type

Optionality

Data Type

MIME Type

Description

name

path

Required

String

text/plain

Required - The name of the reference set to add or update an element in

value

query

Required

String

text/plain

Required - The value to add or update in the reference set. Note: Date values must be represented in milliseconds since the Unix Epoch January 1st 1970.

source

query

Optional

String

text/plain

Optional - An indication of where the data originated. The default value is 'reference data api'

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 119: POST /reference_data/sets/{name} Response Codes

HTTP Response Code

Unique Code

Description

200

 

The reference set has had an element added or updated

404

1002

The reference set does not exist

422

1005

A request parameter is not valid

500

1020

An error occurred while attempting to add or update an element in the reference set

Response Description

Information about the reference set that had an element added or updated. This returns information about the reference set but not the contained data.

Response Sample

{ "creation_time": 42, "element_type": "String <one of: ALN, NUM, IP, PORT, ALNIC, DATE>", "name": "String", "number_of_elements": 42, "time_to_live": "String", "timeout_type": "String <one of: UNKNOWN, FIRST_SEEN, LAST_SEEN>" }

DELETE /reference_data/sets/{name}/{value} DEPRECATED

Remove a value from a reference set.

Table 120: DELETE /reference_data/sets/{name}/{value} Resource Details

MIME Type

application/json

Table 121: DELETE /reference_data/sets/{name}/{value} Request Parameter Details

Parameter

Type

Optionality

Data Type

MIME Type

Description

name

path

Required

String

text/plain

Required - The name of the reference set to remove a value from

value

path

Required

String

text/plain

Required - The value to remove from the reference set. Note: Date values must be represented in milliseconds since the Unix Epoch January 1st 1970.

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 122: DELETE /reference_data/sets/{name}/{value} Response Codes

HTTP Response Code

Unique Code

Description

200

 

The reference set that had a value removed

404

1002

The reference set does not exist

404

1003

The record does not exist in the reference set

422

1005

A request parameter is not valid

500

1020

An error occurred while attempting to remove the value from the reference set.

Response Description

Information about the reference set that had an value removed. This returns information about the reference set but not the contained data.

Response Sample

{ "creation_time": 42, "element_type": "String <one of: ALN, NUM, IP, PORT, ALNIC, DATE>", "name": "String", "number_of_elements": 42, "time_to_live": "String", "timeout_type": "String <one of: UNKNOWN, FIRST_SEEN, LAST_SEEN>" }

POST /reference_data/sets DEPRECATED

Create a new reference set.

Table 123: POST /reference_data/sets Resource Details

MIME Type

application/json

Table 124: POST /reference_data/sets Request Parameter Details

Parameter

Type

Optionality

Data Type

MIME Type

Description

name

query

Required

String

text/plain

Required - The name of the reference set being created

element_type

query

Required

String

text/plain

Required - The element type for the values allowed in the reference set. The allowed values are: ALN (alphanumeric), ALNIC (alphanumeric ignore case), IP (IP address), NUM (numeric), PORT (port number) or DATE. Note that date values need to be represented in milliseconds since the Unix Epoch January 1st 1970.

timeout_type

query

Optional

String

text/plain

Optional - The allowed values are "FIRST_SEEN", "LAST_SEEN" and "UNKNOWN". The default value is "UNKNOWN". This indicates if the time_to_live interval is based on when the data was first seen or last seen.

time_to_live

query

Optional

String

text/plain

Optional - The time to live interval, for example: "1 month" or "5 minutes"

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 125: POST /reference_data/sets Response Codes

HTTP Response Code

Unique Code

Description

201

 

A new reference set was successfully created

409

1004

The reference set could not be created, the name provided is already in use. Please change the name and try again.

422

1005

A request parameter is not valid

500

1020

An error occurred while attempting to create the reference set

Response Description

Information about the newly created reference set.

Response Sample

{ "creation_time": 42, "element_type": "String <one of: ALN, NUM, IP, PORT, ALNIC, DATE>", "name": "String", "number_of_elements": 42, "time_to_live": "String", "timeout_type": "String <one of: UNKNOWN, FIRST_SEEN, LAST_SEEN>" }

GET /reference_data/tables DEPRECATED

Retrieve a list of all reference tables.

Table 126: GET /reference_data/tables Resource Details

MIME Type

application/json

Table 127: GET /reference_data/tables 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 128: GET /reference_data/tables Response Codes

HTTP Response Code

Unique Code

Description

200

 

The reference table list has been retrieved

500

1020

An error occurred while attempting to retrieve all of the reference tables

Response Description

A list of all of the reference tables. This returns information about the tables but not the contained data.

Response Sample

[ { "creation_time": 42, "element_type": "String <one of: ALN, NUM, IP, PORT, ALNIC, DATE>", "key_label": "String", "key_name_types": { "String": "String <one of: ALN, NUM, IP, PORT, ALNIC, DATE>" }, "name": "String", "number_of_elements": 42, "time_to_live": "String", "timeout_type": "String <one of: UNKNOWN, FIRST_SEEN, LAST_SEEN>" } ]

DELETE /reference_data/tables/{name} DEPRECATED

Remove a reference table or purge its contents.

Table 129: DELETE /reference_data/tables/{name} Resource Details

MIME Type

application/json

Table 130: DELETE /reference_data/tables/{name} Request Parameter Details

Parameter

Type

Optionality

Data Type

MIME Type

Description

name

path

Required

String

text/plain

Required - The name of the reference table to remove or purge

purge_only

query

Optional

String

text/plain

Optional - The allowed values are "false" or "true". The default value is false. This indicates if the reference table should have its contents purged (true), keeping the reference table structure. If the value is "false" or not specified the reference table will be removed completely.

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 131: DELETE /reference_data/tables/{name} Response Codes

HTTP Response Code

Unique Code

Description

200

 

The reference table has had its contents purged

204

 

The reference table has been removed

404

1002

The reference table does not exist

409

1004

The reference table could not be deleted, it is being used by other objects.

422

1005

A request parameter is not valid

500

1020

An error occurred while attempting to remove or purge values from the reference table

Response Description

If the table was removed nothing is returned, otherwise information about the reference table that had its contents purged is returned.

Response Sample

{ "creation_time": 42, "element_type": "String <one of: ALN, NUM, IP, PORT, ALNIC, DATE>", "key_label": "String", "key_name_types": { "String": "String <one of: ALN, NUM, IP, PORT, ALNIC, DATE>" }, "name": "String", "number_of_elements": 42, "time_to_live": "String", "timeout_type": "String <one of: UNKNOWN, FIRST_SEEN, LAST_SEEN>" }

GET /reference_data/tables/{name} DEPRECATED

Return the reference table identified by name. If provided, limit specifies the number of records to return that start at the record specified by offset. If not specified, then the first 20 records are returned.

Table 132: GET /reference_data/tables/{name} Resource Details

MIME Type

application/json

Table 133: GET /reference_data/tables/{name} Request Parameter Details

Parameter

Type

Optionality

Data Type

MIME Type

Description

name

path

Required

String

text/plain

Required - The name of the reference table 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.

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 134: GET /reference_data/tables/{name} Response Codes

HTTP Response Code

Unique Code

Description

200

 

The reference table has been retrieved

404

1002

The reference table does not exist

422

1005

A request parameter is not valid

500

1020

An error occurred while attempting to retrieve the reference table

Response Description

The reference table identified by the name specified in the request. The portion of the reference table's data returned is dependent on the limit and offset specified in the request.

Response Sample

{ "creation_time": 42, "data": { "String": { "String": { "first_seen": 42, "last_seen": 42, "source": "String", "value": "String" } } }, "element_type": "String <one of: ALN, NUM, IP, PORT, ALNIC, DATE>", "key_label": "String", "key_name_types": { "String": "String <one of: ALN, NUM, IP, PORT, ALNIC, DATE>" }, "name": "String", "number_of_elements": 42, "time_to_live": "String", "timeout_type": "String <one of: UNKNOWN, FIRST_SEEN, LAST_SEEN>" }

DELETE /reference_data/tables/{name}/{outer_key}/{inner_key} DEPRECATED

Remove a value from a reference table.

Table 135: DELETE /reference_data/tables/{name}/{outer_key}/{inner_key} Resource Details

MIME Type

application/json

Table 136: DELETE /reference_data/tables/{name}/{outer_key}/{inner_key} Request Parameter Details

Parameter

Type

Optionality

Data Type

MIME Type

Description

name

path

Required

String

text/plain

Required - The name of the reference table to remove a value from

outer_key

path

Required

String

text/plain

Required - The outer key of the value to remove

inner_key

path

Required

String

text/plain

Required - The inner key of the value to remove

value

query

Required

String

text/plain

Required - The value to remove from the reference table. Note: Date values must be represented in milliseconds since the Unix Epoch January 1st 1970.

fields

query

Optional

String

text/plain

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

Table 137: DELETE /reference_data/tables/{name}/{outer_key}/{inner_key} Response Codes

HTTP Response Code

Unique Code

Description

200

 

The reference table had had a value removed

404

1002

The reference table does not exist

404

1003

The record does not exist in the reference table

422

1005

A request parameter is not valid

500

1020

An error occurred while attempting to remove the reference table value

Response Description

Information about the reference table that had an element removed. This returns information about table but not the contained data.

Response Sample

{ "creation_time": 42, "element_type": "String <one of: ALN, NUM, IP, PORT, ALNIC, DATE>", "key_label": "String", "key_name_types": { "String": "String <one of: ALN, NUM, IP, PORT, ALNIC, DATE>" }, "name": "String", "number_of_elements": 42, "time_to_live": "String", "timeout_type": "String <one of: UNKNOWN, FIRST_SEEN, LAST_SEEN>" }

POST /reference_data/tables/{name} DEPRECATED

Add or update an element in a reference table.

The value to be added must be of the appropriate type: either the type that corresponds to the innerKey predefined for the reference table, or the default elementType of the reference table.

Table 138: POST /reference_data/tables/{name} Resource Details

MIME Type

application/json

Table 139: POST /reference_data/tables/{name} Request Parameter Details

Parameter

Type

Optionality

Data Type

MIME Type

Description

name

path

Required

String

text/plain

Required - The name of the reference table to add or update an element in

outer_key

query

Required

String

text/plain

Required - The outer key for the element to add or update

inner_key

query

Required

String

text/plain

Required - The inner key for the element to add or update

value

query

Required

String

text/plain

Required - The value to add or update in the reference table. Note: Date values must be represented in milliseconds since the Unix Epoch January 1st 1970.

source

query

Optional

String

text/plain

Optional - An indication of where the data originated. The default value is 'reference data api'

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: POST /reference_data/tables/{name} Response Codes

HTTP Response Code

Unique Code

Description

200

 

The reference table has had an element added or updated

404

1002

The reference table does not exist

422

1005

A request parameter is not valid

500

1020

An error occurred while attempting to add or update data in the reference table

Response Description

Information about the reference table that had an element added or updated. This returns information about the reference table but not the contained data.

Response Sample

{ "creation_time": 42, "element_type": "String <one of: ALN, NUM, IP, PORT, ALNIC, DATE>", "key_label": "String", "key_name_types": { "String": "String <one of: ALN, NUM, IP, PORT, ALNIC, DATE>" }, "name": "String", "number_of_elements": 42, "time_to_live": "String", "timeout_type": "String <one of: UNKNOWN, FIRST_SEEN, LAST_SEEN>" }

POST /reference_data/tables DEPRECATED

Create a new reference table.

Table 141: POST /reference_data/tables Resource Details

MIME Type

application/json

Table 142: POST /reference_data/tables Request Parameter Details

Parameter

Type

Optionality

Data Type

MIME Type

Description

name

query

Required

String

text/plain

Required - The name of the reference table to create

element_type

query

Required

String

text/plain

Required - The default element type for the values allowed in the reference table. This is used when values are added or updated in the reference table who's inner key was not defined in the key_name_types parameter. The allowed values are: ALN (alphanumeric), ALNIC (alphanumeric ignore case), IP (IP address), NUM (numeric), PORT (port number) or DATE. Note that date values need to be represented in milliseconds since the Unix Epoch January 1st 1970.

outer_key_label

query

Optional

String

text/plain

Optional - The label to describe the outer keys

timeout_type

query

Optional

String

text/plain

Optional - The allowed values are "FIRST_SEEN", "LAST_SEEN" and "UNKNOWN". The default value is "UNKNOWN". This indicates if the time_to_live interval is based on when the data was first seen or last seen.

time_to_live

query

Optional

String

text/plain

Optional - The time to live interval, for example: "1 month" or "5 minutes"

key_name_types

query

Optional

Array<Object>

application/json

Optional - A JSON formatted string. This array creates the inner key names and corresponding value types for the table

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: POST /reference_data/tables Response Codes

HTTP Response Code

Unique Code

Description

201

 

A new reference table was successfully created

409

1004

The reference table could not be created, the name provided is already in use. Please change the name and try again.

422

1005

A request parameter is not valid

500

1020

An error occurred while attempting to create the reference table

Response Description

Information about the newly created reference table.

Response Sample

{ "creation_time": 42, "element_type": "String <one of: ALN, NUM, IP, PORT, ALNIC, DATE>", "key_label": "String", "key_name_types": { "String": "String <one of: ALN, NUM, IP, PORT, ALNIC, DATE>" }, "name": "String", "number_of_elements": 42, "time_to_live": "String", "timeout_type": "String <one of: UNKNOWN, FIRST_SEEN, LAST_SEEN>" }

Scanner Endpoints

Use the references for REST API V4 scanner endpoints.

GET /scanner/profiles DEPRECATED

Retrieves all of the currently created scan profiles.

No parameters are required and the following information should be retrieved for each scan profile:

  • scanProfileId

  • scanProfileName

  • description

  • scanType

  • scannerName

Table 144: GET /scanner/profiles Resource Details

MIME Type

application/json

There are no parameters for this endpoint.

Table 145: GET /scanner/profiles Response Codes

HTTP Response Code

Unique Code

Description

200

 

The list of scan profiles was successfully returned

500

1030

Occurs when an attempt is made to list scan profiles when certain conditions are not met, or when too many scan requests have been made

Response Description

The list of scan profiles currently configured in JSA Vulnerability Manager.

Response Sample

POST /scanner/profiles/create DEPRECATED

Initiates a request to create a new scan profile.

The request takes one parameter - createScanRequest, which is just a POJO. To create the scan, you need to build up a JSON object that contains the Scan Profile name and ips to scan e.g. {'name':'New Scan Profile', 'ips':['10.100.85.135']}.

Table 146: POST /scanner/profiles/create Resource Details

MIME Type

text/plain

Table 147: POST /scanner/profiles/create Request Body Details

Parameter

Data Type

MIME Type

Description

Sample

scanProfile

JSON

application/json

null

null

Table 148: POST /scanner/profiles/create Response Codes

HTTP Response Code

Unique Code

Description

200

 

The scan has been successfully created

419

9101

Occurs when a parameter is missing or invalid

500

1030

Occurs when an attempt is made to create a scan when certain conditions are not met, or when too many scan requests have been made

Response Description

An indicator of whether the scan has been created successfully or not.

Response Sample

String

POST /scanner/profiles/start DEPRECATED

Initiates a request to start an existing scan profile.

The request takes one parameter - scanProfileId. To get a list of scanProfileIds, simply get a list of the current scan profiles by initiating a 'profiles' request on the scanner endpoint. The scanProfileId is validated and an appropriate message returned.

Table 149: POST /scanner/profiles/start Resource Details

MIME Type

text/plain

Table 150: POST /scanner/profiles/start Request Parameter Details

Parameter

Type

Optionality

Data Type

MIME Type

Description

scanProfileId

query

Required

String

text/plain

The unique id of the scan profile we want to start

Table 151: POST /scanner/profiles/start Response Codes

HTTP Response Code

Unique Code

Description

200

 

The scan has been successfully started

403

1000

Occurs if the user does not have permission to start a scan, or the scan is in progress

500

1030

Occurs when an attempt is made to start a scan when certain conditions are not met, or when too many scan requests have been made

Response Description

An indicator of whether the scan has been started successfully or not.

Response Sample

String

GET /scanner/scanprofiles DEPRECATED

Retrieves all of the currently created scan profiles.

No parameters are required and the following information should be retrieved for each scan profile:

  • scanProfileId

  • name

  • description

  • scanType

  • scannerName

  • schedule

  • status

  • progress

  • endTime

  • duration

Table 152: GET /scanner/scanprofiles Resource Details

MIME Type

application/json

Table 153: GET /scanner/scanprofiles Request Parameter Details

Parameter

Type

Optionality

Data Type

MIME Type

Description

fields

query

Optional

String

text/plain

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

filter

query

Optional

String

text/plain

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

Range

header

Optional

String

text/plain

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

Table 154: GET /scanner/scanprofiles Response Codes

HTTP Response Code

Unique Code

Description

200

 

The list of scan profiles was successfully returned

500

1030

Occurs when an attempt is made to list scan profiles when certain conditions are not met, or when too many scan requests have been made

Response Description

The list of scan profiles currently configured in JSA Vulnerability Manager.

Response Sample

[ { "description": "String", "duration": { "days": 42, "hours": 42, "minutes": 42, "months": 42, "seconds": 42.5, "type": "String", "value": "String", "years": 42 }, "endTime": { "date": 42, "day": 42, "hours": 42, "minutes": 42, "month": 42, "seconds": 42, "time": 42, "timezoneOffset": 42, "year": 42 }, "progress": 42, "scanProfileId": 42, "scanProfileName": "String", "scanType": "String", "scannerName": "String", "schedule": "String", "status": "String" } ]

POST /scanner/scanprofiles DEPRECATED

Initiates a request to create a new scanProfile.

The request takes one parameter - createScanRequest, which is just a POJO. To create the scan, you will need to build up a JSON object that contains the Scan Profile name and hosts to scan e.g. {'name':'New Scan Profile', 'hosts':['10.100.85.135']}

Table 155: POST /scanner/scanprofiles Resource Details

MIME Type

text/plain

Table 156: POST /scanner/scanprofiles Request Body Details

Parameter

Data Type

MIME Type

Description

Sample

scanProfile

Object

application/json

null

{ "description": "String", "hosts": [ "String" ], "name": "String" }

Table 157: POST /scanner/scanprofiles Response Codes

HTTP Response Code

Unique Code

Description

200

 

The scan has been successfully created

500

1030

Occurs when an attempt is made to create a scan when certain conditions are not met, or when too many scan requests have been made

Response Description

An indicator of whether the scan is created successfully or not.

Response Sample

String

GET /scanner/scanprofiles/{profileid} DEPRECATED

Retrieves a scan profile for a given Scan Profile ID.

The only parameter required is the Scan Profile ID. The following information about a scan profile is returned:

  • scanProfileId

  • name

  • description

  • scanType

  • scannerName

  • schedule

  • status

  • progress

  • endTime

  • duration

Table 158: GET /scanner/scanprofiles/{profileid} Resource Details

MIME Type

application/json

Table 159: GET /scanner/scanprofiles/{profileid} Request Parameter Details

Parameter

Type

Optionality

Data Type

MIME Type

Description

profileid

path

Required

String

text/plain

The unique id of the scan profile we need to retrieve information 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.

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 160: GET /scanner/scanprofiles/{profileid} Response Codes

HTTP Response Code

Unique Code

Description

200

 

The scan profile was successfully returned

500

1030

Occurs when an attempt is made to list a scan profile when certain conditions are not met, or when too many scan requests have been made

Response Description

The list of scan profiles currently configured in JSA Vulnerability Manager.

Response Sample

[ { "description": "String", "duration": { "days": 42, "hours": 42, "minutes": 42, "months": 42, "seconds": 42.5, "type": "String", "value": "String", "years": 42 }, "endTime": { "date": 42, "day": 42, "hours": 42, "minutes": 42, "month": 42, "seconds": 42, "time": 42, "timezoneOffset": 42, "year": 42 }, "progress": 42, "scanProfileId": 42, "scanProfileName": "String", "scanType": "String", "scannerName": "String", "schedule": "String", "status": "String" } ]

POST /scanner/scanprofiles/{profileid} DEPRECATED

Update a scan profile.

The Scan Profile ID is required. The following information on a scan profile can be updated: - name - description - ips eg {'name':'Updated Scan Profile', 'ips':['10.100.85.135']}

  • name

  • description

  • ips

For example:

{'name':'Updated Scan Profile', 'ips':['10.100.85.135']}

Table 161: POST /scanner/scanprofiles/{profileid} Resource Details

MIME Type

application/json

Table 162: POST /scanner/scanprofiles/{profileid} Request Parameter Details

Parameter

Type

Optionality

Data Type

MIME Type

Description

profileid

path

Required

String

text/plain

The unique id of the scan profile used to update

Table 163: POST /scanner/scanprofiles/{profileid} Request Body Details

Parameter

Data Type

MIME Type

Description

Sample

scanProfile

JSON

application/json

null

null

Table 164: POST /scanner/scanprofiles/{profileid} Response Codes

HTTP Response Code

Unique Code

Description

202

 

The scan profile was successfully updated

500

1030

Occurs when an attempt is made to update a scan profile when certain conditions are not met, or when too many scan requests have been made

Response Description

A message to indicate whether the scan profile has updated or not.

Response Sample

DELETE /scanner/scanprofiles/{profileid} DEPRECATED

Initiates a request to delete a scanProfile. The request takes one parameter - the Scan Profile ID.

Table 165: DELETE /scanner/scanprofiles/{profileid} Resource Details

MIME Type

text/plain

Table 166: DELETE /scanner/scanprofiles/{profileid} Request Parameter Details

Parameter

Type

Optionality

Data Type

MIME Type

Description

profileid

path

Required

String

text/plain

null

Table 167: DELETE /scanner/scanprofiles/{profileid} Response Codes

HTTP Response Code

Unique Code

Description

204

 

The scan has been successfully deleted

500

1030

Occurs when an attempt is made to delete a scan when certain conditions are not met, or when too many scan requests have been made

Response Description

An indicator of whether the scan has been deleted successfully or not.

Response Sample

String

POST /scanner/scanprofiles/{profileid}/start DEPRECATED

Initiates a request to start an already created scanProfile.

The request takes one parameter - scanProfileId, and one optional parameter - ips. To get a list of scanProfileIds, simply get a list of the current scan profiles by initiating a 'profiles' request on the scanner endpoint. The scanProfileId is validated and an appropriate message returned.

Table 168: POST /scanner/scanprofiles/{profileid}/start Resource Details

MIME Type

text/plain

Table 169: POST /scanner/scanprofiles/{profileid}/start Request Parameter Details

Parameter

Type

Optionality

Data Type

MIME Type

Description

profileid

path

Required

String

text/plain

The unique id of the scan profile we want to start

Table 170: POST /scanner/scanprofiles/{profileid}/start Request Body Details

Parameter

Data Type

MIME Type

Description

Sample

ips

JSON

application/json

null

null

Table 171: POST /scanner/scanprofiles/{profileid}/start Response Codes

HTTP Response Code

Unique Code

Description

202

 

The scan has been successfully started

403

1000

Occurs if the user does not have permission to start a scan, or the scan is in progress

500

1030

Occurs when an attempt is made to start a scan when certain conditions are not met, or when too many scan requests have been made

Response Description

An indicator of whether the scan has been started successfully or not.

Response Sample

String

SIEM Endpoints

Use the references for REST API V4 SIEM endpoints.

GET /siem/local_destination_addresses DEPRECATED

Retrieve a list offense local destination addresses currently in the system.

Table 172: GET /siem/local_destination_addresses Resource Details

MIME Type

application/json

Table 173: GET /siem/local_destination_addresses 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 174: GET /siem/local_destination_addresses Response Codes

HTTP Response Code

Unique Code

Description

200

 

The local destination address list was retrieved.

422

1005

A request parameter is not valid.

422

1010

The filter parameter is not valid.

500

1020

An error occurred while the local destination address list was being retrieved.

Response Description

An array of local destination address objects. A local destination address object contains the following fields:

  • id - Number - The ID of the destination address.

  • local_destination_ip - String - The IP address.

  • magnitude - Number - The magnitude of the destination address.

  • network - String - The network of the destination address.

  • offense_ids - Array of Numbers - List of offense IDs the destination address is part of.

  • source_address_ids - Array of Numbers - List of source address IDs associated with the destination address.

  • event_flow_count - Number - The number of events and flows that are associated with the destination address.

  • first_event_flow_seen - Number - The number of milliseconds since epoch when the first event or flow was seen.

  • last_event_flow_seen - Number - The number of milliseconds since epoch when the last event or flow was seen.

  • domain_id - Number - The ID of associated domain.

Response Sample

[ { "domain_id": 42, "event_flow_count": 42, "first_event_flow_seen": 42, "id": 42, "last_event_flow_seen": 42, "local_destination_ip": "String", "magnitude": 42, "network": "String", "offense_ids": [ 42 ], "source_address_ids": [ 42 ] } ]

GET /siem/local_destination_addresses/{local_destination_address_id} DEPRECATED

Retrieve an offense local destination address.

Table 175: GET /siem/local_destination_addresses/{local_destination_address_id} Resource Details

MIME Type

application/json

Table 176: GET /siem/local_destination_addresses/{local_destination_address_id} Request Parameter Details

Parameter

Type

Optionality

Data Type

MIME Type

Description

local_destination_address_id

path

Required

Number (Integer)

text/plain

Required - The ID of the local destination address 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 177: GET /siem/local_destination_addresses/{local_destination_address_id} Response Codes

HTTP Response Code

Unique Code

Description

200

 

The local destination was retrieved.

404

1002

No local destination address was found for the provided local_destination_address_id.

422

1005

A request parameter is not valid.

500

1020

An error occurred while the local destination address was being retrieved.

Response Description

A local destination address object. A local destination address object contains the following fields:

  • id - Number - The ID of the destination address.

  • local_destination_ip - String - The IP address.

  • magnitude - Number - The magnitude of the destination address.

  • network - String - The network of the destination address.

  • offense_ids - Array of Numbers - List of offense IDs the destination address is part of.

  • source_address_ids - Array of Numbers - List of source address IDs associated with the destination address.

  • event_flow_count - Number - The number of events and flows that are associated with the destination address.

  • first_event_flow_seen - Number - The number of milliseconds since epoch when the first event or flow was seen.

  • last_event_flow_seen - Number - The number of milliseconds since epoch when the last event or flow was seen.

  • domain_id - Number - The ID of associated domain.

Response Sample

{ "domain_id": 42, "event_flow_count": 42, "first_event_flow_seen": 42, "id": 42, "last_event_flow_seen": 42, "local_destination_ip": "String", "magnitude": 42, "network": "String", "offense_ids": [ 42 ], "source_address_ids": [ 42 ] }

GET /siem/offense_closing_reasons DEPRECATED

Retrieve a list of all offense closing reasons.

Table 178: GET /siem/offense_closing_reasons Resource Details

MIME Type

application/json

Table 179: GET /siem/offense_closing_reasons Request Parameter Details

Parameter

Type

Optionality

Data Type

MIME Type

Description

include_reserved

query

Optional

Boolean

text/plain

Optional - If true, reserved closing reasons are included in the response. Defaults to false. Reserved closing reasons cannot be used to close an offense.

include_deleted

query

Optional

Boolean

text/plain

Optional - If true, deleted closing reasons are included in the response. Defaults to false. Deleted closing reasons cannot be used to close an offense.

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 180: GET /siem/offense_closing_reasons Response Codes

HTTP Response Code

Unique Code

Description

200

 

The closing reasons list was retrieved.

500

1020

An error occurred while the closing reasons list was being retrieved.

Response Description

An array of ClosingReason objects. A closing reason object contains the following fields:

  • id - Number - The ID of the closing reason.

  • text - String - The text of the closing reason.

  • is_deleted - Boolean - Determines whether the closing reason is deleted. Deleted closing reasons cannot be used to close an offense.

  • is_reserved - Boolean - Determines whether the closing reason is reserved. Reserved closing reasons cannot be used to close an offense.

Response Sample

[ { "id": 42, "is_deleted": true, "is_reserved": true, "text": "String" } ]

POST /siem/offense_closing_reasons DEPRECATED

Create an offense closing reason.

Table 181: POST /siem/offense_closing_reasons Resource Details

MIME Type

application/json

Table 182: POST /siem/offense_closing_reasons Request Parameter Details

Parameter

Type

Optionality

Data Type

MIME Type

Description

reason

query

Required

String

text/plain

Required - The text of the offense closing reason must be 5 - 60 characters in length.

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 183: POST /siem/offense_closing_reasons Response Codes

HTTP Response Code

Unique Code

Description

201

 

The closing reason was created.

409

1004

The closing reason already exists.

422

1005

A request parameter is not valid.

500

1020

An error occurred while attempting to create the closing reason.

Response Description

A ClosingReason object. A closing reason object contains the following fields:

  • id - Number - The ID of the closing reason.

  • text - String - The text of the closing reason.

  • is_deleted - Boolean - Determines whether the closing reason is deleted. Deleted closing reasons cannot be used to close an offense.

  • is_reserved - Boolean - Determines whether the closing reason is reserved. Reserved closing reasons cannot be used to close an offense.

Response Sample

{ "id": 42, "is_deleted": true, "is_reserved": true, "text": "String" }

GET /siem/offense_closing_reasons/{closing_reason_id} DEPRECATED

Retrieve an offense closing reason.

Table 184: GET /siem/offense_closing_reasons/{closing_reason_id} Resource Details

MIME Type

application/json

Table 185: GET /siem/offense_closing_reasons/{closing_reason_id} Request Parameter Details

Parameter

Type

Optionality

Data Type

MIME Type

Description

closing_reason_id

path

Required

Number (Integer)

text/plain

Required - The closing reason ID.

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 186: GET /siem/offense_closing_reasons/{closing_reason_id} Response Codes

HTTP Response Code

Unique Code

Description

200

 

The closing reason was retrieved.

404

1002

No closing reason was found for the provided closing_reason_id.

422

1005

A request parameter is not valid.

500

1020

An error occurred while attempting to retrieve the closing reason.

Response Description

A ClosingReason object. A closing reason object contains the following fields:

  • id - Number - The ID of the closing reason.

  • text - String - The text of the closing reason.

  • is_deleted - Boolean - Determines whether the closing reason is deleted. Deleted closing reasons cannot be used to close an offense.

  • is_reserved - Boolean - Determines whether the closing reason is reserved. Reserved closing reasons cannot be used to close an offense.

Response Sample

{ "id": 42, "is_deleted": true, "is_reserved": true, "text": "String" }

GET /siem/offenses DEPRECATED

Retrieve a list of offenses currently in the system.

Table 187: GET /siem/offenses Resource Details

MIME Type

application/json

Table 188: GET /siem/offenses 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 189: GET /siem/offenses Response Codes

HTTP Response Code

Unique Code

Description

200

 

The offense list was retrieved.

422

1005

A request parameter is not valid.

422

1010

The filter parameter is not valid.

500

1020

An error occurred while the offense list was being retrieved.

Response Description

An array of Offense objects. An Offense object contains the following fields:

  • id - Number - The ID of the offense.

  • description - String - The description of the offense. Filtering is not supported on this field.

  • assigned_to - String - The user the offense is assigned to.

  • categories - Array of strings - Event categories that are associated with the offense.

  • category_count - Number - The number of event categories that are associated with the offense.

  • policy_category_count - Number - The number of policy event categories that are associated with the offense.

  • security_category_count - Number - The number of security event categories that are associated with the offense.

  • close_time - Number - The number of milliseconds since epoch when the offense was closed.

  • closing_user - String - The user that closed the offense.

  • closing_reason_id - Number - The ID of the offense closing reason. The reason the offense was closed.

  • credibility - Number - The credibility of the offense.

  • relevance - Number - The relevance of the offense.

  • severity - Number - The severity of the offense.

  • magnitude - Number - The magnitude of the offense.

  • destination_networks - Array of strings - The destination networks that are associated with the offense.

  • source_network - String - The source network that is associated with the offense. Filtering is not supported on this field.

  • device_count - Number - The number of devices that are associated with the offense.

  • event_count - Number - The number of events that are associated with the offense.

  • flow_count - Number - The number of flows that are associated with the offense.

  • inactive - Boolean - True if the offense is inactive.

  • last_updated_time - Number - The number of milliseconds since epoch when the offense was last updated.

  • local_destination_count - Number - The number of local destinations that are associated with the offense.

  • offense_source - String - The source of the offense. Filtering is not supported on this field.

  • offense_type - Number - A number that represents the offense type. See the Offense Type Codes table for the code to offense type mapping.

  • protected - Boolean - True if the offense is protected.

  • follow_up - Boolean - True if the offense is marked for follow up.

  • remote_destination_count - Number - The number of remote destinations that are associated wit the offense.

  • source_count - Number - The number of sources that are associated with the offense.

  • start_time - Number - The number of milliseconds since epoch when the offense was started.

  • status - String - The status of the offense. One of "OPEN", "HIDDEN", or "CLOSED". The following operators are not supported when you filter on this field: "<", ">", "<=", ">=", "BETWEEN".

  • username_count - The number of usernames that are associated with the offense.

  • source_address_ids - Array of numbers -The source address IDs that are associated with the offense.

  • local_destination_address_ids - Array of numbers - The local destination address IDs that are associated with the offense.

  • domain_id - Number - Optional. ID of associated domain if the offense is associated with a single domain.

Table 190: Offense Type Codes

Code

Offense Type

0

Source IP

1

Destination IP

2

Event Name

3

Username

4

Source MAC Address

5

Destination MAC Address

6

Log Source

7

Hostname

8

Source Port

9

Destination Port

10

Source IPv6

11

Destination IPv6

12

Source ASN

13

Destination ASN

14

Rule

15

App Id

18

Scheduled Search

Response Sample

[{"credibility": 42, "source_address_ids": [42], "remote_destination_count": 42, "local_destination_address_ids": [42], "assigned_to": "String", "local_destination_count": 42, "source_count": 42, "start_time": 42, "id": 42, "destination_networks": ["String"], "inactive": true, "protected": true, "policy_category_count": 42, "description": "String", "category_count": 42, "domain_id": 42, "relevance": 42, "device_count": 42, "security_category_count": 42, "flow_count": 42, "event_count": 42, "offense_source": "String", "status": "String <one of: OPEN, HIDDEN, CLOSED>", "magnitude": 42, "severity": 42, "username_count": 42, "closing_user": "String", "follow_up": true, "closing_reason_id": 42, "close_time": 42, "source_network": "String", "last_updated_time": 42, "categories": ["String"], "offense_type": 42}]

GET /siem/offenses/{offense_id} DEPRECATED

Retrieve an offense structure that describes properties of an offense

Table 191: GET /siem/offenses/{offense_id} Resource Details

MIME Type

application/json

Table 192: GET /siem/offenses/{offense_id} Request Parameter Details

Parameter

Type

Optionality

Data Type

MIME Type

Description

offense_id

path

Required

Number (Integer)

text/plain

Required - The offense ID.

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 193: GET /siem/offenses/{offense_id} Response Codes

HTTP Response Code

Unique Code

Description

200

 

The offense was retrieved.

404

1002

No offense was found for the provided offense_id.

422

1005

A request parameter is not valid.

500

1020

An error occurred while the offense was being retrieved.

Response Description

An Offense object. An Offense object contains the following fields:

  • id - Number - The ID of the offense.

  • description - String - The description of the offense.

  • assigned_to - String - The user the offense is assigned to.

  • categories - Array of strings - Event categories that are associated with the offense.

  • category_count - Number - The number of event categories that are associated with the offense.

  • policy_category_count - Number - The number of policy event categories that are associated with the offense.

  • security_category_count - Number - The number of security event categories that are associated with the offense.

  • close_time - Number - The number of milliseconds since epoch when the offense was closed.

  • closing_user - String - The user that closed the offense.

  • closing_reason_id - Number - The ID of the offense closing reason. The reason the offense was closed.

  • credibility - Number - The credibility of the offense.

  • relevance - Number - The relevance of the offense.

  • severity - Number - The severity of the offense.

  • magnitude - Number - The magnitude of the offense.

  • destination_networks - Array of strings - The destination networks that are associated with the offense.

  • source_network - String - The source network that is associated with the offense.

  • device_count - Number - The number of devices that are associated with the offense.

  • event_count - Number - The number of events that are associated with the offense.

  • flow_count - Number - The number of flows that are associated with the offense.

  • inactive - Boolean - True if the offense is inactive.

  • last_updated_time - Number - The number of milliseconds since epoch when the offense was last updated.

  • local_destination_count - Number - The number of local destinations that are associated with the offense.

  • offense_source - String - The source of the offense.

  • offense_type - Number - A number that represents the offense type. See the Offense Type Codes table for the code to offense type mapping.

  • protected - Boolean - True if the offense is protected.

  • follow_up - Boolean - True if the offense is marked for follow up.

  • remote_destination_count - Number - The number of remote destinations that are associated wit the offense.

  • source_count - Number - The number of sources that are associated with the offense.

  • start_time - Number - The number of milliseconds since epoch when the offense was started.

  • status - String - The status of the offense. One of "OPEN", "HIDDEN", or "CLOSED".

  • username_count - The number of usernames that are associated with the offense.

  • source_address_ids - Array of numbers -The source address IDs that are associated with the offense.

  • local_destination_address_ids - Array of numbers - The local destination address IDs that are associated with the offense.

  • domain_id - Number - Optional. ID of associated domain if the offense is associated with a single domain.

Table 194: Offense Type Codes

Code

Offense Type

0

Source IP

1

Destination IP

2

Event Name

3

Username

4

Source MAC Address

5

Destination MAC Address

6

Log Source

7

Hostname

8

Source Port

9

Destination Port

10

Source IPv6

11

Destination IPv6

12

Source ASN

13

Destination ASN

14

Rule

15

App Id

18

Scheduled Search

Response Sample

{ "assigned_to": "String", "categories": [ "String" ], "category_count": 42, "close_time": 42, "closing_reason_id": 42, "closing_user": "String", "credibility": 42, "description": "String", "destination_networks": [ "String" ], "device_count": 42, "domain_id": 42, "event_count": 42, "flow_count": 42, "follow_up": true, "id": 42, "inactive": true, "last_updated_time": 42, "local_destination_address_ids": [ 42 ], "local_destination_count": 42, "magnitude": 42, "offense_source": "String", "offense_type": 42, "policy_category_count": 42, "protected": true, "relevance": 42, "remote_destination_count": 42, "security_category_count": 42, "severity": 42, "source_address_ids": [ 42 ], "source_count": 42, "source_network": "String", "start_time": 42, "status": "String <one of: OPEN, HIDDEN, CLOSED>", "username_count": 42 }

POST /siem/offenses/{offense_id} DEPRECATED

Update an offense.

Table 195: POST /siem/offenses/{offense_id} Resource Details

MIME Type

application/json

Table 196: POST /siem/offenses/{offense_id} Request Parameter Details

Parameter

Type

Optionality

Data Type

MIME Type

Description

offense_id

path

Required

Number (Integer)

text/plain

Required - The ID of the offense to update.

protected

query

Optional

Boolean

text/plain

Optional - Set to true to protect the offense.

follow_up

query

Optional

Boolean

text/plain

Optional - Set to true to set the follow up flag on the offense.

status

query

Optional

String

text/plain

Optional - The new status for the offense. Set to one of: OPEN, HIDDEN, CLOSED. When the status of an offense is being set to CLOSED, a valid closing_reason_id must be provided. To hide an offense, use the HIDDEN status. To show a previously hidden offense, use the OPEN status.

closing_reason_id

query

Optional

Number (Integer)

text/plain

Optional - The ID of a closing reason. You must provide a valid closing_reason_id when you close an offense.

assigned_to

query

Optional

String

text/plain

Optional - A user to assign the offense to.

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: POST /siem/offenses/{offense_id} Response Codes

HTTP Response Code

Unique Code

Description

200

 

The offense was updated.

403

1009

User does not have the required capability to assign an offense.

404

1002

No offense was found for the provided offense_id.

409

1008

Request cannot be completed due to the state of the offense.

422

1005

A request parameter is not valid.

500

1020

An error occurred while the offense was being updated.

Response Description

An updated Offense object. An Offense object contains the following fields:

  • id - Number - The ID of the offense.

  • description - String - The description of the offense.

  • assigned_to - String - The user the offense is assigned to.

  • categories - Array of strings - Event categories that are associated with the offense.

  • category_count - Number - The number of event categories that are associated with the offense.

  • policy_category_count - Number - The number of policy event categories that are associated with the offense.

  • security_category_count - Number - The number of security event categories that are associated with the offense.

  • close_time - Number - The number of milliseconds since epoch when the offense was closed.

  • closing_user - String - The user that closed the offense.

  • closing_reason_id - Number - The ID of the offense closing reason. The reason the offense was closed.

  • credibility - Number - The credibility of the offense.

  • relevance - Number - The relevance of the offense.

  • severity - Number - The severity of the offense.

  • magnitude - Number - The magnitude of the offense.

  • destination_networks - Array of strings - The destination networks that are associated with the offense.

  • source_network - String - The source network that is associated with the offense.

  • device_count - Number - The number of devices that are associated with the offense.

  • event_count - Number - The number of events that are associated with the offense.

  • flow_count - Number - The number of flows that are associated with the offense.

  • inactive - Boolean - True if the offense is inactive.

  • last_updated_time - Number - The number of milliseconds since epoch when the offense was last updated.

  • local_destination_count - Number - The number of local destinations that are associated with the offense.

  • offense_source - String - The source of the offense.

  • offense_type - Number - A number that represents the offense type. See the Offense Type Codes table for the code to offense type mapping.

  • protected - Boolean - True if the offense is protected.

  • follow_up - Boolean - True if the offense is marked for follow up.

  • remote_destination_count - Number - The number of remote destinations that are associated wit the offense.

  • source_count - Number - The number of sources that are associated with the offense.

  • start_time - Number - The number of milliseconds since epoch when the offense was started.

  • status - String - The status of the offense. One of "OPEN", "HIDDEN", or "CLOSED".

  • username_count - The number of usernames that are associated with the offense.

  • source_address_ids - Array of numbers -The source address IDs that are associated with the offense.

  • local_destination_address_ids - Array of numbers - The local destination address IDs that are associated with the offense.

  • domain_id - Number - Optional. ID of associated domain if the offense is associated with a single domain.

Table 198: Offense Type Codes

Code

Offense Type

0

Source IP

1

Destination IP

2

Event Name

3

Username

4

Source MAC Address

5

Destination MAC Address

6

Log Source

7

Hostname

8

Source Port

9

Destination Port

10

Source IPv6

11

Destination IPv6

12

Source ASN

13

Destination ASN

14

Rule

15

App Id

18

Scheduled Search

Response Sample

{ "assigned_to": "String", "categories": [ "String" ], "category_count": 42, "close_time": 42, "closing_reason_id": 42, "closing_user": "String", "credibility": 42, "description": "String", "destination_networks": [ "String" ], "device_count": 42, "domain_id": 42, "event_count": 42, "flow_count": 42, "follow_up": true, "id": 42, "inactive": true, "last_updated_time": 42, "local_destination_address_ids": [ 42 ], "local_destination_count": 42, "magnitude": 42, "offense_source": "String", "offense_type": 42, "policy_category_count": 42, "protected": true, "relevance": 42, "remote_destination_count": 42, "security_category_count": 42, "severity": 42, "source_address_ids": [ 42 ], "source_count": 42, "source_network": "String", "start_time": 42, "status": "String <one of: OPEN, HIDDEN, CLOSED>", "username_count": 42 }

GET /siem/offenses/{offense_id}/notes DEPRECATED

Retrieve a list of notes for an offense.

Table 199: GET /siem/offenses/{offense_id}/notes Resource Details

MIME Type

application/json

Table 200: GET /siem/offenses/{offense_id}/notes Request Parameter Details

Parameter

Type

Optionality

Data Type

MIME Type

Description

offense_id

path

Required

Number (Integer)

text/plain

Required - The offense ID to retrieve the notes 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.

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 201: GET /siem/offenses/{offense_id}/notes Response Codes

HTTP Response Code

Unique Code

Description

200

 

The note list was retrieved.

404

1002

No offense was found for the provided offense_id.

422

1005

A request parameter is not valid.

500

1020

An error occurred while the note list was being retrieved.

Response Description

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

  • id - Number - The ID of the note.

  • create_time - Number - The number of milliseconds since epoch when the note was created.

  • username - String - The user or authorized service that created the note.

  • note_text - String - The note text.

Response Sample

[ { "create_time": 42, "id": 42, "note_text": "String", "username": "String" } ]

POST /siem/offenses/{offense_id}/notes DEPRECATED

Create a note on an offense.

Table 202: POST /siem/offenses/{offense_id}/notes Resource Details

MIME Type

application/json

Table 203: POST /siem/offenses/{offense_id}/notes Request Parameter Details

Parameter

Type

Optionality

Data Type

MIME Type

Description

offense_id

path

Required

Number (Integer)

text/plain

Required - The offense ID to add the note to.

note_text

query

Required

String

text/plain

Required - The note text.

fields

query

Optional

String

text/plain

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

Table 204: POST /siem/offenses/{offense_id}/notes Response Codes

HTTP Response Code

Unique Code

Description

201

 

The note was created.

404

1002

No offense was found for the provided offense_id.

422

1005

A request parameter is not valid.

500

1020

An error occurred while attempting to create the note.

Response Description

The Note object that was created. A Note object contains the following fields:

  • id - Number - The ID of the note.

  • create_time - Number - The number of milliseconds since epoch when the note was created.

  • username - String - The user or authorized service that created the note.

  • note_text - String - The note text.

Response Sample

{ "create_time": 42, "id": 42, "note_text": "String", "username": "String" }

GET /siem/offenses/{offense_id}/notes/{note_id} DEPRECATED

Retrieve a note for an offense.

Table 205: GET /siem/offenses/{offense_id}/notes/{note_id} Resource Details

MIME Type

application/json

Table 206: GET /siem/offenses/{offense_id}/notes/{note_id} Request Parameter Details

Parameter

Type

Optionality

Data Type

MIME Type

Description

offense_id

path

Required

Number (Integer)

text/plain

Required - The offense ID to retrieve the note from.

note_id

path

Required

Number (Integer)

text/plain

Required - The note ID.

fields

query

Optional

String

text/plain

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

Table 207: GET /siem/offenses/{offense_id}/notes/{note_id} Response Codes

HTTP Response Code

Unique Code

Description

200

 

The note was retrieved.

404

1002

No offense was found for the provided offense_id.

404

1003

No note was found for the provided note_id.

422

1005

A request parameter is not valid.

500

1020

An error occurred while attempting to retrieve the note.

Response Description

The Note object for the note ID. A Note object contains the following fields:

  • id - Number - The ID of the note.

  • create_time - Number - The number of milliseconds since epoch when the note was created.

  • username - String - The user or authorized service that created the note.

  • note_text - String - The note text.

Response Sample

{ "create_time": 42, "id": 42, "note_text": "String", "username": "String" }

GET /siem/source_addresses DEPRECATED

Retrieve a list offense source addresses currently in the system.

Table 208: GET /siem/source_addresses Resource Details

MIME Type

application/json

Table 209: GET /siem/source_addresses 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 210: GET /siem/source_addresses Response Codes

HTTP Response Code

Unique Code

Description

200

 

The source address list was retrieved.

422

1005

A request parameter is not valid.

422

1010

The filter parameter is not valid.

500

1020

An error occurred while the source address list was being retrieved.

Response Description

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

  • id - Number - The ID of the source.

  • source_ip - String - The IP address.

  • magnitude - Number - The magnitude of the source address.

  • network - String - The network of the source address.

  • offense_ids - Array of Numbers - List of offense IDs the source is part of.

  • local_destination_address_ids - Array of Numbers - List of local destination address IDs associated with the source address.

  • event_flow_count - Number - The number of events and flows that are associated with the source.

  • first_event_flow_seen - Number - The number of milliseconds since epoch when the first event or flow was seen.

  • last_event_flow_seen - Number - The number of milliseconds since epoch when the last event or flow was seen.

  • domain_id - Number - The ID of associated domain.

Response Sample

[ { "domain_id": 42, "event_flow_count": 42, "first_event_flow_seen": 42, "id": 42, "last_event_flow_seen": 42, "local_destination_address_ids": [ 42 ], "magnitude": 42, "network": "String", "offense_ids": [ 42 ], "source_ip": "String" } ]

GET /siem/source_addresses/{source_address_id} DEPRECATED

Retrieve an offense source address.

Table 211: GET /siem/source_addresses/{source_address_id} Resource Details

MIME Type

application/json

Table 212: GET /siem/source_addresses/{source_address_id} Request Parameter Details

Parameter

Type

Optionality

Data Type

MIME Type

Description

source_address_id

path

Required

Number (Integer)

text/plain

Required - The ID of the source address 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 213: GET /siem/source_addresses/{source_address_id} Response Codes

HTTP Response Code

Unique Code

Description

200

 

The source address was retrieved.

404

1002

No source address was found for the provided source_address_id.

422

1005

A request parameter is not valid.

500

1020

An error occurred while the source address was being retrieved.

Response Description

A source address object. A source address object contains the following fields:

  • id - Number - The ID of the source.

  • source_ip - String - The IP address.

  • magnitude - Number - The magnitude of the source address.

  • network - String - The network of the source address.

  • offense_ids - Array of Numbers - List of offense IDs the source is part of.

  • local_destination_address_ids - Array of Numbers - List of local destination address IDs associated with the source address.

  • event_flow_count - Number - The number of events and flows that are associated with the source.

  • first_event_flow_seen - Number - The number of milliseconds since epoch when the first event or flow was seen.

  • last_event_flow_seen - Number - The number of milliseconds since epoch when the last event or flow was seen.

  • domain_id - Number - The ID of associated domain.

Response Sample

{ "domain_id": 42, "event_flow_count": 42, "first_event_flow_seen": 42, "id": 42, "last_event_flow_seen": 42, "local_destination_address_ids": [ 42 ], "magnitude": 42, "network": "String", "offense_ids": [ 42 ], "source_ip": "String" }