Security and Command Approval

Relevant source files

• agent/redact.py
• scripts/benchmark_browser_eval.py
• tests/agent/test_pre_compress_memory_context.py
• tests/agent/test_redact.py
• tests/agent/test_tool_call_arg_no_redaction.py
• tests/gateway/test_approve_deny_commands.py
• tests/gateway/test_async_delegation_session_binding.py
• tests/gateway/test_internal_event_bypass_pairing.py
• tests/gateway/test_matrix_exec_approval.py
• tests/gateway/test_session_store_runtime_stale_guard.py
• tests/gateway/test_yolo_command.py
• tests/run_agent/test_24996_fallback_exhaustion_cooldown.py
• tests/run_agent/test_pre_compress_memory_context.py
• tests/tools/test_approval.py
• tests/tools/test_approval_interrupt.py
• tests/tools/test_approved_command_clean_slate.py
• tests/tools/test_browser_cdp_override.py
• tests/tools/test_browser_cdp_tool.py
• tests/tools/test_browser_eval_supervisor_path.py
• tests/tools/test_browser_hybrid_routing.py
• tests/tools/test_browser_supervisor.py
• tests/tools/test_code_execution.py
• tests/tools/test_code_execution_windows_env.py
• tests/tools/test_command_guards.py
• tests/tools/test_cron_approval_mode.py
• tests/tools/test_execution_flag_detection.py
• tests/tools/test_file_tools_live.py
• tests/tools/test_hardline_blocklist.py
• tests/tools/test_interrupt.py
• tests/tools/test_local_env_blocklist.py
• tests/tools/test_local_env_cwd_recovery.py
• tests/tools/test_local_env_windows_msys.py
• tests/tools/test_notify_on_complete.py
• tests/tools/test_process_registry.py
• tests/tools/test_tirith_security.py
• tests/tools/test_voice_cli_integration.py
• tests/tools/test_voice_mode.py
• tests/tools/test_watch_patterns.py
• tests/tools/test_yolo_mode.py
• tools/approval.py
• tools/browser_cdp_tool.py
• tools/browser_supervisor.py
• tools/code_execution_tool.py
• tools/environments/local.py
• tools/interrupt.py
• tools/process_registry.py
• tools/tirith_security.py
• tools/voice_mode.py
• website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/security.md

Purpose and Scope

The Security and Command Approval system is a safeguard layer in Hermes Agent designed to intercept and manage the execution of potentially dangerous commands issued by the AI or users. It balances flexibility and security by detecting destructive or risky operations and requiring explicit user approval before execution, thus preventing accidental system damage, unauthorized actions, or malicious code execution.

This system employs multiple overlapping mechanisms to provide a comprehensive approval workflow:

1. Dangerous Command Detection: Uses a curated set of regex patterns to identify commands posing high-risk operations (e.g., recursive deletion, permission changes, sensitive file writes). This is implemented in tools.approval tools/approval.py1-9
2. Tirith Security Integration: Integrates with the Tirith security engine to analyze commands for threats like homograph URLs, pipe-to-interpreter, and terminal injection tools/approval.py95-97
3. Approval States and Session Management: Tracks approval status on a per-session basis using thread-safe contextvars, supporting one-time, per-session, and permanent approvals tools/approval.py35-50
4. Approval UI/Callbacks: Supports interactive CLI prompts as well as asynchronous approval via the messaging Gateway with explicit blocking and notification callbacks tools/approval.py54-77
5. Allowlist and YOLO Mode: Supports a permanent allowlist loaded from config.yaml and a YOLO shortcut mode to bypass approvals within a session tools/approval.py30-35
6. Secret Redaction: Automatically masks API keys, tokens, and credentials in logs and tool outputs to prevent accidental exposure agent/redact.py1-8
7. Subprocess Isolation: For programmatic tool calling via execute_code, a strict environment variable blocklist prevents the leakage of Hermes' own provider secrets into the child process tools/code_execution_tool.py135-161

Sources: tools/approval.py1-77 agent/redact.py1-8 tools/code_execution_tool.py135-161

---

System Architecture

The security and approval subsystem fits into the Hermes tool execution pathway as a gatekeeper between the agent issuing commands and their actual execution on the host system.

Architecture Flow Diagram

Sources: tools/approval.py35-77 agent/redact.py1-15 tools/environments/local.py17-21 tools/process_registry.py17-30

---

Dangerous Command Detection

