Using REST API

The REST API is intended to be used by a client script or program to interact with and control the TrueSight Vulnerability Management application from a remote machine. You can use the API to perform the following tasks:

Manage exceptions
Tag assets and vulnerabilities
Import scans

The aim of the API is to enable you to perform most tasks that you can currently do through the GUI.

The API follows the REST architectural style, so resources, HTTP verbs, and status codes are used. JavaScript Object Notation (JSON) is used to represent data structures in request and response bodies. The endpoints provided by the API are specified using the Swagger specification language. All endpoints (except the Login API) use the OAuth 2.0 protocol for authentication.

Calling the API
Login API
Exception Management API
Import Scan API
Tags API
Update Tags API
Import Tags API
Vulnerability Asset Tagging API
Object definitions

Calling the API

Calls to the API can be made from any scripting or programming language that supports HTTPS. Whatever client language or tool you use to call the REST API, it is recommended you read the related documentation first to see how to construct valid requests and to handle responses.

Requests to all endpoints in the REST API must be on behalf of a TrueSight Vulnerability Management user. Before processing a request, the API authenticates the request to determine the user. After successful authentication of a user, endpoints check whether the user has permission to perform the requested action. Users must be granted the same rights as if they were attempting the action through the equivalent user interface or command line tool. If the user lacks the required right, a 403 Forbidden status code is returned by the endpoint.

Login API

The base URL for the Login API is:

https://<TSVMserverName>:<portNumber>/tsvm/api/login

Description

Logs in a user, to verify access is allowed to the system and to identify which resources can be used subsequently.

Parameters

Name	Located in	Description	Schema
username	body	Name of the user who is logging in	string
password	body	Password of the user who is logging in	string

Responses

