afsharidevops/hermes-execution-broker repository overview

⁠Hermes Stack Execution Broker

Security-separated execution and approval boundary for Hermes Linux Stack.

Hermes Execution Broker provides the optional controlled execution layer used by Hermes Linux Stack. It is not a general-purpose remote shell, unrestricted Docker API proxy, or replacement for host access controls.

⁠Current release

Hermes Execution Broker 0.1.3 — paired with Hermes Linux Stack 0.5.8.

docker pull afsharidevops/hermes-execution-broker:0.1.3

Recommended production reference:

afsharidevops/hermes-execution-broker:0.1.3

Because this image is a security boundary, use the explicit version tag or an immutable digest.

⁠Target platforms

linux/amd64
linux/arm64

⁠Purpose and security model

Execution Broker isolates optional execution authority from Smart Router and the normal Hermes application path.

The design separates four responsibilities:

docker
ssh
approver
admin

A structured operation can be prepared by Hermes, but approval and execution authority remain separated.

The independent approver recomputes the request digest and human-readable summary, checks the authorized numeric user, and signs an exact one-time decision.

Brokers validate and atomically consume approved grants.

The goal is to keep powerful host authority out of Smart Router.

⁠Modes

⁠docker

Provides controlled local Sandbox and structured Docker execution.

Docker mode can receive:

Docker socket
approval public verification key
broker/control request material
capability state

It must not receive:

approval private signing key
dedicated Telegram approval-bot token
SSH private credentials

Sandbox controls can include:

• digest-pinned images;
• sealed workspaces;
• non-root execution;
• read-only root filesystem;
• dropped Linux capabilities;
• no-new-privileges;
• bounded process counts;
• no network by default;
• one-time signed approvals.

Only Docker mode receives Docker-socket authority.

⁠ssh

Provides structured SSH operations through locally configured profiles.

SSH mode can seal and verify metadata such as:

• host;
• user;
• authentication type;
• known-hosts identity;
• key/public fingerprint metadata;
• password-profile integrity metadata.

It must not receive:

Docker socket
approval private signing key
dedicated Telegram approval-bot token

Only SSH mode receives SSH profile authority.

⁠approver

Runs the independent Telegram execution approval service.

Responsibilities include:

• Telegram long polling;
• exact human-readable approval summaries;
• authorized numeric-user checks;
• persistent approve/deny state;
• canonical digest verification;
• Ed25519 decision signing.

Approver mode receives:

dedicated Telegram approval-bot token
Ed25519 approval-signing private key
numeric execution-user policy
approval state

It must not receive:

Docker socket
SSH private credentials

⁠admin

Provides the narrow browser-facing configuration boundary used by Hermes Operations Center.

Admin mode can:

• inspect approver/Docker/SSH health;
• enable or disable live local, docker, and ssh policy for already deployed brokers;
• manage numeric execution approver IDs;
• replace the dedicated Telegram approval-bot token without readback;
• rotate the broker control secret;
• expose redacted SSH profile metadata;
• expose execution-admin audit events;
• increment execution policy generation after sensitive policy changes.

Admin mode must not receive:

Ed25519 approval-signing private key
Docker socket
SSH private keys
SSH passwords
Smart Router admin credential

⁠What is new in 0.1.3

0.1.3 is the Execution Broker companion release for Hermes Linux Stack 0.5.8.

The main change is improved browser connectivity for Execution & Approvals while preserving the same trust separation.

Execution Admin now supports the browser preflight behavior needed for private-network administration when the request origin is explicitly allowed.

Hermes 0.5.8 also checks Execution Admin health before attempting key authentication, so operators can distinguish:

network / private bind / CORS problem

from:

invalid Execution Admin key

This does not move the Execution Admin credential into Smart Router.

⁠Operations Center integration

Hermes Operations Center includes:

System
└── Execution & Approvals

The operator browser connects directly to the optional Execution Admin service using a separate Execution Admin key.

Conceptually:

Operator Browser
      |
      | separate Execution Admin key
      v
Execution Admin :8752
      |
      +-- live execution feature policy
      +-- Telegram execution approver IDs
      +-- write-only approval-bot token replacement
      +-- broker control-secret rotation
      +-- health/status
      +-- redacted SSH metadata
      +-- execution-admin audit

Smart Router does not receive the Execution Admin key or the dedicated approval-bot token.

⁠Default binding and remote browser access

Execution Admin defaults to:

127.0.0.1:8752

Loopback is appropriate for local administration but is not reachable from a browser on another machine.

For remote browser administration, configure only a trusted private address and exact Operations Center origin.

With Hermes Linux Stack 0.5.8:

./manage.sh configure-execution-admin-browser   http://YOUR_PRIVATE_SERVER_IP:8787   YOUR_PRIVATE_SERVER_IP

