# Converting Sigma Rules

## Overview

Use the [`sigma-cli`](https://github.com/SigmaHQ/sigma-cli) tool to convert [Sigma rules](https://sigmahq.io/docs/basics/rules.html) into [Simple Detections](https://docs.panther.com/detections#simple-detections) or [Python detections](https://docs.panther.com/detections/rules/python).

In security and threat intelligence communities, Sigma rules are a common way to share detection logic in a vendor-agnostic format. This converter makes thousands of Sigma rules available for use in Panther. It also can make it easier to migrate to Panther from another SIEM.

Currently, only rules for [certain Panther log sources](#supported-conversions) are supported for conversion.

## Installing the tool

To install the tool:

1. Install `sigma-cli`:
   * On MacOS, you can do so using Homebrew:\
     `brew install sigma-cli`
   * On other platforms, follow [these installation instructions](https://github.com/SigmaHQ/sigma-cli#installation).
2. Run the following command to install the Panther backend and pipelines:

   ```bash
   sigma plugin install panther
   ```

## Upgrading the tool

1. Upgrade `sigma-cli`:
   * On MacOS, run `brew upgrade`.
   * On other platforms, rerun [these installation instructions](https://github.com/SigmaHQ/sigma-cli#installation).
2. Upgrade the plugin by rerunning the installation command:

   ```bash
   sigma plugin install panther
   ```

## Using the tool

To use the conversion tool:

1. Navigate to your local directory of Sigma rules.
2. Run the conversion command:

   ```bash
   sigma convert -s -t panther -f <format> -p <processing pipeline> path/to/rules -O output_dir=output/directory
   ```

   * The value of the processing pipeline flag (`-p`) differs depending on whether the source is a [cloud](#cloud-log-sources) or [endpoint detection and response (EDR)](#edr-log-sources) source.
     * Cloud log sources: Use `panther` (default)
     * EDR sources: See options in the [`sigma convert` flags](#sigma-convert-flags) table, below
   * The value of the format flag (`-f`) can be one of the following:
     * `python` (default): Generates [Python Detections](https://docs.panther.com/detections/rules/python)
     * `sdyaml`: Generates [Simple Detections](https://docs.panther.com/detections/rules/writing-simple-detections)
   * Learn about additional command options in the [`sigma convert` flags](#sigma-convert-flags) table, below. See the [Usage section of the `sigma-cli` `README`](https://github.com/SigmaHQ/sigma-cli/tree/main#usage) for additional usage instructions.
3. Upload the converted rules to Panther using the [Panther Analysis Tool](https://docs.panther.com/panther-developer-workflows/detections-repo/pat) or the [Bulk Uploader](https://docs.panther.com/panther-developer-workflows/ci-cd/deployment-workflows/pat/pat-commands#uploading-content-in-the-panther-console).

## Supported conversions

### Cloud log sources

All cloud sources use the same conversion command:

```bash
sigma convert -s -t panther path/to/rules -O output_dir=output/directory
```

<table><thead><tr><th width="201">Source name</th><th width="594">Supported Panther schema(s)</th></tr></thead><tbody><tr><td>AWS CloudTrail</td><td><a href="../../data-onboarding/supported-logs/aws/cloudtrail#aws.cloudtrail"><code>AWS.CloudTrail</code></a></td></tr><tr><td>GCP Audit</td><td><a href="https://docs.panther.com/data-onboarding/supported-logs/gcp"><code>GCP.AuditLog</code></a></td></tr><tr><td>GitHub</td><td><a href="../data-onboarding/supported-logs/github"><code>GitHub.Audit</code></a></td></tr><tr><td>Okta</td><td><a href="../../data-onboarding/supported-logs/okta#okta.systemlog"><code>Okta.SystemLog</code></a></td></tr></tbody></table>

### EDR log sources

This tool can convert detections for endpoint events from certain EDR sources. These detections are applicable to logs generated in Windows, Mac, and Linux systems.

Currently, the following Sigma log source categories are supported:

* `process_creation`
* `file_event`
* `network_connection`

Note that for EDR sources, the value of the processing pipeline flag (`-p`) is unique to each source.

<table><thead><tr><th width="161">Source name</th><th width="287.728271484375">Supported Panther schema(s)</th><th width="328.6197509765625">-p flag value</th></tr></thead><tbody><tr><td>CrowdStrike</td><td><a href="../../data-onboarding/supported-logs/crowdstrike/falcon-data-replicator#crowdstrike.fdrevent"><code>Crowdstrike.FDREvent</code></a></td><td><code>crowdstrike_panther</code></td></tr><tr><td>Carbon Black</td><td><a href="../../data-onboarding/supported-logs/carbon-black#carbonblack.endpointevent"><code>CarbonBlack.EndpointEvent</code></a></td><td><code>carbon_black_panther</code></td></tr><tr><td>SentinelOne</td><td><a href="https://docs.panther.com/data-onboarding/supported-logs/sentinel-one"><code>SentinelOne.DeepVisibilityV2</code></a></td><td><code>sentinelone_panther</code></td></tr><tr><td>Windows Event</td><td><a href="../../data-onboarding/supported-logs/windows-event-logs#windows.eventlogs"><code>Windows.EventLogs</code></a></td><td>For Windows security logs: <code>windows_audit_panther</code><br><br>For Sysmon logs: <code>sysmon_panther</code><br><br>For other Windows log types, like PowerShell:<br><code>windows_logsource_panther</code></td></tr></tbody></table>

#### CrowdStrike example conversion command

```bash
sigma convert -s -t panther -p crowdstrike_panther path/to/rules -O output_dir=output/directory
```

## `sigma convert` flags

<table><thead><tr><th width="210">Long name</th><th width="108">Short flag</th><th width="234">Options</th><th>Description</th></tr></thead><tbody><tr><td><code>--target</code></td><td><code>-t</code></td><td><code>panther</code></td><td>The Sigma backend to use</td></tr><tr><td><code>--pipeline</code></td><td><code>-p</code></td><td><code>panther</code> (default): for <a href="#cloud-log-sources">cloud log sources</a><br><code>crowdstrike_panther</code><br><code>carbon_black_panther</code><br><code>sentinelone_panther</code></td><td>The log source pipeline to use</td></tr><tr><td><code>--format</code></td><td><code>-f</code></td><td><code>python</code> (default)<br><code>sdyaml</code></td><td>The output format of the converted rules</td></tr><tr><td><code>--skip-unsupported</code></td><td><code>-s</code></td><td>None</td><td>Using this flag is recommended when converting rules in bulk</td></tr><tr><td><code>--backend-option</code></td><td><code>-O</code></td><td><code>output_dir=...</code></td><td>The directory in which to save the converted rules</td></tr><tr><td><code>--help</code></td><td>None</td><td>None</td><td>View the help docs</td></tr></tbody></table>