Uploading data via API

Use the IBM® Concert API to upload SBOM files, image scans, and certificate data.

Attention: There is a known limitation in which Concert does not support concurrent uploads of SBOMs that have common packages. If you upload two or more CycloneDX SBOMs or vulnerability scan files that have a common subset of packages or vulnerabilities, you might encounter one of these errors:
  • The SBOM and packages relation couldn't be created.
  • The database connection couldn't be acquired because an error occurred.
  • The pipeline couldn't be invoked.
As a workaround, you can upload the SBOM files one at a time and view the Event logs and ensure the event status is complete before uploading subsequent files.
Note: Refer to the https://developer.ibm.com/apis/catalog/concert--ibm-concert-api for a full index of endpoints and requests.
You can use a POST request to the API endpoint to upload the following data types to Concert:
  • Application SBOM (application_sbom)
  • Build SBOM (application_sbom)
  • Deploy SBOM (application_sbom)
  • Package SBOM (package_sbom)
  • Vulnerability scans (CVEs and exposures)
    • Vulnerability scan of an image (image_scan)
    • Vulnerability scan of source code (code_scan)
    • Vulnerability scan of a runtime or virtual machine (vm_scan)
    • Dynamic Application Security Testing (DAST) for a CVE (dynamic_scan)
    • Static Application Security Testing (SAST) of source code in SARIF format (static_code_scan)
  • Certificate details (certificate)
Note: When uploading a ConcertDef SBOM file, you must set the data_type parameter value to application_sbom, regardless if it is an application SBOM, build SBOM, or deploy SBOM.

Before you begin

API endpoint for data ingestion

https://${concert_host}:${port}/ingestion/api/v1/upload_files
Variable Description
${concert_host} Hostname of the Concert API server.
{port} The number of the port on which the API server is listening for incoming requests. For SaaS and OpenShift Container Platform deployments, the port value of 443. The port number can vary for VM deployments.

Code snippet

$CURL -X 'POST' \
    "https://${concert_host}:${port}/ingestion/api/v1/upload_files" \
    -H 'accept: application/json' \
    -H "InstanceID: <string>" \
    -H "Authorization: <type> ${Concert_API_Key}" \ 
    -H 'Content-Type: multipart/form-data' \
    -F "data_type=<enum>" \
    -F "filename=@<string>"

Parameters

Parameter Description
InstanceID Unique ID of your Concert instance. This value appears temporarily in the UI, along with other details that are related to API key usage, when you generate an API key in the Concert UI. Example format: 0000-0000-0000-0000
Authorization The Concert API key type and value.
  • Replace <type> with C_API_KEY for SaaS and VM deployments, and ZenApiKey for OpenShift Container Platform deployments.
  • Replace ${Concert_API_key} with the unique API key value generated in the Concert UI.
data_type The type of data you are uploading.
  • Application SBOM (application_sbom)
  • Build SBOM (application_sbom)
  • Deploy SBOM (application_sbom)
  • Package SBOM (package_sbom)
  • Vulnerability scans (CVEs and exposures)
    • Vulnerability scan of an image (image_scan)
    • Vulnerability scan of source code (code_scan)
    • Vulnerability scan of a runtime or virtual machine (vm_scan)
    • Dynamic Application Security Testing (DAST) for a CVE (dynamic_scan)
    • Static Application Security Testing (SAST) of source code in SARIF format (static_code_scan)
  • Certificate details (certificate)
filename File path and name of the file you want to upload. Precede the file path with an @ symbol. For example, @slacksim-definition.json
Table 1. File upload matrix
Category Data format Data type File type Metadata
Concert Inventory Application SBOM (ConcertDef) application_sbom json No metadata
Build SBOM (ConcertDef) application_sbom json No metadata
Deploy SBOM (ConcertDef) application_sbom json No metadata
Software Composition Package SBOM (CycloneDX) - Image package_sbom json No metadata
Package SBOM (CycloneDX) - Source package_sbom json (Optional) repo_url
Vulnerability Prisma Cloud scan image_scan json (Optional) scanner_name
Prisma Cloud scan image_scan csv (Optional) scanner_name
Sysdig image_scan csv (Optional) scanner_name
VDR scan (CycloneDX) image_scan json (Optional) scanner_name
Aqua Security image_scan json (Optional) scanner_name
VDR scan (CycloneDX) code_scan json (Required) repo_url
Concert Custom Format code_scan csv (Optional) scanner_name
(Optional) repo_url
Mend code_scan csv (Optional) scanner_name
(Optional) repo_url
Qualys vm_scan csv (Optional) scanner_name
SARIF static_code_scan json (Required) repo_url
(Required) repo_name
Concert Custom Format static_code_scan csv (Required) repo_url
(Required) repo_name
SonarQube static_code_scan csv (Required) repo_url
(Required) repo_name
(Optional) scanner_name
Zap dynamic_scan json (Required) env_name
(Required) access_point_name
Concert Custom Format dynamic_scan csv (Required) env_name
(Required) access_point_name
(Required) access_point_url
Certificate Concert Custom Format certificate csv (Required) env_name
Certificate SBOM (ConcertDef) certificate json No metadata
Compliance Compliance Catalog compliance_catalog json No metadata
Compliance Posture compliance_posture json No metadata

Examples

Each of the following examples demonstrates the structure of an API call for uploading a specific type of data to the Concert platform.

Upload an application, build, or deploy SBOM file (ConcertDef format)

The following example uploads an application, build, or deploy SBOM file that is called, example-SBOM.json, in ConcertDef format.

