Threat Grid Integration (Cisco AMP Threat Grid)

{"_id":"581a1c6a9d2fee0f005a2f5c","project":"5615790c0f5ed00d00483dd1","parentDoc":null,"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"},"__v":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","updates":[],"next":{"pages":[],"description":""},"createdAt":"2016-11-02T17:03:38.635Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"settings":"","results":{"codes":[]},"auth":"required","params":[],"url":""},"isReference":false,"order":19,"body":"The Umbrella Investigate integration with Cisco AMP Threat Grid shows samples from the ThreatGrid database associated with a domain, IP or URL that you’re looking to find out more information about. Information about samples is provided in the form of checksums associated when looking up a specific host or IP.\n\nOnce information about samples has been gathered, there is a second pivot where the Investigate API will look up checksums and reveal additional information about the individual malware samples, including behavior of the sample on the network. The information about what the sample does can then lead back to Investigate to find more clues about the network infrastructure used by the malware you’re researching. Additional research can be done in regard to the severity of the malware samples and the samples’ behaviors when they were analyzed.\n\nThe two primary endpoints for this API are /samples/ and /sample/. /samples/ gives all the sample information about a specific domain, IP, or URL and once that information has been obtained, the /sample/ endpoint can be used to dig into those samples further and reveal the artifacts, connections, and behaviors of those samples. Using information about the connections of the malware samples, you can continue to investigate related domains and IPs.\n\nAn alternate use case is taking a list of checksums from another threat intel source, such as an in-house SIEM or third party data feed, and review those checksums against the /sample/ endpoints to find more information about the threats.\n\n\n### API USAGE AND LIMITATIONS \n\nAll requests to the API endpoints are GET requests and follow the standard authentication scheme for any other Investigate endpoint. For more about authentication, refer to the 'About the API' section of this guide.\n\nIt’s important to understand that some perfectly normal, safe domains, such as www.google.com, will have malicious samples associated with them because the malware uses that domain or IP to check internet connectivity, or even as a source to determine more data about the host on which it resides (such as the public IP of the infected host or network). \n\nNot all data from Threat Grid is in Investigate. Some of the data has not been ported over as it doesn’t apply to the way Investigate should be used for security incidents. Some legacy information has also not been brought over, although if Threat Grid were to see this sample again, it would become part of the data set. \n\n**NOTE:** Portions of the functionality described for this feature of Investigate are only available for customers of both Threat Grid and Investigate. **If you are an existing Thread Grid customer and do not see the details outlined in the areas marked for “Threat Grid Customers Only”, please contact Umbrella Support ([umbrella-support:::at:::cisco.com](mailto:umbrella-support@cisco.com)).**\nIf you would like to add Threat Grid to your existing license, contact your account representative\n\n## Usage\nAll requests to the API endpoints are GET requests and follow the standard authentication scheme for any other Investigate endpoint. \n\nThe two primary endpoints covered in this section are \"samples\" and \"sample\":\n* *The /samples/ API endpoint to research a domain, IP or URL and obtain sample information*\n* *The /sample/ API endpoint to research a sample in depth*\n\nWithin the /sample/ endpoint the following information can be found:\n\n* _Artifacts and pagination of artifacts_\n* _Samples of samples and pagination of sub-samples_ – **_Threat Grid Customers only_**\n* _Connections of a sample and pagination of connections_\n* _Behaviors of a sample_\n\n## Glossary of Terms\n\nThe following terms are used by the API (and the UI) and are defined here, in advance, so it’s clear what data is being represented. A full list of all terms used by Threat Grid can be found here—[or Threat Grid customers only](https://panacea.threatgrid.com/doc/main/threat-grid-glossary.html).\n\n#### Sample\nA sample is a type of file, or even a file-like object, such as a process running in memory submitted and analyzed by Threat Grid. \n\n#### Artifact\nArtifacts are files that are created or modified during a sample analysis. Malware executables often download additional components and infect or modify system files, documents, and running processes. Artifacts are sometimes executables which can also be analyzed in Threat Grid and become a sample.\n\n#### Behavioral indicators (Behaviors)\nKey traits and behaviors that have been identified as indicators of malicious activity. Behavioral indicators include threat severity levels, HTTP Traffic, DNS Traffic, TCP/IP network sessions, processes, artifacts, registry activities, and more.\n\n#### Connections\nA network connection made by this particular sample to an IP or a domain, along with information about whether that IP or domain is known malicious.\n\n### The /samples/ API endpoint to research a domain, IP or URL\nThe /samples/ endpoint gives all samples associated with a specific domain, IP address or URL. This endpoint takes input in the form of a domain, an IP, or a URL using standard formats for each. This endpoint will return all samples associated with the domain; the default maximum number of responses is 10, but can be extended. \n\nTypically an error is seen when the requested host (domain/IP/URL) is not in a valid format, if the requested host is not found in our database, or if there is no data available for the domain or IP you’ve requested. Please check your input to ensure the format is valid\n\n**NOTE:** CIDR subnets (eg: 10.10.10.0/24) are not supported and neither is the pattern search.\n\nSample error:\n[block:code]\n{\n \"codes\": [\n {\n \"code\": \"{\\n \\\"error\\\": \\\"No data available for 'host.com'\\\"\\n}\",\n \"language\": \"text\"\n }\n ]\n}\n[/block]\nThe basic query format is \"https://investigate.api.umbrella.com/samples/[domain/ip/url]\"\n\nSample query for a domain with a limit of 100 results, sorted by the threat score:\n[block:code]\n{\n \"codes\": [\n {\n \"code\": \"https://investigate.api.umbrella.com/samples/google.com?limit=100&sortby=score\\n\",\n \"language\": \"text\"\n }\n ]\n}\n[/block]\nSample query for an IP address with a limit of 15 results, sorted by last seen date:\n[block:code]\n{\n \"codes\": [\n {\n \"code\": \"https://investigate.api.umbrella.com/samples/195.22.28.196?limit=15&sortby=last-seen\",\n \"language\": \"text\"\n }\n ]\n}\n[/block]\n>**IMPORTANT NOTE:** URL queries must be encoded and must include the protocol! The example below outlines a typical example of that.\n\nSample query for a URL with an executable included, with a limit of 10 results:\n[block:code]\n{\n \"codes\": [\n {\n \"code\": \"https://investigate.api.umbrella.com/samples/http%3A%2F%2Fwww.hoarafushionline.net%2Fhabeys.exe?limit=10\",\n \"language\": \"text\"\n }\n ]\n}\n[/block]\n### Parameter for input ###\n[block:parameters]\n{\n \"data\": {\n \"0-0\": \"limit\",\n \"0-1\": \"The number of responses; default of 10 as a limit on response, can be extended.\",\n \"1-1\": \"Default to 0, used to pagination between sets of data if limit is exceeded.\",\n \"1-0\": \"offset\",\n \"2-0\": \"sortby\",\n \"2-1\": \"Default is score. Choose from [“first-seen\\\", \\\"last-seen\\\", \\\"score”]. The syntax is appending “sortby=first-seen” to the end of a requirement. \\\"first-seen\\\" sorts the samples in date descending order from first to last.\\n\\\"last-seen\\\" sorts the samples in ascending order from last to first.\\n\\\"score\\\" sorts the samples by the ThreatScore.\",\n \"h-0\": \"Field\",\n \"h-1\": \"Description\"\n },\n \"cols\": 2,\n \"rows\": 3\n}\n[/block]\n### Returned value for output if Success 200 ###\n\nWe've broken the response down into two sections. All types of query will have the following return values:\n[block:parameters]\n{\n \"data\": {\n \"0-0\": \"query\",\n \"0-1\": \"string\",\n \"1-0\": \"totalresults\",\n \"1-1\": \"integer\",\n \"2-0\": \"moreDataAvailable\",\n \"2-1\": \"boolean\",\n \"3-1\": \"integer\",\n \"0-2\": \"What string was queried or seen by the API.\",\n \"1-2\": \"The number of results returned. Same as limit if limit is reached and moreDataAvailable is true.\",\n \"2-2\": \"If more data is available. Extend the limit and/or offset to view.\",\n \"3-2\": \"Number of sample results.\",\n \"3-0\": \"limit\",\n \"4-0\": \"offset\",\n \"4-1\": \"integer\",\n \"4-2\": \"The offset of the individual entities in the query’s response; used for pagination.\",\n \"h-0\": \"Field\",\n \"h-1\": \"Type\",\n \"h-2\": \"Description\"\n },\n \"cols\": 3,\n \"rows\": 5\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/samples/google.com?limit=100&sortby=score\\\"\\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%\\\" \\\\\\n\\\"https://investigate.api.umbrella.com/samples/google.com?limit=100&sortby=score\\\"\\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 \\\"query\\\": \\\"google.com\\\",\\n \\\"totalResults\\\": 10,\\n \\\"moreDataAvailable\\\": true,\\n \\\"limit\\\": 10,\\n \\\"offset\\\": 0,\\n\\n </pre>\\n </div>\\n</div>\\n<style></style>\"\n}\n[/block]\nIn the second portion of the return from the /samples/ endpoint is information about the actual sample. This return here has been shortened for ease of reading.\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/samples/google.com?limit=100&sortby=score\\\"\\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%\\\" \\\\\\n\\\"https://investigate.api.umbrella.com/samples/google.com?limit=100&sortby=score\\\"\\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\\\"samples\\\": [\\n {\\n \\\"sha256\\\": \\\"e9d3470c37dada28d5a32fb53a243c5b20def35bb01abf8f5403182cc2b91fdd\\\",\\n \\\"sha1\\\": \\\"de182fdcc3c0d473b90a0df0ad14c2074d1e7c50\\\",\\n \\\"md5\\\": \\\"282f80e8a2cf9e0e0dd72093787d99c6\\\",\\n \\\"magicType\\\": \\\"PE32 executable (GUI) Intel 80386, for MS Windows\\\",\\n \\\"threatScore\\\": 100,\\n \\\"size\\\": 192512,\\n \\\"firstSeen\\\": 1460108539000,\\n \\\"lastSeen\\\": 1460108539000,\\n \\\"visible\\\": true,\\n \\\"avresults\\\": [\\n {\\n \\\"signature\\\": \\\"Win.Trojan.Ramnit\\\",\\n \\\"product\\\": \\\"ClamAV\\\"\\n },\\n {\\n \\\"signature\\\": \\\"Win.Trojan.Parite\\\",\\n \\\"product\\\": \\\"ClamAV\\\"\\n }\\n ]\\n },\\n]\\n </pre>\\n </div>\\n</div>\\n<style></style>\"\n}\n[/block]\n\n[block:parameters]\n{\n \"data\": {\n \"0-0\": \"sha256\",\n \"0-2\": \"The SHA256 checksum of the sample. This checksum is important if you’d like to find out more about this sample in the /sample/ endpoint.\",\n \"0-1\": \"hash\",\n \"1-0\": \"sha1\",\n \"1-1\": \"hash\",\n \"1-2\": \"The SHA1 checksum of the sample. As above, can be searched in /sample/ endpoint.\",\n \"2-0\": \"md5\",\n \"2-1\": \"hash\",\n \"2-2\": \"The MD5 checksum of the sample, as above, can be searched in /sample/ endpoint.\",\n \"4-0\": \"threatScore\",\n \"4-1\": \"integer\",\n \"4-2\": \"The score given to a particular sample based on the analysis performed by Threat Grid. A threatScore is a measure of the amount of system weakening, obfuscation, persistence, modification, data exfiltration, and other behaviors which may be a threat to the host system’s integrity. It is intended as an overall threat indicator that can be used as a guide to the likelihood that a submission is malicious. The Threat Score is not an authoritative classification of good and bad software.\",\n \"5-0\": \"size\",\n \"5-2\": \"The size of the sample in bytes.\",\n \"5-1\": \"integer\",\n \"6-0\": \"firstSeen\",\n \"6-1\": \"string\",\n \"6-2\": \"The epoch time stamp for when this sample was first seen by Threat Grid.\",\n \"7-0\": \"lastSeen\",\n \"7-1\": \"string\",\n \"7-2\": \"The epoch time stamp for when this sample was last seen by Threat Grid. The lastSeen and firstSeen will often be the same if the sample is more recent.\",\n \"8-0\": \"visible\",\n \"8-1\": \"boolean\",\n \"8-2\": \"Boolean, either true or false. For internal Umbrella use only, please ignore.\",\n \"9-0\": \"avresults\",\n \"9-2\": \"AntiVirus results according to ClamAV. A sample can have more than one signature if it is possibly detected under more than one family of malware. A sample may also have no signatures associated.\",\n \"9-1\": \"string\",\n \"3-0\": \"magicType\",\n \"3-1\": \"string\",\n \"3-2\": \"A ‘magic type’ is better understood as a file type. Specifically, it is the output of the Linux “file” utility.\",\n \"h-0\": \"Field\",\n \"h-1\": \"Type\",\n \"h-2\": \"Description\"\n },\n \"cols\": 3,\n \"rows\": 10\n}\n[/block]\n### The /sample/ API endpoint to research a sample \n\nOnce you have gathered the information from the /samples/ endpoint, digging deeper requires that you pivot using the checksums of the samples revealed in your initial query. This pivot will reveal large chunks of new data about the malware being researched.\n\nThe /sample/ endpoint returns a variety of data as nested JSON arrays. The initial results array contains the information about the original sample. These results are described first and are, in effect, the samples of the sample.\n\nUnderneath, the following results are nested in JSON outlining additional information:\n\n*Artifacts*\nOther samples associated with this sample, but that are not given a threatScore. *Note that Artifacts are only available for Threat Grid customers.*\n*Connections*\nInformation about network activity associated with this sample, such as connections to other domains or IPs\n*Behaviors*\nInformation about specific actions or unique properties of this sample, especially local to your network or the computer the sample is run on.\n\nThe basic query format for the /sample/ endpoint is is \"https://investigate.api.umbrella.com/sample/{hash}\" \n\nThe hash must be a valid MD5, SHA1 or SHA256.\n\n### Parameter for input ###\n[block:parameters]\n{\n \"data\": {\n \"0-0\": \"limit\",\n \"0-1\": \"integer\",\n \"0-2\": \"default of 10, can be extended for a larger data set.\",\n \"1-0\": \"offset\",\n \"1-1\": \"integer\",\n \"1-2\": \"the offset of the individual entities in the query’s response, used for pagination.\",\n \"h-0\": \"Field\",\n \"h-1\": \"Type\",\n \"h-2\": \"Description\"\n },\n \"cols\": 3,\n \"rows\": 2\n}\n[/block]\nThree errors are typically seen. When a valid hash does not match any known samples, or when the hash value is invalid, or when the hash length does not match any known hash types.\n\nSample errors:\n[block:code]\n{\n \"codes\": [\n {\n \"code\": \"{\\n \\\"errorMessage\\\": \\\"hash The provided hash's length does not match known hash type\\\"\\n}\\n\\n{\\n \\\"errorMessage\\\": \\\"hash The provided hash does not validate as a valid SHA256 value\\\"\\n}\\n{\\n \\\"error\\\": \\\"Could not find sample for '3ee3cbe0ca92d2470f50712adf60fb03e4ad327fd78e630e004571b89db47cea'\\\"\\n}\",\n \"language\": \"text\"\n }\n ]\n}\n[/block]\nSample query for a hash with the limit set to 100 and offset of 10:\n[block:code]\n{\n \"codes\": [\n {\n \"code\": \"https://investigate.api.umbrella.com/sample/e9d3470c37dada28d5a32fb53a243c5b20def35bb01abf8f5403182cc2b91fdd?limit=100&offset=10\",\n \"language\": \"text\"\n }\n ]\n}\n[/block]\n### Returned value for output if Success 200 ###\n\nAll types of query will have the following return values. The first section of results will match those from the /samples/ API query earlier but are repeated here:\n[block:parameters]\n{\n \"data\": {\n \"0-0\": \"sha256\",\n \"0-1\": \"hash\",\n \"0-2\": \"The SHA256 checksum of the sample.\",\n \"3-0\": \"magictype\",\n \"3-2\": \"A ‘magic type’ is better understood as a file type based on established file format types that allow files to be associated by the operating system and executed or loaded into memory.\",\n \"1-0\": \"sha1\",\n \"1-1\": \"hash\",\n \"1-2\": \"The SHA1 checksum of the sample.\",\n \"2-0\": \"md5\",\n \"2-1\": \"hash\",\n \"2-2\": \"The MD5 checksum of the sample.\",\n \"3-1\": \"string\",\n \"4-0\": \"threatScore\",\n \"4-2\": \"The score given to a particular sample based on the analysis performed by Threat Grid. A threatScore is a measure of the amount of system weakening, obfuscation, persistence, modification, data exfiltration, and other behaviors which may be a threat to the host system’s integrity. It is intended as an overall threat indicator that can be used as a guide to the likelihood that a submission is malicious. The Threat Score is not an authoritative classification of good and bad software.\",\n \"5-0\": \"size\",\n \"5-1\": \"integer\",\n \"5-2\": \"The size of the sample in bytes.\",\n \"4-1\": \"string\",\n \"6-0\": \"firstSeen\",\n \"6-2\": \"The epoch timestamp for when this sample was first seen by Threat Grid.\",\n \"6-1\": \"integer\",\n \"7-0\": \"lastSeen\",\n \"7-1\": \"integer\",\n \"7-2\": \"The epoch tim stamp for when this sample was last seen by Threat Grid.\",\n \"8-0\": \"visible\",\n \"8-1\": \"boolean\",\n \"8-2\": \"For internal Umbrella use only, please ignore.\",\n \"9-0\": \"avresults\",\n \"9-1\": \"string\",\n \"9-2\": \"AntiVirus results according to ClamAV. A sample can have more than one signature if it is possibly detected under more than one family of malware. A sample may also have no signatures associated.\",\n \"h-0\": \"Field\",\n \"h-1\": \"Type\",\n \"h-2\": \"Description\"\n },\n \"cols\": 3,\n \"rows\": 10\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/sample/{hash}?limit=100&offset=10\\\"\\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%\\\" \\\\\\n\\\"https://investigate.api.umbrella.com/sample/{hash}?limit=100&offset=10\\\"\\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 \\\"sha256\\\": \\\"e9d3470c37dada28d5a32fb53a243c5b20def35bb01abf8f5403182cc2b91fdd\\\",\\n \\\"sha1\\\": \\\"de182fdcc3c0d473b90a0df0ad14c2074d1e7c50\\\",\\n \\\"md5\\\": \\\"282f80e8a2cf9e0e0dd72093787d99c6\\\",\\n \\\"magicType\\\": \\\"PE32 executable (GUI) Intel 80386, for MS Windows\\\",\\n \\\"threatScore\\\": 100,\\n \\\"size\\\": 192512,\\n \\\"firstSeen\\\": 1460108539000,\\n \\\"lastSeen\\\": 1460108539000,\\n \\\"visible\\\": true,\\n \\\"avresults\\\": [\\n {\\n \\\"signature\\\": \\\"Win.Trojan.Ramnit\\\",\\n \\\"product\\\": \\\"ClamAV\\\"\\n },\\n {\\n \\\"signature\\\": \\\"Win.Trojan.Parite\\\",\\n \\\"product\\\": \\\"ClamAV\\\"\\n }\\n ],\\n\\n </pre>\\n </div>\\n</div>\\n<style></style>\"\n}\n[/block]\n### /sample/ for artifacts and samples\n[block:callout]\n{\n \"type\": \"success\",\n \"title\": \"NOTE:\",\n \"body\": \"The /artifacts/ section will only display for Threat Grid customers.\"\n}\n[/block]\nThe next section of response is a nested JSON blob for artifacts. The /artifacts/ field under the /sample/ endpoint is split into two fields: \n\n* 'artifacts' that hold artifacts without Threatscore\n* 'samples' that hold artifacts with Threatscore \n\nTo paginate for additional artifacts, you can specify an extended limit if your totalResults were to exceed the limit by using this endpoint:\n\n/sample/{hash}/artifacts/\n\nWhere {hash} is the MD5/SHA1/SHA256 of the sample.\n\n### Parameter for input for /artifacts/ ###\n[block:parameters]\n{\n \"data\": {\n \"0-0\": \"limit\",\n \"0-1\": \"integer\",\n \"0-2\": \"Default to 10, but can be extended for a larger data set\",\n \"1-0\": \"offset\",\n \"1-1\": \"integer\",\n \"1-2\": \"Used to paginate between sets of data\",\n \"h-0\": \"Field\",\n \"h-1\": \"Type\",\n \"h-2\": \"Description\"\n },\n \"cols\": 3,\n \"rows\": 2\n}\n[/block]\nTo paginate for additional samples, you can specify an extended limit if your totalResults were to exceed the limit by using this endpoint:\n\n/sample/{hash}/samples\n\nWhere {hash} is MD5/SHA1/SHA256 of the sample.\n\n### Parameter for input for /samples/{hash}/samples ###\n[block:parameters]\n{\n \"data\": {\n \"0-0\": \"limit\",\n \"0-1\": \"integer\",\n \"0-2\": \"Default to 10, but can be extended for a larger data set\",\n \"1-0\": \"offset\",\n \"1-1\": \"integer\",\n \"1-2\": \"Used to paginate between sets of data\",\n \"h-0\": \"Field\",\n \"h-1\": \"Type\",\n \"h-2\": \"Description\"\n },\n \"cols\": 3,\n \"rows\": 2\n}\n[/block]\nSample query for an artifact with a limit of 100\n[block:code]\n{\n \"codes\": [\n {\n \"code\": \"https://investigate.api.umbrella.com/sample/de182fdcc3c0d473b90a0df0ad14c2074d1e7c50/artifacts?limit=100\",\n \"language\": \"text\"\n }\n ]\n}\n[/block]\nThe results have been shortened here for ease of reading. Descriptions match those for /sample/\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/sample/{hash}/artifacts?limit=100\\\"\\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%\\\" \\\\\\n\\\"https://investigate.api.umbrella.com/sample/{hash}/artifacts?limit=100\\\"\\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 \\\"artifacts\\\": {\\n \\\"totalResults\\\": 10,\\n \\\"moreDataAvailable\\\": true,\\n \\\"limit\\\": 100,\\n \\\"offset\\\": 0,\\n \\\"artifacts\\\": [\\n {\\n \\\"sha256\\\": \\\"fd6c69c345f1e32924f0a5bb7393e191b393a78d58e2c6413b03ced7482f2320\\\",\\n \\\"sha1\\\": \\\"b4fa74a6f4dab3a7ba702b6c8c129f889db32ca6\\\",\\n \\\"md5\\\": \\\"ff5e1f27193ce51eec318714ef038bef\\\",\\n \\\"magicType\\\": \\\"PE32 executable (GUI) Intel 80386, for MS Windows, UPX compressed\\\",\\n \\\"size\\\": 56320,\\n \\\"firstSeen\\\": 1460108539000,\\n \\\"lastSeen\\\": 1460108539000,\\n \\\"visible\\\": false,\\n \\\"avresults\\\": []\\n },\\n \\\"samples\\\": {\\n \\\"totalResults\\\": 1,\\n \\\"moreDataAvailable\\\": false,\\n \\\"limit\\\": 2,\\n \\\"offset\\\": 0,\\n \\\"samples\\\": [\\n {\\n \\\"sha256\\\":\\\"9e55cc29f8edb91e6d86530986f08528bb20429e8dce0fec0cfb74f189054db2\\\",\\n \\\"sha1\\\": \\\"ea020f1adf052edcea33b03318b0ecb99a640448\\\",\\n \\\"md5\\\": \\\"ea0008159914b7f20e2f82db77528171\\\",\\n \\\"magicType\\\": \\\"\\\",\\n \\\"threatScore\\\": 56,\\n \\\"size\\\": 16,\\n \\\"firstSeen\\\": 1456268452000,\\n \\\"lastSeen\\\": 1456268452000,\\n \\\"avresults\\\": [],\\n \\\"Behaviors\\\": []\\n }\\n ]\\n },\\n\\n\\n </pre>\\n </div>\\n</div>\\n<style></style>\"\n}\n[/block]\n### /sample/ for connections\n\nThe next nested array is “Connections”, which are IP or domain ‘call outs’ associated with this sample. This gives you additional pivot points from within the sample that you can then associate in Investigate to determine if these are related to this malware’s activity or simply a domain or IP that is being used by the malware to determine connectivity (as in the ‘google.com’ result in the example below).\n\nTo paginate for additional connections, you can specify an extended limit if your totalResults were to exceed the limit by using this endpoint:\n\n/sample/{hash}/connections/\n\nWhere {hash} is the MD5/SHA1/SHA256 of the sample.\n\n### Parameter for input for /sample/{hash}/connections ###\n[block:parameters]\n{\n \"data\": {\n \"0-0\": \"limit\",\n \"0-1\": \"integer\",\n \"0-2\": \"Default to 10, but can be extended for a larger data set\",\n \"1-0\": \"offset\",\n \"1-1\": \"integer\",\n \"1-2\": \"Used to paginate between sets of data\",\n \"h-0\": \"Field\",\n \"h-1\": \"Type\",\n \"h-2\": \"Description\"\n },\n \"cols\": 3,\n \"rows\": 2\n}\n[/block]\nSample query for connections of a hash with a limit of 100:\n[block:code]\n{\n \"codes\": [\n {\n \"code\": \"https://investigate.api.umbrella.com/sample/de182fdcc3c0d473b90a0df0ad14c2074d1e7c50/connections?limit=100\",\n \"language\": \"text\"\n }\n ]\n}\n[/block]\n### Returned value for output if Success 200 ###\n[block:parameters]\n{\n \"data\": {\n \"0-0\": \"Name\",\n \"0-1\": \"string\",\n \"0-2\": \"The name of the connection, whether that's a domain or an IP address.\",\n \"1-0\": \"firstSeen\",\n \"1-1\": \"integer\",\n \"1-2\": \"The epoch timestamp for when this sample was first seen by Threat Grid.\",\n \"2-0\": \"lastSeen\",\n \"2-1\": \"integer\",\n \"2-2\": \"The epoch timestamp for when this sample was last seen by Threat Grid. The lastSeen and firstSeen will often be the same if the sample is more recent.\",\n \"3-0\": \"securityCategories\",\n \"3-1\": \"string\",\n \"3-2\": \"These categories are the ones that Umbrella assigns to a domain (malware, botnet, etc).\",\n \"4-0\": \"attacks\",\n \"4-1\": \"string\",\n \"4-2\": \"The name of attacks, if any, associated with this connection. An example might be a named botnet such as Kelihos.\",\n \"5-0\": \"type\",\n \"5-1\": \"string\",\n \"5-2\": \"Either HOST, if a domain, or IP if an IP.\",\n \"6-0\": \"ips\",\n \"6-1\": \"array\",\n \"6-2\": \"The list of the actual IP addresses associated with this connection, if any.\",\n \"7-0\": \"urls\",\n \"7-1\": \"array\",\n \"7-2\": \"The list of the domains or URLs associated with this connection, if any.\",\n \"h-0\": \"Field\",\n \"h-1\": \"Type\",\n \"h-2\": \"Description\"\n },\n \"cols\": 3,\n \"rows\": 8\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/sample/{hash}/connections?limit=100\\\"\\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%\\\" \\\\\\n\\\"https://investigate.api.umbrella.com/sample/{hash}/connections?limit=100\\\"\\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 \\\"connections\\\": {\\n \\\"totalResults\\\": 2,\\n \\\"moreDataAvailable\\\": true,\\n \\\"limit\\\": 2,\\n \\\"offset\\\": 0,\\n \\\"connections\\\": [\\n {\\n \\\"name\\\": \\\"google.com\\\",\\n \\\"firstSeen\\\": 1456268452000,\\n \\\"lastSeen\\\": 1456268452000,\\n \\\"securityCategories\\\": [],\\n \\\"attacks\\\": [],\\n \\\"threatTypes\\\": [],\\n \\\"type\\\": \\\"HOST\\\",\\n \\\"ips\\\": [\\n \\\"172.217.1.78\\\"\\n ],\\n \\\"urls\\\": [\\n \\\"http://goo.gl/PDIfV\\\"\\n ]\\n },\\n {\\n \\\"name\\\": \\\"rtvwerjyuver.com\\\",\\n \\\"firstSeen\\\": 1456268452000,\\n \\\"lastSeen\\\": 1456268452000,\\n \\\"securityCategories\\\": [\\n \\\"Botnet\\\",\\n \\\"Malware\\\"\\n ],\\n \\\"attacks\\\": [],\\n \\\"threatTypes\\\": [],\\n \\\"type\\\": \\\"HOST\\\",\\n “ips”: [\\n ],\\n “urls”: [\\n ]\\n }\\n ]\\n },\\n\\n </pre>\\n </div>\\n</div>\\n<style></style>\"\n}\n[/block]\n### Samples for /Behaviors \n\nThe next nested JSON array is ‘behaviors’, which are key traits and behaviors that have been identified as indicators of malicious activity. Individual ‘behaviors’ are broken down within the results from a single checksum. This section will match what you see in the user interface for “behavioral indicators,” and for users of Threat Grid, a list of possible indicators can be found here: https://panacea.threatgrid.com/indicators\n\nAll behaviors for a sample are listed and there should be no need to paginate for additional behaviors. All results are displayed with each query and dding a 'limit' to the result will not result in a syntax error, but will not be honored. \n\nTo isolate to only show behaviors of samples use this endpoint:\n\n/sample/{hash}/behaviors/\n\nWhere {hash} is the MD5/SHA1/SHA256 of the sample.\n\nSample query for the behavior of a hash\n[block:code]\n{\n \"codes\": [\n {\n \"code\": \"https://investigate.api.umbrella.com/sample/de182fdcc3c0d473b90a0df0ad14c2074d1e7c50/behaviors/\",\n \"language\": \"text\"\n }\n ]\n}\n[/block]\n### Returned value for output if Success 200 ###\n[block:parameters]\n{\n \"data\": {\n \"0-0\": \"name\",\n \"0-1\": \"string\",\n \"0-2\": \"The name of the behavior as defined by Threat Grid.\",\n \"1-0\": \"title\",\n \"1-1\": \"string\",\n \"1-2\": \"The formal title of the behavior (human readable) as defined by Threat Grid.\",\n \"2-0\": \"hits\",\n \"2-1\": \"integer\",\n \"2-2\": \"The number of times this behavior was seen in this sample.\",\n \"3-0\": \"confidence\",\n \"3-1\": \"integer\",\n \"3-2\": \"The confidence score indicates the likelihood of a sample exhibiting the stated behavior, ranging from 0 to 100.\",\n \"4-0\": \"severity\",\n \"4-1\": \"integer\",\n \"4-2\": \"The severity score indicates the likely security risk posed by a given behavior, ranging from 0 to 100.\",\n \"5-0\": \"tags\",\n \"5-1\": \"string\",\n \"5-2\": \"Tags associated with this particular behavior; these are provided by ThreatGrid and associated with the type of behavior.\",\n \"6-0\": \"threat\",\n \"6-1\": \"integer\",\n \"6-2\": \"A score measuring the relative threat of this behavior, ranging from 0 to 100. This score is an aggregate of the confidence and severity scores (it is confidence and severity scores multiplied together and divided by 100).\",\n \"7-0\": \"category\",\n \"7-1\": \"string\",\n \"7-2\": \"A list of categories of behaviors, as provided by Threat Grid. The categories include malware, network, and file. The most common category is simply \\\"attribute\\\". For existing Threat Grid customers, a full list can be found in the categories column here: https://panacea.threatgrid.com/indicators\",\n \"h-0\": \"Field\",\n \"h-1\": \"Type\",\n \"h-2\": \"Description\"\n },\n \"cols\": 3,\n \"rows\": 8\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/sample/{hash}/behaviors/\\\"\\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%\\\" \\\\\\n\\\"https://investigate.api.umbrella.com/sample/{hash}/behaviors/\\\"\\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\\\"totalResults\\\": 2,\\n \\\"moreDataAvailable\\\": true,\\n \\\"limit\\\": 2,\\n \\\"offset\\\": 0,\\n \\\"behaviors\\\": [\\n {\\n \\\"name\\\": \\\"pe-packed-upx\\\",\\n \\\"title\\\": \\\"Executable Packed with UPX\\\",\\n \\\"hits\\\": 2,\\n \\\"confidence\\\": 30,\\n \\\"severity\\\": 30,\\n \\\"tags\\\": [\\n \\\"packer\\\",\\n \\\"crypter\\\",\\n \\\"encoding\\\",\\n \\\"PE\\\"\\n ],\\n \\\"threat\\\": 9,\\n \\\"category\\\": [\\n \\\"attribute\\\"\\n ]\\n },\\n {\\n \\\"name\\\": \\\"pe-header-timestamp-null\\\",\\n \\\"title\\\": \\\"PE COFF Header Timestamp is Not Set\\\",\\n \\\"hits\\\": 2,\\n \\\"confidence\\\": 60,\\n \\\"severity\\\": 5,\\n \\\"tags\\\": [\\n \\\"file\\\",\\n \\\"attributes\\\",\\n \\\"anomaly\\\",\\n \\\"PE\\\"\\n ],\\n \\\"threat\\\": 3,\\n \\\"category\\\": [\\n \\\"attribute\\\"\\n ]\\n }\\n ]\\n}\\n\\n\\n </pre>\\n </div>\\n</div>\\n<style></style>\"\n}\n[/block]\n---\n[Latest Malicious Domains for an IP](https://docs.umbrella.com/developer/investigate-api/latest-malicious-domains-for-an-ip-1/) < **Threat Grid Integration (Cisco AMP Threat Grid)**","excerpt":"","slug":"threat-grid-integration-cisco-amp-threat-grid","type":"basic","title":"Threat Grid Integration (Cisco AMP Threat Grid)"}

