pmg/docs/sandbox.md

Sandbox

PMG sandbox design goal is to protect against unknown supply chain attacks using principle of least privilege.

We do not want to re-invent sandbox and 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.

Security Model

The sandbox is default-deny. Every operation is blocked unless the policy allows it, and deny rules win over allow rules when both match. PMG ships mandatory denies for credential files (.env, .ssh, .aws, .gcloud and more). See dangerous.go for the full list. This protects against accidental credential leaks and some classes of supply chain attacks that attempt to access credentials. To allow legitimate access, you can opt out of a mandatory deny via an exact match entry in allow_read or allow_write (in the policy or via --sandbox-allow).

Detailed rules

• Default deny: All operations are blocked unless explicitly allowed by the policy. An empty policy grants no access.
• Deny rules override allow rules: When a path appears in both allow and deny lists, the deny rule wins. Deny rules are placed after allow rules in the generated sandbox profile to ensure this.
• Credential and sensitive file protection: The sandbox blocks read and write access to known list of credential files by default.
• Git hooks are always blocked: Write access to .git/hooks/ in both $CWD and $HOME is always denied to prevent arbitrary code execution via repository hooks.
• Git config is blocked by default: Write access to .git/config is denied unless allow_git_config: true is set in the policy. This prevents credential helper manipulation.
• Runtime overrides remove only exact-match deny entries: When --sandbox-allow adds a path to an allow list, only a literal string match in the corresponding deny list is removed. Glob and wildcard deny patterns (e.g., /etc/**) are never removed. An exact-match entry in allow_read or allow_write (policy or runtime) opts out of the mandatory deny for that credential file. .git/hooks does not accept opt-outs.
• Profile inheritance is single-level: A profile can inherit from one built-in profile. Allow and deny lists are merged using union semantics. Boolean fields (allow_pty, allow_git_config) in the child override the parent.
• Variable expansion is runtime-only: Policy paths use ${HOME}, ${CWD}, and ${TMPDIR} which are expanded when the sandbox is set up, not when the policy is defined.
• Process-level isolation only: The sandbox restricts the package manager process and its children. It does not enforce CPU, memory, or disk quotas. Network filtering is coarse-grained — host-level filtering is not enforced on either platform.

Mandatory Credential Protection

PMG maintains a known list of credential and sensitive files at dangerous.go that are blocked by default in the sandbox. PMG injects three deny patterns per file:

• The path under ${CWD}
• The path under ${HOME}
• A **/<file> glob.

To opt out, list the literal path in allow_read or allow_write in your policy, or pass --sandbox-allow read=... / write=... at runtime. Listing a CWD-absolute or HOME-absolute path also suppresses the matching **/<file> glob on the same direction, so --sandbox-allow read=./.env is enough to read ${CWD}/.env. Suppression is exact post-expansion match; broad globs like ${HOME}/** do not opt out of ${HOME}/.aws. The unnamed absolute form stays denied. .git/hooks does not accept opt-outs because hooks can execute arbitrary code.

Requirements

• Bubblewrap on Linux
• Seatbelt on MacOS

Bubblewrap Installation on Linux

For Debian-based Linux distributions, you can install Bubblewrap with the following command:

sudo apt install bubblewrap

For Arch Linux, you can install Bubblewrap with the following command:

sudo pacman -S bubblewrap

For other Linux distributions, you can install Bubblewrap from the package manager of your choice. See Bubblewrap Installation for more details.

Usage

• Make sure sandbox is enabled in your config.yml file. See configuration for the configuration schema.
• Make sure sandbox profiles are configured for the package managers you want to sandbox.

See configuration and config/config.template.yml for the configuration schema. Once sandbox is enabled, you can run package manager commands with sandbox protection.

pmg npm install express

Explicitly enable sandbox if not enabled in the config.yml file:

pmg --sandbox --sandbox-profile=npm-restrictive npm install express

Run sandbox with custom policy file:

pmg --sandbox --sandbox-profile=/path/to/custom-policy.yml npm install express

Runtime Allow Overrides

Use --sandbox-allow to make one-off exceptions without creating a custom profile. This is useful when a command needs access that the default profile blocks.

# Allow writing to a specific file
pmg --sandbox-allow write=./.gitignore npx create-next-app@latest

# Allow executing a binary blocked by the profile
pmg --sandbox-allow exec=$(which curl) npm install some-package

# Allow outbound connection to a private registry
pmg --sandbox-allow net-connect=npm.internal.corp:443 npm install @corp/private-pkg

# Allow a dev server to bind to a local port
pmg --sandbox-allow net-bind=127.0.0.1:3000 npx some-dev-tool

# Multiple overrides
pmg \
  --sandbox-allow write=./.gitignore \
  --sandbox-allow exec=$(which curl) \
  npm install some-package

Supported types: read, write, exec, net-connect, net-bind.

Overrides are non-persistent (apply to current invocation only) and logged in the event log for auditing. An override adds the path to the allow list and removes an exact match entry from the corresponding deny list. Glob deny patterns are never removed. An exact-match entry in allow_read or allow_write (in the policy or via --sandbox-allow read=... / write=...) opts out of the mandatory deny for that credential file. PMG treats both channels as explicit user intent. Suppression is exact-match only; broad paths or globs do not opt out. .git/hooks does not accept opt-outs.

Custom policy overrides using Policy Templates

Policy templates allow custom policy overrides. To setup custom policy overrides for your package manager, start by looking up the PMG configuration directory:

pmg setup info

Create a new policy template file in the PMG configuration directory and edit it to suit your needs:

# Set the PMG configuration directory
export PMG_CONFIG_DIR="/path/to/pmg/config/dir"

# Create the policy template file
cat > $PMG_CONFIG_DIR/sandbox-custom-policy.yml <<EOF
name: pnpm-macos-custom-sandbox
description: Custom profile for pnpm in MacOS
inherits: npm-restrictive

package_managers:
  - pnpm

allow_pty: true

filesystem:
  allow_write:
    # pnpm i need write access here
    - ${HOME}/Library/pnpm/.tools/**

    # pnpm i creates these tmp files in local dir, at least on MacOS
    - ${CWD}/_tmp_*

    # pnpm self-update (or likely update) creates temporary package.json files
    # for writing. This is likely for atomic update using filesystem rename operation
    # which guarantees atomicity
    - ${CWD}/package.json.*

    # Need access for dependency resolution
    - ${CWD}/.pnpm-store

  # Additional deny rules for extra security
  deny_write:
    - ${CWD}/.env
    - ${CWD}/.env.*
EOF

Edit PMG configuration file to use the custom policy template and override the default policy for your package manager:

policy_templates:
  pnpm-macos-custom-sandbox:
    path: ./sandbox-custom-policy.yml

policies:
  pnpm:
    enabled: true
    profile: pnpm-macos-custom-sandbox

Next time you run pmg pnpm install, the custom policy template will be used instead of the default policy.

Supported Platforms

Platform	Supported	Implementation
MacOS	Yes	Seatbelt sandbox-exec
Linux	Yes	Bubblewrap with namespace isolation
Windows	No	Not yet supported

Platform-Specific Limitations

Linux (Bubblewrap)

Filesystem permissions are coarse-grained: 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.

Per-direction mandatory deny is asymmetric on Linux: bwrap has no primitive that allows writes while denying reads for the same path. --bind exposes both directions; --tmpfs and --ro-bind /dev/null block both. If you opt out of write for a mandatory deny path (e.g., list it in allow_write but not allow_read), the bind mount also exposes reads, and PMG cannot enforce the read-side mandatory deny. PMG warns via log.Warnf when it detects this case. macOS Seatbelt does not have this limitation; its file-read* and file-write* rules are independent.

macOS (Seatbelt)

Network filtering is limited: Seatbelt supports network rules in policies, but fine-grained host:port filtering is not enforced.

Concepts

PMG layers three concepts: a Policy is the rule set defining what is allowed and denied. A Profile is a named binding from a package manager to a policy. A Policy Template maps a profile name to a YAML file so you can override the built-ins.

Detailed concepts

Policy

Policy is a set of rules that define the allowed and denied actions for a package manager. A sandbox implementation, such as sandbox-exec on MacOS enforces the policy.

PMG defines its own policy model. The design goal is simplicity and ease of use. Sandbox implementations are expected to translate the policy model into their own native policy format. Rules for policy are:

• Deny by default unless explicitly allowed
• Deny rules have higher priority than allow rules
• Policy profile allows binding package managers to a specific sandbox policy
• Package manager must have a sandbox profile when sandbox is enabled
• Package manager specific sandbox profile may be disabled to skip sandbox for the package manager

Profile

Profile is a named reference to a policy. It is used to associate a policy with a package manager. PMG ships with a set of built-in profiles that are used to enforce the policies for the package manager. See sandbox/profiles for the list of built-in profiles.

Custom profiles can be created by copying a built-in profile and modifying the rules to suit the needs. See sandbox/profiles/README.md for more details.

Policy Template

Policy template is a configuration primitive for overriding a built-in profile or creating a custom profile. It is used to map a profile name to a path. See config/config.template.yml for an example.

Threat Model

PMG trusts policy files and the operator's CLI as the source of intent. The sandbox implementation enforces what the policy declares. Translation from PMG's YAML to the native sandbox format must not weaken it. Variable interpolation consumes only trusted sources.

Detailed assumptions

• Policy files are trusted
• Policy enforcement is a sandbox implementation concern
• YAML to sandbox specific policy translation must not make the policy weaker than the original policy
• Variable interpolation in policy files must consider only trusted sources

Enforcement

The sandbox implementation currently only support block mode. This means, any policy violation will block the execution of the package manager command.

Debug

MacOS

OSX sandbox implementation is based on Chromium OSX Sandbox Design and Anthropic Sandbox Runtime. Current implementation does not support identifying sandbox policy violations.

To manually investigate sandbox policy violations, you can use the following command:

APP_LOG_LEVEL=debug APP_LOG_FILE=/tmp/pmg-debug.log pmg --sandbox --sandbox-profile=npm-restrictive npm install express

Find the log tag in the debug log file and use it to investigate the sandbox policy violation.

grep "PMG_SBX_" /tmp/pmg-debug.log

Use log(1) to filter the log file by the log tag.

log show --last 5m --predicate 'message ENDSWITH "PMG_SBX_${TAG}"' --style compact

Linux

Linux sandbox implementation uses Bubblewrap for namespace-based isolation. Enable debug logging to see translated sandbox arguments:

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:

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:

# 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
• https://geminicli.com/docs/cli/sandbox/
• https://github.com/containers/bubblewrap