How to: Create Detection Rules for Chainsaw

Chainsaw is a powerful (and free) command-line tool created by F-Secure which in my experience is great for quick wins and providing start points in Windows endpoint investigations and Threat Hunts.

Chainsaw uses both in-built detection logic and external rules to identify threats in Windows Event logs. The external rules use the ‘Sigma’ signature format (written in YAML) which is designed to help security analysts describe and share information about logs easily.

Chainsaw’s use of Sigma means you can add your own detection rules as and when you identify new event log Indicators of Compromise (IOCs). In this blog I’ll be showing you how to make and incorporate your own Sigma rules into Chainsaw.

Hunt syntax

Before we modify any files, it is useful to understand how they interact when Chainsaw is executed. Chainsaw has two functionalities, ‘search’ and ‘hunt’. The latter utilises external Sigma rules to match against .evtx files.

When you use Chainsaw’s ‘hunt’ functionality with external rules, you need to provide three parameters:

1) The location of the .evtx files (the event logs you want hunt accross)

2) The location of the .yml files (the Sigma rule IOCs you want to hunt for)

3) The location of the .yml file used for rule mapping (the specific Event IDs within the .evtx to hunt in)

The hunt command will look something like:

chainsaw.exe hunt "C:\DirectoryContainingEventLogs" --rules “C:\DirectoryContainingSigmaRules” --mapping “C:\SigmaMappingFile.yml”

Why make your own rules?

Testing Chainsaw’s in-built detection logic and the Sigma rules available to download with the tool against sample data from previous incidents, I was able to identify Windows Event Log IOCs that weren’t being detected.

Specifically, the tool wasn’t detecting event logs that indicated usage of Base64 encoded PowerShell. These events were being logged with Event IDs 400 and 600 which weren’t part of the ‘out-of-the-box’ mapping file (sigma-mapping.yml) and the existing Sigma rules also weren’t configured to spot it. Therefore, to successfully detect my encoded PowerShell IOC with Chainsaw, I needed to create/modify the external rules and mapping.

Creating Your Own Rules

First up, you can either create a new mapping file if you wanted to run your custom detections separately, or you can edit the existing mapping file ‘sigma-mapping.yml’. In this example, I modified the original so that my custom Sigma rules are added to the existing search logic.

In the mapping file, you are providing the Event ID you want Chainsaw to run the rules against, the provider of the logs, which fields of the log you want to become search fields, and what additional fields you want as table headers in the output.

To help the correct name of the ‘provider’ etc. it’s a good idea to open the ‘Friendly View’ details of the event log you’re creating a rule for in Event Viewer.

It’s also a good idea to use an existing Sigma rule as a template as YAML won’t forgive you if your indentations and spacings aren’t perfect.

Screenshot of Sigma Mapping file

In this mapping file example, I have added that I want Chainsaw to hunt in the Event Data of PowerShell logs with the Event IDs 400 and 600. I have also specified that the System Channel (log name) be added as a table header when output.

Event Properties of interesting event log

Now we’ve told Chainsaw where it needs to look, we need to tell it what to look for with our Sigma rule. In this example I have created a new Sigma rule which contains among other things, the title of the detection (for output) and the strings that need to be present in the log to produce a match.

Custom Sigma rule

In this Sigma rule I have specified that EventData needs to contain the string ‘powershell’ and (to demonstrate the flexibility of Sigma) just one of the strings ‘FromBase64String’, ‘Compression.GzipStream’ and ‘Decompress’.

To use this rule in the same Chainsaw ‘hunt’ as the default Sigma rules, I saved the new .yml file in a new ‘CustomRules’ subdirectory under the existing ‘sigma_rules’ directory.

Now when running Chainsaw it successfully identifies my encoded PowerShell IOC:

Command line output

And when you output the results as .csv, Chainsaw uses the title you provided in the mapping file to name the spreadsheet:

CSV output

Happy Hunting!

Command syntax and rule shown compatible with Chainsaw Version 1.*