{"id":17665458,"url":"https://github.com/hartwork/sandwine","last_synced_at":"2025-04-05T19:12:26.576Z","repository":{"id":83858457,"uuid":"606505520","full_name":"hartwork/sandwine","owner":"hartwork","description":":wine_glass: Command-line tool to run Windows apps with Wine and bwrap/bubblewrap isolation on Linux","archived":false,"fork":false,"pushed_at":"2024-10-21T22:47:18.000Z","size":135,"stargazers_count":75,"open_issues_count":8,"forks_count":5,"subscribers_count":4,"default_branch":"main","last_synced_at":"2024-10-25T13:50:25.958Z","etag":null,"topics":["bubblewrap","bubblewrap-wrap","bwrap","gplv3-licensing","nxagent","pulseaudio","python","python-3","python3","sandbox","sandbox-environment","sandboxing","winamp","windows","wine","x11","x2go","xephyr","xnest"],"latest_commit_sha":null,"homepage":"https://pypi.org/project/sandwine/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/hartwork.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"COPYING","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-02-25T17:38:09.000Z","updated_at":"2024-10-24T13:49:20.000Z","dependencies_parsed_at":null,"dependency_job_id":"fddc220b-de59-4aeb-b2ec-5100fddadcb2","html_url":"https://github.com/hartwork/sandwine","commit_stats":{"total_commits":48,"total_committers":1,"mean_commits":48.0,"dds":0.0,"last_synced_commit":"008b37ba55ef463f5dc0ad5dea8b138f8de5f705"},"previous_names":[],"tags_count":12,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hartwork%2Fsandwine","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hartwork%2Fsandwine/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hartwork%2Fsandwine/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hartwork%2Fsandwine/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/hartwork","download_url":"https://codeload.github.com/hartwork/sandwine/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247386265,"owners_count":20930619,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["bubblewrap","bubblewrap-wrap","bwrap","gplv3-licensing","nxagent","pulseaudio","python","python-3","python3","sandbox","sandbox-environment","sandboxing","winamp","windows","wine","x11","x2go","xephyr","xnest"],"created_at":"2024-10-23T21:01:28.504Z","updated_at":"2025-04-05T19:12:26.554Z","avatar_url":"https://github.com/hartwork.png","language":"Python","funding_links":[],"categories":["Python"],"sub_categories":[],"readme":"[![pre-commit](https://img.shields.io/badge/pre--commit-enabled-brightgreen?logo=pre-commit)](https://github.com/pre-commit/pre-commit)\n[![Run the test suite](https://github.com/hartwork/sandwine/actions/workflows/run-tests.yml/badge.svg)](https://github.com/hartwork/sandwine/actions/workflows/run-tests.yml)\n[![Run pre-commit](https://github.com/hartwork/sandwine/actions/workflows/pre-commit.yml/badge.svg)](https://github.com/hartwork/sandwine/actions/workflows/pre-commit.yml)\n\n[![sandwine_threat_model.png](https://raw.githubusercontent.com/hartwork/sandwine/main/sandwine_threat_model.png)](https://github.com/hartwork/sandwine#threat-model-and-known-limitations)\n\n\n# What is sandwine?\n\n**sandwine** is a command-line tool to run Windows applications on GNU/Linux\nthat offers more isolation than raw [Wine](https://www.winehq.org/)\nand more convenience than raw [bubblewrap](https://github.com/containers/bubblewrap).\nIt *uses* Wine and bubblewrap (\u003e=0.8.0), it does not replace them.\n**sandwine** is Software Libre written in Python 3, and\nis licensed under the \"GPL v3 or later\" license.\n\n\n# Installation\n\n```console\n# pip3 install sandwine\n```\n\n\n# Usage Examples\n\n\n### Install Winamp 5.66: no networking, no X11, no sound, no access to `~/*` files\n\n```\n# cd ~/Downloads/\n# sha256sum -c \u003c(echo 'ac70a0c8a2928c91400b9ac3774b331f1d700f3486bab674dbd09da6b31fe130  winamp566_full_en-us.exe')\n# WINEDEBUG=-all sandwine --dotwine winamp/:rw ./winamp566_full_en-us.exe /S /D='C:\\Program' 'Files' '(x86)\\Winamp' '5.66'\n```\n\n(The weird quoting in `/D='C:\\Program' 'Files' '(x86)\\Winamp' '5.66'`\nis [documented behavior](https://nsis.sourceforge.io/Which_command_line_parameters_can_be_used_to_configure_installers%3F)\nfor NSIS.)\n\n\n### Run installed Winamp: with sound, with nested X11, no networking, no `~/*` file access\n\n```console\n# sandwine --pulseaudio --x11 --dotwine winamp/:rw --pass ~/Music/:ro --configure -- winamp\n```\n\nArgument `--configure` will bring up `winecfg` prior to Winamp so that you have a chance at\nunchecking these two boxes:\n\n- `Graphics`:\n    - `Allow the window manage to *decorate* the windows`\n    - `Allow the window manage to *control* the windows`\n\nIf Winamp crashes right after showing the main window, run it once more,\nthere is some Wine bug at work here.\n\n\n### Run Geiss Screensaver: with sound, with host X11 (careful!), no networking, no `~/*` file access\n\n```console\nsandwine --host-x11-danger-danger --pulseaudio --retry -- ./geiss.scr /S\n```\n\n`--host-x11-danger-danger` make sandwine talk to the host X11 server, which would\n[expose you to keyloggers](https://blog.invisiblethings.org/2011/04/23/linux-security-circus-on-gui-isolation.html)\nso please re-visit your threat model before using `--host-x11-danger-danger`.\n\n`--retry` is used to start programs a second time that consistently\ncrash from graphics issues in a fresh Wine environment\nthe first but not the second time.\nPotentially a bug in Wine, needs more investigation.\n\nPS: The Geiss Screensaver has its GitHub home at https://github.com/geissomatik/geiss .\n\n\n### Run wget: with networking, no X11, no sound, no access to `~/*` files\n\n```console\n# sandwine --network --no-wine -- wget -S -O/dev/null https://blog.hartwork.org/\n```\n\nArgument `--no-wine` is mostly intended for debugging,\nbut is needed here to invoke non-Wine wget.\n\n\n# Under the Hood\n\n**sandwine** aims to protect against Windows applications that:\n\n- read and leak personal files through/to the Internet\n- read and leak keystrokes from other running applications\n  ([related post](https://blog.invisiblethings.org/2011/04/23/linux-security-circus-on-gui-isolation.html))\n- modify/destroy personal files\n- modify/destroy system files\n\nTo achieve that, by default the launched application:\n\n- Sees no files in ``${HOME}`` and/or `/home/` (unless you pass `--pass PATH:{ro,rw}` for a related directory).\n- Does not have access to the internet (unless you pass ``--network``).\n- Does not have access to your local X11 server\n  (unless you enable some form of X11 integration, ideally nested X11).\n- Does not have access to your sound card.\n\nSo what is shared with the application by default then?\n\n\n## What is Exposed by Default?\n\n\n### Files\n\n| Path | Content |\n| ---- | ------- |\n| `/` | new tmpfs |\n| `/bin` | read-only bind mount |\n| `/dev` | new devtmpfs |\n| `/dev/dri` | read-write bind mount with device access |\n| `/etc` | read-only bind mount |\n| `${HOME}` | new tmpfs |\n| `${HOME}/.wine` | new tmpfs |\n| `/lib` | read-only bind mount |\n| `/lib32` | read-only bind mount |\n| `/lib64` | read-only bind mount |\n| `/proc` | new procfs |\n| `/sys` | read-only bind mount |\n| `/tmp` | new tmpfs |\n| `/usr` | read-only bind mount |\n\n\n### Environment Variables\n\n- `${DISPLAY}`\n- `${HOME}`\n- `${HOSTNAME}` (with random 12-hex-digits value)\n- `${PATH}` (with known-unavailable entries removed)\n- `${TERM}`\n- `${USER}`\n\n\n**sandwine** features include:\n\n- A focus on security, usability, transparency\n- Support for nested X11 provided by:\n  - X2Go nxagent (seamless)\n  - Xephyr\n  - Xnest\n  - Xpra (experimental, careful!)\n  - Xvfb (invisible)\n- Support for PulseAudio\n- Support for `/etc/resolv.conf` provided by:\n  - NetworkManager\n  - systemd-resolved\n\n\n# Threat Model and Known Limitations\n\n- If your life depends on the sandbox, please consider using\n  a virtual machine rather than sandwine, e.g. because your username\n  is exposed to the running application and depending on your threat model,\n  that may be too much already.\n- sandwine is not intended for use with known-malicious software, viruses, malware.\n- sandwine has not seen any known external security audits, yet.\n- sandwine relies on [bubblewrap](https://github.com/containers/bubblewrap)\n  for its security, so it can only be as secure as bubblewrap.\n- sandwine does not limit the set of syscalls that the application can do.\n  bubblewrap supports arguments `--seccomp` and `--add-seccomp-fd` to go further\n  on that end, but sandwine does not use them so far.\n- sandwine does not keep the application from using loads of RAM, CPU time and/or disk space.\n  If your concerns include **denial of service**, you need protection beyond sandwine.\n- sandwine relies on sane file permissions in the places that are shared read-only.\n  If you have files in e.g. `/etc` that contain credentials but are readable by\n  unprivileged users, sandwine will do nothing to block that read access.\n- If the Windows application to be run expects a GNU/Linux environment and includes\n  **Linux Kernel exploit** code, then that exploit is not likely to be stopped by sandwine.\n- If you manually allow the sandboxed application to communicate with an unsandboxed application\n  and the latter executes commands for the former, then the sandbox cannot prevent privilege\n  escalation.  Think of a model like the Docker daemon where whoever can talk to the Docker\n  daemon can become root. If you use sandwine with something like that, sandwine will have a problem.\n- Start-up time below 200ms is not a goal.\n\n\n# Reporting Vulnerabilities\n\nIf you think you found a vulnerability in sandwine,\nplease reach out [via e-mail](https://github.com/hartwork)\nso we can have a closer look\nand [coordinate disclosure](https://en.wikipedia.org/wiki/Coordinated_vulnerability_disclosure).\n\n---\n[Sebastian Pipping](https://github.com/hartwork), Berlin, 2023\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhartwork%2Fsandwine","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhartwork%2Fsandwine","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhartwork%2Fsandwine/lists"}