Threat Intelligence Data Exchange  

Contents

Overview
Credentials
API Access
User Interface Access
Querying Data
Query Active Threats
Query Data for a Single Threat Indicator
Query for a Specific IP Address
Query for a Specific Host Name
Query for a Specific URL
Query Data from a Particular Time
Get Threats for Time Period
Retrieve a List of Provider Organizations
Query Data from a Specified Organization
Threat Class APIs
Get Threat Classes
Appendix A: Common HTTP Status Codes

Overview

This Getting Started Guide takes you through the steps required to query data via the Cloud Services
Portal (CSP). See the Cloud Services Portal API Guide for detailed information on the API calls and terms used in this document.

Back to top of page

Credentials

API Access

The issuance of an API key is required to query and submit data to the platform via API. The API key is
passed in the username field and is used for authentication. The password field should be set to an
empty string.

Example of a Cloud Services Portal API token: <MY TOKEN>

User Interface Access

Example of Cloud Services Portal credentials:
Username: user@company.com
Password: *dk5seOg3TW46

Back to top of page

Querying Data

These scenarios make use of multiple API calls to query available data or information, based on the parameters passed.

Query Active Threats

To access active threats available to your organization, use tide/api/data/threats/state/. If you don't specify a provider organization (using the "profile" query string parameter) then the search will be executed against all available data. You can specify multiple provider organizations by having multiple "profile" parameters.

To make samples a bit easier to use, the calls also specify the “rlimit” query string parameter. It's an optional parameter that limits the number of returned records.

Python

#note: install the 'requests' library first:
#pip install -U requests import requests
from pprint import pprint

#note: replace this api_key value with your api key! api_key = 'YOUR_API_KEY'
api_endpoint = 'https://csp.infoblox.com' api_path = '/tide/api/data/threats/state'
url = '%s%s' % (api_endpoint,api_path) params = {'rlimit': 2}(optional)

token = '<MY TOKEN>'

r = requests.get(url,headers={'Content-Type':'application/json','Authorization':'token {}'.format(token)})      
print (r.status_code)
print (r.json())
# OR
#print (r.content)
                                                                                                                                    
                                                                                                                  

Sample Result

Curl

curl ‘https:/csp.infoblox.com/tide/api/data/threats/state?profile=EmergingThreats:Hostnames_Feed&class=APT,Bot&type=host&show_full_profiles=true&data_format=ndjson' -H 'Authorization:Token token=<MYTOKEN>' | python -mjson.tool

Sample Result

{
     "threat": [
        {
                  "batch_id": "ffffffff-f343-11e3-897c-55530a829c6f", 
                  "class": "Exploit_Kit",
                  "detected": "2017-06-13T17:24:26.000Z",
                  "dga": "false",
                  "domain": "real-bad-host.info", 
                  "host": "drawer.real-bad-host.info",
                  "id": "ffffffff-f343-11e3-897c-55530a829cf6", 
                  "imported": "2017-06-13T21:42:54.429Z",
                  "ip": "",
                  "origin": "IID",
                  "profile": "IID",
                  "property": "Exploit_Kit_Nuclear", 
                  "target": "",
                  "threat_level": 1, 
                  "tld": "info",
                  "tlp": "",
                  "type": "HOST",
                  "up": "true",
                  "url": ""
        },
        {
                  "batch_id": "ffffffff-0c5a-11e4-913b-fb8aa419fdba", 
                  "class": "Spam_Bot",
                  "detected": "2017-07-15T10:36:44.000Z",
                  "domain": "",
                  "host": "",
                  "id": "ffffffff-0c5b-11d4-913b-fb8aa419fdba", 
                  "imported": "2017-07-15T20:06:57.174Z",
                  "ip": "1.55.122.11",
                  "origin": "OrgA",
                  "profile": "OrgA", 
                  "property": "Bot Cutwail", 
                  "target": "", 
                  "threat_level": 1,
                  "tld": "",
                  "tlp": "",
                  "type": "IP",
                  "url": ""
        }
],
        "record_count": 2,
        "filtered_record_count": 2,
        "dropped_record_count": 0, 
        "dropped": false
}

Back to top of page

Query Data for a Single Threat Indicator

You can query the platform to retrieve all data for a single threat indicator, such as a particular IP address, host name, or URL.

The following requests will return threat records like the ones in the Query Active Threats example.

Back to top of page

Query for a Specific IP Address

If you wanted to search for all instances of IP address 1.2.3.4 in csv format, you could submit the following curl request:

If you wanted to search for all instances of IP address 1.2.3.4 detected in the last day in csv format, you could submit the following curl request:

If you wanted to search for all instances of IP address 1.2.3.4 which were reported as Zero Access Bots in csv format, you could submit the following curl request:

(A list of valid properties can be found at the API /api/data/properties.)

Back to top of page

Query for a Specific Host Name

If you wanted to search for all instances of host example.com in csv format, you could submit the following curl request:

If you wanted to search for all instances of host example.com imported in the last hour in csv format, you could submit the following curl request:

If you wanted to search for all instances of host example.com for threat class Malware C2 in csv format, you could submit the following curl request:

(A list of valid threat classes can be found at the API /api/data/threat_classes.)

Back to top of page

Query for a Specific URL

If you wanted to search for all instances of URL http://www.example.com, you could submit the following curl request:

If you wanted to search for all instances of URL http://www.example.com detected since August 1, 2017 UTC, you could submit the following curl request:

If you wanted to search for all instances of URL http://www.example.com detected since August 1, 2017 UTC and targeting your company, you could submit the following curl request:

Back to top of page

Query Data from a Particular Time

