Insert Simple Indicators, JSON

Insert threat indicators using an array of JSON objects.

Synopsis

URI
/public_api/v1/indicators/insert_jsons
HTTP Method
POST
Required License
Cortex XDR Pro per Endpoint

Description

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

Request Fields

The body of this request contains a JSON object with a single field:
request_data
. This field is required. Its value is an array of JSON objects, each element of which represents IOC data. Each object must include at a minimum the required fields, which are identified below.
Field
Description
request_data
(
Required
) A dictionary containing the API request fields.
indicator
(
Required
) String that identifies the indicator you want to insert into Cortex XDR.
type
(
Required
) Keyword identifying the type of indicator. Valid values are:
  • HASH
  • IP
  • PATH
  • DOMAIN_NAME
  • FILENAME
severity
(
Required
) Keyword identifying the indicator's severity. Valid values are:
  • INFO
  • LOW
  • MEDIUM
  • HIGH
expiration_date
Integer representing the indicator's expiration timestamp. This is 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 expiration date. Valid values are:
  • 7 days
  • 30 days
  • 90 days
  • 180 days
comment
Comment string.
reputation
Keyword representing the indicator's reputation. Valid values are:
  • GOOD
  • BAD
  • SUSPICIOUS
  • UNKNOWN
reliability
Character representing the indicator's reliability rating. Valid values are A - F. A is the most reliable, F is the least.
vendors
JSON array of objects representing the vendors from which this IOC was obtained. Each field in the array is:
  • vendor_name
    String representing the name of the vendor who reported this indicator.
  • reputation
    Keyword representing the vendor's reputation. Valid values are:
    • GOOD
    • BAD
    • SUSPICIOUS
    • UNKNOWN
  • reliability
    Character representing the vendor's reliability rating. Valid values are A - F. A is the most reliable, F is the least.
class
String representing the indicator class (for example, 'Malware').
validate
Boolean,
True
or
False
if whether to r return an array of errors in the case of an unsuccessful update indicator API request.
Request Example (whitespace added for readability)
curl --request POST \ --url https://api-{fqdn}/public_api/v1/indicators/insert_jsons \ --header 'authorization: {API_KEY} \ --header 'content-type: application/json' \ --header 'x-xdr-auth-id: {API_KEY_ID}' \ --data '{ "request_data": [ { "indicator": "<indicator ID>", "type": "HASH", "severity": "HIGH", "expiration_date": 1587054895000, "comment": "This is an example IOC", "reputation": "GOOD", "reliablity": "D", "vendors": [ { "vendor_name": "PANW", "reputation": "GOOD", "reliablity": "B" }, { "vendor_name": "PANW", "reputation": "SUSPICIOUS", "reliablity": "D" } ], "class": "Malware" } ] }'

Success Response

Upon success, the HTTP response code is 200.
Field
Description
reply
-— JSON object containing a query result.
success
true
—Upload successful.
validation_errors
Empty array.

Unsuccessful Response

Upon on unsuccessful request, the response includes the following fields.
Field
Description
reply
-— JSON object containing a query result.
success
false
—One or more indicators failed to upload.
validation_errors
Array of the following fields:
  • indicator
    —Name of the indicator that failed to upload.
  • error
    —Description of the error that caused the indicator to upload.
Response Example
{ "reply":{ "success":false, "validation_errors":[ { "indicator":"testtest.com", "error":"Got type: HASH, Indicator: testtest.com mismatch" } ] } }

Error Response

Upon error, the reply includes an HTTP response code, an error message, and additional information describing the error. The HTTP response code is one of the following:
Field
Description
400
Bad Request.
401
Unauthorized access. An issue occurred during authentication. This can indicate an incorrect key, id, or other invalid authentication parameters.
402
Unauthorized access. User does not have the required license type to run this API.
403
Forbidden access. The provided API Key does not have the required RBAC permissions to run this API.
500
Internal server error. A unified status for API communication type errors.
Error Response Format
{"reply": {"err_code": STATUS_CODE, "err_msg": GENERAL_MESSAGE, "err_extra": EXTRA_DATA}}

Recommended For You