$CURL -X 'POST' \
    "https://${concert_host}:${port}/ingestion/api/v1/upload_files" \
    -H 'accept: application/json' \
    -H "InstanceID: 0000-0000-0000-0000" \
    -H "Authorization: <type> ${Concert_API_key}" \ 
    -H 'Content-Type: multipart/form-data' \
    -F "data_type=application_sbom" \
    -F "filename=@my-application-SBOM.json"

Upload a package SBOM (CycloneDX format)

The following example uploads a package SBOM file that is called, my-package-sbom.json, in CycloneDX format.

$CURL -X 'POST' \
    "https://${concert_host}:${port}/ingestion/api/v1/upload_files" \
    -H 'accept: application/json' \
    -H "InstanceID: 0000-0000-0000-0000" \
    -H "Authorization: <type> ${Concert_API_key}" \ 
    -H 'Content-Type: multipart/form-data' \
    -F "data_type=package_sbom" \
    -F "filename=@my-package-SBOM.json"

Upload a vulnerability scan (of image)

The following example uploads a vulnerability scan called, my-image-scan.csv.

$CURL -X 'POST' \
    "https://${concert_host}:${port}/ingestion/api/v1/upload_files" \
    -H 'accept: application/json' \
    -H "InstanceID: 0000-0000-0000-0000" \
    -H "Authorization: <type> ${Concert_API_key}" \ 
    -H 'Content-Type: multipart/form-data' \
    -F "data_type=image_scan" \
    -F "filename=@my-image-scan.csv" \
    -F 'metadata={"scanner_name": "<scan source>"}'

Upload a vulnerability scan (of source code)

The following example uploads a vulnerability scan called, my-code-scan.csv.

$CURL -X 'POST' \
    "https://${concert_host}:${port}/ingestion/api/v1/upload_files" \
    -H 'accept: application/json' \
    -H "InstanceID: 0000-0000-0000-0000" \
    -H "Authorization: <type> ${Concert_API_key}" \ 
    -H 'Content-Type: multipart/form-data' \
    -F "data_type=code_scan" \
    -F "filename=@my-code-scan.csv" \
    -F 'metadata={"scanner_name": "<scan source>"}'

Upload a vulnerability scan (of a runtime or virtual machine)

The following example uploads a vulnerability scan called, my-vm-scan.csv.

$CURL -X 'POST' \
    "https://${concert_host}:${port}/ingestion/api/v1/upload_files" \
    -H 'accept: application/json' \
    -H "InstanceID: 0000-0000-0000-0000" \
    -H "Authorization: <type> ${Concert_API_key}" \ 
    -H 'Content-Type: multipart/form-data' \
    -F "data_type=vm_scan" \
    -F "filename=@my-vm-scan.csv" \
    -F 'metadata={"scanner_name": "<scan source>"}'

Upload a DAST dynamic vulnerability scan

The following example uploads a Dynamic Application Security Testing (DAST) scan that is called, dast-scan.csv.

$CURL -X 'POST' \
    "https://${concert_host}:${port}/ingestion/api/v1/upload_files" \
    -H 'accept: application/json' \
    -H "InstanceID: 0000-0000-0000-0000" \
    -H "Authorization: <type> ${Concert_API_key}" \ 
    -H 'Content-Type: multipart/form-data' \
    -F "data_type=dynamic_scan" \
    -F "filename=@/Users/jsmith/Desktop/dast-scan.csv" \
    -F 'metadata={"env_name": "prod","access_point_name": "<string>","access_point_url": "<url>"}'

Upload a SAST vulnerability scan

The following example uploads a Static Application Security Testing (SAST) scan in SARIF format that is called, sast-scan.csv.

$CURL -X 'POST' \
    "https://${concert_host}:${port}/ingestion/api/v1/upload_files" \
    -H 'accept: application/json' \
    -H "InstanceID: 0000-0000-0000-0000" \
    -H "Authorization: <type> ${Concert_API_key}" \ 
    -H 'Content-Type: multipart/form-data' \
    -F "data_type=static_code_scan" \
    -F "filename=@/Users/jsmith/Desktop/sast-scan.csv" \
    -F 'metadata={"env_name": "prod","repo_url": "<url>", "repo_name":"<string>"}'

Upload certificate details

Certificate data can be uploaded as a csv file or JSON file. For detailed steps and sample files, refer uploading certificate data.

The following example is for uploading a csv file that is called, my-certificates.csv.

$CURL -X 'POST' \
    "https://${concert_host}:${port}/ingestion/api/v1/upload_files" \
    -H 'accept: application/csv' \
    -H "InstanceID: 0000-0000-0000-0000" \
    -H "Authorization: <type> ${Concert_API_key}" \ 
    -H 'Content-Type: multipart/form-data' \
    -F "data_type=certificate" \
    -F 'metadata={"env_name": "prod"}'
    -F "filename=@my-certificates.csv"

The following example uses JSON file that is called my-certificates.json for uploading certificate data.

$CURL -X 'POST' \ "https://${concert_host}:{port}/ingestion/api/v1/upload_files" \ 
-H 'accept: application/json' \ 
-H "InstanceID: 0000-0000-0000-0000" \ 
-H "Authorization: <type> ${Concert_API_key}" \ 
-H 'Content-Type: multipart/form-data" \ 
-F "data_type=certificate" \ 
-F "filename=@my-certificates.json"
Note: You can also use the API to upload evidence files. Refer to Upload evidence through API.

HTTP response codes

  • 200 Success. The file was uploaded successfully.
  • 400 Invalid request parameters. Review the details of your request.
  • 401 Unauthorized - Invalid or missing authorization token.
  • 500 Internal Server Error - An error occurred on the server.