Introduction
Summary of Resource URL Patterns
/v1/repcategories
/v1/domains/{domain}/events
/v1/domains/{domain}/geoloc
/v1/domains/{domain}/ips
/v1/domains/{domain}/nameservers
/v1/domains/{domain}/reputation
/v1/domains/{domain}/samples
/v1/domains/{domain}/urls
/v1/domains/{domain}/whois
/v1/ips/{ip}/domains
/v1/ips/{ip}/events
/v1/ips/{ip}/geoloc
/v1/ips/{ip}/reputation
/v1/ips/{ip}/samples
/v1/ips/{ip}/urls
/v1/samples/{md5}
/v1/samples/{md5}/connections
/v1/samples/{md5}/dns
/v1/samples/{md5}/events
/v1/samples/{md5}/http
/v1/sids/{sid}
/v1/sids/{sid}/ips
/v1/sids/{sid}/domains
/v1/sids/{sid}/samples
The ET Intelligence API is organized around REST with JSON responses. Our API is designed to use HTTP response codes to indicate API success/errors. We support cross-origin resource sharing (CORS) to allow you to interact with our API from a client-side web application. JSON will be returned in all responses from the API.
The ET Intelligence API can be used to get information such as up-to-date reputation of domains and IPs, as well as related information on our entire database of over 300 million malware samples.
We currently have code examples using curl and Python. If you have a particular language you'd like to see API examples for, please let us know. You can view code examples in the dark area to the right, and you can switch the programming language of the examples with the tabs in the top right.
Authentication
To authenticate, use this code:
# With curl, you can just pass the correct header with each request
curl https://api.emergingthreats.net/v1/repcategories -H "Authorization: SECRETKEY"
from urllib2 import Request, urlopen
request = Request("api_endpoint_here")
request.add_header("Authorization", "SECRETKEY")
Make sure to replace
SECRETKEYwith your API key.
Emerging Threats uses API keys to allow access to our API. If your company has paid for API access, you can find your API key by visiting https://etadmin.proofpoint.com/api-access.
The Query API expects for the API key to be included in all API requests to the server in a header that looks like the following:
Authorization: SECRETKEY
Rate-limiting
The ET Intelligence API will rate limit requests on a per-API key basis. If you exceed your rate limit you will receive an API response with a 429 HTTP status code and a brief message indicating you have exceeded your rate limit. To increase your rate limit, contact sales.
The JSON response associated with an exceeded rate limit should look something like:
{
"success": false,
"message": "Rate limit exceeded",
"response": {}
}
Reputation Metadata
List reputation categories
curl https://api.emergingthreats.net/v1/repcategories -H "Authorization: SECRETKEY"
from urllib2 import Request, urlopen
request = Request("https://api.emergingthreats.net/v1/repcategories")
request.add_header("Authorization", "SECRETKEY")
result = urlopen(request)
print result.read()
The JSON response should look something like:
{
"success": true,
"response": [
{
"name": "Bot",
"description": "Known Infected Bot"
},
{
"name": "CnC",
"description": "Malware Command and Control Server"
},
{
"name": "Spam",
"description": "Known Spam Source"
}
]
}
This endpoint lists all of the possible categories for reputation categorization and a brief description of each item.
HTTP Request
GET https://api.emergingthreats.net/v1/repcategories
Response Parameters
| Parameter | Optional? | Description |
|---|---|---|
| name | No | The name of the reputation category. |
| description | No | A brief description of the category. |
Domain Information
Get current domain reputation
curl "https://api.emergingthreats.net/v1/domains/{domain}/reputation"
-H "Authorization: SECRETKEY"
from urllib2 import Request, urlopen
request = Request("https://api.emergingthreats.net/v1/domains/{domain}/reputation")
request.add_header("Authorization", "SECRETKEY")
result = urlopen(request)
print result.read()
The JSON response should look something like:
{
"success": true,
"response": [
{
"category": "DynDNS",
"score": 120
},
{
"category": "CnC",
"score": 100
},
{
"category": "SpywareCnC",
"score": 95
}
]
}
This endpoint retrieves the current reputation scores in categories that are currently associated with the specified domain.
HTTP Request
GET https://api.emergingthreats.net/v1/domains/{domain}/reputation
Response Parameters
| Parameter | Optional? | Description |
|---|---|---|
| category | No | The category of reputation under which this score falls. |
| score | No | The numerical reputation score for this category. Scores are non-negative integers ranging from 0 to 127. |
Get domain malware-requested URLs
curl "https://api.emergingthreats.net/v1/domains/{domain}/urls"
-H "Authorization: SECRETKEY"
from urllib2 import Request, urlopen
request = Request("https://api.emergingthreats.net/v1/domains/{domain}/urls")
request.add_header("Authorization", "SECRETKEY")
result = urlopen(request)
print result.read()
The JSON response should look something like:
{
"success": true,
"response": [
"/index.php?id=XXXXXXXXXXXXXXX&scn=X&inf=X&ver=XX&cnt=XXX",
"/index.php?id=XXXXXXXXXXXXXX&scn=X&inf=X&ver=XX&cnt=XXX",
"/index.php?id=XXXXXXXXXXXXXXXXXX&scn=X&inf=X&ver=XX&cnt=XXX"
]
}
This endpoint retrieves the most recent http requests made by malware to the specified domain.
HTTP Request
GET https://api.emergingthreats.net/v1/domains/{domain}/urls
Response Parameters
| Parameter | Optional? | Description |
|---|---|---|
| url | No | The url string of the request with query parameter values masked. |
Get domain related malware samples
curl "https://api.emergingthreats.net/v1/domains/{domain}/samples"
-H "Authorization: SECRETKEY"
from urllib2 import Request, urlopen
equest = Request("https://api.emergingthreats.net/v1/domains/{domain}/samples")
request.add_header("Authorization", "SECRETKEY")
result = urlopen(request)
print result.read()
The JSON response should look something like:
{
"success": true,
"response": [
{
"source": "45999bfea907bf37acbab63d5d9ea683",
"first_seen": "2014-02-13",
"last_seen": "2014-02-13"
},
{
"source": "f75da3cd3a38aadebdcf86eb53c6eb1c",
"first_seen": "2014-02-13",
"last_seen": "2014-02-13"
}
]
}
This endpoint retrieves the most recent malware samples that communicated with the specified domain.
HTTP Request
GET https://api.emergingthreats.net/v1/domains/{domain}/samples
Response Parameters
| Parameter | Optional? | Description |
|---|---|---|
| source | No | The md5sum of the malware sample. |
| first_seen | No | The date the malware sample was first seen associated to the domain. |
| last_seen | No | The date the malware sample was last seen associated to the domain. |
Get domain related IPs
curl "https://api.emergingthreats.net/v1/domains/{domain}/ips"
-H "Authorization: SECRETKEY"
from urllib2 import Request, urlopen
request = Request("https://api.emergingthreats.net/v1/domains/{domain}/ips")
request.add_header("Authorization", "SECRETKEY")
result = urlopen(request)
print result.read()
The JSON response should look something like:
{
"success": true,
"response": [
{
"ip": "213.219.245.212",
"first_seen": "2011-12-04",
"last_seen": "2012-02-27"
},
{
"ip": "78.109.30.160",
"first_seen": "2014-02-22",
"last_seen": "2014-04-09"
}
]
}
This endpoint retrieves the most recent IPs that have been associated with the specified domain.
HTTP Request
GET https://api.emergingthreats.net/v1/domains/{domain}/ips
Response Parameters
| Parameter | Optional? | Description |
|---|---|---|
| ip | No | |
| first_seen | No | The date the IP was first seen associated to the domain. |
| last_seen | No | The date the IP was last seen associated to the domain. |
Get domain related IDS events
curl "https://api.emergingthreats.net/v1/domains/{domain}/events"
-H "Authorization: SECRETKEY"
from urllib2 import Request, urlopen
request = Request("https://api.emergingthreats.net/v1/domains/{domain}/events")
request.add_header("Authorization", "SECRETKEY")
result = urlopen(request)
print result.read()
The JSON response should look something like:
{
"success": true,
"response": [
{
"domain": "citi-bank.ru",
"date": "2014-03-31",
"source": false,
"sid": "2803583",
"signature": "ETPRO TROJAN Win32.Sality.At Checkin",
"count": 1
},
{
"domain": "citi-bank.ru",
"date": "2014-03-23",
"source": false,
"sid": "2803583",
"signature": "ETPRO TROJAN Win32.Sality.At Checkin",
"count": 2
}
]
}
This endpoint retrieves the most recent IDS events that have been observed against the specified domain.
HTTP Request
GET https://api.emergingthreats.net/v1/domains/{domain}/events
Response Parameters
| Parameter | Optional? | Description |
|---|---|---|
| domain | No | |
| date | No | The date the IDS event was observed. |
| source | No | Indicates whether the domain was the source of the IDS event. |
| sid | No | The SID that generated the IDS event. |
| signature | No | The signature name of the SID that generated the IDS event. |
| count | No | How many times this particular IDS event was observed in our sensor net for the given date. |
Get domain nameserver info
curl "https://api.emergingthreats.net/v1/domains/{domain}/nameservers"
-H "Authorization: SECRETKEY"
from urllib2 import Request, urlopen
request = Request("https://api.emergingthreats.net/v1/domains/{domain}/nameservers")
request.add_header("Authorization", "SECRETKEY")
result = urlopen(request)
print result.read()
The JSON response should look something like:
{
"success": true,
"response": [
{
"server": "ns1.yourhostingaccount.com.",
"first_seen": "2013-02-15",
"last_seen": "2013-11-17"
},
{
"server": "ns1.mydomain.com",
"first_seen": "2013-08-16",
"last_seen": "2013-11-17"
}
]
}
This endpoint retrieves the nameserver information related to the specified domain.
HTTP Request
GET https://api.emergingthreats.net/v1/domains/{domain}/nameservers
Response Parameters
| Parameter | Optional? | Description |
|---|---|---|
| server | No | The address of a nameserver associated with the domain. |
| first_seen | Yes | The date the nameserver was first seen associated to the domain. |
| last_seen | Yes | The date the nameserver was last seen associated to the domain. |
Get domain whois info
curl "https://api.emergingthreats.net/v1/domains/{domain}/whois"
-H "Authorization: SECRETKEY"
from urllib2 import Request, urlopen
request = Request("https://api.emergingthreats.net/v1/domains/{domain}/whois")
request.add_header("Authorization", "SECRETKEY")
result = urlopen(request)
print result.read()
The JSON response should look something like:
{
"success": true,
"response": {
"domain": "bing.com",
"registrant": {
"name": "Microsoft Corporation",
"email": "domains@microsoft.com",
"created": "1996-01-29",
"updated": "2012-11-29",
"expires": "2019-01-30"
},
"registrar": {
"name": "MarkMonitor Inc.",
"country": "USA",
"website": "http://www.markmonitor.com"
}
}
}
This endpoint retrieves whois info for a single domain.
HTTP Request
GET https://api.emergingthreats.net/v1/domains/{domain}/whois
Response Parameters
| Parameter | Optional? | Description |
|---|---|---|
| domain | No | The domain associated with the whois record. |
| registrant.name | Yes | Name of the domain registrant. |
| registrant.email | Yes | Email address of the domain registrant. |
| registrant.created | Yes | Date the whois record was originally created. |
| registrant.updated | Yes | Date the whois record was last updated. |
| registrant.expires | Yes | Date the whois record will expire. |
| registrar.name | Yes | Name of the domain registrar. |
| registrar.country | Yes | Home country of the domain registrar. |
| registrar.website | Yes | Homepage for the domain registrar. |
Get domain geolocation info
curl "https://api.emergingthreats.net/v1/domains/{domain}/geoloc"
-H "Authorization: SECRETKEY"
from urllib2 import Request, urlopen
request = Request("https://api.emergingthreats.net/v1/domains/{domain}/geoloc")
request.add_header("Authorization", "SECRETKEY")
result = urlopen(request)
print result.read()
The JSON response should look something like:
{
"success": true,
"response": [
{
"ip": "107.20.206.69",
"country_code": "US",
"country": "United States",
"region": "VA",
"city": "Ashburn",
"latitude": 39.043701171875,
"longitude": -77.48750305175781
},
{
"ip": "216.38.198.78",
"country_code": "US",
"country": "United States",
"region": "CO",
"city": "Henderson",
"latitude": 39.88650131225586,
"longitude": -104.88099670410156
}
]
}
This endpoint retrieves geolocation info for a single domain.
HTTP Request
GET https://api.emergingthreats.net/v1/domains/{domain}/geoloc
Response Parameters
| Parameter | Optional? | Description |
|---|---|---|
| ip | No | An IP associated with the specified domain. |
| country_code | No | The two character ISO 3166-1 alpha-2 country code in which the IP was last observed. |
| country | Yes | The country in which the IP was last observed. |
| region | Yes | A two character ISO-3166-2 or FIPS 10-4 code for the state or region associated with the IP. |
| city | Yes | The city or town name associated with the IP. |
| latitude | Yes | The latitude associated with the IP. |
| longitude | Yes | The longitude associated with the IP. |
IP Information
Get current IP reputation
curl "https://api.emergingthreats.net/v1/ips/{ip}/reputation"
-H "Authorization: SECRETKEY"
from urllib2 import Request, urlopen
request = Request("https://api.emergingthreats.net/v1/ips/{ip}/reputation")
request.add_header("Authorization", "SECRETKEY")
result = urlopen(request)
print result.read()
The JSON response should look something like:
{
"success": true,
"response": [
{
"category": "DynDNS",
"score": 120
},
{
"category": "CnC",
"score": 100
},
{
"category": "SpywareCnC",
"score": 95
}
]
}
This endpoint retrieves the current reputation scores in categories that are currently associated with the specified IP.
HTTP Request
GET https://api.emergingthreats.net/v1/ips/{ip}/reputation
Response Parameters
| Parameter | Optional? | Description |
|---|---|---|
| category | No | The category of reputation under which this score falls. |
| score | No | The numerical reputation score for this category. Scores are non-negative integers ranging from 0 to 127. |
Get IP malware-requested URLs
curl "https://api.emergingthreats.net/v1/ips/{ip}/urls"
-H "Authorization: SECRETKEY"
from urllib2 import Request, urlopen
request = Request("https://api.emergingthreats.net/v1/ips/{ip}/urls")
request.add_header("Authorization", "SECRETKEY")
result = urlopen(request)
print result.read()
The JSON response should look something like:
{
"success": true,
"response": [
"/index.php?id=XXXXXXXXXXXXXXX&scn=X&inf=X&ver=XX&cnt=XXX",
"/index.php?id=XXXXXXXXXXXXXX&scn=X&inf=X&ver=XX&cnt=XXX",
"/index.php?id=XXXXXXXXXXXXXXXXXX&scn=X&inf=X&ver=XX&cnt=XXX"
]
}
This endpoint retrieves the most recent http requests made by malware to the specified IP.
HTTP Request
GET https://api.emergingthreats.net/v1/ips/{ip}/urls
Response Parameters
| Parameter | Optional? | Description |
|---|---|---|
| url | No | The url string of the request with query parameter values masked. |
Get IP related malware samples
curl "https://api.emergingthreats.net/v1/ips/{ip}/samples"
-H "Authorization: SECRETKEY"
from urllib2 import Request, urlopen
request = Request("https://api.emergingthreats.net/v1/ips/{ip}/samples")
request.add_header("Authorization", "SECRETKEY")
result = urlopen(request)
print result.read()
The JSON response should look something like:
{
"success": true,
"response": [
{
"source": "6c885bee0b4ef2f539b26298b252212d",
"first_seen": "2014-05-13",
"last_seen": "2014-05-13"
},
{
"source": "8449da068aec412fbec6fd48bc675396",
"first_seen": "2014-05-03",
"last_seen": "2014-05-03"
}
]
}
This endpoint retrieves the most recent malware samples that communicated with the specified IP.
HTTP Request
GET https://api.emergingthreats.net/v1/ips/{ip}/samples
Response Parameters
| Parameter | Optional? | Description |
|---|---|---|
| source | No | The md5sum of the malware sample. |
| first_seen | No | The date the malware sample was first seen associated to the IP. |
| last_seen | No | The date the malware sample was last seen associated to the IP. |
Get IP related domains
curl "https://api.emergingthreats.net/v1/ips/{ip}/domains"
-H "Authorization: SECRETKEY"
from urllib2 import Request, urlopen
request = Request("https://api.emergingthreats.net/v1/ips/{ip}/domains")
request.add_header("Authorization", "SECRETKEY")
result = urlopen(request)
print result.read()
The JSON response should look something like:
{
"success": true,
"response": [
{
"domain": "citi-bank.ru",
"first_seen": "2014-02-22",
"last_seen": "2014-04-09"
},
{
"domain": "tat-neftbank.ru",
"first_seen": "2014-04-04",
"last_seen": "2014-04-04"
}
]
}
This endpoint retrieves the most recent domains that have been associated with the specified IP.
HTTP Request
GET https://api.emergingthreats.net/v1/ips/{ip}/domains
Response Parameters
| Parameter | Optional? | Description |
|---|---|---|
| domain | No | |
| first_seen | No | The date the domain was first seen associated to the IP. |
| last_seen | No | The date the domain was last seen associated to the IP. |
Get IP related IDS events
curl "https://api.emergingthreats.net/v1/ips/{ip}/events"
-H "Authorization: SECRETKEY"
from urllib2 import Request, urlopen
request = Request("https://api.emergingthreats.net/v1/ips/{ip}/events")
request.add_header("Authorization", "SECRETKEY")
result = urlopen(request)
print result.read()
The JSON response should look something like:
{
"success": true,
"response": [
{
"ip": "208.111.161.254",
"date": "2014-04-08",
"source": false,
"sid": "2008365",
"signature": "ET TROJAN Playtech Downloader Online Gaming Checkin",
"count": 1
},
{
"ip": "208.111.161.254",
"date": "2014-04-02",
"source": false,
"sid": "2008365",
"signature": "ET TROJAN Playtech Downloader Online Gaming Checkin",
"count": 1
}
]
}
This endpoint retrieves the most recent IDS events that have been observed against the specified IP.
HTTP Request
GET https://api.emergingthreats.net/v1/ips/{ip}/events
Response Parameters
| Parameter | Optional? | Description |
|---|---|---|
| ip | No | The string representation of the IP address, or "private" if it was a private IP. |
| date | No | The date the IDS event was observed. |
| source | No | Indicates whether the IP was the source of the IDS event. |
| sid | No | The SID that generated the IDS event. |
| signature | No | The signature name of the SID that generated the IDS event. |
| count | No | How many times this particular IDS event was observed in our sensor net for the given date. |
Get IP geolocation info
curl "https://api.emergingthreats.net/v1/ips/{ip}/geoloc"
-H "Authorization: SECRETKEY"
from urllib2 import Request, urlopen
request = Request("https://api.emergingthreats.net/v1/ips/{ip}/geoloc")
request.add_header("Authorization", "SECRETKEY")
result = urlopen(request)
print result.read()
The JSON response should look something like:
{
"success": true,
"response": [
{
"ip": "216.38.198.78",
"country_code": "US",
"country": "United States",
"region": "CO",
"city": "Henderson",
"latitude": 39.88650131225586,
"longitude": -104.88099670410156
}
]
}
This endpoint retrieves geolocation info for a single IP address.
HTTP Request
GET https://api.emergingthreats.net/v1/ips/{ip}/geoloc
Response Parameters
| Parameter | Optional? | Description |
|---|---|---|
| ip | No | The IP address specified. |
| country_code | No | The two character ISO 3166-1 alpha-2 country code in which the IP was last observed. |
| country | Yes | The country in which the IP was last observed. |
| region | Yes | A two character ISO-3166-2 or FIPS 10-4 code for the state or region associated with the IP. |
| city | Yes | The city or town name associated with the IP. |
| latitude | Yes | The latitude associated with the IP. |
| longitude | Yes | The longitude associated with the IP. |
Malware Samples
Get sample details
curl "https://api.emergingthreats.net/v1/samples/{md5}"
-H "Authorization: SECRETKEY"
from urllib2 import Request, urlopen
request = Request("https://api.emergingthreats.net/v1/samples/{md5}")
request.add_header("Authorization", "SECRETKEY")
result = urlopen(request)
print result.read()
The JSON response should look something like:
{
"success": true,
"response": {
"md5sum": "fa86e86e9dfb7a4571b3c3091fbf4bff",
"submit_date": "2012-06-11 04:00:00",
"file_type": "PE32 executable for MS Windows (DLL) (console) Intel 80386 32-bit",
"file_size": 69459,
"sha256": "e12012672d33cbcb22cf953ff787af250f8f5e920c565f03d4496a619c13a889"
}
}
This endpoint retrieves metadata information for a single malware sample.
HTTP Request
GET https://api.emergingthreats.net/v1/samples/{md5}
Response Parameters
| Parameter | Optional? | Description |
|---|---|---|
| md5 | No | The MD5 hash of the binary. |
| submit_date | No | The date and time the malware was originally submitted to Emerging Threats; format is yyyy-MM-dd HH:mm:ss |
| file_type | Yes | |
| file_size | Yes | The size of the binary in bytes. |
| sha256 | Yes | The SHA-256 hash of the binary. |
Get sample connections
curl "https://api.emergingthreats.net/v1/samples/{md5}/connections"
-H "Authorization: SECRETKEY"
from urllib2 import Request, urlopen
request = Request("https://api.emergingthreats.net/v1/samples/{md5}/connections")
request.add_header("Authorization", "SECRETKEY")
result = urlopen(request)
print result.read()
The JSON response should look something like:
{
"success": true,
"response": [
{
"source": "177f3c8a2623d4efb41b0020d680be83",
"date": "2014-03-31",
"source_ip": "10.10.10.104",
"destination_ip": "178.254.11.36",
"source_port": 49382,
"destination_port": 80,
"bytes_down": 508,
"bytes_up": 306,
"bytes_total": 814,
"packets_down": 4,
"packets_up": 6,
"packets_total": 10,
"protocol": "tcp"
},
{
"source": "177f3c8a2623d4efb41b0020d680be83",
"date": "2014-03-31",
"source_ip": "10.10.10.104",
"destination_ip": "208.117.232.117",
"source_port": 49381,
"destination_port": 80,
"bytes_down": 0,
"bytes_up": 0,
"bytes_total": 0,
"packets_down": 2,
"packets_up": 4,
"packets_total": 6,
"protocol": "tcp"
}
]
}
This endpoint retrieves the most recent connections an individual malware sample was observed to have made.
HTTP Request
GET https://api.emergingthreats.net/v1/samples/{md5}/connections
Response Parameters
| Parameter | Optional? | Description |
|---|---|---|
| source | No | The source of the connection. |
| date | No | The date the connection was observed. |
| source_ip | No | The source IP of the traffic associated with the connection. |
| destination_ip | No | The destination IP of the traffic associated with the connection. |
| source_port | No | The source port of the traffic associated with the connection. |
| destination_port | No | The destination port of the traffic associated with the connection. |
| bytes_down | Yes | The total number of bytes downloaded via this connection. |
| bytes_up | Yes | The total number of bytes uploaded via this connection. |
| bytes_total | Yes | The total number of bytes transmitted via this connection. |
| packets_down | Yes | The total number of packets downloaded via this connection. |
| packets_up | Yes | The total number of packets uploaded via this connection. |
| packets_total | Yes | The total number of packets transmitted via this connection. |
| protocol | Yes | The communication protocol associated with this connection (e.g. tcp, udp). |
Get sample dns lookups
curl "https://api.emergingthreats.net/v1/samples/{md5}/dns"
-H "Authorization: SECRETKEY"
from urllib2 import Request, urlopen
request = Request("https://api.emergingthreats.net/v1/samples/{md5}/dns")
request.add_header("Authorization", "SECRETKEY")
result = urlopen(request)
print result.read()
The JSON response should look something like:
{
"success": true,
"response": [
{
"source": "177f3c8a2623d4efb41b0020d680be83",
"date": "2014-04-02",
"domain": "partirenimmobilier.fr",
"address": "10.10.10.1",
"record_type": "A"
},
{
"source": "177f3c8a2623d4efb41b0020d680be83",
"date": "2014-04-02",
"domain": "www.fredianipueyrredon.com.ar",
"address": "10.10.10.1",
"record_type": "A"
}
]
}
This endpoint retrieves the most recent dns lookups an individual malware sample was observed to have made.
HTTP Request
GET https://api.emergingthreats.net/v1/samples/{md5}/dns
Response Parameters
| Parameter | Optional? | Description |
|---|---|---|
| source | No | The source of the dns lookup. |
| date | No | The date the lookup was observed. |
| domain | No | The domain whose DNS record was being queried. |
| answer | Yes | If the DNS response was not an A record pointing to an IP, this field will contain the DNS query response (e.g. the CNAME). |
| address | Yes | If the DNS response was an A record pointing to an IP, this field will contain the IP in question. |
| record_type | Yes | The DNS record type (e.g. A, CNAME, etc.) |
Get sample http requests
curl "https://api.emergingthreats.net/v1/samples/{md5}/http"
-H "Authorization: SECRETKEY"
from urllib2 import Request, urlopen
request = Request("https://api.emergingthreats.net/v1/samples/{md5}/http")
request.add_header("Authorization", "SECRETKEY")
result = urlopen(request)
print result.read()
The JSON response should look something like:
{
"success": true,
"response": [
{
"source": "177f3c8a2623d4efb41b0020d680be83",
"date": "2014-04-02",
"domain": "vicaire.fr",
"source_ip": "10.10.10.102",
"destination_ip": "10.10.10.1",
"source_port": 49367,
"destination_port": 80,
"method": "GET",
"url": "/images/1/filenames.php",
"user_agent": "Mozilla/4.0 (compatible; MSIE 7.0; Windows NT 6.1; Trident/4.0; SLCC2; .NET CLR 2.0.50727; .NET CLR 3.5.30729; .NET CLR 3.0.30729; Media Center PC 6.0; .NET4.0C; .NET4.0E)"
},
{
"source": "177f3c8a2623d4efb41b0020d680be83",
"date": "2014-04-02",
"domain": "www.danielalmeida.adv.br",
"source_ip": "10.10.10.102",
"destination_ip": "10.10.10.1",
"source_port": 49351,
"destination_port": 80,
"method": "GET",
"url": "/images/1/filenames.php",
"user_agent": "Mozilla/4.0 (compatible; MSIE 7.0; Windows NT 6.1; Trident/4.0; SLCC2; .NET CLR 2.0.50727; .NET CLR 3.5.30729; .NET CLR 3.0.30729; Media Center PC 6.0; .NET4.0C; .NET4.0E)"
}
]
}
This endpoint retrieves the most recent http requests an individual malware sample was observed to have made.
HTTP Request
GET https://api.emergingthreats.net/v1/samples/{md5}/http
Response Parameters
| Parameter | Optional? | Description |
|---|---|---|
| source | No | The source of the http request. |
| date | No | The date the request was observed. |
| domain | No | The domain the request was destined for. |
| source_ip | No | The source IP of the http request. |
| destination_ip | No | The IP the request was destined for. |
| source_port | Yes | The source port of the traffic associated with the request. |
| destination_port | Yes | The port the request was destined for. |
| method | Yes | The HTTP method used in the request. |
| url | Yes | The URL requested. |
| user_agent | Yes | The user agent string associated with the request. |
Get sample IDS events
curl "https://api.emergingthreats.net/v1/samples/{md5}/events"
-H "Authorization: SECRETKEY"
from urllib2 import Request, urlopen
request = Request("https://api.emergingthreats.net/v1/samples/{md5}/events")
request.add_header("Authorization", "SECRETKEY")
result = urlopen(request)
print result.read()
The JSON response should look something like:
{
"success": true,
"response": [
{
"source": "177f3c8a2623d4efb41b0020d680be83",
"date": "2014-04-02",
"sid": 2010228,
"source_ip": "10.10.10.102",
"destination_ip": "10.10.10.1",
"source_port": 49191,
"destination_port": 80,
"revision": "7",
"signature_name": "ET POLICY Suspicious Microsoft Windows NT 6.1 User-Agent Detected"
},
{
"source": "177f3c8a2623d4efb41b0020d680be83",
"date": "2014-03-31",
"sid": 2001117,
"source_ip": "10.10.10.1",
"destination_ip": "10.10.10.104",
"source_port": 53,
"destination_port": 51394,
"revision": "6",
"signature_name": "ET DNS Standard query response, Name Error"
}
]
}
This endpoint retrieves the most recent IDS events an individual malware sample was observed to have triggered.
HTTP Request
GET https://api.emergingthreats.net/v1/samples/{md5}/events
Response Parameters
| Parameter | Optional? | Description |
|---|---|---|
| source | No | The source of the event. |
| date | No | The date the event was observed. |
| sid | No | The SID associated with the event. |
| source_ip | No | The source IP of the traffic associated with the event. |
| destination_ip | No | The destination IP of the traffic associated with the event. |
| source_port | No | The source port of the traffic associated with the event. |
| destination_port | No | The destination port of the traffic associated with the event. |
| revision | Yes | The rule revision of the SID in question. |
| signature_name | Yes | The name of the signature associated with this SID. |
Signature Information
Get Signature name
curl "https://api.emergingthreats.net/v1/sids/{sid}"
-H "Authorization: SECRETKEY"
from urllib2 import Request, urlopen
request = Request("https://api.emergingthreats.net/v1/sids/{sid}")
request.add_header("Authorization", "SECRETKEY")
result = urlopen(request)
print result.read()
The JSON response should look something like:
{
"success": true,
"response": {
"sid": 2007771,
"sig_name": "ET TROJAN Pushdo Update URL Detected"
}
}
HTTP Request
GET https://api.emergingthreats.net/v1/sids/{sid}
Response Parameters
| Parameter | Optional? | Description |
|---|---|---|
| sid | no | Signature id that reflects request |
| sig_name | no | Name of the signature requested |
This endpoint retrieves the signature name for a particular Signature (SID).
Get related IP addresses
curl "https://api.emergingthreats.net/v1/sids/{sid}/ips"
-H "Authorization: SECRETKEY"
from urllib2 import Request, urlopen
request = Request("https://api.emergingthreats.net/v1/sids/{sid}/ips")
request.add_header("Authorization", "SECRETKEY")
result = urlopen(request)
print result.read()
Request Parameters
| Parameter | Optional? | Description |
|---|---|---|
| sortBy | Yes | Valid values: "ip" and "last_seen", controls the field results are ordered by. Default is "last_seen" if no value or invalid value provided |
| sortDirection | Yes | Valid values of "ASC" and "DESC", descending is the default if no value provided, or invalid value |
The JSON response should look something like:
{
"success": true,
"response": [
{
"long_ip": 16909060,
"ip": "1.2.3.4",
"first_seen": "2012-04-01",
"last_seen": "2014-02-05"
},
{
"long_ip": 16909061,
"ip": "1.2.3.5",
"first_seen": "2013-12-22",
"last_seen": "2014-08-17"
}
]
}
HTTP Request
GET https://api.emergingthreats.net/v1/sids/{sid}/ips
Response Parameters
| Parameter | Optional? | Description |
|---|---|---|
| long_ip | no | Long number representation of an IP address |
| ip | no | Dotted notation representation of an IP address |
| first_seen | no | Date the IP was first observed for this SID |
| last_seen | no | Date the IP was last observed for this SID |
This endpoint retrieves the IPs related to a particular Signature (SID).
Get domain SID
curl "https://api.emergingthreats.net/v1/sids/{sid}/domains"
-H "Authorization: SECRETKEY"
from urllib2 import Request, urlopen
request = Request("https://api.emergingthreats.net/v1/sids/{sid}/domains")
request.add_header("Authorization", "SECRETKEY")
result = urlopen(request)
print result.read()
The JSON response should look something like:
{
"success": true,
"response": [
{
"domain": "wr.example.com",
"first_seen": "2012-04-01",
"last_seen": "2014-02-05"
},
{
"domain": "cc.example.com",
"first_seen": "2013-12-22",
"last_seen": "2014-08-17"
}
]
}
This endpoint retrieves the Domains related to a particular Signature (SID).
HTTP Request
GET https://api.emergingthreats.net/v1/sids/{sid}/domains
Response Parameters
| Parameter | Optional? | Description |
|---|---|---|
| domain | no | Domain name |
| first_seen | no | Date the IP was first observed for this SID |
| last_seen | no | Date the IP was last observed for this SID |
Get sid related malware samples
curl "https://api.emergingthreats.net/v1/sids/{sid}/samples"
-H "Authorization: SECRETKEY"
from urllib2 import Request, urlopen
request = Request("https://api.emergingthreats.net/v1/sids/{sid}/samples")
request.add_header("Authorization", "SECRETKEY")
result = urlopen(request)
print result.read()
The JSON response should look something like:
{
"success": true,
"response": [
{
"source": "45999bfea907bf37acbab63d5d9ea683",
"first_seen": "2014-02-13",
"last_seen": "2014-02-13"
},
{
"source": "f75da3cd3a38aadebdcf86eb53c6eb1c",
"first_seen": "2014-02-13",
"last_seen": "2014-02-13"
}
]
}
This endpoint retrieves the most recent malware samples that communicated with the specified sid.
HTTP Request
GET https://api.emergingthreats.net/v1/sids/{sid}/samples
Response Parameters
| Parameter | Optional? | Description |
|---|---|---|
| source | No | The md5sum of the malware sample. |
| first_seen | No | The date the malware sample was first seen associated to the SID. |
| last_seen | No | The date the malware sample was last seen associated to the SID. |
Get Signature Text
curl "https://api.emergingthreats.net/v1/sids/{sid}/text"
-H "Authorization: SECRETKEY"
from urllib2 import Request, urlopen
request = Request("https://api.emergingthreats.net/v1/sids/{sid}/text")
request.add_header("Authorization", "SECRETKEY")
result = urlopen(request)
print result.read()
The JSON response should look something like:
{
"success":true,
"response":
{
"sid":2000005,
"suricata_text":"alert tcp $EXTERNAL_NET any -> $HOME_NET 23 (msg:\"ET EXPLOIT Cisco Telnet Buffer Overflow\"; flow: to_server,established; content:\"|3f 3f 3f 3f 3f 3f 3f 3f 3f 3f 3f 3f 3f 3f 3f 3f 3f 61 7e 20 25 25 25 25 25 58 58|\"; threshold: type limit, track by_src, count 1, seconds 120; reference:url,www.cisco.com/warp/public/707/cisco-sn-20040326-exploits.shtml; reference:url,doc.emergingthreats.net/bin/view/Main/2000005; classtype:attempted-dos; sid:2000005; rev:7;)",
"snort_text":"alert tcp $EXTERNAL_NET any -> $HOME_NET 23 (msg:\"ET EXPLOIT Cisco Telnet Buffer Overflow\"; flow: to_server,established; content:\"|3f 3f 3f 3f 3f 3f 3f 3f 3f 3f 3f 3f 3f 3f 3f 3f 3f 61 7e 20 25 25 25 25 25 58 58|\"; detection_filter: track by_src, count 1, seconds 120; reference:url,www.cisco.com/warp/public/707/cisco-sn-20040326-exploits.shtml; reference:url,doc.emergingthreats.net/bin/view/Main/2000005; classtype:attempted-dos; sid:2000005; rev:8;)"
}
}
This endpoint retrieves the most recent documentation available for the specified sid. If you do not have access to the rule requested (i.e. the rule is for ETPro and you do not have an ETPro subscription, this will return a 403 Forbidden.
HTTP Request
GET https://api.emergingthreats.net/v1/sids/{sid}/text
Response Parameters
| Parameter | Optional? | Description |
|---|---|---|
| sid | No | Sid that was requested |
| suricata_text | Yes | Example of the rule for Suricata |
| snort_text | Yes | Example of rule for Snort 2.9 |
Get Signature documentation
curl "https://api.emergingthreats.net/v1/sids/{sid}/documentation"
-H "Authorization: SECRETKEY"
from urllib2 import Request, urlopen
request = Request("https://api.emergingthreats.net/v1/sids/{sid}/documentation")
request.add_header("Authorization", "SECRETKEY")
result = urlopen(request)
print result.read()
The JSON response should look something like:
{
"success": true,
"response":
{
"sid": 2000005,
"summary": "This alert is triggered when an attempt is made to exploit a vulnerability in a system or application.",
"description": "An EXPLOIT Attempt event likely occurs when an attacker has attempted to gain
unauthorized access to an asset or service by exploiting a direct vulnerability in an application or
operating system. A successful exploitation of an asset or service may lead to malicious code being left
behind to facilitate remote control. Further investigation may be needed to ascertain if an attacker successfully exploited this asset or service.",
"impact": "Compromised Server"
}
}
This endpoint retrieves the most recent documentation available for the specified sid.
HTTP Request
GET https://api.emergingthreats.net/v1/sids/{sid}/documentation
Response Parameters
| Parameter | Optional? | Description |
|---|---|---|
| sid | No | Sid that was requested |
| summary | No | Summary of the information this alert is trying to convey. |
| description | No | Detailed description of the exploit being caught. |
| impact | No | What kinds of systems does this impact |
Get Signature references
curl "https://api.emergingthreats.net/v1/sids/{sid}/references"
-H "Authorization: SECRETKEY"
from urllib2 import Request, urlopen
request = Request("https://api.emergingthreats.net/v1/sids/{sid}/references")
request.add_header("Authorization", "SECRETKEY")
result = urlopen(request)
print result.read()
The JSON response should look something like:
{
"success":true,
"response":
[
{
"reference_type":"url",
"reference_description":"HTTP URL",
"reference_urls":
[
"http://doc.emergingthreats.net/bin/view/Main/2000005",
"http://www.cisco.com/warp/public/707/cisco-sn-20040326-exploits.shtml"
]
}
]
}
This endpoint retrieves lookup references for this SID.
HTTP Request
GET https://api.emergingthreats.net/v1/sids/{sid}/references
Response Parameters
| Parameter | Optional? | Description |
|---|---|---|
| reference_type | No | The type of reference this refers to, as a key |
| reference_description | No | Plain text description of the reference type |
| reference_urls | No | List of urls to references |
Errors
The ET Intelligence API uses the following error codes:
| Error Code | Meaning |
|---|---|
| 401 | Unauthorized -- You did not provide an API key. |
| 403 | Forbidden -- The API key does not have access to the requested action or your subscription has elapsed. |
| 404 | Not Found -- The requested action does not exist. |
| 408 | Request Timeout -- The request took too long to complete on our side. Please reduce the amount of information you are requesting, or try again later. |
| 429 | Rate Limit Exceeded -- You have exceeded your provisioned rate limit. If this becomes a regular occurrence, please contact sales to have your rate limit increased. |
| 500 | Internal Server Error -- We had a problem internal to our systems. Please try again later. |