EchoTrail Private API

&nbsp

Summary

Access to the EchoTrail Private REST API is available for purchase. For pricing and additional information, please contact us at sales@echotrail.io. Use of the API requires an API key in the request header field X-Api-Key. Results will be returned in JSON format and will vary by resource. The API is located at https://api.echotrail.io/v1/private/.

&nbsp

Available resources:

  • GET /insights/{searchTerm}
  • GET /insights/{searchTerm}/{field}
  • GET /insights/{searchTerm}/{field}/{subsearch}

&nbsp &nbsp

GET /insights/{searchTerm}

Get a full summary of the requested filename or hash. The summary will contain similar information to what can be found in a search on our website.

searchTerm must be one of:

  • Windows filename with extension (i.e. svchost.exe)
  • SHA256 Hash
  • MD5 Hash

The following items will be included in the results:

  • Description
  • EchoTrail Prevalence Score
  • Host Prevalence, Execution Rank
  • Top 20 Parents
  • Top 20 Children
  • Top 20 Grandparents
  • Top 20 Hashes/filenames
  • Top 20 Paths
  • Top 20 Network connection ports.
  • Intel

Example:

curl -H "X-Api-key:[your-api-key-here]" https://api.echotrail.io/v1/private/insights/svchost.exe

Example Result:

{
    "rank": 11,
    "host_prev": "95.3", 
    "eps": "96.70", 
    "description": "Svchost.exe is the name for services that run from dynamic-linked libraries (DLLs). The Service Host Process acts like a shell for loading services from DLL files. Those services are partitioned into groups and each group is run in a different instance of the Service Host Process. This prevents problems in one instance from affecting other instances. That is also why you will see multiple instances of svchost.exe running at the same time.",
    "intel": "It is normal to see many svchost processes running on a single machine. It usually has elevated privileges and a tremendous amount of trust from Windows and third-party applications, leading to its abuse during a variety of attacks. Automated, opportunistic malware as well as manual, targeted tools commonly abuse this process in a few ways...",
    "paths": [
    ["c:\\windows\\system32", "99.99"],
        ["c:\\windows\\syswow64", "0.00"],
        ["c:\\windows\\temp", "0.00"]
    ],
    "parents": [
        ["services.exe", "99.88"],
        ["msmpeng.exe", "0.11"],
        ["svchost.exe", "0.00"],
        ["explorer.exe", "0.00"],
        ["cmd.exe", "0.00"],
        ["python.exe", "0.00"],
        ["mrt-kb890830.exe", "0.00"],
        ["mrt.exe", "0.00"],
        ["17c3d74e3c0645edb4b5145335b342d2929c92dff856cca1a5e79fa5d935fec2.exe", "0.00"]
    ],
    "children": [
        ["wmiprvse.exe", "19.99"],
        ["backgroundtaskhost.exe", "11.60"],
        ["runtimebroker.exe", "6.47"],
        ["dllhost.exe", "6.30"],
        ["taskhostw.exe", "6.09"],
        ["googleupdate.exe", "3.06"],
        ["hxtsr.exe", "2.89"],
        ["fchelper64.exe", "2.86"],
        ["gpupdate.exe", "2.55"],
        ["wermgr.exe", "1.82"],
        ["hpnetworkcommunicatorcom.exe", "1.81"],
        ["microsoft.photos.exe", "1.77"],
        ["audiodg.exe", "1.35"],
        ["officec2rclient.exe", "1.33"],
        ["rundll32.exe", "1.24"],
        ["consent.exe", "1.21"],
        ["smartscreen.exe", "1.17"],
        ["tokenbrokercookies.exe", "1.11"],
        ["g2mupdate.exe", "1.04"],
        ["sshsession.exe", "0.97"],
        ["taskeng.exe", "0.95"]
    ],
    "grandparents": [
        ["wininit.exe", "99.87"],
        ["services.exe", "0.13"],
        ["explorer.exe", "0.00"],
        ["cmd.exe", "0.00"],
        ["userinit.exe", "0.00"],
        ["windows-kb890830-x64-v5.62-delta.exe", "0.00"],
        ["windows-kb890830-x64-v5.58-delta.exe", "0.00"],
        ["windows-kb890830-x64-v5.57-delta.exe", "0.00"]
    ],
    "hashes": [
        ["b868487f8edbd0571d30d89573f087bfeac3da190652344afd351b1868ea0f8b", "65.81"],
        ["9f21e51442209bcec0ea4a468ef8a4741685ae204d5063f4c3e45e1f8cf72643", "26.25"],
        ["c9a28dc8004c3e043cbf8e3a194fda2b756ce90740df2175488337281b485f69", "4.12"],
        ["c7db4ae8175c33a47baa3ddfa089fad17bc8e362f21e835d78ab22c9231fe370", "1.81"],
        ["438b6ccd84f4dd32d9684ed7d58fd7d1e5a75fe3f3d12ab6c788e6bb0ffad5e7", "1.15"],
        ["5d00bbeb147e0c838a622fc42c543b2913d57eaca4e69d9a37ed61e98c819347", "0.45"],
        ["93b2ed4004ed5f7f3039dd7ecbd22c7e4e24b6373b4d9ef8d6e45a179b13a5e8", "0.26"],
        ["745e45b1e868c395c033c3178b423d2be121da0abbf859553adf1a7d383099b7", "0.06"],
        ["8a88e067e89d1dcfcafd842c0cb7de5dc7e6754447f2064a2bdf8496b088bd52", "0.05"],
        ["40a73317ac3adc9236338920ff106ceb9844af15295f02d6f85a9427d1dac01d", "0.04"],
        ["9f9425fe5725e5d9b519e8dd704de02736515845a6d0eff30d2ecab285c727d5", "0.00"],
        ["99e7587d1744bf62086feb06a778cf3966199f1cc2dfb91fda53a9166a2a3aec", "0.00"],
        ["1030ce4102dac701fab043e40444e8f6c96c8c04b5bd512a59e1a4999d22b38c", "0.00"],
        ["abd4afd71b3c2bd3f741bbe3cec52c4fa63ac78d353101d2e7dc4de2725d1ca1", "0.00"],
        ["6f88fb88ffb0f1d5465c2826e5b4f523598b1b8378377c8378ffebc171bad18b", "0.00"],
        ["dab5dc65269c0f834eade5177f8fb486c08685eb6773369576303855f70ef82f", "0.00"],
        ["20846d6246af9d7d606c5d6d63d962e76dc45770c0d32b5034b0f666073872de", "0.00"],
        ["935c1861df1f4018d698e8b65abfa02d7e9037d8f68ca3c2065b6ca165d44ad2", "0.00"],
        ["c2de637757a907da8151c0922b5cf735f6cd5faabef233abff72868241dcfd0d", "0.00"],
        ["81085213f6c49a2edcc0c26954f8a5a78bdd4583fb4608fdeb6235267edadf46", "0.00"],
        ["7a1c7d7b5c77789106ea4ffd398a132825c6c97b69957d76719ff64b34628df9", "0.00"]
    ],
    "network": [
        ["443", "45.15"],
        ["80", "32.48"],
        ["5355", "0.61"],
        ["1900", "0.39"],
        ["5353", "0.30"],
        ["53", "0.23"],
        ["54188", "0.23"],
        ["3702", "0.21"],
        ["54189", "0.10"],
        ["67", "0.07"],
        ["53240", "0.07"],
        ["59298", "0.07"],
        ["547", "0.07"],
        ["53242", "0.06"],
        ["53241", "0.05"],
        ["53048", "0.05"],
        ["62120", "0.05"],
        ["64473", "0.04"],
        ["58569", "0.04"],
        ["50531", "0.04"],
        ["51114", "0.04"]
    ]
}

