Limitations

Maximum file size: 10 MB per request.
SARIF version: Only SARIF v2.1.0 is supported. Files with invalid formats or schema will return a 400 error.

Path parameters

collectorId String required

Unique identifier for the collector instance. This is the id field returned by the GET /public_api/appsec/v1/data_source_instances?type=collector endpoint. The collector must be of type COLLECTOR with detectionMethod: SAST and fileType: SARIF

Example: col_7f2a9b4e1c3d5f8a0b6e2d4c

Request headers

Authorization String required

{api_key}

Example: your_api_key_here

x-xdr-auth-id String required

{api_key_id}

Example: 1

Query parameters

repository_id String required

The asset ID of the target repository. This is the id field (SHA-256 hash format) returned by the GET /public_api/appsec/v1/repositories endpoint. At least one of repository_url or repository_id must be provided. Both may be included. If neither is supplied, the request returns a 400 Bad Request.

Example: a3b8f2e1c7d4509a6b1e3f8c2d7a4b9e5f0c1d6a8b3e7f2c4d9a0b5e1f6c3d8

repository_url String required

The URL of the target repository. At least one of repository_url or repository_id must be provided. Both may be included. If neither is supplied, the request returns a 400 Bad Request.

Example: https://github.com/testapp/cves

branch String

Optional. Branch name to associate findings with. Defaults to the repository's default branch when omitted.

Example: main

CLIENT REQUEST

          curl -X 'POST'

        -H
        'Accept: application/json'
      
        -H
        'Content-Type: application/json'
      
          -H
          'Authorization: your_api_key_here'
          -H
          'x-xdr-auth-id: 1'
      
      'https://api-yourfqdn/public_api/appsec/v1/collectors/{collectorId}?repository_id=a3b8f2e1c7d4509a6b1e3f8c2d7a4b9e5f0c1d6a8b3e7f2c4d9a0b5e1f6c3d8&repository_url=https://github.com/testapp/cves&branch=main'
    
      -d
      ''

import http.client

conn = http.client.HTTPSConnection("api-yourfqdn")

payload = "{}"

headers = {
    'Authorization': "your_api_key_here",
    'x-xdr-auth-id': "1",
    'content-type': "application/json"
    }

conn.request("POST", "/public_api/appsec/v1/collectors/col_7f2a9b4e1c3d5f8a0b6e2d4c?repository_id=a3b8f2e1c7d4509a6b1e3f8c2d7a4b9e5f0c1d6a8b3e7f2c4d9a0b5e1f6c3d8&repository_url=https%3A%2F%2Fgithub.com%2Ftestapp%2Fcves&branch=main", payload, headers)

res = conn.getresponse()
data = res.read()

print(data.decode("utf-8"))

require 'uri'
require 'net/http'
require 'openssl'

url = URI("https://api-yourfqdn/public_api/appsec/v1/collectors/col_7f2a9b4e1c3d5f8a0b6e2d4c?repository_id=a3b8f2e1c7d4509a6b1e3f8c2d7a4b9e5f0c1d6a8b3e7f2c4d9a0b5e1f6c3d8&repository_url=https%3A%2F%2Fgithub.com%2Ftestapp%2Fcves&branch=main")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
http.verify_mode = OpenSSL::SSL::VERIFY_NONE

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'your_api_key_here'
request["x-xdr-auth-id"] = '1'
request["content-type"] = 'application/json'
request.body = "{}"

response = http.request(request)
puts response.read_body

const data = JSON.stringify({});

const xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("POST", "https://api-yourfqdn/public_api/appsec/v1/collectors/col_7f2a9b4e1c3d5f8a0b6e2d4c?repository_id=a3b8f2e1c7d4509a6b1e3f8c2d7a4b9e5f0c1d6a8b3e7f2c4d9a0b5e1f6c3d8&repository_url=https%3A%2F%2Fgithub.com%2Ftestapp%2Fcves&branch=main");
xhr.setRequestHeader("Authorization", "your_api_key_here");
xhr.setRequestHeader("x-xdr-auth-id", "1");
xhr.setRequestHeader("content-type", "application/json");

xhr.send(data);

