OTX Example API Calls

= Examples of how OTX API calls relate different indicator types =
Official documentation is available at https://otx.alienvault.com/api but may be missing a couple of the newer calls
These are some unofficial notes
The API key below is for a dummy demo account. It should work but I would suggest using your own.
Some of the JSON responses are quite nested, and editor such as http://jsoneditoronline.org/ may be useful

== Input: Hostname / Domain ==

The following calls can be made for both domains and hostname, ie you can swap 'hostname' with 'domain' below.

= Get Reports, Adversary from hostname =
curl https://otx.alienvault.com/api/v1/indicator/hostname/ahnlab.myfw.us
Output: Report Names - in the 'name' key in list pulse_info.pulses. Eg; "Continued HeartBeat APT activity", "testRaja"
Output: Adversary - in the 'adversary' key in list pulse_info.pulses Eg; "Heartbeat"

= Get Filehashes from hostname =
curl https://otx.alienvault.com/api/v1/indicator/hostname/google.com/malware?limit=50&page=1
Output: SHA256 Filehashes - eg; 0e083dd6ce3c7d4e296c5c74c5d1ac7a096341e362bbc773970d48380d784a2b

= Get Whois data from a hostname =
curl https://otx.alienvault.com/api/v1/indicator/hostname/google.com/whois
Output: Hostnames - that are nameservers eg; 'ns3.google.com', 'ns2.google.com' - Anything in data. with the key 'name_servers'
Output: Emails - eg 'dns-admin@google.com', 'abusecomplaints@markmonitor.com' - Anything in data. with the key 'emails'
Output: Country - eg 'US' - Anything in the list data. with the key 'country'
Theses are a bit odd as they are two hops in one API call - and may fit better under a different heading:
Output: Domains - related by shared e-mail eg 'blogger.com'. The key 'domain' in the list 'related', where 'related_type' is 'email'.
Output: Domains - related by shared SSL eg 'maps.gstatic.com'. The key 'domain' in the list 'related', where 'related_type' is 'ssl'.

curl https://otx.alienvault.com/indicator/hostname/coin-hive.com
Output: Domains - that link to the domain. Eg; 'applelostiphones.com'. The key 'domain' in the list 'related', where 'related_type' is 'link'.

= Get URLs from a hostname =
Output: URLs - in list url_list. Eg; https://google.com/url?q=https
curl https://otx.alienvault.com/api/v1/indicator/hostname/google.com/url_list

= Get HTTP(S) Scan Data =
curl https://otx.alienvault.com/api/v1/indicator/hostname/google.com/http_scans
Output: Domains - from alternative SSL names. Eg; 'android.com'. Anything in the list 'data' with the key '443 Certificate Subjectaltname'

curl https://otx.alienvault.com/api/v1/indicator/hostname/applelostiphones.com/http_scans
Output: URLs - that this domain loads scripts from. Eg; 'https://coin-hive.com/lib/coinhive.min.js'. Anything in the list 'data' with 'script_urls' in the key.
Output: Domains - that this domain loads scripts from. Eg; 'coin-hive.com'. Anything in the list 'data' with 'script_domains' in the key.
Output: Domains - that this domain links to. Eg; 'wordpress.org'. Anything in the list 'data' with 'a_domains' in the key.

= Passive DNS =
curl https://otx.alienvault.com/api/v1/indicator/hostname/alienvault.com/passive_dns
Output: IP Addresses - that the domain resolves to. Eg; '104.25.119.19'. The key 'address' in the list 'passive_dns'.





== Get details from IP Address ==

= Get Reports, Adversary from hostname =
curl https://otx.alienvault.com/api/v1/indicator/IPv4/103.10.197.50/
Output: Report Name - from 'name' fields in list pulse_info.pulses. Eg; "TOR-Relay-Nodes"
Output: Adversary - from 'adversary' field in list pulse_info.pulses

= Get GEO information =
curl https://otx.alienvault.com/api/v1/indicator/IPv4/103.10.197.50/geo
Output: Country - from 'Country' field. Eg; 'Hong Kong'

= Get reverse DNS =
curl https://otx.alienvault.com/api/v1/indicator/IPv4/8.8.8.8/passive_dns
Output: Hostnames that resolve to the IP address. Eg; 'pctestrenos.com'. In the field 'hostname'.