Then verify:

./manage.sh execution-admin-status

Retrieve the separate admin key only from a trusted interactive terminal:

./manage.sh show-execution-admin-key

Do not:

• expose port 8752 directly to the public Internet;
• use wildcard CORS;
• use a public bind as a shortcut;
• place the Execution Admin key in public configuration or logs.

Prefer private administration networks or TLS/reverse-proxy protection.

⁠Live policy and policy generation

Execution Admin can manage live policy for already deployed capabilities:

local
docker
ssh

Security-sensitive changes increment the execution policy generation.

Pending approvals or grants tied to an older policy generation can then fail closed rather than silently surviving a policy change.

First-time deployment or removal of high-authority broker containers remains a host-level manage.sh operation.

The browser does not receive Docker-socket authority.

⁠Telegram approval management

Configure the dedicated execution approval bot through the stack manager:

./manage.sh set-execution-approval-bot-token

Manage numeric execution approvers:

./manage.sh set-execution-users 123456789,987654321
./manage.sh add-execution-user 123456789
./manage.sh remove-execution-user 123456789

Execution approvers must remain within the host-approved Hermes Telegram user boundary.

The dedicated approval-bot token is write-only from Execution Admin:

configured / not configured
replace token

There is intentionally no token-readback API.

⁠Use through Hermes Linux Stack

Use this image through the Hermes Linux Stack docker-compose.yml and manage.sh.

The stack applies mode-specific mounts, state, network separation, and secret handling.

Useful commands:

./manage.sh execution
./manage.sh execution-status

./manage.sh set-execution-approval-bot-token
./manage.sh set-execution-users 123456789
./manage.sh add-execution-user 123456789
./manage.sh remove-execution-user 123456789

./manage.sh enable-execution sandbox
./manage.sh enable-execution docker
./manage.sh enable-execution ssh
./manage.sh enable-execution all

./manage.sh disable-execution sandbox
./manage.sh disable-execution docker
./manage.sh disable-execution ssh
./manage.sh disable-execution all

./manage.sh enable-execution-admin
./manage.sh execution-admin-status
./manage.sh configure-execution-admin-browser   http://YOUR_PRIVATE_SERVER_IP:8787   YOUR_PRIVATE_SERVER_IP

For the complete lifecycle and security model, use the repository README, Execution Broker README, Operations Center guide, and SECURITY.md.

⁠Fail-closed behavior

There are deliberately no safe permissive defaults for privileged execution.

Missing or invalid security material should cause readiness or execution to fail closed, including missing or invalid:

• broker control secret;
• approval-request secret;
• approval signing/verification keys;
• authorized numeric approvers;
• dedicated approval-bot token;
• execution/workspace seals;
• feature policy;
• required SSH authority information.

Never mount the private approval signing key or approval-bot token into Smart Router or the Docker/SSH broker modes.

Do not mount:

Docker socket outside docker mode
SSH profiles outside ssh mode
SSH password-profile authority outside ssh mode

Keep execution-control networking separate from unrestricted/general application networking.

⁠Trust-separation summary

Expected authority split:

Smart Router
  no Execution Admin key
  no approval private signing key
  no Docker socket
  no SSH private credentials

Docker broker
  Docker socket
  approval public key
  no approval private key

SSH broker
  SSH profile authority
  approval public key
  no Docker socket
  no approval private key

Approver
  Telegram approval-bot token
  approval private signing key
  no Docker socket
  no SSH private credentials

Execution Admin
  narrow configuration authority
  separate admin key
  no approval private signing key
  no Docker socket
  no SSH private credentials

⁠Production recommendations

For production:

• pin afsharidevops/hermes-execution-broker:0.1.3 or an immutable digest;
• verify the multi-architecture manifest before rollout;
• keep broker/admin endpoints off the public Internet;
• use exact CORS allowlists;
• use private administration access or TLS reverse proxying;
• validate actual container mounts after deployment;
• keep approval signing authority separate from execution authority;
• rotate credentials if they are ever exposed;
• back up required state according to the Hermes Linux Stack deployment guide.

⁠Source

Repository:

https://github.com/Afsharidevops/hermes-linux-stack

Branches:

main
hermes-omniroute-linux-stack

Execution Broker source:

execution-broker/

The same Execution Broker source is intended to support both Hermes gateway branches.

⁠License

See the repository LICENSE file.

⁠Hermes Stack Execution Broker 0.1.3

Independent approval. Narrow execution authority. Fail-closed configuration.

Hermes can request execution.
The broker validates and isolates execution.
The independent Telegram approver authorizes the exact operation.
Execution Admin can manage policy without receiving the approval signing key or execution authority.