appjail 0.1.0__tar.gz

appjail-0.1.0/.gitignore

@@ -0,0 +1,3 @@
+/vm/
+__pycache__/
+*.pyc

appjail-0.1.0/LICENSES/MPL-2.0.txt

@@ -0,0 +1,373 @@
+Mozilla Public License Version 2.0
+==================================
+
+1. Definitions
+--------------
+
+1.1. "Contributor"
+    means each individual or legal entity that creates, contributes to
+    the creation of, or owns Covered Software.
+
+1.2. "Contributor Version"
+    means the combination of the Contributions of others (if any) used
+    by a Contributor and that particular Contributor's Contribution.
+
+1.3. "Contribution"
+    means Covered Software of a particular Contributor.
+
+1.4. "Covered Software"
+    means Source Code Form to which the initial Contributor has attached
+    the notice in Exhibit A, the Executable Form of such Source Code
+    Form, and Modifications of such Source Code Form, in each case
+    including portions thereof.
+
+1.5. "Incompatible With Secondary Licenses"
+    means
+
+    (a) that the initial Contributor has attached the notice described
+        in Exhibit B to the Covered Software; or
+
+    (b) that the Covered Software was made available under the terms of
+        version 1.1 or earlier of the License, but not also under the
+        terms of a Secondary License.
+
+1.6. "Executable Form"
+    means any form of the work other than Source Code Form.
+
+1.7. "Larger Work"
+    means a work that combines Covered Software with other material, in 
+    a separate file or files, that is not Covered Software.
+
+1.8. "License"
+    means this document.
+
+1.9. "Licensable"
+    means having the right to grant, to the maximum extent possible,
+    whether at the time of the initial grant or subsequently, any and
+    all of the rights conveyed by this License.
+
+1.10. "Modifications"
+    means any of the following:
+
+    (a) any file in Source Code Form that results from an addition to,
+        deletion from, or modification of the contents of Covered
+        Software; or
+
+    (b) any new file in Source Code Form that contains any Covered
+        Software.
+
+1.11. "Patent Claims" of a Contributor
+    means any patent claim(s), including without limitation, method,
+    process, and apparatus claims, in any patent Licensable by such
+    Contributor that would be infringed, but for the grant of the
+    License, by the making, using, selling, offering for sale, having
+    made, import, or transfer of either its Contributions or its
+    Contributor Version.
+
+1.12. "Secondary License"
+    means either the GNU General Public License, Version 2.0, the GNU
+    Lesser General Public License, Version 2.1, the GNU Affero General
+    Public License, Version 3.0, or any later versions of those
+    licenses.
+
+1.13. "Source Code Form"
+    means the form of the work preferred for making modifications.
+
+1.14. "You" (or "Your")
+    means an individual or a legal entity exercising rights under this
+    License. For legal entities, "You" includes any entity that
+    controls, is controlled by, or is under common control with You. For
+    purposes of this definition, "control" means (a) the power, direct
+    or indirect, to cause the direction or management of such entity,
+    whether by contract or otherwise, or (b) ownership of more than
+    fifty percent (50%) of the outstanding shares or beneficial
+    ownership of such entity.
+
+2. License Grants and Conditions
+--------------------------------
+
+2.1. Grants
+
+Each Contributor hereby grants You a world-wide, royalty-free,
+non-exclusive license:
+
+(a) under intellectual property rights (other than patent or trademark)
+    Licensable by such Contributor to use, reproduce, make available,
+    modify, display, perform, distribute, and otherwise exploit its
+    Contributions, either on an unmodified basis, with Modifications, or
+    as part of a Larger Work; and
+
+(b) under Patent Claims of such Contributor to make, use, sell, offer
+    for sale, have made, import, and otherwise transfer either its
+    Contributions or its Contributor Version.
+
+2.2. Effective Date
+
+The licenses granted in Section 2.1 with respect to any Contribution
+become effective for each Contribution on the date the Contributor first
+distributes such Contribution.
+
+2.3. Limitations on Grant Scope
+
+The licenses granted in this Section 2 are the only rights granted under
+this License. No additional rights or licenses will be implied from the
+distribution or licensing of Covered Software under this License.
+Notwithstanding Section 2.1(b) above, no patent license is granted by a
+Contributor:
+
+(a) for any code that a Contributor has removed from Covered Software;
+    or
+
+(b) for infringements caused by: (i) Your and any other third party's
+    modifications of Covered Software, or (ii) the combination of its
+    Contributions with other software (except as part of its Contributor
+    Version); or
+
+(c) under Patent Claims infringed by Covered Software in the absence of
+    its Contributions.
+
+This License does not grant any rights in the trademarks, service marks,
+or logos of any Contributor (except as may be necessary to comply with
+the notice requirements in Section 3.4).
+
+2.4. Subsequent Licenses
+
+No Contributor makes additional grants as a result of Your choice to
+distribute the Covered Software under a subsequent version of this
+License (see Section 10.2) or under the terms of a Secondary License (if
+permitted under the terms of Section 3.3).
+
+2.5. Representation
+
+Each Contributor represents that the Contributor believes its
+Contributions are its original creation(s) or it has sufficient rights
+to grant the rights to its Contributions conveyed by this License.
+
+2.6. Fair Use
+
+This License is not intended to limit any rights You have under
+applicable copyright doctrines of fair use, fair dealing, or other
+equivalents.
+
+2.7. Conditions
+
+Sections 3.1, 3.2, 3.3, and 3.4 are conditions of the licenses granted
+in Section 2.1.
+
+3. Responsibilities
+-------------------
+
+3.1. Distribution of Source Form
+
+All distribution of Covered Software in Source Code Form, including any
+Modifications that You create or to which You contribute, must be under
+the terms of this License. You must inform recipients that the Source
+Code Form of the Covered Software is governed by the terms of this
+License, and how they can obtain a copy of this License. You may not
+attempt to alter or restrict the recipients' rights in the Source Code
+Form.
+
+3.2. Distribution of Executable Form
+
+If You distribute Covered Software in Executable Form then:
+
+(a) such Covered Software must also be made available in Source Code
+    Form, as described in Section 3.1, and You must inform recipients of
+    the Executable Form how they can obtain a copy of such Source Code
+    Form by reasonable means in a timely manner, at a charge no more
+    than the cost of distribution to the recipient; and
+
+(b) You may distribute such Executable Form under the terms of this
+    License, or sublicense it under different terms, provided that the
+    license for the Executable Form does not attempt to limit or alter
+    the recipients' rights in the Source Code Form under this License.
+
+3.3. Distribution of a Larger Work
+
+You may create and distribute a Larger Work under terms of Your choice,
+provided that You also comply with the requirements of this License for
+the Covered Software. If the Larger Work is a combination of Covered
+Software with a work governed by one or more Secondary Licenses, and the
+Covered Software is not Incompatible With Secondary Licenses, this
+License permits You to additionally distribute such Covered Software
+under the terms of such Secondary License(s), so that the recipient of
+the Larger Work may, at their option, further distribute the Covered
+Software under the terms of either this License or such Secondary
+License(s).
+
+3.4. Notices
+
+You may not remove or alter the substance of any license notices
+(including copyright notices, patent notices, disclaimers of warranty,
+or limitations of liability) contained within the Source Code Form of
+the Covered Software, except that You may alter any license notices to
+the extent required to remedy known factual inaccuracies.
+
+3.5. Application of Additional Terms
+
+You may choose to offer, and to charge a fee for, warranty, support,
+indemnity or liability obligations to one or more recipients of Covered
+Software. However, You may do so only on Your own behalf, and not on
+behalf of any Contributor. You must make it absolutely clear that any
+such warranty, support, indemnity, or liability obligation is offered by
+You alone, and You hereby agree to indemnify every Contributor for any
+liability incurred by such Contributor as a result of warranty, support,
+indemnity or liability terms You offer. You may include additional
+disclaimers of warranty and limitations of liability specific to any
+jurisdiction.
+
+4. Inability to Comply Due to Statute or Regulation
+---------------------------------------------------
+
+If it is impossible for You to comply with any of the terms of this
+License with respect to some or all of the Covered Software due to
+statute, judicial order, or regulation then You must: (a) comply with
+the terms of this License to the maximum extent possible; and (b)
+describe the limitations and the code they affect. Such description must
+be placed in a text file included with all distributions of the Covered
+Software under this License. Except to the extent prohibited by statute
+or regulation, such description must be sufficiently detailed for a
+recipient of ordinary skill to be able to understand it.
+
+5. Termination
+--------------
+
+5.1. The rights granted under this License will terminate automatically
+if You fail to comply with any of its terms. However, if You become
+compliant, then the rights granted under this License from a particular
+Contributor are reinstated (a) provisionally, unless and until such
+Contributor explicitly and finally terminates Your grants, and (b) on an
+ongoing basis, if such Contributor fails to notify You of the
+non-compliance by some reasonable means prior to 60 days after You have
+come back into compliance. Moreover, Your grants from a particular
+Contributor are reinstated on an ongoing basis if such Contributor
+notifies You of the non-compliance by some reasonable means, this is the
+first time You have received notice of non-compliance with this License
+from such Contributor, and You become compliant prior to 30 days after
+Your receipt of the notice.
+
+5.2. If You initiate litigation against any entity by asserting a patent
+infringement claim (excluding declaratory judgment actions,
+counter-claims, and cross-claims) alleging that a Contributor Version
+directly or indirectly infringes any patent, then the rights granted to
+You by any and all Contributors for the Covered Software under Section
+2.1 of this License shall terminate.
+
+5.3. In the event of termination under Sections 5.1 or 5.2 above, all
+end user license agreements (excluding distributors and resellers) which
+have been validly granted by You or Your distributors under this License
+prior to termination shall survive termination.
+
+************************************************************************
+*                                                                      *
+*  6. Disclaimer of Warranty                                           *
+*  -------------------------                                           *
+*                                                                      *
+*  Covered Software is provided under this License on an "as is"       *
+*  basis, without warranty of any kind, either expressed, implied, or  *
+*  statutory, including, without limitation, warranties that the       *
+*  Covered Software is free of defects, merchantable, fit for a        *
+*  particular purpose or non-infringing. The entire risk as to the     *
+*  quality and performance of the Covered Software is with You.        *
+*  Should any Covered Software prove defective in any respect, You     *
+*  (not any Contributor) assume the cost of any necessary servicing,   *
+*  repair, or correction. This disclaimer of warranty constitutes an   *
+*  essential part of this License. No use of any Covered Software is   *
+*  authorized under this License except under this disclaimer.         *
+*                                                                      *
+************************************************************************
+
+************************************************************************
+*                                                                      *
+*  7. Limitation of Liability                                          *
+*  --------------------------                                          *
+*                                                                      *
+*  Under no circumstances and under no legal theory, whether tort      *
+*  (including negligence), contract, or otherwise, shall any           *
+*  Contributor, or anyone who distributes Covered Software as          *
+*  permitted above, be liable to You for any direct, indirect,         *
+*  special, incidental, or consequential damages of any character      *
+*  including, without limitation, damages for lost profits, loss of    *
+*  goodwill, work stoppage, computer failure or malfunction, or any    *
+*  and all other commercial damages or losses, even if such party      *
+*  shall have been informed of the possibility of such damages. This   *
+*  limitation of liability shall not apply to liability for death or   *
+*  personal injury resulting from such party's negligence to the       *
+*  extent applicable law prohibits such limitation. Some               *
+*  jurisdictions do not allow the exclusion or limitation of           *
+*  incidental or consequential damages, so this exclusion and          *
+*  limitation may not apply to You.                                    *
+*                                                                      *
+************************************************************************
+
+8. Litigation
+-------------
+
+Any litigation relating to this License may be brought only in the
+courts of a jurisdiction where the defendant maintains its principal
+place of business and such litigation shall be governed by laws of that
+jurisdiction, without reference to its conflict-of-law provisions.
+Nothing in this Section shall prevent a party's ability to bring
+cross-claims or counter-claims.
+
+9. Miscellaneous
+----------------
+
+This License represents the complete agreement concerning the subject
+matter hereof. If any provision of this License is held to be
+unenforceable, such provision shall be reformed only to the extent
+necessary to make it enforceable. Any law or regulation which provides
+that the language of a contract shall be construed against the drafter
+shall not be used to construe this License against a Contributor.
+
+10. Versions of the License
+---------------------------
+
+10.1. New Versions
+
+Mozilla Foundation is the license steward. Except as provided in Section
+10.3, no one other than the license steward has the right to modify or
+publish new versions of this License. Each version will be given a
+distinguishing version number.
+
+10.2. Effect of New Versions
+
+You may distribute the Covered Software under the terms of the version
+of the License under which You originally received the Covered Software,
+or under the terms of any subsequent version published by the license
+steward.
+
+10.3. Modified Versions
+
+If you create software not governed by this License, and you want to
+create a new license for such software, you may create and use a
+modified version of this License if you rename the license and remove
+any references to the name of the license steward (except to note that
+such modified license differs from this License).
+
+10.4. Distributing Source Code Form that is Incompatible With Secondary
+Licenses
+
+If You choose to distribute Source Code Form that is Incompatible With
+Secondary Licenses under the terms of this version of the License, the
+notice described in Exhibit B of this License must be attached.
+
+Exhibit A - Source Code Form License Notice
+-------------------------------------------
+
+  This Source Code Form is subject to the terms of the Mozilla Public
+  License, v. 2.0. If a copy of the MPL was not distributed with this
+  file, You can obtain one at https://mozilla.org/MPL/2.0/.
+
+If it is not possible or desirable to put the notice in a particular
+file, then You may include the notice in a location (such as a LICENSE
+file in a relevant directory) where a recipient would be likely to look
+for such a notice.
+
+You may add additional accurate notices of copyright ownership.
+
+Exhibit B - "Incompatible With Secondary Licenses" Notice
+---------------------------------------------------------
+
+  This Source Code Form is "Incompatible With Secondary Licenses", as
+  defined by the Mozilla Public License, v. 2.0.