The Umbrella Investigate integration with Cisco AMP Threat Grid shows samples from the ThreatGrid database associated with a domain, IP or URL that you’re looking to find out more information about. Information about samples is provided in the form of checksums associated when looking up a specific host or IP. Once information about samples has been gathered, there is a second pivot where the Investigate API will look up checksums and reveal additional information about the individual malware samples, including behavior of the sample on the network. The information about what the sample does can then lead back to Investigate to find more clues about the network infrastructure used by the malware you’re researching. Additional research can be done in regard to the severity of the malware samples and the samples’ behaviors when they were analyzed. The two primary endpoints for this API are /samples/ and /sample/. /samples/ gives all the sample information about a specific domain, IP, or URL and once that information has been obtained, the /sample/ endpoint can be used to dig into those samples further and reveal the artifacts, connections, and behaviors of those samples. Using information about the connections of the malware samples, you can continue to investigate related domains and IPs. An alternate use case is taking a list of checksums from another threat intel source, such as an in-house SIEM or third party data feed, and review those checksums against the /sample/ endpoints to find more information about the threats. ### API USAGE AND LIMITATIONS All requests to the API endpoints are GET requests and follow the standard authentication scheme for any other Investigate endpoint. For more about authentication, refer to the 'About the API' section of this guide. It’s important to understand that some perfectly normal, safe domains, such as www.google.com, will have malicious samples associated with them because the malware uses that domain or IP to check internet connectivity, or even as a source to determine more data about the host on which it resides (such as the public IP of the infected host or network). Not all data from Threat Grid is in Investigate. Some of the data has not been ported over as it doesn’t apply to the way Investigate should be used for security incidents. Some legacy information has also not been brought over, although if Threat Grid were to see this sample again, it would become part of the data set. **NOTE:** Portions of the functionality described for this feature of Investigate are only available for customers of both Threat Grid and Investigate. **If you are an existing Thread Grid customer and do not see the details outlined in the areas marked for “Threat Grid Customers Only”, please contact Umbrella Support ([umbrella-support@cisco.com](mailto:umbrella-support@cisco.com)).** If you would like to add Threat Grid to your existing license, contact your account representative ## Usage All requests to the API endpoints are GET requests and follow the standard authentication scheme for any other Investigate endpoint. The two primary endpoints covered in this section are "samples" and "sample": * *The /samples/ API endpoint to research a domain, IP or URL and obtain sample information* * *The /sample/ API endpoint to research a sample in depth* Within the /sample/ endpoint the following information can be found: * _Artifacts and pagination of artifacts_ * _Samples of samples and pagination of sub-samples_ – **_Threat Grid Customers only_** * _Connections of a sample and pagination of connections_ * _Behaviors of a sample_ ## Glossary of Terms The following terms are used by the API (and the UI) and are defined here, in advance, so it’s clear what data is being represented. A full list of all terms used by Threat Grid can be found here—[or Threat Grid customers only](https://panacea.threatgrid.com/doc/main/threat-grid-glossary.html). #### Sample A sample is a type of file, or even a file-like object, such as a process running in memory submitted and analyzed by Threat Grid. #### Artifact Artifacts are files that are created or modified during a sample analysis. Malware executables often download additional components and infect or modify system files, documents, and running processes. Artifacts are sometimes executables which can also be analyzed in Threat Grid and become a sample. #### Behavioral indicators (Behaviors) Key traits and behaviors that have been identified as indicators of malicious activity. Behavioral indicators include threat severity levels, HTTP Traffic, DNS Traffic, TCP/IP network sessions, processes, artifacts, registry activities, and more. #### Connections A network connection made by this particular sample to an IP or a domain, along with information about whether that IP or domain is known malicious. ### The /samples/ API endpoint to research a domain, IP or URL The /samples/ endpoint gives all samples associated with a specific domain, IP address or URL. This endpoint takes input in the form of a domain, an IP, or a URL using standard formats for each. This endpoint will return all samples associated with the domain; the default maximum number of responses is 10, but can be extended. Typically an error is seen when the requested host (domain/IP/URL) is not in a valid format, if the requested host is not found in our database, or if there is no data available for the domain or IP you’ve requested. Please check your input to ensure the format is valid **NOTE:** CIDR subnets (eg: 10.10.10.0/24) are not supported and neither is the pattern search. Sample error: [block:code] { "codes": [ { "code": "{\n \"error\": \"No data available for 'host.com'\"\n}", "language": "text" } ] } [/block] The basic query format is "https://investigate.api.umbrella.com/samples/[domain/ip/url]" Sample query for a domain with a limit of 100 results, sorted by the threat score: [block:code] { "codes": [ { "code": "https://investigate.api.umbrella.com/samples/google.com?limit=100&sortby=score\n", "language": "text" } ] } [/block] Sample query for an IP address with a limit of 15 results, sorted by last seen date: [block:code] { "codes": [ { "code": "https://investigate.api.umbrella.com/samples/195.22.28.196?limit=15&sortby=last-seen", "language": "text" } ] } [/block] >**IMPORTANT NOTE:** URL queries must be encoded and must include the protocol! The example below outlines a typical example of that. Sample query for a URL with an executable included, with a limit of 10 results: [block:code] { "codes": [ { "code": "https://investigate.api.umbrella.com/samples/http%3A%2F%2Fwww.hoarafushionline.net%2Fhabeys.exe?limit=10", "language": "text" } ] } [/block] ### Parameter for input ### [block:parameters] { "data": { "0-0": "limit", "0-1": "The number of responses; default of 10 as a limit on response, can be extended.", "1-1": "Default to 0, used to pagination between sets of data if limit is exceeded.", "1-0": "offset", "2-0": "sortby", "2-1": "Default is score. Choose from [“first-seen\", \"last-seen\", \"score”]. The syntax is appending “sortby=first-seen” to the end of a requirement. \"first-seen\" sorts the samples in date descending order from first to last.\n\"last-seen\" sorts the samples in ascending order from last to first.\n\"score\" sorts the samples by the ThreatScore.", "h-0": "Field", "h-1": "Description" }, "cols": 2, "rows": 3 } [/block] ### Returned value for output if Success 200 ### We've broken the response down into two sections. All types of query will have the following return values: [block:parameters] { "data": { "0-0": "query", "0-1": "string", "1-0": "totalresults", "1-1": "integer", "2-0": "moreDataAvailable", "2-1": "boolean", "3-1": "integer", "0-2": "What string was queried or seen by the API.", "1-2": "The number of results returned. Same as limit if limit is reached and moreDataAvailable is true.", "2-2": "If more data is available. Extend the limit and/or offset to view.", "3-2": "Number of sample results.", "3-0": "limit", "4-0": "offset", "4-1": "integer", "4-2": "The offset of the individual entities in the query’s response; used for pagination.", "h-0": "Field", "h-1": "Type", "h-2": "Description" }, "cols": 3, "rows": 5 } [/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/samples/google.com?limit=100&sortby=score\"\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%\" \\\n\"https://investigate.api.umbrella.com/samples/google.com?limit=100&sortby=score\"\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 \"query\": \"google.com\",\n \"totalResults\": 10,\n \"moreDataAvailable\": true,\n \"limit\": 10,\n \"offset\": 0,\n\n </pre>\n </div>\n</div>\n<style></style>" } [/block] In the second portion of the return from the /samples/ endpoint is information about the actual sample. This return here has been shortened for ease of reading. [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/samples/google.com?limit=100&sortby=score\"\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%\" \\\n\"https://investigate.api.umbrella.com/samples/google.com?limit=100&sortby=score\"\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\"samples\": [\n {\n \"sha256\": \"e9d3470c37dada28d5a32fb53a243c5b20def35bb01abf8f5403182cc2b91fdd\",\n \"sha1\": \"de182fdcc3c0d473b90a0df0ad14c2074d1e7c50\",\n \"md5\": \"282f80e8a2cf9e0e0dd72093787d99c6\",\n \"magicType\": \"PE32 executable (GUI) Intel 80386, for MS Windows\",\n \"threatScore\": 100,\n \"size\": 192512,\n \"firstSeen\": 1460108539000,\n \"lastSeen\": 1460108539000,\n \"visible\": true,\n \"avresults\": [\n {\n \"signature\": \"Win.Trojan.Ramnit\",\n \"product\": \"ClamAV\"\n },\n {\n \"signature\": \"Win.Trojan.Parite\",\n \"product\": \"ClamAV\"\n }\n ]\n },\n]\n </pre>\n </div>\n</div>\n<style></style>" } [/block] [block:parameters] { "data": { "0-0": "sha256", "0-2": "The SHA256 checksum of the sample. This checksum is important if you’d like to find out more about this sample in the /sample/ endpoint.", "0-1": "hash", "1-0": "sha1", "1-1": "hash", "1-2": "The SHA1 checksum of the sample. As above, can be searched in /sample/ endpoint.", "2-0": "md5", "2-1": "hash", "2-2": "The MD5 checksum of the sample, as above, can be searched in /sample/ endpoint.", "4-0": "threatScore", "4-1": "integer", "4-2": "The score given to a particular sample based on the analysis performed by Threat Grid. A threatScore is a measure of the amount of system weakening, obfuscation, persistence, modification, data exfiltration, and other behaviors which may be a threat to the host system’s integrity. It is intended as an overall threat indicator that can be used as a guide to the likelihood that a submission is malicious. The Threat Score is not an authoritative classification of good and bad software.", "5-0": "size", "5-2": "The size of the sample in bytes.", "5-1": "integer", "6-0": "firstSeen", "6-1": "string", "6-2": "The epoch time stamp for when this sample was first seen by Threat Grid.", "7-0": "lastSeen", "7-1": "string", "7-2": "The epoch time stamp for when this sample was last seen by Threat Grid. The lastSeen and firstSeen will often be the same if the sample is more recent.", "8-0": "visible", "8-1": "boolean", "8-2": "Boolean, either true or false. For internal Umbrella use only, please ignore.", "9-0": "avresults", "9-2": "AntiVirus results according to ClamAV. A sample can have more than one signature if it is possibly detected under more than one family of malware. A sample may also have no signatures associated.", "9-1": "string", "3-0": "magicType", "3-1": "string", "3-2": "A ‘magic type’ is better understood as a file type. Specifically, it is the output of the Linux “file” utility.", "h-0": "Field", "h-1": "Type", "h-2": "Description" }, "cols": 3, "rows": 10 } [/block] ### The /sample/ API endpoint to research a sample Once you have gathered the information from the /samples/ endpoint, digging deeper requires that you pivot using the checksums of the samples revealed in your initial query. This pivot will reveal large chunks of new data about the malware being researched. The /sample/ endpoint returns a variety of data as nested JSON arrays. The initial results array contains the information about the original sample. These results are described first and are, in effect, the samples of the sample. Underneath, the following results are nested in JSON outlining additional information: *Artifacts* Other samples associated with this sample, but that are not given a threatScore. *Note that Artifacts are only available for Threat Grid customers.* *Connections* Information about network activity associated with this sample, such as connections to other domains or IPs *Behaviors* Information about specific actions or unique properties of this sample, especially local to your network or the computer the sample is run on. The basic query format for the /sample/ endpoint is is "https://investigate.api.umbrella.com/sample/{hash}" The hash must be a valid MD5, SHA1 or SHA256. ### Parameter for input ### [block:parameters] { "data": { "0-0": "limit", "0-1": "integer", "0-2": "default of 10, can be extended for a larger data set.", "1-0": "offset", "1-1": "integer", "1-2": "the offset of the individual entities in the query’s response, used for pagination.", "h-0": "Field", "h-1": "Type", "h-2": "Description" }, "cols": 3, "rows": 2 } [/block] Three errors are typically seen. When a valid hash does not match any known samples, or when the hash value is invalid, or when the hash length does not match any known hash types. Sample errors: [block:code] { "codes": [ { "code": "{\n \"errorMessage\": \"hash The provided hash's length does not match known hash type\"\n}\n\n{\n \"errorMessage\": \"hash The provided hash does not validate as a valid SHA256 value\"\n}\n{\n \"error\": \"Could not find sample for '3ee3cbe0ca92d2470f50712adf60fb03e4ad327fd78e630e004571b89db47cea'\"\n}", "language": "text" } ] } [/block] Sample query for a hash with the limit set to 100 and offset of 10: [block:code] { "codes": [ { "code": "https://investigate.api.umbrella.com/sample/e9d3470c37dada28d5a32fb53a243c5b20def35bb01abf8f5403182cc2b91fdd?limit=100&offset=10", "language": "text" } ] } [/block] ### Returned value for output if Success 200 ### All types of query will have the following return values. The first section of results will match those from the /samples/ API query earlier but are repeated here: [block:parameters] { "data": { "0-0": "sha256", "0-1": "hash", "0-2": "The SHA256 checksum of the sample.", "3-0": "magictype", "3-2": "A ‘magic type’ is better understood as a file type based on established file format types that allow files to be associated by the operating system and executed or loaded into memory.", "1-0": "sha1", "1-1": "hash", "1-2": "The SHA1 checksum of the sample.", "2-0": "md5", "2-1": "hash", "2-2": "The MD5 checksum of the sample.", "3-1": "string", "4-0": "threatScore", "4-2": "The score given to a particular sample based on the analysis performed by Threat Grid. A threatScore is a measure of the amount of system weakening, obfuscation, persistence, modification, data exfiltration, and other behaviors which may be a threat to the host system’s integrity. It is intended as an overall threat indicator that can be used as a guide to the likelihood that a submission is malicious. The Threat Score is not an authoritative classification of good and bad software.", "5-0": "size", "5-1": "integer", "5-2": "The size of the sample in bytes.", "4-1": "string", "6-0": "firstSeen", "6-2": "The epoch timestamp for when this sample was first seen by Threat Grid.", "6-1": "integer", "7-0": "lastSeen", "7-1": "integer", "7-2": "The epoch tim stamp for when this sample was last seen by Threat Grid.", "8-0": "visible", "8-1": "boolean", "8-2": "For internal Umbrella use only, please ignore.", "9-0": "avresults", "9-1": "string", "9-2": "AntiVirus results according to ClamAV. A sample can have more than one signature if it is possibly detected under more than one family of malware. A sample may also have no signatures associated.", "h-0": "Field", "h-1": "Type", "h-2": "Description" }, "cols": 3, "rows": 10 } [/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/sample/{hash}?limit=100&offset=10\"\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%\" \\\n\"https://investigate.api.umbrella.com/sample/{hash}?limit=100&offset=10\"\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 \"sha256\": \"e9d3470c37dada28d5a32fb53a243c5b20def35bb01abf8f5403182cc2b91fdd\",\n \"sha1\": \"de182fdcc3c0d473b90a0df0ad14c2074d1e7c50\",\n \"md5\": \"282f80e8a2cf9e0e0dd72093787d99c6\",\n \"magicType\": \"PE32 executable (GUI) Intel 80386, for MS Windows\",\n \"threatScore\": 100,\n \"size\": 192512,\n \"firstSeen\": 1460108539000,\n \"lastSeen\": 1460108539000,\n \"visible\": true,\n \"avresults\": [\n {\n \"signature\": \"Win.Trojan.Ramnit\",\n \"product\": \"ClamAV\"\n },\n {\n \"signature\": \"Win.Trojan.Parite\",\n \"product\": \"ClamAV\"\n }\n ],\n\n </pre>\n </div>\n</div>\n<style></style>" } [/block] ### /sample/ for artifacts and samples [block:callout] { "type": "success", "title": "NOTE:", "body": "The /artifacts/ section will only display for Threat Grid customers." } [/block] The next section of response is a nested JSON blob for artifacts. The /artifacts/ field under the /sample/ endpoint is split into two fields: * 'artifacts' that hold artifacts without Threatscore * 'samples' that hold artifacts with Threatscore To paginate for additional artifacts, you can specify an extended limit if your totalResults were to exceed the limit by using this endpoint: /sample/{hash}/artifacts/ Where {hash} is the MD5/SHA1/SHA256 of the sample. ### Parameter for input for /artifacts/ ### [block:parameters] { "data": { "0-0": "limit", "0-1": "integer", "0-2": "Default to 10, but can be extended for a larger data set", "1-0": "offset", "1-1": "integer", "1-2": "Used to paginate between sets of data", "h-0": "Field", "h-1": "Type", "h-2": "Description" }, "cols": 3, "rows": 2 } [/block] To paginate for additional samples, you can specify an extended limit if your totalResults were to exceed the limit by using this endpoint: /sample/{hash}/samples Where {hash} is MD5/SHA1/SHA256 of the sample. ### Parameter for input for /samples/{hash}/samples ### [block:parameters] { "data": { "0-0": "limit", "0-1": "integer", "0-2": "Default to 10, but can be extended for a larger data set", "1-0": "offset", "1-1": "integer", "1-2": "Used to paginate between sets of data", "h-0": "Field", "h-1": "Type", "h-2": "Description" }, "cols": 3, "rows": 2 } [/block] Sample query for an artifact with a limit of 100 [block:code] { "codes": [ { "code": "https://investigate.api.umbrella.com/sample/de182fdcc3c0d473b90a0df0ad14c2074d1e7c50/artifacts?limit=100", "language": "text" } ] } [/block] The results have been shortened here for ease of reading. Descriptions match those for /sample/ [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/sample/{hash}/artifacts?limit=100\"\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%\" \\\n\"https://investigate.api.umbrella.com/sample/{hash}/artifacts?limit=100\"\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 \"artifacts\": {\n \"totalResults\": 10,\n \"moreDataAvailable\": true,\n \"limit\": 100,\n \"offset\": 0,\n \"artifacts\": [\n {\n \"sha256\": \"fd6c69c345f1e32924f0a5bb7393e191b393a78d58e2c6413b03ced7482f2320\",\n \"sha1\": \"b4fa74a6f4dab3a7ba702b6c8c129f889db32ca6\",\n \"md5\": \"ff5e1f27193ce51eec318714ef038bef\",\n \"magicType\": \"PE32 executable (GUI) Intel 80386, for MS Windows, UPX compressed\",\n \"size\": 56320,\n \"firstSeen\": 1460108539000,\n \"lastSeen\": 1460108539000,\n \"visible\": false,\n \"avresults\": []\n },\n \"samples\": {\n \"totalResults\": 1,\n \"moreDataAvailable\": false,\n \"limit\": 2,\n \"offset\": 0,\n \"samples\": [\n {\n \"sha256\":\"9e55cc29f8edb91e6d86530986f08528bb20429e8dce0fec0cfb74f189054db2\",\n \"sha1\": \"ea020f1adf052edcea33b03318b0ecb99a640448\",\n \"md5\": \"ea0008159914b7f20e2f82db77528171\",\n \"magicType\": \"\",\n \"threatScore\": 56,\n \"size\": 16,\n \"firstSeen\": 1456268452000,\n \"lastSeen\": 1456268452000,\n \"avresults\": [],\n \"Behaviors\": []\n }\n ]\n },\n\n\n </pre>\n </div>\n</div>\n<style></style>" } [/block] ### /sample/ for connections The next nested array is “Connections”, which are IP or domain ‘call outs’ associated with this sample. This gives you additional pivot points from within the sample that you can then associate in Investigate to determine if these are related to this malware’s activity or simply a domain or IP that is being used by the malware to determine connectivity (as in the ‘google.com’ result in the example below). To paginate for additional connections, you can specify an extended limit if your totalResults were to exceed the limit by using this endpoint: /sample/{hash}/connections/ Where {hash} is the MD5/SHA1/SHA256 of the sample. ### Parameter for input for /sample/{hash}/connections ### [block:parameters] { "data": { "0-0": "limit", "0-1": "integer", "0-2": "Default to 10, but can be extended for a larger data set", "1-0": "offset", "1-1": "integer", "1-2": "Used to paginate between sets of data", "h-0": "Field", "h-1": "Type", "h-2": "Description" }, "cols": 3, "rows": 2 } [/block] Sample query for connections of a hash with a limit of 100: [block:code] { "codes": [ { "code": "https://investigate.api.umbrella.com/sample/de182fdcc3c0d473b90a0df0ad14c2074d1e7c50/connections?limit=100", "language": "text" } ] } [/block] ### Returned value for output if Success 200 ### [block:parameters] { "data": { "0-0": "Name", "0-1": "string", "0-2": "The name of the connection, whether that's a domain or an IP address.", "1-0": "firstSeen", "1-1": "integer", "1-2": "The epoch timestamp for when this sample was first seen by Threat Grid.", "2-0": "lastSeen", "2-1": "integer", "2-2": "The epoch timestamp for when this sample was last seen by Threat Grid. The lastSeen and firstSeen will often be the same if the sample is more recent.", "3-0": "securityCategories", "3-1": "string", "3-2": "These categories are the ones that Umbrella assigns to a domain (malware, botnet, etc).", "4-0": "attacks", "4-1": "string", "4-2": "The name of attacks, if any, associated with this connection. An example might be a named botnet such as Kelihos.", "5-0": "type", "5-1": "string", "5-2": "Either HOST, if a domain, or IP if an IP.", "6-0": "ips", "6-1": "array", "6-2": "The list of the actual IP addresses associated with this connection, if any.", "7-0": "urls", "7-1": "array", "7-2": "The list of the domains or URLs associated with this connection, if any.", "h-0": "Field", "h-1": "Type", "h-2": "Description" }, "cols": 3, "rows": 8 } [/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/sample/{hash}/connections?limit=100\"\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%\" \\\n\"https://investigate.api.umbrella.com/sample/{hash}/connections?limit=100\"\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 \"connections\": {\n \"totalResults\": 2,\n \"moreDataAvailable\": true,\n \"limit\": 2,\n \"offset\": 0,\n \"connections\": [\n {\n \"name\": \"google.com\",\n \"firstSeen\": 1456268452000,\n \"lastSeen\": 1456268452000,\n \"securityCategories\": [],\n \"attacks\": [],\n \"threatTypes\": [],\n \"type\": \"HOST\",\n \"ips\": [\n \"172.217.1.78\"\n ],\n \"urls\": [\n \"http://goo.gl/PDIfV\"\n ]\n },\n {\n \"name\": \"rtvwerjyuver.com\",\n \"firstSeen\": 1456268452000,\n \"lastSeen\": 1456268452000,\n \"securityCategories\": [\n \"Botnet\",\n \"Malware\"\n ],\n \"attacks\": [],\n \"threatTypes\": [],\n \"type\": \"HOST\",\n “ips”: [\n ],\n “urls”: [\n ]\n }\n ]\n },\n\n </pre>\n </div>\n</div>\n<style></style>" } [/block] ### Samples for /Behaviors The next nested JSON array is ‘behaviors’, which are key traits and behaviors that have been identified as indicators of malicious activity. Individual ‘behaviors’ are broken down within the results from a single checksum. This section will match what you see in the user interface for “behavioral indicators,” and for users of Threat Grid, a list of possible indicators can be found here: https://panacea.threatgrid.com/indicators All behaviors for a sample are listed and there should be no need to paginate for additional behaviors. All results are displayed with each query and dding a 'limit' to the result will not result in a syntax error, but will not be honored. To isolate to only show behaviors of samples use this endpoint: /sample/{hash}/behaviors/ Where {hash} is the MD5/SHA1/SHA256 of the sample. Sample query for the behavior of a hash [block:code] { "codes": [ { "code": "https://investigate.api.umbrella.com/sample/de182fdcc3c0d473b90a0df0ad14c2074d1e7c50/behaviors/", "language": "text" } ] } [/block] ### Returned value for output if Success 200 ### [block:parameters] { "data": { "0-0": "name", "0-1": "string", "0-2": "The name of the behavior as defined by Threat Grid.", "1-0": "title", "1-1": "string", "1-2": "The formal title of the behavior (human readable) as defined by Threat Grid.", "2-0": "hits", "2-1": "integer", "2-2": "The number of times this behavior was seen in this sample.", "3-0": "confidence", "3-1": "integer", "3-2": "The confidence score indicates the likelihood of a sample exhibiting the stated behavior, ranging from 0 to 100.", "4-0": "severity", "4-1": "integer", "4-2": "The severity score indicates the likely security risk posed by a given behavior, ranging from 0 to 100.", "5-0": "tags", "5-1": "string", "5-2": "Tags associated with this particular behavior; these are provided by ThreatGrid and associated with the type of behavior.", "6-0": "threat", "6-1": "integer", "6-2": "A score measuring the relative threat of this behavior, ranging from 0 to 100. This score is an aggregate of the confidence and severity scores (it is confidence and severity scores multiplied together and divided by 100).", "7-0": "category", "7-1": "string", "7-2": "A list of categories of behaviors, as provided by Threat Grid. The categories include malware, network, and file. The most common category is simply \"attribute\". For existing Threat Grid customers, a full list can be found in the categories column here: https://panacea.threatgrid.com/indicators", "h-0": "Field", "h-1": "Type", "h-2": "Description" }, "cols": 3, "rows": 8 } [/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/sample/{hash}/behaviors/\"\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%\" \\\n\"https://investigate.api.umbrella.com/sample/{hash}/behaviors/\"\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\"totalResults\": 2,\n \"moreDataAvailable\": true,\n \"limit\": 2,\n \"offset\": 0,\n \"behaviors\": [\n {\n \"name\": \"pe-packed-upx\",\n \"title\": \"Executable Packed with UPX\",\n \"hits\": 2,\n \"confidence\": 30,\n \"severity\": 30,\n \"tags\": [\n \"packer\",\n \"crypter\",\n \"encoding\",\n \"PE\"\n ],\n \"threat\": 9,\n \"category\": [\n \"attribute\"\n ]\n },\n {\n \"name\": \"pe-header-timestamp-null\",\n \"title\": \"PE COFF Header Timestamp is Not Set\",\n \"hits\": 2,\n \"confidence\": 60,\n \"severity\": 5,\n \"tags\": [\n \"file\",\n \"attributes\",\n \"anomaly\",\n \"PE\"\n ],\n \"threat\": 3,\n \"category\": [\n \"attribute\"\n ]\n }\n ]\n}\n\n\n </pre>\n </div>\n</div>\n<style></style>" } [/block] --- [Latest Malicious Domains for an IP](https://docs.umbrella.com/developer/investigate-api/latest-malicious-domains-for-an-ip-1/) < **Threat Grid Integration (Cisco AMP Threat Grid)**

Umbrella Investigate REST API

Splunk integration with the Investigate API