vastlimits/uberAgent-ESA-Sysmon-Converter

# uberAgent-ESA-Sysmon-Converter ## Table of Contents - [Platforms](#platforms) - [Getting Started](#getting-started) - [Syntax](#syntax) - [Example](#example) - [Limitations](#limitations) - [License](#license) ## Platforms uberAgent-ESA-Sysmon-Converter is developed in .NET 8 and, therefore, platform-independent. ## Getting Started ### Download 1. The latest binary archive can be found [here](https://github.com/vastlimits/uberAgent-ESA-Sysmon-Converter/releases/tag/v1.2.1). 2. After unpacking, the converter can be controlled via the command line. ### Converting Further information at [Syntax](#syntax). ### After converting After the converter has run successfully, the following file is created in the output directory. 1. `uberAgent-ESA-am-converted.conf` All supported rules are serialized to `uberAgent-ESA-am-converted.conf`. For more information about the setup of uberAgent, see the documentation about [Threat Detection Engine](https://uberagent.com/docs/uberagent/latest/esa-features-configuration/threat-detection-engine/). ## Syntax To convert all rules from one or more files, use the following command: vl.Sysmon.Converter --input filePath1 filePath2 --output outputFolder To convert one or more specific Sysmon rules: vl.Sysmon.Converter --input filePath1 filePath2 --output outputFolder --rule 1 2 12 The default risk score of the resulting uberAgent rules is 50. It can be overridden on the command line: vl.Sysmon.Converter --input filePath1 filePath2 --output outputFolder --rule 1 2 12 --score 75 ### Target uberAgent version If no uberAgent version is specified, the latest supported uberAgent version is assumed. To convert to an older uberAgent version, specify it on the command line: vl.Sysmon.Converter --input filePath1 filePath2 --output outputFolder --rule 1 2 12 --score 75 --version 6.1 A shorter notation of the above: vl.Sysmon.Converter -i filePath1 -o outputFolder -r 1 2 12 -s 75 -v 6.1 #### Supported uberAgent versions - 6.0 - 6.1 - 6.2 - 7.0 - 7.1 - 7.2 - 7.3 - 7.4 - 7.5 - 8.0 Unknown version values are logged as warnings and fall back to the latest supported release. ### Validation The solution contains an xUnit test project that covers the converter semantics that are easiest to regress: - Sysmon include/exclude precedence. - Default Sysmon field semantics (`or` for repeated fields, `and` across different fields). - Nested `` / `` parentheses. - Repeated event elements inside one `` and sysmon-modular event wrapper files. - `OriginalFileName` stage-one mapping. - Version parsing for current uberAgent releases. Run the validation suite with: dotnet test vl.Sysmon.Converter.sln ## Example A **ProcessCreate** excerpt from the [Sysmon configuration of SwiftOnSecurity](https://github.com/SwiftOnSecurity/sysmon-config): C:\Windows\System32\RuntimeBroker.exe -Embedding C:\Program Files (x86)\Common Files\microsoft shared\ink\TabTip32.exe AppContainer %%SystemRoot%%\system32\csrss.exe ObjectDirectory=\Windows C:\windows\system32\wermgr.exe -queuereporting C:\Windows\system32\SearchIndexer.exe C:\Windows\system32\svchost.exe -k appmodel -s StateRepository C:\Windows\system32\svchost.exe -k wsappx C:\Windows\system32\svchost.exe -k netsvcs C:\Windows\system32\svchost.exe -k localSystemNetworkRestricted C:\Windows\system32\deviceenroller.exe /c /AutoEnrollMDM "C:\Program Files (x86)\Microsoft\Edge Dev\Application\msedge.exe" --type= C:\Windows\Microsoft.NET\Framework\v4.0.30319\ngen.exe C:\WINDOWS\Microsoft.NET\Framework64\v4.0.30319\Ngen.exe C:\Windows\Microsoft.NET\Framework64\v4.0.30319\mscorsvw.exe C:\Windows\Microsoft.NET\Framework\v4.0.30319\mscorsvw.exe C:\Windows\Microsoft.Net\Framework64\v3.0\WPF\PresentationFontCache.exe C:\Windows\Microsoft.NET\Framework64\v4.0.30319\ngentask.exe C:\Windows\Microsoft.NET\Framework64\v4.0.30319\mscorsvw.exe C:\Windows\Microsoft.NET\Framework64\v4.0.30319\ngentask.exe C:\Windows\Microsoft.NET\Framework\v4.0.30319\mscorsvw.exe C:\Windows\Microsoft.NET\Framework\v4.0.30319\ngentask.exe C:\Program Files\Microsoft Office\Office16\MSOSYNC.EXE C:\Program Files (x86)\Microsoft Office\Office16\MSOSYNC.EXE C:\Program Files\Common Files\Microsoft Shared\ClickToRun\OfficeC2RClient.exe C:\Program Files\Common Files\Microsoft Shared\ClickToRun\OfficeClickToRun.exe C:\Program Files\Common Files\Microsoft Shared\ClickToRun\OfficeC2RClient.exe C:\Program Files\Windows Media Player\wmpnscfg.exe "C:\Program Files (x86)\Google\Chrome\Application\chrome.exe" --type= "C:\Program Files\Google\Chrome\Application\chrome.exe" --type= After executing the command `vl.Sysmon.Converter -i C:\tmp\example.xml -o C:\tmp\exampleOutput\` you should see **uberAgent-ESA-am-converted.conf** containing an `[ActivityMonitoringRule]` stanza. The converter preserves Sysmon's include/exclude and group-relation semantics and emits escaped uAQL string literals. [ActivityMonitoringRule] RuleName = ProcessStart converted rule EventType = Process.Start Tag = processstart-1-converted-rule RiskScore = 50 Query = not (Process.CommandLine == "C:\\Windows\\System32\\RuntimeBroker.exe -Embedding" or ...) ## Limitations ### Sysmon event IDs The following Sysmon event IDs are not yet supported by uberAgent and are ignored during conversion: - 10: ProcessAccess - 19: WMI filter - 20: WMI consumer - 21: WMI consumer filter - 23: FileDelete - Not fully supported and treated as `ID: 26 - File Delete Logged`. - 24: ClipboardChange - 27: File Block Executable - 28: File Block Shredding - 29: File Executable Detected ### Sysmon fields The following Sysmon fields are not yet supported by uberAgent and are ignored during conversion: - Archived - Contents - CurrentDirectory - Description - Device - Guid - Initiated - IntegrityLevel - LogonGuid - LogonId - Product - SourceProcessGuid - TargetProcessGuid - SourceImage - UtcTime - QueryStatus `OriginalFileName` is supported as stage-one mapping. Until uberAgent exposes a dedicated `OriginalFileName` property, the converter maps it to the corresponding process or image name field. ### Rule names Sysmon rule group names are converted to uberAgent rule names. The names of Sysmon rules that are part of a rule group are not converted. #### Example Sysmon rule fragement: Converted uberAgent rule stanza: [ActivityMonitoringRule] RuleName = ExampleRule EventType = Process.Start Tag = examplerule RiskScore = 100 Query = true ## License Apache License 2.0. ### Third-party code This project uses the following third-party libraries: - [CommandLineParser](https://github.com/commandlineparser/commandline) - [Serilog](https://serilog.net/) - [xUnit](https://xunit.net/) for tests