Raxol.Agent.Sandbox.Shell (Raxol Agent v2.6.0)

Copy Markdown View Source

Shell isolation dimension for Raxol.Agent.Sandbox.

Gates Raxol.Agent.Directive.Shell directives by matching the command against an allowlist, denylist, or wholesale deny.

Matching semantics

The shell command is the binary passed to Raxol.Agent.Directive.shell/2. The match check is binary name by default: "ls -la" matches the entry "ls". For finer-grained matching, use a predicate function.

Constructors

Sandbox.Shell.none()
  # abstain; any shell command allowed (default-allow)

Sandbox.Shell.deny_all()
  # block every shell command

Sandbox.Shell.allowlist(["ls", "cat", "wc"])
  # allow only those binary names

Sandbox.Shell.allowlist(fn cmd -> String.starts_with?(cmd, "git ") end)
  # arbitrary predicate

Sandbox.Shell.denylist(["rm", "dd", "shutdown"])
  # block those binary names; allow everything else

Sandbox.Shell.denylist(fn cmd -> String.contains?(cmd, "sudo") end)
  # arbitrary predicate

The none/0 sandbox is the default-allow case (a sandbox that doesn't restrict shell). The deny_all/0 is the default-deny case. The other two are the explicit policies.

Summary

Types

mode()

Internal mode. Authors use the constructors; this is the wire shape so the protocol impl can pattern-match.

t()

Functions

allowed?(shell, command)

Check whether command is permitted by the sandbox's mode. Exposed so callers can validate commands outside the protocol.

allowlist(list_or_fun)

Construct an allowlist shell sandbox. Accepts a list of binary names (matched as the first whitespace-separated token of the command) or a 1-arity predicate function on the full command.

deny_all()

Construct a deny-all shell sandbox.

denylist(list_or_fun)

Construct a denylist shell sandbox. Accepts the same list or predicate shape as allowlist/1.

none()

Construct a no-op shell sandbox (abstain).

Types

mode()

@type mode() ::
  :none
  | :deny_all
  | {:allowlist, [String.t()] | (String.t() -> boolean())}
  | {:denylist, [String.t()] | (String.t() -> boolean())}

Internal mode. Authors use the constructors; this is the wire shape so the protocol impl can pattern-match.

t()

@type t() :: %Raxol.Agent.Sandbox.Shell{mode: mode()}

Functions

allowed?(shell, command)

@spec allowed?(t(), String.t()) :: boolean()

Check whether command is permitted by the sandbox's mode. Exposed so callers can validate commands outside the protocol.

allowlist(list_or_fun)

@spec allowlist([String.t()] | (String.t() -> boolean())) :: t()

Construct an allowlist shell sandbox. Accepts a list of binary names (matched as the first whitespace-separated token of the command) or a 1-arity predicate function on the full command.

deny_all()

@spec deny_all() :: t()

Construct a deny-all shell sandbox.

denylist(list_or_fun)

@spec denylist([String.t()] | (String.t() -> boolean())) :: t()

Construct a denylist shell sandbox. Accepts the same list or predicate shape as allowlist/1.

none()

@spec none() :: t()

Construct a no-op shell sandbox (abstain).