The Power of the ThreatQ Open Exchange API – Part 1

save
Share and earn Cybytes
Facebook Twitter LinkedIn Email

The Power of the ThreatQ Open Exchange API – Part 1

POSTED BY JULIAN DEFRONZO

While most user interaction with the ThreatQ 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.

The post The Power of the ThreatQ Open Exchange API – Part 1 appeared first on ThreatQuotient.

Share this post and earn Cybytes
Facebook Twitter LinkedIn Email
Follow
85 Followers
About ThreatQuotient
ThreatQuotient™ understands that the foundation of intelligence-driven security is people. The company’s open and extensible threat intelligence platform, ThreatQ, provides defenders with the context, customization and collaboration needed to ensure that intelligence is accurate, relevant and timely to their business. Leading global companies are using ThreatQ as the cornerstone of their threat operations and management system, increasing security effectiveness and efficiency. For more information, visit http://www.threatquotient.com.

Our Revolution

We believe Cyber Security training should be free, for everyone, FOREVER. Everyone, everywhere, deserves the OPPORTUNITY to learn, begin and grow a career in this fascinating field. Therefore, Cybrary is a free community where people, companies and training come together to give everyone the ability to collaborate in an open source way that is revolutionizing the cyber security educational experience.

Cybrary On The Go

Get the Cybrary app for Android for online and offline viewing of our lessons.

Get it on Google Play
 

Support Cybrary

Donate Here to Get This Month's Donor Badge

 
Skip to toolbar

We recommend always using caution when following any link

Are you sure you want to continue?

Continue
Cancel