hermes-ssh 0.3.2__tar.gz → 0.3.4__tar.gz

{hermes_ssh-0.3.2 → hermes_ssh-0.3.4}/CHANGELOG.md

@@ -1,5 +1,18 @@
 # Changelog
 
+## Unreleased
+
+- Relax the `cryptography` lower bound to support Hermes Agent 0.19.0's pinned 46.0.7 runtime dependency.
+- Spool background stdout and stderr to restricted files so verbose commands cannot deadlock.
+- Keep returned large-output files available after completed sessions are closed.
+- Redact common inline secrets from audit logs, with metadata-only and disabled modes.
+- Default new machine registrations to the current local user instead of root.
+- Resolve `__version__` from installed package metadata.
+
+## [0.3.3] - 2026-07-24
+
+- Update development dependencies to mypy 2.3.0 and pytest 9.1.1.
+
 ## [0.3.2] - 2026-07-13
 
 - Align the packaged Hermes manifest with the release version.

{hermes_ssh-0.3.2 → hermes_ssh-0.3.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: hermes-ssh
-Version: 0.3.2
+Version: 0.3.4
 Summary: SSH remote execution plugin for Hermes Agent
 Project-URL: Homepage, https://github.com/TheEpTic/hermes-plugins
 Project-URL: Repository, https://github.com/TheEpTic/hermes-plugins
@@ -20,11 +20,11 @@ Classifier: Programming Language :: Python :: 3.13
 Classifier: Topic :: System :: Systems Administration
 Classifier: Typing :: Typed
 Requires-Python: >=3.11
-Requires-Dist: cryptography<49,>=48.0.1
+Requires-Dist: cryptography<49,>=46.0.7
 Provides-Extra: dev
 Requires-Dist: black==26.5.1; extra == 'dev'
-Requires-Dist: mypy==1.16.0; extra == 'dev'
-Requires-Dist: pytest==9.0.3; extra == 'dev'
+Requires-Dist: mypy==2.3.0; extra == 'dev'
+Requires-Dist: pytest==9.1.1; extra == 'dev'
 Description-Content-Type: text/markdown
 
 # hermes-ssh
@@ -37,46 +37,44 @@ SSH remote execution plugin for [Hermes Agent](https://github.com/NousResearch/h
 
 Run commands on remote servers, track sessions, reuse connections — all from inside Hermes.
 
-```
+```text
 /ssh web1 uptime
-ssh_machines add name=web1 host=192.168.1.50
-ssh_sessions list
+ssh_machines action=add name=web1 host=192.168.1.50 user=deploy
+ssh_sessions action=list
 ```
 
-## Quick Start
+## quick start
+
+`hermes-ssh` is for **named multi-host operations**. Hermes's core SSH backend is useful for one configured remote terminal; this plugin adds a reusable machine inventory, aliases, per-command targeting, background sessions, and audit history.
 
-> **Requires Python 3.11+** and an OpenSSH client (`ssh`) on the host system.
+> Requires Python 3.11+, Hermes Agent, and an OpenSSH client named `ssh`.
 
-### Option 1: Deploy script (recommended)
+Install the package into the same Python environment that runs Hermes:
 
 ```bash
-git clone https://github.com/TheEpTic/hermes-plugins.git
-cd hermes-plugins/hermes-ssh
-./deploy.sh
+python -m pip install hermes-ssh
+hermes plugins enable hermes-ssh --no-allow-tool-override
 ```
 
-Then restart Hermes with `/reset`.
-
-### Option 2: Manual symlink
+Run `/reset` or restart Hermes, then verify:
 
 ```bash
-git clone https://github.com/TheEpTic/hermes-plugins.git
-ln -s "$(pwd)/hermes-plugins/hermes-ssh/src/ssh_tools" ~/.hermes/plugins/hermes-ssh
+python -m pip show hermes-ssh
+hermes plugins list --enabled --plain
 ```
 
-Then `/reset` in Hermes. The symlink points at the source tree, but Python modules are imported once, so code changes still require `/reset` or a Hermes process restart before they load.
+If Hermes cannot see the package, the `python` command above was not Hermes's Python. Follow the environment procedure in the repository [AGENTS.md](../AGENTS.md).
 
-### Option 3: As a Python package
+For source development:
 
 ```bash
-pip install git+https://github.com/TheEpTic/hermes-plugins.git#subdirectory=hermes-ssh
+git clone https://github.com/TheEpTic/hermes-plugins.git
+cd hermes-plugins/hermes-ssh
+./deploy.sh
+hermes plugins enable hermes-ssh --no-allow-tool-override
 ```
 
-Then enable it and restart Hermes:
-
-```bash
-hermes plugins enable hermes-ssh
-```
+Run `/reset` or restart Hermes after changing the source tree.
 
 ## Features
 
@@ -84,7 +82,7 @@ hermes plugins enable hermes-ssh
 
 Execute any command on a remote machine. Commands run through `bash -c` with `pipefail`, so pipelines work correctly.
 
-```bash
+```text
 # Synchronous (waits for completion)
 ssh_terminal machine=web1 command="df -h"
 
@@ -97,9 +95,9 @@ ssh_terminal machine=web1 command="make -j4" timeout=300
 
 **Output truncation:** When output exceeds `max_output_chars` (default: 50,000), the full output is saved under the plugin's restricted output directory and a summary with the file path is returned. The LLM can then use `read_file` to access the complete output.
 
-**Background commands:** Long-running commands can be backgrounded. The plugin tracks the process and lets you poll for status or retrieve output later.
+**Background commands:** Long-running commands spool stdout and stderr to restricted files, avoiding pipe-buffer deadlocks. The plugin tracks the process and lets you poll for status or retrieve output later.
 
-```bash
+```text
 # Check if still running
 ssh_terminal poll=<session_id>
 
@@ -115,7 +113,7 @@ ssh_sessions action=read_output session_id=<session_id>
 
 Register servers once, refer to them by name or alias.
 
-```bash
+```text
 # Add a server
 ssh_machines action=add name=web1 host=192.168.1.50 user=deploy key=~/.ssh/id_ed25519
 
@@ -138,7 +136,7 @@ Machine names must be alphanumeric with dots, hyphens, or underscores (1-64 char
 
 Every command creates a session. Sessions track the PID, machine, command count, and idle time.
 
-```bash
+```text
 # List active sessions
 ssh_sessions action=list
 
@@ -175,10 +173,11 @@ All settings live in `src/ssh_tools/config.py` as an `SSHConfig` dataclass:
 | Setting | Default | Description |
 |---------|---------|-------------|
 | `default_port` | 22 | SSH port for new machines |
-| `default_user` | root | SSH user for new machines |
+| `default_user` | current local user | SSH user for new machines |
 | `connect_timeout` | 5s | SSH handshake timeout |
 | `command_timeout` | 30s | Command execution timeout |
 | `max_output_chars` | 50,000 | Output truncation threshold |
+| `audit_log_mode` | redacted | `redacted`, `metadata`, or `off` |
 | `idle_check_interval` | 60s | Seconds between idle checks |
 | `idle_timeout_minutes` | 30m | Auto-kill after this idle time |
 | `closed_prune_hours` | 24h | Remove closed sessions after this |
@@ -219,6 +218,7 @@ See [SECURITY.md](SECURITY.md) for the full picture.
 
 - `StrictHostKeyChecking=accept-new` — accepts first-seen host keys but rejects changed keys. Set to `yes` for strict production hosts.
 - Machine credentials are encrypted at rest in `~/.hermes/ssh-tools/machines.json`. Data directory is 0o700.
+- Audit logs redact common inline credentials by default. Use metadata mode when command text must not be stored.
 - All commands execute with the permissions of the Hermes agent process.
 
 **Hardening applied:**

{hermes_ssh-0.3.2 → hermes_ssh-0.3.4}/README.md

@@ -8,46 +8,44 @@ SSH remote execution plugin for [Hermes Agent](https://github.com/NousResearch/h
 
 Run commands on remote servers, track sessions, reuse connections — all from inside Hermes.
 
-```
+```text
 /ssh web1 uptime
-ssh_machines add name=web1 host=192.168.1.50
-ssh_sessions list
+ssh_machines action=add name=web1 host=192.168.1.50 user=deploy
+ssh_sessions action=list
 ```
 
-## Quick Start
+## quick start
+
+`hermes-ssh` is for **named multi-host operations**. Hermes's core SSH backend is useful for one configured remote terminal; this plugin adds a reusable machine inventory, aliases, per-command targeting, background sessions, and audit history.
 
-> **Requires Python 3.11+** and an OpenSSH client (`ssh`) on the host system.
+> Requires Python 3.11+, Hermes Agent, and an OpenSSH client named `ssh`.
 
-### Option 1: Deploy script (recommended)
+Install the package into the same Python environment that runs Hermes:
 
 ```bash
-git clone https://github.com/TheEpTic/hermes-plugins.git
-cd hermes-plugins/hermes-ssh
-./deploy.sh
+python -m pip install hermes-ssh
+hermes plugins enable hermes-ssh --no-allow-tool-override
 ```
 
-Then restart Hermes with `/reset`.
-
-### Option 2: Manual symlink
+Run `/reset` or restart Hermes, then verify:
 
 ```bash
-git clone https://github.com/TheEpTic/hermes-plugins.git
-ln -s "$(pwd)/hermes-plugins/hermes-ssh/src/ssh_tools" ~/.hermes/plugins/hermes-ssh
+python -m pip show hermes-ssh
+hermes plugins list --enabled --plain
 ```
 
-Then `/reset` in Hermes. The symlink points at the source tree, but Python modules are imported once, so code changes still require `/reset` or a Hermes process restart before they load.
+If Hermes cannot see the package, the `python` command above was not Hermes's Python. Follow the environment procedure in the repository [AGENTS.md](../AGENTS.md).
 
-### Option 3: As a Python package
+For source development:
 
 ```bash
-pip install git+https://github.com/TheEpTic/hermes-plugins.git#subdirectory=hermes-ssh
+git clone https://github.com/TheEpTic/hermes-plugins.git
+cd hermes-plugins/hermes-ssh
+./deploy.sh
+hermes plugins enable hermes-ssh --no-allow-tool-override
 ```
 
-Then enable it and restart Hermes:
-
-```bash
-hermes plugins enable hermes-ssh
-```
+Run `/reset` or restart Hermes after changing the source tree.
 
 ## Features
 
@@ -55,7 +53,7 @@ hermes plugins enable hermes-ssh
 
 Execute any command on a remote machine. Commands run through `bash -c` with `pipefail`, so pipelines work correctly.
 
-```bash
+```text
 # Synchronous (waits for completion)
 ssh_terminal machine=web1 command="df -h"
 
@@ -68,9 +66,9 @@ ssh_terminal machine=web1 command="make -j4" timeout=300
 
 **Output truncation:** When output exceeds `max_output_chars` (default: 50,000), the full output is saved under the plugin's restricted output directory and a summary with the file path is returned. The LLM can then use `read_file` to access the complete output.
 
-**Background commands:** Long-running commands can be backgrounded. The plugin tracks the process and lets you poll for status or retrieve output later.
+**Background commands:** Long-running commands spool stdout and stderr to restricted files, avoiding pipe-buffer deadlocks. The plugin tracks the process and lets you poll for status or retrieve output later.
 
-```bash
+```text
 # Check if still running
 ssh_terminal poll=<session_id>
 
@@ -86,7 +84,7 @@ ssh_sessions action=read_output session_id=<session_id>
 
 Register servers once, refer to them by name or alias.
 
-```bash
+```text
 # Add a server
 ssh_machines action=add name=web1 host=192.168.1.50 user=deploy key=~/.ssh/id_ed25519
 
@@ -109,7 +107,7 @@ Machine names must be alphanumeric with dots, hyphens, or underscores (1-64 char
 
 Every command creates a session. Sessions track the PID, machine, command count, and idle time.
 
-```bash
+```text
 # List active sessions
 ssh_sessions action=list
 
@@ -146,10 +144,11 @@ All settings live in `src/ssh_tools/config.py` as an `SSHConfig` dataclass:
 | Setting | Default | Description |
 |---------|---------|-------------|
 | `default_port` | 22 | SSH port for new machines |
-| `default_user` | root | SSH user for new machines |
+| `default_user` | current local user | SSH user for new machines |
 | `connect_timeout` | 5s | SSH handshake timeout |
 | `command_timeout` | 30s | Command execution timeout |
 | `max_output_chars` | 50,000 | Output truncation threshold |
+| `audit_log_mode` | redacted | `redacted`, `metadata`, or `off` |
 | `idle_check_interval` | 60s | Seconds between idle checks |
 | `idle_timeout_minutes` | 30m | Auto-kill after this idle time |
 | `closed_prune_hours` | 24h | Remove closed sessions after this |
@@ -190,6 +189,7 @@ See [SECURITY.md](SECURITY.md) for the full picture.
 
 - `StrictHostKeyChecking=accept-new` — accepts first-seen host keys but rejects changed keys. Set to `yes` for strict production hosts.
 - Machine credentials are encrypted at rest in `~/.hermes/ssh-tools/machines.json`. Data directory is 0o700.
+- Audit logs redact common inline credentials by default. Use metadata mode when command text must not be stored.
 - All commands execute with the permissions of the Hermes agent process.
 
 **Hardening applied:**

hermes_ssh-0.3.4/llms.txt

@@ -0,0 +1,59 @@
+# hermes-ssh
+
+Named multi-host SSH operations for Hermes Agent.
+
+## install
+
+Install into the exact Python environment that launches `hermes`:
+
+```bash
+/path/to/hermes-python -m pip install hermes-ssh
+hermes plugins enable hermes-ssh --no-allow-tool-override
+hermes plugins list --enabled --plain
+```
+
+Run `/reset` or restart Hermes. Do not use the monorepo URL with `hermes plugins install`.
+
+Requirements: Python 3.11+, Hermes Agent, and OpenSSH `ssh`.
+
+## safe setup
+
+Ask the user for the machine name, host, SSH user, port, and key path. Never guess root access.
+
+```text
+ssh_machines action=add name=web1 host=192.0.2.10 user=deploy key=~/.ssh/id_ed25519
+ssh_machines action=test name=web1
+```
+
+## tools
+
+```text
+ssh_terminal machine=web1 command="df -h"
+ssh_terminal machine=web1 command="make -j4" background=true
+ssh_terminal poll=<session_id>
+ssh_terminal read_output=<session_id>
+
+ssh_machines action=list
+ssh_machines action=inspect name=web1
+ssh_machines action=test name=web1
+ssh_machines action=remove name=web1
+
+ssh_sessions action=list
+ssh_sessions action=kill session_id=<id>
+ssh_sessions action=cleanup
+ssh_sessions action=prune
+```
+
+Slash command:
+
+```text
+/ssh
+/ssh web1
+/ssh web1 uptime
+/ssh test
+/ssh cleanup
+```
+
+Large outputs are retained under the restricted output directory and returned by path. Background output is spooled to files rather than pipes. Machine records are encrypted at rest. Audit logs redact common inline credentials by default; configuration supports `redacted`, `metadata`, and `off`.
+
+Commands run with the remote user's permissions. Use dedicated non-root accounts and least privilege.

{hermes_ssh-0.3.2 → hermes_ssh-0.3.4}/pyproject.toml

@@ -4,12 +4,12 @@ build-backend = "hatchling.build"
 
 [project]
 name = "hermes-ssh"
-version = "0.3.2"
+version = "0.3.4"
 description = "SSH remote execution plugin for Hermes Agent"
 readme = "README.md"
 requires-python = ">=3.11"
 license = "MIT"
-dependencies = ["cryptography >= 48.0.1, < 49"]
+dependencies = ["cryptography >= 46.0.7, < 49"]
 authors = [
     { name = "TheEpTic", email = "nexus@eptic.me" },
 ]
@@ -36,8 +36,8 @@ Changelog = "https://github.com/TheEpTic/hermes-plugins/blob/main/hermes-ssh/CHA
 [project.optional-dependencies]
 dev = [
     "black==26.5.1",
-    "mypy==1.16.0",
-    "pytest==9.0.3",
+    "mypy==2.3.0",
+    "pytest==9.1.1",
 ]
 
 [tool.hatch.build.targets.wheel]

{hermes_ssh-0.3.2 → hermes_ssh-0.3.4}/src/ssh_tools/__init__.py

@@ -10,6 +10,7 @@ Provides:
 from __future__ import annotations
 
 import logging
+from importlib.metadata import PackageNotFoundError, version as distribution_version
 from typing import Any
 
 from .handlers import handle_ssh_machines, handle_ssh_sessions, handle_ssh_terminal
@@ -17,7 +18,10 @@ from .handlers.slash import create_slash_handler
 from .manager import SSHManager
 from .schemas import SSH_MACHINES_SCHEMA, SSH_SESSIONS_SCHEMA, SSH_TERMINAL_SCHEMA
 
-__version__ = "0.2.0"
+try:
+    __version__ = distribution_version("hermes-ssh")
+except PackageNotFoundError:
+    __version__ = "0.0.0+local"
 __all__ = [
     "SSH_MACHINES_SCHEMA",
     "SSH_SESSIONS_SCHEMA",

{hermes_ssh-0.3.2 → hermes_ssh-0.3.4}/src/ssh_tools/config.py

@@ -3,6 +3,7 @@
 from __future__ import annotations
 
 import contextlib
+import getpass
 import os
 from dataclasses import dataclass, field
 from pathlib import Path
@@ -19,13 +20,14 @@ class SSHConfig:
 
     # SSH defaults
     default_port: int = 22
-    default_user: str = "root"
+    default_user: str = field(default_factory=getpass.getuser)
     connect_timeout: int = 5
     command_timeout: int = 30
     strict_host_key_checking: str = "accept-new"
 
     # Output
     max_output_chars: int = 50_000  # save to output_dir if exceeded
+    audit_log_mode: str = "redacted"  # redacted, metadata, or off
 
     # Session management
     idle_check_interval: int = 60  # seconds between idle checks

{hermes_ssh-0.3.2 → hermes_ssh-0.3.4}/src/ssh_tools/handlers/machines.py

@@ -45,7 +45,7 @@ def handle_ssh_machines(manager: SSHManager) -> Callable[[dict[str, Any]], str]:
                     Machine(
                         name=params["name"],
                         host=params["host"],
-                        user=params.get("user", "root"),
+                        user=params.get("user") or manager.config.default_user,
                         port=params.get("port", 22),
                         key=params.get("key", ""),
                         aliases=params.get("aliases", []),