HttpResponse<String> response = Unirest.post("https://api-yourfqdn/public_api/appsec/v1/collectors/col_7f2a9b4e1c3d5f8a0b6e2d4c?repository_id=a3b8f2e1c7d4509a6b1e3f8c2d7a4b9e5f0c1d6a8b3e7f2c4d9a0b5e1f6c3d8&repository_url=https%3A%2F%2Fgithub.com%2Ftestapp%2Fcves&branch=main")
  .header("Authorization", "your_api_key_here")
  .header("x-xdr-auth-id", "1")
  .header("content-type", "application/json")
  .body("{}")
  .asString();

import Foundation

let headers = [
  "Authorization": "your_api_key_here",
  "x-xdr-auth-id": "1",
  "content-type": "application/json"
]
let parameters = [] as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

let request = NSMutableURLRequest(url: NSURL(string: "https://api-yourfqdn/public_api/appsec/v1/collectors/col_7f2a9b4e1c3d5f8a0b6e2d4c?repository_id=a3b8f2e1c7d4509a6b1e3f8c2d7a4b9e5f0c1d6a8b3e7f2c4d9a0b5e1f6c3d8&repository_url=https%3A%2F%2Fgithub.com%2Ftestapp%2Fcves&branch=main")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "POST"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api-yourfqdn/public_api/appsec/v1/collectors/col_7f2a9b4e1c3d5f8a0b6e2d4c?repository_id=a3b8f2e1c7d4509a6b1e3f8c2d7a4b9e5f0c1d6a8b3e7f2c4d9a0b5e1f6c3d8&repository_url=https%3A%2F%2Fgithub.com%2Ftestapp%2Fcves&branch=main",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => "{}",
  CURLOPT_HTTPHEADER => [
    "Authorization: your_api_key_here",
    "content-type: application/json",
    "x-xdr-auth-id: 1"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

CURL *hnd = curl_easy_init();

curl_easy_setopt(hnd, CURLOPT_CUSTOMREQUEST, "POST");
curl_easy_setopt(hnd, CURLOPT_URL, "https://api-yourfqdn/public_api/appsec/v1/collectors/col_7f2a9b4e1c3d5f8a0b6e2d4c?repository_id=a3b8f2e1c7d4509a6b1e3f8c2d7a4b9e5f0c1d6a8b3e7f2c4d9a0b5e1f6c3d8&repository_url=https%3A%2F%2Fgithub.com%2Ftestapp%2Fcves&branch=main");

struct curl_slist *headers = NULL;
headers = curl_slist_append(headers, "Authorization: your_api_key_here");
headers = curl_slist_append(headers, "x-xdr-auth-id: 1");
headers = curl_slist_append(headers, "content-type: application/json");
curl_easy_setopt(hnd, CURLOPT_HTTPHEADER, headers);

curl_easy_setopt(hnd, CURLOPT_POSTFIELDS, "{}");

CURLcode ret = curl_easy_perform(hnd);

var client = new RestClient("https://api-yourfqdn/public_api/appsec/v1/collectors/col_7f2a9b4e1c3d5f8a0b6e2d4c?repository_id=a3b8f2e1c7d4509a6b1e3f8c2d7a4b9e5f0c1d6a8b3e7f2c4d9a0b5e1f6c3d8&repository_url=https%3A%2F%2Fgithub.com%2Ftestapp%2Fcves&branch=main");
var request = new RestRequest(Method.POST);
request.AddHeader("Authorization", "your_api_key_here");
request.AddHeader("x-xdr-auth-id", "1");
request.AddHeader("content-type", "application/json");
request.AddParameter("application/json", "{}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);

Body parameters

Object

application/json

REQUESTVeracode Static Analysis
{
  "$schema": "https://raw.githubusercontent.com/oasis-tcs/sarif-spec/master/Schemata/sarif-schema-2.1.0.json",
  "version": "2.1.0",
  "runs": [
    {
      "tool": {
        "driver": {
          "name": "Veracode Static Analysis Policy Scan",
          "rules": [
            {
              "id": "78",
              "name": "Improper Neutralization of Special Elements used in an OS Command ('OS Command Injection')",
              "shortDescription": {
                "text": "CWE-78: Improper Neutralization of Special Elements used in an OS Command ('OS Command Injection')"
              },
              "helpUri": "https://cwe.mitre.org/data/definitions/78.html",
              "properties": {
                "category": "STATIC",
                "tags": [
                  "STATIC"
                ]
              },
              "defaultConfiguration": {
                "level": "error"
              }
            },
            {
              "id": "89",
              "name": "Improper Neutralization of Special Elements used in an SQL Command ('SQL Injection')",
              "shortDescription": {
                "text": "CWE-89: Improper Neutralization of Special Elements used in an SQL Command ('SQL Injection')"
              },
              "helpUri": "https://cwe.mitre.org/data/definitions/89.html",
              "properties": {
                "category": "STATIC",
                "tags": [
                  "STATIC"
                ]
              },
              "defaultConfiguration": {
                "level": "error"
              }
            }
          ],
          "version": "1.0"
        }
      },
      "results": [
        {
          "level": "error",
          "rank": 5,
          "message": {
            "text": "This call to java.lang.ProcessBuilder.start() contains a command injection flaw. The argument to the function is constructed using untrusted input. If an attacker is allowed to specify all or part of the command, it may be possible to execute commands on the server with the privileges of the executing process."
          },
          "locations": [
            {
              "physicalLocation": {
                "artifactLocation": {
                  "uri": "com/scalesec/vulnado/Cowsay.java"
                },
                "region": {
                  "startLine": 16
                }
              },
              "logicalLocations": [
                {
                  "name": "Cowsay.java",
                  "fullyQualifiedName": "com.scalesec.vulnado.Cowsay.run",
                  "kind": "function"
                }
              ]
            }
          ],
          "ruleId": "78",
          "partialFingerprints": {
            "context_guid": "",
            "file_path": "",
            "procedure": ""
          }
        },
        {
          "level": "error",
          "rank": 4,
          "message": {
            "text": "This database query contains a SQL injection flaw. The call to java.sql.Statement.executeQuery() constructs a dynamic SQL query using a variable derived from untrusted input. An attacker could exploit this flaw to execute arbitrary SQL queries against the database."
          },
          "locations": [
            {
              "physicalLocation": {
                "artifactLocation": {
                  "uri": "com/scalesec/vulnado/User.java"
                },
                "region": {
                  "startLine": 49
                }
              },
              "logicalLocations": [
                {
                  "name": "User.java",
                  "fullyQualifiedName": "com.scalesec.vulnado.User.fetch",
                  "kind": "function"
                }
              ]
            }
          ],
          "ruleId": "89",
          "partialFingerprints": {
            "context_guid": "",
            "file_path": "",
            "procedure": ""
          }
        }
      ]
    }
  ]
}

Responses

Returned when the SARIF file is accepted and the ingestion process has started.

Body

application/json

statusstring (Enum)

Ingestion status.

Allowed values:"INGESTED""PARTIALLY_VALID"

messagestring

Human-readable result message including the number of findings to be ingested.

RESPONSEExample 1
{
  "status": "INGESTED",
  "message": "SARIF file uploaded successfully. Ingestion in progress, findings may take a few minutes to show. 1 findings will be ingested"
}

Bad Request

Body

application/json

Error response for validation failures or bad requests.

statusstring

Status of the request (for example, INVALID, INGESTED_FAILED).

messagestring

Human-readable error message.

errorCodestring

Error code identifying the type of error.

RESPONSE

{
  "status": "INVALID",
  "message": "Validation failed: Invalid SARIF format - the \"version\" field is missing"
}

{
  "status": "INVALID",
  "message": "Validation failed: Invalid SARIF format - the rules section is empty"
}

{
  "status": "INGESTED_FAILED",
  "message": "File ingestion failed - Invalid repository id format"
}

{
  "errorCode": "_BadRequestError",
  "message": "Missing required repository identifier"
}

Forbidden

The API key lacks required permissions. Required role: Instance Admin, AppSec Admin, or Data Sources edit permission.

Body

application/json

replyobject

err_codeinteger

Error code identifying the type of error.

err_msgstring

Human-readable error message.

err_extrastring

RESPONSEExample 1
{
  "reply": {
    "err_code": 403,
    "err_msg": "Forbidden. Access was denied to this resource.",
    "err_extra": "Insufficient permissions for api key"
  }
}

Not Found

Body

application/json

errorCodestring

Error code identifying the type of error.

messagestring

Human-readable error message.

RESPONSECollector ID does not exist.
{
  "errorCode": "_NotFoundError",
  "message": "Collector 'invalid-collector-id' not found"
}

Service Unavailable. Returned when the collector is disabled.