= Get Snort signatures that that IP address has fired from our telemetry =
curl "https://otx.alienvault.com/api/v1/indicator/IPv4/103.10.197.50/nids_list" -H "X-OTX-API-KEY: 766ba1df3ab54db9c0fcbf62ef048c3a04c260e8ca65b6c25346084b7b4719ad"
Output: Snort signature IDs in the list 'result'. Eg; '2018789'.

= Get malware =
curl https://otx.alienvault.com/api/v1/indicator/IPv4/103.10.197.50/malware
Same as examples above for hostname

= Get HTTP(s) Scan Data =
curl https://otx.alienvault.com/api/v1/indicator/IPv4/8.8.8.8/http_scans
Same as above examples for hostname

= Get URLs =
curl https://otx.alienvault.com/api/v1/indicator/IPv4/8.8.8.8/url_list
Same as above examples for hostname






== Get Details from Malware =

= Get Reports, Adversary from filehash =
curl https://otx.alienvault.com/api/v1/indicator/file/464535ead01ac837e1329effb49e4d8074b466eb70fe0949410e75b68c2a61e6
curl https://otx.alienvault.com/api/v1/indicator/file/272cb6c16e083ca143d40c63005753a2
Output: Report Name - from 'name' fields in list pulse_info.pulses. Eg; "APT3 Uncovered: The code evolution of Pirpi"
Output: Adversary - from 'adversary' field in list pulse_info.pulses. Eg; 'UPS'

= Get Sandbox data from filehash =
curl https://otx.alienvault.com/api/v1/indicator/file/43e1abf631e0f08c6ad659833c7828d4e9b2a6fb218fe6bdcc305676959a14a0/analysis
Output: IP Addresses - from 'dst' fields in analysis.plugins.cuckoo.result.network.hosts. Eg; '78.46.218.253'
Output: Domains - from 'request' fields in analysis.plugins.cuckoo.result.network.dns. Eg; 'www.cnzztj.net'
Output: Snort Rule IDs - from 'sid' fields in analysis.plugins.cuckoo.result.network.suricata.rules. Eg; '2009991'
Output: Snort Rule Names - from 'name' fields in analysis.plugins.cuckoo.result.network.suricata.rules. Eg; 'User-Agent (MyIE/1.0)'
Output: Malware family name - from analysis.plugins.avast.detection. Eg; 'Win32:Dogkild'
There is also an API in the UI API to take a malware family name and return file hashes, but I don't think it's available in the API yet.






== Get Details from E-Mails ==

= Get Reports, Adversary from E-mail =
curl https://otx.alienvault.com/api/v1/indicator/email/04@gmail.com
Same as above

= Domains from reverse-whois search =
curl https://otx.alienvault.com/api/v1/indicator/email/contact-admin@google.com/whois
Output: Domains - from 'domain' field in list. Eg; 'blogger.com', 'google.com'.




== Get Details from URLs ==

= Get Reports, Adversary from e-mail =
curl https://otx.alienvault.com/api/v1/indicator/url/http:%252F%252Fdchs.edu.bd%252Fvxx%252Fmcsmed%252F/general
Same as above

= Get HTTP(S) Scan Data =
https://otx.alienvault.com/api/v1/indicator/url/http:%252F%252Fdchs.edu.bd%252Fvxx%252Fmcsmed%252F/http_scans
Same as above





== Snort Signatures ==

= Get IP Addresses from Snort signature ID =
curl "https://otx.alienvault.com/api/v1/indicator/nids/2819973/ip_list?limit=50&page=1" -H "X-OTX-API-KEY: 766ba1df3ab54db9c0fcbf62ef048c3a04c260e8ca65b6c25346084b7b4719ad"
Output: IPv4s ["189.218.72.4", "187.160.144.5" etc.]





== Upload Indicators to OTX ==
If you want an upload functionality, which will store the data on the site otx.alienvault.com for others to view.
The following example will create a pulse, visible at https://otx.alienvault.com/user/api_example/pulses, with the domain 'aoldaily.com' and the IP '69.73.130.198'

from OTXv2 import OTXv2
otx = OTXv2("766ba1df3ab54db9c0fcbf62ef048c3a04c260e8ca65b6c25346084b7b4719ad")
name = 'Autognerated Pulse'
indicators = [{'indicator': '69.73.130.198', 'type': 'IPv4'},{'indicator': 'aoldaily.com', 'type': 'Domain'}]
response = otx.create_pulse(name=name ,public=True ,indicators=indicators ,tags=[] , references=[])