Skip to main content

Module protocol

par_term_scripting

Module protocol 

Source
Expand description

JSON protocol types for communication between the terminal and script subprocesses.

Scripts read ScriptEvent objects from stdin (one JSON object per line) and write ScriptCommand objects to stdout (one JSON object per line).

§Security Model

§Trust Assumptions

Scripts are user-configured subprocesses launched from ScriptConfig entries in ~/.config/par-term/config.yaml. The script binary is implicitly trusted (it was placed there by the user). However, this trust must be bounded because:

  1. Supply-chain attacks: A malicious package could replace a trusted script with one that emits dangerous command payloads.
  2. Injection through event data: Malicious terminal sequences could produce events whose payloads are forwarded to the script, which could reflect them back in commands (terminal injection risk).
  3. Compromised scripts: A script may be modified after initial deployment.

§Command Categories

Script commands fall into three security categories:

§Safe Commands (no permission required)

  • Log: Write to the script’s output buffer (UI only)
  • SetPanel / ClearPanel: Display markdown content in a panel
  • Notify: Show a desktop notification
  • SetBadge: Set the tab badge text
  • SetVariable: Set a user variable

§Restricted Commands (require permission flags)

These commands require explicit opt-in via ScriptConfig permission fields:

  • WriteText: Inject text into the PTY (requires allow_write_text: true)
    • Must strip VT/ANSI escape sequences before writing
    • Subject to rate limiting
  • RunCommand: Spawn an external process (requires allow_run_command: true)
    • Must check against check_command_denylist() from par-term-config
    • Must use shell tokenization (not /bin/sh -c) to prevent metacharacter injection
    • Subject to rate limiting
  • ChangeConfig: Modify terminal configuration (requires allow_change_config: true)
    • Must validate config keys against an allowlist

§Implementation Status

All commands are implemented:

  • Log, SetPanel, ClearPanel: Safe, always allowed
  • Notify, SetBadge, SetVariable: Safe, always allowed
  • WriteText: Requires allow_write_text, rate-limited, VT sequences stripped
  • RunCommand: Requires allow_run_command, rate-limited, denylist-checked, tokenised without shell invocation
  • ChangeConfig: Requires allow_change_config, allowlisted keys only

§Dispatcher Responsibility

The command dispatcher in src/app/window_manager/scripting.rs is responsible for:

  1. Checking command.requires_permission() before executing restricted commands
  2. Verifying the corresponding ScriptConfig.allow_* flag is set
  3. Applying rate limits, denylists, and input sanitization

See par-term-scripting/SECURITY.md for the complete security model.

Structs§

ScriptEvent
An event sent from the terminal to a script subprocess (via stdin).

Enums§

ScriptCommand
A command sent from a script subprocess to the terminal (via stdout).
ScriptEventData
Event-specific payload data.

Functions§

strip_vt_sequences
Strip VT/ANSI escape sequences from text before PTY injection.