CapabilitySet

The CapabilitySet class is the primary way to define what resources your sandboxed process can access. It provides methods for granting filesystem access, blocking network access, and managing command execution.

Constructor

const caps = new CapabilitySet();

Creates an empty capability set. By default, no filesystem paths are accessible and network access is allowed.

Methods

allowPath

allowPath(path: string, mode: AccessMode): void

Grant access to a directory and all its contents.

string

required

Absolute path to the directory. Must exist and be a directory.

AccessMode

required

Access level to grant: Read, Write, or ReadWrite.

Throws an error if the path does not exist or is not a directory.

import { CapabilitySet, AccessMode } from 'nono-ts';

const caps = new CapabilitySet();

// Read-only access to system libraries
caps.allowPath('/usr/lib', AccessMode.Read);

// Read-write access to application data
caps.allowPath('/var/app/data', AccessMode.ReadWrite);

// Write-only access to logs
caps.allowPath('/var/log/app', AccessMode.Write);

allowFile

allowFile(path: string, mode: AccessMode): void

Grant access to a single file.

string

required

Absolute path to the file. Must exist and be a regular file.

AccessMode

required

Access level to grant: Read, Write, or ReadWrite.

Throws an error if the path does not exist or is not a file.

caps.allowFile('/etc/hosts', AccessMode.Read);
caps.allowFile('/var/run/app.pid', AccessMode.ReadWrite);

blockNetwork

blockNetwork(): void

Block all outbound network access. Once blocked, the process cannot make any network connections.

caps.blockNetwork();
console.log(caps.isNetworkBlocked); // true

allowCommand

allowCommand(cmd: string): void

Add a command to the allow list. Commands on the allow list can be executed even if they would otherwise be blocked.

string

required

The command name to allow (e.g., "git", "npm").

caps.allowCommand('git');
caps.allowCommand('npm');

blockCommand

blockCommand(cmd: string): void

Add a command to the block list. Blocked commands cannot be executed.

string

required

The command name to block (e.g., "curl", "wget").

caps.blockCommand('curl');
caps.blockCommand('wget');

platformRule

platformRule(rule: string): void

Add a raw platform-specific sandbox rule.

string

required

On macOS, this is a Seatbelt S-expression. Ignored on Linux.

Throws an error if the rule is malformed or attempts to grant dangerous access.

// macOS Seatbelt rule
caps.platformRule('(allow file-read* (subpath "/opt/custom"))');

deduplicate

deduplicate(): void

Remove duplicate filesystem capabilities, keeping the highest access level for each path.

caps.allowPath('/tmp', AccessMode.Read);
caps.allowPath('/tmp', AccessMode.Write);
caps.deduplicate();
// Now /tmp has ReadWrite access

pathCovered

pathCovered(path: string): boolean

Check if a path is covered by an existing directory capability.

string

required

The path to check.

boolean

true if the path would be accessible, false otherwise.

caps.allowPath('/tmp', AccessMode.ReadWrite);

caps.pathCovered('/tmp/foo/bar.txt');  // true
caps.pathCovered('/var/data');          // false

fsCapabilities

fsCapabilities(): FsCapabilityInfo[]

Get a list of all filesystem capabilities in this set.

FsCapabilityInfo[]

Array of capability objects with the following properties:

original: The path as originally specified
resolved: The canonicalized absolute path
access: Access mode string ("read", "write", or "read+write")
isFile: true if this is a file capability, false for directories
source: How the capability was added

caps.allowPath('/tmp', AccessMode.ReadWrite);
caps.allowFile('/etc/hosts', AccessMode.Read);

const capabilities = caps.fsCapabilities();
console.log(capabilities);
// [
//   { original: '/tmp', resolved: '/private/tmp', access: 'read+write', isFile: false, source: 'api' },
//   { original: '/etc/hosts', resolved: '/private/etc/hosts', access: 'read', isFile: true, source: 'api' }
// ]

summary

summary(): string

Get a human-readable summary of all capabilities.

string

Multi-line string describing all filesystem and network capabilities.

caps.allowPath('/tmp', AccessMode.ReadWrite);
caps.allowPath('/usr', AccessMode.Read);
caps.blockNetwork();

console.log(caps.summary());
// Filesystem:
//   /private/tmp [read+write] (dir)
//   /usr [read] (dir)
// Network:
//   outbound: blocked

Properties

isNetworkBlocked

get isNetworkBlocked(): boolean

Returns true if network access has been blocked.

const caps = new CapabilitySet();
console.log(caps.isNetworkBlocked); // false

caps.blockNetwork();
console.log(caps.isNetworkBlocked); // true

Example: Web Server Sandbox

import { CapabilitySet, AccessMode } from 'nono-ts';

function createWebServerCapabilities(
  staticDir: string,
  uploadDir: string
): CapabilitySet {
  const caps = new CapabilitySet();

  // Static files (read-only)
  caps.allowPath(staticDir, AccessMode.Read);

  // Upload directory (read-write)
  caps.allowPath(uploadDir, AccessMode.ReadWrite);

  // Node.js runtime
  caps.allowPath('/usr/lib', AccessMode.Read);
  caps.allowPath('/lib', AccessMode.Read);

  // SSL certificates
  caps.allowPath('/etc/ssl/certs', AccessMode.Read);

  // DNS resolution
  caps.allowFile('/etc/resolv.conf', AccessMode.Read);
  caps.allowFile('/etc/hosts', AccessMode.Read);

  // Temp directory for uploads
  caps.allowPath('/tmp', AccessMode.ReadWrite);

  return caps;
}

const caps = createWebServerCapabilities('/var/www/html', '/var/uploads');
console.log(caps.summary());

Getting Started

API Reference

Examples

Constructor

Methods

allowPath

allowFile

blockNetwork

allowCommand

blockCommand

platformRule

deduplicate

pathCovered

fsCapabilities

summary

Properties

isNetworkBlocked

Example: Web Server Sandbox

​Constructor

​Methods

​allowPath

​allowFile

​blockNetwork

​allowCommand

​blockCommand

​platformRule

​deduplicate

​pathCovered

​fsCapabilities

​summary

​Properties

​isNetworkBlocked

​Example: Web Server Sandbox

Constructor

Methods

allowPath

allowFile

blockNetwork

allowCommand

blockCommand

platformRule

deduplicate

pathCovered

fsCapabilities

summary

Properties

isNetworkBlocked

Example: Web Server Sandbox