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}
The Splunk Enterprise Security API | Notable Event API reference |
This documentation applies to the following versions of Splunk® Enterprise Security: 7.0.1, 7.0.2, 7.1.0, 7.1.1, 7.1.2, 7.2.0, 7.3.0, 7.3.1, 7.3.2
Feedback submitted, thanks!