Extension Sandboxing

Phylum's CLI extensions allow developers to impose additional restrictions when
running third party applications. This can protect the system from damage when
these applications contain vulnerabilities or execute untrusted code.

Example

The following code provides an example on how you could sandbox cat to only
allow access to files in the current working directory or below it:

import { PhylumApi } from 'phylum';

// Ensure a file path is passed as the only argument.
if (Deno.args.length !== 1) {
    console.log("USAGE: local-cat <FILE>");
    Deno.exit(123);
}

// Run `cat` in our sandboxed environment.
const output = PhylumApi.runSandboxed({
    cmd: 'cat',
    args: [Deno.args[0]],
    stdout: 'inherit',
    stderr: 'inherit',
    exceptions: {
        read: ['./'],
        write: false,
        run: false,
        net: false,
    },
});

// Propagate `cat`'s exit code.
Deno.exit(output.code);

When running this against a file in your local directory, it will print its
content, otherwise, you'll see cat printing the following error:

cat: /tmp/illegal: Permission denied

The important part in this code snippet is the exceptions field. By default
access to most system resources is restricted, so if you want to access them
from within the sandbox you'll have to add an exception.

Available fields for exceptions are read, write, run, and net. The run
permission is a superset of read that allows for execution. While read,
write, and run accept either a path to be allowed or a boolean, net only
allows for a boolean value.

Limitations

The PhylumApi.runSandboxed method is the only recommended means of spawning
child processes from an extension. The Deno.run method should be avoided
in order to prevent extensions from escaping the sandbox, and will be disabled
in a future version.

The PhylumApi.runSandboxed method is only allowed to request permissions that
are at least as restrictive as the ones specified in the manifest.

Advanced Usage

By default, access to some paths is granted automatically to make extension
sandboxing easier and ensure portability between operating systems. If you want
more control over your sandboxing exceptions, you can pass strict: true to the
exceptions:

const output = PhylumApi.runSandboxed({
    cmd: 'cat',
    args: [Deno.args[0]],
    stdout: 'inherit',
    stderr: 'inherit',
    exceptions: {
        // Discard all default sandboxing exceptions.
        strict: true,

        // You can see the required additional exceptions here.
        // These paths might differ between operating systems and distributions.
        run: ['/usr/bin/cat', '/usr/lib'],

        // These are identical to our previous example.
        read: ['./'],
        write: false,
        net: false,
    },
});

Finding Required Exceptions

It can be somewhat difficult to find out which exceptions you need to add to
allow your application to run without any errors. To simplify this a bit you can
use the find-permissions extension.

This extension will run a script against each path in your filesystem
recursively to validate what the most granular necessary exceptions are. Once
completed, it will output all necessary paths.

Most invocations of this extension will probably look something like this:

phylum find-permissions \
    --read \
    --write \
    --pre-bin ./setup.sh \
    --bin ./test.sh \
    --post-bin ./cleanup.sh

By passing both --read and --write we check for both permissions at the same
time. The test.sh script should contain the executable we want to sandbox; in
our example it would run cat against some local files. The --pre-bin and
--post-bin are optional, but here we could setup and remove local files to run
cat against for example.

Since this crawls your entire directory tree, it might take some time. If you
don't need file-level granularity you can help speed it up by passing
--skip-files.