otxcli

Python library and CLI covering every endpoint of the AlienVault OTX v1 API

Overview

otxcli is a Python toolkit to query and manage threat intelligence on AlienVault OTX. Every endpoint documented in the OTX v1 API is implemented: indicator lookups, file/URL submissions, pulse management, search, and user actions — usable both as a command-line tool and as a typed Python library.

Key Features

Supported Outputs

CLI          Pretty-printed JSON on stdout, errors on stderr
Library      Decoded JSON (dict/list) per call, OTXError on failure

Installation

From PyPI (Recommended)

pip install otxcli

From Source

git clone https://github.com/seifreed/otxcli.git
cd otxcli
python3 -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate
pip install -e .

Quick Start

Get an API key from your OTX account settings and export it:

export OTX_API_KEY=your-key-here

# Validate your API key
otx me

# Look up an indicator
otx ipv4 8.8.8.8

# Search pulses
otx search-pulses zeus --limit 5

Usage

Command Line Interface

# Indicator sections
otx ipv4 8.8.8.8 --section reputation
otx domain rghost.net --section malware
otx file 6c5360d41bd2b14b1565f5b18e5c203cf512e493 --section analysis
otx url http://example.com/ --section url_list
otx cve CVE-2014-0160

# Submissions
otx submit-url http://example.com/ --tlp white
otx submit-file suspicious.bin
otx submitted-files --limit 10 --sort add_date

# Pulses
otx pulse 57204e9b3c4c3e015d93cb12
otx create-pulse '{"name": "My pulse", "public": true, "TLP": "white"}'
otx edit-pulse 57204e9b3c4c3e015d93cb12 '{"description": "New description"}'
otx subscribed-pulses --limit 10 --modified-since 2026-01-01T00:00:00+00:00

# Users
otx subscribe-to-user AlienVault

Available Commands

Run otx --help for the full list and otx <command> --help for the options of a specific command.

Global Options

Python Library

Basic Usage

from otxcli import OTXClient

client = OTXClient("your-key-here")

client.me()
client.ipv4("8.8.8.8", section="reputation")
client.domain("rghost.net", section="malware")
client.search_pulses("zeus", limit=5)

pulse = client.create_pulse({"name": "My pulse", "public": True, "TLP": "white"})
client.edit_pulse(pulse["id"], {"description": "New description"})
client.delete_pulse(pulse["id"])

Every method returns the decoded JSON response, or None when the endpoint answers with an empty body. HTTP errors and unparseable responses raise otxcli.OTXError, which carries status and detail attributes.

Internationalized Domains

domain and hostname accept internationalized names: OTX only resolves ASCII hosts, so the name is converted to punycode with UTS46 mapping, the same rules a browser applies. client.domain("bücher.de") looks up xn--bcher-kva.de, and a homograph such as ᴳoogle.com reaches google.com rather than a lookalike nobody serves. ASCII hostnames are sent exactly as given.

Requirements

• Python 3.14+
• One runtime dependency: idna — see pyproject.toml

Development

All dependencies (runtime and development) live in pyproject.toml:

pip install -e '.[dev]'

Quality and security gates, all of which must pass clean:

black --check .
ruff check .
mypy .
bandit -r .
pip-audit

Tests run against the live OTX API (no mocks) and require OTX_API_KEY:

export OTX_API_KEY=your-key-here
pytest

Coverage below 100% fails the build.

Contributing

Contributions are welcome.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Support the Project

If this project is useful in your workflows, you can support development:

License

This project is licensed under the MIT license. See LICENSE.

Attribution

• Author: Marc Rivero López | @seifreed
• Repository: github.com/seifreed/otxcli

_{Built for practical threat intelligence workflows and security automation}