Share this page

# Add vulnerability issues

Use the vulnerabilities resource to send security vulnerability issues.

In this topic:

## Overview

The vulnerabilities synchronous resource sends security vulnerability analysis to the OpenText Software Delivery Management 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.

Back to top

## 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, the remote ID defined in the external static code analysis tool is checked, 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.

Back to top

## 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

Back to top

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

Back to top

See also:

- API access

- Track security vulnerabilities

https://admhelp.microfocus.com Software Delivery Management 8942
Tips to improve your search results... OpenText™ Software Delivery Management Help Center OpenText™ Software Delivery Management Help 26.1 All View Local Help Center View Online Help Center Version: