The Power of the ThreatQ Open Exchange API - Part 1

POSTED BY JULIAN DEFRONZO

While most user interaction with the ThreatQ threat intelligence platform is done from the user interface, you can discover just how extensible and powerful the platform is by working directly with the ThreatQ Open Exchange API. It is through the API that feeds, custom connectors, and other integrations interact with the platform, allowing you to script out threat creation and retrieval of data from the Threat Library to support your specific workflows.

In this blog series, we will cover many use cases for working with the ThreatQ Open Exchange API. Here, in Part 1, we will cover Authentication and working with Indicators.

Authentication

Step One: Create an Authentication JSON file

The ThreatQ Open Exchange uses the OAuth protocol for authentication. This process involves getting a username, password, and Client ID. To get started, create a JSON file with the following structure, replacing the email, password, and client_id with your specific credentials. We will use this file to facilitate authentication to the API (Figure 1).

$ cat auth.json
{
“email”: “user@threatq.com”,
“password”: “thisisapassword”,
“grant_type”: “password”,
“client_id”: “yjc0mmi1ymezn2fjmzvmy2i2otaxm2zm”
}

Figure 1: Authentication JSON file

Use your email address and password to login to the ThreatQ user interface.To obtain your Client ID, access the ThreatQ user interface and navigate to Settings » OAuth Management and copy the displayed client ID (Figure 2).

Figure 2: Obtaining your Client ID

Step Two: Request an Access Token

Before we can make any requests to the API, to make the next few examples easier to follow along, you can store the hostname or IP address of your ThreatQ system as a shell variable, THREATQ_HOST (Figure 3).

$ export THREATQ_HOST=”tq.threatq.com”
$ echo $THREATQ_HOST
tq.threatq.com

Figure 3: Setting THREATQ_HOST variable

To access the API endpoints, you will first need to request an API access token (Figure 4). You will use this token in the header of subsequent requests.

$ curl -k -X POST “https://$THREATQ_HOST/api/token” -H “Content-Type: application/json” -d @auth.json

{
“access_token”: “NTFlMWYwZGNmOTc5”,
“token_type”: “bearer”,
“expires_in”: 3600,
“refresh_token”: “NTY4ZGUwNjlkZWM3”
}

Figure 4: Obtaining Access Token

The most important value to note in this response for now is the access_token. This will be used for subsequent requests to the API. You can store the access_token as another shell variable ACCESS_TOKEN (Figure 5).

$ export ACCESS_TOKEN=NTFlMWYwZGNmOTc5
$ echo $ACCESS_TOKEN
NTFlMWYwZGNmOTc5

Figure 5: Setting ACCESS_TOKEN variable

NOTE: This token will expire in 60 minutes (3600 seconds) and will need to be refreshed using the previous step to obtain a new access token.

Working with Indicators

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

Listing Indicators

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

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

{
“total”: 22405,
“data”: [
{
“id”: 1,
“type_id”: 11,
“status_id”: 1,
“class”: “host”,
“hash”: “046303732fec03b6ab43a36bfd4ef598”,
“value”: “1440057b2f45160b908f6df2656119f3”,
“last_detected_at”: null,
“expires_at”: null,
“expired_at”: null,
“expires_calculated_at”: “2017-06-08 17:00:03”,
“created_at”: “2017-04-18 14:36:49”,
“updated_at”: “2017-06-08 17:00:03”,
“touched_at”: “2017-06-08 17:00:03”
},…

Figure 6: Retrieving a list of Indicators

Querying for Specific Indicator Values

In this example we want to query for the FQDN, example.com in our Threat Library. We can use the /api/indicators endpoint again, passing a value URL parameter with our search query (Figure 7). The API will return the basic indicator fields.

$ curl -k “https://$THREATQ_HOST/api/indicators?value=example.com” -H “Authorization: Bearer $ACCESS_TOKEN”

{
“total”: 1,
“data”: [
{
“last_detected_at”: null,
“hash”: “6559d290f2e7f589e24c3b47440c50c5”,
“status_id”: 4,
“created_at”: “2017-05-03 15:11:26”,
“type_id”: 7,
“updated_at”: “2017-06-08 17:00:22”,
“value”: “example.com”,
“id”: 18256,
“touched_at”: “2017-06-08 17:00:22”,
“expires_calculated_at”: “2017-06-08 17:00:22”,
“expires_at”: null,
“class”: “network”,
“expired_at”: null
}
]
}

Figure 7: Querying for example.com

To return more fields beyond the basic ones, we can include a with URL parameter to specify the additional data fields we want to include. Options for this endpoint include adversaries, attachments, attributes, comments, events, indicators, score, signatures, sources, status, tags, type, and watchlist. In this case we are requesting sources, score, and attributes (Figure 8).

$ curl -k “https://$THREATQ_HOST/api/indicators?value=example.com&with=sources,score,attributes” -H “Authorization: Bearer $ACCESS_TOKEN”

{
“total”: 1,
“data”: [
{
“last_detected_at”: null,
“hash”: “6559d290f2e7f589e24c3b47440c50c5”,
“status_id”: 4,
“created_at”: “2017-05-03 15:11:26”,
“type_id”: 7,
“updated_at”: “2017-06-08 17:00:22”,
“value”: “example.com”,
“id”: 18256,
“touched_at”: “2017-06-08 17:00:22”,
“sources”: [
{
“name”: “ArcSight”,
“created_at”: “2017-05-03 15:11:26”,
“updated_at”: “2017-05-09 15:44:26”,
“published_at”: “2017-05-02 14:10:01”,
“pivot”: {
“source_id”: 14,
“indicator_id”: 18256,
“id”: 29453,
“creator_source_id”: 8
},
“type”: “other_sources”,
“id”: 14,
“tlp_id”: null
},
{
“name”: “CG’s Email”,
“created_at”: “2017-05-08 15:34:59”,
“updated_at”: “2017-05-08 15:36:03”,
“published_at”: null,
“pivot”: {
“source_id”: 20,
“indicator_id”: 18256,
“id”: 29471,
“creator_source_id”: 8
},
“type”: “other_sources”,
“id”: 20,
“tlp_id”: null
}
],
“score”: {
“created_at”: “2017-05-03 15:11:26”,
“updated_at”: “2017-06-08 16:57:39”,
“generated_score”: “6.00”,
“indicator_id”: 18256,
“score_config_hash”: “4698e1ce1aac6def30a9600629236c0fa88170f6”,
“manual_score”: null,
“id”: 32700
},
“expires_calculated_at”: “2017-06-08 17:00:22”,
“expires_at”: null,
“attributes”: [
{
“name”: “False Positive”,
“attribute”: {
“updated_at”: “2017-05-08 13:41:43”,
“created_at”: “2017-05-08 13:41:43”,
“id”: 243439,
“name”: “False Positive”
},
“created_at”: “2017-05-08 14:05:30”,
“updated_at”: “2017-05-08 14:05:39”,
“value”: “No”,
“touched_at”: “2017-05-08 14:05:39”,
“indicator_id”: 18256,
“attribute_id”: 243439,
“id”: 86489
}
],
“class”: “network”,
“expired_at”: null
}
]
}

Figure 8: Specifying additional data fields

Creating an Indicator

To create an indicator, we will first create a JSON file that will contain the basic indicator details: the indicator value, the type of indicator, the indicator’s status and the source of the indicator. As in the authentication step above, we will create a JSON file to facilitate making the API call (Figure 9).

$ cat indicator.json

{
“value”: “80.85.158.121”,
“type”: “IP Address”,
“status”: “Review”,
“sources”: [{
“name”: “Malware Traffic Analysis”
}]
}

Figure 9: Indicator JSON file

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

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

{
“total”: 1,
“data”: [
{
“id”: 25505,
“type_id”: 10,
“status_id”: 4,
“class”: “network”,
“hash”: “ef9941406bec44e3be542e73251f8cd7”,
“value”: “80.85.158.121”,
…      ]
}
]
}

Figure 10: Creating an Indicator

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. In Part 2 of this blog series, we will cover more API use cases, including working with Events, Adversaries, and Files.

0 Comments

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