Timeline and Classifiers

The timeline and classifiers endpoints are similar, but provide different pieces of information about the same resource. The timeline shows when a domain was given attribution, whereas the classifiers shows when a domain was first queried and what it is now classified as.

Timeline

The timeline endpoint shows when a domain, IP or URL was given attribution of a particular security categorization or threat type (indicators of compromise). It also shows when the attribution changed, whether that’s an added attribution, a subtracted attribution, or an attribution that's been re-added later. This can be used to determine if a domain, IP or URL that's been blocked is a newly discovered threat or has been blocked for a long period of time.

Often domains, IP or URLs are flagged as malicious in our research, but the site owner takes time to patch the server from any exploits or malware being hosted. The categorization is updated on our end, and the /timeline/ endpoint reflects the change.

The timeline endpoint is ordered in descending order from the newest status change to the oldest.

Note: While we have made a best effort approach to reconstruct the past timeline of events, categorization information for indicators of compromise prior to August 2017 may be inaccurate.

If there is no information about the domain, a blank array is returned.

Sample query:

curl -H "Authorization: Bearer %YourToken%" "https://investigate.api.umbrella.com/timeline/{name}"

Parameter for Input

Field
Type
String

name

string

Domain Name, IP address or URL

Returned Value for Output if Success 200

Field
Type
Description

categories

array of strings

which Umbrella security category, if any, matched the input

attacks

array of strings

which named attacks, if any, matched the input

threatTypes

array of strings

which threat type, if any, matched in the input.

timestamp

integer

the time when the attribution for this domain or URL changed. This is given in epoch (unix) time stamps.

GET https://investigate.api.umbrella.com/timeline/{domain.com}
REQUEST
curl --include \
     --header "Authorization: Bearer %YourToken%" \
https://investigate.api.umbrella.com/timeline/{domain.com}
    
RESPONSE (HTTP 200, Content-Type: application/json)
[
  {
    categories: [
      "Malware"
    ],
    attacks: [ ],
    threatTypes: [ ],
    timestamp: 1450665168956
  }
]

    

In this example, the original domain was detected as Malware and Exploit Kit, but was later changed to be clean.

GET https://investigate.api.umbrella.com/timeline/{domain.com}
REQUEST
curl --include \
     --header "Authorization: Bearer %YourToken%" \
https://investigate.api.umbrella.com/timeline/{domain.com}
    
RESPONSE (HTTP 200, Content-Type: application/json)
[
  {
    categories: [ ],
    attacks: [ ],
    threatTypes: [ ],
    timestamp: 1501697925911
  },
  {
    categories: [
      "Malware"
    ],
    attacks: [ ],
    threatTypes: [
      "Exploit Kit"
    ],
    timestamp: 1488397543490
  }
]
    

Sample query for encoded URL is below. Note that all URLs must be percent-encoded.

curl -H "Authorization: Bearer %YourToken%"
https://investigate.api.opendns.com/timeline/http%3A%2F%2Fdomain.org%2Findex.html

Classifiers

The classifiers endpoint returns the first queried time for a particular domain. This endpoint only applies to new domains, which is defined as domains first queried some time after we started tracking it's availability.

Anything other than a new domain will return a "null". It will also return null for non-domains (IPs or URLs) because we're not tracking first queried time for individual URLs. Since IPs are not queried at all, we do not record a queried time for them.

There is also an additional endpoint: /info. This is intended to be an all-purpose endpoint that we can add additional info to in the future, hence the name. Currently, /info/ shows the first queried date.

Note: While we have made a best effort approach to reconstruct the past timeline of events, categorization information for indicators of compromise prior to August 2017 may be inaccurate.

Sample query for classifiers:

curl -H "Authorization: Bearer %YourToken%" "https://investigate.api.umbrella.com/url/cosmos.furnipict.com/classifiers"

Sample query for classifiers info:

curl -H "Authorization: Bearer %YourToken%" "https://investigate.api.umbrella.com/url/cosmos.furnipict.com/info"

Parameter for Input

Field
Type
Description

url

string

domain name

Returned Value for Output if Success 200

For /classifiers/:

Field
Type
Description

securityCategories

array of strings

which Umbrella security category, if any, matched the input

attacks

array of strings

which named attacks, if any, match with the domain in the input

threatTypes

array of strings

which threat type, if any, matched with the domain in the input.

For /info/:

Field
Type
Description

firstQueried

integer

first time that Umbrella saw this domain being queried, in epoch time.

GET https://investigate.api.umbrella.com/url/{domains}/classifiers
REQUEST
curl --include \
     --header "Authorization: Bearer %YourToken%" \
https://investigate.api.umbrella.com/url/{domains}/classifiers
    
RESPONSE (HTTP 200, Content-Type: application/json)
[
  {
    categories: [
      "Malware"
      "Dynamic DNS"
    ],
    attacks: [
    "Neutrino
    ],
    threatTypes: [
    "Exploit Kit"
    ],
  }
]

    
GET https://investigate.api.umbrella.com/url/{domain.com}/info
REQUEST
curl --include \
     --header "Authorization: Bearer %YourToken%" \
https://investigate.api.umbrella.com/url/{domain.com}/info
    
RESPONSE (HTTP 200, Content-Type: application/json)
[
  {
		firstQueried: 1479496560000
    }
]

    

Domain Status and Categorization < Timeline and Classifiers > Domain Volume

Timeline and Classifiers