Hermes uses regex patterns to scan commands for destructive operations. The detection logic performs command normalization to prevent homograph-based bypasses where lookalike characters are used to hide malicious commands tools/approval.py20-23

Key Patterns and Their Intentions

Pattern Category	Description
Recursive Delete	Matches rm -rf, rm -r, or rm --recursive to prevent mass deletion tests/tools/test_approval.py110-120
Windows Delete	Flags cmd /c del /f /q, rmdir /s, and PowerShell destructive commands tests/tools/test_approval.py171-180
Shell Injections	Detects bash -c, `curl
Verification Exemption	Specifically allows non-recursive cleanup of Hermes verification artifacts in temp directories tests/tools/test_approval.py122-129

Sources: tools/approval.py1-23 tests/tools/test_approval.py110-183

---

Secret Redaction

To prevent credential leakage, Hermes implements a regex-based redaction system that masks sensitive data before it reaches logs or tool outputs agent/redact.py1-8

• Pattern Matching: Detects OpenAI keys (sk-), GitHub tokens (ghp_), AWS keys (AKIA), Slack tokens, and generic KEY=value assignments agent/redact.py71-119
• Context-Aware: Redacts sensitive query parameters in URLs (e.g., access_token, api_key) and JSON body keys while leaving benign code (e.g., os.getenv, process.env) untouched agent/redact.py17-149
• Masking Strategy: Short tokens (< 18 chars) are fully masked. Longer tokens preserve the first 6 and last 4 characters for debuggability agent/redact.py6-7
• Immutable Status: Redaction status is snapshotted at import time via _REDACT_ENABLED to prevent LLM-generated commands from disabling security mid-session agent/redact.py59-69

Sources: agent/redact.py1-154 tests/agent/test_redact.py18-170

---

Subprocess Isolation and Environment Sanitization

When spawning local subprocesses (via terminal or execute_code), Hermes strictly sanitizes the environment to prevent credential leakage and misrouting tests/tools/test_local_env_blocklist.py1-9

• Provider Blocklist: A comprehensive list of environment variables used by Hermes' model providers (e.g., OPENAI_API_KEY, ANTHROPIC_API_KEY, AWS_BEARER_TOKEN_BEDROCK) is stripped from child processes tests/tools/test_local_env_blocklist.py64-115
• Operational Vars: Only a specific allowlist of operational variables (e.g., HERMES_HOME, HERMES_PROFILE) is permitted to reach the child context tools/code_execution_tool.py167-173
• Secret Substrings: Any environment variable containing substrings like KEY, TOKEN, SECRET, or PASSWORD is automatically scrubbed unless it is an OS-essential variable tools/code_execution_tool.py151-161

Sources: tools/code_execution_tool.py135-173 tests/tools/test_local_env_blocklist.py64-115

---

Approval State and Callbacks

The system manages approval state using thread-safe structures to support concurrent sessions in the Gateway and ACP server.

Session and Interactive Context

Hermes uses contextvars to isolate session identities and interactive flags. This prevents race conditions where one session's approval state could clobber another's tools/approval.py35-64

• set_hermes_interactive_context(bool): Binds interactive mode for the current thread or asyncio task tools/approval.py69-76
• set_current_session_key(session_key): Binds the active approval session key to the current context tools/approval.py171-173
• _fire_approval_hook(hook_name): Invokes plugin lifecycle hooks (pre_approval_request, post_approval_response) for observability tools/approval.py96-115

Code Entity Mapping

Sources: tools/approval.py35-173 agent/redact.py1-15 tools/code_execution_tool.py135-173 tools/process_registry.py142-160

---

YOLO and Smart Approvals

YOLO Mode

YOLO mode bypasses dangerous command prompts. To prevent privilege escalation via prompt injection, this mode is frozen at module import time tools/approval.py32-35

• Frozen State: _YOLO_MODE_FROZEN reads HERMES_YOLO_MODE once. Any subsequent environment changes by the agent or skills inside the process are ignored tools/approval.py33-35

Smart Approval

When enabled, the system uses an auxiliary LLM via _smart_approve to analyze command risk tests/tools/test_approval.py66-70

• Auto-Approval: If the auxiliary LLM returns APPROVE, the command proceeds without a user prompt.
• Observability: Smart approval decisions are preceded by _prepare_smart_approval_observer which redacts the command before emitting the hook tools/approval.py123-155
• Policy: Smart approval does not permanently allowlist a pattern; it is a per-command decision tests/tools/test_approval.py79-106

Sources: tools/approval.py30-168 tests/tools/test_approval.py60-106