Contents
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.
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
The issuance of a username and password is required to access the Cloud Services Portal (CSP) userinterface at https://csp.infoblox.com. User interface access is not required for API access, but certain
functions, including the creation of data profiles, are simpler to do with the user interface.
Example of Cloud Services Portal credentials:
Username: user@company.com
Password: *dk5seOg3TW46
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: |
Sample Result
200 |
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
{ |
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.
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:
curl ‘https://csp.infoblox.com/tide/api/data/threats/state?type=ip&ip=1.2.3.4&data_format=csv' -H 'Authorization:Token token=<MYTOKEN>' |
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:
curl ‘https://csp.infoblox.com/tide/api/data/threats/state?type=ip&ip=1.2.3.4&period=1d&data_format=csv -H 'Authorization:Token token=<MYTOKEN>' |
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:
curl ‘https://csp.infoblox.com/tide/api/data/threats/state?type=ip&ip=1.2.3.4&property=bot_zeroaccess&data_format=csv’ -H 'Authorization:Token token=<MYTOKEN>' |
(A list of valid properties can be found at the API /api/data/properties.)
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:
curl ‘https://csp.infoblox.com/tide/api/data/threats/state?type=host&host=example.com&data_format=csv’ -H 'Authorization:Token token=<MYTOKEN>' |
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:
curl ‘https://csp.infoblox.com/tide/api/data/threats/state?type=host&host=example.com&imported_period=1h&data_format=csv’ -H 'Authorization:Token token=<MYTOKEN>' |
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:
curl ‘https://csp.infoblox.com/tide/api/data/threats/state?type=host&host=example.com&class=Malware_C2&data_format=csv’ -H 'Authorization:Token token=<MYTOKEN>' |
(A list of valid threat classes can be found at the API /api/data/threat_classes.)
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:
curl ‘https://csp.infoblox.com/tide/api/data/threats/state?type=url&url=http://www.example.com&data_format=csv’ -H 'Authorization:Token token=<MYTOKEN>' |
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:
curl ‘https://csp.infoblox.com/tide/api/data/threats/state?type=url&url=http://www.example.com&from_date=2017-08-01T00:00:00Z&data_format=csv’ -H 'Authorization:Token token=<MYTOKEN>' |
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:
curl ‘https://csp.infoblox.com/tide/api/data/threats/state?type=url&url=http://www.example.com&from_date=2017-08-01T00:00:00Z&target=my%20company&data_format=csv’ -H 'Authorization:Token token=<MYTOKEN>' |
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:
curl ‘https://csp.infoblox.com/tide/api/data/threats/host/hourly?imported_period=1h&class=MalwareC2DGA&data_format=csv' -H 'Authorization:Token token=<MYTOKEN>' |
Or you could save the date/time of your last retrieval and use it with imported_from_date and the suitable time period:
curl ‘https://csp.infoblox.com/tide/api/data/threats/host/daily?imported_from_date=[last retrieval]&class=MalwareC2DGA&data_format=csv' -H 'Authorization:Token token=<MYTOKEN>' |
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
Path Parameters | |||
---|---|---|---|
Parameter | Value | Data Type | Description |
type | host, ip, or url | string | Type of threats to return |
age | recent, hourly, daily, weekly, monthly | string | The age of threats to return. recent = 30 minutes, hourly = 90 minutes, daily = 25 hours, weekly = 7 days, monthly = 30 days |
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:
curl ‘https://csp.infoblox.com/tide/api/data/threats/host/daily?data_format=ndjson' -H 'Authorization:Token token=<MYTOKEN>' |
Response
{ |
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: |
Sample result:
200 {u'status': u'success', u'code': 0, u'data': [u'IID']} |
Curl
curl |
Sample Result
{ |
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: |
Sample result
200 {u'dropped': False, |
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
{ |
Threat Class APIs
Threat classes indicate the categories of threat, for example, phishing or spambots.
Get Threat Classes
Gets a list of threat classes.
Request
GET /data/threat_classes
Example:
Request using Curl
curl ‘https://csp.infoblox.com/tide/api/data/threat_classes' -H 'Authorization:Token token=<MYTOKEN>' | python -mjson.tool |
Response (with some detail removed for brevity):
{ |
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.
Common HTTP Status Codes | ||
---|---|---|
Code | Reason | Description |
200 | OK | The request succeeded. |
201 | Created | The server created a new item, for example, a new threat batch. The server will generally return a Location URI in the response header indicating the location of the newly created item. |
204 | No Content | No content needed to be returned from the server, for example, if an entity has been deleted. |
400 | Bad Request | There was an error in the request due to bad syntax. There may be, for example, errors in the query parameters or in the body of the request. Check your syntax against the API documentation. |
401 | Unauthorized | The user has not submitted valid credentials. Make sure you are using the proper API key in your transmission. |
403 | Forbidden | The user does not have access to the requested resource. |
404 | Not Found | The server did not find a resource matching the request URI. |
500 | Internal Server Error | The server encountered an unexpected condition which prevented it from fulfilling the request. |
503 | Service Unavailable | The server is currently unable to handle the request due to a temporary overloading or maintenance of the server. |
This page has no comments.