Feature: Flexible command restrictions

[lostbean]

Note: This is PR 2 of 3, splitting #4 (sandbox) as requested by @dbernheisel. The stack is:

1. Refactor: Consolidate ExCmd into CommandPort #5 — Consolidate ExCmd into CommandPort
2. This PR — Flexible command restrictions (depends on Refactor: Consolidate ExCmd into CommandPort #5)
3. Pluggable virtual filesystem (depends on this PR)

Motivation

PR #5 consolidated all ExCmd usage into CommandPort and added restriction gates there. However, per @dbernheisel's review feedback, restriction decisions should be made at a higher level — not in the process-spawning layer. The boolean restricted: true/false is also too rigid; users need fine-grained control over which commands are allowed.

Design

Bash.CommandPolicy struct

An extensible struct stored on Bash.Session state, immutable once set:

%CommandPolicy{
  commands: command_rule(),  # gates command execution
  paths: nil,               # reserved for future filesystem restrictions
  files: nil                # reserved for future file access restrictions
}

Category-aware policy engine

Every command falls into one of four categories, and rules can gate any of them:

Category	Atom in rules	What it covers
:builtin	:builtins	echo, cd, export, etc.
:external	:externals	OS commands on $PATH
:function	:functions	User-defined name() { ... }
:interop	:interop	Elixir interop via defbash

Common recipes

Goal	Policy
Allow everything (default)	commands: :unrestricted
Block all externals	commands: :no_external
Builtins only	commands: [{:allow, [:builtins]}]
Builtins + functions	commands: [{:allow, [:builtins, :functions]}]
Builtins + specific externals	commands: [{:allow, [:builtins, "cat", "grep"]}]
Everything except externals	commands: [{:disallow, [:externals]}, {:allow, :all}]
Block specific builtins	commands: [{:disallow, ["eval", "source"]}, {:allow, :all}]
Block everything	commands: [{:disallow, :all}]

Rule evaluation

Rules are evaluated in order, first match wins, fail-closed (no match = deny):

• {:allow, items} / {:disallow, items} — items can be strings, regexes, or category atoms
• {:allow, :all} / {:disallow, :all} — catch-all
• fun/2 — receives (name, category), return true to allow
• fun/1 — legacy, only evaluated for :external commands

Command dispatch restructured

resolve_and_execute in AST.Command now follows resolve-then-check-then-dispatch:

1. Resolve — determine category (:function, :interop, :builtin, or :external)
2. Check — CommandPolicy.check_command(policy, name, category)
3. Dispatch — execute via the appropriate handler

Policy enforcement points

Enforcement Point	Category
AST.Command.resolve_and_execute	All categories (resolve → check → dispatch)
Pipeline.external_command?	:external (streaming optimization)
exec builtin	:external
command builtin	:external (run and lookup)
coproc builtin	:external
Session (background jobs)	:external

Backwards compatible

• check_command/2 defaults to :external category
• :no_external only blocks externals (builtins/functions/interop pass through)
• fun/1 policies only fire for externals
• options: %{restricted: true} normalized to command_policy: :no_external

Immutable once set

• set builtin preserves command_policy across option changes
• shopt restricted_shell is read-only, reflects command_policy != :unrestricted

Usage

# Block all external commands
{:ok, session} = Bash.Session.new(command_policy: [commands: :no_external])

# Allow builtins + specific externals
{:ok, session} = Bash.Session.new(
  command_policy: [commands: [{:allow, [:builtins, "cat", "grep"]}]]
)

# Allow builtins and functions, block externals and interop
{:ok, session} = Bash.Session.new(
  command_policy: [commands: [{:allow, [:builtins, :functions]}]]
)

# Block dangerous builtins, allow everything else
{:ok, session} = Bash.Session.new(
  command_policy: [commands: [{:disallow, ["eval", "source"]}, {:allow, :all}]]
)

# Category-aware function
{:ok, session} = Bash.Session.new(
  command_policy: [commands: fn _name, cat -> cat in [:builtin, :function] end]
)

Test plan

• All 2195 tests pass (0 failures)
• test/bash/command_restrictions_test.exs — 142 tests covering:
  • :no_external blocks external commands (simple, absolute path, pipeline, subshell, command substitution, background jobs)
  • Allowlist/denylist with strings, regexes, and functions
  • Category-aware policies: builtins-only, externals-only, functions-only, interop-only
  • All multi-category combinations (builtins+externals, builtins+functions, builtins+interop, builtins+functions+interop)
  • Disallow specific categories while allowing the rest
  • Disallow specific commands by name across categories
  • {:disallow, :all} blocks everything
  • fun/2 receives category, fun/1 backwards compat (external-only)
  • Policy inherits to subshells and command substitutions
  • Policy is immutable via set and shopt
  • command -v respects policy
  • exec, coproc, background jobs, pipelines respect all policy types
  • CommandPolicy struct: normalization, check_command/3, command_allowed?/3
• mix format --check-formatted clean
• mix compile --warnings-as-errors clean

[dbernheisel]

Most of this looks to include changes from the other branch -- ignoring that, I think this is a good direction, though let's expand the CommandPolicy idea a bit into a struct that can be built to hold more decisions.

I'm thinking something like:

%CommandPolicy{
  commands: :no_external | [{:allow | :disallow, [...]}, fn x -> end] | fn x -> ... end,
  paths: [~r/.../, "..", fn x -> ... end],
  files: [~r/.../, "..", fn x -> ... end],
}

this would be evaluated at the time of the access request and respond appropriately.

[lostbean]

Hey @dbernheisel, that's a great insight on moving the data structure to a struct and planning for support across different dimensions (commands, paths, files).

I've reworked CommandPolicy into an extensible struct:

%CommandPolicy{
  commands: :unrestricted | :no_external | [rules] | fn/1,
  paths: nil,   # reserved for future filesystem policy
  files: nil    # reserved for future filesystem policy
}

Rules support strings, regex, and functions — evaluated in order, first match wins:

# Denylist with catch-all allow
Bash.Session.new(command_policy: [commands: [{:disallow, ["rm", "dd"]}, {:allow, :all}]])

# Regex-based
Bash.Session.new(command_policy: [commands: [{:allow, [~r/^git-/]}]])

# Function-based
Bash.Session.new(command_policy: [commands: fn cmd -> String.starts_with?(cmd, "safe-") end])

Also promoted command_policy from state.options to a top-level session field (like filesystem), which makes immutability automatic since set only touches the options map.

The paths and files fields are declared but not enforced yet — that'll come naturally once the filesystem branch lands, with policy checks at the Bash.Filesystem dispatch layer.