appjail 0.2.2__tar.gz → 0.3.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Potentially problematic release.


This version of appjail might be problematic. Click here for more details.

Files changed (57) hide show
  1. {appjail-0.2.2 → appjail-0.3.0}/PKG-INFO +58 -31
  2. {appjail-0.2.2 → appjail-0.3.0}/README.md +56 -30
  3. {appjail-0.2.2 → appjail-0.3.0}/pyproject.toml +4 -0
  4. {appjail-0.2.2 → appjail-0.3.0}/src/appjail/catalog.py +1 -1
  5. {appjail-0.2.2 → appjail-0.3.0}/src/appjail/cli.py +5 -5
  6. {appjail-0.2.2 → appjail-0.3.0}/src/appjail/cmd_add.py +2 -2
  7. {appjail-0.2.2 → appjail-0.3.0}/src/appjail/cmd_addimage.py +3 -3
  8. {appjail-0.2.2 → appjail-0.3.0}/src/appjail/cmd_apps.py +21 -13
  9. {appjail-0.2.2 → appjail-0.3.0}/src/appjail/cmd_index.py +36 -29
  10. {appjail-0.2.2 → appjail-0.3.0}/src/appjail/dbusproxy.py +10 -6
  11. {appjail-0.2.2 → appjail-0.3.0}/src/appjail/desktop.py +69 -0
  12. {appjail-0.2.2 → appjail-0.3.0}/src/appjail/github.py +9 -0
  13. {appjail-0.2.2 → appjail-0.3.0}/src/appjail/grants.py +15 -1
  14. appjail-0.3.0/src/appjail/gui/__init__.py +50 -0
  15. appjail-0.3.0/src/appjail/gui/__main__.py +8 -0
  16. appjail-0.3.0/src/appjail/gui/app.py +460 -0
  17. appjail-0.3.0/src/appjail/gui/appjail.svg +16 -0
  18. appjail-0.3.0/src/appjail/gui/apps.py +47 -0
  19. appjail-0.3.0/src/appjail/gui/argv.py +134 -0
  20. appjail-0.3.0/src/appjail/gui/console.py +60 -0
  21. appjail-0.3.0/src/appjail/gui/dialogs.py +257 -0
  22. appjail-0.3.0/src/appjail/gui/worker.py +53 -0
  23. {appjail-0.2.2 → appjail-0.3.0}/src/appjail/history.py +1 -2
  24. {appjail-0.2.2 → appjail-0.3.0}/src/appjail/indexstore.py +19 -14
  25. {appjail-0.2.2 → appjail-0.3.0}/src/appjail/jail.py +31 -18
  26. appjail-0.3.0/src/appjail/landlock.py +87 -0
  27. {appjail-0.2.2 → appjail-0.3.0}/src/appjail/permargs.py +6 -4
  28. {appjail-0.2.2 → appjail-0.3.0}/src/appjail/portal.py +41 -13
  29. {appjail-0.2.2 → appjail-0.3.0}/src/appjail/runner.py +6 -0
  30. {appjail-0.2.2 → appjail-0.3.0}/src/appjail/runtimejail.py +5 -4
  31. {appjail-0.2.2 → appjail-0.3.0}/src/appjail/seccomp.py +28 -3
  32. {appjail-0.2.2 → appjail-0.3.0}/src/appjail/textsafe.py +1 -1
  33. appjail-0.2.2/src/appjail/amsource.py +0 -171
  34. {appjail-0.2.2 → appjail-0.3.0}/.gitignore +0 -0
  35. {appjail-0.2.2 → appjail-0.3.0}/LICENSES/MPL-2.0.txt +0 -0
  36. {appjail-0.2.2 → appjail-0.3.0}/REUSE.toml +0 -0
  37. {appjail-0.2.2 → appjail-0.3.0}/src/appjail/__init__.py +0 -0
  38. {appjail-0.2.2 → appjail-0.3.0}/src/appjail/__main__.py +0 -0
  39. {appjail-0.2.2 → appjail-0.3.0}/src/appjail/appimage.py +0 -0
  40. {appjail-0.2.2 → appjail-0.3.0}/src/appjail/attest.py +0 -0
  41. {appjail-0.2.2 → appjail-0.3.0}/src/appjail/cmd_desktop.py +0 -0
  42. {appjail-0.2.2 → appjail-0.3.0}/src/appjail/cmd_open.py +0 -0
  43. {appjail-0.2.2 → appjail-0.3.0}/src/appjail/cmd_portals.py +0 -0
  44. {appjail-0.2.2 → appjail-0.3.0}/src/appjail/cmd_update.py +0 -0
  45. {appjail-0.2.2 → appjail-0.3.0}/src/appjail/cmd_updateimage.py +0 -0
  46. {appjail-0.2.2 → appjail-0.3.0}/src/appjail/console.py +0 -0
  47. {appjail-0.2.2 → appjail-0.3.0}/src/appjail/fetcher.py +0 -0
  48. {appjail-0.2.2 → appjail-0.3.0}/src/appjail/imagesrc.py +0 -0
  49. {appjail-0.2.2 → appjail-0.3.0}/src/appjail/index.py +0 -0
  50. {appjail-0.2.2 → appjail-0.3.0}/src/appjail/manifest.py +0 -0
  51. {appjail-0.2.2 → appjail-0.3.0}/src/appjail/services.py +0 -0
  52. {appjail-0.2.2 → appjail-0.3.0}/src/appjail/snappy.py +0 -0
  53. {appjail-0.2.2 → appjail-0.3.0}/src/appjail/store.py +0 -0
  54. {appjail-0.2.2 → appjail-0.3.0}/src/appjail/tools.py +0 -0
  55. {appjail-0.2.2 → appjail-0.3.0}/src/appjail/updater.py +0 -0
  56. {appjail-0.2.2 → appjail-0.3.0}/src/appjail/valid.py +0 -0
  57. {appjail-0.2.2 → appjail-0.3.0}/src/appjail/wayland.py +0 -0
@@ -1,10 +1,11 @@
1
1
  Metadata-Version: 2.5
