Welcome to the Threat Response Extensibility Documentation
Threat Response is designed to work in many IT Security and Security Operations Center environments - small, medium, or large. The product was designed with extensibility in mind and we have built multiple tools that allow for ease of integration with 3rd party security products. In this document we will look at the following extensibility components:
THREAT RESPONSE API
Threat Response provides rich API functionality and supports customizations and custom integrations through the following options:
- List Management API: Threat Response allows users to add, edit, and remove members from lists via HTTP request.
- Incident API: Threat Response provides APIs to retrieve incident details, retrieve incidents in bulk, or add comments or users to an incident.
- Custom Response API: Threat response allows administrators to create custom responses that can be used during the incident investigation process.
JSON ALERT SOURCE
Threat Response allows users to ingest custom 3rd party alerts using REST API and JSON data format
ETL SCRIPTING (Extract, Transform, Load)
Threat Response allows users to write custom Python scripts to ingest alert data from sources not natively supported by the platform.
CUSTOM POWERSHELL SCRIPTS
Threat Response allows users to run custom PowerShell scripts to perform actions or collect data from Windows endpoints.
Complete Threat Response documentation is located here:
Threat Response Documentation Portal.
Threat Response API
'GET /api/lists/{list_id}/{members_type}'
'GET /api/lists/{list_id}/members/{member_id}.json'
'POST /api/lists/{list_id}/members.json'
'PUT /api/lists/{list_id}/members/{member_id}.json'
'DELETE /api/lists/{list_id}/members/{member_id}.json'
'GET /api/incidents/{incident_id}.json'
'GET /api/incidents/?{state}&{created_after}&{created_before}'
'POST /api/incidents/{incident_id}/comments.json'
'POST /api/incidents/{incident_id}/users.json'
'GET /api/lists/{list_id}/{members_type}'
'GET /api/lists/{list_id}/members/{member_id}.json'
'POST /api/lists/{list_id}/members.json'
'PUT /api/lists/{list_id}/members/{member_id}.json'
'DELETE /api/lists/{list_id}/members/{member_id}.json'
'GET /api/incidents/{incident_id}.json'
'GET /api/incidents/?{state}&{created_after}&{created_before}'
'POST /api/incidents/{incident_id}/comments.json'
'POST /api/incidents/{incident_id}/users.json'
In this section we will look at the Threat Response API functionality and cover endpoints for:
- List API
- Incident API
- Custom Response API
Authentication
Starting with the Threat Response 3.0.0 release, Threat Response has stopped basic authentication for API access. Threat Response only supports API access via API keys that must be generated one per application that is connecting to Threat Response using REST APIs.
In order to generate an API Key, proceed with the following steps:
- Navigate to
System Settings > Customization > API Keys - Click on
(+)icon next to API Keys heading - Provide the
nameof your application and check the“Enabled”checkbox - Click
“Save”
After you have saved, Threat Response will generate the API Token and add it to the API Keys table.
The following API endpoints require token authentication:
| API type | Auth required? |
|---|---|
| List management API | Yes |
| Incident API | Yes |
| Custom Response API | No |
Here is an example of how the API token must be used:
curl -X GET --header 'Accept: application/json' --header 'Authorization: API TOKEN GOES HERE' 'https://172.16.84.128/api/lists/2/members.json' -v -k
import requests, json
r = requests.get('https://172.16.84.128/api/lists/2/members.json',
headers={'Authorization': 'YOUR TOKEN GOES HERE'}, verify=False)
json_object = json.dumps(r.json(), indent=4)
print(json_object)
Once you have generated the API key for your application, you must pass the API Token with each REST API call to Threat Response appliance. The API Token for your appliance is available in the API Keys table.
List management API
One of the fundamental blocks of Threat Response is the concept of Lists. Lists are used to add hosts/hashes/urls to them and then block those atomic indicators on the enforcement devices. Threat Response exposes lists management functionality though the API.
To perform actions on a list, you must first obtain the identification number (list-id) for that list in Threat Response. The steps below describe how to locate the ID:
- Log in to Threat Response.
- Navigate to the
Listspage (and to the sub-tab for the list you are looking for). - Click on the desired list to display the list details.
- Review the URL in your browser’s address bar; the ID will be at the end of the URL.
Get all list members
Request example below:
curl -X GET --header 'Accept: application/json' --header 'Authorization: c02d2dde-0d91-4f36-97dc-a9cd75784a40' 'https://172.16.84.128/api/lists/2/members.json' -v -k
import requests, json
r = requests.get('https://172.16.84.128/api/lists/2/members.json',
headers={'Authorization': 'c02d2dde-0d91-4f36-97dc-a9cd75784a40'}, verify=False)
json_object = json.dumps(r.json(), indent=4)
print(json_object)
The above command returns JSON structured like this:
[
{
"id": 8,
"list_id": 2,
"host_id": 20,
"response_id": null,
"reverse_user_id": null,
"hash_reputation_id": null,
"user_id": null,
"enabled": true,
"deleted": false,
"description": "IP to block",
"expiration": "2018-12-18T19:08:56Z",
"created_at": "2017-01-11T03:47:15Z",
"updated_at": "2017-01-11T03:47:15Z",
"host": {
"created_at": "2017-01-11T03:47:15Z",
"host": "75.76.13.144",
"id": 20,
"resolution_state": 4,
"ttl": 0,
"updated_at": "2017-01-11T03:47:15Z"
}
},
{
"id": 6,
"list_id": 2,
"host_id": 6,
"response_id": null,
"reverse_user_id": null,
"hash_reputation_id": null,
"user_id": null,
"enabled": true,
"deleted": false,
"description": "test",
"expiration": null,
"created_at": "2017-01-11T03:43:54Z",
"updated_at": "2017-01-11T03:43:54Z",
"host": {
"created_at": "2016-12-29T04:56:13Z",
"host": "string",
"id": 6,
"resolution_state": 4,
"ttl": 0,
"updated_at": "2017-01-13T00:45:16Z"
}
}
]
Retrive all the members of a Threat Response list. List can be host list, url list, user list, of file list. You can also specify what type of information you want to get in return, by specifying the members_type path parameter
HTTPs Request
GET /api/lists/{list_id}/{members_type}
Request parameters
| Parameter | Description | Data type | Parameter type | Required? |
|---|---|---|---|---|
| list_id | The id value of list | integer | path | yes |
| Authorization | Authentication token | string | header | yes |
| members_type | The information format to get in return. Available options include: - members.pan (for published lists) - members.bluecoat (for published lists) - members.json |
integer | path | yes |
Get single list member
Request example below:
curl -X GET --header 'Accept: application/json' --header 'Authorization: c02d2dde-0d91-4f36-97dc-a9cd75784a40' 'https://172.16.84.128/api/lists/2/members/6.json' -v -k
import requests, json
r = requests.get('https://172.16.84.128/api/lists/2/members/6.json',
headers={'Authorization': 'c02d2dde-0d91-4f36-97dc-a9cd75784a40'}, verify=False)
json_object = json.dumps(r.json(), indent=4)
print(json_object)
The above command returns JSON structured like this:
{
"id": 6,
"list_id": 2,
"host_id": 6,
"response_id": null,
"reverse_user_id": null,
"hash_reputation_id": null,
"user_id": null,
"enabled": true,
"deleted": false,
"description": "test",
"expiration": null,
"created_at": "2017-01-11T03:43:54Z",
"updated_at": "2017-01-11T03:43:54Z",
"host": {
"created_at": "2016-12-29T04:56:13Z",
"host": "string",
"id": 6,
"resolution_state": 4,
"ttl": 0,
"updated_at": "2017-01-13T00:42:16Z"
}
}
Retrive a single member record from a list, by specifying the member id.
HTTPs Request
GET /api/lists/{list_id}/members/{member_id}.json
Request parameters
| Parameter | Description | Data type | Parameter type | Required? |
|---|---|---|---|---|
| list_id | The id value of list | integer | path | yes |
| Authorization | Authentication token | string | header | yes |
| member_id | id of the list member to retrieve | integer | path | yes |
Add member to list
Request example below:
curl -X POST --header 'Content-Type: application/json' --header 'Accept: application/json' --header 'Authorization: 93096c62-21aa-4f09-8a79-453787dd6e1c' -d '{"member": "175.76.13.144","description": "IP to block", "expiration": "2018-12-18 18:59:51.545783"}' 'https://10.10.108.220/api/lists/2/members.json' -v -k
import requests, json
json_body = {'member': '75.76.13.144',
'description': 'IP to block',
'expiration': '2018-12-18 18:59:51.545783'}
r = requests.post('https://172.16.84.128/api/lists/2/members.json',
headers={'Authorization': 'c02d2dde-0d91-4f36-97dc-a9cd75784a40'},
verify=False, data=json.dumps(json_body))
json_object = json.dumps(r.json(), indent=4)
print(json_object)
The above command returns JSON structured like this:
{
"id": 8,
"list_id": 2,
"host_id": 20,
"response_id": null,
"reverse_user_id": null,
"hash_reputation_id": null,
"user_id": null,
"enabled": true,
"deleted": false,
"description": "IP to block",
"expiration": "2018-12-18T19:08:56Z",
"created_at": "2017-01-11T03:47:15Z",
"updated_at": "2017-01-11T03:47:15Z",
"host": {
"created_at": "2017-01-11T03:47:15Z",
"host": "75.76.13.144",
"id": 20,
"resolution_state": 4,
"ttl": 0,
"updated_at": "2017-01-11T03:47:15Z"
}
}
In the second example, we can perform bulk hash upload to the file list. You can create a json file / python dictionary and then upload to Threat Response. The contents of the json file / python dictionary in our example can be specified as follows:
[
{
"hashes": [
"221eeb322a71509d3cc3afe92c4a70453b478e18c7e353c95ba82642bf91911e",
"fedaaa1e53d8cdcb1ec3c85fe6197a28"
],
"md5_hash": [
"fddaaa1e53d8cdcb1ec3c85fe6197a28"
],
"duration": 800000,
"desc": "1st batch"
},
{
"md5_hash": [
"facbbbd7c5aafb08d95f5d36a4e57e26"
],
"desc": "2nd batch"
}
]
The request example is shown below:
curl -X POST --header "Content-Type: application/json" --header "Authorization: c02d2dde-0d91-4f36-97dc-a9cd75784a40" -d@md5.json "https://172.16.84.128/api/lists/5/members.json" -v -k
import requests, json
json_body = [
{'hashes': ['221eeb322a71509d3cc3afe92c4a70453b478e18c7e353c95ba82642bf91911e',
'fedaaa1e53d8cdcb1ec3c85fe6197a28'],
'md5_hash': ['fddaaa1e53d8cdcb1ec3c85fe6197a28'],
'duration': '800000',
'desc': '1st batch'},
{'md5_hash': ['facbbbd7c5aafb08d95f5d36a4e57e26'],
'desc': '2nd batch'}]
r = requests.post('https://172.16.84.128/api/lists/5/members.json',
headers={'Authorization': 'c02d2dde-0d91-4f36-97dc-a9cd75784a40'},
verify=False, data=json.dumps(json_body))
print(r.text)
The response wil be similar to:
'Successfully added 4 members to list id 5'
'Successfully added 4 members to list id 5'
Add host, IP address, or URL to a list. List can be host list, url list, user list, of file list.
HTTPs Request
POST /api/lists/{list_id}/members.json
Request parameters
| Parameter | Description | Data type | Parameter type | Required? |
|---|---|---|---|---|
| list_id | The id value of list | integer | path | yes |
| Authorization | Authentication token | string | header | yes |
| member | List member to add | string | body | yes |
| description | Short description of list member | string | body | no |
| expiration | Timestamp to expire member. Format: 2017-01-11T03:47:15Z | string | body | no |
| duration | # of milliseconds after which to expire membership. Expiration takes precedence. | string | body | no |
Update member of list
Request example below:
curl -X PUT --header "Content-Type: application/json" --header "Authorization: c02d2dde-0d91-4f36-97dc-a9cd75784a40" -d "{"description":"Hello PTR", "expiration":"2017-12-03 10:15:30.555"}" "https://172.16.84.128/api/lists/2/members/4.json" -v -k
import requests, json
json_body = {'description':'Hello PTR', 'expiration': '2017-12-03 10:15:30.555'}
r = requests.put('https://172.16.84.128/api/lists/2/members/4.json',
headers={'Authorization': 'c02d2dde-0d91-4f36-97dc-a9cd75784a40'},
verify=False, data=json.dumps(json_body))
json_object = json.dumps(r.json(), indent=4)
print(json_object)
The above command returns JSON structured like this:
{
"id": 4,
"list_id": 2,
"host_id": 4,
"response_id": null,
"reverse_user_id": null,
"hash_reputation_id": null,
"user_id": null,
"enabled": true,
"deleted": false,
"description": "Hello PTR",
"expiration": "2017-12-03T10:15:30Z",
"created_at": "2016-12-29T01:52:33Z",
"updated_at": "2017-01-13T00:55:27Z",
"host": {
"created_at": "2016-12-29T01:52:33Z",
"host": "7.7.7.7",
"id": 4,
"resolution_state": 4,
"ttl": 0,
"updated_at": "2016-12-29T01:52:33Z"
}
}
Update the member of the list by specifying the list and the member to update.
HTTPs Request
PUT /api/lists/{list_id}/members/{member_id}.json
Request parameters
| Parameter | Description | Data type | Parameter type | Required? |
|---|---|---|---|---|
| list_id | The id value of list | integer | path | yes |
| Authorization | Authentication token | string | header | yes |
| member_id | id of the list member to retrieve | integer | path | yes |
Delete member of list
Request example below:
curl -X DELETE --header "Content-Type: application/json" --header "Authorization: c02d2dde-0d91-4f36-97dc-a9cd75784a40" "https://172.16.84.128/api/lists/2/members/4.json" -v -k
import requests, json
r = requests.delete('https://172.16.84.128/api/lists/2/members/4.json',
headers={'Authorization': 'c02d2dde-0d91-4f36-97dc-a9cd75784a40'}, verify=False)
print(r.status_code)
The above command returns “200 OK” in case of success.
Delete the member of the list by specifying the list_id and the member_id to delete
HTTPs Request
DELETE /api/lists/{list_id}/members/{member_id}.json
Request parameters
| Parameter | Description | Data type | Parameter type | Required? |
|---|---|---|---|---|
| list_id | The id value of list | integer | path | yes |
| Authorization | Authentication token | string | header | yes |
| member_id | id of the list member to retrieve | integer | path | yes |
Incident API
Incident API is used to retrieve information about incidents, as well as manipulate incident data, such as add comments to existing incident.
Get incident details
Request example below:
curl -X GET --header 'Accept: application/json' --header 'Authorization: c02d2dde-0d91-4f36-97dc-a9cd75784a40' 'https://172.16.84.128/api/incidents/3.json' -v -k
import requests, json
r = requests.get('https://172.16.84.128/api/incidents/3.json',
headers={'Authorization': 'c02d2dde-0d91-4f36-97dc-a9cd75784a40'}, verify=False)
json_object = json.dumps(r.json(), indent=4)
print(json_object)
The above command returns JSON structured like this:
{
"id": 1,
"type": "Malware",
"summary": "Unsolicited Bulk Email",
"description": "EvilScheme test message",
"score": 4200,
"state": "Open",
"created_at": "2018-05-26T21:07:17Z",
"false_positive_count": 0,
"event_count": 3,
"event_sources": [
"Proofpoint TAP"
],
"users": [
"nbadguy"
],
"assignee": "Unassigned",
"team": "Unassigned",
"hosts": {
"attacker": [
"54.214.13.31",
"http://tapdemo.evilscheme.org/files/313532373336373133382e33.pdf"
],
"forensics": [
"http://tapdemo.evilscheme.org/files/313532373336373133382e33.pdf",
"tapdemo.evilscheme.org"
]
},
"incident_field_values": [
{
"name": "Attack Vector",
"value": "Email"
},
{
"name": "Classification",
"value": "Spam"
},
{
"name": "Severity",
"value": "Critical"
},
],
"events": [
{
"id": 3,
"category": "malware",
"severity": "Info",
"source": "Proofpoint TAP",
"threatname": "Infection.PDF.File.Exploit.CVE-2010-0188_LibTIFF.",
"classified": false,
"state": "Linked",
"description": "Infection.PDF.File.Exploit.CVE-2010-0188_LibTIFF.",
"attackDirection": "inbound",
"received": "2018-05-26T21:07:17Z",
"malwareName": "Infection.PDF.File.Exploit.CVE-2010-0188_LibTIFF."
},
{
"id": 1,
"category": "spam",
"severity": "Critical",
"source": "Proofpoint TAP",
"threatname": "Unsolicited Bulk Email",
"classified": false,
"state": "Linked",
"attackDirection": "inbound",
"received": "2018-05-26T21:07:17Z"
},
{
"id": 2,
"category": "spam",
"severity": "Critical",
"source": "Proofpoint TAP",
"threatname": "Unsolicited Bulk Email",
"classified": false,
"state": "Linked",
"attackDirection": "inbound",
"received": "2018-05-26T21:07:17Z"
}
],
"comments": [
{
"user": "soc-mgr",
"comment": "This incident needs to be prioritized.",
"commented_on": "2019-09-12T13:58:32Z"
},
{
"user": "soc-1",
"comment": "Email needs to be quarantined.",
"commented_on": "2019-09-12T14:00:20Z"
}
],
"quarantine_results": [],
"successful_quarantines": 0,
"failed_quarantines": 0,
"pending_quarantines": 0
}
Here’s what the JSON structured response would like for the above incident, if it were in Closed state:
{
"id": 1,
"type": "Malware",
"summary": "Unsolicited Bulk Email",
"description": "EvilScheme test message",
"score": 4200,
"state": "Closed",
"created_at": "2018-05-26T21:07:17Z",
"closed_at": "2018-05-28T09:54:17Z",
"close_description": "Closing comment - Email has been quarantined",
"event_count": 3,
"false_positive_count": 0,
"event_sources": [
"Proofpoint TAP"
],
...
}
Retrieve incident metadata from Threat Response.
HTTPs Request
GET /api/incidents/{incident_id}.json
Request parameters
| Parameter | Description | Data type | Parameter type | Required? |
|---|---|---|---|---|
| incident_id | The id value of incident to retrieve | integer | path | yes |
| Authorization | Authentication token | string | header | yes |
| expand_events | Get incident with events data expanded Values can be: - true (default) - false |
string | query | no |
For a closed incident, the following additional fields are returned in the response:
| Field Name | Description | Data type |
|---|---|---|
| closed_at | Time at which incident was closed | string |
| close_description | Comment added when closing the incident | string |
Retrieve incidents
Request example below:
curl -X GET -k --header 'Accept: application/json' --header 'Authorization: 869b062a-44d4-490b-a1dd-69075935a385' 'https://172.16.84.128/api/incidents?state=open' -v -k
import requests, json
r = requests.get('https://172.16.84.128/api/incidents', params={'state': 'open'},
headers={'Authorization': '869b062a-44d4-490b-a1dd-69075935a385'}, verify=False)
print(r.status_code)
json_object = json.dumps(r.json(), indent=4)
print(json_object)
The above command returns JSON structured like this:
[
{
"id": 1,
"type": "Malware",
"summary": "Unsolicited Bulk Email",
"description": "EvilScheme test message",
"score": 4200,
"state": "Open",
"created_at": "2018-05-26T21:07:17Z",
"event_count": 3,
"event_sources": [
"Proofpoint TAP"
],
"users": [
"nbadguy"
],
"assignee": "Unassigned",
"team": "Unassigned",
"hosts": {
"attacker": [
"54.214.13.31",
"http://tapdemo.evilscheme.org/files/313532373336373133382e33.pdf"
],
"forensics": [
"http://tapdemo.evilscheme.org/files/313532373336373133382e33.pdf",
"tapdemo.evilscheme.org"
]
},
"incident_field_values": [
{
"name": "Attack Vector",
"value": "Email"
},
{
"name": "Classification",
"value": "Spam"
},
{
"name": "Severity",
"value": "Critical"
}
],
"events": [
{
"id": 3,
"category": "malware",
"severity": "Info",
"source": "Proofpoint TAP",
"threatname": "Infection.PDF.File.Exploit.CVE-2010-0188_LibTIFF.",
"classified": false,
"state": "Linked",
"description": "Infection.PDF.File.Exploit.CVE-2010-0188_LibTIFF.",
"attackDirection": "inbound",
"received": "2018-05-26T21:07:17Z",
"malwareName": "Infection.PDF.File.Exploit.CVE-2010-0188_LibTIFF."
},
{
"id": 1,
"category": "spam",
"severity": "Critical",
"source": "Proofpoint TAP",
"threatname": "Unsolicited Bulk Email",
"classified": false,
"state": "Linked",
"attackDirection": "inbound",
"received": "2018-05-26T21:07:17Z"
},
{
"id": 2,
"category": "spam",
"severity": "Critical",
"source": "Proofpoint TAP",
"threatname": "Unsolicited Bulk Email",
"classified": false,
"state": "Linked",
"attackDirection": "inbound",
"received": "2018-05-26T21:07:17Z"
}
],
"quarantine_results": [],
"successful_quarantines": 0,
"failed_quarantines": 0,
"pending_quarantines": 0
},
{
"id": 2,
"type": "Reported-abuse",
"summary": "Unsolicited Bulk Email",
"description": "",
"score": 5200,
"state": "Open",
"created_at": "2018-06-01T17:57:09Z",
"event_count": 2,
"event_sources": [
"Abuse Mailbox 1",
"Proofpoint TAP"
],
"users": [],
"assignee": "Unassigned",
"team": "Unassigned",
"hosts": {
"attacker": [
"54.214.13.31",
"http://tapdemo.evilscheme.org/files/313532373837353631342e3137.pdf"
],
"cnc": [
"54.214.13.31"
],
"url": [
"http://tapdemo.evilscheme.org/files/313532373837353631342e3137.pdf",
"https://urldefense.proofpoint.com/v2/url?u=http-3A__tapdemo.evilscheme.org_files_313532373837353631342e3137.pdf&d=DwMBAg&c=iwluXPtBMDye_7UHm8BbHNhgJ2spJfG0G_Q5BwBe3AQ&r=zo9nQ1F7O9QiDphB0J9hvAhz521RbrdV9nCXSkiNU_g&m=7wroSca_eZ7TP3t47x-Q6n9tm1ABRvkUGBwwUvdvb6I&s=xTtBtrXodsTPyBwCFIDGBJxCvLCJXaYaiPQa1uSx6cs&e="
],
"forensics": [
"http://tapdemo.evilscheme.org/files/313532373837353631342e3137.pdf",
"tapdemo.evilscheme.org"
]
},
"incident_field_values": [
{
"name": "Attack Vector",
"value": "Email"
},
{
"name": "Severity",
"value": "Critical"
},
{
"name": "Classification",
"value": "Reported Abuse"
},
{
"name": "Abuse Disposition",
"value": "Malicious"
}
],
"events": [
{
"id": 8,
"category": "malware",
"severity": "Info",
"source": "Proofpoint TAP",
"threatname": "Malicious content dropped during execution",
"classified": false,
"state": "Linked",
"description": "Malicious content dropped during execution",
"attackDirection": "inbound",
"received": "2018-06-01T18:02:10Z",
"malwareName": "Malicious content dropped during execution"
},
{
"id": 6,
"category": "malware",
"severity": "Info",
"source": "Proofpoint TAP",
"threatname": "Example signature to fire on TAP demo evilness",
"classified": false,
"state": "Linked",
"description": "Example signature to fire on TAP demo evilness",
"attackDirection": "inbound",
"received": "2018-06-01T17:57:10Z",
"malwareName": "Example signature to fire on TAP demo evilness"
},
],
"quarantine_results": [
{
"alertSource": "Not Available",
"startTime": "2018-06-01T18:17:43.941Z",
"endTime": "2018-06-01T18:17:44.001Z",
"status": "successful",
"recipientType": "Search",
"recipient": "jsmith@company.com",
"messageId": "<20180601175356.GA30914@tapdemo.evilscheme.org>"
"isRead": "true",
"wasUndone": "true",
"details": "Success"
}
],
"successful_quarantines": 1,
"failed_quarantines": 0,
"pending_quarantines": 0
}
]
Calling with expand_events set to false returns JSON structured like this:
[
{
"id": 1,
"type": "Malware",
"summary": "Unsolicited Bulk Email",
"description": "EvilScheme test message",
"score": 4200,
"state": "Open",
"created_at": "2018-05-26T21:07:17Z",
"event_count": 3,
"event_sources": [
"Proofpoint TAP"
],
"users": [
"nbadguy"
],
"assignee": "Unassigned",
"team": "Unassigned",
"hosts": {
"attacker": [
"54.214.13.31",
"http://tapdemo.evilscheme.org/files/313532373336373133382e33.pdf"
],
"forensics": [
"http://tapdemo.evilscheme.org/files/313532373336373133382e33.pdf",
"tapdemo.evilscheme.org"
]
},
"incident_field_values": [
{
"name": "Attack Vector",
"value": "Email"
},
{
"name": "Classification",
"value": "Spam"
},
{
"name": "Severity",
"value": "Critical"
}
],
"event_ids": [1,2,3],
"quarantine_results": [],
"successful_quarantines": 0,
"failed_quarantines": 0,
"pending_quarantines": 0
Retrieve all incident metadata from Threat Response by specifying filter criteria such as the state of the incident or time of closure.
HTTPs Request
GET /api/incidents?{query_parameters}
Request parameters
| Parameter | Description | Data type | Parameter type | Required? |
|---|---|---|---|---|
| Authorization | Authentication token | string | header | yes |
| state | State of the incidents to retrive Incident states can be: - new - open - assigned - closed - ignored |
string | query | no |
| created_after | Retrieve incidents that were created after specified date, in ISO 8601 format (UTC) | string | query | no |
| created_before | Retrieve incidents that were created before specified date, in ISO 8601 format (UTC) | string | query | no |
| closed_after | Retrieve incidents that were closed after specified date, in ISO 8601 format (UTC) | string | query | no |
| closed_before | Retrieve incidents that were closed before specified date, in ISO 8601 format (UTC) | string | query | no |
| expand_events | Retrieve incidents with events data expanded Values can be: - true (default) - false |
string | query | no |
The following conditions need to be met when using date range parameters in the API.
- The created and closed parameters are mutually exclusive. In other words, created_after or created_before cannot be used in conjunction with closed_after or closed_before.
- The API client must specify created_after or closed_after for any API call.
- If created_before or closed_before are omitted, the current timestamp on the system is used in their place.
- The API cannot be called by spcifying only created_before or only closed_before; an after date range parameter must be specified.
- The date range must be less than or equal to 30 days.
Add incident comments
Request example below:
curl -X POST --header 'Authorization: c02d2dde-0d91-4f36-97dc-a9cd75784a40' --header 'Content-type: application/json' -d '{"summary": "comments here", "detail": "details here"}' 'https://172.16.84.128/api/incidents/16/comments.json' -v -k
import requests, json
json_body = {'summary': 'comments here', 'detail': 'details here'}
r = requests.post('https://172.16.84.128/api/incidents/16/comments.json',
headers={'Authorization': 'c02d2dde-0d91-4f36-97dc-a9cd75784a40'},
verify=False, data=json.dumps(json_body))
print(r.status_code)
json_object = json.dumps(r.json(), indent=4)
print(json_object)
The above command returns JSON structured like this:
{
"id": 56,
"incident_id": 16,
"response_id": null,
"user_id": null,
"history_type": "comment",
"state_from": "none",
"state_to": "none",
"summary": "comments here",
"detail": "details here",
"created_at": "2017-01-17T20:58:38Z",
"updated_at": "2017-01-17T20:58:38Z"
}
Comments can be added to existing Threat Response incidents either manually, through the Incident Workbench UI, or via an HTTP POST request. The payload must be a JSON object with a field, “comment,” whose value is the comment to be added (detail field is optional).
HTTPs Request
POST /api/incidents/{incident_id}/comments.json
Request parameters
| Parameter | Description | Data type | Parameter type | Required? |
|---|---|---|---|---|
| incident_id | The id value of incident to retrieve | integer | path | yes |
| Authorization | Authentication token | string | header | yes |
| summary | Summary of the comments | string | body | yes |
| detail | Details of the comments | string | body | no |
Add user to incident
Request example below:
curl -X POST --header 'Authorization: c02d2dde-0d91-4f36-97dc-a9cd75784a40' --header 'Content-type: application/json' -d '{"targets": ["user1"], "attackers": ["user2"]}' 'https://172.16.84.128/api/incidents/16/users.json' -v -k
import requests, json
json_body = {'targets': ['user1'], 'attackers': ['user2']}
r = requests.post('https://172.16.84.128/api/incidents/16/users.json',
headers={'Authorization': 'c02d2dde-0d91-4f36-97dc-a9cd75784a40'},
verify=False, data=json.dumps(json_body))
print(r.status_code)
The above command returns “200 OK” in case of success.
The “Add User to Incident” API enables you to programmatically assign a user to an incident as a target or attacker.
HTTPs Request
POST /api/incidents/{incident_id}/users.json
Request parameters
| Parameter | Description | Data type | Parameter type | Required? |
|---|---|---|---|---|
| incident_id | The id value of incident to retrieve | integer | path | yes |
| Authorization | Authentication token | string | header | yes |
| targets | List of targets to add to an incident | array | body | yes |
| attackers | List of attackers to add to an incident | array | body | yes |
Update Incident Description
This API is used to set the Description field of an incident to a specified value.
Request example below:
curl -X POST --header 'Authorization: c02d2dde-0d91-4f36-97dc-a9cd75784a40' --header 'Content-type: application/json' -d '{"description":"Handing off incident to threat research team", "overwrite":"false"}' 'https://172.16.84.128/api/incidents/1616/description.json' -v -k
import requests, json
json_body = {"description":"Handing off incident to threat research team", "overwrite":"false"}
r = requests.post('https://172.16.84.128/api/incidents/1616/description.json',
headers={'Authorization': 'c02d2dde-0d91-4f36-97dc-a9cd75784a40'},
verify=False, data=json.dumps(json_body))
print(r.status_code)
The above command returns “200 OK” in case of success.
The above command returns “400 ERROR” in case the incident does not exist or the incident is closed.
<html>
<head>
<meta http-equiv="Content-Type" content="text/html;charset=utf-8"/>
<title>Error 400 Incident with id: 1608 is closed; its description can not be updated</title>
</head>
<body><h2>HTTP ERROR 400</h2>
<p>Problem accessing /api/incidents/1608/description.json. Reason:
<pre>Incident with id: 1608 is closed; its description can not be updated</pre>
</p>
</body>
</html>
HTTPs Request
POST /api/incidents/{incident_id}/description.json
Request parameters
| Parameter | Description | Data type | Parameter type | Required? |
|---|---|---|---|---|
| incident_id | The id value of incident to retrieve | integer | path | yes |
| Authorization | Authentication token | string | header | yes |
| description | Incident Description | string | body | yes |
| overwrite | Overwrite existing description | string | body | no |
Close Incident
This API is used to close a specified incident.
Request example below:
curl -X POST --header 'Authorization: c02d2dde-0d91-4f36-97dc-a9cd75784a40' --header 'Content-type: application/json' -d '{"summary":"Closing incident", "detail":"Message has been quarantined and user has been notified."}' 'https://172.16.84.128/api/incidents/1605/close.json' -v -k
import requests, json
json_body = {"summary":"Closing incident", "detail":"Message has been quarantined and user has been notified."}
r = requests.post('https://172.16.84.128/api/incidents/1605/close.json',
headers={'Authorization': 'c02d2dde-0d91-4f36-97dc-a9cd75784a40'},
verify=False, data=json.dumps(json_body))
print(r.status_code)
The above command returns “200 OK” in case of success or when the specified incident is already closed.
The above command returns “404 NOT FOUND” in case the incident does not exist.
HTTPs Request
POST /api/incidents/{incident_id}/close.json
Request parameters
| Parameter | Description | Data type | Parameter type | Required? |
|---|---|---|---|---|
| incident_id | The id value of incident to retrieve | integer | path | yes |
| Authorization | Authentication token | string | header | yes |
| summary | Incident Closure Summary | string | body | yes |
| detail | Incident Closure Detail | string | body | yes |
Alert API
The Alert API is used to retrieve information about alerts/events that are part of an incident. The API is available in Threat Response/TRAP from version 4.5.0 and beyond.
Get Alert Details
Retrieve alert metadata from Threat Response.
Request example below:
curl -X GET --header 'Accept: application/json' --header 'Authorization: c02d2dde-0d91-4f36-97dc-a9cd75784a40' 'https://172.16.84.128/api/v1/alerts?id=3' -v -k
import requests, json
r = requests.get('https://172.16.84.128/api/v1/alerts?id=3',
headers={'Authorization': 'c02d2dde-0d91-4f36-97dc-a9cd75784a40'}, verify=False)
json_object = json.dumps(r.json(), indent=4)
print(json_object)
The above command returns JSON structured like this:
{
"id": 3,
"severity": "Info",
"source": "Abuse Mailbox Monitor",
"state": "Linked",
"attackDirection": "inbound",
"received": "2019-02-25T17:22:48Z",
"emails": [
{
"sender": {
"email": "analyzer@analyzer.featbot.io"
},
"recipient": {
"email": "x-abuse@acme.com"
},
"subject": "FW: Report me!",
"messageId": "<BE095FD07C20C5419BF398E428D3AAD416664E78@orion-exch.orion.local>",
"body": "<html dir=\"ltr\">DELETED</html>",
"bodyType": "html",
"headers": {
"Thread-Index": "AdTNIeEpSJX5TD0eRy+DKCAGay+zzgAABtQOAAAiV44AAwUbrg==",
"Received": "from ORION-EXCH.orion.local ([::1]) by orion-exch.orion.local ([::1]) with mapi id 14.03.0123.003; Mon, 25 Feb 2019 09:21:59 -0800",
"X-MS-TNEF-Correlator": "<BE095FD07C20C5419BF398E428D3AAD416664E78@orion-exch.orion.local>",
"Thread-Topic": "Report me!",
"Message-ID": "<BE095FD07C20C5419BF398E428D3AAD416664E78@orion-exch.orion.local>",
"Content-Transfer-Encoding": "binary",
"X-MS-Exchange-Organization-AuthAs": "Internal",
"In-Reply-To": "<BE095FD07C20C5419BF398E428D3AAD416664E63@orion-exch.orion.local>",
"X-MS-Exchange-Organization-AuthSource": "orion-exch.orion.local",
"Subject": "FW: Report me!",
"MIME-Version": "1.0",
"Date": "Mon, 25 Feb 2019 09:21:58 -0800",
"X-MS-Exchange-Organization-AuthMechanism": "04",
"X-MS-Exchange-Organization-SCL": "-1",
"References": "<F4F06DB4324F7649A88EA3C014334523166CE43E@orion-exch.orion.local>,<BE095FD07C20C5419BF398E428D3AAD416664E56@orion-exch.orion.local>,<BE095FD07C20C5419BF398E428D3AAD416664E63@orion-exch.orion.local>",
"X-Originating-IP": "[10.23.160.157]",
"Accept-Language": "en-US",
"X-MS-Has-Attach": "yes",
"Content-Language": "en-US",
"Content-Type": "application/ms-tnef",
"X-PhishAlarm-Clear-Id": "876724f6-2b0c-4c4b-8d85-3813298527a1",
"X-PhishAlarm-Clear-Timeout": 45,
"X-PhishAlarm-Format": "PhishAlarm for Gmail; MethodOfDetermination=\"Guessing\"",
"X-PhishAlarm-Overcast-Trace-Token": "ZG-AEQ=ZHMACg=R9pKjo-6JX_EdjS2h7Mo",
"X-PhishAlarm-Reporter": "test-user-1@clear-gmail-testing.page",
"X-PhishAlarm-SES-key": "725d98a1-2d08-4350-97af-d22a6e57d152"
},
"urls": [
"http://www.google.com"
],
"attachments": [
{
"timestamp": 1551109849000,
"safename": "62aeae6f18dbe28939babe759c095c7b.pdf",
"realnamePII": {
"secret": "Hanhart Pioneer Valjoux 23 Flyback.pdf"
},
"size": 404674,
"contentType": "application/pdf",
"md5": "e64e6f2d9a148e948aafe4081e4f4f03",
"sha256": "dda637869121ac6bede4e8127c8333375901940d6a5e87da4eb3ab250a1ad518"
}
],
"abuseCopy": true
},
{
"sender": {
"email": "badguy@whatever.com"
},
"recipient": {
"email": "employee@acme.com"
},
"subject": "FW: Report me!",
"messageId": "<BE095FD07C20C5419BF398E428D3AAD416664E63@orion-exch.orion.local>",
"body": "<html dir=\"ltr\">removed</html>",
"bodyType": "html",
"headers": {
"Thread-Index": "AdTNIeEpSJX5TD0eRy+DKCAGay+zzgAABtQOAAAiV44AAwUbrg==",
"Received": "from ORION-EXCH.orion.local ([::1]) by orion-exch.orion.local ([::1]) with mapi id 14.03.0123.003; Mon, 25 Feb 2019 09:21:59 -0800",
"X-MS-TNEF-Correlator": "<BE095FD07C20C5419BF398E428D3AAD416664E78@orion-exch.orion.local>",
"Thread-Topic": "Report me!",
"Message-ID": "<BE095FD07C20C5419BF398E428D3AAD416664E78@orion-exch.orion.local>",
"Content-Transfer-Encoding": "binary",
"X-MS-Exchange-Organization-AuthAs": "Internal",
"In-Reply-To": "<BE095FD07C20C5419BF398E428D3AAD416664E63@orion-exch.orion.local>",
"X-MS-Exchange-Organization-AuthSource": "orion-exch.orion.local",
"Subject": "FW: Report me!",
"MIME-Version": "1.0",
"Date": "Mon, 25 Feb 2019 09:21:58 -0800",
"X-MS-Exchange-Organization-AuthMechanism": "04",
"X-MS-Exchange-Organization-SCL": "-1",
"References": "<F4F06DB4324F7649A88EA3C014334523166CE43E@orion-exch.orion.local>,<BE095FD07C20C5419BF398E428D3AAD416664E56@orion-exch.orion.local>,<BE095FD07C20C5419BF398E428D3AAD416664E63@orion-exch.orion.local>",
"X-Originating-IP": "[10.23.160.157]",
"Accept-Language": "en-US",
"X-MS-Has-Attach": "yes",
"Content-Language": "en-US",
"Content-Type": "application/ms-tnef"
},
"urls": [
"http://www.google.com"
],
"attachments": [
{
"timestamp": 1551109849000,
"safename": "62aeae6f18dbe28939babe759c095c7b.pdf",
"realnamePII": {
"secret": "Hanhart Pioneer Valjoux 23 Flyback.pdf"
},
"size": 404674,
"contentType": "application/pdf",
"md5": "e64e6f2d9a148e948aafe4081e4f4f03",
"sha256": "dda637869121ac6bede4e8127c8333375901940d6a5e87da4eb3ab250a1ad518"
}
],
"mimeContent": "removed",
"abuseCopy": false
}
]
}
HTTPs Request
GET /api/v1/alerts?id={alert_id}
Request parameters
| Parameter | Description | Data type | Parameter type | Required? |
|---|---|---|---|---|
| alert_id | The id value of alert to retrieve | integer | path | yes |
| Authorization | Authentication token | string | header | yes |
Investigation API
The Investigation API is used to retrieve information about investigations conducted inside Threat Response, involving one or more incidents. The API is available in Threat Response/TRAP from version 5.5.0 and beyond.
Get Investigation Details
Retrieve investigation metadata from Threat Response.
Request example below:
curl -X GET --header 'Accept: application/json' --header 'Authorization: c02d2dde-0d91-4f36-97dc-a9cd75784a40' 'https://172.16.84.128/api/investigations/1.json' -v -k
import requests, json
r = requests.get('https://172.16.84.128/api/investigations/1.json',
headers={'Authorization': 'c02d2dde-0d91-4f36-97dc-a9cd75784a40'}, verify=False)
json_object = json.dumps(r.json(), indent=4)
print(json_object)
The above command returns JSON structured like this:
{
"id": 1,
"created_at": "2021-01-08T17:20:07Z",
"updated_at": "2021-03-11T05:49:15Z",
"name": "test",
"assignee": "System Administrator",
"team": "Script Admins",
"description": "asdadad",
"investigation_field_values": [
{
"name": "Classification",
"value": "Malware"
},
{
"name": "Severity",
"value": "Informational"
},
{
"name": "Attack Vector",
"value": "Email"
},
{
"name": "IS-Unknown",
"value": "False"
}
],
"incident_ids": [
132,
124
],
"incidents": []
}
Calling with expand_incidents set to true returns JSON structured like this:
{
"id": 1,
"created_at": "2021-01-08T17:20:07Z",
"updated_at": "2021-03-11T05:49:15Z",
"name": "test",
"assignee": "System Administrator",
"team": "Script Admins",
"description": "asdadad",
"investigation_field_values": [
{
"name": "Classification",
"value": "Malware"
},
{
"name": "Severity",
"value": "Informational"
},
{
"name": "Attack Vector",
"value": "Email"
},
{
"name": "IS-Unknown",
"value": "False"
}
],
"incident_ids": [
132,
124
],
"incidents": [
{
"id": 124,
"summary": "Smart Search - Message delivered to root",
"description": "",
"score": 1400,
"state": "New",
"created_at": "2020-04-09T11:49:05Z",
"updated_at": "2021-03-11T05:49:04Z",
"event_count": 15,
"false_positive_count": null,
"event_sources": [
"Smart Search - Export to TRAP"
],
"users": [],
"assignee": "Unassigned",
"team": "Unassigned",
"hosts": {},
"incident_field_values": [
{
"name": "Classification",
"value": "Malware"
},
{
"name": "Attack Vector",
"value": "Email"
},
{
"name": "IS-Unknown",
"value": "False"
},
{
"name": "Abuse Disposition",
"value": null
},
{
"name": "Severity",
"value": "Informational"
},
{
"name": "Is-Malicious",
"value": null
},
{
"name": "Workflow Stage",
"value": null
}
],
"events": null,
"event_ids": [
13218,
13221,
],
"comments": [],
"quarantine_results": [],
"successful_quarantines": 0,
"failed_quarantines": 0,
"pending_quarantines": 0
},
{
"id": 132,
"summary": "Smart Search - Message delivered to root",
"description": "",
"score": 1400,
"state": "New",
"created_at": "2020-04-09T15:01:09Z",
"updated_at": "2021-03-11T05:49:15Z",
"event_count": 18,
"false_positive_count": null,
"event_sources": [
"Smart Search - Export to TRAP"
],
"users": [],
"assignee": "Unassigned",
"team": "Unassigned",
"hosts": {},
"incident_field_values": [
{
"name": "Classification",
"value": "Malware"
},
{
"name": "Attack Vector",
"value": "Email"
},
{
"name": "IS-Unknown",
"value": "False"
},
{
"name": "Abuse Disposition",
"value": null
},
{
"name": "Severity",
"value": "Informational"
},
{
"name": "Is-Malicious",
"value": null
},
{
"name": "Workflow Stage",
"value": null
}
],
"events": null,
"event_ids": [
14145,
14152,
],
"comments": [],
"quarantine_results": [],
"successful_quarantines": 0,
"failed_quarantines": 0,
"pending_quarantines": 0
}
]
}
Calling with both expand_incidents and expand_events set to true returns JSON structured like this:
{
"id": 1,
"created_at": "2021-01-08T17:20:07Z",
"updated_at": "2021-03-11T05:49:15Z",
"name": "test",
"assignee": "System Administrator",
"team": "Script Admins",
"description": "asdadad",
"investigation_field_values": [
{
"name": "Classification",
"value": "Malware"
},
{
"name": "Severity",
"value": "Informational"
},
{
"name": "Attack Vector",
"value": "Email"
},
{
"name": "IS-Unknown",
"value": "False"
}
],
"incident_ids": [
132,
124
],
"incidents": [
{
"id": 124,
"summary": "Smart Search - Message delivered to root",
"description": "",
"score": 1400,
"state": "New",
"created_at": "2020-04-09T11:49:05Z",
"updated_at": "2021-03-11T05:49:04Z",
"event_count": 15,
"false_positive_count": null,
"event_sources": [
"Smart Search - Export to TRAP"
],
"users": [],
"assignee": "Unassigned",
"team": "Unassigned",
"hosts": {},
"incident_field_values": [
{
"name": "Classification",
"value": "Malware"
},
{
"name": "Attack Vector",
"value": "Email"
},
{
"name": "IS-Unknown",
"value": "False"
},
{
"name": "Abuse Disposition",
"value": null
},
{
"name": "Severity",
"value": "Informational"
},
{
"name": "Is-Malicious",
"value": null
},
{
"name": "Workflow Stage",
"value": null
}
],
"events": [
{
"id": 13218,
"alertType": "unknown",
"severity": "Minor",
"source": "Smart Search - Export to TRAP",
"threatname": "Smart Search - Message delivered to root",
"state": "Linked",
"attackDirection": "inbound",
"received": "2020-04-09T11:49:06Z",
"alertCustomFields": [
{
"name": "Suborg",
"value": "0"
},
{
"name": "Attachment_Names",
"value": ""
},
{
"name": "Policy_Route",
"value": "allow_relay,firewallsafe,internalnet"
},
{
"name": "Header_CC",
"value": ""
},
{
"name": "Inbound_TLS_version",
"value": ""
},
{
"name": "Header_To",
"value": "root@qavmtestj052.lab.proofpoint.com"
},
{
"name": "SMIME_Recipients",
"value": ""
},
{
"name": "Virus_Names",
"value": ""
},
{
"name": "Header_Return-Path",
"value": ""
},
{
"name": "Processing_Agent",
"value": "qavmtestj052.lab.proofpoint.com"
},
{
"name": "Message_Encrypted",
"value": "false"
},
{
"name": "Inbound_TLS_Cipher",
"value": ""
},
{
"name": "HELO",
"value": "qavmtestj052.lab.proofpoint.com"
},
{
"name": "Header_Reply-to",
"value": ""
},
{
"name": "Quarantine_Folder",
"value": ""
},
{
"name": "Duration",
"value": "0.084298"
},
{
"name": "Quarantine_Rule",
"value": ""
},
{
"name": "Spam_Score",
"value": ""
},
{
"name": "Message_Size",
"value": "989"
},
{
"name": "QID",
"value": "0238B2K3023078"
},
{
"name": "Rules",
"value": "system"
},
{
"name": "SID",
"value": "2yhgn2g03m"
},
{
"name": "Inbound_TLS_Cipher_Strength",
"value": ""
},
{
"name": "SMIME_Signed_Recipients",
"value": ""
},
{
"name": "Scan_Modules",
"value": "access"
},
{
"name": "Final_Rule",
"value": "system"
},
{
"name": "PE_Recipients",
"value": ""
},
{
"name": "Header_From",
"value": "root@qavmtestj052.lab.proofpoint.com (Cron Daemon)"
},
{
"name": "Country",
"value": "**"
},
{
"name": "Inbound_TLS_policy",
"value": ""
},
{
"name": "Final_Action",
"value": "accept"
}
],
"emails": [
{
"sender": {
"email": "root@qavmtestj052.lab.proofpoint.com",
"vap": false
},
"subject": "Cron <root@qavmtestj052> /usr/sbin/logrotate /etc/logrotate.d/pps_maillog",
"messageId": "<202003030811.0238B2Ux023076@qavmtestj052.lab.proofpoint.com>",
"messageDeliveryTime": {
"chronology": {
"zone": {
"fixed": true,
"id": "UTC"
}
},
"millis": 1583223062338,
"zone": {
"fixed": true,
"id": "UTC"
},
"afterNow": false,
"beforeNow": true,
"equalNow": false
},
"abuseCopy": false
}
],
"falsePositive": false
},
{
"id": 13221,
"alertType": "unknown",
"severity": "Minor",
"source": "Smart Search - Export to TRAP",
"threatname": "Smart Search - Message delivered to root",
"state": "Linked",
"attackDirection": "inbound",
"received": "2020-04-09T11:49:06Z",
"alertCustomFields": [
{
"name": "Suborg",
"value": "0"
},
{
"name": "Attachment_Names",
"value": ""
},
{
"name": "Policy_Route",
"value": "allow_relay,firewallsafe,internalnet"
},
{
"name": "Header_CC",
"value": ""
},
{
"name": "Inbound_TLS_version",
"value": ""
},
{
"name": "Header_To",
"value": "root@qavmtestj052.lab.proofpoint.com"
},
{
"name": "SMIME_Recipients",
"value": ""
},
{
"name": "Virus_Names",
"value": ""
},
{
"name": "Header_Return-Path",
"value": ""
},
{
"name": "Processing_Agent",
"value": "qavmtestj052.lab.proofpoint.com"
},
{
"name": "Message_Encrypted",
"value": "false"
},
{
"name": "Inbound_TLS_Cipher",
"value": ""
},
{
"name": "HELO",
"value": "qavmtestj052.lab.proofpoint.com"
},
{
"name": "Header_Reply-to",
"value": ""
},
{
"name": "Quarantine_Folder",
"value": ""
},
{
"name": "Duration",
"value": "0.059843"
},
{
"name": "Quarantine_Rule",
"value": ""
},
{
"name": "Spam_Score",
"value": ""
},
{
"name": "Message_Size",
"value": "989"
},
{
"name": "QID",
"value": "0239B1mA003712"
},
{
"name": "Rules",
"value": "system"
},
{
"name": "SID",
"value": "2yhm5wg00p"
},
{
"name": "Inbound_TLS_Cipher_Strength",
"value": ""
},
{
"name": "SMIME_Signed_Recipients",
"value": ""
},
{
"name": "Scan_Modules",
"value": "access"
},
{
"name": "Final_Rule",
"value": "system"
},
{
"name": "PE_Recipients",
"value": ""
},
{
"name": "Header_From",
"value": "root@qavmtestj052.lab.proofpoint.com (Cron Daemon)"
},
{
"name": "Country",
"value": "**"
},
{
"name": "Inbound_TLS_policy",
"value": ""
},
{
"name": "Final_Action",
"value": "accept"
}
],
"emails": [
{
"sender": {
"email": "root@qavmtestj052.lab.proofpoint.com",
"vap": false
},
"subject": "Cron <root@qavmtestj052> /usr/sbin/logrotate /etc/logrotate.d/pps_maillog",
"messageId": "<202003030911.0239B1Yh003710@qavmtestj052.lab.proofpoint.com>",
"messageDeliveryTime": {
"chronology": {
"zone": {
"fixed": true,
"id": "UTC"
}
},
"millis": 1583226661872,
"zone": {
"fixed": true,
"id": "UTC"
},
"afterNow": false,
"beforeNow": true,
"equalNow": false
},
"abuseCopy": false
}
],
"falsePositive": false
}
],
"event_ids": null,
"comments": [],
"quarantine_results": [],
"successful_quarantines": 0,
"failed_quarantines": 0,
"pending_quarantines": 0
},
{
"id": 132,
"summary": "Smart Search - Message delivered to root",
"description": "",
"score": 1400,
"state": "New",
"created_at": "2020-04-09T15:01:09Z",
"updated_at": "2021-03-11T05:49:15Z",
"event_count": 18,
"false_positive_count": null,
"event_sources": [
"Smart Search - Export to TRAP"
],
"users": [],
"assignee": "Unassigned",
"team": "Unassigned",
"hosts": {},
"incident_field_values": [
{
"name": "Classification",
"value": "Malware"
},
{
"name": "Attack Vector",
"value": "Email"
},
{
"name": "IS-Unknown",
"value": "False"
},
{
"name": "Abuse Disposition",
"value": null
},
{
"name": "Severity",
"value": "Informational"
},
{
"name": "Is-Malicious",
"value": null
},
{
"name": "Workflow Stage",
"value": null
}
],
"events": [
{
"id": 14145,
"alertType": "unknown",
"severity": "Minor",
"source": "Smart Search - Export to TRAP",
"threatname": "Smart Search - Message delivered to root",
"state": "Linked",
"attackDirection": "inbound",
"received": "2020-04-09T15:01:09Z",
"alertCustomFields": [
{
"name": "Suborg",
"value": "0"
},
{
"name": "Attachment_Names",
"value": ""
},
{
"name": "Policy_Route",
"value": "allow_relay,firewallsafe,internalnet"
},
{
"name": "Header_CC",
"value": ""
},
{
"name": "Inbound_TLS_version",
"value": ""
},
{
"name": "Header_To",
"value": "root@qavmtestj052.lab.proofpoint.com"
},
{
"name": "SMIME_Recipients",
"value": ""
},
{
"name": "Virus_Names",
"value": ""
},
{
"name": "Header_Return-Path",
"value": ""
},
{
"name": "Processing_Agent",
"value": "qavmtestj052.lab.proofpoint.com"
},
{
"name": "Message_Encrypted",
"value": "FALSE"
},
{
"name": "Inbound_TLS_Cipher",
"value": ""
},
{
"name": "HELO",
"value": "qavmtestj052.lab.proofpoint.com"
},
{
"name": "Header_Reply-to",
"value": ""
},
{
"name": "Quarantine_Folder",
"value": ""
},
{
"name": "Duration",
"value": "0.176308"
},
{
"name": "Quarantine_Rule",
"value": ""
},
{
"name": "Spam_Score",
"value": ""
},
{
"name": "Message_Size",
"value": "1041"
},
{
"name": "QID",
"value": "023813Z5015491"
},
{
"name": "Rules",
"value": "system"
},
{
"name": "SID",
"value": "2yhgn2g02y"
},
{
"name": "Inbound_TLS_Cipher_Strength",
"value": ""
},
{
"name": "SMIME_Signed_Recipients",
"value": ""
},
{
"name": "Scan_Modules",
"value": "access"
},
{
"name": "Final_Rule",
"value": "system"
},
{
"name": "PE_Recipients",
"value": ""
},
{
"name": "Header_From",
"value": "root@qavmtestj052.lab.proofpoint.com (Cron Daemon)"
},
{
"name": "Country",
"value": "**"
},
{
"name": "Inbound_TLS_policy",
"value": ""
},
{
"name": "Final_Action",
"value": "accept"
}
],
"emails": [
{
"sender": {
"email": "root@qavmtestj052.lab.proofpoint.com",
"vap": false
},
"subject": "Cron <root@qavmtestj052> run-parts /etc/cron.hourly",
"messageId": "<202003030801.023813eo015482@qavmtestj052.lab.proofpoint.com>",
"messageDeliveryTime": {
"chronology": {
"zone": {
"fixed": true,
"id": "UTC"
}
},
"millis": 1583222463948,
"zone": {
"fixed": true,
"id": "UTC"
},
"afterNow": false,
"beforeNow": true,
"equalNow": false
},
"abuseCopy": false
}
],
"falsePositive": false
},
{
"id": 14152,
"alertType": "unknown",
"severity": "Minor",
"source": "Smart Search - Export to TRAP",
"threatname": "Smart Search - Message delivered to root",
"state": "Linked",
"attackDirection": "inbound",
"received": "2020-04-09T15:01:09Z",
"alertCustomFields": [
{
"name": "Suborg",
"value": "0"
},
{
"name": "Attachment_Names",
"value": ""
},
{
"name": "Policy_Route",
"value": "allow_relay,firewallsafe,internalnet"
},
{
"name": "Header_CC",
"value": ""
},
{
"name": "Inbound_TLS_version",
"value": ""
},
{
"name": "Header_To",
"value": "root@qavmtestj052.lab.proofpoint.com"
},
{
"name": "SMIME_Recipients",
"value": ""
},
{
"name": "Virus_Names",
"value": ""
},
{
"name": "Header_Return-Path",
"value": ""
},
{
"name": "Processing_Agent",
"value": "qavmtestj052.lab.proofpoint.com"
},
{
"name": "Message_Encrypted",
"value": "FALSE"
},
{
"name": "Inbound_TLS_Cipher",
"value": ""
},
{
"name": "HELO",
"value": "qavmtestj052.lab.proofpoint.com"
},
{
"name": "Header_Reply-to",
"value": ""
},
{
"name": "Quarantine_Folder",
"value": ""
},
{
"name": "Duration",
"value": "0.059843"
},
{
"name": "Quarantine_Rule",
"value": ""
},
{
"name": "Spam_Score",
"value": ""
},
{
"name": "Message_Size",
"value": "989"
},
{
"name": "QID",
"value": "0239B1mA003712"
},
{
"name": "Rules",
"value": "system"
},
{
"name": "SID",
"value": "2yhm5wg00p"
},
{
"name": "Inbound_TLS_Cipher_Strength",
"value": ""
},
{
"name": "SMIME_Signed_Recipients",
"value": ""
},
{
"name": "Scan_Modules",
"value": "access"
},
{
"name": "Final_Rule",
"value": "system"
},
{
"name": "PE_Recipients",
"value": ""
},
{
"name": "Header_From",
"value": "root@qavmtestj052.lab.proofpoint.com (Cron Daemon)"
},
{
"name": "Country",
"value": "**"
},
{
"name": "Inbound_TLS_policy",
"value": ""
},
{
"name": "Final_Action",
"value": "accept"
}
],
"emails": [
{
"sender": {
"email": "root@qavmtestj052.lab.proofpoint.com",
"vap": false
},
"subject": "Cron <root@qavmtestj052> /usr/sbin/logrotate /etc/logrotate.d/pps_maillog",
"messageId": "<202003030911.0239B1Yh003710@qavmtestj052.lab.proofpoint.com>",
"messageDeliveryTime": {
"chronology": {
"zone": {
"fixed": true,
"id": "UTC"
}
},
"millis": 1583226661872,
"zone": {
"fixed": true,
"id": "UTC"
},
"afterNow": false,
"beforeNow": true,
"equalNow": false
},
"abuseCopy": false
}
],
"falsePositive": false
}
],
"event_ids": null,
"comments": [],
"quarantine_results": [],
"successful_quarantines": 0,
"failed_quarantines": 0,
"pending_quarantines": 0
}
]
}
HTTPs Request
GET /api/investigations/{investigation_id}.json
Request parameters
| Parameter | Description | Data type | Parameter type | Required? |
|---|---|---|---|---|
| investigation_id | The id value of investigation to retrieve | integer | path | yes |
| Authorization | Authentication token | string | header | yes |
| expand_incidents | Retrieve investigations with incidents data expanded Values can be: - true - false (default) |
string | query | no |
| expand_events | Retrieve investigations with events data expanded Values can be: - true - false (default) |
string | query | no |
The expand_events parameter cannot be used without the expand_incidents parameter. Data about events can be included only within the context of data about incidents.
Custom response API
Upon activating the custom response, Threat Response will combine the administrator-defined payload with details about the incident. The resulting JSON that is sent to the remote server will appear similar to the following:
{
"type": "pcap",
"incident_id": 58,
"event_ids": [
58
],
"automated": true,
"event": {
"event_id": 58,
"event_source_id": 3,
"event_source_name": "FireEye Web MPS",
"category": "malware- object",
"severity": "MAJOR",
"users": [
"SALESDEMO\\ematula"
],
"hosts": {
"src": [
"10.10.124.169 "
],
"dst": [
"92.63.203.241"
],
"cnc": [
"5.72.234.136",
"5.72.84.54",
"5.75.115.157",
"219.151.16.19 0",
"58.46.234.4"
],
"url": [
"http:\/\/www2.k6taazzbck86.sxx.in\/hdcp231_5708.php?n63a9x=kqiX 2ZzjqJzZys%2FcoNfMz3VrpWZrh6nhz3Onh8Lc3NSgvYyBlKKmnmurnFzj1J7x8JmJzaGaq5iSqn6 wkZ7Yzc3rt8vKz6yXlJmWno7LkZ%2FknpaqqJKRnGlpnG9rh6zszKrp1J6roNnMz3Vrolyn1aW1z WeklpOysJmWn5pc4qlwkmyvnGutlZmzrIjH2qWX16Rw2LDvnmTol8ez6NnI362X5Glh1LHwmZ %2Fih9bz88XUqK%2Bw1J6oh6ztzXnhxZ7t39DHsaGi01o%3D"
]
}
}
}
Threat Response supports custom responses by manually or automatically triggering an HTTP request to an external service. Custom response may be used as an integration point with other internal or external services.
Custom responses are configured in System Settings. The steps below outline the process for creating a new custom response:
- Log in to Threat Response
- Navigate to
System Settings > Customization > Custom Responses. - Click the
Add (+)button next in the Custom Responses section to open the New Custom Response panel on the right side of the page. - Configure the following options:
a. Name: A label for the custom response that will appear in the response drop-down menu.
b. URL: The URL to POST the response to.
c. Username: Used to log into the system you want to send this custom information.
d. Password: Used to log into the system you want to send this custom information.
e. Payload: A customizable section of the JSON that can be used to specify a response action.
With the custom response configuration in place, the administrator can define match conditions in Threat Response to automatically activate these responses as new alerts are received. Additionally, a Threat Response user can manually activate one of these responses during their investigation.
Once the response has been activated, a status icon will be displayed next to the response indicating whether it was successful or failed. This status is driven by the HTTP status code returned by the server after the response is pushed. If the HTTP status code is 2xx, the response will show a successful status indicated with a green checkmark. If the status code is 4xx or 5xx, the response will show that it has failed with a red circle-backslash symbol.
In addition to the response status, the server can optionally provide a JSON reply to Threat Response. This response is treated as a comment on the incident, and is recorded in the Incident Activity box. The JSON must include a key/value pair where the key is “comment”, and the value is a string type:
{"comment":"Packet capture available at: http://www.example.com/pcaps/5cc22de8"}
Custom response API JSON syntax
When a custom response is triggered, Threat Response makes an HTTP POST request with a JSON request body. The following fields may be present in the request body:
| Parameter | Description | Type |
|---|---|---|
| automated | True if this custom response was triggered automatically during alert processing, false if it was triggered manually by a user. | boolean |
| custom_payload | JSON object configured as part of the custom response. | object |
| automated_payload | The “automated payload” is a JSON object that will be included in the response if the response was executed from a match condition. The payload itself will include details about the alert that triggered the match condition. | object |
| manual_payload | The “manual payload” is a JSON object that will be included in the response if the response was manually executed from an incident. The payload itself will include details about the incident, including all hosts selected for the response, as well as all alerts reported in the incident. | object |
| incident | The “incident” is a JSON object that will be included in the response if the response was manually executed from an incident. This object contains information about the incident itself. - incident_id (integer) ID of this incident - event_ids (array of integers) IDs of the alerts that are linked to this incident |
object |
| event | The “event” object contains information about the event, or alerts, related to this response. - event_id (integer) ID of this event- event_source_id (integer) ID of the source that produced this event- event_source_name (string) Name of the event source that produced this alert- category (string) Category of this event- severity (string) (string) Severity of the event. Values: “UNKNOWN”, “MINOR”, “MAJOR”, “CRITICAL”, “INFO”- users (array of strings) Usernames that were present in the event.- hosts (object) The filed names indicate the type of host: “src”, “dst”, “cnc”, “attack”, “url”, “other”, or “collected”. The value for each field is an array of strings that are either IP addresses, hostnames, or URLs. |
object |
JSON Alert Source
The JSON Alert Source refers to a JSON-based source that can be created in Threat Response. This source enables administrators to craft custom alerts in a JSON format to be sent into Threat Response via HTTP POST.
Before you can ingest JSON alerts into Threat Response, you need to create JSON source:
- Login to Threat Response.
- Navigate to the
Sourcespage. - Click the
Add (+)button in the left panel to create a new event source. - Select the
JSON Eventoption from the Type dropdown. - Provide the new source a
nameanddescription. - Click Save Changes.
The source is now ready to receive alerts. Note that the source has a POST URL, similar to other source types. This is the URL that should be used to POST custom alerts to Threat Response.
JSON Alert Source 2.0
Request example below:
curl -X POST --header 'Content-Type: application/json'
--header 'Accept: application/json'
--header 'Authorization: c02d2dde-0d91-4f36-97dc-a9cd75784a40' -v -k
-d '
{
"json_version": "2.0",
"attacker": {
"host_name": "evil.com",
"ip_address": "103.251.90.43",
"port": 443,
"url": "http://badurl.example.com",
"user": "user_id"
},
"classification": "Malware",
"cnc_hosts": [
{
"host": "cnc1.com",
"port": 443
},
{
"host": "cnc2.com",
"port": 22
}
],
"custom_fields": {
"custom_field_1": "custom value string 1",
"custom_field_2": "custom value string 2",
"custom_field_3": "custom value string 3",
"custom_field_4": "custom value string 4",
"custom_field_5": "custom value string 5",
"custom_field_6": "custom value string 6"
},
"description": "A Description",
"detector": {
"action": "Cleaned",
"event_category": "Malware",
"host_name": "siem.corp.domain.com",
"ip_address": "192.168.1.1",
"product": "SIEM product",
"vendor": "AwesomeSoft"
},
"email": {
"attachments": [
{
"content_type": "JPEG",
"date": "2014-01-01T10:11:12Z",
"md5": "somemd5sumhere",
"name": "attachment1.atch",
"sha256": "somesha256here",
"size": 567
},
{
"content_type": "HTML",
"date": "2014-01-01T10:11:12Z",
"md5": "somemd5sumhere",
"name": "attachment2.atch",
"sha256": "somesha256here",
"size": 567763
}
],
"body": "some body text",
"body_type": "text",
"headers": {
"foo": "bar",
"fooey": "barry"
},
"message_delivery_time": "2014-01-01T10:11:12Z",
"message_id": "abcdefg",
"recipient": "recipient@corp.com",
"sender": "sender@whatever.com",
"subject": "Click Me!",
"urls": [
"http://foo.com",
"https://bar.com/foobar/test?foo=5"
]
},
"forensics_hosts": [
{
"host": "forensics1.com",
"port": 80
},
{
"host": "forensics2.com",
"port": 443
}
],
"link_attribute": "target_ip_address",
"severity": "medium",
"target": {
"host_name": "host.yourdomain.com",
"ip_address": "10.10.111.111",
"mac_address": "01:23:45:67:89:ab",
"port": 22,
"url": "http://sample.example.com",
"user": "user_id"
},
"threat_info": {
"filename": "malware.ppt",
"name": "Zeus",
"occurred_at": "2014-01-01T10:11:12Z",
"type": "Trojan"
},
"url": "http://www.badurl.com"
}' 'https://172.16.84.128/threat/json_event/events/wQEQhPxm_61Fe2rV1E4k_w'
import requests, json
json_body = {
"json_version": "2.0",
"attacker": {
"host_name": "evil.com",
"ip_address": "103.251.90.43",
"port": 443,
"url": "http://badurl.example.com",
"user": "user_id"
},
"classification": "Malware",
"cnc_hosts": [
{
"host": "cnc1.com",
"port": 443
},
{
"host": "cnc2.com",
"port": 22
}
],
"custom_fields": {
"custom_field_1": "custom value string 1",
"custom_field_2": "custom value string 2",
"custom_field_3": "custom value string 3",
"custom_field_4": "custom value string 4",
"custom_field_5": "custom value string 5",
"custom_field_6": "custom value string 6"
},
"description": "A Description",
"detector": {
"action": "Cleaned",
"event_category": "Malware",
"host_name": "siem.corp.domain.com",
"ip_address": "192.168.1.1",
"product": "SIEM product",
"vendor": "AwesomeSoft"
},
"email": {
"attachments": [
{
"content_type": "JPEG",
"date": "2014-01-01T10:11:12Z",
"md5": "somemd5sumhere",
"name": "attachment1.atch",
"sha256": "somesha256here",
"size": 567
},
{
"content_type": "HTML",
"date": "2014-01-01T10:11:12Z",
"md5": "somemd5sumhere",
"name": "attachment2.atch",
"sha256": "somesha256here",
"size": 567763
}
],
"body": "some body text",
"body_type": "text",
"headers": {
"foo": "bar",
"fooey": "barry"
},
"message_delivery_time": "2014-01-01T10:11:12Z",
"message_id": "abcdefg",
"recipient": "recipient@corp.com",
"sender": "sender@whatever.com",
"subject": "Click Me!",
"urls": [
"http://foo.com",
"https://bar.com/foobar/test?foo=5"
]
},
"forensics_hosts": [
{
"host": "forensics1.com",
"port": 80
},
{
"host": "forensics2.com",
"port": 443
}
],
"link_attribute": "target_ip_address",
"severity": "medium",
"target": {
"host_name": "host.yourdomain.com",
"ip_address": "10.10.111.111",
"mac_address": "01:23:45:67:89:ab",
"port": 22,
"url": "http://sample.example.com",
"user": "user_id"
},
"threat_info": {
"filename": "malware.ppt",
"name": "Zeus",
"occurred_at": "2014-01-01T10:11:12Z",
"type": "Trojan"
},
"url": "http://www.badurl.com"
}
r = requests.post('https://172.16.84.128/threat/json_event/events/wQEQhPxm_61Fe2rV1E4k_w',data=json.dumps(json_body),headers={'Authorization': 'c02d2dde-0d91-4f36-97dc-a9cd75784a40'}, verify=False)
json_object = json.dumps(r.json(), indent=4)
print(json_object)
Ingest an alert into Threat Response.
HTTPs Request
POST /threat/json_event/events/{json_source_id}
Request parameters
Objects are represented in bold text, and are detailed below.
| Parameter | Description | Data type | Parameter type | Required? |
|---|---|---|---|---|
| json_source_id | POST URL of the JSON alert source | string | path | yes |
| json_version | Threat Response JSON version | string | body | yes |
| attacker | Attacker information | object | body | no |
| classification | The alert classification shown as “Alert Type” in the UI Supported classifications: - malware - policy-violation - vulnerability - network - spam - phish - command-and-control - data-match - authentication - system-behavior - impostor - reported-abuse - unknown |
string | body | no |
| cnc_hosts | Command and Control host information | object array | body | no |
| detector | JSON object to describe the threat detection tool such as Firewall and IPS/IDS systems which generated the original alert which was then collected by solutions integrated with Threat Response such as a SIEM (e.g. Splunk) | object | body | no |
| Email metadata related to the alert | object | body | no | |
| forensics_hosts | Forensics host information | object array | body | no |
| link_attribute | Attribute to link alerts on Supported attributes for linking: - target_ip_address - target_hostname - target_machine_name - target_user - target_mac_address - attacker_ip_address - attacker_hostname - attacker_machine_name - attacker_user - attacker_mac_address - email_recipient - email_sender - email_subject - message_id - threat_filename - threat_filehash |
string | body | no |
| Parameter | Description | Data type | Parameter type | Required? |
|---|---|---|---|---|
| severity | Severity of an alert Supported values: - info - minor - moderate - major - critical - Informational* - Low* - Medium* - High* - Critical* |
string | body | no |
| Parameter | Description | Data type | Parameter type | Required? |
|---|---|---|---|---|
| summary | Alert summary that will populate Alert Details field | string | body | no |
| target | Target information | object | body | no |
attacker Object
"attacker": {
"host_name": "evil.com",
"ip_address": "103.251.90.43",
"port": 443,
"url": "http://badurl.example.com",
"user": "user_id"
},
Description: Attacker host information
Data type: object
Parameter type: body
Required?: no
| Parameter | Description | Data type | Parameter type | Required? |
|---|---|---|---|---|
| host_name | Hostname of the attacker host | string | body | no |
| ip_address | IP address of the attacker host | string | body | no |
| port | port of the attacker host | integer | body | no |
| mac_address | MAC address of the attacker host | string | body | no |
| user | Username of the attacker host | string | body | no |
| url | URL associated with attacker host | string | body | no |
cnc_hosts Object
"cnc_hosts": [
{
"host": "cnc1.com",
"port": 443
},
{
"host": "cnc2.com",
"port": 22
}
],
Description: Command and Control host information
Data type: object array
Parameter type: body
Required?: no
| Parameter | Description | Data type | Parameter type | Required? |
|---|---|---|---|---|
| host | Hostname of the command and control host | string | body | no |
| port | port of the command and control host | integer | body | no |
detector Object
"detector": {
"action": "Cleaned",
"event_category": "Malware",
"host_name": "siem.corp.domain.com",
"ip_address": "192.168.1.1",
"product": "SIEM product",
"vendor": "AwesomeSoft"
}
Description: detection tool such as Firewall and IPS/IDS systems which generated the original alert which was then collected by solutions integrated with Threat Response such as a SIEM (e.g. Splunk)
Data type: object
Parameter type: body
Required?: no
| Parameter | Description | Data type | Parameter type | Required? |
|---|---|---|---|---|
| ip_address | Detector IP address | string | body | no |
| host_name | Detector host name | string | body | no |
| product | Detector product name (e.g. Cisco ASA) | string | body | no |
| vendor | Detector vendor name (e.g. Cisco) | string | body | no |
| event_category | Event category as per the detector (e.g. Command & Control) | string | body | no |
| action | Action taken by the detector (e.g. Block) | string | body | no |
email Object
"email": {
"attachments": [
{
"content_type": "JPEG",
"date": "2014-01-01T10:11:12Z",
"md5": "somemd5sumhere",
"name": "attachment1.atch",
"sha256": "somesha256here",
"size": 567
},
{
"content_type": "HTML",
"date": "2014-01-01T10:11:12Z",
"md5": "somemd5sumhere",
"name": "attachment2.atch",
"sha256": "somesha256here",
"size": 567763
}
],
"body": "some body text",
"body_type": "text",
"headers": {
"foo": "bar",
"fooey": "barry"
},
"message_delivery_time": "2014-01-01T10:11:12Z",
"message_id": "abcdefg",
"recipient": "recipient@corp.com",
"sender": "sender@whatever.com",
"subject": "Click Me!",
"urls": [
"http://foo.com",
"https://bar.com/foobar/test?foo=5"
]
}
Description: Email metadata related to the alert
Data type: object
Parameter type: body
Required?: no
| Parameter | Description | Data type | Parameter type | Required? |
|---|---|---|---|---|
| body | Full body text of the message | string | body | no |
| body_type | Format of message body Supported values: - html - text |
string | body | no |
| headers | Headers and their contents | string/dictionary | body | no |
| message_delivery_time | When the message was delivered | ISO 8601 datetime | body | no |
| message_id | Message ID of the email (if applicable) | string | body | no |
| recipient | The recipient’s email address | string | body | no |
| sender | The sender’s email address | string | body | no |
| subject | The subject of the email | string | body | no |
| urls | A list of valid URIs found in the message body | string/array | body | no |
| attachments | List of email attachment objects | object array | body | no |
| content_type | MIME type of the attachment | string | body | no |
| date | File date | ISO 8601 datetime | body | no |
| md5 | MD5 hash of the attachment contents | string | body | no |
| name | Attachment file name | string | body | no |
| sha256 | SHA256 hash of the attachment contents | string | body | no |
| size | Size of the file (bytes) | integer | body | no |
forensics_hosts Object
"forensics_hosts": [
{
"host": "forensics1.com",
"port": 80
},
{
"host": "forensics2.com",
"port": 443
}
],
Description: Forensics host information
Data type: object array
Parameter type: body
Required?: no
| Parameter | Description | Data type | Parameter type | Required? |
|---|---|---|---|---|
| host | Hostname of the forensics host | string | body | no |
| port | port of the forensics host | integer | body | no |
target Object
"target": {
"host_name": "host.yourdomain.com",
"ip_address": "10.10.111.111",
"mac_address": "01:23:45:67:89:ab",
"port": 22,
"url": "http://sample.example.com",
"user": "user_id"
}
Description: Target host information
Data type: object
Parameter type: body
Required?: no
| Parameter | Description | Data type | Parameter type | Required? |
|---|---|---|---|---|
| host_name | Hostname of the target host | string | body | no |
| ip_address | IP address of the target host | string | body | no |
| port | port of the target host | integer | body | no |
| mac_address | MAC address of the target host | string | body | no |
| user | Username of the taget host | string | body | no |
| url | URL associated with target host | string | body | no |
threat_info Object
"threat_info": {
"filehash": "77b63872fabf3884d694f694a2a87e2e"
"filename": "malware.ppt",
"name": "Zeus",
"occurred_at": "2014-01-01T10:11:12Z",
"type": "Trojan"
}
Description: Threat information
Data type: object
Parameter type: body
Required?: no
| Parameter | Description | Data type | Parameter type | Required? |
|---|---|---|---|---|
| name | Name of the “threat” (e.g. malware family) | string | body | no |
| filename | Name of the malicious file | string | body | no |
| type | Type of malicious file (e.g. malware family). [Deprecated] | string | body | no |
| md5sum | Md5 hash value of malicious file [Deprecated, use filehash] | string | body | no |
| filehash | Md5, sha1, or sha256 hash of malicious file | string | body | no |
| occurred_at | UTC timestamp of the alert | ISO 8601 datetime | body | no |
"custom_fields": {
"custom_field_1": "custom value string 1",
"custom_field_2": "custom value string 2",
"custom_field_3": "custom value string 3",
"custom_field_4": "custom value string 4",
"custom_field_5": "custom value string 5",
"custom_field_6": "custom value string 6"
}
| Parameter | Description | Data type | Parameter type | Required? |
|---|---|---|---|---|
| custom_fields | JSON object for collecting custom name value pairs as part of the JSON alert sent to Threat Response. You can add one or more custom name and value pairs. Although there is no limit to the number of custom fields, we recommend keeping it to 10 or fewer fields. “custom field name”: “custom field value” |
object | body | no |
JSON Alert Source 1.0 [Deprecated]
Request example below:
curl -X POST --header 'Content-Type: application/json'
--header 'Accept: application/json'
--header 'Authorization: c02d2dde-0d91-4f36-97dc-a9cd75784a40' -v -k
-d '
{
"category": "malware",
"severity": "High",
"description": "Banking malware alert",
"url": "http://www.downloadmalware.com/malware.exe",
"threat_info": {
"name": "Zeus",
"filename": "malware.ppt",
"type": "Trojan",
"md5sum": "0c3552346d890e6c33c19ac1ec1ef33d",
"filehash": "d82cbf481a8c28f75bcab4b22131c877",
"occurred_at": "2014-01-01T10:11:12Z"
},
"targets": [{
"hostname": "host.yourdomain.com",
"ip_address": "10.10.111.111",
"port": 22,
"mac_address": "01:23:45:67:89:ab",
"user": "user_id",
"url": "http://sample.example.com"
}],
"attackers": [{
"hostname": "evil.com",
"ip_address": "103.251.90.43",
"port": 443,
"user": "user_id",
"url": "http://badurl.example.com"
}],
"email" : {
"sender" : "sender@whatever.com",
"recipient" : "recipient@corp.com",
"subject" : "Click Me",
"message_id" : "abcdefg"
},
"detector": {
"address": "192.168.1.1",
"host_name": "siem.corp.domain.com",
"product": "SIEM product XXX",
"vendor": "AwesomeSoft",
"event_category": "Malware",
"action": "Cleaned"
},
"custom_fields": {
"custom_field_1": "custom value string 1",
"custom_field_2": "custom value string 2",
"custom_field_3": "custom value string 3",
"custom_field_4": "custom value string 4",
"custom_field_5": "custom value string 5",
"custom_field_6": "custom value string 6"
}
}' 'https://172.16.84.128/threat/json_event/events/wQEQhPxm_61Fe2rV1E4k_w'
import requests, json
json_body = {
"category": "malware",
"severity": "High",
"description": "Banking malware alert",
"url": "http://www.downloadmalware.com/malware.exe",
"threat_info": {
"name": "Zeus",
"filename": "malware.ppt",
"type": "Trojan",
"md5sum": "0c3552346d890e6c33c19ac1ec1ef33d",
"filehash": "d82cbf481a8c28f75bcab4b22131c877",
"occurred_at": "2014-01-01T10:11:12Z"
},
"targets": [{
"hostname": "host.yourdomain.com",
"ip_address": "10.10.111.111",
"port": 22,
"mac_address": "01:23:45:67:89:ab",
"user": "user_id",
"url": "http://sample.example.com"
}],
"attackers": [{
"hostname": "evil.com",
"ip_address": "103.251.90.43",
"port": 443,
"user": "user_id",
"url": "http://badurl.example.com"
}],
"email" : {
"sender" : "sender@whatever.com",
"recipient" : "recipient@corp.com",
"subject" : "Click Me",
"message_id" : "abcdefg"
},
"detector": {
"address": "192.168.1.1",
"host_name": "siem.corp.domain.com",
"product": "SIEM product XXX",
"vendor": "AwesomeSoft",
"event_category": "Malware",
"action": "Cleaned"
},
"custom_fields": {
"custom_field_1": "custom value string 1",
"custom_field_2": "custom value string 2",
"custom_field_3": "custom value string 3",
"custom_field_4": "custom value string 4",
"custom_field_5": "custom value string 5",
"custom_field_6": "custom value string 6"
}
}
r = requests.post('https://172.16.84.128/threat/json_event/events/wQEQhPxm_61Fe2rV1E4k_w',data=json.dumps(json_body),headers={'Authorization': 'c02d2dde-0d91-4f36-97dc-a9cd75784a40'}, verify=False)
json_object = json.dumps(r.json(), indent=4)
print(json_object)
Ingest an alert into Threat Response.
HTTPs Request
POST /threat/json_event/events/{json_source_id}
Request parameters
| Parameter | Description | Data type | Parameter type | Required? |
|---|---|---|---|---|
| json_source_id | POST URL of the JSON alert source | string | path | yes |
| category | The alert category shown as “Alert Type” in the UI Supported categories - malware - policy-violation - vulnerability - network - spam - phish - command-and-control - data-match - authentication - system behavior - unknown |
string | body | no |
| severity | Severity of an event Supported values: - info - minor - major - critical |
string | body | no |
| summary | Alert summary that will populate Alert Details field | string | body | no |
| threat_info | Threat information | object | body | no |
| - name | Name of the “threat” (e.g. malware family) | string | body | no |
| - filename | Name of the malicious file | string | body | no |
| - type | Type of malicious file (e.g. malware family). — Deprecated | string | body | no |
| - md5sum | Md5 hash value of malicious file | string | body | no |
| - filehash | Md5, sha1, or sha256 hash of malicious file | string | body | no |
| - occurred_at | UTC timestamp of the alert | date | body | no |
| targets | Target IP or hostname | string/array | body | no |
| - hostname | Hostname of the target host | string | body | no |
| - ip_address | IP address of the target host | string | body | no |
| - port | port of the target host | integer | body | no |
| - mac_address | MAC address of the target host | string | body | no |
| - user | Username of the taget host | string | body | no |
| - url | URL associated with target host | string | body | no |
| attackers | Attacker IP or hostname | string/array | body | no |
| - hostname | Hostname of the attacker host | string | body | no |
| - ip_address | IP address of the attacker host | string | body | no |
| - port | port of the attacker host | integer | body | no |
| - mac_address | MAC address of the attacker host | string | body | no |
| - user | Username of the attacker host | string | body | no |
| - url | URL associated with attacker host | string | body | no |
| *email* | Email metadata related to the alert | object | body | no |
| - sender | Sender email address | string | body | no |
| - recipient | Recipient email address | string | body | no |
| - subject | Email subject | string | body | no |
| - message_id | Email message ID | string | body | no |
| *detector* | JSON object to describe the threat detection tool such as Firewall and IPS/IDS systems which generated the original alert which was then collected by solutions integrated with Threat Response such as a SIEM (e.g. Splunk) | object | body | no |
| - address | Detector IP address | string | body | no |
| - host_name | Detector host name | string | body | no |
| - product | Detector product name (e.g. Cisco ASA) | string | body | no |
| - vendor | Detector vendor name (e.g. Cisco) | string | body | no |
| - event_category | Event category as per the detector (e.g. Command & Control) | string | body | no |
| - action | Action taken by the detector (e.g. Block) | string | bosy | no |
| custom_fields | JSON object for collecting custom name value pairs as part of the JSON alert sent to Threat Response. You can add one or more custom name and value pairs. Although there is no limit to the number of custom fields, we recommend keeping it to 10 or less fields. “custom field name”: “custom field value” |
object | body | no |
ETL Scripting
ETL (Extract, Transform, Load) scripts are Python scripts that can be used to ingest alert data from sources not natively supported by Threat Response.
JSON SDK
Proofpoint has developed an SDK (json_sdk) to allow you to transform your source data into a standard format that Threat Response recognizes. The JSON SDK encompasses several classes representing the information needed to fill out an Alert object and generate a JSON string compatible with Threat Response.
Downloading and installing the SDK
Use your Proofpoint CTS credentials to access the JSON SDK:
https://dl1.proofpoint.com/download/ThreatResponse/4.0.0/PTR_JSON_SDK-4.0.0.zip
This zipfile contains:
The JSON SDK: located in
python/json_sdk/artifacts. Distributed as a standard tarball and can be installed via setuptools. You may require root access to install a new Python module.$ tar xzf json_sdk-1.0.0.tar.gz
$ cd json_sdk-1.0.0
$ python ./setup.py installExample scripts: located in
python/examplesSDK documentation: located in
python/json_sdk/artifacts/doc/json_sdk
Python environment
The environment available for custom ETL scripts runs Python version 2.7. In addition to the default modules available in the base Python distribution, the following additional modules have been included:
- six (Python 2 and 3 compatibility utilities)
- requests (HTTP library)
- psutil (Cross-platform lib for process and system monitoring)
- numpy (Array processing for numbers, strings, records, and objects)
- dill (Extension of
picklemodule for serializing and de-serializing python objects) - scipy (Scientific Library)
- scikit-learn (Machine learning and data mining)
- pandas (Data structures for data analysis, time series, and statistics)
- tensorflow (Machine learning)
Script structure
Core functions
import json_sdk
def initialize():
pass
def parse_alert():
return json_sdk.Alert(description='An alert.')
def finalize():
pass
if __name__ == "__main__":
alert = parse_alert()
print alert.create_json()
Three core functions are provided to customer scripts, and are executed by the script runner in the order below:
| Function | Required? |
|---|---|
initialize(): Used to prepare the environment |
No |
parse_alert(): Transforms data from the remote system and creates alerts if needed |
Yes |
finalize(): Performs any required cleanup actions |
No |
Any custom functions required to handle the device data must be called from one of these functions.
Helper items
Threat response provides additional helper functions and variables to work with key/value pairs and device data:
# Retrieve from the auth profile
username = ptr.kv_auth_profile.get('Login')
password = ptr.kv_auth_profile.get('Password')
kv_auth_profile
| Description | Data Type | Read-Only? | Avaiable Methods |
|---|---|---|---|
| Get data from the linked auth profile | Object | Yes | get('key') |
# Retrieve from the variable file
device_ip_address = ptr.kv_file.get('Device Address')
kv_file
| Description | Data Type | Read-Only? | Avaiable Methods |
|---|---|---|---|
| Get data from the linked variable file | Object | Yes | get('key') |
# Retrieve from the alert source k/v store
num = ptr.kv_alert_source.get('last_value')
# Write to the alert source k/v store
ptr.kv_alert_source.set('last_value', str(value))
kv_alert_source - Set/get data from the alert source k/v store
| Data Type | Read-Only? | Avaiable Methods |
|---|---|---|
| Object | No | get('key')set('key', 'value') |
DEVICE_ALERT_DATA
| Description | Data Type | Read-Only? |
|---|---|---|
| Raw string containing the data pushed from the remote device (for scripted listener alert sources) | String | Yes |
TEST
| Description | Data Type | Read-Only? |
|---|---|---|
| Flag to indicate if this run is a test (no alerts will be generated) | Boolean | Yes |
Help Item Functions get(key) is_secret(key) set(key, value) set_secret(key) set_plaintext(key) remove(key) get_data_as_list()
Custom PowerShell scripts
Threat Response allows users to run custom PowerShell scripts in order to perform actions and collect information from Windows endpoints. In this section we will take a look at several examples of PowerShell scripts and associated responses.
In order to learn more about how to upload custom PowerShell scripts, please, refer to the following section:
In order to learn more about how to use PowerShell scripts, please, refer to the following section:
Custom PowerShell scripts IOC collection
Get newest security event logs
This PowerShell script allows us to collect 100 newest security event logs.
#Print the PowerShell version for context
write-host "PowerShell Version: " $PSVersionTable.PSVersion.tostring()
write-host
#Print a simple list of all Newest 100 security event logs on localhost
write-host "========================================================="
write-host "List of Newest 100 Security event logs."
write-host "========================================================="
write-host
# Get all 3rd party drivers
$eventList = get-eventlog -log security -newest 100
foreach ($event in $eventList) {
write-host "Index :" $event.Index
write-host "Time :" $event.TimeGenerated
write-host "EntryType :" $event.EntryType
write-host "Source :" $event.Source
write-host "Event ID :" $event.EventID
write-host "Message :" $event.Message
write-host
Write-host "************************************************************************"
write-host
}
Response should look similar to the following screenshot below.
List startup programs
This PowerShell script allows us to collect the information about startup programs on the host.
#Print the PowerShell version for context
write-host "PowerShell Version: " $PSVersionTable.PSVersion.tostring()
write-host
#Print a simple list of Startup Programs on localhost
$colItems = Get-WmiObject Win32_StartupCommand -computername .
foreach ($objItem in $colItems) {
write-host "Name :" $objItem.Name
write-host "Command :" $objItem.command
write-host "Location :" $objItem.Location
write-host "User :" $objItem.User
write-host
}
Response should look similar to the following screenshot below.
List installed software
This PowerShell script allows us to collect list installed software on the host.
#Print the PowerShell version for context
write-host "PowerShell Version: " $PSVersionTable.PSVersion.tostring()
write-host
#Print a simple list of Installed Programs on localhost
write-host "========================================================="
write-host "List of Installed Programs on this host."
write-host "========================================================="
write-host
$installList = Get-WmiObject -Class Win32_Product
foreach ($program in $installList) {
write-host "Name :" $program.Name
write-host "Command :" $program.Version
write-host "Vendor :" $program.Vendor
write-host "Caption :" $program.Caption
write-host "Signed :" $program.Signed
write-host
}
Response should look similar to the following screenshot below.
List installed drivers
This PowerShell script allows us to collect the list of installed drivers on the host.
# Print the PowerShell version for context
write-host "PowerShell Version: " $PSVersionTable.PSVersion.tostring()
write-host
# Print a list of installed 3rd party drivers on localhost. This script requires elevated privileges.
write-host "============================================================="
write-host "List of installed drivers."
write-host "============================================================="
write-host
# Get all drivers
$driverList = driverquery -SI -FO csv | ConvertFrom-Csv | Where-Object { $_.InfName -like "*.inf" }
foreach ($driver in $driverList) {
write-host "Driver Name :" $driver.DeviceName
write-host "File Name :" $driver.InfName
write-host "Provider Name :" $driver.Manufacturer
write-host "IsSigned :" $driver.IsSigned
write-host
}
Response should look similar to the following screenshot below.
List services configured on host
This PowerShell script allows us to collect the list of services running on the host.
#Print the PowerShell version for context
write-host "PowerShell Version: " $PSVersionTable.PSVersion.tostring()
write-host
#Print a simple list of Configured Services on localhost
write-host "========================================================="
write-host "List of configured services on this host."
write-host "========================================================="
write-host
$serviceList = Get-Service | Sort-Object -descending Status
foreach ($service in $serviceList) {
write-host "Service Name :" $service.ServiceName
write-host "Display Name :" $service.DisplayName
write-host "Service Type :" $service.ServiceType
write-host "Start Type :" $service.StartType
write-host "Status :" $service.Status
write-host
}
Response should look similar to the following screenshot below.
List of scheduled tasks
This PowerShell script allows us to collect the list of tasks scheduled on the host.
#Print the PowerShell version for context
write-host "PowerShell Version: " $PSVersionTable.PSVersion.tostring()
write-host
#Print a simple list of all Scheduled Tasks on localhost
write-host "========================================================="
write-host "List of Scheduled Tasks on this host."
write-host "========================================================="
write-host
$psMajorVersion = $PSVersionTable.PSVersion.Major
if ($psMajorVersion -ge 3) {
$taskList = Get-ScheduledTask | sort state -descending
foreach ($task in $taskList) {
write-host "Task Name :" $task.TaskName
write-host "Task Path :" $task.TaskPath
write-host "Author :" $task.Author
write-host "Description :" $task.Description
write-host "Status :" $task.State
write-host
}
}
else {
$schedule = new-object -com("Schedule.Service")
$schedule.connect()
$taskList = $schedule.getfolder("\").gettasks(0)
foreach ($task in $taskList) {
write-host "Task Name :" $task.Name
write-host "Path :" $task.Path
write-host "Last Run Time :" $task.LastRunTime
write-host "Next Run Time :" $task.NextRunTime
write-host
}
}
Response should look similar to the following screenshot below.
