Skip to content

README: rewrite for discoverability; add MIT license #3

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
SecClay merged 2 commits into from
Oct 16, 2026
Merged

README: rewrite for discoverability; add MIT license #3

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
b6d5099
README: rewrite for discoverability and cover Linux
claude Oct 16, 2026
7280a69
Add MIT license
claude Oct 16, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
21 changes: 21 additions & 0 deletions LICENSE
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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.
95 changes: 62 additions & 33 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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.
2 changes: 2 additions & 0 deletions THIRD_PARTY.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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`.
Loading