Share this page

# Add vulnerability issues to ALM Octane

This topic describes how you use the vulnerabilities resource to send security vulnerability issues to the ALM Octane server.

In this topic:

## Overview

The vulnerabilities synchronous resource sends security vulnerability analysis to the ALM Octane server.

Using this resource, you can add or update vulnerability issues in ALM Octane 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 into ALM Octane. 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 Authenticating.

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, ALM Octane 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, ALM Octane creates a new vulnerability issue. If the remote ID exists, ALM Octane updates the existing vulnerability issue.

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 ALM Octane REST API syntax. Here is an 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 ALM Octane 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, ALM Octane creates a new vulnerability issue (POST). If you supply an existing remote ID, ALM Octane updates an existing vulnerability issue (PUT). 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. ALM Octane uses this field to identify the user. Optional.
state | A reference field to the list_node collection for states. Can also be editing in the ALM Octane 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 editing in the ALM Octane 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 would like to display in the vulnerability description in the ALM Octane UI.
category | Free text indicating the vulnerability category, such as for a group by categories.

Back to top

See also:

- Set up API access

- Track security vulnerabilities

https://admhelp.microfocus.com ALM Octane 8942
Tips to improve your search results... ValueEdge & ALM Octane Help Center ValueEdge ALM Octane Help 16.0.100-16.0.400 All View Local Help Center View Online Help Center back Go back in browser history forward Go forward in browser history Remove search highlights next topic Go to next topic previous topic Go to previous topic Print the current topic Version: