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

Author: abhisek

.github/workflows/pmg-e2e.yml

@@ -443,3 +443,61 @@ jobs:
 
       - name: Run Sandbox E2E Test
         run: pmg --sandbox npm exec -- node test/sandbox-e2e.js
+
+  sandbox-e2e-linux:
+    name: Sandbox E2E - Linux (Bubblewrap)
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    defaults:
+      run:
+        shell: bash
+    steps:
+      - name: Checkout Source
+        uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4
+
+      - name: Setup Go
+        uses: actions/setup-go@0aaccfd150d50ccaeb58ebd88d36e91967a5f35b # v5
+        with:
+          go-version-file: go.mod
+
+      - name: Setup Node.js
+        uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4
+        with:
+          node-version: 20
+          check-latest: true
+
+      - name: Install Bubblewrap
+        run: sudo apt-get update && sudo apt-get install -y bubblewrap
+
+      - name: Verify Bubblewrap Installation
+        run: bwrap --version
+
+      - name: Build PMG
+        run: make
+
+      - name: Add pmg to PATH
+        run: echo "$GITHUB_WORKSPACE/bin" >> $GITHUB_PATH
+
+      - name: Setup PMG
+        run: pmg setup install
+
+      - name: Create Test Directories for Sandbox Permissions Tests
+        run: mkdir -p ~/.aws ~/.gcloud ~/.kube ~/.ssh ~/.gnupg ~/.docker
+
+      - name: Create Test Files for Sandbox Permissions Tests
+        run: |
+          touch ~/.aws/credentials
+          touch ~/.gcloud/credentials.json
+          touch ~/.kube/config
+          touch ~/.ssh/id_rsa
+          touch ~/.gnupg/pubring.kbx
+          touch ~/.docker/config.json
+
+      - name: Disable AppArmor for Bubblewrap
+        run: |
+          sudo systemctl stop apparmor
+          sudo systemctl disable apparmor
+          sudo sysctl -w kernel.apparmor_restrict_unprivileged_userns=0
+
+      - name: Run Sandbox E2E Test
+        run: pmg --sandbox --sandbox-profile npm-restrictive npm exec -- node test/sandbox-e2e.js

README.md

@@ -17,6 +17,10 @@ See [example](https://safedep.io/malicious-npm-package-express-cookie-parser/)
 - Blocks malicious packages at install time
 - No configuration required, just install and use
 - Maintains package installation event log for transparency and audit trail
+- Enforces least privilege and defense in depth using OS native sandboxing
+
+PMG guarantees its own artifact integrity using GitHub and npm attestations. Users can cryptographically prove that the binary they run
+matches the source code they reviewed, eliminating the risk of tampered or malicious builds. See [why and how to trust PMG](docs/trust.md).
 
 ## PMG in Action
 

config/config.template.yml

@@ -57,8 +57,14 @@ trusted_packages:
 #
 # Currently supported platforms:
 # - macOS (using Seatbelt sandbox-exec)
-# - Linux (planned: Bubblewrap or seccomp-bpf)
+# - Linux (using Bubblewrap with namespace isolation)
 # - Windows (planned)
+#
+# Platform-specific limitations:
+# - Linux: Filesystem permissions use coarse-grained bind mounts. Glob patterns (e.g., *.txt)
+#   are expanded at policy translation time, but entire directories may be mounted rather than
+#   individual matching files. This is less precise than macOS regex-based filtering.
+# - macOS: Network filtering is limited (all-or-nothing for most policies).
 sandbox:
   # Enable sandbox mode (opt-in, default: false for backward compatibility)
   enabled: false

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

sandbox/executor/apply.go

@@ -56,7 +56,12 @@ func ApplySandbox(ctx context.Context, cmd *exec.Cmd, pmName string, opts ...app
 
 		policy, err = registry.GetProfile(cfg.SandboxProfileOverride)
 		if err != nil {
-			return nil, fmt.Errorf("failed to load override sandbox policy %s: %w", cfg.SandboxProfileOverride, err)
+			return nil, usefulerror.Useful().
+				WithCode("sandbox_policy_load_failed").
+				WithHumanError(fmt.Sprintf("failed to load override sandbox policy %s: %s", cfg.SandboxProfileOverride, err)).
+				WithHelp("Please check the sandbox profile path and try again.").
+				WithAdditionalHelp("See more at: https://github.com/safedep/pmg/blob/main/docs/sandbox.md").
+				Wrap(fmt.Errorf("failed to load override sandbox policy %s: %w", cfg.SandboxProfileOverride, err))
 		}
 	} else {
 		log.Debugf("Looking up sandbox policy for %s", pmName)
@@ -68,6 +73,7 @@ func ApplySandbox(ctx context.Context, cmd *exec.Cmd, pmName string, opts ...app
 		policyRef, exists := cfg.Config.Sandbox.Policies[pmName]
 		if !exists {
 			return nil, usefulerror.Useful().
+				WithCode("sandbox_policy_not_configured").
 				WithHumanError(fmt.Sprintf("no sandbox policy configured for %s", pmName)).
 				WithHelp("Please configure a sandbox policy for this package manager in the config file.").
 				WithAdditionalHelp("See https://github.com/safedep/pmg/blob/main/docs/sandbox.md for more information.").
@@ -123,7 +129,12 @@ func ApplySandbox(ctx context.Context, cmd *exec.Cmd, pmName string, opts ...app
 	}
 
 	if !sb.IsAvailable() {
-		return nil, fmt.Errorf("sandbox %s is required but not available", sb.Name())
+		return nil, usefulerror.Useful().
+			WithCode("sandbox_not_available").
+			WithHumanError(fmt.Sprintf("sandbox %s is required but not available", sb.Name())).
+			WithHelp("Please install the sandbox provider and try again.").
+			WithAdditionalHelp("See more at: https://github.com/safedep/pmg/blob/main/docs/sandbox.md").
+			Wrap(fmt.Errorf("sandbox %s is required but not available", sb.Name()))
 	}
 
 	log.Debugf("Running %s in %s sandbox with policy %s", pmName, sb.Name(), policy.Name)