×
 
 
  •  
$helper.renderConfluenceMacro('{bmc-global-announcement:$space.key}')

Unsupported content

 

This version of the product has reached end of support. The documentation is available for your convenience. However, you must be logged in to access it. You will not be able to leave comments.
TrueSight Vulnerability Management 3.1

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

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

NameLocated inDescriptionSchema
usernamebody

Name of the user who is logging in

string
passwordbodyPassword of the user who is logging in
string

Responses

Code/ MessageDescriptionSchema
ClientID

Successful: A unique Id required for each client to access the application

string
cookiesSuccessful: Session cookies required for each client to access the applicationstring
X-XSRF-TOKENSuccessful: A unique CSRF token required for each client to access the applicationstring
{"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 foundFailure: 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

NameLocated inDescriptionSchema
ClientIdheaderA unique Id required for each client to access the applicationstring
X-XSRF-TOKENheaderCSRF tokenstring

Responses

CodeDescriptionSchema
200

Created: New exception successfully added

[ ExceptionDefinition
]

400Bad request
500Internal server error: Unexpected exception occurred

PUT /exceptions/{exceptionId}

Description

Updates an exception definition.

Parameters

NameLocated inDescriptionSchema
ClientIdheaderA unique Id required for each client to access the applicationstring
X-XSRF-TOKENheaderCSRF tokenstring
exceptionIdpathUnique exception Idstring

Responses

CodeDescriptionSchema
200

Successful operation: Exception updated.

ExceptionDefinition
400Bad request
500Internal server error: Unexpected exception occurred

DELETE /exceptions/{exceptionId}

Description

Deletes an exception definition.

Parameters

NameLocated inDescriptionSchema
ClientIdheaderA unique Id required for each client to access the applicationstring
X-XSRF-TOKENheaderCSRF tokenstring
exceptionIdpathUnique exception Idstring

Responses

CodeDescriptionSchema
200

Successful operation: Exception deleted.

ExceptionDefinition
400Bad request
500Internal server error: Unexpected exception occurred

POST /exceptions/search

Description

Searches for an exception definition.

Parameters

NameLocated inDescriptionSchema
ClientIdheaderA unique Id required for each client to access the applicationstring
X-XSRF-TOKENheaderCSRF tokenstring

Responses

CodeDescriptionSchema
200

Successful operation: Exception retrieved.

[
ExceptionDefinition
]

400Bad request
500Internal server error: Unexpected exception occurred

POST /exceptions/upload/{securityGroupId}

Description

Imports an exception definition.

Parameters

NameLocated inDescriptionSchema
ClientIdheaderA unique Id required for each client to access the applicationstring
X-XSRF-TOKENheaderCSRF tokenstring
securityGroupIdpathSecurity group Id of logged in userstring

Responses

CodeDescriptionSchema
200

Successful operation: Exception imported.

string
400Bad request
500Internal server error: Unexpected exception occurred

POST /exceptions/export

Description

Exports an exception definition.

Parameters

NameLocated inDescriptionSchema
ClientIdheaderA unique Id required for each client to access the applicationstring
X-XSRF-TOKENheaderCSRF tokenstring

Responses

CodeDescriptionSchema
200

Successful operation: Exception exported.

File (in byte stream)
400Bad request
500Internal 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

NameLocated inDescriptionSchema
ClientIdheaderA unique Id required for each client to access the applicationstring
X-XSRF-TOKENheaderCSRF tokenstring

Responses

CodeDescriptionSchema
200

Successful operation: Retrieved exception.

SearchTagResult
400Bad request
500Internal 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

NameLocated inDescriptionSchema
ClientIdheaderA unique Id required for each client to access the applicationstring
X-XSRF-TOKENheaderCSRF tokenstring

Responses

CodeDescriptionSchema
200

Successful operation: Retrieved.

ExceptionSmartFilter
400Bad request
500Internal server error: Unexpected exception occurred

POST /assets/search

Description

Searches for the assets associated with specific set of vulnerabilities.

Parameters

NameLocated inDescriptionSchema
ClientIdheaderA unique Id required for each client to access the applicationstring
X-XSRF-TOKENheaderCSRF tokenstring

Responses

CodeDescriptionSchema
200

Successful operation: Retrieved assets.

AssetSearchResult
400Bad request
500Internal 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

NameLocated inDescriptionSchema
ClientIdheaderA unique Id required for each client to access the applicationstring
X-XSRF-TOKENheaderCSRF tokenstring
CookieheaderConcatenation of XSRF token and JSESSIONID value from login sessionstring
Content-Typeheader

Content type to be used for submitting forms that contain files. Valid value is multipart/form-data

string
selectedVendorbodyType of vulnerability management system data that you want to import. Valid values are Qualys, Rapid7, and Nessus.string
severitiesTobeConsideredbody

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
osTobeConsideredbody

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
cidrsTobeConsideredbody

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
filenamebody

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

CodeDescriptionSchema
200

Successful operation

string
400Bad request
500Internal 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

NameLocated inDescriptionSchema
ClientIdheaderA unique Id required for each client to access the applicationstring
X-XSRF-TOKENheaderCSRF tokenstring
CookieheaderConcatenation of XSRF token and JSESSIONID value from login sessionstring
Content-Typeheader

Content type to be used for submitting forms that contains data in JSON format. Valid value is application/json.

string
keybodyName of the tag keystring
resourceTypebodyResource type for which tag is being created. Valid value is assets.string


Responses

CodeDescriptionSchema
200

Successful operation

string
400Bad request
500Internal 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

NameLocated inDescriptionSchema
ClientIdheaderA unique Id required for each client to access the applicationstring
X-XSRF-TOKENheaderCSRF tokenstring
CookieheaderConcatenation of XSRF token and JSESSIONID value from login sessionstring
Content-Typeheader

Content type to be used for submitting forms that contain data in JSON format. Valid value is application/json.

string
dnsbodyDNS of the assetstring
key/valuebodyKey/Value pair. For example, "tags":[{"key":"BU","values":[{"value":"Facilities"}]}]JSON


Responses

CodeDescriptionSchema
200

Successful operation

string
400Bad request
500Internal 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

NameLocated inDescriptionSchema
ClientIdheaderA unique Id required for each client to access the applicationstring
X-XSRF-TOKENheaderCSRF tokenstring
CookieheaderConcatenation of XSRF token and JSESSIONID value from login sessionstring
Content-Typeheader

Content type to be used for submitting forms that contain files. Valid value is multipart/form-data

string


Responses

CodeDescriptionSchema
200

Successful operation

string
400Bad request
500Internal 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

NameLocated inDescriptionSchema
ClientIdheaderA unique Id required for each client to access the applicationstring
X-XSRF-TOKENheaderCSRF tokenstring
CookieheaderConcatenation of XSRF token and JSESSIONID value from login sessionstring
Content-Typeheader

Content type to be used for submitting forms that contain files. Valid value is multipart/form-data

string
filenamebodyName of the CSV file to be importedstring
files[]bodyDirectory path in which the CSV file is locatedFile

Responses

CodeDescriptionSchema
200

Successful operation

string
400Bad request
500Internal server error: Unexpected exception occurred

Object definitions

ObjectSchema

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

}

Was this page helpful? Yes No Submitting... Thank you
Last modified by Sulekha Gulati on Jan 03, 2022

Comments

Log in or register to comment.

Viewing license usage
Troubleshooting
© Copyright 2013 - 2019 BMC Software, Inc.
Legal notices

Powered by Atlassian Confluence and Scroll Viewport

© Copyright 2005-2024 BMC Software, Inc. Use of this site signifies your acceptance of BMC’s Terms of Use . BMC, the BMC logo, and other BMC marks are assets of BMC Software, Inc. These trademarks are registered and may be registered in the U.S. and in other countries.