Submit assets and vulnerabilities from an external scanner

post /public_api/vulnerability-management/v1/external-scans/assets

Imports asset and vulnerability data from a third-party scanner into Cortex vulnerability management.

Each request must include at least one asset. Each asset can carry multiple CVE findings. The platform validates all input on receipt — if validation fails, a 422 Unprocessable Entity response is returned with field-level error details.

Successful requests are processed asynchronously. The response includes a job_id that can be polled using the Get BYOS import job status endpoint, plus counts of accepted assets and vulnerabilities.

RBAC permission required: manage_vulnerabilities_action

Required licenses: Exposure Management; and either Cortex XSIAM Premium or any Cortex XSIAM product with the Cloud Runtime Security or Cloud Posture Security add-ons

Request headers

x-xdr-auth-id required

Authorization String required

Example: authorization_example

CLIENT REQUEST

          curl -X 'POST'

        -H
        'Accept: application/json'
      

        -H
        'Content-Type: application/json'
      

          -H
          'x-xdr-auth-id: '
          -H
          'Authorization: authorization_example'
      

      'https://api-yourfqdn/public_api/vulnerability-management/v1/external-scans/assets'
    

      -d
      '{
  "product" : "product",
  "assets" : [ {
    "product" : "product",
    "origin_asset_id" : "origin_asset_id",
    "last_seen" : 1,
    "fqdn" : [ "fqdn", "fqdn" ],
    "version" : "version",
    "origin_tags" : [ "env:perf-test", "batch:stress" ],
    "ipv4" : [ "ipv4", "ipv4" ],
    "asset_name" : "asset_name",
    "ipv6" : [ "ipv6", "ipv6" ],
    "mac_address" : "mac_address",
    "vendor" : "vendor",
    "vulnerabilities" : [ {
      "protocol" : "TCP",
      "vulnerability_id" : "vulnerability_id",
      "last_seen" : 0,
      "evidence" : "evidence",
      "port" : 39500,
      "cve_id" : [ "cve_id", "cve_id" ],
      "raw_output" : "raw_output",
      "confidence" : "Potential",
      "description" : "description",
      "scan_name" : "scan_name"
    }, {
      "protocol" : "TCP",
      "vulnerability_id" : "vulnerability_id",
      "last_seen" : 0,
      "evidence" : "evidence",
      "port" : 39500,
      "cve_id" : [ "cve_id", "cve_id" ],
      "raw_output" : "raw_output",
      "confidence" : "Potential",
      "description" : "description",
      "scan_name" : "scan_name"
    } ],
    "os_name" : "os_name"
  }, {
    "product" : "product",
    "origin_asset_id" : "origin_asset_id",
    "last_seen" : 1,
    "fqdn" : [ "fqdn", "fqdn" ],
    "version" : "version",
    "origin_tags" : [ "env:perf-test", "batch:stress" ],
    "ipv4" : [ "ipv4", "ipv4" ],
    "asset_name" : "asset_name",
    "ipv6" : [ "ipv6", "ipv6" ],
    "mac_address" : "mac_address",
    "vendor" : "vendor",
    "vulnerabilities" : [ {
      "protocol" : "TCP",
      "vulnerability_id" : "vulnerability_id",
      "last_seen" : 0,
      "evidence" : "evidence",
      "port" : 39500,
      "cve_id" : [ "cve_id", "cve_id" ],
      "raw_output" : "raw_output",
      "confidence" : "Potential",
      "description" : "description",
      "scan_name" : "scan_name"
    }, {
      "protocol" : "TCP",
      "vulnerability_id" : "vulnerability_id",
      "last_seen" : 0,
      "evidence" : "evidence",
      "port" : 39500,
      "cve_id" : [ "cve_id", "cve_id" ],
      "raw_output" : "raw_output",
      "confidence" : "Potential",
      "description" : "description",
      "scan_name" : "scan_name"
    } ],
    "os_name" : "os_name"
  } ],
  "vendor" : "vendor",
  "version" : "version"
}'
    


      

import http.client

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

payload = "{\"vendor\":\"string\",\"product\":\"string\",\"version\":\"string\",\"assets\":[{\"ipv4\":[\"192.168.0.1\"],\"vulnerabilities\":[{\"vulnerability_id\":\"string\",\"last_seen\":0,\"port\":1,\"protocol\":\"TCP\",\"raw_output\":\"string\",\"confidence\":\"Potential\",\"description\":\"string\",\"evidence\":\"string\",\"scan_name\":\"string\",\"cve_id\":[\"string\"]}],\"origin_asset_id\":\"string\",\"asset_name\":\"string\",\"ipv6\":[\"2001:0db8:85a3:0000:0000:8a2e:0370:7334\"],\"fqdn\":[\"string\"],\"mac_address\":\"string\",\"origin_tags\":[\"env:perf-test\",\"batch:stress\"],\"last_seen\":0,\"os_name\":\"string\",\"product\":\"string\",\"vendor\":\"string\",\"version\":\"string\"}]}"

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

conn.request("POST", "/public_api/vulnerability-management/v1/external-scans/assets", 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/vulnerability-management/v1/external-scans/assets")

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["x-xdr-auth-id"] = 'SOME_INTEGER_VALUE'
request["Authorization"] = 'SOME_STRING_VALUE'
request["content-type"] = 'application/json'
request.body = "{\"vendor\":\"string\",\"product\":\"string\",\"version\":\"string\",\"assets\":[{\"ipv4\":[\"192.168.0.1\"],\"vulnerabilities\":[{\"vulnerability_id\":\"string\",\"last_seen\":0,\"port\":1,\"protocol\":\"TCP\",\"raw_output\":\"string\",\"confidence\":\"Potential\",\"description\":\"string\",\"evidence\":\"string\",\"scan_name\":\"string\",\"cve_id\":[\"string\"]}],\"origin_asset_id\":\"string\",\"asset_name\":\"string\",\"ipv6\":[\"2001:0db8:85a3:0000:0000:8a2e:0370:7334\"],\"fqdn\":[\"string\"],\"mac_address\":\"string\",\"origin_tags\":[\"env:perf-test\",\"batch:stress\"],\"last_seen\":0,\"os_name\":\"string\",\"product\":\"string\",\"vendor\":\"string\",\"version\":\"string\"}]}"

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

const data = JSON.stringify({
  "vendor": "string",
  "product": "string",
  "version": "string",
  "assets": [
    {
      "ipv4": [
        "192.168.0.1"
      ],
      "vulnerabilities": [
        {
          "vulnerability_id": "string",
          "last_seen": 0,
          "port": 1,
          "protocol": "TCP",
          "raw_output": "string",
          "confidence": "Potential",
          "description": "string",
          "evidence": "string",
          "scan_name": "string",
          "cve_id": [
            "string"
          ]
        }
      ],
      "origin_asset_id": "string",
      "asset_name": "string",
      "ipv6": [
        "2001:0db8:85a3:0000:0000:8a2e:0370:7334"
      ],
      "fqdn": [
        "string"
      ],
      "mac_address": "string",
      "origin_tags": [
        "env:perf-test",
        "batch:stress"
      ],
      "last_seen": 0,
      "os_name": "string",
      "product": "string",
      "vendor": "string",
      "version": "string"
    }
  ]
});

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/vulnerability-management/v1/external-scans/assets");
xhr.setRequestHeader("x-xdr-auth-id", "SOME_INTEGER_VALUE");
xhr.setRequestHeader("Authorization", "SOME_STRING_VALUE");
xhr.setRequestHeader("content-type", "application/json");

xhr.send(data);

HttpResponse<String> response = Unirest.post("https://api-yourfqdn/public_api/vulnerability-management/v1/external-scans/assets")
  .header("x-xdr-auth-id", "SOME_INTEGER_VALUE")
  .header("Authorization", "SOME_STRING_VALUE")
  .header("content-type", "application/json")
  .body("{\"vendor\":\"string\",\"product\":\"string\",\"version\":\"string\",\"assets\":[{\"ipv4\":[\"192.168.0.1\"],\"vulnerabilities\":[{\"vulnerability_id\":\"string\",\"last_seen\":0,\"port\":1,\"protocol\":\"TCP\",\"raw_output\":\"string\",\"confidence\":\"Potential\",\"description\":\"string\",\"evidence\":\"string\",\"scan_name\":\"string\",\"cve_id\":[\"string\"]}],\"origin_asset_id\":\"string\",\"asset_name\":\"string\",\"ipv6\":[\"2001:0db8:85a3:0000:0000:8a2e:0370:7334\"],\"fqdn\":[\"string\"],\"mac_address\":\"string\",\"origin_tags\":[\"env:perf-test\",\"batch:stress\"],\"last_seen\":0,\"os_name\":\"string\",\"product\":\"string\",\"vendor\":\"string\",\"version\":\"string\"}]}")
  .asString();

import Foundation

let headers = [
  "x-xdr-auth-id": "SOME_INTEGER_VALUE",
  "Authorization": "SOME_STRING_VALUE",
  "content-type": "application/json"
]
let parameters = [
  "vendor": "string",
  "product": "string",
  "version": "string",
  "assets": [
    [
      "ipv4": ["192.168.0.1"],
      "vulnerabilities": [
        [
          "vulnerability_id": "string",
          "last_seen": 0,
          "port": 1,
          "protocol": "TCP",
          "raw_output": "string",
          "confidence": "Potential",
          "description": "string",
          "evidence": "string",
          "scan_name": "string",
          "cve_id": ["string"]
        ]
      ],
      "origin_asset_id": "string",
      "asset_name": "string",
      "ipv6": ["2001:0db8:85a3:0000:0000:8a2e:0370:7334"],
      "fqdn": ["string"],
      "mac_address": "string",
      "origin_tags": ["env:perf-test", "batch:stress"],
      "last_seen": 0,
      "os_name": "string",
      "product": "string",
      "vendor": "string",
      "version": "string"
    ]
  ]
] as [String : Any]

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

let request = NSMutableURLRequest(url: NSURL(string: "https://api-yourfqdn/public_api/vulnerability-management/v1/external-scans/assets")! 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/vulnerability-management/v1/external-scans/assets",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => "{\"vendor\":\"string\",\"product\":\"string\",\"version\":\"string\",\"assets\":[{\"ipv4\":[\"192.168.0.1\"],\"vulnerabilities\":[{\"vulnerability_id\":\"string\",\"last_seen\":0,\"port\":1,\"protocol\":\"TCP\",\"raw_output\":\"string\",\"confidence\":\"Potential\",\"description\":\"string\",\"evidence\":\"string\",\"scan_name\":\"string\",\"cve_id\":[\"string\"]}],\"origin_asset_id\":\"string\",\"asset_name\":\"string\",\"ipv6\":[\"2001:0db8:85a3:0000:0000:8a2e:0370:7334\"],\"fqdn\":[\"string\"],\"mac_address\":\"string\",\"origin_tags\":[\"env:perf-test\",\"batch:stress\"],\"last_seen\":0,\"os_name\":\"string\",\"product\":\"string\",\"vendor\":\"string\",\"version\":\"string\"}]}",
  CURLOPT_HTTPHEADER => [
    "Authorization: SOME_STRING_VALUE",
    "content-type: application/json",
    "x-xdr-auth-id: SOME_INTEGER_VALUE"
  ],
]);

$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/vulnerability-management/v1/external-scans/assets");

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

curl_easy_setopt(hnd, CURLOPT_POSTFIELDS, "{\"vendor\":\"string\",\"product\":\"string\",\"version\":\"string\",\"assets\":[{\"ipv4\":[\"192.168.0.1\"],\"vulnerabilities\":[{\"vulnerability_id\":\"string\",\"last_seen\":0,\"port\":1,\"protocol\":\"TCP\",\"raw_output\":\"string\",\"confidence\":\"Potential\",\"description\":\"string\",\"evidence\":\"string\",\"scan_name\":\"string\",\"cve_id\":[\"string\"]}],\"origin_asset_id\":\"string\",\"asset_name\":\"string\",\"ipv6\":[\"2001:0db8:85a3:0000:0000:8a2e:0370:7334\"],\"fqdn\":[\"string\"],\"mac_address\":\"string\",\"origin_tags\":[\"env:perf-test\",\"batch:stress\"],\"last_seen\":0,\"os_name\":\"string\",\"product\":\"string\",\"vendor\":\"string\",\"version\":\"string\"}]}");

CURLcode ret = curl_easy_perform(hnd);

var client = new RestClient("https://api-yourfqdn/public_api/vulnerability-management/v1/external-scans/assets");
var request = new RestRequest(Method.POST);
request.AddHeader("x-xdr-auth-id", "SOME_INTEGER_VALUE");
request.AddHeader("Authorization", "SOME_STRING_VALUE");
request.AddHeader("content-type", "application/json");
request.AddParameter("application/json", "{\"vendor\":\"string\",\"product\":\"string\",\"version\":\"string\",\"assets\":[{\"ipv4\":[\"192.168.0.1\"],\"vulnerabilities\":[{\"vulnerability_id\":\"string\",\"last_seen\":0,\"port\":1,\"protocol\":\"TCP\",\"raw_output\":\"string\",\"confidence\":\"Potential\",\"description\":\"string\",\"evidence\":\"string\",\"scan_name\":\"string\",\"cve_id\":[\"string\"]}],\"origin_asset_id\":\"string\",\"asset_name\":\"string\",\"ipv6\":[\"2001:0db8:85a3:0000:0000:8a2e:0370:7334\"],\"fqdn\":[\"string\"],\"mac_address\":\"string\",\"origin_tags\":[\"env:perf-test\",\"batch:stress\"],\"last_seen\":0,\"os_name\":\"string\",\"product\":\"string\",\"vendor\":\"string\",\"version\":\"string\"}]}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);

Body parameters

required

application/json

Request body for importing vulnerable assets from an external scanner.

vendorstringrequired

Vulnerability scanner vendor. Examples: TENABLE, QUALYS, RAPID7_VM, RAPID7_CLOUD.

productstringrequired

Product name associated with the vulnerabilities.

versionstring

Product version, used for (vendor, product, version) CVE mapping.

assetsarrayrequired

List of assets with their vulnerability findings. Must contain at least one asset.

[

ipv4array[string]

IPv4 addresses used to identify this asset in the source system.

vulnerabilitiesarrayrequired

All vulnerabilities related to this asset.

[

vulnerability_idstringrequired

CVE ID for the vulnerability. Typically follows the canonical CVE format (for example, CVE-2024-12345), but the API does not enforce this format and accepts any non-empty string identifier.

last_seenintegerrequired

Timestamp in milliseconds. Must be within the last 30 days from the current time. Older or future timestamps are rejected with HTTP 422.

portinteger

Port used for remote scanning. Must be a positive integer less than 65,535.

protocolstring (Enum)

Network protocol used during scanning.

Allowed values:"TCP""UDP"

raw_outputstring

Additional output from the scanner. Maximum 2,000 characters.

confidencestring (Enum)

Confidence level of the vulnerability finding.

Allowed values:"Potential""Confirmed"

descriptionstring

Description of the vulnerability.

evidencestring

Evidence supporting the vulnerability finding.

scan_namestring

Name of the scan that detected this vulnerability.

cve_idarray[string]

List of CVE IDs associated with this vulnerability.

]

origin_asset_idstring

Unique ID generated by the source system. Used as a uniqueness constraint for future matching.

asset_namestring

Friendly name of the asset. If omitted, the platform may auto-generate a name from the FQDN, IPv4, or IPv6 address.

ipv6array[string]

IPv6 addresses used to identify this asset in the source system.

fqdnarray[string]

FQDNs used to identify this asset in the source system.

mac_addressstring

MAC address assigned to the asset in the source system.

origin_tagsarray[string]

Tags from the origin system. Stored in the platform tags field to allow ingesting additional asset context. Parsed as key/value pairs separated by colons.

Example:["env:perf-test","batch:stress"]

last_seenintegerrequired

Timestamp in milliseconds. Must be within the last 30 days from the current time. Older or future timestamps are rejected with HTTP 422.

os_namestring

Operating system name of the asset.

productstring

Product name installed on the asset.

vendorstring

Vendor of the product installed on the asset.

versionstring

Version of the product installed on the asset.

]

REQUEST
{
  "vendor": "example",
  "product": "example",
  "version": "example",
  "assets": [
    {
      "ipv4": [
        "ipv4 string"
      ],
      "vulnerabilities": [
        {
          "vulnerability_id": "example",
          "last_seen": 0,
          "port": 0,
          "protocol": "TCP",
          "raw_output": "example",
          "confidence": "Potential",
          "description": "example",
          "evidence": "example",
          "scan_name": "example",
          "cve_id": [
            "example"
          ]
        }
      ],
      "origin_asset_id": "example",
      "asset_name": "example",
      "ipv6": [
        "ipv6 string"
      ],
      "fqdn": [
        "example"
      ],
      "mac_address": "example",
      "origin_tags": [
        "env:perf-test",
        "batch:stress"
      ],
      "last_seen": 0,
      "os_name": "example",
      "product": "example",
      "vendor": "example",
      "version": "example"
    }
  ]
}

Responses

Assets accepted for asynchronous processing. The response includes import counts and the job_id for status polling.

Body

application/json

Response for a successful vulnerable asset import. Returns counts and the async job identifier needed to poll for completion.

assets_countintegerrequired

Total number of assets accepted in the import request.

Example:2

vulnerabilities_countintegerrequired

Total number of vulnerabilities accepted across all assets in the import request.

Example:4

job_idstringrequireduuid

Unique identifier for the async import job. Use this value with the Get BYOS Import Job Status endpoint to poll for completion.

Example:"a2b1aba2-37fe-4fb4-ba6d-829e8cf5d653"

job_statusobjectrequired

Initial status of the import job. Will be INITIATED immediately after a successful POST.

string (Enum)

Possible status values for a BYOS import job.

Allowed values:"INITIATED""PROCESSING""COMPLETED""COMPLETED_WITH_ERRORS""FAILED"

RESPONSE
{
  "assets_count": 2,
  "vulnerabilities_count": 4,
  "job_id": "a2b1aba2-37fe-4fb4-ba6d-829e8cf5d653",
  "job_status": "INITIATED"
}

Validation Error — one or more request fields failed schema validation. Check the detail array for field-level error messages.

Body

application/json

detailarray

[

locarrayrequired

[

Any of

string

integer

]

msgstringrequired

typestringrequired

]

RESPONSE
{
  "detail": [
    {
      "loc": [
        0
      ],
      "msg": "example",
      "type": "example"
    }
  ]
}