Insert Simple Indicators, JSON

post /public_api/v1/indicators/insert_jsons

Upload IOCs as JSON objects that you retrieved from external threat intelligence sources.

Note: Cortex XDR does not scan historic data, but rather only new incoming data.

Required License: Cortex XDR Pro per Endpoint or Cortex XDR Pro per GB

Request headers

Authorization String required

{api_key}

Example: authorization_example

x-xdr-auth-id String required

{api_key_id}

Example: xXdrAuthId_example

Accept-Encoding String

For retrieving a compressed gzipped response

Example: acceptEncoding_example

Default: gzip

CLIENT REQUEST

          curl -X 'POST'

        -H
        'Accept: application/json'
      
        -H
        'Content-Type: application/json'
      
          -H
          'Authorization: authorization_example'
          -H
          'x-xdr-auth-id: xXdrAuthId_example'
          -H
          'Accept-Encoding: acceptEncoding_example'
      
      'https://api-yourfqdn/public_api/v1/indicators/insert_jsons'
    
      -d
      ''

import http.client

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

payload = "{\"request_data\":[{\"indicator\":\"string\",\"type\":\"HASH\",\"severity\":\"INFO\",\"expiration_date\":0,\"comment\":\"string\",\"reputation\":\"GOOD\",\"reliability\":\"A\",\"vendors\":[{\"vendor_name\":\"string\",\"reliability\":\"string\",\"reputation\":\"string\"}],\"class\":\"string\"}],\"validate\":true}"

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

