{"id":17800908,"url":"https://github.com/refi64/zypak","last_synced_at":"2025-03-17T10:34:27.188Z","repository":{"id":42958542,"uuid":"223828105","full_name":"refi64/zypak","owner":"refi64","description":"Run Electron binaries in a sandboxed Flatpak environment","archived":false,"fork":false,"pushed_at":"2024-01-18T02:12:27.000Z","size":250,"stargazers_count":95,"open_issues_count":12,"forks_count":5,"subscribers_count":6,"default_branch":"main","last_synced_at":"2024-01-18T08:03:47.496Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-3-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/refi64.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null}},"created_at":"2019-11-24T23:54:56.000Z","updated_at":"2024-01-13T12:46:43.000Z","dependencies_parsed_at":"2024-01-18T03:45:24.921Z","dependency_job_id":"d7dccc32-9c4d-47f5-bd72-73f6f435a54a","html_url":"https://github.com/refi64/zypak","commit_stats":null,"previous_names":[],"tags_count":21,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/refi64%2Fzypak","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/refi64%2Fzypak/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/refi64%2Fzypak/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/refi64%2Fzypak/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/refi64","download_url":"https://codeload.github.com/refi64/zypak/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":221675289,"owners_count":16861860,"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":[],"created_at":"2024-10-27T12:32:33.440Z","updated_at":"2025-03-17T10:34:27.179Z","avatar_url":"https://github.com/refi64.png","language":"C++","funding_links":[],"categories":[],"sub_categories":[],"readme":"# zypak\n\nAllows you to run Chromium based applications that require a sandbox in a Flatpak environment,\nby using LD_PRELOAD magic and a redirection system that redirects Chromium's sandbox to use\nthe Flatpak sandbox. Zypak is actively used by the majority of the Electron and Chrome-based\nFlatpaks on Flathub.\n\n## Basic usage\n\nThis requires your Flatpak to be using:\n\n- `org.freedesktop.Platform` / `Sdk` version `21.08` or later.\n- `org.electronjs.Electron2.BaseApp` as your base app. Recent releases include Zypak\n  built-in.\n\nNow, instead of running your Electron binary directly, call it via\n`zypak-wrapper PATH/TO/MY/ELECTRON/BINARY`. Note that this will only work if\nyour application is fully installed; simply running `zypak-wrapper` from a\n`flatpak-builder --run` shell or similar will fail.\n\n## Re-exec behavior\n\n`ZYPAK_SPAWN_LATEST_ON_REEXEC=1` will have Zypak detect when the app is re-\nexec'ing itself and attempt to spawn the latest version, in order for\n`chrome://restart` to function. (Previous versions of Zypak defaulted to this\nbeing enabled.)\n\n### Usage with a wrapper script\n\nIf `ZYPAK_SPAWN_LATEST_ON_REEXEC=1` is set, and Zypak was invoked by some sort\nof wrapper script, make sure you set `CHROME_WRAPPER=` to the path of said\nscript. Otherwise, if the application attempts to re-exec itself (i.e.\n`chrome://restart`), it won't be using the wrapper on re-exec, leading to\npotentially unexpected behavior.\n\n## Widevine support\n\nChromium and variants often cannot legally distribute Widevine themselves, so the binaries are\ndownloaded at runtime, usually into a folder named `WidevineCdm` located somewhere under the\nbrowser's data storage directory. For instance:\n\n- Chromium downloads Widevine to:\n  `~/.var/app/org.chromium.Chromium/config/chromium/WidevineCdm`\n- Brave downloads Widevine to:\n  `~/.var/app/com.brave.Browser/config/BraveSoftware/Brave-Browser/WidevineCdm`\n\nThis directory will also usually contain one or more of these files:\n\n- `latest-component-updated-widevine-cdm`\n- `manifest.json`\n\nIn order for the Widevine path to be exposed to the sandbox, you must set\n`ZYPAK_EXPOSE_WIDEVINE_PATH=` to the full path to this Widevine directory. Otherwise, the CDM module\nwill be downloaded, but the browser will be unable to load it.\n\nThe easiest way to test if Widevine is working is [this test page](https://bitmovin.com/demos/drm);\nif `ZYPAK_EXPOSE_WIDEVINE_PATH=` was set incorrectly, you'll see a message like this:\n\n```\nUnable to instantiate a key system supporting the required combinations\n(DRM_NO_KEY_SYSTEM)\n```\n\n## Alternate sandbox binary names\n\nSome applications like Microsoft Edge use a custom file name for the sandbox binary name, rather\nthan the default of `chrome-sandbox`. In that case, you may see messages like this:\n\n```\nThe SUID sandbox helper binary was found, but is not configured correctly. Rather than run without\nsandboxing I'm aborting now. You need to make sure that /app/extra/msedge-sandbox is owned by root\nand has mode 4755.\n```\n\nTo fix this, set `ZYPAK_SANDBOX_FILENAME=the-sandbox-basename`, e.g.\n`ZYPAK_SANDBOX_FILENAME=msedge-sandbox`.\n\n## Setting `LD_PRELOAD`\n\nZypak needs to override `LD_PRELOAD` in order to inject its redirection libraries into the\napplication process. If you need to add your own libraries to `LD_PRELOAD`, place them in\n`ZYPAK_LD_PRELOAD`, which will result in Zypak adding them to the `LD_PRELOAD` list, in addition to\nits own required libraries.\n\n## CEF support\n\nIf the application uses CEF, set `ZYPAK_CEF_LIBRARY_PATH` to the absolute path to the `libcef.so`\nlibrary.\n\n## Using a different version\n\nIf you want to try a different Zypak version for testing, or without using the\nElectron baseapp, then find the release tag you want to use and add one of these\nmodules somewhere in your Flatpak manifest:\n\n```json\n{\n  \"name\": \"zypak\",\n  \"sources\": [\n    {\n      \"type\": \"git\",\n      \"url\": \"https://github.com/refi64/zypak\",\n      \"tag\": \"THE_RELEASE_TAG\"\n    }\n  ]\n}\n```\n\n```yaml\n- name: zypak\n  sources:\n    - type: git\n      url: https://github.com/refi64/zypak\n      tag: THE_RELEASE_TAG\n```\n\n## Debugging\n\n- Set `ZYPAK_DEBUG=1` to enable debug logging.\n- Set `ZYPAK_STRACE=all` to run strace on the host and child processes.\n  - To make it host-only or child-only, set `ZYPAK_STRACE=host` or `ZYPAK_STRACE=child`, respectively.\n  - If only some child processes should be searched, use `ZYPAK_STRACE=child:type1,type2,...`, e.g.\n    `ZYPAK_STRACE=child:ppapi,utility` to trace all children of `--type=utility` and `--type=ppapi`.\n  - Set `ZYPAK_STRACE_FILTER=expr` to pass a filter expression to `strace -e`.\n  - In order to avoid arguments being ellipsized, set `ZYPAK_STRACE_NO_LINE_LIMIT=1`.\n- Set `ZYPAK_DISABLE_SANDBOX=1` to disable the use of the `--sandbox` argument\n  (required if the Electron binary is not installed, as the sandboxed calls will be unable to locate the Electron binary).\n\n## How does it work?\n\nZypak works by using LD_PRELOAD to trick Chromium into thinking its SUID sandbox is present and still\nsetuid, but all calls to it get instead redirected to another binary: Zypak's own sandbox.\n\nThis sandbox has two strategies to sandbox Chromium:\n\n### The mimic strategy\n\nThe *mimic strategy* works on the majority of Flatpak versions. It works by mimicking the zygote\nand redirecting all the incoming commands to actually become `flatpak-spawn` commands, then\nreturning those PIDs as the results of the \"fork\". This *does* have the side effect of slower\nstartup and higher memory usage, since there is no true zygote running, and thus this is only used\nwhere the spawn strategy (see below) does not work.\n\n### The spawn strategy\n\nThe *spawn strategy* a far better implementation, available on all Flatpak versions 1.8.2+. (Flatpak\n1.8.0 and 1.8.1 are not really supported.) It relies on two particular new features in 1.8.0:\n`expose-pids` and `SpawnStarted`:\n\n- `expose-pids` lets the process that opens a new sandbox see the PIDs of the sandboxed processes.\n  This essentially means it behaves much like using user namespaces to perform sandboxing and allows\n  Chromium to see the true PIDs of its child processes rather than trying to use an intermediary\n  (`flatpak-spawn` in the mimic strategy).\n- `SpawnStarted` is emitted when a sandboxed process fully starts, and it passes along the PID that\n  can be used for the parent to reach the sandboxed children.\n\nIn this strategy, the zygote is no longer mimicked; rather, the actual zygote is run sandboxed, just\nlike Chromium's official sandboxes work. The only difference is, the Flatpak sandbox is used instead\nof Chromium's setuid or namespace sandboxes.\n\nThis is a bit messy because Flatpak's sandboxing APIs all use D-Bus, so a new D-Bus session must be\n\"injected\" into the main Chromium process, which then runs in a separate thread and handles all the\nsandbox functionality. When the separate zypak-sandbox binary is started, it talks to this\n\"supervisor\" thread via a local socket pair, asking it to run the sandboxed process and staying\nalive until the sandboxed process completes. Meanwhile, the supervisor thread will swap out the\nsandbox PID for the true sandboxed process PID.\n\n### Rough layout of execution\n\n- When you use `zypak-wrapper`, it sets up the paths to the Zypak binary and\n  library directories and then calls `zypak-helper`.\n- `zypak-helper` will set up the LD_PRELOAD environment and start the main\n  process.\n    - If the spawn strategy is being used, a supervisor thread is started to manage the\n      sandboxed processes and communication with Flatpak.\n- When Chromium attempts to launch a sandboxed process, `zypak-sandbox` is used as the\n  sandbox instead of the SUID sandbox, and it then does one of the following:\n  - If the mimic strategy is being used, Zypak's mimic zygote will run, replacing\n    the true zygote. All the zygote messages get handled, and process forks instead\n    start a new process via `flatpak-spawn`.\n  - If the spawn strategy is being used, the sandbox will send a message to the supervisor\n    to start a new sandboxed process, then wait for the sandboxed process to exit.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frefi64%2Fzypak","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frefi64%2Fzypak","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frefi64%2Fzypak/lists"}