Threat Intelligence API reference

Access the Threat Intelligence framework in Splunk Enterprise Security.

The Threat Intelligence framework is a mechanism for consuming and managing threat feeds, detecting threats, and alerting. For more information about working with the framework, see Threat Intelligence framework in Splunk ES.

/data/threat_intel/upload

Upload a threat intelligence file in STIX, IOC, or CSV format.

Syntax

https://<host>:<mPort>/data/threat_intel/upload

Usage details
For details of how Splunk Enterprise Security processes threat intelligence files, see Threat Intelligence framework in Splunk ES.

POST

Upload a file.

Request parameters

Field	Type	Default	Description
encoded_content required	String		The threat Intelligence file content encoded in base64 format.
file_name required	String		The threat intelligence file name, with extension.
weight required	Integer		The relative weight assigned to this source of threat intelligence, used for risk score calculations in notable events. Most threat intelligence sources have a weight of 1.
threat_group required for CSV only	String		The threat group to which this threat intelligence belongs. Optional for IOC and STIX files because the parser can extract this value from the file itself. Required for CSV files.
threat_category required for CSV only	String		The threat category to which this threat intelligence belongs. Optional for IOC and STIX files because the parser can extract this value from the file itself. Required for CSV files.
overwrite	Boolean	false	If set to true and a file with this name already exists, the API overwrites the file and reports success. If set to false and a file with this name already exists, the API returns an error.

Data payload
A JSON-encoded string with the arguments.

Response

The endpoint returns a success or failure message, with HTTP status codes.

Example request

curl -k -u admin:changeme https://localhost:8089/services/data/threat_intel/upload -d '{"file_name":"threat.xml", "encoded_content":"aXAsZGVzY3JpcHRpb24KMTQzLjMuMi4zLHRlc3QK<truncated for brevity>", "weight":"10", "threat_category":"APT", "threat_group":"APT", "overwrite":"true"}'  -H "Content-Type: application/json" -X POST

Example response

{"success":true,"message":"Uploaded successfully."}

/services/data/threat_intel/item/{threat_intel_collection}

Perform create and read operations on an existing threat intelligence collection.

Syntax

https://<host>:<mPort>/services/data/threat_intel/item/{threat_intel_collection}

Usage details
The collection name must be one of the following:

• ip_intel
• file_intel
• user_intel
• http_intel
• email_intel
• service_intel
• process_intel
• registry_intel
• certificate_intel

GET

List one or more rows from a collection.

Request parameters

Field	Type	Default	Description
item required	JSON encoded string		The field/value pairs to match. For example, {'ip':'41.41.41.41'} returns rows that have ip=41.41.41.41 and {'file_name':'threat.trt', 'file_extension':'trt'} returns all the rows that match file_name=threat.trt and file_extension=trt.

Data payload
The item field must contain at least one of the important fields for the threat collection to use as search criteria, in a JSON encoded string.

Collection name	Important fields
user_intel	user
file_intel	file_name, file_hash
ip_intel	ip, domain
http_intel	http_user_agent, ip, http_referrer, url, domain
email_intel	embedded_domain, src_user, subject, file_hash, file_name, embedded_ip
service_intel	service_file_hash, service_dll_file_hash, service_dll_file_name, service_file_name, service
process_intel	dest, src, process_file_name, process
registry_intel	registry_path, registry_value_name, registry_value_text, user
certificate_intel	certificate_issuer_common_name, certificate_subject_common_name, certificate_common_name, certificate_issuer_organization, certificate_subject_organization, certificate_serial, certificate_issuer, certificate_subject, certificate_issuer_unit, certificate_subject_unit, certificate_issuer_email, certificate_subject_email, ip, domain

Response

If the request is successful, the endpoint returns all the rows that match the values supplied in the item parameter. If the request fails, the endpoint returns an error message.

Example request

curl -k -u admin:pass https://localhost:8089/services/data/threat_intel/item/ip_intel  -d item='{"ip":"10.10.1.1 "}'  -G -X  GET

Example response

{"message": [{"_user": "nobody", "time": 1481566235.98246, "threat_key": "fireeye:stix-b7b16e67-4292-46a3-ba64-60c1a491723d|stix_file.xml.xml", "ip": "10.10.1.1", "_key": "fireeye:stix-b7b16e67-4292-46a3-ba64-60c1a491723d:fireeye:observable-00375905-04b4-4255-b453-2a5875c20b6d"}], "status": true}

POST

Create a row in a collection.

Request parameters

Field	Type	Default	Description
item required	JSON encoded string		The field/value pairs to insert as a new row in a collection. For example, {'ip':'41.41.41.41'} creates a new row with ip=41.41.41.41 and {'file_name':'threat.trt', 'file_extension':'trt'} creates a row that has file_name=threat.trt and file_extension=trt. See the Data payload information for a list of important fields. The item must include at least one of the important fields for the relevant collection name, or the API returns an error.

Data payload
The item field must contain at least one of the important fields for the threat collection being modified, in a JSON encoded string.

