vulnerabilities

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

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.

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/workspaces/<workspace_id>/vulnerabilities?instance-id='<instance_id>'&job-ci-id='<path_to_file>'&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 this syntax.

  • 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": "MyPackage.com",
      "line": 10,
      "remote_id": "<A new or existing remote ID>",
      "primary_location_full": "src/test/java/SimpleTest.java",
      "introduced_date": "2018-06-03T14:06:58Z",
      "owner_email":"TheUser@TheCompany.com",
      "state": {
        "type": "list_node",
        "id": "list_node.issue_state_node.closed"      
       },
      "tool_type": {
        "type": "list_node", 
        "id": "list_node.securityTool.fod"
       },
      "tool_name": "external tool",
      "external_link":"MyURL",
      "analysis": {
         "type": "list_node",
         "id": "list_node.issue_analysis_node.maybe_an_issue"
       },
      "defect": {
         "type":"defect",
         "id":2003
       },
      "extended_data" : {
         "<key>":"<value>",
         "<key>":"<value>"
       },
      "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: