From b6d50997249abd9585a8bed80cdc2a2591bd402b Mon Sep 17 00:00:00 2001 From: Claude Date: Fri, 16 Oct 2026 01:48:58 +0000 Subject: [PATCH 1/2] README: rewrite for discoverability and cover Linux Lead with what the project does and who it is for, use the terms people search for (Sysmon, auditd, PowerShell script block logging, DFIR, detection engineering, air-gapped), add a Windows/Linux comparison table, CI badge, tested matrix with explicit gaps, and related projects. Co-Authored-By: Claude Sonnet 5.5 --- README.md | 91 +++++++++++++++++++++++++++++++++++-------------------- 1 file changed, 58 insertions(+), 33 deletions(-) diff --git a/README.md b/README.md index 937f7a8..4f09ce6 100644 --- a/README.md +++ b/README.md @@ -1,45 +1,70 @@ -# 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 and their licenses: [THIRD_PARTY.md](THIRD_PARTY.md). + +## 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. From 7280a699b3ed1de8341d36fc955f8baea5a75901 Mon Sep 17 00:00:00 2001 From: Claude Date: Fri, 16 Oct 2026 01:52:47 +0000 Subject: [PATCH 2/2] Add MIT license Co-Authored-By: Claude Sonnet 5.5 --- LICENSE | 21 +++++++++++++++++++++ README.md | 6 +++++- THIRD_PARTY.md | 2 ++ 3 files changed, 28 insertions(+), 1 deletion(-) create mode 100644 LICENSE 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 4f09ce6..a109587 100644 --- a/README.md +++ b/README.md @@ -63,7 +63,11 @@ Maintained logging guidance and tools worth knowing, and what inspired this one: - [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 and their licenses: [THIRD_PARTY.md](THIRD_PARTY.md). +Bundled third-party files keep their own licenses: [THIRD_PARTY.md](THIRD_PARTY.md). + +## License + +[MIT](LICENSE) for the WinLogs scripts and docs. ## Disclaimer 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`.