Defining a custom sandfly involves a specific JSON structure and a myriad of values, some required, some optional, and some different based on which engine is being used. This section goes into those details along with providing examples to aid you in making your own sandflies.

Sandfly JSON Details

Custom sandflies look similar to the JSON below. We will go over what each section means further below.

{
  "active": true,
  "author": "Sandfly Security",
  "comment": "",
  "description": "Searches for generic shell commands that may be operating as a backdoor on the system (variant 1).",
  "format": "4.0",
  "max_cpu_load": 1,
  "max_disk_load": 1,
  "max_timeout": 360,
  "name": "process_backdoor_bindshell_generic_1_copy",
  "options": {
    "engines": [
      "sandfly_engine_process"
    ],
    "explanation": "The process name '{process.name}' with PID '{process.pid}' may be operating as a generic shell backdoor based on the command line contents. Check this process and any open network ports to be sure it is not malicious as it could allow remote access or exfiltration of data.",
    "response": {
      "process": {
        "kill": false,
        "suspend": false
      }
    },
    "rule_op": "and",
    "rules": [
      "process.cmdline matches '(.*/dev/(tcp|udp)/.*/[0-9]{1,5})'",
      "process.network_ports.operating == true"
    ]
  },
  "severity": 5,
  "tags": [
    "attack.id.T1048",
    "attack.id.T1059",
    "attack.id.T1095",
    "attack.tactic.command_and_control",
    "attack.tactic.execution",
    "attack.tactic.exfiltration",
    "process"
  ],
  "type": "process",
  "version": "2024-01-15T19:00:00.000Z",
  "custom": false,
  "date_added": "2024-01-15T19:00:08.000Z"
}

Header

The header of the custom Sandfly describes what it is to the system. This is used to organize the Sandfly in the database and for display in the UI. Key elements include:

• name - Name of the Sandfly using only lower case and underscores (_) characters in the value.
• author - Name of the author of this sandfly.
• comment - Additional comments explaining how the sandfly works, intended to provide clarification to sandfly authors (as opposed to users of the sandfly) if necessary.
• description - A short description of what the sandfly does which is shown in the UI listing.
• format - Sandfly format version. Use the default and do not alter it, otherwise the Sandfly will be 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 load this sandfly may cause on the remote host. A value of 1 is lowest and value of 3 the highest.
• severity - A value ranging from 0 to 3 used to for personalizing a sandfly for use within your environment.
• tags - Informational tags applied to this sandfly. At a minimum, each sandfly must have a tag matching its type.
• type - This is either directory, file, incident, log, policy, process, recon or user. Any other value is rejected.
• version - Informational version string for authors to indicate the version of the sandfly.
• options - The options to pass to the forensic engine. See Custom Sandfly Options for full details.

Important points regarding the naming of sandflies:

• A custom sandfly can never be saved with the name of an existing system sandfly.
  • If a system sandfly needs to be extended, you can use the same base name and simply add some extra identifier to help indicate that this is a modified version of a system sandfly.
  • Example: 'dirs_hidden_bin' could become 'dirs_hidden_bin_modified' or 'dirs_hidden_bin_internal'.
• Ensure that custom sandfly names are unique. If a new or uploaded custom sandfly has the name of an existing custom sandfly, when saved it will completely overwrite the existing sandfly regardless of its content.

❗️

IMPORTANT: Custom Sandflies With The Same Name Will Be Overwritten!

Ensure that custom sandfly names are unique. If a new or uploaded custom sandfly has the name of an existing custom sandfly, when saved it will completely overwrite the existing sandfly regardless of its content.