{"_id":"598b4bdd42d567000fae7559","project":"5615790c0f5ed00d00483dd1","version":{"_id":"5615790d0f5ed00d00483dd4","__v":6,"project":"5615790c0f5ed00d00483dd1","createdAt":"2015-10-07T19:57:01.307Z","releaseDate":"2015-10-07T19:57:01.307Z","categories":["5615790d0f5ed00d00483dd5","56157b2af432910d0000f9fe","56157cfb0f5ed00d00483ddb","562684d95db46b1700fd4f48","573b7ea9ef164e2900a2b8ff","582e285d8373c20f00810608"],"is_deprecated":false,"is_hidden":false,"is_beta":false,"is_stable":true,"codename":"","version_clean":"1.0.0","version":"1.0"},"category":{"_id":"5615790d0f5ed00d00483dd5","__v":19,"pages":["5615790e0f5ed00d00483dd7","561d48e46386060d00e06003","561d48fe31d9630d001eb5bd","561d49b657165b0d00aa5d8b","561d4a879463520d00cd11e2","561d67f48ca8b90d00210234","561d6a0bf0cff80d00ca22c3","561d6c5b071cd60d000d3221","562f9c2543c5570d001fe6bd","56311c99eae7ef0d00270e3d","56311d6702aff217007dba23","56311f96f1c0580d00fac719","563120b7242cda1900198b79","5631229bf1c0580d00fac721","563131559ead230d00a188f6","563134a324014b0d00bd9a4f","5631392082d96a0d00b0fb1d","56313c584b36120d00fdebfb","5642658ef424a10d00118360"],"project":"5615790c0f5ed00d00483dd1","version":"5615790d0f5ed00d00483dd4","sync":{"url":"","isSync":false},"reference":false,"createdAt":"2015-10-07T19:57:01.871Z","from_sync":false,"order":0,"slug":"opendns-investigate-rest-api","title":"Umbrella Investigate REST API"},"user":"560b40145148ba0d009bd0b5","__v":0,"parentDoc":null,"updates":[],"next":{"pages":[],"description":""},"createdAt":"2017-08-09T17:52:29.496Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"results":{"codes":[]},"settings":"","auth":"required","params":[],"url":""},"isReference":false,"order":6,"body":"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.\n\n##Timeline \n\nThe 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, or added again.  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. \n\nOften 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.\n\nThe timeline endpoint is ordered in descending order from the newest status change to the oldest.\n\n**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._\n\nIf there is no information about the domain, a blank array is returned.  \n\nSample query:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"curl -H \\\"Authorization: Bearer %YourToken%\\\" \\\"https://investigate.api.umbrella.com/timeline/{name}\\\"\",\n      \"language\": \"text\"\n    }\n  ]\n}\n[/block]\n### Parameter for input ###\n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"Field\",\n    \"h-1\": \"Type\",\n    \"h-2\": \"String\",\n    \"0-0\": \"name\",\n    \"0-1\": \"string\",\n    \"0-2\": \"Domain Name, IP address or URL\"\n  },\n  \"cols\": 3,\n  \"rows\": 1\n}\n[/block]\n### Returned value for output if Success 200 ###\n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"Field\",\n    \"h-1\": \"Type\",\n    \"h-2\": \"Description\",\n    \"0-0\": \"categories\",\n    \"1-0\": \"attacks\",\n    \"2-0\": \"threatTypes\",\n    \"3-0\": \"timestamp\",\n    \"0-1\": \"array of strings\",\n    \"0-2\": \"which Umbrella security category, if any, matched the input\",\n    \"1-1\": \"array of strings\",\n    \"2-1\": \"array of strings\",\n    \"2-2\": \"which threat type, if any, matched in the input.\",\n    \"3-1\": \"integer\",\n    \"3-2\": \"the time when the attribution for  this domain or URL changed.  This is given in epoch (unix) time stamps.\",\n    \"1-2\": \"which named attacks, if any, matched the input\"\n  },\n  \"cols\": 3,\n  \"rows\": 4\n}\n[/block]\n\n[block:html]\n{\n  \"html\": \"<div class=\\\"api-code-block\\\">\\n  <div class=\\\"api-code-block__header\\\">\\n    <span class=\\\"api-code-block__header__label\\\">GET</span> https://investigate.api.umbrella.com/timeline/{domain.com}\\n  </div>\\n  <div class=\\\"api-code-block__section\\\">\\n    <div class=\\\"api-code-block__section__header\\\">REQUEST</div>\\n    <pre>curl --include \\\\\\n     --header \\\"Authorization: Bearer %YourToken%\\\" \\\\\\nhttps://investigate.api.umbrella.com/timeline/{domain.com}\\n    </pre>\\n  </div>\\n  <div class=\\\"api-code-block__section\\\">\\n    <div class=\\\"api-code-block__section__header\\\">RESPONSE <em>(HTTP 200, Content-Type: application/json)</em>\\n    </div>\\n    <pre>\\n[\\n  {\\n    categories: [\\n      \\\"Malware\\\"\\n    ],\\n    attacks: [ ],\\n    threatTypes: [ ],\\n    timestamp: 1450665168956\\n  }\\n]\\n\\n    </pre>\\n  </div>\\n</div>\"\n}\n[/block]\nIn this example, the original domain was detected as Malware and Exploit Kit, but was later changed to be clean:\n[block:html]\n{\n  \"html\": \"<div class=\\\"api-code-block\\\">\\n  <div class=\\\"api-code-block__header\\\">\\n    <span class=\\\"api-code-block__header__label\\\">GET</span> https://investigate.api.umbrella.com/timeline/{domain.com}\\n  </div>\\n  <div class=\\\"api-code-block__section\\\">\\n    <div class=\\\"api-code-block__section__header\\\">REQUEST</div>\\n    <pre>curl --include \\\\\\n     --header \\\"Authorization: Bearer %YourToken%\\\" \\\\\\nhttps://investigate.api.umbrella.com/timeline/{domain.com}\\n    </pre>\\n  </div>\\n  <div class=\\\"api-code-block__section\\\">\\n    <div class=\\\"api-code-block__section__header\\\">RESPONSE <em>(HTTP 200, Content-Type: application/json)</em>\\n    </div>\\n    <pre>\\n[\\n  {\\n    categories: [ ],\\n    attacks: [ ],\\n    threatTypes: [ ],\\n    timestamp: 1501697925911\\n  },\\n  {\\n    categories: [\\n      \\\"Malware\\\"\\n    ],\\n    attacks: [ ],\\n    threatTypes: [\\n      \\\"Exploit Kit\\\"\\n    ],\\n    timestamp: 1488397543490\\n  }\\n]\\n    </pre>\\n  </div>\"\n}\n[/block]\nSample query for encoded URL is below.  Note that all URLs must be [percent-encoded](https://en.wikipedia.org/wiki/Percent-encoding):\n\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"curl -H \\\"Authorization: Bearer %YourToken%\\\"\\nhttps://investigate.api.opendns.com/timeline/http%3A%2F%2Fdomain.org%2Findex.html\",\n      \"language\": \"text\"\n    }\n  ]\n}\n[/block]\n## Classifiers\n\nThe 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. \n\nAnything 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. \n\nThere 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.\n\n**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._\n\nSample query for classifiers:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"curl -H \\\"Authorization: Bearer %YourToken%\\\" \\\"https://investigate.api.umbrella.com/url/cosmos.furnipict.com/classifiers\\\"\",\n      \"language\": \"text\"\n    }\n  ]\n}\n[/block]\nSample query for classifiers info:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"curl -H \\\"Authorization: Bearer %YourToken%\\\" \\\"https://investigate.api.umbrella.com/url/cosmos.furnipict.com/info\\\"\",\n      \"language\": \"text\"\n    }\n  ]\n}\n[/block]\n### Parameter for input ###\n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"Field\",\n    \"h-1\": \"Type\",\n    \"h-2\": \"Description\",\n    \"0-0\": \"url\",\n    \"0-1\": \"string\",\n    \"0-2\": \"domain name\"\n  },\n  \"cols\": 3,\n  \"rows\": 1\n}\n[/block]\n### Returned value for output if Success 200 ###\n\nFor /classifiers/:\n\n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"Field\",\n    \"h-1\": \"Type\",\n    \"h-2\": \"Description\",\n    \"0-0\": \"securityCategories\",\n    \"2-0\": \"threatTypes\",\n    \"1-0\": \"attacks\",\n    \"0-1\": \"array of strings\",\n    \"1-1\": \"array of strings\",\n    \"2-1\": \"array of strings\",\n    \"0-2\": \"which Umbrella security category, if any, matched the input\",\n    \"1-2\": \"which named attacks, if any, match with the domain in the input\",\n    \"2-2\": \"which threat type, if any,  matched with the domain in the input.\"\n  },\n  \"cols\": 3,\n  \"rows\": 3\n}\n[/block]\nFor /info/:\n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"Field\",\n    \"h-1\": \"Type\",\n    \"h-2\": \"Description\",\n    \"0-0\": \"firstQueried\",\n    \"0-1\": \"integer\",\n    \"0-2\": \"first time that Umbrella saw this domain being queried, in epoch time.\"\n  },\n  \"cols\": 3,\n  \"rows\": 1\n}\n[/block]\n\n[block:html]\n{\n  \"html\": \"<div class=\\\"api-code-block\\\">\\n  <div class=\\\"api-code-block__header\\\">\\n    <span class=\\\"api-code-block__header__label\\\">GET</span> https://investigate.api.umbrella.com/url/{domains}/classifiers\\n  </div>\\n  <div class=\\\"api-code-block__section\\\">\\n    <div class=\\\"api-code-block__section__header\\\">REQUEST</div>\\n    <pre>curl --include \\\\\\n     --header \\\"Authorization: Bearer %YourToken%\\\" \\\\\\nhttps://investigate.api.umbrella.com/url/{domains}/classifiers\\n    </pre>\\n  </div>\\n  <div class=\\\"api-code-block__section\\\">\\n    <div class=\\\"api-code-block__section__header\\\">RESPONSE <em>(HTTP 200, Content-Type: application/json)</em>\\n    </div>\\n    <pre>\\n[\\n  {\\n    categories: [\\n      \\\"Malware\\\"\\n      \\\"Dynamic DNS\\\"\\n    ],\\n    attacks: [\\n    \\\"Neutrino\\n    ],\\n    threatTypes: [\\n    \\\"Exploit Kit\\\"\\n    ],\\n  }\\n]\\n\\n    </pre>\\n  </div>\\n</div>\"\n}\n[/block]\n\n[block:html]\n{\n  \"html\": \"<div class=\\\"api-code-block\\\">\\n  <div class=\\\"api-code-block__header\\\">\\n    <span class=\\\"api-code-block__header__label\\\">GET</span> https://investigate.api.umbrella.com/url/{domain.com}/info\\n  </div>\\n  <div class=\\\"api-code-block__section\\\">\\n    <div class=\\\"api-code-block__section__header\\\">REQUEST</div>\\n    <pre>curl --include \\\\\\n     --header \\\"Authorization: Bearer %YourToken%\\\" \\\\\\nhttps://investigate.api.umbrella.com/url/{domain.com}/info\\n    </pre>\\n  </div>\\n  <div class=\\\"api-code-block__section\\\">\\n    <div class=\\\"api-code-block__section__header\\\">RESPONSE <em>(HTTP 200, Content-Type: application/json)</em>\\n    </div>\\n    <pre>\\n[\\n  {\\n\\t\\tfirstQueried: 1479496560000\\n    }\\n]\\n\\n    </pre>\\n  </div>\\n</div>\"\n}\n[/block]","excerpt":"","slug":"timeline","type":"basic","title":"Timeline and Classifiers"}

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, or added again. 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: [block:code] { "codes": [ { "code": "curl -H \"Authorization: Bearer %YourToken%\" \"https://investigate.api.umbrella.com/timeline/{name}\"", "language": "text" } ] } [/block] ### Parameter for input ### [block:parameters] { "data": { "h-0": "Field", "h-1": "Type", "h-2": "String", "0-0": "name", "0-1": "string", "0-2": "Domain Name, IP address or URL" }, "cols": 3, "rows": 1 } [/block] ### Returned value for output if Success 200 ### [block:parameters] { "data": { "h-0": "Field", "h-1": "Type", "h-2": "Description", "0-0": "categories", "1-0": "attacks", "2-0": "threatTypes", "3-0": "timestamp", "0-1": "array of strings", "0-2": "which Umbrella security category, if any, matched the input", "1-1": "array of strings", "2-1": "array of strings", "2-2": "which threat type, if any, matched in the input.", "3-1": "integer", "3-2": "the time when the attribution for this domain or URL changed. This is given in epoch (unix) time stamps.", "1-2": "which named attacks, if any, matched the input" }, "cols": 3, "rows": 4 } [/block] [block:html] { "html": "<div class=\"api-code-block\">\n <div class=\"api-code-block__header\">\n <span class=\"api-code-block__header__label\">GET</span> https://investigate.api.umbrella.com/timeline/{domain.com}\n </div>\n <div class=\"api-code-block__section\">\n <div class=\"api-code-block__section__header\">REQUEST</div>\n <pre>curl --include \\\n --header \"Authorization: Bearer %YourToken%\" \\\nhttps://investigate.api.umbrella.com/timeline/{domain.com}\n </pre>\n </div>\n <div class=\"api-code-block__section\">\n <div class=\"api-code-block__section__header\">RESPONSE <em>(HTTP 200, Content-Type: application/json)</em>\n </div>\n <pre>\n[\n {\n categories: [\n \"Malware\"\n ],\n attacks: [ ],\n threatTypes: [ ],\n timestamp: 1450665168956\n }\n]\n\n </pre>\n </div>\n</div>" } [/block] In this example, the original domain was detected as Malware and Exploit Kit, but was later changed to be clean: [block:html] { "html": "<div class=\"api-code-block\">\n <div class=\"api-code-block__header\">\n <span class=\"api-code-block__header__label\">GET</span> https://investigate.api.umbrella.com/timeline/{domain.com}\n </div>\n <div class=\"api-code-block__section\">\n <div class=\"api-code-block__section__header\">REQUEST</div>\n <pre>curl --include \\\n --header \"Authorization: Bearer %YourToken%\" \\\nhttps://investigate.api.umbrella.com/timeline/{domain.com}\n </pre>\n </div>\n <div class=\"api-code-block__section\">\n <div class=\"api-code-block__section__header\">RESPONSE <em>(HTTP 200, Content-Type: application/json)</em>\n </div>\n <pre>\n[\n {\n categories: [ ],\n attacks: [ ],\n threatTypes: [ ],\n timestamp: 1501697925911\n },\n {\n categories: [\n \"Malware\"\n ],\n attacks: [ ],\n threatTypes: [\n \"Exploit Kit\"\n ],\n timestamp: 1488397543490\n }\n]\n </pre>\n </div>" } [/block] Sample query for encoded URL is below. Note that all URLs must be [percent-encoded](https://en.wikipedia.org/wiki/Percent-encoding): [block:code] { "codes": [ { "code": "curl -H \"Authorization: Bearer %YourToken%\"\nhttps://investigate.api.opendns.com/timeline/http%3A%2F%2Fdomain.org%2Findex.html", "language": "text" } ] } [/block] ## 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: [block:code] { "codes": [ { "code": "curl -H \"Authorization: Bearer %YourToken%\" \"https://investigate.api.umbrella.com/url/cosmos.furnipict.com/classifiers\"", "language": "text" } ] } [/block] Sample query for classifiers info: [block:code] { "codes": [ { "code": "curl -H \"Authorization: Bearer %YourToken%\" \"https://investigate.api.umbrella.com/url/cosmos.furnipict.com/info\"", "language": "text" } ] } [/block] ### Parameter for input ### [block:parameters] { "data": { "h-0": "Field", "h-1": "Type", "h-2": "Description", "0-0": "url", "0-1": "string", "0-2": "domain name" }, "cols": 3, "rows": 1 } [/block] ### Returned value for output if Success 200 ### For /classifiers/: [block:parameters] { "data": { "h-0": "Field", "h-1": "Type", "h-2": "Description", "0-0": "securityCategories", "2-0": "threatTypes", "1-0": "attacks", "0-1": "array of strings", "1-1": "array of strings", "2-1": "array of strings", "0-2": "which Umbrella security category, if any, matched the input", "1-2": "which named attacks, if any, match with the domain in the input", "2-2": "which threat type, if any, matched with the domain in the input." }, "cols": 3, "rows": 3 } [/block] For /info/: [block:parameters] { "data": { "h-0": "Field", "h-1": "Type", "h-2": "Description", "0-0": "firstQueried", "0-1": "integer", "0-2": "first time that Umbrella saw this domain being queried, in epoch time." }, "cols": 3, "rows": 1 } [/block] [block:html] { "html": "<div class=\"api-code-block\">\n <div class=\"api-code-block__header\">\n <span class=\"api-code-block__header__label\">GET</span> https://investigate.api.umbrella.com/url/{domains}/classifiers\n </div>\n <div class=\"api-code-block__section\">\n <div class=\"api-code-block__section__header\">REQUEST</div>\n <pre>curl --include \\\n --header \"Authorization: Bearer %YourToken%\" \\\nhttps://investigate.api.umbrella.com/url/{domains}/classifiers\n </pre>\n </div>\n <div class=\"api-code-block__section\">\n <div class=\"api-code-block__section__header\">RESPONSE <em>(HTTP 200, Content-Type: application/json)</em>\n </div>\n <pre>\n[\n {\n categories: [\n \"Malware\"\n \"Dynamic DNS\"\n ],\n attacks: [\n \"Neutrino\n ],\n threatTypes: [\n \"Exploit Kit\"\n ],\n }\n]\n\n </pre>\n </div>\n</div>" } [/block] [block:html] { "html": "<div class=\"api-code-block\">\n <div class=\"api-code-block__header\">\n <span class=\"api-code-block__header__label\">GET</span> https://investigate.api.umbrella.com/url/{domain.com}/info\n </div>\n <div class=\"api-code-block__section\">\n <div class=\"api-code-block__section__header\">REQUEST</div>\n <pre>curl --include \\\n --header \"Authorization: Bearer %YourToken%\" \\\nhttps://investigate.api.umbrella.com/url/{domain.com}/info\n </pre>\n </div>\n <div class=\"api-code-block__section\">\n <div class=\"api-code-block__section__header\">RESPONSE <em>(HTTP 200, Content-Type: application/json)</em>\n </div>\n <pre>\n[\n {\n\t\tfirstQueried: 1479496560000\n }\n]\n\n </pre>\n </div>\n</div>" } [/block]