* feat(sandbox): report landlock seccomp denials via pmg sandbox violations The landlock driver's seccomp supervisor already emitted structured deny events over the audit socket, but the driver drained them to io.Discard, so the violation cache was never populated on Linux and violations list / explain always came up empty. Capture the events at the driver, enrich them with access mode and process name, and implement BestEffortViolation mirroring the seatbelt reporter: failure-only collection, seccomp_deny events only, (kind, target) dedupe. The platform-neutral cache/list/explain pipeline picks it up unchanged. Only the seccomp deny-list layer is observable; denials made by the Landlock LSM itself (allow-list boundary, delete/rename, network) fail in-kernel with no userspace signal and are documented as out of scope. Also make the explain renderer driver-neutral: the raw-log label was hardcoded as "Seatbelt log" and an empty correlation ID printed a blank value. * fix: address review findings on landlock violation reporting Report the deny rule that fired, not the requested access: an O_RDWR open denied by a read-only rule now surfaces as a read denial with an effective override suggestion (allow write= prunes only deny_write). The matched rule path is emitted as rule_path and mapped to RuleTarget, bringing the "Matched rule:" line to parity with seatbelt. Dedupe deny events by (kind, path) at capture time so a retry loop on one denied path cannot fill the buffer and evict a later distinct denial; the cap now bounds distinct denials. Stamp deny events with a timestamp (they rendered "ts":0 in the raw log) and default unknown syscalls to generic_deny instead of fs_write. * refactor: single source for the deny dedupe key Capture-time and extract-time dedupe must agree on what identifies a denial; building the key in two places risks them drifting apart. * fix: bound the capture dedupe map by marking keys only on append seen grew for every distinct deny key even after the buffer was full, and keys carry attacker-chosen path bytes — a hostile process looping over crafted unique denied paths could grow the pmg parent's memory for the run's duration, defeating the cap. Marking keys only when the event is appended bounds the map at the cap and keeps the one-time drop warning reachable for distinct denials past it. * docs(sandbox): AppArmor userns fix for the Landlock driver on Ubuntu 23.10+ The shim fails with "install seccomp: ... permission denied" when kernel.apparmor_restrict_unprivileged_userns=1. Document the per-binary AppArmor profile as the recommended fix and the sysctl as the blunt alternative. * docs(sandbox): drop em dashes from the landlock sections * fix(doctor): cover landlock in the AppArmor userns probe The warn detail only named the bwrap failure and the only suggested fix was the system-wide sysctl. Name the landlock shim error too and suggest the per-binary AppArmor profile first, pointing at the new docs section.
29 KiB
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$CWDand$HOMEis always denied to prevent arbitrary code execution via repository hooks. - Git config is blocked by default: Write access to
.git/configis denied unlessallow_git_config: trueis set in the policy. This prevents credential helper manipulation. - Runtime overrides remove only exact-match deny entries: When
--sandbox-allowadds 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 inallow_readorallow_write(policy or runtime) opts out of the mandatory deny for that credential file..git/hooksdoes 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.
Environment Variable Protection
Many supply chain attacks steal credentials from the process environment rather than from files
(e.g. AWS_SECRET_ACCESS_KEY, GITHUB_TOKEN, NPM_TOKEN, TWINE_PASSWORD). When the sandbox is
enabled, PMG scrubs a default-deny list of credential-bearing variables from the package manager
child process before it is spawned. The built-in list is an explicit, curated set of known secret
names. See DANGEROUS_ENV_VARS. There are deliberately no generic
*_TOKEN / *_SECRET catch-alls in the default, because broad wildcards there would risk clipping
legitimate build variables.
Scrubbing is platform-independent (it filters the environment regardless of the OS sandbox driver)
and runs as the last step before launch, after project overlays and --sandbox-allow overrides are
merged. Scrubbed variable names (never values) are logged at info level. Run with --debug to
see what was removed.
The shared base profiles (npm-restrictive, pypi-restrictive) allow no environment variables.
Each package manager's leaf profile (npm, yarn, bun, pnpm, npx, pip, pipx, uv,
uvx, poetry) re-allows only the variables that package manager legitimately needs via an
environment.allow block, so package managers keep working:
environment:
# Re-permit only what this package manager needs; everything else in the
# default deny list stays scrubbed. allow always wins over deny.
allow:
- NPM_TOKEN
- npm_config_*
# Optionally scrub more than the default. Glob patterns are supported here
# (they are intentionally not in the built-in default).
deny:
- MY_CUSTOM_SECRET
- "*_TOKEN"
Accepted trade-off: a leaf profile re-allows its own package manager's auth token, so a
malicious package executed during npm install can read NPM_TOKEN, but not a yarn or bun token, a
PyPI token, AWS key, or other cloud/secret-manager credential, which stay scrubbed. The reverse
holds for the other profiles. This is deliberate: the package manager needs its own auth token to
function.
Configs written before the profile split may still map npm, yarn, or bun to npm-restrictive, pnpm
to pnpm-restrictive, or pip, pip3, poetry, or uv to pypi-restrictive. PMG re-maps these legacy
defaults to the per-package-manager leaf profile at load time, unless a custom policy template
overrides the legacy name, in which case the template wins as before.
Matching is on the variable name, case-insensitive, and supports the same glob syntax as filesystem
rules. A small set of core variables (PATH, HOME, LC_*, TZ, ...) is never scrubbed.
Requirements
- Linux kernel 5.13+ with Landlock enabled (default, no external dependencies)
- Bubblewrap on Linux (fallback for kernels < 5.13, or when
PMG_SANDBOX_DRIVER=bubblewrapis set) - Seatbelt on MacOS
- On Ubuntu 23.10+, an AppArmor profile granting pmg unprivileged user namespaces. See AppArmor blocks the Landlock driver
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.ymlfile. 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.
Run pmg sandbox doctor to see platform specific sandbox setup and driver status. Continue using
PMG as usual, sandbox will be applied to configured package managers automatically.
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
Sandbox Profile Commands
Use profile commands to inspect, create, and validate sandbox profiles.
# List built-in and user profiles
pmg sandbox profile list
# Scaffold a user profile that inherits from a built-in
pmg sandbox profile init my-npm --from npm-restrictive
# Open a user profile in $VISUAL / $EDITOR, then validate and lint it
pmg sandbox profile edit my-npm
# Show a profile, or its fully resolved policy
pmg sandbox profile show npm-restrictive
pmg sandbox profile show npm-restrictive --resolved
# Lint a built-in, user profile, or profile file
pmg sandbox profile lint npm-restrictive
pmg sandbox profile lint ./my-profile.yml --strict
# Compare two resolved profiles
pmg sandbox profile diff npm-restrictive pypi-restrictive
pmg sandbox profile edit resolves the profile name to its file under the user profile
directory, opens it in your editor, and re-validates and lints the result when the editor
exits. Built-in profiles are embedded in the binary and cannot be edited; create an editable
copy with pmg sandbox profile init <new-name> --from <builtin>.
To activate a user profile for a package manager, reference it by name in config.yml — no
policy template is needed for profiles in the user profile directory:
policies:
pnpm:
enabled: true
profile: my-pnpm
Policy templates (see below) are only needed to override a built-in profile name or to load a policy file from outside the user profile directory.
Sandbox Debug Commands
Use these commands when a sandboxed package manager command fails and you need to inspect why.
# Check sandbox driver availability and host setup
pmg sandbox doctor
# List recent sandbox denials captured by PMG
pmg sandbox violations list
# Explain the latest captured denial and show a suggested override when possible
pmg sandbox explain --last
# Inspect the resolved policy PMG will apply
pmg sandbox profile show npm-restrictive --resolved
pmg sandbox doctor runs platform-specific checks for the current host. Cached violation reports
used by violations list and explain --last are produced by macOS Seatbelt diagnostics and, on
Linux, by the Landlock driver's seccomp supervisor.
Coverage differs by platform. Seatbelt logs every denial, including the default-deny allow-list
boundary. The Landlock driver only reports denials made by its seccomp deny-list layer (reads and
writes of deny_* paths, blocked deny_exec binaries): denials made by the Landlock LSM itself
(operations outside the allow-list, delete/rename, network rules) fail in-kernel with EACCES and
produce no report. deny_write entries outside writable areas are enforced by Landlock rather than
seccomp, so they are likewise not reported. Operational degradation events on the audit socket
(namespace_isolation_unavailable, memfd_open_failed) are not included in violation reports
today; they may be added later. Bubblewrap denials only appear as command errors such as EACCES.
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
# Re-allow a sensitive environment variable that the profile scrubs by default
pmg --sandbox-allow env=AWS_PROFILE aws-cdk-using-package install
# 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, env.
For env, the value is an environment variable name or name glob (e.g. NPM_TOKEN,
npm_config_*) and is kept verbatim. It is not path-resolved. It is an allow-only override that
re-permits a variable the profile would otherwise scrub; allow always wins, so there is no deny list
to edit. If a command fails with an auth error, re-run with --debug and look for a "scrubbed" log
line naming the variable, then re-allow it with --sandbox-allow env=NAME.
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.
Project Overlays
A project overlay is a per-repository allow-set that PMG applies automatically on every run in
that repo, so you do not have to retype the same --sandbox-allow flags. The overlay is local
only, keyed by the repo's git toplevel (CWD when not a git repo), and stored under
<config_dir>/sandbox/overlays/. It is purely additive on top of the resolved policy, never
weakens mandatory denies, and is ignored when global_lockdown is set.
# Save manual allowances for the current repo
pmg sandbox allow write=./.astro net-bind=localhost:4321
# Persist an environment variable allowance so the profile stops scrubbing it
# in this repo (same semantics as --sandbox-allow env=..., but saved)
pmg sandbox allow env=AWS_PROFILE
# Promote the primary violation from the most recent cached report
pmg sandbox allow --last
# Promote every safe FS/exec violation from that report
pmg sandbox allow --last --all
# Allow a sensitive path (e.g. .env, .npmrc) explicitly
pmg sandbox allow --force read=./.env
# Inspect the current repo's overlay
pmg sandbox project show
pmg sandbox project show --json
# List overlays across all known repos
pmg sandbox project list
# Delete the current repo's overlay
pmg sandbox project reset --yes
Presets
A preset is a named, additive-only bundle of allowances for one workload (git hooks tooling, an Astro/Vite/Next.js dev server, ...). Instead of discovering allowances one denial at a time, apply a curated bundle:
pmg sandbox preset list
pmg sandbox preset show git
pmg sandbox allow preset=git preset=astro
Presets can also be attached to a profile via a presets: list. See
sandbox-presets.md for usage and how to author your own.
Notes:
--last/--last --allonly auto-promotes filesystem and exec denials. Network allowances (net-connect,net-bind) and environment allowances (env) must be passed manually astype=valuebecause drivers do not classify network denials yet and environment scrubbing is logged rather than recorded as a violation. Run with--debugto see scrubbed variable names, then persist withpmg sandbox allow env=NAME.pmg sandbox allowrefuses sensitive targets (.env*,.npmrc,.ssh,.aws,.kube,.gnupg, ...) unless--forceis given.- Applied overlay entries are recorded in the audit event log with a
+overlaysource tag so they can be distinguished from--sandbox-allowflags.
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 | Landlock (default, kernel 5.13+) or Bubblewrap (fallback) |
| Windows | No | Not yet supported |
Platform-Specific Limitations
Linux (Landlock, default)
Default sandbox on kernel 5.13+: Landlock provides kernel-native filesystem access control without requiring external binaries or unprivileged user namespaces.
For the architecture, design tradeoffs, and known limitations see sandbox-landlock.md.
Deny enforcement: Deny rules (DenyRead, DenyWrite, DenyExec) are enforced via seccomp user notifications. This introduces a small TOCTOU window (microseconds) between reading the path and responding.
Deny enforcement across the process tree: seccomp-notify resolves the path argument of
an intercepted openat(2) by reading /proc/<pid>/mem of the trapping process. PMG ships
this in a two-stage architecture so enforcement applies to direct targets AND every
descendant (grandchildren, great-grandchildren, etc.):
- The helper process (
pmg __landlock_sandbox_exec) clones a tiny shim (pmg __landlock_shim) withCLONE_NEWUSERand a uid/gid map of0 -> host uid. The shim runs as uid 0 inside a fresh user namespace so it hasCAP_SYS_ADMINin that namespace. - The shim installs the seccomp-notify filter without
PR_SET_NO_NEW_PRIVS(permitted byCAP_SYS_ADMINin the ns). It then applies Landlock andexecves the real target. - Because
NO_NEW_PRIVSwas never set, subsequentexecvecalls in the tree do not resetdumpableto 0, so the helper can keep opening/proc/<pid>/memfor any descendant. Deny rules like~/.sshare enforced for the full process tree.
The user namespace is purely a capability vehicle. Host uid/gid are preserved through the mapping, so targets see the same filesystem ownership they normally would. Tools that refuse to run as root (npm's root-in-container warning) are unaffected because the outside-view uid never changes.
Requirements: unprivileged user namespaces must be enabled (unprivileged_userns_clone=1
on Debian/Ubuntu; default on most modern distros). If disabled, the helper fails with an
EPERM on clone() and the sandbox falls back to Bubblewrap.
Network filtering: Not enforced. Landlock supports TCP port filtering only (V4+, no hostname). PMG's proxy interception provides network control.
PID/IPC namespace isolation: Applied best-effort via CLONE_NEWPID|CLONE_NEWIPC|CLONE_NEWNS.
If unavailable, a warning is printed and the command continues. Set PMG_SANDBOX_DRIVER=bubblewrap
to force Bubblewrap if namespace isolation is required.
/proc access: The sandbox supervisor requires /proc read access. When PID namespace
isolation succeeds, /proc is scoped to the child's namespace. When it fails, /proc
exposes all system processes.
Fallback: If Landlock is unavailable (kernel < 5.13), Bubblewrap is used automatically.
Set PMG_SANDBOX_DRIVER=bubblewrap to force Bubblewrap.
Linux (Bubblewrap, fallback)
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 lockdown (network_via_proxy_only): Fine-grained host:port filtering is not
expressible in Seatbelt, so per-host control happens at the PMG proxy instead. With
network_via_proxy_only: true, the sandbox denies all non-loopback outbound network; only the
running PMG proxy's port is reachable, and profiles with allow_network_bind additionally keep
loopback↔loopback connects open. Raw sockets, QUIC, and arbitrary non-loopback ports are blocked
at the kernel.
Direct DNS is disabled by default (the proxy resolves names); allow_direct_dns: true re-opens
it. The Go profile ships with lockdown enabled.
Lockdown is fail-closed: it requires the proxy flow, and pmg errors out rather than running
without confinement when no proxy is available — including on Linux, where
network_via_proxy_only is not yet supported (the drivers reject it with a clear error, never a
silent fallback).
For local development: plain commands like npm run dev are not sandboxed unless
enforce_always is set; loopback↔loopback traffic keeps working via allow_network_bind (as
noted above); and
proxy-honoring clients reach any destination through the proxy CONNECT path. What breaks under
lockdown is direct non-loopback sockets — tools that ignore HTTP_PROXY/HTTPS_PROXY and
non-HTTP wire protocols (e.g. Postgres or Redis clients pointed at non-loopback hosts). Such
denials render as:
direct network access blocked by network_via_proxy_only — traffic must flow through the PMG proxy (a tool may have ignored HTTP_PROXY/HTTPS_PROXY)
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.
With the Landlock driver, denials made by the seccomp deny-list layer on a failed run are captured
into the violation cache and can be inspected with pmg sandbox violations list and
pmg sandbox explain --last (see Sandbox Debug Commands above for coverage limits).
AppArmor blocks the Landlock driver (Ubuntu 23.10+)
Ubuntu restricts unprivileged user namespaces via AppArmor
(kernel.apparmor_restrict_unprivileged_userns=1, default since 23.10). The Landlock driver needs
one: it re-executes pmg inside a user namespace to install its seccomp filter. With the restriction
active, sandboxed commands fail with:
Error: shim: install seccomp: SECCOMP_SET_MODE_FILTER without NNP (user-ns CAP_SYS_ADMIN required): permission denied
pmg sandbox doctor flags this as the "AppArmor user namespaces" check.
The recommended fix is Ubuntu's own mechanism: an AppArmor profile that grants pmg (and only pmg)
the userns permission. Create /etc/apparmor.d/pmg with the pmg binary path (command -v pmg):
abi <abi/4.0>,
include <tunables/global>
profile pmg /usr/local/bin/pmg flags=(unconfined) {
userns,
include if exists <local/pmg>
}
Load it (persists across reboots; no restart needed):
sudo apparmor_parser -r /etc/apparmor.d/pmg
Alternatively, disable the restriction system-wide. This is simpler but weakens the protection for every binary on the host, so prefer the profile:
sudo sysctl -w kernel.apparmor_restrict_unprivileged_userns=0