Scoring API
Using the EchoTrail API, you can provide a process execution profile and EchoTrail will return a detailed and weighted scoring on the commonality of that profile, based on our insights data. This information can be used to create new alerts, upgrade or downgrade existing alerts, or provide a starting point for threat hunting operations.
The Scoring API provides one set of scores by comparing the profile you send us with the global Insights database. However, if you tell us to store statistics about the execution profiles you send us, we can provide you with a much more complete set of scores including:
- customer insights
- environment insights
- host insights
You have control over whether or not we store this information via the record_execution parameter. To enable environment and host insights, you will need to provide those fields and save data with us. Scoring against your own data lets you keep track of what is normal for you, split into categories that align with your business. The more you use the Scoring API, the more the quality of data will improve, and the more confidently you can spot anomalous behavior.
A note on privacy. If you do opt-in to storing data with us, we will store your data securely and separately from our anonymized global database. Some customers choose to md5 hash hostnames to minimize sharing internal information outside their organization. Your local data can be deleted at any time upon request.
For a more detailed explanation of EchoTrail Scoring, see here.
This endpoint allows you to get a score for a process execution profile.
Headers
- Name
api-version- Type
- string
- Description
Optional. See production usage guide.
Body
This endpoint can handle variable process profile fields, and will provide scores based on the fields you pass in. For example, if you only pass in the required image field - you will recieve a score without parent, grandparent, children, etc.
{ "image": "<process name with optional path>", # NOTE: required. "hostname": "<string>", "parent_image": "<parent process with optional path>", "grandparent_image": "<grandparent process with optional path>", "hash": "<string>", "children": [ "<process without path>" ], "network_ports": [ 443 ], "environment": "<string>", "record_execution": <boolean> }
{ "image": "<process name with optional path>", # NOTE: required. "hostname": "<string>", "parent_image": "<parent process with optional path>", "grandparent_image": "<grandparent process with optional path>", "hash": "<string>", "children": [ "<process without path>" ], "network_ports": [ 443 ], "environment": "<string>", "record_execution": <boolean> }
Response
Status Codes:
- 200 OK
- 403 Invalid API Key
- 404 Invalid Path
- 429 Too many requests (exceeded quota)
Each individual score (such as path_score) is the percentage of times we've seen that particular field for a given execution. There is additional nuance in the calculations specific to the individual fields, but thinking of it as a flat percentage is a accurate approximation. If you are interested in more details about this, please contact us!
The echotrail score is a weighted aggregation of each present overall score, each overall score is a weighted aggregation of each score in that block. With 0 being something unusual or never before seen, and 100 being the most common execution seen.
Request
curl https://api.echotrail.io/score \ -X POST \ -H "x-api-key: [your api key]" \ -d '{"image": "C:\\Windows\\System32\\cmd.exe"}'
curl https://api.echotrail.io/score \ -X POST \ -H "x-api-key: [your api key]" \ -d '{"image": "C:\\Windows\\System32\\cmd.exe"}'
Response
# response if you include all fields, but haven't stored data with us. { "echotrail_score": 97, "global": { "rank": 2, "host_prev": 99, "overall_score": 98, "path_score": 97, } }
# response if you include all fields, but haven't stored data with us. { "echotrail_score": 97, "global": { "rank": 2, "host_prev": 99, "overall_score": 98, "path_score": 97, } }