&nbsp

Empty Result

If the search was successful, but the filename wasn’t found in the database, the API will return a 200 status code with the below result:

{ "message": "EchoTrail has never observed foo.exe execute in the wild" }

&nbsp

In the event of an invalid search or an incorrect url path, the EchoTrail API will return a 403 or 404. If the path is correct but the authorization token is invalid, EchoTrail will return a 403.

&nbsp &nbsp


GET /insights/{searchTerm}/{field}

Get one particular field from the summary results. If you only need access to one field in the above summary, use this resource as it will be much more efficient to fetch the one field you need.

searchTerm must be one of:

  • Windows filename with extension (i.e. svchost.exe)
  • SHA256 Hash
  • MD5 Hash

field must be one of the following:

  • description
  • rank
  • host_prev
  • eps
  • parents
  • children
  • grandparents
  • hashes
  • paths
  • network
  • intel

Example:

curl -H "X-Api-key:[your-api-key-here]" https://api.echotrail.io/v1/private/insights/svchost.exe/description

Example Result:

{
    "description": "Svchost.exe is the name for services that run from dynamic-linked libraries (DLLs). The Service Host Process acts like a shell for loading services from DLL files. Those services are partitioned into groups and each group is run in a different instance of the Service Host Process. This prevents problems in one instance from affecting other instances. That is also why you will see multiple instances of svchost.exe running at the same time.\n\nTypical Path: c:\\windows\\system32\nTypical Hash: b868487f8edbd0571d30d89573f087bfeac3da190652344afd351b1868ea0f8b"
}

&nbsp

Empty Results

In the event of a successful search with empty results, echotrail will return a 200 with an empty result like the below example:

{ "network": [ ] }

This will occur in scenarios where a given file has never been observed exhibiting the behavior being searched for.

&nbsp

Invalid field

In the event of an invalid field, the EchoTrail API 404 with a message field indicated an invalid field.

{ "message": "Invalid Field" }

&nbsp &nbsp


GET /insights/{searchTerm}/{field}/{subsearch}

For fields with a list of results, such as parents, this resource gives you the ability to subsearch that list.

The following fields can be subsearched:

  • parents
  • children
  • grandparents
  • hashes
  • paths

subsearch can be any string to search for within the results of the field search. For example, when subsearching a list of parents, the subsearch string should be a filename with extension.

Example:

curl -H "X-Api-key:[your-api-key-here]" https://api.echotrail.io/v1/private/insights/svchost.exe/parents/services.exe

In this example, you are searching the list of parents of svchost.exe to see if services.exe has been observed as a parent. If it has, a result will be returned with the prevalence of services.exe as a parent of svchost.exe.

Example Result:

["services.exe", 99.88]

In this case, services.exe has been observed as the parent of svchost.exe 99.88% of the time. Indicating an extremely common relationship.

&nbsp

Empty Results

In the event of a successful subsearch with empty results, echotrail will return a 200 with the below message:

{ "message": "No results found." }