NAV Navbar
Logo
shell Python (2.x)

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 SECRETKEY with 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.
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.
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.
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.
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.
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.
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).

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
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.