Contributing New Detections

Each detection in trawler is contained within it's own function - to create a new detection, simply write a function with a descriptive name starting with "Check-ABC" where "ABC" is some relatively descriptive term telling a developer what that function is doing.

Each new detection should include a SYNOPSIS docstring that describes in greater detail what the function is doing and why it is useful.

To actually generate a new detection, a custom Detection object must be created and sent to the Write-Detection function like below:

$detection = [PSCustomObject]@{
    Name = 'Suspicious DLL with commonly-masqueraded name loaded into running process.'
    Risk = 'High'
    Source = 'Processes'
    Technique = "T1574: Hijack Execution Flow"
    Meta = [PSCustomObject]@{
        Location = $module.FileName
        Created = $item.CreationTime
        Modified = $item.LastWriteTime
        ProcessName = $process.ProcessName
        PID = $process.ProcessId
        Executable = $process.ExecutablePath
        Hash = Get-File-Hash $module.FileName
    }
}
Write-Detection $detection

At a minimum, detections must include the 5 core fields: Name, Risk, Source, Technique and Meta. Optionally, a Reference field can be included. All fields should be strings except for Meta - which, as seen above, is a custom object that includes additional metadata for the specific detection.

In general, please follow the below guidelines for metadata fields:

1. Please try to use these standardized fields as much as possible:

• Location [string] - Use this to represent WHERE a detection exists - usually a file or registry path
• EntryName [string] - Use this to represent a registry key name, file name etc
• EntryValue [string] - Use this to represent usually the main 'item' in the detection - registry value, file name, etc
• SuspiciousEntry [string] - Use this if there was some logic included to help the analyst understand WHAT caused a detection
• Created [datetime]
• Modified [datetime]
• Hash [string] - If there is a hash of value, include it here as in the above example.

2. When possible, include Created and Modified field as a datetime string, such as file metadata - always use LOCAL time for this, UTC time is automatically added to ALL datetime objects when processing detections.

• If you are able to, also include a comparison against $threshold_date - this is a date that is setup during initialization and we should ignore detections which have 'occurred' prior to this date - this needs to be interpreted for each detection as appropriate rather than being decided globally.

3. Risk should be a string value as "Very Low", "Low", "Medium", "High", "Very High"

4. There are multiple script-level variables setup to help augment developers with data shared across multiple detections - please see below:

• $suspicious_process_paths- Array containing regex items that represent typically-suspicious paths for processes to execute from
• $suspicious_extensions - Array containing typically-suspicious extensions often seen during investigations
• $ipv4_pattern, $ipv6_pattern - Special regex used to help validate whether or not something is an IP address or to extract an IP from some other data.
• $office_addin_extensions - A list of extensions associated with Office AddIns
• $rat_terms - A list of strings associated with RMM Installs/Processes/Services
• $suspicious_software - A list of regex associated with 'suspicious' software - primary RMM/Transfer type utilities
• $threshold_date - A date that should be used for time-based comparisons to check if we should discard a specific detection due to age.