Sigmac Usage Examples

README.md

@@ -67,7 +67,7 @@ Florian wrote a short [rule creation tutorial](https://www.nextron-systems.com/2
 1. Download or clone the respository
 2. Check the `./rules` sub directory for an overview on the rule base
 3. Run `python sigmac --help` in folder `./tools` to get a help on the rule converter
-4. Convert a rule of your choice with `sigmac` like `python sigmac -t splunk ../rules/windows/builtin/win_susp_process_creations.yml`
+4. Convert a rule of your choice with `sigmac` like `./sigmac -t splunk -c tools/config/generic/sysmon.yml ./rules/windows/process_creation/win_susp_whoami.yml`
 5. Convert a whole rule directory with `python sigmac -t splunk -r ../rules/proxy/`
 6. Check the `./tools/config` folder and the [wiki](https://github.com/Neo23x0/sigma/wiki/Converter-Tool-Sigmac) if you need custom field or log source mappings in your environment
 
@@ -96,7 +96,82 @@ Sigmac converts sigma rules into queries or inputs of the supported targets list
 Sigma library that may be used to integrate Sigma support in other projects. Further, there's `merge_sigma.py` which
 merges multiple YAML documents of a Sigma rule collection into simple Sigma rules.
 
-![sigmac_converter](./images/Sigmac-win_susp_rc4_kerberos.png)
+### Usage
+
+```
+usage: sigmac [-h] [--recurse] [--filter FILTER]
+              [--target {arcsight,es-qs,es-dsl,kibana,xpack-watcher,elastalert,graylog,logpoint,grep,netwitness,powershell,qradar,qualys,splunk,splunkxml,sumologic,fieldlist,wdatp}]
+              [--target-list] [--config CONFIG] [--output OUTPUT]
+              [--backend-option BACKEND_OPTION] [--defer-abort]
+              [--ignore-backend-errors] [--verbose] [--debug]
+              [inputs [inputs ...]]
+
+Convert Sigma rules into SIEM signatures.
+
+positional arguments:
+  inputs                Sigma input files ('-' for stdin)
+
+optional arguments:
+  -h, --help            show this help message and exit
+  --recurse, -r         Use directory as input (recurse into subdirectories is
+                        not implemented yet)
+  --filter FILTER, -f FILTER
+                        Define comma-separated filters that must match (AND-
+                        linked) to rule to be processed. Valid filters:
+                        level<=x, level>=x, level=x, status=y, logsource=z,
+                        tag=t. x is one of: low, medium, high, critical. y is
+                        one of: experimental, testing, stable. z is a word
+                        appearing in an arbitrary log source attribute. t is a
+                        tag that must appear in the rules tag list, case-
+                        insensitive matching. Multiple log source
+                        specifications are AND linked.
+  --target {arcsight,es-qs,es-dsl,kibana,xpack-watcher,elastalert,graylog,logpoint,grep,netwitness,powershell,qradar,qualys,splunk,splunkxml,sumologic,fieldlist,wdatp}, -t {arcsight,es-qs,es-dsl,kibana,xpack-watcher,elastalert,graylog,logpoint,grep,netwitness,powershell,qradar,qualys,splunk,splunkxml,sumologic,fieldlist,wdatp}
+                        Output target format
+  --target-list, -l     List available output target formats
+  --config CONFIG, -c CONFIG
+                        Configurations with field name and index mapping for
+                        target environment. Multiple configurations are merged
+                        into one. Last config is authorative in case of
+                        conflicts.
+  --output OUTPUT, -o OUTPUT
+                        Output file or filename prefix if multiple files are
+                        generated
+  --backend-option BACKEND_OPTION, -O BACKEND_OPTION
+                        Options and switches that are passed to the backend
+  --defer-abort, -d     Don't abort on parse or conversion errors, proceed
+                        with next rule. The exit code from the last error is
+                        returned
+  --ignore-backend-errors, -I
+                        Only return error codes for parse errors and ignore
+                        errors for rules that cause backend errors. Useful,
+                        when you want to get as much queries as possible.
+  --verbose, -v         Be verbose
+  --debug, -D           Debugging output
+```
+
+### Examples
+
+Translate a single rule
+```
+tools/sigmac -t splunk rules/windows/sysmon/sysmon_susp_image_load.yml
+```
+Translate a whole rule directory and ignore backend errors (`-I`) in rule conversion for the selected backend (`-t splunk`)
+```
+tools/sigmac -I -t splunk -r rules/windows/sysmon/
+```
+Apply your own config file (`-c ~/my-elk-winlogbeat.yml`) during conversion, which can contain you custom field and source mappings
+```
+tools/sigmac -t es-qs -c ~/my-elk-winlogbeat.yml -r rules/windows/sysmon
+```
+Use a config file for `process_creation` rules (`-r rules/windows/process_creation`) that instructs sigmac to create queries for a Sysmon log source (`-c tools/config/generic/sysmon.yml`) and the ElasticSearch target backend (`-t es-qs`) 
+```
+tools/sigmac -t es-qs -c tools/config/generic/sysmon.yml -r rules/windows/process_creation
+```
+Use a config file for a single `process_creation` rule (`./rules/windows/process_creation/win_susp_outlook.yml`) that instructs sigmac to create queries for process creation events generated in the Windows Security Eventlog (`-c tools/config/generic/windows-audit.yml`) and a Splunk target backend (`-t splunk`)
+```
+tools/sigmac -t splunk -c ~/my-splunk-mapping.yml -c tools/config/generic/windows-audit.yml ./rules/windows/process_creation/win_susp_outlook.yml
+```
+(See @blubbfiction's [blog post](https://patzke.org/a-guide-to-generic-log-sources-in-sigma.html) for more information)
 
 ### Supported Targets