diff --git a/LICENSE b/LICENSE new file mode 100644 index 0000000..7bd5b44 --- /dev/null +++ b/LICENSE @@ -0,0 +1,21 @@ +MIT License + +Copyright (c) 2016-2026 SecClay + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. diff --git a/README.md b/README.md index 937f7a8..a109587 100644 --- a/README.md +++ b/README.md @@ -1,45 +1,74 @@ -# WinLogs +# WinLogs: one-command logging setup for malware analysis and detection labs -Quick, disposable-lab logging setup for malware detonation and security-control validation. -Windows is done; Linux and macOS are planned on the same model. +[![test](https://github.com/SecClay/WinLogs/actions/workflows/test.yml/badge.svg)](https://github.com/SecClay/WinLogs/actions/workflows/test.yml) -> Use on throwaway lab machines only. It turns on very verbose logging. +WinLogs turns on the telemetry you want **before** you detonate malware, validate a security control, or run a detection-engineering exercise: Windows audit policy, PowerShell Script Block / Module / Transcription logging, Sysmon, `auditd`, and persistent `journald`. One script per OS, safe to re-run, fully revertable, and usable on air-gapped lab machines. -## Supported -Windows 10, Windows 11, Windows Server 2022/2025. Windows PowerShell 5.1 or PowerShell 7, run as Administrator. -Older systems are no longer supported. The previous Windows 10 TH2 / LGPO script is in git history. +Built for disposable VMs: malware analysis sandboxes, DFIR and threat-hunting practice, Sigma rule testing, purple-team and blue-team labs. **Do not run it on production or work machines.** It turns on very verbose logging. -## Use +## Quick start + +**Windows 10 / 11 / Server 2022 / 2025** (elevated PowerShell 5.1 or 7): ```powershell -.\windows\Install-WinLogs.ps1 # asks for confirmation, then applies everything -.\windows\Install-WinLogs.ps1 -WhatIf # show what would change -.\windows\Install-WinLogs.ps1 -Revert # undo +.\windows\Install-WinLogs.ps1 # asks for confirmation, then applies everything +.\windows\Install-WinLogs.ps1 -WhatIf # preview +.\windows\Install-WinLogs.ps1 -Revert # undo +``` + +**Linux** (Debian/Ubuntu/Kali, RHEL/Fedora/Rocky/Alma, openSUSE, Arch; as root): +```bash +sudo ./linux/install.sh # asks for confirmation, then applies everything +sudo ./linux/install.sh --dry-run # preview +sudo ./linux/install.sh --revert # undo ``` -Options: `-SkipSysmon`, `-SysmonConfigPath`, `-SysmonSha256`, `-LogSizeMB`, `-Force`, `-OfflinePath`. + +## What you get + +| | Windows | Linux | +|---|---|---| +| Audit policy | Advanced audit policy via `auditpol` (logon, account and group management, process creation 4688 with command line, object access, policy change, DPAPI, SAM, ...) plus a Server profile (Kerberos, Directory Service) | `auditd` with the [Neo23x0 ruleset](https://github.com/Neo23x0/auditd): exec, file, network, privilege and persistence rules | +| Scripting visibility | PowerShell Script Block (4104), Module (4103) and Transcription logging for Windows PowerShell and PowerShell 7 | Interactive bash commands logged to syslog | +| Process / network / DNS / file telemetry | **Sysmon** with the [sysmon-modular](https://github.com/olafhartong/sysmon-modular) config (on by default) | `auditd` execve rules; **Sysmon for Linux** is opt-in with `--with-sysmon` | +| Retention | Event logs raised to 1 GB for Security, Sysmon and PowerShell; Task Scheduler, DNS-Client and more channels enabled | `auditd` keeps 10 x 200 MB with synchronous writes; `journald` persistent with rate limiting off | +| Object auditing | Per-object audit rules (SACLs) on persistence and tamper-prone registry keys and folders | n/a (covered by `auditd` watches) | +| Undo | `-Revert` | `--revert` | + +Details and event IDs: [docs/what-gets-logged.md](docs/what-gets-logged.md). ## Air-gapped labs -Sysmon is not redistributable, so fetch it once on a connected machine: + +Sysmon is Microsoft software that this repo does not redistribute, and lab machines often have no internet. Fetch what you need once on a connected machine, carry the folder in, and install offline: + ```powershell -.\windows\Prepare-Offline.ps1 -OutPath E:\winlogs-offline -# copy the repo and that folder to the lab, then +.\windows\Prepare-Offline.ps1 -OutPath E:\winlogs-offline # Sysmon, signature + SHA-256 checked .\windows\Install-WinLogs.ps1 -OfflinePath E:\winlogs-offline ``` -The bundle is checked against Microsoft's signature and a SHA-256 manifest. +```bash +sudo ./linux/prepare-offline.sh ./winlogs-offline # run on a machine matching the lab image +sudo ./linux/install.sh --offline-dir ./winlogs-offline # verified against SHA256SUMS +``` -## What you get -See [docs/what-gets-logged.md](docs/what-gets-logged.md). Third-party licenses: [THIRD_PARTY.md](THIRD_PARTY.md). - -## Status -The Windows scripts parse cleanly but have **not been run on Windows yet**. Treat the first run as a test in a snapshot-able VM. -Not yet done: Linux, macOS, using the built-in Sysmon on Windows 11 / Server 2025, optional log forwarding. - -## Resources -Original inspiration (older: the core Windows cheat sheet is Feb 2019, the Sysmon one Jan 2020): -- https://www.malwarearchaeology.com/cheat-sheets -- https://www.log-md.com/ - -Newer / maintained: -- https://github.com/olafhartong/sysmon-modular (the Sysmon config bundled here, MIT) -- https://github.com/Yamato-Security/EnableWindowsLogSettings (audit/log settings aimed at Sigma coverage; GPL-3.0, so referenced rather than bundled) -- https://learn.microsoft.com/windows-server/administration/windows-commands/sysmon (Microsoft's Sysmon docs, including the built-in Windows 11 feature) -- https://learn.microsoft.com/windows/security/threat-protection/auditing/advanced-security-auditing (advanced audit policy reference) +## Tested + +CI runs the full install, verify-events and revert cycle on Windows Server 2022 and 2025 (Windows PowerShell 5.1 and PowerShell 7), Windows 11 on ARM64, and Ubuntu 22.04 and 24.04. The Fedora job runs in a container, so it covers package install, config and revert but not live auditing. + +Not yet tested: Windows 10 and x64 Windows 11 client builds, a real domain controller, RHEL-family live auditing (Rocky/Alma), Debian, Kali, openSUSE, Arch, and Sysmon for Linux. Treat the first run as a test inside a snapshot-able VM. macOS is planned. + +## Related projects + +Maintained logging guidance and tools worth knowing, and what inspired this one: +- [Yamato-Security/EnableWindowsLogSettings](https://github.com/Yamato-Security/EnableWindowsLogSettings): Windows log settings aimed at Sigma coverage +- [olafhartong/sysmon-modular](https://github.com/olafhartong/sysmon-modular): modular Sysmon configs +- [Neo23x0/auditd](https://github.com/Neo23x0/auditd): best-practice auditd rules +- [Malware Archaeology logging cheat sheets](https://www.malwarearchaeology.com/cheat-sheets) and [Log-MD](https://www.log-md.com/): the original inspiration (the core Windows sheet dates from 2019) +- [Microsoft Sysmon documentation](https://learn.microsoft.com/windows-server/administration/windows-commands/sysmon) and [advanced security auditing](https://learn.microsoft.com/windows/security/threat-protection/auditing/advanced-security-auditing) + +Bundled third-party files keep their own licenses: [THIRD_PARTY.md](THIRD_PARTY.md). + +## License + +[MIT](LICENSE) for the WinLogs scripts and docs. + +## Disclaimer + +Built to set up temporary systems that will run hostile software. It works for the author's labs; test it in yours before trusting it. No warranty. diff --git a/THIRD_PARTY.md b/THIRD_PARTY.md index 88bf454..84763aa 100644 --- a/THIRD_PARTY.md +++ b/THIRD_PARTY.md @@ -7,3 +7,5 @@ Rule for this repo: only bundle what the license clearly allows, and keep each license text next to the file. Anything else is fetched by the user, with a signature or SHA-256 check. + +The WinLogs scripts and docs themselves are MIT licensed; see `LICENSE`.