Share this page
Add vulnerability issues to ALM Octane
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 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, 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.
Note: If you deactivate a Fortify value in ALM Octane Settings, 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 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:
|
| 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:
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:
|
| 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:
|
| 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:
|
| 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. |
See also:
