Add vulnerability issues

Use the vulnerabilities resource to send security vulnerability issues.

Overview

The vulnerabilities synchronous resource sends security vulnerability analysis to the OpenText Core Software Delivery Platform server.

Using this resource, you can add or update vulnerability issues that were detected about your code using Fortify on Demand and other static code analysis tools.

Vulnerability issues are only associated with the runs of pipelines that have been defined with a Type of Security.

You can set a maximum number of vulnerability issues to inject. For details, see VULNERABILITIES_PER_PIPELINE_RUN_LIMIT in Configuration parameters.

You must log in to the server using the authentication API before using this resource. When authenticating, you must have the same permissions as the predefined CI/CD integration role. For details on authenticating, see Authentication.

Note: Vulnerabilities from before the Security pipeline creation date, or from before it was set as Security type, are not injected.

URI

.../api/shared_spaces/<space_id>/vulnerabilities

Supported HTTP methods

This resource supports only the POST operation, however this special resource can perform PUT operation instead, if it finds a matching pipeline run.

To determine the POST or the PUT, OpenText Core Software Delivery Platform checks the remote ID defined in the external static code analysis tool, and provided in the payload.

If the remote ID supplied in the payload contains a value that does not already exist for a pipeline run, a new vulnerability issue is created. If the remote ID exists, the existing vulnerability issue is updated.

Note: If you deactivate a Fortify value, you cannot then inject this value using REST API.

The request

The request syntax for injecting security vulnerability analysis information is:

POST .../api/shared_spaces/<space_id>/vulnerabilities?instance-id='<instance_id>'&job-ci-id='<job_id>'&build-ci-id='<build_id>'

When POSTing, specify:

A query for identifying the pipeline run.
A request body containing the JSON payload that conforms to the accepted syntax. For details, see The JSON payload in the request body.
The Content-Type header field, set to application/json.
Optionally, the content can be compressed in gzip format. In this case, the Content-Encoding header field must be set to application/gzip.

The following table describes how to identify the corresponding pipeline run in request:

Item	Field
CI server ID	instance-id
Job name, such as Jenkins	job-ci-id
Build ID	build-ci-id

The JSON payload in the request body

The payload in the request body describes:

The pipeline run that you want to update with vulnerability issues.
The vulnerability issues detected by your static code analysis tool.

You can specify more than one issue in the payload.

The payload uses the standard REST API syntax.

Example:

{ "data": [{ 
    "severity": { 
        "type": "list_node", 
        "id": "list_node.severity.low" 
    }, 
    "package": "com.mf.presales.web", 
    "line": 10, 
    "remote_id": "3122", 
    "primary_location_full": "src/test/java/SimpleTest.java",
    "introduced_date": "2020-12-10T12:46:06Z",
    "state": { 
        "type": "list_node", 
        "id": "list_node.issue_state_node.new" 
    }, 
    "tool_type": { 
        "type": "list_node", 
        "id": "list_node.securityTool.fod"
    }, 
    "tool_name": "Fortify", 
    "analysis": { 
        "type": "list_node", 
        "id": "list_node.issue_analysis_node.maybe_an_issue" 
    }, 
    "category": "My category" 
    }] 
}

Use only the fields listed below when preparing the payload.

Tip: Unless indicated otherwise, you can only update these fields using the REST API. Updating most of these fields is not supported using the UI.

Field	Description
severity	A reference field to the list_node collection, indicating the severity for the detected vulnerability issue. Valid values: list_node.severity.low list_node.severity.medium list_node.severity.high list_node.severity.very_high list_node.severity.urgent
package	The name of the Java package.
line	Long integer indicating the line number where a change causing a vulnerability was introduced in the file.
remote_id	The ID as defined in the static code analysis tool. Either a new or existing remote ID: If you supply a non-existing remote ID, a new vulnerability issue (POST) is created. If you supply an existing remote ID, the existing vulnerability issue (PUT) is updated. Mandatory.
primary_location_full	Path to the file that contains the vulnerability issues. Mandatory.
introduced_date	Date at which the vulnerability was detected by the tool.
owner_email	Email of the workspace user responsible for the vulnerability. This field is used to identify the user. Optional.
state	A reference field to the list_node collection for states. Can also be edited in the UI. Valid values: list_node.issue_state_node.new list_node.issue_state_node.existing list_node.issue_state_node.waiting_for_review list_node.issue_state_node.reviewed list_node.issue_state_node.bug_submitted list_node.issue_state_node.not_an_issue list_node.issue_state_node.closed
tool_type	A reference field to the list_node collection for tool types.
tool_name	The name of the tool. Free text string. Valid values: list_node.securityTool.fod
external_link	A URL for the vulnerability issue.
analysis	A reference field to the list_node collection for analysis issues. Can also be edited in the UI. Valid values: list_node.issue_analysis_node.maybe_an_issue list_node.issue_analysis_node.reviewed list_node.issue_state_node.bug_submitted list_node.issue_state_node.not_an_issue
defect	A reference field to the defect collection, indicating the defect associated with the detected vulnerability issue. Can be used if the defect ID is known. Optional.
extended_data	A custom field type containing a set of key-value pairs. Use this field to specify additional fields and values that you want to display in the vulnerability description in the UI.
category	Free text indicating the vulnerability category, such as for a group by categories.