In [24]:
from OTXv2 import OTXv2, IndicatorTypes
In [5]:
from pandas.io.json import json_normalize
In [6]:
from datetime import datetime, timedelta
In [7]:
otx = OTXv2("")
Replace YOUR_KEY with your OTX API key. You can find it on your settings page https://otx.alienvault.com/settings.
The getall() method accesses your subscriptions. It downloads all the OTX pulses and their assocciated indicators of compromise (IOCs) from your account. This includes:
In [4]:
pulses = otx.getall()
In [5]:
len(pulses)
Out[5]:
Let's list a few pulses:
In [6]:
json_normalize(pulses)[0:5]
Out[6]:
Let's explore the indicators object:
In [8]:
json_normalize(pulses[1]["indicators"])
Out[8]:
The following Indicator Types are supported (also defined in IndicatorTypes.py):
In [12]:
indicator_types = [
{
"name": "IPv4",
"description": "An IPv4 address indicating the online location of a server or other computer."
},
{
"name": "IPv6",
"description": "An IPv6 address indicating the online location of a server or other computer."
},
{
"name": "domain",
"description": "A domain name for a website or server. Domains encompass a series of hostnames."
},
{
"name": "hostname",
"description": "The hostname for a server located within a domain."
},
{
"name": "email",
"description": "An email associated with suspicious activity."
},
{
"name": "URL",
"description": " Uniform Resource Location (URL) summarizing the online location of a file or resource."
},
{
"name": "URI",
"description": "Uniform Resource Indicator (URI) describing the explicit path to a file hosted online."
},
{
"name": "FileHash-MD5",
"description": "A MD5-format hash that summarizes the architecture and content of a file."
},
{
"name": "FileHash-SHA1",
"description": "A SHA-format hash that summarizes the architecture and content of a file."
},
{
"name": "FileHash-SHA256",
"description": "A SHA-256-format hash that summarizes the architecture and content of a file."
},
{
"name": "FileHash-PEHASH",
"description": "A PEPHASH-format hash that summarizes the architecture and content of a file."
},
{
"name": "FileHash-IMPHASH",
"description": "An IMPHASH-format hash that summarizes the architecture and content of a file."
},
{
"name": "CIDR",
"description": "Classless Inter-Domain Routing (CIDR) address, which describes both a server's IP address and the network architecture (routing path) surrounding that server."
},
{
"name": "FilePath",
"description": "A unique location in a file system."
},
{
"name": "Mutex",
"description": "The name of a mutex resource describing the execution architecture of a file."
},
{
"name": "CVE",
"description": "Common Vulnerability and Exposure (CVE) entry describing a software vulnerability that can be exploited to engage in malicious activity."
}]
In [13]:
json_normalize(indicator_types)
Out[13]:
In [27]:
mtime = (datetime.now() - timedelta(days=1)).isoformat()
In [28]:
mtime
Out[28]:
Besides receiving the pulse information, there is another function that can retrieve different events that are ocurring in the OTX system and affect your account.
In [29]:
events = otx.getevents_since(mtime)
In [30]:
json_normalize(events)
Out[30]:
When developing an application, you must decide how you want to handle different types of events. For instance, if one OTX user unsubscribes from another user, do you want to delete the IOCs the second user contributed from your application? How do you plan to reconcile the data on the server versus the data in your application? The same question comes up when users delete a pulse.
The OTX API allows you to search for pulses and users by keyword. This allows you to obtain pulses that you're not (yet) subscribed to.
In [8]:
pulses = otx.search_pulses("Russian")
In [10]:
json_normalize(pulses["results"])
Out[10]:
Let's say we're interested in viewing the full details (including indicators) from one of our search results. For example maybe we're interested in the Enigma Ransomware:
In [16]:
pulse_id = pulses["results"][1]["id"]
In [17]:
pulse_details = otx.get_pulse_details(pulse_id)
In [18]:
json_normalize(pulse_details)
Out[18]:
Let's investigate an indicator included in the Enigma Ransomware pulse.
In [ ]:
indicator = pulse_details["indicators"][4]["indicator"]
In [28]:
indicator_details = otx.get_indicator_details_full(IndicatorTypes.IPv4, indicator)
Indicator details are divided into sections for convenience:
In [30]:
indicator_details.keys()
Out[30]:
In [37]:
json_normalize(indicator_details["url_list"])
Out[37]:
In [39]:
json_normalize(indicator_details["passive_dns"].get('passive_dns'))
Out[39]:
Indicator details are not available for all supported indicator types. IndicatorTypes.supported_api_types contains a list of the indicator types you can use with get_indicator_details_by_section and get_indicator_details_full.
You can create new pulses using the create_pulse function. A name string is required. Public boolean is also required but will be set True if not provided:
In [41]:
indicators = [{"indicator": "82.194.84.121", "description":"", "type": "IPv4"}, {"indicator": "82.194.84.122", "description":"", "type": "IPv4"}]
In [42]:
new_pulse = otx.create_pulse(name="IPy Notebook Test", indicators=indicators, public=False)
In [43]:
json_normalize(new_pulse)
Out[43]:
The following fields can be passed into create_pulse: