feat: Add support for Linux Sandbox using Bubblewrap (#120)

* feat: Add support for bubblewrap sandbox

* fix: Glob pattern expansion limit for linux

* fix: Bug in glob pattern expansion for bwrap

* fix: README on trust

* fix: Multiple bubblewrap translator fix

* test: Add E2E for linux sandbox

* fix: Refactor bwrap sandbox to use common dangerous files

* fix: Path test case

* fix: Non-existent path handling bug

* refactor: Misc cleanup

* fix: Avoid bind mount for non-existentent deny protection

* fix: Off by one bug in path depth handling

* ci: Disable AppArmor on GHA runner

* fix: Disable apparmor userns restrictions

docs/sandbox.md

@@ -5,6 +5,31 @@ PMG sandbox design goal is to protect against unknown supply chain attacks using
 We do not want to re-invent sandbox and likely rely on OS native sandbox primitives. This is at the cost of developer experience,
 where we have to work within the limitations of the sandbox implementations that we use.
 
+## Requirements
+
+- Bubblewrap on Linux
+- Seatbelt on MacOS
+
+<details>
+<summary>Bubblewrap Installation on Linux</summary>
+
+For Debian-based Linux distributions, you can install Bubblewrap with the following command:
+
+```bash
+sudo apt install bubblewrap
+```
+
+For Arch Linux, you can install Bubblewrap with the following command:
+
+```bash
+sudo pacman -S bubblewrap
+```
+
+For other Linux distributions, you can install Bubblewrap from the package manager of your choice.
+See [Bubblewrap Installation](https://github.com/containers/bubblewrap#installation) for more details.
+
+</details>
+
 ## Usage
 
 - Make sure sandbox is enabled in your `config.yml` file.
@@ -99,11 +124,39 @@ Next time you run `pmg pnpm install`, the custom policy template will be used in
 
 ## Supported Platforms
 
-| Platform | Supported | Implementation                     |
-| -------- | --------- | ---------------------------------- |
-| MacOS    | Yes       | Seatbelt sandbox-exec              |
-| Linux    | No        | Bubblewrap / seccomp-bpf (planned) |
-| Windows  | No        | Not yet supported                  |
+| Platform | Supported | Implementation                      |
+| -------- | --------- | ----------------------------------- |
+| MacOS    | Yes       | Seatbelt sandbox-exec               |
+| Linux    | Yes       | Bubblewrap with namespace isolation |
+| Windows  | No        | Not yet supported                   |
+
+### Platform-Specific Limitations
+
+<details>
+<summary>Linux (Bubblewrap)</summary>
+
+**Filesystem permissions are coarse-grained**: [Bubblewrap](https://github.com/containers/bubblewrap) uses bind mounts for filesystem isolation.
+
+To prevent `Argument list too long` errors with large directory trees, PMG automatically uses
+coarse-grained fallback strategies when glob patterns match many files.
+
+**Fallback Behavior:**
+
+- **Small patterns** (< 100 matches): Individual files are mounted (fine-grained, most precise)
+- **Large patterns** (> 100 matches): Parent directory is mounted (coarse-grained, scalable)
+- **Threshold**: 100 paths per pattern triggers coarse-grained fallback
+
+**Network filtering**: All-or-nothing network isolation (via `--unshare-net`). Host-specific 
+filtering is not enforced.
+
+</details>
+
+<details>
+<summary>macOS (Seatbelt)</summary>
+
+**Network filtering is limited**: Seatbelt supports network rules in policies, but fine-grained `host:port` filtering is not enforced.
+
+</details>
 
 ## Concepts
 
@@ -176,6 +229,29 @@ Use `log(1)` to filter the log file by the log tag or generic `PMG_SBX_` prefix.
 log show --last 5m --predicate 'message ENDSWITH "PMG_SBX_"' --style compact
 ```
 
+### Linux
+
+Linux sandbox implementation uses Bubblewrap for namespace-based isolation. Enable debug logging to see translated sandbox arguments:
+
+```bash
+APP_LOG_LEVEL=debug APP_LOG_FILE=/tmp/pmg-debug.log pmg --sandbox --sandbox-profile=npm-restrictive npm install express
+```
+
+Review the debug log to see the translated `bwrap` command-line arguments:
+
+```bash
+grep "Bubblewrap arguments" /tmp/pmg-debug.log
+```
+
+To debug sandbox violations, you can manually test commands with increased verbosity by running the sandbox command directly:
+
+```bash
+# Extract the bwrap command from debug logs and run with --verbose
+bwrap --verbose [arguments...] -- npm install express
+```
+
+**Note**: Unlike macOS, Bubblewrap does not provide real-time violation logging. Policy violations typically manifest as `EACCES` (Permission denied) errors.
+
 ## References
 
 - https://github.com/anthropic-experimental/sandbox-runtime

docs/trust.md

@@ -10,7 +10,7 @@ The assertion in [2] cannot be *implicit*. If so, it breaks the entire security
 ## Security Goals
 
 - Adopt software supply chain security best practices so that PMG users can *verify* and only then trust PMG
-- PMG is open source, built in public and reviewed by the community for trust in code
+- PMG is open source, built in public and reviewed by the community for verifiable source of truth
 - PMG leverages GitHub build attestation to verify the integrity of the PMG binary with source provenance
 - PMG npm package has build attestation to verify the integrity of the PMG binary and build environment with source provenance
 - PMG security model is multi-layered without single point of failure
@@ -48,7 +48,7 @@ Install verified binary for your platform:
 gh release download $RELEASE_TAG -R safedep/pmg --dir ./pmg-$RELEASE_TAG 
 ```
 
-Install the platform specific binary from `./$pmg-$RELEASE_TAG`. To see binary specific attestation metadata, run:
+Install the platform specific binary from `./pmg-$RELEASE_TAG`. To see binary specific attestation metadata, run:
 
 ```bash
 gh attestation verify pmg_Linux_x86_64.tar.gz -R safedep/pmg --format json