ATatlassian
Security Information

Submit Vulnerability data

Changed on

Update / Insert Vulnerability data.

Vulnerabilities are identified by their ID, any existing Vulnerability data with the same ID will be replaced if it exists and the updateSequenceNumber of the existing data is less than the incoming data.

Submissions are performed asynchronously. Most updates are available within a short period of time but may take some time during peak load and/or maintenance times. The GET vulnerability endpoint can be used to confirm that data has been stored successfully (if needed).

In the case of multiple Vulnerabilities being submitted in one request, each is validated individually prior to submission. Details of Vulnerabilities that failed submission (if any) are available in the response object.

A maximum of 1000 vulnerabilities can be submitted in one request.

post/rest/security/1.0/bulk

Request

  • Base URL
    https://your-domain.atlassian.net
  • URL
    https://your-domain.atlassian.net/rest/security/1.0/bulk
  • Auth
    OAuth 2
    Authorization code: https://auth.atlassian.com/authorize
    Token URL: https://auth.atlassian.com/oauth/token scopes: write:security:jira

Request body

operationType'NORMAL' | 'SCAN' | 'BACKFILL'

Indicates the operation being performed by the provider system when sending this data. "NORMAL" - Data received during real-time, user-triggered actions (e.g. user closed or updated a vulnerability). "SCAN" - Data sent through some automated process (e.g. some periodically scheduled repository scan). "BACKFILL" - Data received while backfilling existing data (e.g. pushing historical vulnerabilities when re-connect a workspace). Default is "NORMAL". "NORMAL" traffic has higher priority but tighter rate limits, "SCAN" traffic has medium priority and looser limits, "BACKFILL" has lower priority and much looser limits

propertiesobject

Properties assigned to vulnerability data that can then be used for delete / query operations.

Examples might be an account or user ID that can then be used to clean up data if an account is removed from the Provider system.

Properties are supplied as key/value pairs, and a maximum of 5 properties can be supplied, keys cannot contain ':' or start with '_'.

Example request

{
  "operationType": "SCAN",
  "properties": {
    "accountId": "account-234",
    "projectId": "project-123"
  },
  "vulnerabilities": [
    {
      "schemaVersion": "1.0",
      "id": "111-222-333",
      "updateSequenceNumber": 1523494301448,
      "containerId": "111-222-333",
      "displayName": "curl/libcurl3 - Buffer Override",
      "description": "## Overview\n\n\nAffected versions of this package are vulnerable to MeltLeak",
      "url": "https://example.com/project/CWE-123/summary",
      "type": "sca",
      "introducedDate": "2018-01-20T23:27:25.000Z",
      "lastUpdated": "2018-01-20T23:27:25.000Z",
      "severity": {
        "level": "critical"
      },
      "identifiers": [
        {
          "displayName": "CWE-123",
          "url": "https://cwe.mitre.org/data/definitions/123.html"
        }
      ],
      "status": "open",
      "additionalInfo": {
        "content": "More information on the vulnerability, as a string",
        "url": "https://example.com/project/CWE-123/additionalInfo"
      },
      "addAssociations": [
        {
          "associationType": "issueIdOrKeys",
          "values": [
            "PROJ-1234"
          ]
        }
      ],
      "removeAssociations": [
        {
          "associationType": "issueIdOrKeys",
          "values": [
            "PROJ-1234"
          ]
        }
      ],
      "associationsLastUpdated": "2018-01-20T23:27:25.000Z",
      "associationsUpdateSequenceNumber": 1523494301448
    }
  ],
  "providerMetadata": {
    "product": "Atlassian Security Platform 2.1.0"
  }
}

Response

Submission accepted. Each Vulnerability submitted in a valid format will eventually be available in Jira.

Details of any Vulnerabilities that were submitted but failed submission (due to data format problems, etc.) are available in the response object.

acceptedVulnerabilitiesstring[]

The IDs of Vulnerabilities that have been accepted for submission.

A Vulnerability may be rejected if it was only associated with unknown project keys.

Note that a Vulnerability that isn't updated due to it's updateSequenceNumber being out of order is not considered a failed submission.

failedVulnerabilitiesobject

Details of Vulnerabilities that have not been accepted for submission, usually due to a problem with the request data.

The object (if present) will be keyed by Vulnerability ID and include any errors associated with that Vulnerability that have prevented it being submitted.

Example response

{
  "acceptedVulnerabilities": [
    "111-222-333",
    "444-555-666"
  ],
  "unknownAssociations": [
    {
      "associationType": "issueIdOrKeys",
      "values": [
        "PROJ-1234"
      ]
    }
  ]
}

Changes

  • 4e108d54b990Revision changes
    • info

      the endpoint scheme security OAuth2 was added to the API

    • info

      added subschema #1: IssueIdOrKeysAssociation to the / response property anyOf list for the response status

    • info

      removed subschema #1: ServiceIdOrKeysAssociation from the / response property anyOf list for the response status

  • 10049ef3cca3Revision changes
    • breaking

      added the pattern [a-zA-Z0-9\-_.~@:{}=]+(/[a-zA-Z0-9\-_.~@:{}=]+)* to the request property //

    • warning

      removed the request property //

    • info

      added the new optional request property //

    • info

      added the new optional request property //

    • info

      added the new optional request property //

    • info

      added the new optional request property //

    • info

      added the new SCAN enum value to the request property