Liberty91LTD lookup-otx
Queries AlienVault OTX for community pulse context on IPs, domains, file hashes, and URLs. Retrieval only — do not interpret results.
When to invoke
- User asks what pulses reference an indicator
- Investigation skill needs community context (who's tracking this?)
- IOC enrichment pipeline is adding pulse metadata
How to invoke
Two CLIs are provided. Pick by capability needed:
Basic lookup — Node CLI (zero deps)
node tools/clis/otx.js <type> <value>
# where <type> is one of: ip, domain, hash, url
Hits the /general endpoint only. Returns pulses, related indicators, passive DNS, whois. Best for fast retrieval inside an investigation chain.
Advanced operations — Python CLI (uses official OTXv2 SDK)
python3 tools/clis/otx.py indicator <type> <value> [--section SECTION]
python3 tools/clis/otx.py pulse search <query> [--limit N]
python3 tools/clis/otx.py pulse get <pulse_id>
python3 tools/clis/otx.py pulse subscribed [--limit N]
Self-bootstraps a private venv at tools/clis/.venv-otx/ on first run (requires Python 3 + a working python3 -m venv). No global pip install.
Capabilities the Node CLI doesn't have:
- Full indicator details across every OTX section (general, reputation, geo, malware, url_list, passive_dns, http_scans, analysis) instead of just
/general. Pass--sectionto limit. - Pulse keyword search (
pulse search "lazarus") — discover pulses by topic. - Pulse retrieval by ID with full description, references, and indicator list.
- Subscribed pulses — list pulses your OTX account follows.
Examples:
# Basic — same shape as Node CLI but with all sections populated
python3 tools/clis/otx.py indicator domain example.com
# Just one section
python3 tools/clis/otx.py indicator ip 203.0.113.42 --section malware
# Hash type auto-detected from length (MD5/SHA1/SHA256)
python3 tools/clis/otx.py indicator hash 44d88612fea8a8f36de82e1278abb02f
# Discover pulses by keyword
python3 tools/clis/otx.py pulse search "ransomware exchange"
# Pull a specific pulse
python3 tools/clis/otx.py pulse get 5f8f3e6e2a1b3c4d5e6f7a8b
Both CLIs accept --dry-run to preview the request without calling the API. Both exit code 2 if $OTX_API_KEY is unset (when not in dry-run). Report missing key; do not fabricate.
Response format
source: otx
indicator: <value>
type: ip | domain | hash | url
query_time: <ISO8601>
pulse_count: <number>
key_pulses:
- name: <pulse name>
tags: [<tags>]
created: <date>
tlp: <TLP>
author: <author>
related_indicators: [<list>]
passive_dns: [<resolutions>] # only for IP/domain
Rate limits
Free tier: 10,000 req/hour — effectively unconstrained for interactive use.
Source reliability (Admiralty default)
Default rating for downstream /score-source: C3 (fairly reliable, possibly true). Community-submitted pulses vary wildly in quality. Upgrade to B2 if pulse author is a known trustworthy org (Mandiant, Unit42, Talos, etc.).
Related skills
/lookup-virustotal— reputation aggregator for the same indicator/lookup-urlscan— live scan of URLs/domains/score-source— apply Admiralty rating/ip-investigation,/domain-investigation,/hash-investigation,/url-investigation
See also
- Integration setup:
tools/integrations/otx.md - Node CLI source:
tools/clis/otx.js - Python CLI source (OTXv2 SDK):
tools/clis/otx.py - Official Python SDK: https://github.com/AlienVault-OTX/OTX-Python-SDK
- API reference: https://otx.alienvault.com/api