Splunk® Enterprise Security

REST API Reference

Acrobat logo Download manual as PDF


This documentation does not apply to the most recent version of Splunk® Enterprise Security. For documentation on the most recent version, go to the latest release.
Acrobat logo Download topic as PDF

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.

Usage details

Authentication and Authorization

Username and password authentication is required for access to endpoints and REST operations. You must have the edit_threat_intel_collections capability to use the threat intelligence endpoints.

Alternatively, you can use token authentication. See Set up authentication with tokens in the Splunk Enterprise Securing the Splunk Platform manual.

Username and password authentication is used in the examples that follow.

Splunk Cloud Platform URL for REST API access

Splunk Cloud Platform has a different host and management port syntax than Splunk Enterprise. Depending on your deployment type, use one of the following options to access REST API resources.

Splunk Cloud Platform deployments

https://<deployment-name>.splunkcloud.com:8089

To get the required credentials, submit a support case on the Support Portal. After installing the credentials, use the following URL.

https://input-<deployment-name>.splunkcloud.com:8089

See Using the REST API in Splunk Cloud Platform in the the Splunk REST API Tutorials for more information.

/services/data/threat_intel/upload

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

The REST API endpoint only uploads the threat intelligence file. To configure threat intelligence, you must define the [threatlist] stanza in the inputs.conf configuration file. For more information on configuring threat intelligence, see Configure Global Threat List Settings.

Syntax

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

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

POST

Upload a file.

Request parameters

Field Type Default Description
content
required
String The threat Intelligence file content encoded in base64 format.
filename
required
String The threat intelligence file name, with extension. Format: __threat_<name>.dmy
overwrite Boolean true 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.
max_size bytes 524288000 or 500 MB The maximum size of the file that is uploaded.

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 -ku admin:changeme https://localhost:8089/services/data/threat_intel/upload -d '{"filename": "__threat_example.dmy", "overwrite": true, "content": "dGhpcyBpcyBhIHRlc3Q="}' -H "Content-Type: application/json" -X POST

Example response

{"message": "File uploaded successfully.", "success": true, "internal_status": 0}


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

Perform CRUD 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

Some methods require the _key field. To find the key for a row 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 row. For example:

| inputlookup ip_intel | eval item_key=_key

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 1: request
Retrieve a single intelligence item.

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 1: response
A single intelligence item is returned.

{"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}

Example 2: request
Retrieve multiple intelligence items.

curl -k -u admin:pass https://localhost:8089/services/data/threat_intel/item/ip_intel -d item='[{"ip":"5.5.5.5"},{"domain":"example.com"}]' -G -X GET

Example 2: response
Multiple intelligence items are returned.

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

PUT

Update one or more rows in a collection.

Request parameters

Field Type Default Description
item
required
JSON encoded string The field/value pairs to update in one or more rows in a collection, accompanied by the _key for those rows. To update multiple rows with a single call, separate the JSON encoded strings with commas inside a set of brackets.
autofill_time_field
optional
epoch true When set to "false", provides the current time for each row that you add to the KVStore collection. The value provided in this field is used for retention to phase out unused items instead of ingestion time. When set to "true" or if no value is provided, the time is automatically set for each row to the current time.

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. The item field must also contain the _key value(s) of the rows you want to modify, in a JSON encoded string. You can update a single row or multiple rows.

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:pass https://localhost:8089/services/data/threat_intel/item/email_intel -d item='[{"src_user": "user_new1", "subject":"click this new update", "time": 1620762180, "_key":"126b0fd6d5c548fbb9a31107a4acddc1"}, {"src_user": "user_new2", "subject":"click this update", "time": 1620762180, "_key":"46cdf4a3579244f4a409c69af02d5101"}]' -d autofill_time_field="false" -X PUT

Example response

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


POST

Create one or more rows 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. To create multiple rows with a single call, separate the JSON encoded strings with commas inside a set of brackets.
Examples:
{'file_name':'threat.trt', 'file_extension':'trt'} creates one new row that has file_name=threat.trt and file_extension=trt.

{'ip':'41.41.41.41'} creates one new row with ip=41.41.41.41.

[{'ip':'41.41.41.41'}, {'ip':'10.10.10.10'}] creates two new rows: one with ip=41.41.41.41 and the other with ip=10.10.10.10.

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.
autofill_time_field
optional
epoch true

When set to "false", provides the current time for each row that you add to the KVStore collection. The value provided in this field is used for retention to phase out unused items instead of ingestion time. When set to "true" or if no value is provided, the time is automatically set for each row to the current time.

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

Create a single row.

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

Create two rows.

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

Example response

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


DELETE

Delete one or more rows from a collection.

Request parameters

Field Type Default Description
item
required
JSON encoded string The _key values of the rows to delete from a threat collection.

Data payload
The item field must contain _key values of the rows you intend to delete in a threat collection, in a JSON encoded string. You can delete a single row or multiple rows.

Response

The endpoint returns one of two responses:

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

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


Example request

curl -k -u admin:changeme https://localhost:8089/services/data/threat_intel/item/email_intel -d item='[{"_key":"2e58177235804a739d4d768c26077b24"},{"_key":"2e58177235804a739d4d768c26077bd4"}]' -G -X DELETE

Example response

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


/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 a row 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 row. 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.
autofill_time_field
optional
epoch true When set to "false", provides the current time for each row that you add to the KVStore collection. The value provided in this field is used for retention to phase out unused items instead of ingestion time. When set to "true" or if no value is provided, the time is automatically set for each row to the current time.

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/7bce624696ad4bc48cc781d8c8204c8f -d item='{"src_user": "user_new1", "subject":"click this!", "time": 123123123}' -d autofill_time_field="false" -X PUT

Example response

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


POST

Create one or more rows in a collection.

Request parameters

Field Type Default Description
autofill_time_field
optional
boolean true When set to "false", provides a valid time for each row that you add to the KVStore collection. The value provided in this field is used for retention to phase out unused items instead of ingestion time. When set to "true" or if no value is provided, the time is automatically set for each row to the current time.

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}


Last modified on 29 January, 2022
PREVIOUS
The Splunk Enterprise Security API
  NEXT
Notable Event API reference

This documentation applies to the following versions of Splunk® Enterprise Security: 4.7.3, 4.7.4, 4.7.5, 4.7.6, 5.0.0, 5.0.1, 5.1.0, 5.1.1, 5.2.0, 5.2.1, 5.2.2, 5.3.0, 5.3.1, 6.0.0, 6.0.1, 6.0.2, 6.1.0, 6.1.1, 6.2.0, 6.3.0 Cloud only, 6.4.0, 6.4.1, 6.5.0 Cloud only, 6.5.1 Cloud only, 6.6.0, 6.6.2


Was this documentation topic helpful?


You must be logged into splunk.com in order to post comments. Log in now.

Please try to keep this discussion focused on the content covered in this documentation topic. If you have a more general question about Splunk functionality or are experiencing a difficulty with Splunk, consider posting a question to Splunkbase Answers.

0 out of 1000 Characters