Jump to: Permissions, Usage, Shell integration, Configuration, Project status, Package managers, Troubleshooting, Contributing
Run Node.js code safely with permissions, preventing rogue dependencies from compromising your system.
node-safe
is an easy to use companion for your regular node
and uses native macOS sandboxing features to control file system access, networking and process spawning to keep your workstation safe.
As developers using Node.js and npm we routinely run a lot of untrusted code directly on our workstations.
Let this sink in: Any npm package you're using has full file system and network access and can exfiltrate your data at will. π± We kinda just close our eyes and hope for the best here, which seems to not work anymore:
Deno (a Node.js alternative/competitor) has a built-in permission system for running code, but besides running in a slow VM or Docker container there hasn't been a simple option available to run Node.js code safely.
See Usage below for more ways to install and use
node-safe
. Note that only macOS is supported currently.
npm install --global @berstend/node-safe
# or use a temporary version:
npx @berstend/node-safe -e "console.log('hello world')"
Let's take this script as an example, which unceremoniously reads your private SSH key:
// example.js
const fs = require("fs")
console.log(fs.readFileSync(process.env.HOME + "/.ssh/id_rsa").toString())
Regular node
does not restrict file system access by default π
node example.js
# => -----BEGIN RSA PRIVATE KEY----- (...)
node-safe
will block file system reads and writes by default π€
node-safe example.js
# => Error: EPERM: operation not permitted, open '/Users/foo/.ssh/id_rsa'
Simple command line options (like --allow-read
) are supported to configure permissions:
# allow reading any file
node-safe --allow-read example.js
# => -----BEGIN RSA PRIVATE KEY----- (...)
# allow reading only that specific file
node-safe --allow-read="$HOME/.ssh/id_rsa" example.js
# => -----BEGIN RSA PRIVATE KEY----- (...)
Elevator pitch:
.node-safe.json
files.node-safe
instead of node
or teach your regular node
command to support sandboxing.npm
, npx
or yarn
are supported as well.node-safe
is a light-weight wrapper that uses your existing node
version.The main reason why running Node.js code is so risky is the complete lack of restrictions, any npm package (or any of it's often hundreds of nested dependencies from a multitude of developers) has:
The question arises why we allow our code to run with all these permissions, when most often they're not needed.
macOS ships with a very robust sandbox implementation (in fact most of your macOS apps run sandboxed). It's a little underdocumented (to put it mildly) but while looking into it more I realized it could be packaged in a neat way to enforce a variety of restrictions while working with Node.js, through easy to use configuration options.
node-safe
is aiming at making these powerful sandbox features available on an everyday basis while working with Node.js: It acts as an API compatible "replacement" for node
, with some additional command line options to configure permissions.
When node-safe
is called it will dynamically generate, based on the desired permissions, a custom profile to instrument the macOS sandbox and run a sandboxed instance of your regular Node.js binary using that profile.
Package managers like npm
or yarn
can be used sandboxed as well, to contain post installation and package.json scripts.
There's two ways how you can use node-safe
and friends:
node-safe
, npm-safe
, yarn-safe
commands directly (installed globally or locally)
node
, npm
, yarn
commands but with optional sandboxing
-safe
commands but requires modifying your $PATH
once.node-safe.json
file is found in the projectCan't decide? See Typical usage for an opinionated take on the preferred way to use node-safe
.
node-safe
does not includenode
, it will use whichevernode
version you have installed in your system. To install Node.js and make switching between versions a breezenvm
is a good option.
You can install node-safe
as global script binary and run your code with node-safe
instead of node
:
npm install --global @berstend/node-safe
# then run a script
node-safe myscript.js
# or use Node's eval feature
node-safe -e "console.log('hello world')"
# or start an interactive REPL
node-safe
In addition to node-safe
this will make npm-safe
, npx-safe
and yarn-safe
available globally.
npx
If you just want to try out node-safe
without really installing it use npx
(which ships with npm
):
npx @berstend/node-safe -e "console.log(require('fs').readFileSync('/etc/hosts').toString())" # fails
npx @berstend/node-safe --allow-read -e "console.log(require('fs').readFileSync('/etc/hosts').toString())" # works
npx @berstend/node-safe --allow-read --allow-net myscript.js # run a script with file read + network permissions
npx @berstend/node-safe # start a REPL with no permissions (it can't even read it's own history file π)
npx @berstend/node-saf --allow-read-write="~/.node_repl_history" # sandboxed REPL with history
npx --ignore-existing @berstend/node-safe # to always use a freshly-installed temporary version
# To use the package manager binaries provided by node-safe:
npx --package @berstend/node-safe npm-safe
npx --package @berstend/node-safe npx-safe
npx --package @berstend/node-safe yarn-safe
You can install node-safe
as a local dev dependency in an existing Node.js project:
yarn add --dev @berstend/node-safe
# or
npm install --dev @berstend/node-safe
Run the following command from the root folder of that project:
$(npm bin)/node-safe -e "console.log('hello world')" # will use ./node_modules/.bin/node-safe
In addition to node-safe
this will make npm-safe
, npx-safe
and yarn-safe
available locally in the project.
In a typical project custom package.json scripts are used to run things and often implicitly call node
(like a mocha
test runner). To run package.json scripts safely make use of npm-safe
or yarn-safe
:
# before (not sandboxed)
yarn run build
npm run build
# run the build script defined in the package.json
yarn-safe run build
npm-safe run build
# allow writing to the ./dist folder during build
yarn-safe --allow-write="./dist/**" run build
npm-safe --allow-write="./dist/**" run build
or when node-safe
has been installed as a dev dependency in the project:
# run the build script defined in the package.json
$(npm bin)/yarn-safe run build # will use ./node_modules/.bin/yarn-safe
$(npm bin)/npm-safe run build # will use ./node_modules/.bin/npm-safe
Everything that happens when running a package.json script (including nested commands, child processes, etc) will be sandboxed and restricted based on the configured permissions.
Simply using npm or yarn to install dependencies can already compromise your machine as lifecycle scripts like postinstall
are executed with unrestricted access. To run package manager commands sandboxed:
# Install all dependencies listed in package.json
yarn-safe install
npm-safe install
# Install 'got' as new dependency
yarn-safe add got
npm-safe install got
# prepublish hooks can execute arbitrary code as well
npm-safe publish
# or when installed as a dev dependency
$(npm bin)/yarn-safe install # will use ./node_modules/.bin/yarn-safe
$(npm bin)/npm-safe install # will use ./node_modules/.bin/npm-safe
npm-safe
and yarn-safe
are optimized for your happiness and will allow certain permissions by default.
By using a .node-safe.json
configuration file it's possible to define (and share) sandbox permissions scoped to specific package manager scripts or commands.
node-safe
does not includenode
, it will use whichevernode
version you have installed in your system. To install Node.js and make switching between versions a breezenvm
is a good option.
node
, npm
, yarn
commands with sandboxingWouldn't it be great if we could teach good old node and npm permission features? Well, we can! π
You can use the shell integration below to make node-safe
, npm-safe
, npx-safe
and yarn-safe
the default when their respective node
, npm
, npx
, yarn
command is called.
We do this by prepending the $PATH
variable (which tells your system in which folders binaries can be found) with our own folder containing small script binaries as shims. When these are invoked they will find and use the regular node
binary to run node-safe
, which takes it from there.
Things of note when using the regular node
, npm
, yarn
commands with node-safe through the shell integration:
--enable-sandbox
or toggle sandboxing automatically by using use per project .node-safe.json
config files.node-safe
, npm-safe
, yarn-safe
commands will apply to your regular node
, npm
, yarn
commands as wellnode --enable-sandbox --allow-read="./comics/**" --allow-net # possible with the shell integration
To add the node-safe shell integration download this file to ~/.node-safe/env.sh
:
mkdir ~/.node-safe
curl -o ~/.node-safe/env.sh https://raw.githubusercontent.com/berstend/node-safe/master/shell/env.sh
Add this line at the end of your ~/.bashrc
, ~/.profile
, or ~/.zshrc
file(s) to have it automatically sourced upon login:
# This loads the shell integration of node-safe
export NODE_SAFE_DIR="$HOME/.node-safe" && [ -s "$NODE_SAFE_DIR/env.sh" ] && source "$NODE_SAFE_DIR/env.sh"
If the files don't exist yet just create them:
touch ~/.zshrc && touch ~/.bashrc
Restart your terminal session for changes to have an effect. To verify everything works:
node --sandbox-version
# => π€ node-safe v0.1.2
To disable the shell integration just remove the line we added earlier and restart your terminal.
I recommend using a .node-safe.json
config file when working on projects. You don't need to remember to use commandline arguments and your team members get to enjoy the sandboxing permissions you've created as well.
Adding a config file to your project also allows you to add this cool badge to your readme π
[![Works with node-safe](https://img.shields.io/badge/%F0%9F%A4%A0%20node--safe-enabled-brightgreen)](https://github.com/berstend/node-safe)
As for the installation: Go for the implicit usage with the shell integration after you played with node-safe
a bit. You can continue using node
and package managers as normal but whenever a .node-safe.json
file is found in one of your projects it will automatically keep you safe with sandboxing.
When creating a new project it's important to enable sandboxing from the start, so you're already safe when installing the first dependencies. When using the implicit mode you can do that by simply creating an empty .node-safe.json
file:
# create a folder for a new project
mkdir new-project-idea && cd new-project-idea
# activate sandboxing with default permissions with an empty config file
touch .node-safe.json && yarn init --yes
# all node, npm, yarn commands executed in this project will now run sandboxed π
Once you run into permission errors you can start whitelisting certain permissions in the .node-safe.json
file as needed.
By default most permissions are restricted when running node-safe
.
The naming to configure permissions has been inspired by Deno:
-safe
commands but the implicit usage (when using the -safe
commands sandboxing is already enabled by default)node-safe
on an unsupported platform (Windows, Linux) will show an error by default, when this option is set sandboxing will be skipped and node executed normallynode-safe
will print a short message to stdout to let you know it's running (only in interactive terminals, not when piping the output or similar)node
)Learn more about Files & Folders further down. Having trouble finding the right permissions to allow? See Troubleshooting
node-safe
is very configurable. It reads it's configuration options from 3 places:
.node-safe.json
config file (usually in the project directory next to the package.json)All configuration options and permissions can be used with npm-safe
, npx-safe
and yarn-safe
as well.
When using the shell integration the regular node
, npm
, npx
, yarn
commands will support these new options too.
node-safe
is meant to be used instead of node
, it supports all regular node
arguments (it will pass them on) in addition to a few new ones to control the sandbox.
Usage: node-safe [permissions] [node options] [ script.js ] [arguments]
Multiple permissions can be configured at once:
node-safe --allow-read="./data/*.json" --allow-write="[temp]/**,./logs/*.txt" script.js
The package managers follow the same pattern:
npm-safe [permissions] <command> [arguments]
npx-safe [permissions] [options] <command>[@version] [command-arg]
yarn-safe [permissions] <command> [flags]
When using the shell integration and regular commands the sandboxing must be enabled (or toggled by a config file):
node --enable-sandbox --allow-read="./data/*.json" script.js
npm --enable-sandbox --allow-write="[temp]/**" install electron
All options can be defined as environment variables as well, prefixed with NODE_SAFE_
and all uppercase:
NODE_SAFE_DEBUG_SANDBOX=true NODE_SAFE_ALLOW_READ="**.png" node-safe script.js
node-safe
and friends will check if a file named .node-safe.json
exists in the current directory or it's parents.
An empty
.node-safe.json
file will enable the sandboxing with default permissions when using the implicit mode where sandboxing is turned off by default.
Here's a simple .node-safe.json
:
{
"$schema": "https://repo.node-safe.com/schema/node-safe.schema.json",
"$readme": "https://github.com/berstend/node-safe#readme",
"node": {
"allow-read": "./data/**",
"allow-read-write": "./build,./build/**",
"allow-net-outbound": true
}
}
$schema
and $readme
are optional, but the schema enables IntelliSense while typing in editors like VSCode π:
Relative paths in the config file will resolve from the directory containing the config file, not the directory from which you invoked node/npm/yarn (most often the same but not always).
The config file supports three (all optional) top level properties with permissions:
node
- Permissions that will apply to any node process run in that project (including package managers)scripts
- Define extra permissions that apply when running package.json scriptscommand
- Define extra permissions that apply when running package manager (npm, yarn) commandsAnother example (comments are for explanation purposes only and not valid JSON):
{
"$schema": "https://repo.node-safe.com/schema/node-safe.schema.json",
"$readme": "https://github.com/berstend/node-safe#readme",
// Custom sandbox permissions when running Node.js in this project
"node": {
// Allow reading all reports and assets
"allow-read": "./reports/**.csv,./assets/**",
// Allow writing files to the logs folder
"allow-write": "./logs/**",
// Internet access so the app can fetch the latest conversion rates
"allow-net-outbound": true
},
// Extra permissions when running specific package.json scripts
"scripts": {
// Applies to any script
"*": {
// Required by rimraf (an npm package) to delete the results folder
// We use "clean" in multiple scripts, so we allow it for all scripts
"allow-read-write": "./results/,./results/**",
// Allow executing rimraf
"allow-run": "./node_modules/rimraf/**"
},
"generate-reports,delete-reports": {
// Only allow write access when generating or deleting reports
// Note: We could have used "*-reports" as well as wildcards are supported
"allow-read-write": "./reports/,./reports"
},
"serve": {
// Allow a local http server to run and bind to ports
"allow-net-inbound": true,
"allow-run": "./node_modules/http-server/**"
}
},
// Extra permissions when running built-in package manager commands
"commands": {
// One of our dependencies has a `postinstall` script that downloads something to the temp folder
// Note: For convenience any package manager command that installs packages will match "install"
// So no need to list "add", "upgrade", etc individually
"install": {
"allow-read-write": "[temp]/**",
// The dependency uses system curl for the download
"allow-run": "[bin]/curl"
}
}
}
If multiple entries match (e.g. npm run delete-reports
will match node
, scripts:*
and scripts:delete-reports
) the permissions of the matching entries will be merged.
node
The underlying permissions affecting all invocations of node-safe
, npm-safe
or yarn-safe
. If additional permissions for specific scripts or commands are defined and match they will be merged.
scripts
Add specific permissions when package.json scripts are called (e.g. npm run-script foo
, yarn run foo
, etc). Comma separated lists of script names and wildcards are supported. Only the first script invoked will be considered for matching.
commands
Add specific permissions when package manager commands are called (e.g. npm whoami
, yarn upgrade-interactive
, etc). Comma separated lists of script names and wildcards are supported. Without a space in the object property only the package manager command will be matched for portability ("info" will match npm info
as well as yarn info
). Commands that trigger package installations are additionally matched as "install" for convenience.
node-safe
tries to make it as convenient as possible to not just use a blanket --allow-read
but be more specific.
Note: If you just specify a folder it's taken literally and won't match descendents unless globbing is used:
node-safe --allow-read="./assets/" # won't allow reading ./assets/foo.png
node-safe --allow-read="./assets/*" # will allow reading ./assets/foo.png
node-safe --allow-read="./assets/*" # won't allow reading ./assets/content/foo.png
node-safe --allow-read="./assets/**" # will allow reading ./assets/content/foo.png
Relative paths are supported and will internally be resolved to absolute ones.
node-safe --allow-write="./logfile.txt" script.js # allows writing to that specific file
node-safe --allow-write="./logs/*" script.js # allows writing files to that specific folder
node-safe --allow-write="../../assets/screenshots/*.png" script.js # allows writing .png files to the screenshots folder
When used in commandline or environment options they're resolved relative to the current working directory (from which you invoked node-safe
or the package managers), in config files they're resolved relative to the config file.
Globbing (aka wildcards) are supported and will internally be translated to regex.
node-safe --allow-read="./*.png" # allows reading .png files in the current directory
node-safe --allow-read="./**.png" # allows reading .png files in the current directory + nested directories
node-safe --allow-read="**.png" # allows reading .png files from anywhere
node-safe --allow-read-write="**/foo/*.png" # allows reading/writing .png files from directories named foo
node-safe --allow-write="**/foo/**.png" # allows writing .png files from foo directories and it's children
node-safe --allow-write="/Users/*/Documents/test/**" # allows writing in `~/Documents/test/` + sub folders
node-safe --allow-write="./assets/**" # allows deleting files in ./assets but not deleting the ./assets folder
node-safe --allow-write="./assets/**,./assets" # allows deleting files in ./assets and the ./assets folder
node-safe --allow-read-write="[project]/**" # full read/write file access but only in the project folder
Using a single star will not match sub directories, a double star (known as "globstar") can be used for that.
A couple of shorthands are supported for convenience and will internally resolve to their absolute paths.
[cwd]
- resolves to the current working directory[temp]
- resolves to the systems temporary directory[home]
- resolves to the home directory (~/
can be used as well)[script]
- resolves to the directory containing the target script (if any)[project]
- resolves to the closest directory (we traverse up) containing a package.json
file[config]
- resolves to the closest directory (we traverse up) containing a .node-safe.json
file[bin]
- resolves to a list of all directories found in the $PATH
(not ./node_modules/.bin
)The shorthands behave like regular folders and can be combined with globbing or used in lists:
node-safe --allow-write="[temp]/**" # allows writing anything in the temporary directory or subdirectories
node-safe --allow-write="[temp]/**.log" # allows writing only .log files in the temporary directory
node-safe --allow-read="[project]/assets/**" # allows reading anything from the project's assets directory
node-safe --allow-run="[bin]/curl" # allows running curl found at `/usr/bin/curl`
node-safe --allow-run="[bin]/**" # allows running any executable found in $PATH
Instead of a single file or folder a comma separated list can be provided.
node-safe --allow-write="[temp]/**,./assets/**" # allows writing anything in the temporary directory + assets folder
node-safe --allow-read="./file1.txt,./file2.txt" # allows reading these two files
node-safe --allow-write="**/.png,/Users/foo/.bashrc" # allows writing .png files anywhere + the .bashrc file to be read
If we would block everything the node process wouldn't even be able to start. π We try to strike a balance between usability and security with sane defaults, to protect your machine while not being annoying to use.
node-safe
The default sandbox node-safe
generates is locked down pretty heavily by default and whitelist (not blacklist) based.
By default blocked:
node
)By default allowed:
.js
/.json
, etc.) from certain directories
node_modules
folders, the directory the script is in as well as the project directory.npm-safe
, yarn-safe
)We grant a few extra default permissions when sandboxing a package manager. If we don't they would not be usable out of the box. To still make this as safe as possible we do some light parsing of the command line arguments to understand the "intent" and only allow what is strictly needed to run that type of package manager command.
By default allowed:
./package.json
and ./node_modules/**
Note for package authors and private package users:
node-safe
will block access to your ~/.npmrc
by default. This is intentional: If you're signed in it contains your npm access token that can be used to update/publish packages. This file has been a juicy target in supply chain attacks and account takeovers before, hence the decision to block access by default.
If you need to be authenticated (while publishing or accessing private packages) you need to specifically allow access:
npm-safe --allow-read-write="~/.npmrc" login # or "whoami", "publish", etc
For even more security consider combining this with using a NPM_TOKEN
environment variable.
Deno implemented a permission system from the start (as one of it's main differentiators to Node.js). Interestingly node-safe
has a huge advantage by using native sandboxing features baked into the OS: Restrictions will apply to all child processes as well, whereas Deno has no control over what spawned processes can do. π
node-safe
borrowed it's CLI argument naming heavily from Deno though as to not reinvent the wheel.
One aspect where Deno allows more fine-grained control is networking: It supports a whitelist of domains/IPs, whereas node-safe
can only enable/disable networking altogether (inbound & outbound separately though).
We also didn't implement an --allow-env
equivalent to Deno, it's possible but I feel it'd be more annoying than useful.
The concept works and the sandboxing is robust, though not everything is fully fleshed out yet - consider this iteration of node-safe
"early access" of sorts and feedback is very welcome.
The main thing we want to work on is probably relaxing some (safe) defaults, as to make the out of the box experience nicer when working on typical projects involving a lot of the common tooling (linting, transpiling, building code, etc).
We could also consider adding something like a --allow-project
flag, or shipping with presets.
Other things that might not be perfect yet:
node
Feedback, ideas, discussions and bug reports are welcome!
sandbox-exec
is macOS only, though there might be ways to support other platforms as wellIf there's sufficient interest I'll be looking into integrating a suitable sandbox implementation for Windows as well. Sandboxie seems like the most likely candidate here. Here's documentation on their supported restrictions and file access. If you're a windows based dev feel free to play with Sandboxie and report your findings in an issue to start the discussion. π
Linux has the advantage that Docker/LXC runs natively with little performance overhead. Still, looking into a light-weight sandboxing option so node-safe
works on all major plattforms with the same user-facing API could make sense.
runsc do
without Docker), LXC/LXD, chroots, etcIf you're interested in helping researching a suitable sandbox implementation for another platform: We're looking for a fast (no lengthy boot), non-root implementation we can control through the command line or environment. Minimum control we need is file system access (read/write separately), networking (at least outbound connections) and process forking. Ideally the filtering is file path based and supports extended (bash 4 like) globbing or regex.
When using node-safe
you'll eventually run into permission errors when only using the default permissions. This is perfectly fine as the idea is to exert control and only whitelist specific access when needed.
If you're in a pinch and don't have time to fine-tune the perfect permissions go with this:
node-safe --allow-read-write="[project]/**" --allow-run="[bin]/**,[project]/node_modules/**" --allow-net
This will allow reading/writing in the project directory, executing any binaries your system or dependencies might come with and network access. Even this is still a whole lot better than unrestricted access to your whole system.
Error: EPERM: operation not permitted, scandir '/Users/foobar/folder'
This error can happen due to lack of read access to a folder. Make sure to use read/write permissions as write permissions alone don't allow the process to read files.
Also make sure you whitelist a folder if needed and not only it's contents:
"./folder/**" # does not give access to the folder itself, only files and folders in it
"./folder,./folder/**" # gives access to the folder itself as well as it's contents
If the errors from the Node.js process don't help you understand what needs whitelisting have a look at Debugging.
./node_modules/.bin
to be executedAssuming a package.json script using rimraf
to clear a directory:
"scripts": {
"clean": "rimraf dist/*"
},
Running this script would result in an error when running sandboxed with default permissions:
yarn-safe run clean
/bin/sh: /Users/foobar/project/node_modules/.bin/rimraf: /usr/bin/env: bad interpreter: Operation not permitted
The error is a bit misleading, as node_modules/.bin/rimraf
is a symlink. By using ls -lh
or the macOS sandbox logs we learn the actual location of the script being blocked from executing is ./node_modules/rimraf/bin.js
.
We need to therefore whitelist ./node_modules/rimraf/
instead of ./node_modules/.bin/rimraf
:
NODE_SAFE_ALLOW_RUN="./node_modules/rimraf/**" NODE_SAFE_ALLOW_READ_WRITE="./dist,./dist/**" yarn-safe run clean
# => β¨ Done in 0.39s.
In the example we additionally allow file read/write access to that folder and it's contents so rimraf
can delete it.
All binaries in node_modules/.bin
are symlinks, when configuring permissions the real path must to be used here as well:
ls -lh ./node_modules/.bin/tsc
# => ./node_modules/.bin/tsc -> ../typescript/bin/tsc
# this is an example of the implict mode of using node-safe, we use `yarn run` with sandboxing enabled
yarn --enable-sandbox --allow-run="./node_modules/typescript/bin/tsc" --allow-write="./tsconfig.json" run tsc --init
# => "Created a new tsconfig.json file"
We will improve the default TS experience in a future update by whitelisting certain things by default.
When packages are installed their postinstall lifecycle scripts will be executed (as long as it's only using the node binary). This is a pretty safe default as all permissions (restricted file system access, etc) are enforced for child processes as well.
Some packages (like electron
) might run more elaborate postinstall scripts that will be blocked by the default sandbox:
yarn-safe add electron
error /Users/foobar/project/node_modules/electron: Command failed.
Exit code: 1
Command: node install.js
Looking at the macOS sandbox logs we see that electron tries to write some files to the temp folder as well as ~/Library/Caches
during installation, which we need to explicity allow:
NODE_SAFE_ALLOW_READ_WRITE="[temp]/**/electron**,[home]/Library/Caches/electron/**" yarn-safe add electron
It also tries to execute the sysctl
binary for some reason but it's fine to keep that blocked. π
Using a browser automation framework is a pretty extreme case, as the sandbox applies to any child processes as well we effectively sandbox a full Google Chrome browser when launching it through puppeteer or playwright. π
To make this work we need to whitelist the minimum permissions Chrome requires to be able to run.
Puppeteer will download the browser binaries to it's own node_modules
folder after installation, hence we need to allow running binaries from that location:
--allow-run="**/node_modules/puppeteer/**,[bin]/**"
We additionally allow executing system binaries as Chrome is using some when launching.
Puppeteer will by default create and use a temporary browser profile folder in temp:
--allow-read-write="[temp]/**"
Chrome cannot launch when not being able to bind to sockets: --allow-net
Special situation: Sandboxing a sandbox
Chrome itself is using the macOS sandbox, we need to instruct Chrome not to use it as we'll already sandbox the process.
To make this convenient node-safe
will expose an environment variable named IS_SANBDOXED
that the code can check for.
All together now:
// pptr-demo.js
const puppeteer = require("puppeteer")
const launchOptions = {
headless: false,
defaultViewport: null,
args: [],
}
// Check if we're running in a sandbox already
if (process.env.IS_SANDBOXED) {
launchOptions.args.push("--no-sandbox")
}
puppeteer.launch(launchOptions).then(async (browser) => {
console.log("Starting..")
const page = await browser.newPage()
await page.goto("https://example.com")
console.log("β¨ Launched sandboxed browser!", await page._client.send("Browser.getVersion"))
await page.screenshot({ path: "screenshot.png", fullPage: true })
await browser.close()
})
node-safe --allow-write="[temp]/**,./screenshot.png" --allow-run="**/node_modules/puppeteer/**,[bin]/**" --allow-net pptr-demo.js
To debug a problem with node-safe itself you want to enable verbose debug logging:
NODE_SAFE_DEBUG_SANDBOX=true node-safe foobar.js
# or
node-safe --debug-sandbox foobar.js
If you run into permission errors but can't figure out what the problem is you want to check the macOS sandbox logs.
You can either open Console.app
, start recording and filter for "sandbox" or use this nifty terminal command:
log stream --style syslog --predicate 'process == "sandboxd" && eventMessage CONTAINS[c] "deny"' --info | grep com.apple.sandbox.reporting
You will see entries like this one that should help you understand what to whitelist:
Sandbox: node(1071) deny(1) file-read-data /private/var/run/resolv.conf
In case you want to eject the sandbox profile that node-safe
generates and use it directly:
node-safe --print-sandbox foobar.js > profile.sb
sandbox-exec -f profile.sb node foobar.js
Using sandbox-exec
directly can be useful when occasionally debugging permissions of external processes :
# launch Chrome Canary with all permissions but only allow writing into the temp directory
sandbox-exec -p '(version 1) (allow default) (deny file-write*) (allow file-write* (subpath "/private/tmp/fooprofile/") (subpath "/private/var/"))' /Applications/Google\ Chrome\ Canary.app/Contents/MacOS/Google\ Chrome\ Canary --no-sandbox --user-data-dir=/private/tmp/fooprofile
# or to deny everything
sandbox-exec -p '(version 1) (debug all) (deny default)' curl https://example.com
Please create an issue to discuss what you have in mind before working on a PR. :-)
Copyright Β© 2021, berstendΜΜΜΜΜΝΝΜΜ²Μ«Μ‘ΜΉΜ ΜΝΝ. Released under the MIT License.