Collection name	Important fields
user_intel	user
file_intel	file_name, file_hash
ip_intel	ip, domain
http_intel	http_user_agent, ip, http_referrer, url, domain
email_intel	embedded_domain, src_user, subject, file_hash, file_name, embedded_ip
service_intel	service_file_hash, service_dll_file_hash, service_dll_file_name, service_file_name, service
process_intel	dest, src, process_file_name, process
registry_intel	registry_path, registry_value_name, registry_value_text, user
certificate_intel	certificate_issuer_common_name, certificate_subject_common_name, certificate_common_name, certificate_issuer_organization, certificate_subject_organization, certificate_serial, certificate_issuer, certificate_subject, certificate_issuer_unit, certificate_subject_unit, certificate_issuer_email, certificate_subject_email, ip, domain

Response

The endpoint returns one of two responses:

{"status": true, "message": "Create operation successful."}

{"status": false, "message": <failure_cause>}

Example request

curl -k -u admin:changeme https://localhost:8089/services/data/threat_intel/item/email_intel -d item='{"src_user": "user_new", "subject":"click this"}'

Example response

{"status": true, "message": "Create operation successful."}

/services/data/threat_intel/item/{threat_intel_collection}/{item_key}

Perform read, update, and delete operations on a row of an existing threat intelligence collection.

Syntax

https://<host>:<mPort>/services/data/threat_intel/item/{threat_intel_collection}/{item_key}

Usage details

The threat_intel_collection must be one of the following:

• ip_intel
• file_intel
• user_intel
• http_intel
• email_intel
• service_intel
• process_intel
• registry_intel
• certificate_intel

The item_key must be a valid key. To find the key for an entry in a collection, run a search using the inputlookup command and the relevant threat_intel_collection and use eval to display the _key field for each item. For example:

| inputlookup ip_intel | eval item_key=_key

GET

Access a row from a collection.

Request parameters
None

Data payload
None

Response

The endpoint returns one of two responses:

{"message":<The row of the collection you requested, as a JSON object>, "status": true}

{"message": "No matching entries found in kvstore.", "status": false}

Example request

curl -k -u admin:changeme https://localhost:8089/services/data/threat_intel/item/ip_intel/fireeye:stix-b7b16e67-4292-46a3-ba64-60c1a491723d:fireeye:observable-00375905-04b4-4255-b453-2a5875c20b6d

Example response

{"message": [{"_user": "nobody", "time": 1481566235.98246, "threat_key": "fireeye:stix-b7b16e67-4292-46a3-ba64-60c1a491723d|stix_file.xml.xml", "ip": "58.64.179.144", "_key": "fireeye:stix-b7b16e67-4292-46a3-ba64-60c1a491723d:fireeye:observable-00375905-04b4-4255-b453-2a5875c20b6d"}], "status": true}

PUT

Update a row in a collection.

Request parameters

Field	Type	Default	Description
item required	JSON encoded string		The field/value pairs in the row to be updated. For example, {'ip':'41.41.41.41'} updates the ip to 41.41.41.41. See the Data payload information for a list of important fields. The item must include at least one of the important fields for the relevant collection name, or the API returns an error.

Data payload
The item field must contain at least one of the important fields for the threat collection being modified.

Collection name	Important fields
user_intel	user
file_intel	file_name, file_hash
ip_intel	ip, domain
http_intel	http_user_agent, ip, http_referrer, url, domain
email_intel	embedded_domain, src_user, subject, file_hash, file_name, embedded_ip
service_intel	service_file_hash, service_dll_file_hash, service_dll_file_name, service_file_name, service
process_intel	dest, src, process_file_name, process
registry_intel	registry_path, registry_value_name, registry_value_text, user
certificate_intel	certificate_issuer_common_name, certificate_subject_common_name, certificate_common_name, certificate_issuer_organization, certificate_subject_organization, certificate_serial, certificate_issuer, certificate_subject, certificate_issuer_unit, certificate_subject_unit, certificate_issuer_email, certificate_subject_email, ip, domain

Response

The endpoint returns one of two responses:

{"status": true, "message": "Update operation successful."}

{"status": false, "message": <failure_cause>}

Example request

curl -k -u admin:changeme https://localhost:8089/services/data/threat_intel/item/email_intel/e83fa2c5036d4c85bd5669a48ca134c5 -d item='{"src_user": "user_new1", "subject":"click this"}' -X PUT

Example response

{"status": true, "message": "Update operation successful."}

DELETE

Delete a row from a collection.

Usage details
The delete operation does not delete the row from the KV Store. Instead, the entry is disabled from participating in threat intelligence matching.

Request parameters
None

Data payload
None

Response

The endpoint returns one of two responses:

{"message": "Delete operation successful.", "status": true}

{"message": <failure_reason>, "status": false}

Example request

curl -k -u admin:changeme https://localhost:8089/services/data/threat_intel/item/email_intel/af8e379623f643a3be149c014b977e6b -X DELETE

Example response

{"message": "Delete operation successful.", "status": true}