2
2
  Name: appjail
3
- Version: 0.2.2
3
+ Version: 0.3.0
4
4
  Summary: Sandboxed AppImage manager built on bubblewrap
5
5
  License-Expression: MPL-2.0
6
6
  License-File: LICENSES/MPL-2.0.txt
7
7
  Classifier: Environment :: Console
8
+ Classifier: Environment :: X11 Applications
8
9
  Classifier: Operating System :: POSIX :: Linux
9
10
  Classifier: Programming Language :: Python :: 3
10
11
  Classifier: Topic :: Security
@@ -44,8 +45,8 @@ is built around the opposite assumptions:
44
45
  app is fetched from, whatever an AppImage's embedded update information says.
45
46
  - **Downloads are jailed.** The download, the extraction and the verification tools run in throwaway sandboxes
46
47
  with only the access they need (a private network namespace for downloads, none for extraction).
47
- - **Everything is denied by default.** An app starts with a private home and a restricted Wayland socket. Network,
48
- directories, D-Bus names, portals and the rest are explicit grants you can inspect and change.
48
+ - **Everything is denied by default.** An app starts with a private home, a restricted Wayland socket, audio and the
49
+ GPU. Network, directories, D-Bus names, portals and the rest are explicit grants you can inspect and change.
49
50
  - **Updates are reviewed.** A new release waits in quarantine (7 days by default), is shown to you as a diff, and
50
51
  is blocked outright if its evidence gets weaker or the repository changes owner.
51
52
 
@@ -61,7 +62,11 @@ is built around the opposite assumptions:
61
62
  the download jails a private network namespace; without it they use the host network and print a warning.
62
63
  - `xdg-dbus-proxy`: D-Bus filtering and portals.
63
64
  - `xwayland`: X11-only apps.
