You can install the SDK directly from PyPI using pip. Alternatively, you can install it from the source by cloning the repository and running the setup script.

pip install OTXv2

Or from source

# From the root directory of the cloned repo
pip install .
# OR
python setup.py install

To use the SDK within a Jupyter Notebook environment, follow these steps:

1. Clone the repository.
2. Install pandas and jupyter.
3. Launch the provided notebook howto_use_python_otx_api.ipynb.

pip install pandas
pip install jupyter

# Run the notebook

jupyter notebook howto_use_python_otx_api.ipynb

To use the OTX-Python-SDK, import OTxv2 and initialize the client with your OTX API key. You can obtain your API key from your AlienVault OTX settings page.

from OTXv2 import OTXv2

otx = OTXv2("YOUR_KEY")

Use the OTXV2 class to interact with the Open Threat Exchange. You can retrieve all indicators associated with a specific pulse ID or fetch full details for a specific indicator type (e.g., Domain, IP, etc.).

from OTXv2 import OTXv2
from OTXv2 import IndicatorTypes

# Initialize with your API Key
otx = OTXv2("API_KEY")

# Get all the indicators associated with a pulse
indicators = otx.get_pulse_indicators("pulse_id")
for indicator in indicators:
    print indicator["indicator"] + indicator["type"]

# Get everything OTX knows about a specific domain
otx.get_indicator_details_full(IndicatorTypes.DOMAIN, "google.com")

You can programmatically create a new pulse by providing a name, visibility (public/private), and a list of indicators. Each indicator in the list must be a dictionary containing the indicator value and its type.

from OTXv2 import OTXv2

otx = OTXv2("API_KEY")
name = 'Test Pulse'
indicators = [
    {'indicator': '69.73.130.198', 'type': 'IPv4'},
    {'indicator': 'aoldaily.com', 'type': 'Domain'}
]

# Create the pulse
response = otx.create_pulse(name=name, public=True, indicators=indicators, tags=[], references=[])
print str(response)

The getall() method retrieves all pulses and their associated Indicators of Compromise (IOCs) that you are subscribed to. This includes:

• Pulses you subscribe to directly.
• Pulses from users you follow.
• Pulses you created (including private ones).
• All pulses created by AlienVault (by default for new accounts).

Each pulse object contains metadata such as author_name, created, description, id, indicators, modified, name, references, revision, and tags.

pulses = otx.getall()

Use getevents_since(mtime) to retrieve events occurring in the OTX system that affect your account. This is useful for reconciling local data with the server when users subscribe/unsubscribe or delete pulses.

Event Fields:

• id: Unique reference identifier.
• action: One of [subscribe | unsubscribe | delete].
• object_type: One of [pulse | user].
• object_id: The unique ID of the pulse or author.
• created: Timestamp of the event.

# Example using an ISO format timestamp
mtime = "2023-01-01T00:00:00"
events = otx.getevents_since(mtime)

Use get_indicator_details_full(indicator_type, indicator) to retrieve comprehensive information about a specific IOC. You must provide the indicator type using the IndicatorTypes class.

Note: Detailed information is not available for all indicator types. Check IndicatorTypes.supported_api_types to see which types support full detail retrieval.

from OTXv2 import IndicatorTypes

# Example: Getting details for an IPv4 indicator
indicator_value = "82.194.84.121"
details = otx.get_indicator_details_full(IndicatorTypes.IPv4, indicator_value)

You can search for pulses and users by keyword using search_pulses(), which allows you to find content you are not yet subscribed to. To get the full details (including all indicators) for a specific pulse found in the search, use get_pulse_details(pulse_id).

# Search for pulses containing a keyword
search_results = otx.search_pulses("Russian")

# Get details for a specific pulse ID from the results
# Note: search_pulses returns a dict with a 'results' key
pulse_id = search_results["results"][0]["id"]

details = otx.get_pulse_details(pulse_id)

The following indicator types are supported by the SDK and are defined in the IndicatorTypes class:

• IPv4 / IPv6: IP addresses.
• domain / hostname: Domain and host information.
• email: Suspicious email addresses.
• URL / URI: Web locations and paths.
• FileHash-MD5 / FileHash-SHA1 / FileHash-SHA256 / FileHash-PEHASH / FileHash-IMPHASH: Various file hash formats.
• CIDR: Network architecture/routing paths.
• FilePath: File system locations.
• Mutex: Mutex resource names.
• CVE: Common Vulnerability and Exposure entries.

# These are accessible via the IndicatorTypes class
# e.g., IndicatorTypes.IPv4, IndicatorTypes.domain, etc.