conn.request("POST", "/public_api/v1/indicators/insert_jsons", 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/v1/indicators/insert_jsons")

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"] = 'SOME_STRING_VALUE'
request["x-xdr-auth-id"] = 'SOME_STRING_VALUE'
request["Accept-Encoding"] = 'SOME_STRING_VALUE'
request["content-type"] = 'application/json'
request.body = "{\"request_data\":[{\"indicator\":\"string\",\"type\":\"HASH\",\"severity\":\"INFO\",\"expiration_date\":0,\"comment\":\"string\",\"reputation\":\"GOOD\",\"reliability\":\"A\",\"vendors\":[{\"vendor_name\":\"string\",\"reliability\":\"string\",\"reputation\":\"string\"}],\"class\":\"string\"}],\"validate\":true}"

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

const data = JSON.stringify({
  "request_data": [
    {
      "indicator": "string",
      "type": "HASH",
      "severity": "INFO",
      "expiration_date": 0,
      "comment": "string",
      "reputation": "GOOD",
      "reliability": "A",
      "vendors": [
        {
          "vendor_name": "string",
          "reliability": "string",
          "reputation": "string"
        }
      ],
      "class": "string"
    }
  ],
  "validate": true
});

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/v1/indicators/insert_jsons");
xhr.setRequestHeader("Authorization", "SOME_STRING_VALUE");
xhr.setRequestHeader("x-xdr-auth-id", "SOME_STRING_VALUE");
xhr.setRequestHeader("Accept-Encoding", "SOME_STRING_VALUE");
xhr.setRequestHeader("content-type", "application/json");

xhr.send(data);

HttpResponse<String> response = Unirest.post("https://api-yourfqdn/public_api/v1/indicators/insert_jsons")
  .header("Authorization", "SOME_STRING_VALUE")
  .header("x-xdr-auth-id", "SOME_STRING_VALUE")
  .header("Accept-Encoding", "SOME_STRING_VALUE")
  .header("content-type", "application/json")
  .body("{\"request_data\":[{\"indicator\":\"string\",\"type\":\"HASH\",\"severity\":\"INFO\",\"expiration_date\":0,\"comment\":\"string\",\"reputation\":\"GOOD\",\"reliability\":\"A\",\"vendors\":[{\"vendor_name\":\"string\",\"reliability\":\"string\",\"reputation\":\"string\"}],\"class\":\"string\"}],\"validate\":true}")
  .asString();

import Foundation

let headers = [
  "Authorization": "SOME_STRING_VALUE",
  "x-xdr-auth-id": "SOME_STRING_VALUE",
  "Accept-Encoding": "SOME_STRING_VALUE",
  "content-type": "application/json"
]
let parameters = [
  "request_data": [
    [
      "indicator": "string",
      "type": "HASH",
      "severity": "INFO",
      "expiration_date": 0,
      "comment": "string",
      "reputation": "GOOD",
      "reliability": "A",
      "vendors": [
        [
          "vendor_name": "string",
          "reliability": "string",
          "reputation": "string"
        ]
      ],
      "class": "string"
    ]
  ],
  "validate": true
] as [String : Any]

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

let request = NSMutableURLRequest(url: NSURL(string: "https://api-yourfqdn/public_api/v1/indicators/insert_jsons")! 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/v1/indicators/insert_jsons",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => "{\"request_data\":[{\"indicator\":\"string\",\"type\":\"HASH\",\"severity\":\"INFO\",\"expiration_date\":0,\"comment\":\"string\",\"reputation\":\"GOOD\",\"reliability\":\"A\",\"vendors\":[{\"vendor_name\":\"string\",\"reliability\":\"string\",\"reputation\":\"string\"}],\"class\":\"string\"}],\"validate\":true}",
  CURLOPT_HTTPHEADER => [
    "Accept-Encoding: SOME_STRING_VALUE",
    "Authorization: SOME_STRING_VALUE",
    "content-type: application/json",
    "x-xdr-auth-id: SOME_STRING_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/v1/indicators/insert_jsons");

struct curl_slist *headers = NULL;
headers = curl_slist_append(headers, "Authorization: SOME_STRING_VALUE");
headers = curl_slist_append(headers, "x-xdr-auth-id: SOME_STRING_VALUE");
headers = curl_slist_append(headers, "Accept-Encoding: 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, "{\"request_data\":[{\"indicator\":\"string\",\"type\":\"HASH\",\"severity\":\"INFO\",\"expiration_date\":0,\"comment\":\"string\",\"reputation\":\"GOOD\",\"reliability\":\"A\",\"vendors\":[{\"vendor_name\":\"string\",\"reliability\":\"string\",\"reputation\":\"string\"}],\"class\":\"string\"}],\"validate\":true}");

CURLcode ret = curl_easy_perform(hnd);

var client = new RestClient("https://api-yourfqdn/public_api/v1/indicators/insert_jsons");
var request = new RestRequest(Method.POST);
request.AddHeader("Authorization", "SOME_STRING_VALUE");
request.AddHeader("x-xdr-auth-id", "SOME_STRING_VALUE");
request.AddHeader("Accept-Encoding", "SOME_STRING_VALUE");
request.AddHeader("content-type", "application/json");
request.AddParameter("application/json", "{\"request_data\":[{\"indicator\":\"string\",\"type\":\"HASH\",\"severity\":\"INFO\",\"expiration_date\":0,\"comment\":\"string\",\"reputation\":\"GOOD\",\"reliability\":\"A\",\"vendors\":[{\"vendor_name\":\"string\",\"reliability\":\"string\",\"reputation\":\"string\"}],\"class\":\"string\"}],\"validate\":true}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);

Body parameters

application/json

request_dataarray

[

indicatorstring

String that identifies the indicator you want to insert into Cortex XDR.

typestring (Enum)

Identifies the type of indicator.

Allowed values:"HASH""IP""DOMAIN_NAME""FILENAME"

severitystring (Enum)

The indicator's severity.

Allowed values:"INFO""LOW""MEDIUM""HIGH""CRITICAL""unknown"

expiration_dateinteger

Integer representing the indicator's expiration timestamp. Thisis a Unix epoch timestamp value, in milliseconds. If this indicator has no expiration, use Never. If this value is NULL, the indicator receives the indicator's type value with the default expirationdate. Valid values are:

7 days
30 days
90 days
180 days

commentstring

A descriptive comment.

reputationstring (Enum)

Keyword representing the indicator's reputation.

Allowed values:"GOOD""BAD""SUSPICIOUS""UNKNOWN""NO_REPUTATION"

reliabilityobject (Enum)

Character representing the indicator's reliability rating. Valid values are A - F. A is the most reliable, F is the least.

Allowed values:"A""B""C""D""E""F""G"

vendorsarray

A list of vendors including vendor name, reliability, and reputation.

[

vendor_namestring

Vendor name.

reliabilitystring

Vendor reliability.

reputationstring

Vendor reputation.

]

classstring

]

validateboolean

Whether to return an array of errors in the case of an unsuccessful update indicator API request.

REQUEST

{
  "request_data": [
    {
      "indicator": "<hash_value>",
      "type": "HASH",
      "comment": "test",
      "reputation": "GOOD",
      "reliability": "D",
      "severity": "high",
      "vendors": [
        {
          "vendor_name": "V1",
          "reliability": "A",
          "reputation": "GOOD"
        },
        {
          "vendor_name": "V2",
          "reliability": "A",
          "reputation": "SUSPICIOUS"
        }
      ],
      "class": "Malware"
    }
  ],
  "validate": true
}

Responses

Body

application/json

replyobject

JSON object containing a query result.

successboolean

Indicates if any of the IOCs were upload successfully.

validation_errorsarray

Array of the IOCs that did not upload.

[

indicatorstring

Name of the indicator that failed to upload.

errorstring

Description of the error that caused the indicator to fail upload.

]

RESPONSE

{
  "reply": {
    "success": true,
    "validation_errors": [
      {
        "indicator": "testtest.com",
        "error": "Got type: HASH, Indicator: testtest.com mismatch"
      }
    ]
  }
}

Bad Request. Got an invalid JSON.

Body

application/json

The query result upon error.

err_codestring

HTTP response code.

err_msgstring

Error message.

Example:"{\"line\": 1, \"column\": 19, \"message\": \"no viable alternative at input '|alter2'\"}"

err_extrastring

Additional information describing the error.

RESPONSE
{
  "err_code": "example",
  "err_msg": "{\"line\": 1, \"column\": 19, \"message\": \"no viable alternative at input '|alter2'\"}",
  "err_extra": "example"
}

Unauthorized access. An issue occurred during authentication. This can indicate an incorrect key, id, or other invalid authentication parameters.

Body

application/json

The query result upon error.

err_codestring

HTTP response code.

err_msgstring

Error message.

Example:"{\"line\": 1, \"column\": 19, \"message\": \"no viable alternative at input '|alter2'\"}"

err_extrastring

Additional information describing the error.

RESPONSE
{
  "err_code": "example",
  "err_msg": "{\"line\": 1, \"column\": 19, \"message\": \"no viable alternative at input '|alter2'\"}",
  "err_extra": "example"
}

Unauthorized access. User does not have the required license type to run this API.

Body

application/json

The query result upon error.

err_codestring

HTTP response code.

err_msgstring

Error message.

Example:"{\"line\": 1, \"column\": 19, \"message\": \"no viable alternative at input '|alter2'\"}"

err_extrastring

Additional information describing the error.

RESPONSE
{
  "err_code": "example",
  "err_msg": "{\"line\": 1, \"column\": 19, \"message\": \"no viable alternative at input '|alter2'\"}",
  "err_extra": "example"
}

Forbidden access. The provided API Key does not have the required RBAC permissions to run this API.

Body

application/json

The query result upon error.

err_codestring

HTTP response code.

err_msgstring

Error message.

Example:"{\"line\": 1, \"column\": 19, \"message\": \"no viable alternative at input '|alter2'\"}"

err_extrastring

Additional information describing the error.

RESPONSE
{
  "err_code": "example",
  "err_msg": "{\"line\": 1, \"column\": 19, \"message\": \"no viable alternative at input '|alter2'\"}",
  "err_extra": "example"
}

Internal server error. A unified status for API communication type errors.

Body

application/json

The query result upon error.

err_codestring

HTTP response code.

err_msgstring

Error message.

Example:"{\"line\": 1, \"column\": 19, \"message\": \"no viable alternative at input '|alter2'\"}"

err_extrastring

Additional information describing the error.

RESPONSE
{
  "err_code": "example",
  "err_msg": "{\"line\": 1, \"column\": 19, \"message\": \"no viable alternative at input '|alter2'\"}",
  "err_extra": "example"
}