Server.Enrichment.EchoTrail

This is a process execution enrichment artifact that can be called from within another artifact (such as one looking at running processes) to enrich the data made available by that artifact. We are calling the EchoTrail v2 API which is still in beta.

NOTE: The EchoTrail free API is limited to 25 queries per day which is very low for most use cases. This artifact may send more than 25 queries at the API!

Ex.

SELECT * from Artifact.Server.Enrichment.EchoTrail(lookup_image='C:\Windows\system32\svchost.exe', lookup_parent_image='C:\Windows\explorer.exe')

Additional lookup parameters that can be passed:

• lookup_hostname: The hostname which the execution occurred on (for host-specific prevelance metrics)
• lookup_image_hash: The SHA256 hash of the process image
• lookup_parent_image_hash: The SHA256 hash of the process parent image
• lookup_commandline: Command line arguments of the process

name: Server.Enrichment.EchoTrail
author: Eric Capuano - @eric_capuano
description: |
  
  This is a process execution enrichment artifact that can be called from within another artifact (such as one looking at running processes) to enrich the 
  data made available by that artifact. We are calling the EchoTrail v2 API which is still in beta. 
  
  NOTE: The EchoTrail free API is limited to 25 queries per day which is very low for most use cases. This artifact may send more than 25 queries at the API!

  Ex.

    `SELECT * from Artifact.Server.Enrichment.EchoTrail(lookup_image='C:\Windows\system32\svchost.exe', lookup_parent_image='C:\Windows\explorer.exe')`

  Additional lookup parameters that can be passed:

    - `lookup_hostname`: The hostname which the execution occurred on (for host-specific prevelance metrics)
    - `lookup_image_hash`: The SHA256 hash of the process image 
    - `lookup_parent_image_hash`: The SHA256 hash of the process parent image
    - `lookup_commandline`: Command line arguments of the process

type: SERVER

parameters:
    - name: EchoTrailKey
      type: string
      description: API key for EchoTrail. Leave blank here if using server metadata store.
      default:
    - name: lookup_hostname
      type: string
      description: The hostname which the execution occurred on
      default:
    - name: lookup_image
      type: string
      description: The full path to the process image 
      default:
    - name: lookup_image_hash
      type: string
      description: The SHA256 hash of the process image 
      default:
    - name: lookup_parent_image
      type: string
      description: The full path to the process parent image
      default:
    - name: lookup_parent_image_hash
      type: string
      description: The SHA256 hash of the process parent image 
      default:
    - name: lookup_commandline
      type: string
      description: Command line arguments of the process
      default:
    - name: lookup_include_scores
      type: bool
      description: 
      default: true
    - name: lookup_include_description
      type: bool
      description: 
      default: true
    - name: lookup_include_detections
      type: bool
      description: 
      default: true
    - name: record_this_execution
      type: bool
      description: Record this as an actual execution in the EchoTrail database to contribute statistics
      default: false

sources:
  - query: |

        LET Creds = if(
           condition=EchoTrailKey,
           then=EchoTrailKey,
           else=server_metadata().EchoTrailKey)

        LET URL <= 'https://api.echotrail.io/v2/process_execution'

        LET Data = SELECT parse_json(data=Content) AS EchoTrailLookup
        FROM http_client(url=URL,
                         headers=dict(
                          `Accept`="application/json",
                          `x-api-key`=Creds,
                          `Content-Type`="application/json"),
                          method='POST',
                          data=serialize(item=dict(
                            hostname=lookup_hostname,
                            image=lookup_image, 
                            hash=lookup_image_hash,
                            parent_image=lookup_parent_image, 
                            parent_hash=lookup_parent_image_hash,
                            commandline=lookup_commandline, 
                            include_scores=lookup_include_scores,
                            include_description=lookup_include_description,
                            include_detections=lookup_include_detections,
                            record_execution=record_this_execution
                            )
                          )
                        )

        SELECT
            EchoTrailLookup.description AS Description,
            EchoTrailLookup.echotrail_score AS EchoTrailScore,
            EchoTrailLookup.global.rank AS GlobalRank,
            EchoTrailLookup.global.host_prev AS HostPrevalence,
            EchoTrailLookup.global.path_score AS PathScore,
            EchoTrailLookup.global.parent_score AS ParentScore,
            EchoTrailLookup.global.overall_score AS OverallScore,
            EchoTrailLookup AS EchoTrailLookup
        FROM Data