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" }