The Power of the ThreatQ Open Exchange API - Part 2

POSTED BY JULIAN DEFRONZO

Continuing our series on the ThreatQ Open Exchange API, today’s topic will cover working Adversaries and Events.

You will need a valid Access Token to follow along. For a refresher on how to authenticate and obtain an Access Token, see the previous post in the series.

Working with Adversaries

The following examples are based around simple use cases for working with adversaries in the API.

Listing Adversaries

To retrieve a list of adversaries, use the /api/adversaries endpoint. This will return the basic data for each adversary in an array. In this case, we are limiting the results to five adversaries (Figure 1).

$ curl -k “https://$THREATQ_HOST/api/adversaries?limit=5” -H “Authorization: Bearer $ACCESS_TOKEN”

{
“total”: 437,
“data”: [
{
“id”: 1,
“name”: “CopyKittens”,
“created_at”: “2017-07-26 12:28:06”,
“updated_at”: “2017-07-26 12:28:06”,
“touched_at”: “2017-09-13 21:04:44”
},…

Figure 1: Retrieving a list of Adversaries

Querying for a Specific Adversary

In this example we want to query for the specific adversary, doubleflag, in our Threat Library. We also want the API to return additional information including the adversary’s sources, description, and attributes. We can use the /api/adversaries endpoint again, passing a name URL parameter with our search query and the values sources, description, and attributes in the with URL parameter (Figure 2).

$ curl -k “https://$THREATQ_HOST/api/adversaries?name=doubleflag&with=sources,description,attributes” -H “Authorization: Bearer $ACCESS_TOKEN”

{
“total”: 1,
“data”: [
{
“id”: 5,
“name”: “doubleflag”,
“created_at”: “2017-07-26 12:29:31”,
“updated_at”: “2017-07-26 12:29:31”,
“touched_at”: “2017-10-18 18:00:55”,
“sources”: [
{
“id”: 44,
“type”: “connectors”,
“name”: “Digital Shadows Intelligence”,
“tlp_id”: null,
“created_at”: “2017-07-26 12:29:31”,
“updated_at”: “2017-07-26 12:29:31”,
“published_at”: “2017-07-26 12:29:31”,
“pivot”: {
“adversary_id”: 5,
“source_id”: 44,
“id”: 5,
“creator_source_id”: 44
}
}
],
“description”: null,
“attributes”: [
{
“id”: 657,
“adversary_id”: 5,
“attribute_id”: 37655073,
“value”: “Low”,
“created_at”: “2017-07-26 12:43:18”,
“updated_at”: “2017-07-26 12:43:18”,
“name”: “Digital Shadows Threat Level”,
“attribute”: {
“id”: 37655073,
“name”: “Digital Shadows Threat Level”,
“created_at”: “2017-07-26 12:37:38”,
“updated_at”: “2017-07-26 12:37:38”
}

Figure 2: Querying for doubleflag with additional fields

Creating an Adversary

To create an adversary, we will first create a JSON file that will contain the basic adversary details: the adversary name and the source of the adversary. As in the authentication step above, we will create a JSON file to facilitate making the API call (Figure 3).

$ cat adversary.json

{
“name”: “Magecart”,
“sources”: [
{
“name”: “RiskIQ”
}
]
}

Figure 3: Adversary JSON file

With the JSON file created, we can create the adversary by making a POST to /api/adversaries (Figure 4).

curl -k -X POST “https://$THREATQ_HOST/api/adversaries” -H “Authorization: Bearer $ACCESS_TOKEN” -d@adversary.json

{
“data”: {
“name”: “Magecart”,
“updated_at”: “2017-10-26 14:35:41”,
“created_at”: “2017-10-26 14:35:41”,
“id”: 439,
“sources”: [
{
“id”: 158,
“type”: “other_sources”,
“name”: “RiskIQ”,
“expire_days”: null,
“score”: null,
“created_at”: “2017-10-26 14:33:35”,
“updated_at”: “2017-10-26 14:33:35”
}
]
}
}

Figure 4: Creating an Adversary

To set the adversary’s description, we must make a POST to /api/adversaries/ADVERSARY_ID/description with the description value (Figure 5). The description value accepts HTML formatting.

curl -k -X POST “https://$THREATQ_HOST/api/adversaries/439/description” -H “Authorization: Bearer $ACCESS_TOKEN” -d ‘{“value”: “<p>Description</p>\n”}’

{
“value”: “<p>Description</p>\n”
}

Figure 5: Setting an Adversary description

Working with Events

The following examples are based around simple use cases for working with events in the API.

Listing Events

To retrieve a list of events, use the /api/events endpoint. This will return the basic data for each event in an array. In this case, we are limiting the results to five events (Figure 6).

$ curl -k “https://$THREATQ_HOST/api/events?limit=5” -H “Authorization: Bearer $ACCESS_TOKEN”

{
“total”: 392,
“data”: [
{
“id”: 1,
“type_id”: 1,
“title”: “Invoice 8565231”,
“description”: null,
“happened_at”: “2017-04-18 19:07:24”,
“hash”: “6a72cdaeabd1dfb623c7f55795df7cab”,
“created_at”: “2017-04-19 15:11:43”,
“updated_at”: “2017-04-19 15:11:43”,
“touched_at”: “2017-04-19 15:11:43”
},…

Figure 6: Retrieving a list of Events

Querying for a Specific Event

In this example we want to query for a specific event with the title RIG Exploit Kit in our Threat Library. We also want the API to return additional information including the adversary’s sources, description, and attributes. We can use the /api/events endpoint again, passing a title URL parameter with our search query and the values sources and attributes in the with URL parameter (Figure 7).

$ curl -k “https://$THREATQ_HOST/api/events?title=RIG%20Exploit%20Kit&with=sources,attributes” -H “Authorization: Bearer $ACCESS_TOKEN”

{
“total”: 1,
“data”: [
{
“id”: 8,
“type_id”: 15,
“title”: “RIG Exploit Kit”,
“description”: “Browser exploit kit used for distribution of malware to vulnerable computers”,
“happened_at”: “2016-11-16 05:55:00”,
“hash”: “65e0a49073cc21582918744014348f2e”,
“created_at”: “2017-05-24 14:26:45”,
“updated_at”: “2017-05-24 19:03:01”,
“touched_at”: “2017-05-24 19:03:01”,
“sources”: [
{
“id”: 23,
“type”: “connectors”,
“name”: “PassiveTotal”,
“tlp_id”: null,
“created_at”: “2017-05-24 14:26:45”,
“updated_at”: “2017-05-24 14:26:45”,
“published_at”: null,
“pivot”: {
“event_id”: 8,
“source_id”: 23,
“id”: 8,
“creator_source_id”: 23
}
}
],
“attributes”: []
}
]
}

Figure 7: Querying for RIG Exploit Kit Event with additional fields

Creating an Event

To create an event, we will first create a JSON file that will contain the basic event details: the event title, event type, and the source of the event. As in the authentication step above, we will create a JSON file to facilitate making the API call (Figure 8).

cat event.json

{
“title”: “Suspicious Traffic”,
“type”: “Command and Control”,
“happened_at”: “2017-03-20 01:43:05”,
“sources”: [
{
“name”: “Firewall”
}
]
}

Figure 8: Event JSON file

Note: You will need to ensure the event type already exists in your Threat Library. To do this you can navigate to ThreatQ Configuration > System Configurations > Event Types (Figure 9).

Event types

Figure 9: Configuring Event Types

With the JSON file created, we can create the adversary by making a POST to /api/events (Figure 10).

curl -k -X POST “https://$THREATQ_HOST/api/events” -H “Authorization: Bearer $ACCESS_TOKEN” -d@event.json

{
“data”: {
“title”: “Suspicious Traffic”,
“type_id”: 7,
“happened_at”: “2017-03-20 01:43:05”,
“hash”: “6f38ac7fd250e7c1873ff14ef1a01342”,
“updated_at”: “2017-10-27 13:59:25”,
“created_at”: “2017-10-27 13:59:25”,
“id”: 576,
“type”: {
“id”: 7,
“name”: “Command and Control”,
“user_editable”: “N”,
“created_at”: “2017-03-28 01:49:50”,
“updated_at”: “2017-03-28 01:49:50”
},
“sources”: [
{
“type”: “other_sources”,
“name”: “Firewall”,
“updated_at”: “2017-10-27 13:59:25”,
“created_at”: “2017-10-27 13:59:25”,
“id”: 53
}
]
}
}

Figure 10: Creating an Event

The ThreatQ Open Exchange API is a powerful backend tool that provides flexibility in working with the data in the Threat Library. By using the API directly, you can manipulate and create new data in a way that works best with your workflows

0 Comments

Trackbacks/Pingbacks

  1. Microsoft LAPS, WatchGuard, and Flexera – Enterprise Security Weekly #68 – Cyber Sercuirty - […] ThreatQ Open Exchange API – Part 2 […]

About ThreatQuotient™

ThreatQuotient™ understands that the foundation of intelligence-driven security is people. The company’s open and extensible threat intelligence platform, ThreatQ™, empowers security teams with the context, customization and prioritization needed to make better decisions, accelerate detection and response and advance team collaboration.
LEARN MORE
Share This