You may want to regularly retrieve data with the same criteria. In this case, you’ll probably want to query by time period.

For example, you want to check for host MalwareC2DGA threats every hour. You might create a cron job that submits:

Or you could save the date/time of your last retrieval and use it with imported_from_date and the suitable time period:

Back to top of page

Get Threats for Time Period

Returns threats submitted within the specified time period. Valid time periods are recent (30 minutes), hourly (90 minutes), daily (25 hours), weekly (7 days), and monthly (30 days).

Request

Request Endpoint

GET /data/threats/{type}

Request Body

N/A

Query Parameters

Response

If the submission is successful, the HTTP code 200 (OK) will be returned with the list of Threat objects.

Example

Request using curl to return host records for the past day:

Response

Back to top of page

Retrieve a List of Provider Organizations

Use /api/admin/sharing/source_orgs as follows to get the ID of the organizations providing data that is available to your organization.

Python

#note: install the 'requests' library first:
#pip install -U requests 
import requests

#note: replace this api_key value with your api key! 
api_key = 'YOUR_API_KEY'
api_endpoint = 'https://csp.infoblox.com'
api_path = 
‘/tide/admin/v1/resources/shared/dataprofiles'
url = '%s%s' % (api_endpoint,api_path)

token = '<MY TOKEN>'

r = requests.get(url,headers={'Content-
Type':'application/json','Authorization':'token {}'.format(token)})
print (r.status_code)
print (r.json())
# OR
#print (r.content)

Sample result:

200

{u'status': u'success', u'code': 0, u'data': [u'IID']}

Curl

curl

‘https://csp.infoblox.com/tide/admin/v1/resources/shared/dataprofiles' -H 'Authorization:Token token=<MYTOKEN>'

| python -mjson.tool

Sample Result

{
     "code": 0,
     "data": [
        "OrgA",
        "OrgB",
        "DemoOrg", 
         "IID"
     ],
     "status": "success"
}

Back to top of page

Query Data from a Specified Organization

To query data from a specified organization, use the state (active threats) or threats by age API.

For example, if you wanted to get a list of all active IP threats from OrgA, you would use the API:

     /tide/api/data/threats/state/ip?profile=OrgA

If you wanted all IP threats submitted by OrgA in the last day, you would use the API:

     /tide/api/data/threats/state/ip/daily?profile=OrgA

You must specify the name of the provider organization using the "profile" query string parameter. You can specify multiple provider organizations by having multiple "profile" parameters.

Python

#note: install the 'requests' library first:
#pip install -U requests import requests
from pprint import pprint

#note: replace this api_key value with your api key! api_key = 'YOUR_API_KEY'
api_endpoint = 'https://csp.infoblox.com'
api_path = '/tide/api/data/threats/ip/daily'
url = '%s%s' % (api_endpoint,api_path)
params = {'profile': ['OrgA','IID'],'rlimit': 2}

token = '<MY TOKEN>'

r = requests.get(url,headers={'Content-Type':'application/json','Authorization':'token {}'.format(token)})
print (r.status_code)
print (r.json())
# OR
#print (r.content)

Sample result

200

{u'dropped': False, 
 u'dropped_record_count': 0,
 u'filtered_record_count': 2,
 u'record_count': 2,
 u'threat': [{u'batch_id': u'fefefefe-f343-11e3-897c-55530a829c6f', 
              u'class': u'ExploitKit',
              u'detected': u'2017-06-13T17:24:26.000Z',
              u'dga': u'false',
              u'domain': u'another-bad-host.info', 
              u'host': u'drawer.another-bad-host.info',
              u'id': u'fefefefe-f343-11e3-fefe-55530a829c6f', 
              u'imported': u'2017-06-13T21:42:54.429Z',
              u'ip': u'',
              u'origin': u'',
              u'profile': u'OrgA',
              u'property': u'ExploitKit_Nuclear', 
              u'target': u'',
              u'threat_level': 100, 
              u'tld': u'info',
              u'tlp': u'',
              u'type': u'HOST',
              u'up': u'true',
              u'url': u''},
             {u'batch_id': u'ad1798f7-fefe-11e3-fefe-55530a829c6f', u'class': u'ExploitKit',
              u'detected': u'2017-06-13T17:24:26.000Z',
              u'dga': u'false',
              u'domain': u'programrealty.info', 
              u'host': u'draw.programrealty.info',
              u'id': u'ad257baa-f343-11e3-897c-fefefefefefe', 
              u'imported': u'2017-06-13T21:42:54.429Z',
              u'ip': u'',
              u'origin': u'IID',
              u'profile': u'IID',
              u'property': u'ExploitKit_Nuclear', 
              u'target': u'',
              u'threat_level': 100, 
              u'tld': u'info',
              u'tlp': u'',
              u'type': u'HOST',
              u'up': u'true',
              u'url': u''}]}

Curl

curl ‘https://csp.infoblox.com/tide/api/data/threats?profile=OrgB&profile=II D&rlimit=2' -H 'Authorization:Token token=<MYTOKEN>' | python -mjson.tool

Sample result

Back to top of page

Threat Class APIs

Threat classes indicate the categories of threat, for example, phishing or spambots.

Back to top of page

Get Threat Classes

Gets a list of threat classes.

Request

GET /data/threat_classes

Example:

Request using Curl

Response (with some detail removed for brevity):

Back to top of page

Appendix A: Common HTTP Status Codes

The 2xx range is returned for successful requests.

The 4xx range is returned due to errors made by the requestor. The 5xx range is returned due to server errors.

The following is not an exhaustive list, but representative of the most likely codes returned by the platform.

Back to top of page