64
- - `git`: the search index (`index update`) and the manifest history.
65
+ - `git`: the manifest history.
66
+ - Linux 6.12 or later with Landlock (both supported systems have it): apps with `network_host`, which are
67
+ refused without it.
68
+ - A Pulse server (`pipewire-pulse` on PipeWire systems, or PulseAudio): audio. PipeWire's own socket is never used.
69
+ - Optional: `python3-tk` for the window (`appjail-gui`, see [Graphical interface](#graphical-interface)).
65
70
  - A Wayland compositor for GUI apps. The host X11 socket is never shared.
66
71
 
67
72
  On Debian or Ubuntu:
@@ -88,10 +93,11 @@ cd appjail
88
93
  pipx install . # or: pip install --user .
89
94
  ```
90
95
 
91
- To try it without installing, run it from the clone: `PYTHONPATH=src python3 -m appjail --help`.
92
- appjail never updates itself: upgrade with `pipx upgrade appjail` (or `git pull` and reinstall) after reading what changed.
93
- `appjail version` (or `--version`) prints the installed version, which comes from the git tag at build time (`0.2.0` on a
94
- release, `0.2.1.dev4+g1a2b3c4` four commits after it) and is `unknown` when run from a source tree that is not installed.
96
+ To try it without installing, run it from the clone: `PYTHONPATH=src python3 -m appjail --help`. appjail never
97
+ updates itself: upgrade with `pipx upgrade appjail` (or `git pull` and reinstall) after reading what changed.
98
+ `appjail version` (or `--version`) prints the installed version, which comes from the git tag at build time (`0.2.0`
99
+ on a release, `0.2.1.dev4+g1a2b3c4` four commits after it) and is `unknown` when run from a source tree that is not
100
+ installed.
95
101
 
96
102
  Data lives in `~/.local/share/appjail` (images, extracted trees, private homes, staging) and `~/.config/appjail`
97
103
  (manifests, tracked in a small local git repository). `APPJAIL_DATA_DIR` and `APPJAIL_CONFIG_DIR` override them.
@@ -106,9 +112,21 @@ appjail update # check every app for a newer release
106
112
  appjail remove lagrange # delete the app and its private home
107
113
  ```
108
114
 
109
- `remove` and `perms` ask for confirmation unless given `--yes`. `appjail COMMAND --help` lists every option.
115
+ Commands that change or delete something ask first; `remove`, `perms`, `portals` and `desktop` accept `--yes`.
116
+ `appjail COMMAND --help` lists every option.
110
117
  `GITHUB_TOKEN`, if set, raises the GitHub API rate limit; it is only ever sent to `api.github.com`.
111
118
 
119
+ ## Graphical interface
120
+
121
+ `appjail-gui` opens a window with the same commands and options: the installed apps (run, run with extra access
122
+ for one run, open a file, update, permissions, portals, history, menu entry, remove), adding an app, searching the
123
+ catalogs and the helper tools. It runs the CLI underneath, so it shows the same reviews and asks the same questions
124
+ (the default answer is always No) in dialogs. It needs the system package `python3-tk` (`sudo apt install python3-tk`)
125
+ and a display.
126
+
127
+ `appjail-gui --desktop` adds appjail to your application menu, with its icon; `appjail-gui --remove-desktop` takes it
128
+ out again. Only a menu entry created that way is ever replaced or deleted.
129
+
112
130
  ## Installing apps
113
131
 
114
132
  **From a GitHub release.** `appjail add owner/repo` shows the repository owner, account age, stars and fork or archive
@@ -158,23 +176,23 @@ appjail portals lagrange --revoke-all # take those grants bac
158
176
  | Permission | Effect |
159
177
  |---|---|
160
178
  | `network` | Outbound internet through a private network namespace made by `pasta`. The app cannot reach services on your machine's localhost or its own addresses. Needs `passt`; without it the app is refused rather than put on the host network. |
161
- | `network_host` | The host's own network, including localhost services (`--allow network_host`, which implies `network`). For apps that really need them. |
162
- | `audio`, `gpu` | On by default; `--no-audio` and `--no-gpu` at `add` time, or `--deny` later. Audio includes the microphone. |
179
+ | `network_host` | The host's own network, including localhost services (`--allow network_host`, which implies `network`). For apps that really need them. Landlock (Linux 6.12 or later) keeps the app off the host's abstract unix sockets, such as the X server's; without it the permission is refused. |
180
+ | `audio`, `gpu` | On by default; `--no-audio` and `--no-gpu` at `add` time, or `--deny` later. Audio (the Pulse socket) includes the microphone. |
163
181
  | `portals` | The safe set of desktop portals; privileged ones are listed per app with `--add-portal`. |
164
182
  | `userns` | Nested user namespaces (Chromium and Electron sandboxes). Weakens isolation, off by default. |
165
- | `dirs` | Directories mapped into the private home (`--dir` / `--add-dir`). Credentials, browser profiles, shell startup files and system trees are refused. |
183
+ | `dirs` | Directories mapped into the private home (`--dir` / `--add-dir`). Credentials, browser profiles, shell startup files, system trees, `/tmp` and `/var/tmp` (other programs' sockets live there) are refused. |
166
184
  | `dbus_filter`, `dbus_own` | Session-bus names the app may talk to (`--dbus`) or own (`--dbus-own`), through `xdg-dbus-proxy`. Desktop namespaces are refused. |
167
185
  | `display` | `wayland` (default) or `xwayland`. |
168
186
 
169
- **Temporary grants.** `run APP --dir PATH[:ro|:rw]` and `run APP --file PATH[:rw]` grant access for that run only and are never
170
- saved. `--file` makes just that one file visible, not the rest of its directory, and appends its path inside the sandbox to
171
- the app's arguments. Credentials, browser profiles and the like are refused as for directories, and shell startup files are
172
- never writable. Apps that save by writing a temporary file and renaming it fail on `:rw`. For a standing grant use a
173
- directory, or the portal file chooser.
187
+ **Temporary grants.** `run APP --dir PATH[:ro|:rw]` and `run APP --file PATH[:rw]` grant access for that run only and
188
+ are never saved. `--file` makes just that one file visible, not the rest of its directory, and appends its path inside
189
+ the sandbox to the app's arguments. Credentials, browser profiles and the like are refused as for directories, and
190
+ shell startup files are never writable. Apps that save by writing a temporary file and renaming it fail on `:rw`. For
191
+ a standing grant use a directory, or the portal file chooser.
174
192
 
175
193
  Every sandbox also drops all capabilities, has its own PID, IPC and UTS namespaces, a read-only system, a minimal
176
- `/dev`, a generated `/etc/passwd`, and a seccomp filter. The extracted app tree is hashed and checked at every
177
- launch.
194
+ `/dev`, a generated `/etc/passwd` and a seccomp filter. Outside `pasta`'s private network, Landlock also keeps it off
195
+ abstract unix sockets created outside the sandbox. The extracted app tree is hashed and checked at every launch.
178
196
 
179
197
  ## Menu entry and opening files
180
198
 
@@ -234,20 +252,22 @@ text, and never runs anything from them.
234
252
  ```sh
235
253
  appjail index update # refresh every catalog: fetch, show what changed, ask before accepting
236
254
  appjail index status # the sources, their revisions and update times
237
- appjail index rollback [NAME] # back to the previous catalog of a source (default: am)
255
+ appjail index rollback [NAME] # back to the previous catalog of a source (default: appjail-db)
238
256
  appjail index add mine --url https://example.org/apps.json # another catalog (https; fetched in the jail)
239
257
  appjail index add local --file ~/apps.json # or a local file
240
- appjail index update mine # refresh one source (--commit SHA is for am only)
258
+ appjail index update mine # refresh one source (--commit SHA is for appjail-db only)
241
259
  appjail index remove mine
242
260
  appjail search editor # all sources; with several, each hit shows its source in brackets
243
261
  ```
244
262
 
245
263
  `search` shows 20 results; use `--limit N` or `--all` for more.
246
264
 
247
- **Sources.** The built-in `am` source is the [AM](https://github.com/ivan-hc/AM) application list: `index update` fetches
248
- its repository in a network-only jail (only the list and the install scripts, no hooks or submodules), reads
249
- each script as text to find the `SITE=` line, and keeps the result as a catalog. The scripts themselves are not
250
- kept. Sources you add yourself provide a catalog directly. Every update shows the number of apps, the apps added and
265
+ **Sources.** The built-in `appjail-db` source is the catalog of the sister project
266
+ [appjail-db](https://github.com/alberto743/appjail-db), rebuilt weekly from the [AM](https://github.com/ivan-hc/AM)
267
+ application list. `index update` asks the GitHub API for the latest commit of that repository, downloads its
268
+ `catalog.json` at that commit in a network-only jail and records the commit, so a catalog can be traced to an exact
269
+ state of appjail-db; `index update appjail-db --commit SHA` fetches a chosen commit instead. The catalog is not signed:
270
+ what protects you is HTTPS, the strict parser and the review below. Sources you add yourself provide a catalog directly. Every update shows the number of apps, the apps added and
251
271
  removed, and every app whose repository changed, with a loud warning when the owner changed, and asks before it
252
272
  replaces the catalog. One previous catalog is kept per source for `index rollback`; sources are stored in
253
273
  `~/.local/share/appjail/index/`.
@@ -304,9 +324,10 @@ owner change.
304
324
  | `remove APP` | Delete the app and its private home. |
305
325
  | `history [APP]` | Recorded changes to the manifests. |
306
326
  | `search WORDS` | Suggestions from the catalogs. |
307
- | `index add\|remove\|update\|rollback\|status` | Manage the catalogs `search` reads (the built-in AM list and any you add). |
327
+ | `index add\|remove\|update\|rollback\|status` | Manage the catalogs `search` reads (the built-in appjail-db list and any you add). |
308
328
  | `tools status\|install NAME` | Helper binaries whose URL, size and hash are pinned in appjail's source (`gh` for attestations, `dwarfs` for DwarFS-based AppImages). |
309
329
  | `version` | The installed version. |
330
+ | `appjail-gui` (separate command) | The window; see [Graphical interface](#graphical-interface). |
310
331
 
311
332
  ## Troubleshooting
312
333
 
@@ -315,6 +336,7 @@ owner change.
315
336
  | bwrap fails with `Operation not permitted` or `setting up uid map: Permission denied` | Unprivileged user namespaces are blocked. On Ubuntu, AppArmor can restrict them (`kernel.apparmor_restrict_unprivileged_userns`); the project's CI relaxes it with `sudo sysctl -w kernel.apparmor_restrict_unprivileged_userns=0`. That changes a system-wide protection, so decide for yourself whether to do it, or give bubblewrap its own AppArmor profile. |
316
337
  | `no usable Wayland session` or `Wayland socket not found` | `run` needs a Wayland compositor and `WAYLAND_DISPLAY`/`XDG_RUNTIME_DIR` in the environment (not available over a plain ssh login). Apps that only speak X11 use `perms APP --display xwayland` (needs `xwayland`). |
317
338
  | An app with `network` is refused, naming `passt` | Install `passt`; the app is never put on the host network silently. |
339
+ | An app with `network_host` is refused, naming Landlock | The kernel lacks Landlock ABI 6 (Linux 6.12 or later, with Landlock enabled). Use `network` instead, which keeps the app in a private network namespace. |
318
340
  | `GitHub API rate limit reached` | Unauthenticated requests are limited to 60 per hour per address. Set `GITHUB_TOKEN`. |
319
341
  | `unsquashfs is not installed` | Install `squashfs-tools`, or accept the offer to run the AppImage's own extractor in a jail with no network. |
320
342
  | DwarFS-based AppImage | `appjail tools install dwarfs` fetches the pinned helper. |
@@ -333,7 +355,11 @@ owner change.
333
355
  only seen by a full download.
334
356
  - A sandboxed app can still do whatever its grants allow. An app with `network` can reach other machines on your LAN.
335
357
  - Granting a directory, a portal or a D-Bus name widens what a compromised app can do.
336
- - The audio permission includes the microphone.
358
+ - The audio permission includes the microphone. It is Pulse only (served by `pipewire-pulse` on PipeWire systems):
359
+ PipeWire's own socket would also expose cameras and screen casts, so apps that speak only native PipeWire get no
360
+ audio.
361
+ - Inside the jail only unix, internet and netlink sockets exist (no Bluetooth sockets, for example), and `io_uring`
362
+ is unavailable; apps that depend on them fail or fall back.
337
363
  - x86-64 only. The GNOME and KDE portal backends have not been tested (the GTK backend and a real X11-only AppImage
338
364
  have, under headless weston; the portal dialogs themselves are not driven). Real internet IPv6 under `pasta` is
339
365
  untested; IPv6 forwarding is tested in a fake network.
@@ -341,13 +367,14 @@ owner change.
341
367
  with SIGKILL, an app with `network` is stopped about a second later by a watcher inside its network namespace (a
342
368
  small empty directory `appjail-life-*` stays in the runtime directory).
343
369
 
344
- The full design is in [DESIGN.md](DESIGN.md); the reasoning behind each choice, rejected alternatives and deferred features are in [DECISIONS.md](DECISIONS.md).
370
+ The full design is in [DESIGN.md](DESIGN.md); the reasoning behind each choice, rejected alternatives and deferred
371
+ features are in [DECISIONS.md](DECISIONS.md).
345
372
 
346
373
  ## Development
347
374
 
348
- The code is stdlib-only Python under `src/appjail/`; tests are plain `pytest`. Many tests start real sandboxes and need a Linux
349
- machine with bubblewrap, `unsquashfs`, `pasta`, a headless Wayland compositor (`weston`) and the other packages in
350
- `tests/vm/packages.txt`.
375
+ The code is stdlib-only Python under `src/appjail/`; tests are plain `pytest`. Many tests start real sandboxes and
376
+ need a Linux machine with bubblewrap, `unsquashfs`, `pasta`, a headless Wayland compositor (`weston`) and the other
377
+ packages in `tests/vm/packages.txt`.
351
378
 
352
379
  ```sh
353
380
  APPJAIL_INTEGRATION=1 python3 -m pytest
@@ -30,8 +30,8 @@ is built around the opposite assumptions:
30
30
  app is fetched from, whatever an AppImage's embedded update information says.
31
31
  - **Downloads are jailed.** The download, the extraction and the verification tools run in throwaway sandboxes
32
32
  with only the access they need (a private network namespace for downloads, none for extraction).
33
- - **Everything is denied by default.** An app starts with a private home and a restricted Wayland socket. Network,
34
- directories, D-Bus names, portals and the rest are explicit grants you can inspect and change.
33
+ - **Everything is denied by default.** An app starts with a private home, a restricted Wayland socket, audio and the
34
+ GPU. Network, directories, D-Bus names, portals and the rest are explicit grants you can inspect and change.
35
35
  - **Updates are reviewed.** A new release waits in quarantine (7 days by default), is shown to you as a diff, and
36
36
  is blocked outright if its evidence gets weaker or the repository changes owner.
37
37
 
@@ -47,7 +47,11 @@ is built around the opposite assumptions:
47
47
  the download jails a private network namespace; without it they use the host network and print a warning.
48
48
  - `xdg-dbus-proxy`: D-Bus filtering and portals.
49
49
  - `xwayland`: X11-only apps.
50
- - `git`: the search index (`index update`) and the manifest history.
50
+ - `git`: the manifest history.
51
+ - Linux 6.12 or later with Landlock (both supported systems have it): apps with `network_host`, which are
52
+ refused without it.
53
+ - A Pulse server (`pipewire-pulse` on PipeWire systems, or PulseAudio): audio. PipeWire's own socket is never used.
54
+ - Optional: `python3-tk` for the window (`appjail-gui`, see [Graphical interface](#graphical-interface)).
51
55
  - A Wayland compositor for GUI apps. The host X11 socket is never shared.
52
56
 
53
57
  On Debian or Ubuntu:
@@ -74,10 +78,11 @@ cd appjail
74
78
  pipx install . # or: pip install --user .
75
79
  ```
76
80
 
77
- To try it without installing, run it from the clone: `PYTHONPATH=src python3 -m appjail --help`.
78
- appjail never updates itself: upgrade with `pipx upgrade appjail` (or `git pull` and reinstall) after reading what changed.
79
- `appjail version` (or `--version`) prints the installed version, which comes from the git tag at build time (`0.2.0` on a
80
- release, `0.2.1.dev4+g1a2b3c4` four commits after it) and is `unknown` when run from a source tree that is not installed.
81
+ To try it without installing, run it from the clone: `PYTHONPATH=src python3 -m appjail --help`. appjail never
82
+ updates itself: upgrade with `pipx upgrade appjail` (or `git pull` and reinstall) after reading what changed.
83
+ `appjail version` (or `--version`) prints the installed version, which comes from the git tag at build time (`0.2.0`
84
+ on a release, `0.2.1.dev4+g1a2b3c4` four commits after it) and is `unknown` when run from a source tree that is not
85
+ installed.
81
86
 
82
87
  Data lives in `~/.local/share/appjail` (images, extracted trees, private homes, staging) and `~/.config/appjail`
83
88
  (manifests, tracked in a small local git repository). `APPJAIL_DATA_DIR` and `APPJAIL_CONFIG_DIR` override them.
@@ -92,9 +97,21 @@ appjail update # check every app for a newer release
92
97
  appjail remove lagrange # delete the app and its private home
93
98
  ```
94
99
 
95
- `remove` and `perms` ask for confirmation unless given `--yes`. `appjail COMMAND --help` lists every option.
100
+ Commands that change or delete something ask first; `remove`, `perms`, `portals` and `desktop` accept `--yes`.
101
+ `appjail COMMAND --help` lists every option.
96
102
  `GITHUB_TOKEN`, if set, raises the GitHub API rate limit; it is only ever sent to `api.github.com`.
97
103
 
104
+ ## Graphical interface
105
+
106
+ `appjail-gui` opens a window with the same commands and options: the installed apps (run, run with extra access
107
+ for one run, open a file, update, permissions, portals, history, menu entry, remove), adding an app, searching the
108
+ catalogs and the helper tools. It runs the CLI underneath, so it shows the same reviews and asks the same questions
109
+ (the default answer is always No) in dialogs. It needs the system package `python3-tk` (`sudo apt install python3-tk`)
110
+ and a display.
111
+
112
+ `appjail-gui --desktop` adds appjail to your application menu, with its icon; `appjail-gui --remove-desktop` takes it
113
+ out again. Only a menu entry created that way is ever replaced or deleted.
114
+
98
115
  ## Installing apps
99
116
 
100
117
  **From a GitHub release.** `appjail add owner/repo` shows the repository owner, account age, stars and fork or archive
@@ -144,23 +161,23 @@ appjail portals lagrange --revoke-all # take those grants bac
144
161
  | Permission | Effect |
145
162
  |---|---|
146
163
  | `network` | Outbound internet through a private network namespace made by `pasta`. The app cannot reach services on your machine's localhost or its own addresses. Needs `passt`; without it the app is refused rather than put on the host network. |
147
- | `network_host` | The host's own network, including localhost services (`--allow network_host`, which implies `network`). For apps that really need them. |
148
- | `audio`, `gpu` | On by default; `--no-audio` and `--no-gpu` at `add` time, or `--deny` later. Audio includes the microphone. |
164
+ | `network_host` | The host's own network, including localhost services (`--allow network_host`, which implies `network`). For apps that really need them. Landlock (Linux 6.12 or later) keeps the app off the host's abstract unix sockets, such as the X server's; without it the permission is refused. |
165
+ | `audio`, `gpu` | On by default; `--no-audio` and `--no-gpu` at `add` time, or `--deny` later. Audio (the Pulse socket) includes the microphone. |
149
166
  | `portals` | The safe set of desktop portals; privileged ones are listed per app with `--add-portal`. |
150
167
  | `userns` | Nested user namespaces (Chromium and Electron sandboxes). Weakens isolation, off by default. |
151
- | `dirs` | Directories mapped into the private home (`--dir` / `--add-dir`). Credentials, browser profiles, shell startup files and system trees are refused. |
168
+ | `dirs` | Directories mapped into the private home (`--dir` / `--add-dir`). Credentials, browser profiles, shell startup files, system trees, `/tmp` and `/var/tmp` (other programs' sockets live there) are refused. |
152
169
  | `dbus_filter`, `dbus_own` | Session-bus names the app may talk to (`--dbus`) or own (`--dbus-own`), through `xdg-dbus-proxy`. Desktop namespaces are refused. |
153
170
  | `display` | `wayland` (default) or `xwayland`. |
154
171
 
155
- **Temporary grants.** `run APP --dir PATH[:ro|:rw]` and `run APP --file PATH[:rw]` grant access for that run only and are never
156
- saved. `--file` makes just that one file visible, not the rest of its directory, and appends its path inside the sandbox to
157
- the app's arguments. Credentials, browser profiles and the like are refused as for directories, and shell startup files are
158
- never writable. Apps that save by writing a temporary file and renaming it fail on `:rw`. For a standing grant use a
159
- directory, or the portal file chooser.
172
+ **Temporary grants.** `run APP --dir PATH[:ro|:rw]` and `run APP --file PATH[:rw]` grant access for that run only and
173
+ are never saved. `--file` makes just that one file visible, not the rest of its directory, and appends its path inside
174
+ the sandbox to the app's arguments. Credentials, browser profiles and the like are refused as for directories, and
175
+ shell startup files are never writable. Apps that save by writing a temporary file and renaming it fail on `:rw`. For
176
+ a standing grant use a directory, or the portal file chooser.
160
177
 
161
178
  Every sandbox also drops all capabilities, has its own PID, IPC and UTS namespaces, a read-only system, a minimal
162
- `/dev`, a generated `/etc/passwd`, and a seccomp filter. The extracted app tree is hashed and checked at every
163
- launch.
179
+ `/dev`, a generated `/etc/passwd` and a seccomp filter. Outside `pasta`'s private network, Landlock also keeps it off
180
+ abstract unix sockets created outside the sandbox. The extracted app tree is hashed and checked at every launch.
164
181
 
165
182
  ## Menu entry and opening files
166
183
 
@@ -220,20 +237,22 @@ text, and never runs anything from them.
220
237
  ```sh
221
238
  appjail index update # refresh every catalog: fetch, show what changed, ask before accepting
222
239
  appjail index status # the sources, their revisions and update times
223
- appjail index rollback [NAME] # back to the previous catalog of a source (default: am)
240
+ appjail index rollback [NAME] # back to the previous catalog of a source (default: appjail-db)
224
241
  appjail index add mine --url https://example.org/apps.json # another catalog (https; fetched in the jail)
225
242
  appjail index add local --file ~/apps.json # or a local file
226
- appjail index update mine # refresh one source (--commit SHA is for am only)
243
+ appjail index update mine # refresh one source (--commit SHA is for appjail-db only)
227
244
  appjail index remove mine
228
245
  appjail search editor # all sources; with several, each hit shows its source in brackets
229
246
  ```
230
247
 
231
248
  `search` shows 20 results; use `--limit N` or `--all` for more.
232
249
 
233
- **Sources.** The built-in `am` source is the [AM](https://github.com/ivan-hc/AM) application list: `index update` fetches
234
- its repository in a network-only jail (only the list and the install scripts, no hooks or submodules), reads
235
- each script as text to find the `SITE=` line, and keeps the result as a catalog. The scripts themselves are not
236
- kept. Sources you add yourself provide a catalog directly. Every update shows the number of apps, the apps added and
250
+ **Sources.** The built-in `appjail-db` source is the catalog of the sister project
251
+ [appjail-db](https://github.com/alberto743/appjail-db), rebuilt weekly from the [AM](https://github.com/ivan-hc/AM)
252
+ application list. `index update` asks the GitHub API for the latest commit of that repository, downloads its
253
+ `catalog.json` at that commit in a network-only jail and records the commit, so a catalog can be traced to an exact
254
+ state of appjail-db; `index update appjail-db --commit SHA` fetches a chosen commit instead. The catalog is not signed:
255
+ what protects you is HTTPS, the strict parser and the review below. Sources you add yourself provide a catalog directly. Every update shows the number of apps, the apps added and
237
256
  removed, and every app whose repository changed, with a loud warning when the owner changed, and asks before it
238
257
  replaces the catalog. One previous catalog is kept per source for `index rollback`; sources are stored in
239
258
  `~/.local/share/appjail/index/`.
@@ -290,9 +309,10 @@ owner change.
290
309
  | `remove APP` | Delete the app and its private home. |
291
310
  | `history [APP]` | Recorded changes to the manifests. |
292
311
  | `search WORDS` | Suggestions from the catalogs. |
293
- | `index add\|remove\|update\|rollback\|status` | Manage the catalogs `search` reads (the built-in AM list and any you add). |
312
+ | `index add\|remove\|update\|rollback\|status` | Manage the catalogs `search` reads (the built-in appjail-db list and any you add). |
294
313
  | `tools status\|install NAME` | Helper binaries whose URL, size and hash are pinned in appjail's source (`gh` for attestations, `dwarfs` for DwarFS-based AppImages). |
295
314
  | `version` | The installed version. |
315
+ | `appjail-gui` (separate command) | The window; see [Graphical interface](#graphical-interface). |
296
316
 
297
317
  ## Troubleshooting
298
318
 
@@ -301,6 +321,7 @@ owner change.
301
321
  | bwrap fails with `Operation not permitted` or `setting up uid map: Permission denied` | Unprivileged user namespaces are blocked. On Ubuntu, AppArmor can restrict them (`kernel.apparmor_restrict_unprivileged_userns`); the project's CI relaxes it with `sudo sysctl -w kernel.apparmor_restrict_unprivileged_userns=0`. That changes a system-wide protection, so decide for yourself whether to do it, or give bubblewrap its own AppArmor profile. |
302
322
  | `no usable Wayland session` or `Wayland socket not found` | `run` needs a Wayland compositor and `WAYLAND_DISPLAY`/`XDG_RUNTIME_DIR` in the environment (not available over a plain ssh login). Apps that only speak X11 use `perms APP --display xwayland` (needs `xwayland`). |
303
323
  | An app with `network` is refused, naming `passt` | Install `passt`; the app is never put on the host network silently. |
324
+ | An app with `network_host` is refused, naming Landlock | The kernel lacks Landlock ABI 6 (Linux 6.12 or later, with Landlock enabled). Use `network` instead, which keeps the app in a private network namespace. |
304
325
  | `GitHub API rate limit reached` | Unauthenticated requests are limited to 60 per hour per address. Set `GITHUB_TOKEN`. |
305
326
  | `unsquashfs is not installed` | Install `squashfs-tools`, or accept the offer to run the AppImage's own extractor in a jail with no network. |
306
327
  | DwarFS-based AppImage | `appjail tools install dwarfs` fetches the pinned helper. |
@@ -319,7 +340,11 @@ owner change.
319
340
  only seen by a full download.
320
341
  - A sandboxed app can still do whatever its grants allow. An app with `network` can reach other machines on your LAN.
321
342
  - Granting a directory, a portal or a D-Bus name widens what a compromised app can do.
322
- - The audio permission includes the microphone.
343
+ - The audio permission includes the microphone. It is Pulse only (served by `pipewire-pulse` on PipeWire systems):
344
+ PipeWire's own socket would also expose cameras and screen casts, so apps that speak only native PipeWire get no
345
+ audio.
346
+ - Inside the jail only unix, internet and netlink sockets exist (no Bluetooth sockets, for example), and `io_uring`
347
+ is unavailable; apps that depend on them fail or fall back.
323
348
  - x86-64 only. The GNOME and KDE portal backends have not been tested (the GTK backend and a real X11-only AppImage
324
349
  have, under headless weston; the portal dialogs themselves are not driven). Real internet IPv6 under `pasta` is
325
350
  untested; IPv6 forwarding is tested in a fake network.
@@ -327,13 +352,14 @@ owner change.
327
352
  with SIGKILL, an app with `network` is stopped about a second later by a watcher inside its network namespace (a
328
353
  small empty directory `appjail-life-*` stays in the runtime directory).
329
354
 
330
- The full design is in [DESIGN.md](DESIGN.md); the reasoning behind each choice, rejected alternatives and deferred features are in [DECISIONS.md](DECISIONS.md).
355
+ The full design is in [DESIGN.md](DESIGN.md); the reasoning behind each choice, rejected alternatives and deferred
356
+ features are in [DECISIONS.md](DECISIONS.md).
331
357
 
332
358
  ## Development
333
359
 
334
- The code is stdlib-only Python under `src/appjail/`; tests are plain `pytest`. Many tests start real sandboxes and need a Linux
335
- machine with bubblewrap, `unsquashfs`, `pasta`, a headless Wayland compositor (`weston`) and the other packages in
336
- `tests/vm/packages.txt`.
360
+ The code is stdlib-only Python under `src/appjail/`; tests are plain `pytest`. Many tests start real sandboxes and
361
+ need a Linux machine with bubblewrap, `unsquashfs`, `pasta`, a headless Wayland compositor (`weston`) and the other
362
+ packages in `tests/vm/packages.txt`.
337
363
 
338
364
  ```sh
339
365
  APPJAIL_INTEGRATION=1 python3 -m pytest
@@ -14,6 +14,7 @@ dependencies = [] # standard library only, by design
14
14
  classifiers = [
15
15
  "Operating System :: POSIX :: Linux",
16
16
  "Environment :: Console",
17
+ "Environment :: X11 Applications",
17
18
  "Programming Language :: Python :: 3",
18
19
  "Topic :: Security",
19
20
  "Topic :: System :: Software Distribution",
@@ -22,6 +23,9 @@ classifiers = [
22
23
  [project.scripts]
23
24
  appjail = "appjail.cli:main"
24
25
 
26
+ [project.gui-scripts]
27
+ appjail-gui = "appjail.gui:main"
28
+
25
29
  # The version is the last vX.Y.Z tag, plus the commits since it and the short hash (PEP 440, like `git describe`). An sdist has
26
30
  # no git history: it carries the version in its PKG-INFO.
27
31
  [tool.hatch.version]
@@ -1,7 +1,7 @@
1
1
  # SPDX-FileCopyrightText: 2026 Alberto P
2
2
  # SPDX-License-Identifier: MPL-2.0
3
3
 
4
- """The catalog format: what `search` reads, whoever produced it (the AM converter, a file or a URL).
4
+ """The catalog format: what `search` reads, whoever produced it (appjail-db, a file or a URL).
5
5
 
6
6
  A catalog is one JSON document listing apps and, where known, where they come from: a kind-prefixed `source` that
7
7
  follows the manifest's grammar (`github:owner/repo`, `gitlab:HOST/group/project`, `forgejo:HOST/owner/repo`,
@@ -82,15 +82,15 @@ def build_parser():
82
82
  add.add_argument("--mime", action="append", default=[], metavar="TYPE",
83
83
  help="with --desktop: offer the app for this file type (must be declared by the app); repeatable")
84
84
  add.add_argument("--mime-all", action="store_true", help="with --desktop: offer every file type the app declares (minus refused ones)")
85
- search = sub.add_parser("search", help="search the local AM index (suggestions only, never installs)")
85
+ search = sub.add_parser("search", help="search the local index (suggestions only, never installs)")
86
86
  search.add_argument("keywords", nargs="+")
87
87
  search.add_argument("--limit", type=int, default=20, help="maximum results (default 20)")
88
88
  search.add_argument("--all", action="store_true", help="show every match")
89
- idx = sub.add_parser("index", help="manage the catalogs `search` reads (the built-in AM list and any you add)")
89
+ idx = sub.add_parser("index", help="manage the catalogs `search` reads (the built-in appjail-db list and any you add)")
90
90
  isub = idx.add_subparsers(dest="index_command", required=True)
91
91
  upd = isub.add_parser("update", help="refresh the catalogs, review the changes, then accept them")
92
92
  upd.add_argument("name", nargs="?", help="one source (default: every source)")
93
- upd.add_argument("--commit", default="HEAD", help="am only: fetch this commit (40 hex digits) instead of the remote HEAD")
93
+ upd.add_argument("--commit", default="HEAD", help="appjail-db only: fetch this appjail-db commit (40 hex digits) instead of the latest")
94
94
  iadd = isub.add_parser("add", help="add a catalog in the appjail-catalog format (see the README, Search)")
95
95
  iadd.add_argument("name", help="a short name for the source")
96
96
  where = iadd.add_mutually_exclusive_group(required=True)
@@ -99,7 +99,7 @@ def build_parser():
99
99
  irm = isub.add_parser("remove", help="remove a source you added, with its catalogs")
100
100
  irm.add_argument("name")
101
101
  irb = isub.add_parser("rollback", help="go back to the previous catalog of a source")
102
- irb.add_argument("name", nargs="?", help="default: am")
102
+ irb.add_argument("name", nargs="?", help="default: appjail-db")
103
103
  isub.add_parser("status", help="list the sources and their catalogs")
104
104
  upd_app = sub.add_parser("update", help="check for a newer release and install it after review and quarantine")
105
105
  upd_app.add_argument("app", nargs="?", help="app name (default: every installed app)")
@@ -177,7 +177,7 @@ def _add(args, client, console, app_args):
177
177
 
178
178
 
179
179
  def _index(args, client, console, app_args):
180
- return {"update": lambda: cmd_index_update(args, console),
180
+ return {"update": lambda: cmd_index_update(args, console, client),
181
181
  "add": lambda: cmd_index_add(args, console),
182
182
  "remove": lambda: cmd_index_remove(args, console),
183
183
  "rollback": lambda: cmd_index_rollback(args, console),
@@ -12,7 +12,7 @@ from .cmd_desktop import install_entry
12
12
  from .console import Abort, human_size
13
13
  from .permargs import (
14
14
  permissions_from_args,
15
- require_pasta,
15
+ require_network_isolation,
16
16
  show_permissions,
17
17
  )
18
18
 
@@ -132,7 +132,7 @@ def cmd_add(args, client, console, download=jail.download, now=None, extract=app
132
132
  raise Abort(f"'{name}' is already added")
133
133
 
134
134
  perms = permissions_from_args(args) # validates --dir before any network access
135
- require_pasta(perms)
135
+ require_network_isolation(perms)
136
136
 
137
137
  info = client.repo_info(args.source)
138
138
  show_review(console, info, now)
@@ -30,7 +30,7 @@ from .imagesrc import (
30
30
  )
31
31
  from .permargs import (
32
32
  permissions_from_args,
33
- require_pasta,
33
+ require_network_isolation,
34
34
  show_permissions,
35
35
  )
36
36
 
@@ -51,7 +51,7 @@ def cmd_add_file(args, console, extract=appimage.extract, extract_ok=appimage.ha
51
51
  if not 0 < st.st_size <= MAX_ASSET:
52
52
  raise Abort(f"unexpected file size ({st.st_size} bytes)")
53
53
  perms = permissions_from_args(args) # validates --dir before anything is copied
54
- require_pasta(perms)
54
+ require_network_isolation(perms)
55
55
 
56
56
  console.out(f"File : {real}")
57
57
  console.out(f"Size : {human_size(st.st_size)}, modified "
@@ -102,7 +102,7 @@ def cmd_add_url(args, console, download_url=jail.download_url, extract=appimage.
102
102
  if not 0 < max_mib * 1024 ** 2 <= MAX_ASSET:
103
103
  raise Abort(f"--max-size must be between 1 and {MAX_ASSET // 1024 ** 2} MiB")
104
104
  perms = permissions_from_args(args)
105
- require_pasta(perms)
105
+ require_network_isolation(perms)
106
106
 
107
107
  console.out(f"URL : {url}")
108
108
  console.out(f"Limit : {human_size(max_mib * 1024 ** 2)}; redirects may go to any host, also over plain http")
@@ -27,7 +27,7 @@ from .permargs import (
27
27
  describe_permissions,
28
28
  dirs_from_args,
29
29
  portals_from_args,
30
- require_pasta,
30
+ require_network_isolation,
31
31
  warn_owned_dbus,
32
32
  warn_privileged_portals,
33
33
  warn_sensitive_dbus,
@@ -62,6 +62,20 @@ def cmd_history(args, console):
62
62
  console.out(line)
63
63
 
64
64
 
65
+ def list_line(name, m):
66
+ """The one line `list` prints for an app."""
67
+ p = m.permissions
68
+ granted = [k for k in PERMISSION_FLAGS if getattr(p, k)] + [f"display={p.display}"]
69
+ pending = updater.load_pending(name)
70
+ return (f"{name} {m.version} {m.source} tier {m.evidence_tier} [{', '.join(granted)}]"
71
+ + (f" dirs: {', '.join(p.dirs)}" if p.dirs else "")
72
+ + (f" dbus: {', '.join(p.dbus_filter)}" if p.dbus_filter else "")
73
+ + (f" dbus-own: {', '.join(p.dbus_own)}" if p.dbus_own else "")
74
+ + (f" portals: {', '.join(p.portal_interfaces)}" if p.portal_interfaces else "")
75
+ + (f" channel: {m.channel}" if m.channel != "stable" else "")
76
+ + (f" (update seen: {pending['tag']})" if pending else ""))
77
+
78
+
65
79
  def cmd_list(console):
66
80
  names = updater.installed()
67
81
  if not names:
@@ -74,23 +88,17 @@ def cmd_list(console):
74
88
  except (manifest.ManifestError, OSError) as e:
75
89
  console.out(f"{name}: unreadable manifest ({e})")
76
90
  continue
77
- p = m.permissions
78
- granted = [k for k in PERMISSION_FLAGS if getattr(p, k)] + [f"display={p.display}"]
79
- pending = updater.load_pending(name)
80
- console.out(f"{name} {m.version} {m.source} tier {m.evidence_tier} [{', '.join(granted)}]"
81
- + (f" dirs: {', '.join(p.dirs)}" if p.dirs else "")
82
- + (f" dbus: {', '.join(p.dbus_filter)}" if p.dbus_filter else "")
83
- + (f" dbus-own: {', '.join(p.dbus_own)}" if p.dbus_own else "")
84
- + (f" portals: {', '.join(p.portal_interfaces)}" if p.portal_interfaces else "")
85
- + (f" channel: {m.channel}" if m.channel != "stable" else "")
86
- + (f" (update seen: {pending['tag']})" if pending else ""))
91
+ console.out(list_line(name, m))
87
92
 
88
93
 
89
94
  def revoke_portal_grants(name, mpath, console):
90
- """Drop the app's document-portal grants; only worth a note when the app had portals and the store is unreachable."""
95
+ """Drop the app's document-portal grants and its other remembered portal decisions (camera, location, ...), so a
96
+ later app with the same name starts with none; only worth a note when the app had portals and the store is
97
+ unreachable."""
91
98
  app = portal.app_id(name)
92
99
  try:
93
100
  portal.revoke_documents(app, os.environ, portal.granted_documents(app, os.environ))
101
+ portal.forget_permissions(app, os.environ)
94
102
  except jail.RunError as e:
95
103
  try:
96
104
  had_portals = manifest.load(mpath).permissions.portals
@@ -212,7 +220,7 @@ def cmd_perms(args, console):
212
220
  new = replace(m, permissions=replace(p, **changes))
213
221
  manifest.validate(new)
214
222
  if new.permissions.network != p.network or new.permissions.network_host != p.network_host:
215
- require_pasta(new.permissions)
223
+ require_network_isolation(new.permissions)
216
224
  console.out(f"{name} before: {describe_permissions(p)}")
217
225
  console.out(f"{name} after : {describe_permissions(new.permissions)}")
218
226
  warn_new_grants(console, p, new.permissions)