https://github.com/ind4skylivey/winewarden
Play Windows games on Linux without trusting random executables with your system.
https://github.com/ind4skylivey/winewarden
gaming heroic linux lutris proton rust sandbox security wine wine-proton
Last synced: 7 months ago
JSON representation
Play Windows games on Linux without trusting random executables with your system.
- Host: GitHub
- URL: https://github.com/ind4skylivey/winewarden
- Owner: ind4skylivey
- License: mit
- Created: 2025-12-22T01:05:42.000Z (7 months ago)
- Default Branch: main
- Last Pushed: 2025-12-22T01:40:45.000Z (7 months ago)
- Last Synced: 2025-12-23T12:57:00.462Z (7 months ago)
- Topics: gaming, heroic, linux, lutris, proton, rust, sandbox, security, wine, wine-proton
- Language: Rust
- Homepage:
- Size: 1.33 MB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
- Security: SECURITY.md
Awesome Lists containing this project
README
# WineWarden
"Play Windows games on Linux without trusting random executables with your system."
WineWarden is a calm, always-on protection layer for Wine, Proton, Lutris, and Steam. It is not an antivirus. It does not moralize. It exists so you can play without anxiety.
```
==[ W I N E W A R D E N ]===================================================
calm by design · silent by default · strict by choice
===========================================================================
```
## What It Is
- Active Enforcement: Landlock sandboxing and Seccomp syscall interception
- WineWarden Mode: silent protection with no prompts during gameplay
- Trust Tiers: clear reassurance signals (Green, Yellow, Red)
- Sacred Zones: protect the places games should never need
- Prefix Hygiene: keep prefixes clean and stable over time
- Network Safety: observe without breaking multiplayer
- Pirate-Safe Mode: stronger isolation with zero judgment
- Human Reports: short, calm summaries after each run
## Why It Feels Different
- Secure by default
- Easy to relax
- Hard to break accidentally
- No popups mid-game
- No shame, no fear
## Active Protection & Requirements
WineWarden now enforces security actively using kernel-level features:
- **Landlock LSM:** Creates a strict filesystem sandbox, blocking access to your personal files (`$HOME`, `.ssh`, etc.) unless explicitly allowed.
- **Seccomp User Notification:** Intercepts network calls (`connect`, `bind`) in real-time, allowing the Policy Engine to decide based on destination IP/Port.
### System Requirements
- **Linux Kernel 5.11+** (Required for Landlock and Seccomp Notify)
- **libseccomp** development headers:
- Debian/Ubuntu: `sudo apt install libseccomp-dev`
- Fedora: `sudo dnf install libseccomp-devel`
- Arch: `sudo pacman -S libseccomp`
## Installation
```bash
# 1. Build from source
cargo build --release
# 2. Install binaries
cargo install --path crates/winewarden-cli
cargo install --path crates/winewarden-daemon
```
## Quick Start
```bash
# Initialize config
winewarden init
# Run a game quietly (no prompts during gameplay)
winewarden run /path/to/game.exe -- -arg1 -arg2
# Run with a provided event log (JSONL of AccessAttempt)
winewarden run /path/to/game.exe --event-log tests/fixtures/events.jsonl --no-run
# View a report
winewarden report --input ~/.local/share/winewarden/reports/.json
```
## Interactive Guide (Full Tour)
[+] 1) Install from source
```bash
cargo build --release
cargo install --path crates/winewarden-cli
cargo install --path crates/winewarden-daemon
```
```
Tip: use a dedicated Rust toolchain for reproducible builds.
```
[+] 2) Initialize config
```bash
winewarden init
```
Config file lives at: `~/.config/winewarden/config.toml`
```
Config path: ~/.config/winewarden/config.toml
Reports: ~/.local/share/winewarden/reports/
```
[+] 3) Run a game (direct)
```bash
winewarden run /path/to/game.exe -- -arg1 -arg2
```
```
No prompts during gameplay. Summary after exit.
```
[+] 4) Run via daemon (background mode)
```bash
winewarden daemon start
winewarden run --daemon /path/to/game.exe -- -arg1 -arg2
winewarden daemon status
```
```
Daemon uses a local Unix socket with user-only access.
```
[+] 5) Live monitoring (optional)
```bash
# All live monitors
winewarden run --live /path/to/game.exe -- -arg1 -arg2
# Or pick specific channels
winewarden run --live-fs --live-proc --live-net --poll-ms 250 /path/to/game.exe -- -arg1
```
```
Live monitoring observes only; it does not interrupt gameplay.
```
[+] 6) Trust tiers (pin or relax)
```bash
# Inspect trust tier for an executable
winewarden trust get /path/to/game.exe
# Pin a tier
winewarden trust set /path/to/game.exe green
```
```
Green = known safe behavior
Yellow = unknown but non-hostile
Red = strict isolation
```
[+] 7) Prefix hygiene
```bash
winewarden prefix scan /path/to/prefix
winewarden prefix snapshot /path/to/prefix
```
```
Prefix hygiene keeps the ecosystem stable over time.
```
[+] 8) Reports (human + JSON)
```bash
winewarden report --input ~/.local/share/winewarden/reports/.json
winewarden report --input ~/.local/share/winewarden/reports/.json --json
```
```
Human summaries by default. Structured JSON on demand.
```
[+] 9) Integration snippets (real paths)
```bash
# Steam (Launch Options):
winewarden run -- %command%
# Steam (example Windows game path):
~/.steam/steam/steamapps/common/SomeGame/SomeGame.exe
# Proton prefix (example, for reference only):
~/.steam/steam/steamapps/compatdata/123456/pfx/drive_c/
# Lutris (example prefix and game path):
~/.local/share/lutris/runners/wine/wine-ge-8-26-x86_64
~/Games/SomeGame/drive_c/Program Files/SomeGame/SomeGame.exe
# Heroic (example default install path):
~/Games/Heroic/SomeGame/SomeGame.exe
```
See:
- `integrations/steam/README.md`
- `integrations/lutris/README.md`
- `integrations/heroic/README.md`
[+] 10) Profiles (default / relaxed / pirate-safe)
Copy one of the presets into your config location:
```bash
cp config/default.toml ~/.config/winewarden/config.toml
# or
cp config/relaxed.toml ~/.config/winewarden/config.toml
# or
cp config/pirate-safe.toml ~/.config/winewarden/config.toml
```
## Flow Maps (Mini Diagrams)
```
Execution Flow
-------------
winewarden run
|
v
[Runner] --> [Monitor] --> [Policy Engine] --> [Reporting]
| | |
v v v
Prefix Manager Live Watch Trust Tiers
```
```
Decision Flow
-------------
Access Attempt
|
v
Sacred Zone? ---> yes ---> Deny / Redirect / Virtualize
|
no
|
v
Inside Prefix? ---> no ---> Deny
|
yes
|
v
Allow + Log
```
## Daemon Mode
```bash
# Start the background daemon
winewarden daemon start
# Run a game through the daemon
winewarden run --daemon /path/to/game.exe -- -arg1 -arg2
# Check daemon health
winewarden daemon ping
```
## Architecture (Separation of Concerns)
- Policy Engine: decisions only
- Monitor: observation without interruption
- Runner: safe command construction
- Prefix Manager: hygiene, snapshots, quarantine
- Reporting: human summaries and JSON
- WineWarden Daemon: background scheduling
```
[Runner] → [Monitor] → [Policy Engine] → [Reporting]
↘ ↘ ↘ ↘
[Prefix Manager] [Trust Tiers] [Human Reports]
```
## Configuration
Configuration is TOML and readable by design. See:
- `config/default.toml`
- `config/relaxed.toml`
- `config/pirate-safe.toml`
Variables supported:
- `${HOME}`
- `${DATA_DIR}`
- `${CONFIG_DIR}`
## Reports (Human First)
Examples of the tone you should expect:
- "This game tried to access files outside its sandbox."
- "That access was denied."
- "Your system remains intact."
## Documentation
- [docs/vision.md](docs/vision.md)
- [docs/threat-model.md](docs/threat-model.md)
- [docs/winewarden-mode.md](docs/winewarden-mode.md)
- [docs/trust-tiers.md](docs/trust-tiers.md)
- [docs/sacred-zones.md](docs/sacred-zones.md)
- [docs/prefix-hygiene.md](docs/prefix-hygiene.md)
- [docs/networking.md](docs/networking.md)
- [docs/pirate-safe-mode.md](docs/pirate-safe-mode.md)
- [docs/reports.md](docs/reports.md)
- [docs/configuration.md](docs/configuration.md)
- [docs/architecture.md](docs/architecture.md)
- [docs/glossary.md](docs/glossary.md)
## Status
The foundation is solid. Active enforcement hooks (Landlock and Seccomp) are implemented and integrated into the monitor layer, providing real protection without changing the calm user experience.