Skip to content

configuration.md

Latest commit

 

History

History
158 lines (105 loc) · 4.01 KB

configuration.md

File metadata and controls

158 lines (105 loc) · 4.01 KB

Configuration

Terminal uses a configuration object to define command filtering policies. All settings are optional and merge with sensible defaults.

Important: Terminal is a command string filter, not a sandbox. It validates the command and arguments before spawning. Once a command is allowed, the OS controls what it can access. See Security for OS-level hardening.

Basic Configuration

Terminal.initialize({
  workspaces: ['/safe/project'],
  commands: {
    allow: ['cd *', 'git *', 'npm *'],
    deny: ['rm *', 'sudo *'],
    maxArgs: 10,
    strictArgs: true,
    noShell: true,
    killSignal: 'SIGTERM',
    windowsHide: false,
    windowsVerbatimArguments: false
  },
  env: {
    allow: ['NODE_ENV', 'PATH'],
    deny: ['HOME', 'SSH_*', 'LD_PRELOAD', 'LD_LIBRARY_PATH']
  },
  timeout: 30000,
  uid: undefined,
  gid: undefined
})

Workspaces

Restrict command execution to specific directories:

workspaces: ['/home/user/projects', '/tmp/builds']

Commands outside these paths will be rejected. Note: This only validates cwd. The spawned process can still access any path the OS allows.

Commands

allow - Command Whitelist

Pattern-based allowlist. Empty array allows all (unless denied).

allow: ['git *', 'npm *', 'echo *']

Warning: allow: ['node *'] or allow: ['python3 *'] effectively allows arbitrary code execution via script files. Terminal does not inspect file contents.

deny - Command Blacklist

Pattern-based denylist. Always checked first.

deny: ['rm -rf *', 'sudo *', 'mkfs.*', 'dd *']

maxArgs - Argument Limit

Maximum number of arguments allowed per command.

maxArgs: 10 // Rejects commands with more than 10 arguments

strictArgs - Strict Validation

Block shell metacharacters and path traversal in arguments:

strictArgs: true // Blocks ; | & ` $ ( ) { } [ ] < > and ../

noShell - Shell Control

noShell: true // Always use direct execution (recommended)

killSignal - Default Kill Signal

Signal sent when a process is aborted or times out. Defaults to SIGTERM.

killSignal: 'SIGKILL' // Use SIGKILL instead of SIGTERM

Valid signals: SIGTERM, SIGKILL, SIGINT, SIGHUP, and all POSIX signal names.

windowsHide - Hide Console Window

Hides the subprocess console window on Windows. Prevents UI hijacking.

windowsHide: true // Hide console window on Windows

windowsVerbatimArguments - Disable Argument Quoting

Disables Node.js quoting and escaping of arguments on Windows. Prevents command-line injection via Windows shell parsing.

windowsVerbatimArguments: true // Pass arguments verbatim on Windows

Environment Variables

allow - Variable Whitelist

allow: ['NODE_ENV', 'PATH']

deny - Variable Blacklist

Supports wildcards. Always deny LD_PRELOAD and LD_LIBRARY_PATH:

deny: ['SSH_*', 'AWS_*', 'TOKEN*', 'LD_PRELOAD', 'LD_LIBRARY_PATH']

Timeout

Default timeout in milliseconds:

timeout: 30000 // 30 seconds

Set to 0 to disable timeouts.

Privilege Dropping

Run spawned processes as a different user or group via setuid/setgid. Requires the parent process to have sufficient privileges.

uid: 1000  // Run as user ID 1000
gid: 1000  // Run as group ID 1000

Note: uid/gid are applied at the OS level via Node.js spawn(). The parent process must have permission to change to the target user/group. This is a defense-in-depth layer — combine with OS-level unprivileged users for real isolation.

Pattern Syntax

Patterns use token matching with optional wildcards:

  • git * - Matches "git" followed by any arguments
  • node *.js - Matches "node" with .js file argument
  • deno run * - Matches exact prefix, allows suffix

See Also