appjail-0.1.0/PKG-INFO

@@ -0,0 +1,194 @@
+Metadata-Version: 2.5
+Name: appjail
+Version: 0.1.0
+Summary: Sandboxed AppImage manager built on bubblewrap
+License-Expression: MPL-2.0
+License-File: LICENSES/MPL-2.0.txt
+Classifier: Environment :: Console
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Topic :: Security
+Classifier: Topic :: System :: Software Distribution
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+
+# appjail
+
+[![CI](https://github.com/alberto743/appjail/actions/workflows/ci.yml/badge.svg)](https://github.com/alberto743/appjail/actions/workflows/ci.yml)
+[![License: MPL-2.0](https://img.shields.io/badge/license-MPL--2.0-blue.svg)](LICENSES/MPL-2.0.txt)
+[![REUSE](https://github.com/alberto743/appjail/actions/workflows/reuse.yml/badge.svg)](https://github.com/alberto743/appjail/actions/workflows/reuse.yml)
+
+A small command-line manager for [AppImages](https://appimage.org/) that runs every app inside a
+[bubblewrap](https://github.com/containers/bubblewrap) sandbox. It works in user mode (no sudo), supports GUI apps
+under Wayland, and treats the software you install as untrusted.
+
+*appjail is young software: read the [limits](#limits) before relying on it.*
+
+## Why
+
+Package managers for AppImages typically download a release and run it with your full privileges. appjail
+is built around the opposite assumptions:
+
+- **Declarative manifests, no remote code.** An app is a small TOML file: source, pinned hash, permissions. Nothing
+  fetched from the network is ever executed or sourced, and appjail has no self-update.
+- **You name the source.** You give a GitHub `owner/repo`. That repository is the only place the app is fetched from,
+  whatever an AppImage's embedded update information says.
+- **Downloads are jailed.** The download, the extraction and the verification tools run in throwaway sandboxes
+  with only the access they need (a private network namespace for downloads, none for extraction).
+- **Everything is denied by default.** An app starts with a private home and a restricted Wayland socket. Network,
+  directories, D-Bus names, portals and the rest are explicit grants you can inspect and change.
+- **Updates are reviewed.** A new release waits in quarantine (7 days by default), is shown to you as a diff, and
+  is blocked outright if its evidence gets weaker or the repository changes owner.
+
+## Requirements
+
+- Linux on x86-64 with unprivileged user namespaces. Tested on Debian 13 and Ubuntu 26.04; older systems are
+  not supported.
+- Python 3.12 or newer (tested with 3.13 on Debian 13 and 3.14 on Ubuntu 26.04; 3.12 is the declared minimum and is not
+  run by the tests). appjail uses only the standard library.
+- `bubblewrap` and `squashfs-tools` (`unsquashfs`) are required.
+- Recommended: `passt` (the `pasta` command) for apps with network access, `xdg-dbus-proxy` for D-Bus filtering,
+  `xwayland` for X11-only apps, `git` for the manifest history and the search index.
+- A Wayland compositor for GUI apps. Apps that need X11 run on a private Xwayland inside their own sandbox; the host
+  X11 socket is never shared.
+
+On Debian or Ubuntu:
+
+```sh
+sudo apt install bubblewrap squashfs-tools passt xdg-dbus-proxy xwayland git
+```
+
+## Install
+
+appjail is a Python package with no dependencies. Install it as a command with [pipx](https://pipx.pypa.io/)
+or pip (pip downloads only the build backend, Hatchling):
+
+```sh
+git clone <repository-url> appjail
+cd appjail
+pipx install .          # or: pip install --user .
+appjail --help
+```
+
+To try it without installing, run it from the clone: `PYTHONPATH=src python3 -m appjail --help`.
+Update appjail with `git pull` after reading what changed, then reinstall.
+
+Data lives in `~/.local/share/appjail` (images, extracted trees, private homes, staging) and `~/.config/appjail`
+(manifests, tracked in a small local git repository). `APPJAIL_DATA_DIR` and `APPJAIL_CONFIG_DIR` override them.
+
+## Quick start
+
+```sh
+appjail add skyjake/lagrange     # review the repository, pick the asset, download, pin, extract
+appjail run lagrange             # run it in its sandbox
+appjail list                     # installed apps, tiers and permissions
+appjail update                   # check every app for a newer release
+appjail remove lagrange          # delete the app and its private home
+```
+
+`add` also takes `--tag TAG` (a specific release instead of the latest), `--name`, `--prerelease`, and the permission
+options below at install time (`--allow`, `--dir`, `--dbus`, `--display xwayland`, `--no-audio`, `--no-gpu`).
+`run` takes `--dir PATH[:ro|:rw]` and `--file PATH[:rw]` for one run only.
+
+`add` shows the repository owner, account age, stars and fork or archive status before it downloads anything, and
+asks if several release assets match. By default an app gets audio and GPU access and nothing else.
+
+### Permissions
+
+```sh
+appjail perms lagrange                              # show
+appjail perms lagrange --allow network              # outbound network only (see below)
+appjail perms lagrange --add-dir ~/Documents:rw     # a directory, read-only unless :rw
+appjail perms lagrange --add-dbus org.example.Name  # talk to one session-bus name through a filtering proxy
+appjail perms lagrange --allow portals              # desktop portals (file chooser, notifications, ...)
+appjail run lagrange --file ~/report.pdf            # one file, for this run only
+```
+
+| Permission | Effect |
+|---|---|
+| `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. |
+| `network_host` | The host's own network, including localhost services. For apps that really need them. |
+| `audio`, `gpu` | On by default; `--no-audio` and `--no-gpu` at `add` time, or `--deny` later. |
+| `portals` | The safe set of desktop portals; privileged ones are listed per app with `--add-portal`. |
+| `userns` | Nested user namespaces (Chromium and Electron sandboxes). Weakens isolation, off by default. |
+| `dirs` | Directories mapped into the private home. Credentials, browser profiles, shell startup files and system trees are refused. |
+| `display` | `wayland` (default) or `xwayland`. |
+
+Every sandbox also drops all capabilities, has its own PID, IPC and UTS namespaces, a read-only system, a minimal
+`/dev`, a generated `/etc/passwd`, and a seccomp filter. The extracted app tree is hashed and checked at every
+launch.
+
+## How trust works
+
+Each app is pinned by hash and carries an *evidence tier* that `update` will never silently lower:
+
+| Tier | Evidence |
+|---|---|
+| 1 | A verified GitHub build attestation (Sigstore), checked with a pinned `gh` that you install on request (`appjail tools install gh`). |
+| 3 | The SHA-256 digest GitHub publishes for the release asset. |
+| 4 | Trust on first use: appjail shows you the hash it computed. |
+
+Tier 2 (GPG signatures) is not implemented. Most AppImages will land on tier 3 or 4, which proves "unchanged and from the
+same account", not "safe".
+
+`appjail update` re-resolves the pinned repository, downloads the candidate in the jail, verifies it, and shows you the
+version, the hashes, the tier and the release link. A release must be seen for the quarantine period before it can
+be installed (`--quarantine DAYS`). For tier 4 apps appjail records the candidate's hash when it is first seen and refuses
+the install if the content changed in the meantime. A change of repository owner or a drop in tier blocks the update.
+`--channel stable|prerelease|pinned` chooses which releases an app follows.
+
+## Searching
+
+appjail can search the [AM](https://github.com/ivan-hc/AM) application list as a source of suggestions. It reads that data
+as plain text only and never runs anything from it.
+
+```sh
+appjail index update      # fetch the list in a jail, review the changes, pin it
+appjail index rollback    # go back to the previous snapshot
+appjail index status      # show the pinned snapshot
+appjail search editor     # candidates only; installing is always `appjail add owner/repo`
+```
+
+## Other commands
+
+- `appjail history [app]`: every change to the manifests, from the local git repository. `appjail run` warns if a
+  manifest was edited outside appjail.
+- `appjail 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).
+- Set `GITHUB_TOKEN` to raise the GitHub API rate limit. It is only ever sent to `api.github.com`.
+
+## Limits
+
+- **Not audited, not a security boundary you should bet on yet.** bwrap and the Linux kernel do the isolation; appjail
+  configures them conservatively but has had no external review.
+- Only GitHub repositories are supported. Apps hosted elsewhere appear in `search` but cannot be added.
+- A sandboxed app can still do whatever its grants allow. An app with `network` can reach other machines on your LAN.
+- Granting a directory, a portal or a D-Bus name widens what a compromised app can do.
+- x86-64 only. The GNOME and KDE portal backends have not been tested (the GTK backend and a real X11-only AppImage
+  have, under headless weston; the portal dialogs themselves are not driven). Real internet IPv6 under `pasta` is
+  untested; IPv6 forwarding is tested in a fake network.
+- Stopping `appjail run` with SIGINT, SIGTERM or SIGHUP stops the whole jail, including `pasta`. If appjail is killed
+  with SIGKILL, an app with `network` is stopped about a second later by a watcher inside its network namespace (a
+  small empty directory `appjail-life-*` stays in the runtime directory).
+- The audio permission includes the microphone.
+
+The full design, the reasoning behind each choice and the verification notes are in [DESIGN.md](DESIGN.md).
+
+## Development
+
+The code is stdlib-only Python under `src/appjail/`; tests are plain `pytest`. Many tests start real sandboxes and need a Linux
+machine with bubblewrap, `unsquashfs`, `pasta`, a headless Wayland compositor (`weston`) and the other packages in
+`tests/vm/packages.txt`.
+
+```sh
+APPJAIL_INTEGRATION=1 python3 -m pytest
+```
+
+Without `APPJAIL_INTEGRATION=1` the tests that need real sandboxes are skipped. Tests that download from the network are
+opt-in (`APPJAIL_E2E=1`, `APPJAIL_LIVE=1`). The project's own workflow runs the suite inside a disposable QEMU guest built
+from `tests/vm/` so that downloads and sandboxed apps never run on the developer's machine; see
+[CLAUDE.md](CLAUDE.md) for the details. GitHub Actions runs the full suite and a REUSE compliance check on every push, and a separate workflow runs every
+opt-in suite (real downloads) on demand and weekly.
+
+## License
+
+[MPL-2.0](LICENSES/MPL-2.0.txt). The repository follows the [REUSE](https://reuse.software/) specification.