The fastest, cheapest, most efficient open-source agent harness. Run more than 500 agents on a $10 VPS.
Rust agent-orchestrationai-agentsai-assistantdesktopllmlocal-firstmcppersonal-aiprivacyrustsecond-braintauri
// tinybox's shell helpers are deprecated in favour of tinysecurity-policy; the
// test-only comparisons below keep using them until that move lands.
#![allow(deprecated)]
use std::path::{Path, PathBuf};
#[cfg(test)]
use super::command_vocabulary::classify_segment_source;
use super::CommandAnalysis;
#[cfg(test)]
use super::types::CommandRiskLevel;
use super::types::{AutonomyLevel, GateDecision, SecurityPolicy};
use crate::security::policy::CommandClass;
#[cfg(test)]
use crate::util::floor_char_boundary;
#[cfg(test)]
use tinybox_core::shell::scan::{
contains_unquoted_char, split_unquoted_segments, strip_quoted_heredoc_bodies,
};
use tinytools::status::POLICY_BLOCKED_MARKER;
#[cfg(test)]
fn command_basename(command: &str) -> &str {
command.rsplit(['/', '\\']).next().unwrap_or(command)
}
#[cfg(test)]
fn normalized_command_name(command: &str) -> String {
command_basename(command.trim_matches(|c: char| matches!(c, '\'' | '"'))).to_ascii_lowercase()
}
#[cfg(test)]
fn skip_env_assignments(command: &str) -> &str {
let mut rest = command;
loop {
rest = rest.trim_start();
let Some(end) = rest.find(char::is_whitespace) else {
return if rest.contains('=') { "" } else { rest };
};
if !rest[..end].contains('=') {
return rest;
}
rest = &rest[end..];
}
}
#[cfg(test)]
fn has_leading_env_assignment(command: &str) -> bool {
command
.split_whitespace()
.next()
.is_some_and(|word| word.contains('='))
}
#[cfg(test)]
fn has_dangerous_env_prefix(command: &str) -> bool {
command
.split_whitespace()
.take_while(|word| word.contains('='))
.any(|word| {
matches!(
word.split('=')
.next()
.unwrap_or_default()
.to_ascii_uppercase()
.as_str(),
"LD_PRELOAD"
| "LD_LIBRARY_PATH"
| "DYLD_INSERT_LIBRARIES"
| "DYLD_LIBRARY_PATH"
| "PATH"
)
})
}
#[cfg(test)]
fn contains_unquoted_single_ampersand(command: &str) -> bool {
contains_unquoted_char(command, '&') && !command.contains("&&") && !command.contains(">&")
}
#[cfg(test)]
fn has_hidden_execution(command: &str) -> bool {
let command = strip_quoted_heredoc_bodies(command);
["$(", "<(", ">("]
.iter()
.any(|needle| command.contains(needle))
|| contains_unquoted_char(&command, '`')
|| contains_unquoted_single_ampersand(&command)
}
#[cfg(test)]
fn is_command_executor(command: &str) -> bool {
let command = command_basename(command.trim_matches(|c: char| matches!(c, '\'' | '"')))
.to_ascii_lowercase();
let command = command.strip_suffix(".exe").unwrap_or(&command);
let python_executor = command
.strip_prefix("pythonw")
.or_else(|| command.strip_prefix("python"))
.is_some_and(|version| {
version.is_empty()
|| version
.chars()
.all(|character| character.is_ascii_digit() || character == '.')
});
python_executor
|| matches!(
command,
"sh" | "bash"
| "zsh"
| "fish"
| "python"
| "python2"
| "node"
| "ruby"
| "perl"
| "php"
| "lua"
| "awk"
| "xargs"
| "env"
)
}
impl SecurityPolicy {
/// Apply the supervised allowlist to parser facts returned by TinyBox.
/// The module owns shell structure; this host owns the permission policy.
#[cfg(feature = "modules")]
pub(crate) fn is_command_allowed_analysis(&self, analysis: &CommandAnalysis) -> bool {
if !self.enabled {
return true;
}
if self.autonomy == AutonomyLevel::ReadOnly {
return false;
}
// Full access deliberately bypasses the supervised command allowlist.
if self.autonomy == AutonomyLevel::Full {
return true;
}
if analysis.hidden_execution
|| analysis.expansion
|| analysis.background
|| analysis.redirection
|| analysis.tee
{
return false;
}
let mut saw_command = false;
for segment in &analysis.segments {
if segment.command.trim().is_empty() {
continue;
}
saw_command = true;
if segment.leading_env_assignment || segment.dangerous_env_prefix || segment.executor {
return false;
}
let base = segment.normalized_name.as_str();
if base.is_empty() || !self.allowed_commands.iter().any(|allowed| allowed == base) {
return false;
}
if !self.is_analysis_args_safe(base, &segment.arguments) {
return false;
}
}
saw_command
}
/// Apply OpenHuman's shell policy to generic facts returned by TinyBox.
/// The module supplies parsing facts, while this host owns path checks,
/// autonomy tiers, and approval decisions.
#[cfg(feature = "modules")]
pub(crate) fn check_gated_command_analysis(
&self,
analysis: &CommandAnalysis,
) -> Result<CommandClass, String> {
self.check_protected_path_words(&analysis.literal_words)?;
let mut class = analysis
.segments
.iter()
.map(|segment| segment.class)
.max()
.unwrap_or(CommandClass::Read);
if analysis.redirection || analysis.tee {
class = class.max(CommandClass::Write);
}
if !self.enabled {
return Ok(class);
}
if self.gate_decision(class) == GateDecision::Block {
return Err(format!(
"{POLICY_BLOCKED_MARKER} Security policy: read-only mode — only read commands are permitted."
));
}
if self.autonomy != AutonomyLevel::Full && analysis.hidden_execution {
return Err(format!(
"{POLICY_BLOCKED_MARKER} Command blocked: hidden command execution is not allowed in this mode."
));
}
Ok(class)
}
/// Classify command risk. Any high-risk segment marks the whole command high.
#[cfg(test)]
pub fn command_risk_level(&self, command: &str) -> CommandRiskLevel {
let mut saw_medium = false;
for segment in split_unquoted_segments(command) {
let cmd_part = skip_env_assignments(&segment);
let mut words = cmd_part.split_whitespace();
let Some(base_raw) = words.next() else {
continue;
};
let base = normalized_command_name(base_raw);
let args: Vec<String> = words.map(|w| w.to_ascii_lowercase()).collect();
let joined_segment = cmd_part.to_ascii_lowercase();
// High-risk = catastrophic / irreversible / privilege-escalating /
// system-control commands ONLY. Interpreters (python/bash/…),
// network tools (curl/wget/ssh/…), and ordinary rm/chmod/chown are
// deliberately NOT high-risk: they are routine for a coding agent and
// are treated as medium-risk below (prompted in Supervised, run in
// Full). This keeps "Full access" actually able to run code while
// still guarding the few irreversible / system-destroying commands.
if matches!(
base.as_str(),
"mkfs"
| "dd"
| "shutdown"
| "reboot"
| "halt"
| "poweroff"
| "sudo"
| "su"
| "mount"
| "umount"
| "iptables"
| "ufw"
| "firewall-cmd"
| "useradd"
| "userdel"
| "usermod"
| "passwd"
) {
return CommandRiskLevel::High;
}
if joined_segment.contains("rm -rf /")
|| joined_segment.contains("rm -fr /")
|| joined_segment.contains(":(){:|:&};:")
{
return CommandRiskLevel::High;
}
// Medium-risk commands (state-changing, but not inherently destructive)
let medium = match base.as_str() {
"git" => args.first().is_some_and(|verb| {
matches!(
verb.as_str(),
"commit"
| "push"
| "reset"
| "clean"
| "rebase"
| "merge"
| "cherry-pick"
| "revert"
| "branch"
| "checkout"
| "switch"
| "tag"
)
}),
"npm" | "pnpm" | "yarn" => args.first().is_some_and(|verb| {
matches!(
verb.as_str(),
"install" | "add" | "remove" | "uninstall" | "update" | "publish"
)
}),
"cargo" => args.first().is_some_and(|verb| {
matches!(
verb.as_str(),
"add" | "remove" | "install" | "clean" | "publish"
)
}),
"touch" | "mkdir" | "mv" | "cp" | "ln" | "rm" | "chmod" | "chown" | "curl"
| "wget" | "nc" | "ncat" | "netcat" | "scp" | "ssh" | "ftp" | "telnet" => true,
_ => false,
};
// Interpreters / code executors run arbitrary code — medium-risk
// (that is the job of a coding agent): prompted in Supervised,
// allowed in Full. They are no longer classified high-risk.
let medium = medium || is_command_executor(base.as_str());
saw_medium |= medium;
}
if saw_medium {
CommandRiskLevel::Medium
} else {
CommandRiskLevel::Low
}
}
/// Classify a shell command into a fail-closed [`CommandClass`]. The highest
/// class across all `;`/`|`/`&&`/`||`/newline-separated segments wins, and a
/// file redirect (`>`/`>>`) or `tee` lifts the class to at least `Write` no
/// matter how benign the base looks (`cat x > y` writes `y`).
///
/// This is the deterministic floor the harness gate keys on; an LLM-declared
/// category may only *raise* it (`gate = max(rust_floor, llm_declared)`),
/// never lower it.
#[cfg(test)]
pub fn classify_command(&self, command: &str) -> CommandClass {
// A quoted heredoc body is document text, not shell. Without this the
// splitter chops the body into "commands" and a prose line containing
// `rm` or `curl` lifts a plain file write to Destructive/Network.
let command = &strip_quoted_heredoc_bodies(command);
let mut class = CommandClass::Read;
// The same per-segment classifier production applies to TinyBox's
// segment facts (`CommandAnalysis::from_shell_analysis`).
for segment in split_unquoted_segments(command) {
if !segment.trim().is_empty() {
class = class.max(classify_segment_source(&segment));
}
}
// A redirect or `tee` writes a file regardless of the base command.
if contains_unquoted_char(command, '>')
|| command
.split_whitespace()
.any(|w| w == "tee" || w.ends_with("/tee"))
{
class = class.max(CommandClass::Write);
}
class
}
/// The gate decision for an acting tool call of `class` under this policy's
/// autonomy tier. The harness turns `Prompt` into an `ApprovalGate`
/// round-trip *before* the tool runs; `Block` is refused outright.
///
/// Matrix: read-only allows only `Read`; ask-before-edit (`Supervised`)
/// prompts on every acting class; full runs `Read`/`Write` silently but
/// always prompts on `Network`/`Destructive`.
pub fn gate_decision(&self, class: CommandClass) -> GateDecision {
if !self.enabled {
return GateDecision::Allow;
}
match self.autonomy {
AutonomyLevel::ReadOnly => match class {
CommandClass::Read => GateDecision::Allow,
_ => GateDecision::Block,
},
AutonomyLevel::Supervised => match class {
CommandClass::Read => GateDecision::Allow,
_ => GateDecision::Prompt,
},
AutonomyLevel::Full => match class {
CommandClass::Read | CommandClass::Write => GateDecision::Allow,
CommandClass::Network | CommandClass::Install | CommandClass::Destructive => {
GateDecision::Prompt
}
},
}
}
/// Defense-in-depth check for the harness-gated command flow (Option 2).
///
/// The run / prompt / block decision is made by [`Self::gate_decision`] +
/// the process-global `ApprovalGate` (which prompts the human *before*
/// `execute()`), so by the time a tool calls this the command is either a
/// read or an already-approved act. This enforces what must still hold:
///
/// - **Read-only**: only `Read`-class commands run (`Block` otherwise).
/// - **Supervised**: no *hidden execution* (command/process substitution,
/// backticks, background `&`) that could smuggle an unseen command past
/// the approval the human read. Plain redirects (`2>&1`, `> file`) and
/// pipes are fine here — `classify_command` already lifts redirects to
/// `Write` so the gate prompted on them, and the human approved the
/// literal command. Full is trusted and skips the structural guard.
///
/// Returns the classified [`CommandClass`] on success.
#[cfg(test)]
pub fn check_gated_command(&self, command: &str) -> Result<CommandClass, String> {
let class = self.classify_command(command);
self.check_protected_path_literals(command)?;
if !self.enabled {
return Ok(class);
}
if self.gate_decision(class) == GateDecision::Block {
return Err(format!(
"{POLICY_BLOCKED_MARKER} Security policy: read-only mode — only read commands are \
permitted. Do not retry this command; use a read-only approach or report that it \
cannot be done in this mode."
));
}
if self.autonomy != AutonomyLevel::Full && has_hidden_execution(command) {
return Err(format!(
"{POLICY_BLOCKED_MARKER} Command blocked: command/process substitution ($(…), \
<(…)), backticks, and background (&) are not allowed in this mode — they can run \
a hidden command the approval prompt wouldn't show. Plain redirects like `2>&1` \
are fine. Do not retry as-is; rewrite the command without these constructs."
));
}
Ok(class)
}
/// Refuse literal references to the protected-path floor before launching
/// a command, including when the autonomy policy is disabled. This is a
/// guard for direct path arguments and source literals; arbitrary shell or
/// interpreter code still needs a filesystem sandbox to enforce the floor.
#[cfg(test)]
pub fn check_protected_path_literals(&self, input: &str) -> Result<(), String> {
let words = strip_quoted_heredoc_bodies(input)
.split(|c: char| {
c.is_whitespace()
|| matches!(
c,
'\'' | '"' | '(' | ')' | '[' | ']' | ',' | ';' | '=' | '@'
)
})
.map(str::to_owned)
.collect::<Vec<_>>();
self.check_protected_path_words(&words)
}
/// Refuse protected paths and unsafe path literals returned by the
/// execution module's command analysis. The host still owns path policy;
/// the module only supplies token boundaries.
pub fn check_protected_path_words(&self, words: &[String]) -> Result<(), String> {
for word in words {
let word = word.trim_matches(|c: char| matches!(c, ':' | '<' | '>' | '&' | '|'));
if word.is_empty() || word.contains("://") {
continue;
}
let candidate_path = PathBuf::from(word);
if word.contains('\0')
|| candidate_path
.components()
.any(|component| matches!(component, std::path::Component::ParentDir))
{
return Err(format!(
"{POLICY_BLOCKED_MARKER} Command references an unsafe path"
));
}
let word = ["${HOME}", "$HOME", "%USERPROFILE%"]
.iter()
.find_map(|prefix| word.strip_prefix(prefix).map(|rest| format!("~{rest}")))
.unwrap_or_else(|| word.to_string());
let candidate = PathBuf::from(self.expand_tilde(&word));
let candidate = if candidate.is_absolute() {
candidate
} else {
self.action_dir.join(candidate)
};
if Self::is_always_forbidden(&candidate)
|| candidate
.canonicalize()
.ok()
.is_some_and(|path| Self::is_always_forbidden(Path::new(&path)))
{
return Err(format!(
"{POLICY_BLOCKED_MARKER} Command references a protected path"
));
}
}
Ok(())
}
/// Parse an LLM-declared command category. This is an **escalate-only**
/// hint: callers combine it with the deterministic floor via
/// `classify_command(cmd).max(declared)`, so the model can *raise* the gate
/// (e.g. flag a `Write` as `Destructive` to request confirmation) but can
/// never lower what the runtime determined. Unknown / empty → `None`.
pub fn parse_declared_class(declared: &str) -> Option<CommandClass> {
match declared.trim().to_ascii_lowercase().as_str() {
"read" => Some(CommandClass::Read),
"write" => Some(CommandClass::Write),
"network" => Some(CommandClass::Network),
"install" => Some(CommandClass::Install),
"destructive" => Some(CommandClass::Destructive),
_ => None,
}
}
/// Validate full command execution policy (allowlist + risk gate).
#[cfg(test)]
pub fn validate_command_execution(
&self,
command: &str,
approved: bool,
) -> Result<CommandRiskLevel, String> {
if !self.enabled {
return Ok(self.command_risk_level(command));
}
if !self.is_command_allowed(command) {
// Truncate the command in BOTH the log and the Err return: the Err
// string is bubbled back to the frontend, and a full untruncated
// command can leak secrets in args (e.g. `curl -H "Authorization:
// Bearer …"`, `psql "postgres://user:pass@…"`). The 80-char cap
// matches the log truncation so a long base command with safe args
// still shows enough context to diagnose the block.
let truncated = &command[..floor_char_boundary(command, 80)];
log::warn!(
"[openhuman:policy] Command blocked by allowlist: {}",
truncated
);
return Err(format!(
"{POLICY_BLOCKED_MARKER} Command not allowed by security policy: {truncated}. \
Do not retry this command; it is off the allowlist for this mode."
));
}
let risk = self.command_risk_level(command);
if risk == CommandRiskLevel::High {
if self.block_high_risk_commands {
log::warn!(
"[openhuman:policy] High-risk command blocked: {}",
&command[..floor_char_boundary(command, 80)]
);
return Err(format!(
"{POLICY_BLOCKED_MARKER} Command blocked: high-risk command is disallowed by \
policy. Do not retry this command; choose a safer approach or report that it \
cannot be done."
));
}
if self.autonomy == AutonomyLevel::Supervised && !approved {
log::warn!(
"[openhuman:policy] High-risk command needs approval: {}",
&command[..floor_char_boundary(command, 80)]
);
return Err(
"Command requires explicit approval (approved=true): high-risk operation"
.into(),
);
}
}
if risk == CommandRiskLevel::Medium
&& self.autonomy == AutonomyLevel::Supervised
&& self.require_approval_for_medium_risk
&& !approved
{
log::info!(
"[openhuman:policy] Medium-risk command needs approval: {}",
&command[..floor_char_boundary(command, 80)]
);
return Err(
"Command requires explicit approval (approved=true): medium-risk operation".into(),
);
}
log::debug!(
"[openhuman:policy] Command validated: risk={:?}, approved={}, cmd={}",
risk,
approved,
&command[..floor_char_boundary(command, 80)]
);
Ok(risk)
}
/// Check if a shell command is allowed.
///
/// Validates the **entire** command string, not just the first word:
/// - Blocks subshell operators (`` ` ``, `$(`) that hide arbitrary execution
/// - Splits on command separators (`|`, `&&`, `||`, `;`, newlines) and
/// validates each sub-command against the allowlist
/// - Blocks single `&` background chaining (`&&` remains supported)
/// - Blocks output redirections (`>`, `>>`) that could write outside workspace
/// - Blocks dangerous arguments (e.g. `find -exec`, `git config`)
#[cfg(test)]
pub fn is_command_allowed(&self, command: &str) -> bool {
if !self.enabled {
return true;
}
if self.autonomy == AutonomyLevel::ReadOnly {
return false;
}
// See `classify_command`: a quoted heredoc body is data, so it must not
// be scanned for `$(`, `&` or a disallowed base command.
let command = &strip_quoted_heredoc_bodies(command);
// Full access bypasses the command allowlist AND the structural guards
// (redirects, pipes, subshells, background) — a Full-access agent is
// trusted to run any command, including the `mkdir`/`node`/`python`/
// redirect-using commands a coding workflow needs. The remaining safety
// net is `validate_command_execution`'s high-risk handling (still gated
// by `block_high_risk_commands`), plus path-level `forbidden_paths` and
// any configured sandbox. The allowlist + structural guards below stay
// in force for Supervised, which runs only curated commands.
if self.autonomy == AutonomyLevel::Full {
return true;
}
// Block subshell/expansion operators — these allow hiding arbitrary
// commands inside an allowed command (e.g. `echo $(rm -rf /)`)
if command.contains('`')
|| command.contains("$(")
|| command.contains("${")
|| command.contains("<(")
|| command.contains(">(")
{
return false;
}
// Block output redirections (`>`, `>>`) — they can write to arbitrary paths.
// Ignore quoted literals, e.g. `echo "a>b"`.
if contains_unquoted_char(command, '>') {
return false;
}
// Block `tee` — it can write to arbitrary files, bypassing the
// redirect check above (e.g. `echo secret | tee /etc/crontab`)
if command
.split_whitespace()
.any(|w| w == "tee" || w.ends_with("/tee"))
{
return false;
}
// Block background command chaining (`&`), which can hide extra
// sub-commands and outlive timeout expectations. Keep `&&` allowed.
if contains_unquoted_single_ampersand(command) {
return false;
}
// Split on unquoted command separators and validate each sub-command.
let segments = split_unquoted_segments(command);
for segment in &segments {
// Reject ANY segment that prefixes the command with an env-var
// assignment, not just the known-dangerous names. Helper-style
// exec primitives (`GIT_SSH=./wrapper git ls-remote`,
// `SSH_ASKPASS=./prompt ssh user@host`, `LD_PRELOAD=./libx.so
// ls`, etc.) change which binary the allowed command actually
// resolves to — or change its behaviour via a hook — without
// any blocked command name ever appearing in the segment. The
// allowlist already names every command we want to permit, and
// none of those commands need an operator-set env var at
// invoke time, so the broader gate has no false-positive
// surface on the approved path. `has_dangerous_env_prefix`
// remains in the source for legacy tests and as the
// narrower-grained signal.
if has_leading_env_assignment(segment) || has_dangerous_env_prefix(segment) {
return false;
}
// Strip leading env var assignments (e.g. FOO=bar cmd)
let cmd_part = skip_env_assignments(segment);
let mut words = cmd_part.split_whitespace();
let base_raw = words.next().unwrap_or("");
let base_cmd = command_basename(base_raw);
if base_cmd.is_empty() {
continue;
}
if !self
.allowed_commands
.iter()
.any(|allowed| allowed == base_cmd)
{
return false;
}
// Validate arguments for the command
let args: Vec<String> = words.map(|w| w.to_ascii_lowercase()).collect();
if is_command_executor(base_cmd) || !self.is_args_safe(base_cmd, &args) {
return false;
}
}
// At least one command must be present
let has_cmd = segments.iter().any(|s| {
let s = skip_env_assignments(s.trim());
s.split_whitespace().next().is_some_and(|w| !w.is_empty())
});
has_cmd
}
/// Check for dangerous arguments that allow sub-command execution.
fn is_args_safe(&self, base: &str, args: &[String]) -> bool {
self.is_analysis_args_safe(base, args)
}
fn is_analysis_args_safe(&self, base: &str, args: &[String]) -> bool {
let base = base.to_ascii_lowercase();
match base.as_str() {
"find" => {
// -exec / -ok run a command per match. -execdir / -okdir do
// the same with the working directory set to the match's
// parent — same code-execution semantics, just with a
// different cwd, so they must be blocked alongside.
!args.iter().any(|arg| {
arg == "-exec" || arg == "-ok" || arg == "-execdir" || arg == "-okdir"
})
}
"git" => {
// git config, alias, and -c can be used to set dangerous options
// (e.g. git config core.editor "rm -rf /")
!args.iter().any(|arg| {
arg == "config"
|| arg.starts_with("config.")
|| arg == "alias"
|| arg.starts_with("alias.")
|| arg == "-c"
})
}
"date" => args.is_empty(),
_ => true,
}
}
}