Code/ Message	Description	Schema
ClientID	Successful: A unique Id required for each client to access the application	string
cookies	Successful: Session cookies required for each client to access the application	string
X-XSRF-TOKEN	Successful: A unique CSRF token required for each client to access the application	string
{"errorCode":"BAD_CREDENTIALS_AUTHENTICATION_FAILURE","taskId":null, "isAuthenticated":false,"savedRequestUri":null,"clientId":nul	Failure: Bad credentials
{"errorCode":"VOID_ERROR_CODE","taskId":null,"isAuthenticated":false, "savedRequestUri":null,"clientId":null,"errorMessage":"Connector did not return response within timeout."}	Failure: Timeout
Site not found	Failure: endpoint manager not found

Exception Management API

The base URL for the Exception Management API is:

https://<TSVMserverName>:<portNumber>/tsvm/api/v1

POST /exceptions

Description

Creates a new exception definition.

Parameters

Name	Located in	Description	Schema
ClientId	header	A unique Id required for each client to access the application	string
X-XSRF-TOKEN	header	CSRF token	string

Responses

Code	Description	Schema
200	Created: New exception successfully added	[ ExceptionDefinition]
400	Bad request
500	Internal server error: Unexpected exception occurred

PUT /exceptions/{exceptionId}

Description

Updates an exception definition.

Parameters

Name	Located in	Description	Schema
ClientId	header	A unique Id required for each client to access the application	string
X-XSRF-TOKEN	header	CSRF token	string
exceptionId	path	Unique exception Id	string

Responses

Code	Description	Schema
200	Successful operation: Exception updated.	ExceptionDefinition
400	Bad request
500	Internal server error: Unexpected exception occurred

DELETE /exceptions/{exceptionId}

Description

Deletes an exception definition.

Parameters

Name	Located in	Description	Schema
ClientId	header	A unique Id required for each client to access the application	string
X-XSRF-TOKEN	header	CSRF token	string
exceptionId	path	Unique exception Id	string

Responses

Code	Description	Schema
200	Successful operation: Exception deleted.	ExceptionDefinition
400	Bad request
500	Internal server error: Unexpected exception occurred

POST /exceptions/search

Description

Searches for an exception definition.

Parameters

Name	Located in	Description	Schema
ClientId	header	A unique Id required for each client to access the application	string
X-XSRF-TOKEN	header	CSRF token	string

Responses

Code	Description	Schema
200	Successful operation: Exception retrieved.	[ ExceptionDefinition]
400	Bad request
500	Internal server error: Unexpected exception occurred

POST /exceptions/upload/{securityGroupId}

Description

Imports an exception definition.

Parameters

Name	Located in	Description	Schema
ClientId	header	A unique Id required for each client to access the application	string
X-XSRF-TOKEN	header	CSRF token	string
securityGroupId	path	Security group Id of logged in user	string

Responses

Code	Description	Schema
200	Successful operation: Exception imported.	string
400	Bad request
500	Internal server error: Unexpected exception occurred

POST /exceptions/export

Description

Exports an exception definition.

Parameters

Name	Located in	Description	Schema
ClientId	header	A unique Id required for each client to access the application	string
X-XSRF-TOKEN	header	CSRF token	string

Responses

Code	Description	Schema
200	Successful operation: Exception exported.	File (in byte stream)
400	Bad request
500	Internal server error: Unexpected exception occurred

POST /exceptions/assets/search_allowed_tags

Description

Searches for tags required while creating exception based on the asset tags.

Parameters

Name	Located in	Description	Schema
ClientId	header	A unique Id required for each client to access the application	string
X-XSRF-TOKEN	header	CSRF token	string

Responses

Code	Description	Schema
200	Successful operation: Retrieved exception.	SearchTagResult
400	Bad request
500	Internal server error: Unexpected exception occurred

POST /exceptions/smart_filter

Description

Retrieves the smart filter related metadata. It mainly takes care of retrieving smart filter values for CVE IDs and assets.

Parameters

Name	Located in	Description	Schema
ClientId	header	A unique Id required for each client to access the application	string
X-XSRF-TOKEN	header	CSRF token	string

Responses

Code	Description	Schema
200	Successful operation: Retrieved.	ExceptionSmartFilter
400	Bad request
500	Internal server error: Unexpected exception occurred

POST /assets/search

Description

Searches for the assets associated with specific set of vulnerabilities.

Parameters

Name	Located in	Description	Schema
ClientId	header	A unique Id required for each client to access the application	string
X-XSRF-TOKEN	header	CSRF token	string

Responses

Code	Description	Schema
200	Successful operation: Retrieved assets.	AssetSearchResult
400	Bad request
500	Internal server error: Unexpected exception occurred

Import Scan API

The base URL for the Import Scan API is:

https://<TSVMserverName>:<portNumber>/tsvm/api

POST /vulnerability/importScan

Description

Imports the results of scans performed by vulnerability management systems such as Qualys, Nessus, or Rapid7.

Parameters

Name	Located in	Description	Schema
ClientId	header	A unique Id required for each client to access the application	string
X-XSRF-TOKEN	header	CSRF token	string
Cookie	header	Concatenation of XSRF token and JSESSIONID value from login session	string
Content-Type	header	Content type to be used for submitting forms that contain files. Valid value is multipart/form-data	string
selectedVendor	body	Type of vulnerability management system data that you want to import. Valid values are Qualys, Rapid7, and Nessus.	string
severitiesTobeConsidered	body	A comma-separated list of severity levels of vulnerabilities for which to import the scan results. Qualys, Nessus, and Rapid7 use different scoring for severity levels. Qualys uses scores of 1-5. Nessus uses scores of 0-4. Rapid7 uses scores of 1-10. To maintain consistency, BMC increases the Nessus severity levels by one (so they become 1-5) and maps the ten Rapid7 severity levels to five levels.	string
osTobeConsidered	body	Comma-separated list of operating systems data that you want to import. Valid values are Windows, Linux, and Others. If you are importing data for networking devices, be sure to specify Others. Networking devices are not always associated with an operating system. If you are importing data for SuSE devices, be sure to specify both Linux and Others.	string
cidrsTobeConsidered	body	IP addresses in the Classless Inter-Domain Routing (CIDR) format, for which you want to import data. From the scan file, data only for the servers that belong to the specified IP address range is imported. Default value of this option is 0.0.0.0/0, which imports data for all the assets from the scan file. You can specify the following types of values: Single IP address (CIDR format). Example: 168.19.13.12/24 Comma-separated multiple IP addresses (CIDR format). Example: 168.19.13.12/24,10.25.24.12/12 A combination of the above formats: Example: 168.19.13.12/24, 168.19.13.12/32,10.25.24.12/12	string
filename	body	Name of the scan file to be imported. Note: Ensure that you use the filename as the parameter name followed by content of the file and file type.	string

Responses

Code	Description	Schema
200	Successful operation	string
400	Bad request
500	Internal server error: Unexpected exception occurred

Tags API

The base URL for the Tags API is:

https://<TSVMserverName>:<portNumber>/tsvm/api/

POST /tagging/v1/tags

Description

Adds a tag key to the system.

Parameters

Name	Located in	Description	Schema
ClientId	header	A unique Id required for each client to access the application	string
X-XSRF-TOKEN	header	CSRF token	string
Cookie	header	Concatenation of XSRF token and JSESSIONID value from login session	string
Content-Type	header	Content type to be used for submitting forms that contains data in JSON format. Valid value is application/json.	string
key	body	Name of the tag key	string
resourceType	body	Resource type for which tag is being created. Valid value is assets.	string

Responses

Code	Description	Schema
200	Successful operation	string
400	Bad request
500	Internal server error: Unexpected exception occurred

Update Tags API

The base URL for the Update Tags API is:

https://<TSVMserverName>:<portNumber>/tsvm/api/

POST /tagging/v1/resources/updateTags

Description

Assigns values to an existing tag key.

Parameters

Name	Located in	Description	Schema
ClientId	header	A unique Id required for each client to access the application	string
X-XSRF-TOKEN	header	CSRF token	string
Cookie	header	Concatenation of XSRF token and JSESSIONID value from login session	string
Content-Type	header	Content type to be used for submitting forms that contain data in JSON format. Valid value is application/json.	string
dns	body	DNS of the asset	string
key/value	body	Key/Value pair. For example, "tags":[{"key":"BU","values":[{"value":"Facilities"}]}]	JSON

Responses

Code	Description	Schema
200	Successful operation	string
400	Bad request
500	Internal server error: Unexpected exception occurred

Import Tags API

The base URL for the Import Tags API is:

https://<TSVMserverName>:<portNumber>/tsvm/api/

POST /tagging/v1/assets/importTags

Description

Imports tags from a CSV file.

Note: When using this API, attach the formatted tag file.

Parameters

Name	Located in	Description	Schema
ClientId	header	A unique Id required for each client to access the application	string
X-XSRF-TOKEN	header	CSRF token	string
Cookie	header	Concatenation of XSRF token and JSESSIONID value from login session	string
Content-Type	header	Content type to be used for submitting forms that contain files. Valid value is multipart/form-data	string

Responses

Code	Description	Schema
200	Successful operation	string
400	Bad request
500	Internal server error: Unexpected exception occurred

Vulnerability Asset Tagging API

The base URL for the Vulnerability Asset Tagging API is:

https://<TSVMserverName>:<portNumber>/tsvm/api/tagging/v1

POST /vulnerability-asset/importTags

Description

Imports the vulnerability-asset tag CSV file.

Note: When using this API, attach the formatted tag file.

Parameters

Name	Located in	Description	Schema
ClientId	header	A unique Id required for each client to access the application	string
X-XSRF-TOKEN	header	CSRF token	string
Cookie	header	Concatenation of XSRF token and JSESSIONID value from login session	string
Content-Type	header	Content type to be used for submitting forms that contain files. Valid value is multipart/form-data	string
filename	body	Name of the CSV file to be imported	string
files[]	body	Directory path in which the CSV file is located	File

Responses

Code	Description	Schema
200	Successful operation	string
400	Bad request
500	Internal server error: Unexpected exception occurred

Object definitions

Object	Schema
ExceptionDefinition	{ exceptionId: string exceptionName: string exceptionReason: string owner: string ticketId: string startDate: string endDate: string status: string serviceContext: ExceptionServiceContext applicableCriteria: [ApplicableCriteria] createdBy: string createdDate: string updatedBy: string updatedDate: string state: string }
ExceptionServiceContextRequest	{ userGroupId: string }
ExceptionServiceContext	{ service: string userGroupId: string vulnerabilityDetails: [VulnerabilityDetails] assetGroupIds: [string] }
VulnerabilityDetails	{ vulnerabilityId: string vulnerabilityName: string referenceIds: [string] }
ApplicableCriteria	{ key: string value: [string] }
ExceptionDefinitionCreateResponse	{ exceptionDefinitions: [ExceptionDefinition] metaData: ExceptionMgmtMetaData }
UpdateExceptionDefinitionResponse	{ exceptionDefinition: ExceptionDefinition }
DeleteExceptionDefinitionResponse	{ exceptionDefinition: ExceptionDefinition }
ExceptionSearchRequestFilter	{ filters: [ExceptionMgmtFilters] parameters: ExceptionParameters sortedColumns: [ExceptionMgmtSortedColumn] pageNumber: integer pageSize: integer }
ExceptionExportRequest	{ filters: [ExceptionMgmtFilters] parameters: ExceptionParameters sortedColumns: [ExceptionMgmtSortedColumn] pageNumber: integer pageSize: integer timeZoneBrowser: string }
ExceptionMgmtFilters	{ name: string value: string isExactMatch: boolean }
ExceptionParameters	{ searchRequest: ExceptionSearchRequest }
ExceptionSearchRequest	{ filter: string pageNumber: integer pageSize: integer sortedOn: string }
ExceptionMgmtSortedColumn	{ columnName: string ascending: string }
ExceptionDefinitionSearchResponse	{ exceptionDefinitions: [ExceptionDefinition] metaData: ExceptionMgmtMetaData }
ExceptionMgmtMetaData	{ total: {} pageNumber: integer pageSize: integer startOffset: integer endOffset: integer }
SearchTagResult	{ oiTags: [OITag] size: integer totalSize: integer pageNumber: integer }
OITag	{ id: string key: string type: string values: [OITagValue] }
OITagValue	{ id: string value: string }
AllowedTagsSearchRequest	{ securityGroupId: [string] }
ExceptionSmartFilter	{ sAsset: [KeyValue] sCVE: [KeyValue] }
KeyValue	{ id: string value: string }
AssetsSearchRequest	{ vulnerabilityId: [string] securityGroupId: [string] pageSize: integer pageNumber: integer }
AssetSearchResult	{ assetList: [KeyValue] }
ErrorResponse	{ errorMessage: string errorCode: string }
ExceptionSuccessResponse	{ success: boolean }
taggingResponse	{ taskId: integer errorCode: string }

Using REST API

Calling the API

Login API

Parameters

Responses

Exception Management API

Description

Parameters

Responses

Description

Responses

Description

Parameters

Responses

Description

Parameters

Responses

Description

Parameters

Responses

Description

Parameters

Responses

Description

Parameters

Responses

Description

Parameters

Responses

Description

Parameters

Responses

Import Scan API

Description

Parameters

Responses

Tags API

Description

Parameters

Responses

Update Tags API

Description

Parameters

Responses

Import Tags API

Description

Parameters

Responses

Vulnerability Asset Tagging API

Description

Parameters

Responses

Object definitions

TrueSight Vulnerability Management 3.1

On this page