| Name | sandwine JSON |
| Version |
4.3.0
JSON |
| download |
| home_page | None |
| Summary | Command-line tool to run Windows apps with Wine and bwrap/bubblewrap isolation |
| upload_time | 2024-10-27 23:13:52 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.9 |
| license | GPLv3+ |
| keywords |
wine
sandbox
sandboxing
bubblewrap
bwrap
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
[](https://github.com/pre-commit/pre-commit)
[](https://github.com/hartwork/sandwine/actions/workflows/run-tests.yml)
[](https://github.com/hartwork/sandwine/actions/workflows/pre-commit.yml)
[](https://github.com/hartwork/sandwine#threat-model-and-known-limitations)
# What is sandwine?
**sandwine** is a command-line tool to run Windows applications on GNU/Linux
that offers more isolation than raw [Wine](https://www.winehq.org/)
and more convenience than raw [bubblewrap](https://github.com/containers/bubblewrap).
It *uses* Wine and bubblewrap (>=0.8.0), it does not replace them.
**sandwine** is Software Libre written in Python 3, and
is licensed under the "GPL v3 or later" license.
# Installation
```console
# pip3 install sandwine
```
# Usage Examples
### Install Winamp 5.66: no networking, no X11, no sound, no access to `~/*` files
```
# cd ~/Downloads/
# sha256sum -c <(echo 'ac70a0c8a2928c91400b9ac3774b331f1d700f3486bab674dbd09da6b31fe130 winamp566_full_en-us.exe')
# WINEDEBUG=-all sandwine --dotwine winamp/:rw ./winamp566_full_en-us.exe /S /D='C:\Program' 'Files' '(x86)\Winamp' '5.66'
```
(The weird quoting in `/D='C:\Program' 'Files' '(x86)\Winamp' '5.66'`
is [documented behavior](https://nsis.sourceforge.io/Which_command_line_parameters_can_be_used_to_configure_installers%3F)
for NSIS.)
### Run installed Winamp: with sound, with nested X11, no networking, no `~/*` file access
```console
# sandwine --pulseaudio --x11 --dotwine winamp/:rw --pass ~/Music/:ro --configure -- winamp
```
Argument `--configure` will bring up `winecfg` prior to Winamp so that you have a chance at
unchecking these two boxes:
- `Graphics`:
- `Allow the window manage to *decorate* the windows`
- `Allow the window manage to *control* the windows`
If Winamp crashes right after showing the main window, run it once more,
there is some Wine bug at work here.
### Run Geiss Screensaver: with sound, with host X11 (careful!), no networking, no `~/*` file access
```console
sandwine --host-x11-danger-danger --pulseaudio --retry -- ./geiss.scr /S
```
`--host-x11-danger-danger` make sandwine talk to the host X11 server, which would
[expose you to keyloggers](https://blog.invisiblethings.org/2011/04/23/linux-security-circus-on-gui-isolation.html)
so please re-visit your threat model before using `--host-x11-danger-danger`.
`--retry` is used to start programs a second time that consistently
crash from graphics issues in a fresh Wine environment
the first but not the second time.
Potentially a bug in Wine, needs more investigation.
PS: The Geiss Screensaver has its GitHub home at https://github.com/geissomatik/geiss .
### Run wget: with networking, no X11, no sound, no access to `~/*` files
```console
# sandwine --network --no-wine -- wget -S -O/dev/null https://blog.hartwork.org/
```
Argument `--no-wine` is mostly intended for debugging,
but is needed here to invoke non-Wine wget.
# Under the Hood
**sandwine** aims to protect against Windows applications that:
- read and leak personal files through/to the Internet
- read and leak keystrokes from other running applications
([related post](https://blog.invisiblethings.org/2011/04/23/linux-security-circus-on-gui-isolation.html))
- modify/destroy personal files
- modify/destroy system files
To achieve that, by default the launched application:
- Sees no files in ``${HOME}`` and/or `/home/` (unless you pass `--pass PATH:{ro,rw}` for a related directory).
- Does not have access to the internet (unless you pass ``--network``).
- Does not have access to your local X11 server
(unless you enable some form of X11 integration, ideally nested X11).
- Does not have access to your sound card.
So what is shared with the application by default then?
## What is Exposed by Default?
### Files
| Path | Content |
| ---- | ------- |
| `/` | new tmpfs |
| `/bin` | read-only bind mount |
| `/dev` | new devtmpfs |
| `/dev/dri` | read-write bind mount with device access |
| `/etc` | read-only bind mount |
| `${HOME}` | new tmpfs |
| `${HOME}/.wine` | new tmpfs |
| `/lib` | read-only bind mount |
| `/lib32` | read-only bind mount |
| `/lib64` | read-only bind mount |
| `/proc` | new procfs |
| `/sys` | read-only bind mount |
| `/tmp` | new tmpfs |
| `/usr` | read-only bind mount |
### Environment Variables
- `${DISPLAY}`
- `${HOME}`
- `${HOSTNAME}` (with random 12-hex-digits value)
- `${PATH}` (with known-unavailable entries removed)
- `${TERM}`
- `${USER}`
**sandwine** features include:
- A focus on security, usability, transparency
- Support for nested X11 provided by:
- X2Go nxagent (seamless)
- Xephyr
- Xnest
- Xpra (experimental, careful!)
- Xvfb (invisible)
- Support for PulseAudio
- Support for `/etc/resolv.conf` provided by:
- NetworkManager
- systemd-resolved
# Threat Model and Known Limitations
- If your life depends on the sandbox, please consider using
a virtual machine rather than sandwine, e.g. because your username
is exposed to the running application and depending on your threat model,
that may be too much already.
- sandwine is not intended for use with known-malicious software, viruses, malware.
- sandwine has not seen any known external security audits, yet.
- sandwine relies on [bubblewrap](https://github.com/containers/bubblewrap)
for its security, so it can only be as secure as bubblewrap.
- sandwine does not limit the set of syscalls that the application can do.
bubblewrap supports arguments `--seccomp` and `--add-seccomp-fd` to go further
on that end, but sandwine does not use them so far.
- sandwine does not keep the application from using loads of RAM, CPU time and/or disk space.
If your concerns include **denial of service**, you need protection beyond sandwine.
- sandwine relies on sane file permissions in the places that are shared read-only.
If you have files in e.g. `/etc` that contain credentials but are readable by
unprivileged users, sandwine will do nothing to block that read access.
- If the Windows application to be run expects a GNU/Linux environment and includes
**Linux Kernel exploit** code, then that exploit is not likely to be stopped by sandwine.
- If you manually allow the sandboxed application to communicate with an unsandboxed application
and the latter executes commands for the former, then the sandbox cannot prevent privilege
escalation. Think of a model like the Docker daemon where whoever can talk to the Docker
daemon can become root. If you use sandwine with something like that, sandwine will have a problem.
- Start-up time below 200ms is not a goal.
# Reporting Vulnerabilities
If you think you found a vulnerability in sandwine,
please reach out [via e-mail](https://github.com/hartwork)
so we can have a closer look
and [coordinate disclosure](https://en.wikipedia.org/wiki/Coordinated_vulnerability_disclosure).
---
[Sebastian Pipping](https://github.com/hartwork), Berlin, 2023
Raw data
{
"_id": null,
"home_page": null,
"name": "sandwine",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": null,
"keywords": "Wine, sandbox, sandboxing, bubblewrap, bwrap",
"author": null,
"author_email": "Sebastian Pipping <sebastian@pipping.org>",
"download_url": "https://files.pythonhosted.org/packages/31/72/226cf5c9fa5c258806f3c6055bafaf34a12598bad0a75cd1dbb72d4ae1e3/sandwine-4.3.0.tar.gz",
"platform": null,
"description": "[](https://github.com/pre-commit/pre-commit)\n[](https://github.com/hartwork/sandwine/actions/workflows/run-tests.yml)\n[](https://github.com/hartwork/sandwine/actions/workflows/pre-commit.yml)\n\n[](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 (>=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 <(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",
"bugtrack_url": null,
"license": "GPLv3+",
"summary": "Command-line tool to run Windows apps with Wine and bwrap/bubblewrap isolation",
"version": "4.3.0",
"project_urls": {
"Bug Tracker": "https://github.com/hartwork/sandwine/issues",
"Homepage": "https://github.com/hartwork/sandwine"
},
"split_keywords": [
"wine",
" sandbox",
" sandboxing",
" bubblewrap",
" bwrap"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "0c476792339dd22942e5e9224b1448012b5780f1deb47b902877b809d8945cbe",
"md5": "5e6487626d8a446d1c18479bd4f70561",
"sha256": "764913799ee4ebd4daaec20a9ac4fdddf318a76e97f335baf4c3976fac5d78f8"
},
"downloads": -1,
"filename": "sandwine-4.3.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "5e6487626d8a446d1c18479bd4f70561",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 27003,
"upload_time": "2024-10-27T23:13:50",
"upload_time_iso_8601": "2024-10-27T23:13:50.519052Z",
"url": "https://files.pythonhosted.org/packages/0c/47/6792339dd22942e5e9224b1448012b5780f1deb47b902877b809d8945cbe/sandwine-4.3.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "3172226cf5c9fa5c258806f3c6055bafaf34a12598bad0a75cd1dbb72d4ae1e3",
"md5": "029a5be6ec8c015a833b2f3ef9b9894d",
"sha256": "be9f37bd0224241fd012cfac470843d044aa1e7d7ac634321ea63618450703eb"
},
"downloads": -1,
"filename": "sandwine-4.3.0.tar.gz",
"has_sig": false,
"md5_digest": "029a5be6ec8c015a833b2f3ef9b9894d",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 28025,
"upload_time": "2024-10-27T23:13:52",
"upload_time_iso_8601": "2024-10-27T23:13:52.330617Z",
"url": "https://files.pythonhosted.org/packages/31/72/226cf5c9fa5c258806f3c6055bafaf34a12598bad0a75cd1dbb72d4ae1e3/sandwine-4.3.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-10-27 23:13:52",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "hartwork",
"github_project": "sandwine",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "sandwine"
}
