Custom Sandflies Operation

Custom sandflies are small JSON modules that are passed to the Sandfly agentless forensic engines to investigate remote systems.

Custom sandflies can be quickly created to leverage the file, directory, log, process, user and other incident response analysis that the full Sandfly system has to offer.

Basics of Custom Sandflies

Custom sandflies look like the JSON below. We'll go over what each section means.

{
  "description": "Sample custom sandfly data that searches for a file hash anywhere on the file system.",
  "format": "2.8",
  "max_timeout": 1800,
  "max_cpu_load": 3,
  "max_disk_load": 3,
  "name": "sandfly_file_custom_example",
  "options": {
    "engines": [
      "sandfly_engine_file"
    ],
    "file": {
      "search_paths_recurse": true,
      "search_paths": [
        "/"
      ],
      "search_paths_patterns": [
        ".*"
      ],
      "search_paths_patterns_ignore": [],
      "search_paths_individual": [],
      "hash": {
        "sha1": [
          "sha1_hash_here",
          "another_hash_here",
          "more_hashes_here"
        ]
      }
    },
    "response": {},
    "explanation": "The file '{file.path}' matches the SHA1 hash '{file.hash.sha1}'. It is owned by UID '{file.uid}' and was created on {file.date.created}."
  },
  "tags": [
    "file",
    "attack.id.T1234",
    "attack.tactic.tactic_name",
    "custom_tag_name"
  ],
  "type": "file",
  "version": "2020-10-19T09:04:26"
}

Custom Sandfly Header

The header of the custom Sandfly describes what it is to the system. This is used to organize and display the Sandfly to the UI and database. The default values consist of:

name - Name of the Sandfly using lower case and underscores (_) only in the values.
description - A short description of what the sandfly does which is shown in the UI listing.
version - Version format for the sandfly. Please use the default and don't alter this or the Sandfly will be rejected.
type - This is either file, directory, user, process, incident or recon. Any other value is rejected.
max_timeout - Maximum number of seconds this Sandfly can run before it is stopped by the system. Maximum timeout value allowed is 1800 seconds (30 minutes). The minimum allowed is 1 second.
max_cpu_load - The relative loading this sandfly may cause on the remote host. A value of 1 is lowest, and value of 3 the highest.
max_disk_load - The relative disk loading this sandfly may cause on the remote host. A value of 1 is lowest and value of 3 the highest.
options - The options to pass to the forensic engine. This will be discussed below.

Custom Sandfly Options

The options area of the custom sandfly is where the parameters for searching are passed to the agentless forensic engines. See the next section on how this works.