Security and Pairing

Relevant source files

• .env.example
• AGENTS.md
• README.md
• agent/auxiliary_client.py
• cli-config.yaml.example
• cli.py
• docs/profile-routing.md
• gateway/authz_mixin.py
• gateway/pairing.py
• gateway/profile_routing.py
• gateway/run.py
• hermes_cli/auth.py
• hermes_cli/commands.py
• hermes_cli/config.py
• hermes_cli/main.py
• hermes_cli/models.py
• hermes_cli/pairing.py
• hermes_cli/runtime_provider.py
• hermes_cli/setup.py
• run_agent.py
• tests/agent/test_auxiliary_client.py
• tests/gateway/test_config_driven_access_policy.py
• tests/gateway/test_multiplex_adapter_registry.py
• tests/gateway/test_multiplex_profile_authz.py
• tests/gateway/test_pairing.py
• tests/gateway/test_pairing_allowlist_bypass.py
• tests/gateway/test_profile_resolution.py
• tests/gateway/test_profile_routing.py
• tests/gateway/test_slack_relay_parent_command.py
• tests/hermes_cli/test_commands.py
• tests/hermes_cli/test_model_validation.py
• tests/hermes_cli/test_runtime_provider_resolution.py
• website/docs/user-guide/multi-profile-gateways.md

This page documents the security architecture, user authorization mechanisms, and command approval systems for the Hermes Agent messaging gateway. It details how the system handles allowlist filtering, the Direct Message (DM) pairing system, and the security model for dangerous command execution.

---

Security Model and Authorization Hierarchy

The Hermes Agent gateway implements a multi-layered authorization system to control access across messaging platforms. Authorization is evaluated to determine if an incoming message event should be processed by an agent.

Authorization Logic

The gateway evaluates access in a specific priority order. This logic is implemented via GatewayAuthorizationMixin, which provides the authorization methods for the GatewayRunner gateway/authz_mixin.py61-64

Priority	Check Type	Code Entity / Configuration
1	Upstream Trust	_adapter_authorization_is_upstream gateway/authz_mixin.py155-157
2	Platform Allowlist	_PLATFORM_ALLOWLIST_ENV (e.g., TELEGRAM_ALLOWED_USERS) gateway/pairing.py65-84
3	DM Pairing	PairingStore.is_approved(platform, user_id) gateway/pairing.py236-260
4	Platform Own Policy	_adapter_enforces_own_access_policy gateway/authz_mixin.py111-137
Default	Deny	Fallback to unauthorized_dm_behavior gateway/authz_mixin.py6-7

Adapter-Level Enforcement

Certain platforms enforce their own access policies at the intake layer. The gateway honors these via _adapter_enforces_own_access_policy gateway/authz_mixin.py111-137 In multiplex mode, the gateway ensures that secondary profiles do not fall back to the default profile's adapter to prevent "fail-open" misrouting gateway/authz_mixin.py80-87

Sources: gateway/authz_mixin.py61-157 gateway/pairing.py65-105

---

DM Pairing System

The pairing system provides a secure, code-based approval flow for authorizing new users on messaging platforms without requiring manual configuration of user IDs.

Security Features

The pairing system is designed based on NIST SP 800-63-4 guidance gateway/pairing.py8-16:

• 8-character codes using an unambiguous alphabet ABCDEFGHJKLMNPQRSTUVWXYZ23456789 (no 0/O or 1/I) gateway/pairing.py43-44
• Cryptographic randomness via secrets.choice() gateway/pairing.py10-25
• 1-hour code expiry (CODE_TTL_SECONDS) gateway/pairing.py47
• Hashed Storage: Plaintext codes are never stored. The system stores a SHA-256 hash and a unique salt for each pending request gateway/pairing.py284-315
• Rate Limiting: 1 request per user per 10 minutes and lockout after 5 failed approval attempts for 1 hour gateway/pairing.py48-53

Approval Workflow

1. Request: User sends a message; the gateway generates a code via PairingStore.generate_code() gateway/pairing.py203-234
2. CLI Approval: The administrator approves the code. The system verifies the code against the stored hash using PairingStore.approve_code() gateway/pairing.py262-282
3. Synchronization: If a platform allowlist is already configured (e.g., TELEGRAM_ALLOWED_USERS), approving a code automatically appends the user to that allowlist via _sync_allowlist_add gateway/pairing.py112-139

Sources: gateway/pairing.py8-53 gateway/pairing.py203-315 gateway/pairing.py112-139

---

Command Approval and Safety Guards

The tools.approval module is the single source of truth for detecting and gating dangerous commands tools/approval.py3-9

Dangerous Pattern Detection

The system maintains two tiers of command blocking:

1. Dangerous Patterns: Commands like rm -rf /tmp or chmod 777 that require user approval tools/approval.py4-6
2. Hardline Patterns: Catastrophic commands (e.g., rm -rf /, mkfs, dd to block devices) that are unconditionally blocked even in YOLO mode tests/tools/test_hardline_blocklist.py1-8

Approval Modes

The system supports three approval modes configured in config.yaml tools/approval.py7-8:

• manual: Always prompt the user for dangerous commands.
• smart: Use an auxiliary LLM to auto-approve low-risk commands tools/approval.py7 This uses _smart_approve which calls the LLM with a specific approval task profile tests/tools/test_approval.py66-78
• off: Auto-approve all dangerous commands (except Hardline).

Gateway Approval Mechanism

In the gateway, approvals use a blocking mechanism where the agent thread waits for a user response tests/gateway/test_approve_deny_commands.py3-5

• Registration: register_gateway_notify binds a session to an approval callback tests/gateway/test_approve_deny_commands.py92-94
• Resolution: Users respond with /approve or /deny, which triggers resolve_gateway_approval to unblock the agent tests/gateway/test_approve_deny_commands.py109-110

Sources: tools/approval.py3-67 tests/tools/test_approval.py16-78 tests/tools/test_hardline_blocklist.py1-138 tests/gateway/test_approve_deny_commands.py1-120

---

Security Architecture Diagrams

Pairing and Authorization Data Flow

This diagram maps the logical pairing flow to internal code entities.

Sources: gateway/authz_mixin.py61-64 gateway/pairing.py43-44 gateway/pairing.py203-234 gateway/pairing.py284-315

Command Approval Pipeline

This diagram illustrates how commands are filtered from the agent to the execution environment.

Sources: tools/approval.py3-25 tests/tools/test_approval.py16-78 tests/tools/test_hardline_blocklist.py12-22 tests/gateway/test_approve_deny_commands.py90-110 run_agent.py18-20