hermes-ssh 0.3.1__tar.gz

hermes_ssh-0.3.1/.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,27 @@
+---
+name: Bug Report
+about: Report a bug in hermes-ssh
+title: ''
+labels: bug
+assignees: ''
+---
+
+**Describe the bug**
+A clear description of what the bug is.
+
+**To reproduce**
+Steps to reproduce the behavior:
+1. ...
+2. ...
+
+**Expected behavior**
+What you expected to happen.
+
+**Environment**
+- OS: [e.g. Ubuntu 24.04, macOS 15]
+- Python version: [e.g. 3.12.3]
+- Hermes version: [e.g. 0.5.0]
+- hermes-ssh version: [e.g. 0.1.0]
+
+**Additional context**
+Any other context (logs, config, etc.).

hermes_ssh-0.3.1/.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,16 @@
+---
+name: Feature Request
+about: Suggest a feature for hermes-ssh
+title: ''
+labels: enhancement
+assignees: ''
+---
+
+**Description**
+What you'd like to happen.
+
+**Use case**
+Why this would be useful.
+
+**Alternatives considered**
+Any workarounds or alternative approaches you've thought of.

hermes_ssh-0.3.1/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,23 @@
+## Description
+
+What does this PR do?
+
+## Type of change
+
+- [ ] Bug fix
+- [ ] New feature
+- [ ] Breaking change
+- [ ] Documentation update
+
+## Testing
+
+- [ ] Tests pass (`pytest`)
+- [ ] Formatting passes (`black --check`)
+- [ ] Type check passes (`mypy`)
+- [ ] New tests added (if bug fix)
+
+## Checklist
+
+- [ ] Code follows project style
+- [ ] Self-review completed
+- [ ] Documentation updated (if needed)

hermes_ssh-0.3.1/.github/workflows/ci.yml

@@ -0,0 +1,43 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+concurrency:
+  group: ci-${{ github.ref }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+
+jobs:
+  lint:
+    name: Format & Type Check
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.13"
+      - run: pip install black==26.5.1 mypy==1.16.0
+      - run: black --check src/ssh_tools/ tests/
+      - run: mypy src/ssh_tools/
+
+  test:
+    name: Tests (Python ${{ matrix.python-version }})
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - run: pip install -e '.[dev]'
+      - run: black --check src/ssh_tools/ tests/
+      - run: mypy src/ssh_tools/
+      - run: pytest

hermes_ssh-0.3.1/.gitignore

@@ -0,0 +1,40 @@
+# Python
+__pycache__/
+*.pyc
+*.pyo
+*.egg-info/
+dist/
+build/
+.eggs/
+
+# Virtual environments
+.venv/
+venv/
+
+# Testing
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+
+# IDE
+.vscode/
+.idea/
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Runtime data (secrets, credentials, logs — NEVER commit)
+**/data/
+**/sockets/
+*.tmp
+*.lock
+!**/uv.lock
+
+# Environment
+.env
+.env.*
+
+# Hermes runtime (if symlinked from install)
+*.log
+node_modules

hermes_ssh-0.3.1/CHANGELOG.md

@@ -0,0 +1,71 @@
+# Changelog
+
+## [0.3.1] - 2026-07-13
+
+- Fix the release artifact path so the tagged build can reach PyPI.
+
+## [0.3.0] - 2026-07-13
+
+- Fail closed when Hermes command approvals are unavailable.
+- Never signal persisted PIDs after restart; only tracked process groups can be killed.
+- Preserve shared SSH ControlMaster sockets when killing individual commands.
+- Make `cryptography` a required dependency and add packaged-plugin discovery metadata.
+- Declare provided tools in the Hermes plugin manifest.
+
+## 0.2.0 — Bug hunt, security hardening, documentation
+
+### New features
+
+- **Background commands** — run long commands with `background=true`, poll status, read output when done
+- **Output truncation** — outputs exceeding `max_output_chars` (50K) saved under the restricted plugin output directory; LLM can `read_file` the full output
+- **Command audit log** — every command logged with timestamps, machine, exit code, and session ID (`~/.hermes/ssh-tools/command_log.jsonl`)
+- **Poll/read_output on ssh_terminal** — check background command status directly from the terminal tool
+- **Machine name validation** — names must match `^[a-zA-Z0-9][a-zA-Z0-9._-]{0,63}$`; prevents path traversal and glob injection
+
+### Bug fixes
+
+- `ssh_terminal` poll/read_output no longer requires machine/command parameters
+- Background process dict uses atomic `pop()` to prevent output loss on concurrent polls
+- Output files written with 0o600 permissions in the restricted plugin output directory
+- Batch session cleanup now removes orphaned saved output files
+- `_write_json` calls `fsync` before `os.replace` to prevent data loss on crash
+- Orphaned SSH control socket files removed after session kill
+- `slash.py` no longer uses `assert` in production code (stripped with `python -O`)
+- Stale help text fixed: `max_output_lines` → `max_output_chars`
+- `list_command_log` reads file tail instead of entire file (unbounded memory)
+- `_log_command` uses single `os.open` instead of double open TOCTOU
+- `prune_closed` handles sessions with naive (non-timezone) timestamps
+- `_load_machines`/`_load_sessions` validate JSON structure (dict check)
+- Startup cleans orphaned `.tmp` files from data directory
+- Background sessions registered in JSON before process reference stored
+- `timeout` parameter coerced to int (string input no longer crashes)
+- Tool schemas updated: poll/read_output descriptions mention session_id
+- `require()` docstring corrected (non-empty → non-None)
+
+### Security
+
+- Data directory created with 0o700 permissions
+- Audit log created with 0o600 permissions
+- Output files written with 0o600 permissions
+- Machine names validated against `^[a-zA-Z0-9][a-zA-Z0-9._-]{0,63}$`
+- `_cleanup_output_files` uses `iterdir()` + prefix matching instead of glob (prevents glob injection)
+
+### Documentation
+
+- `llms.txt` added — installation and usage guide for LLMs
+- README rewritten with full feature documentation
+- CHANGELOG updated
+
+## 0.1.0 — Initial release
+
+- `ssh_terminal` — run commands on remote machines via SSH
+- `ssh_machines` — machine registry with aliases, tags, and connectivity tests
+- `ssh_sessions` — session tracking with idle detection and cleanup
+- `ControlMaster` — persistent SSH connections with 5-minute reuse window
+- `bash -c` wrapping with `pipefail` for reliable pipeline exit codes
+- `/ssh` slash command for quick machine inspection and command execution
+- Background idle checker with configurable timeout
+- Atomic JSON writes with temp files for crash safety
+- Thread-safe operations via locks
+- 77 tests covering config, manager, tool handlers, and edge cases
+- CI with black, mypy, and pytest across Python 3.11–3.13

hermes_ssh-0.3.1/CONTRIBUTING.md

@@ -0,0 +1,78 @@
+# Contributing
+
+PRs welcome. Here's the workflow.
+
+## Setup
+
+```bash
+git clone https://github.com/TheEpTic/hermes-plugins.git
+cd hermes-plugins/hermes-ssh
+python -m venv .venv && source .venv/bin/activate
+pip install -e '.[dev]'
+```
+
+## Development
+
+```bash
+black src/ssh_tools/ tests/
+mypy src/ssh_tools/
+pytest
+```
+
+## Testing
+
+Run the full test suite with:
+
+```bash
+pytest
+```
+
+For coverage:
+
+```bash
+pytest --cov=ssh_tools --cov-report=term-missing
+```
+
+Aim for **90%+ coverage** on new code. The test suite uses pytest fixtures defined in `tests/conftest.py` for mocking SSH connections and the manager. When adding a new tool or handler, write tests that cover:
+
+- Happy path (valid input, successful execution)
+- Error cases (missing params, connection failures, timeouts)
+- Edge cases (empty output, very large output, special characters)
+
+## Guidelines
+
+- **Tests required for bug fixes.** Each fix gets a test that reproduces the issue.
+- **Separate PRs for separate concerns.** Don't bundle unrelated changes.
+- Run `black` and `mypy` before pushing. CI will catch it if you don't.
+
+## Project Structure
+
+```
+src/ssh_tools/
+├── __init__.py          # Plugin registration + Hermes hooks
+├── config.py            # SSHConfig dataclass (all settings)
+├── manager.py           # SSHManager — machines, sessions, execution
+├── models.py            # Machine, Session dataclasses
+├── schemas.py           # Tool schemas (what the LLM sees)
+├── utils.py             # Shared helpers (ok/err response builders)
+├── py.typed             # PEP 561 marker
+└── handlers/
+    ├── __init__.py
+    ├── terminal.py      # ssh_terminal tool handler
+    ├── machines.py      # ssh_machines tool handler
+    ├── sessions.py      # ssh_sessions tool handler
+    └── slash.py         # /ssh slash command
+tests/
+├── conftest.py          # Shared fixtures
+├── test_config.py
+├── test_manager.py
+└── test_tools.py
+```
+
+## Architecture
+
+- **`SSHManager`** owns all state. Thread-safe. No module-level mutable state.
+- **Handlers** are thin wrappers — validate params, dispatch to manager, return JSON.
+- **`utils.py`** provides `ok()`, `err()`, `require()` to eliminate boilerplate.
+- **`/ssh` slash command** uses a factory pattern (`create_slash_handler`) for testability.
+- **Idle checker** runs as a background daemon thread, cleaning up stale sessions.

hermes_ssh-0.3.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 TheEpTic
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

hermes_ssh-0.3.1/PKG-INFO

@@ -0,0 +1,273 @@
+Metadata-Version: 2.4
+Name: hermes-ssh
+Version: 0.3.1
+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
+Project-URL: Issues, https://github.com/TheEpTic/hermes-plugins/issues
+Project-URL: Changelog, https://github.com/TheEpTic/hermes-plugins/blob/main/hermes-ssh/CHANGELOG.md
+Author-email: TheEpTic <nexus@eptic.me>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agent,devops,hermes,remote,ssh
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+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
+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'
+Description-Content-Type: text/markdown
+
+# hermes-ssh
+
+[![CI](https://github.com/TheEpTic/hermes-plugins/actions/workflows/ci.yml/badge.svg)](https://github.com/TheEpTic/hermes-plugins/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+[![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)
+
+SSH remote execution plugin for [Hermes Agent](https://github.com/NousResearch/hermes-agent).
+
+Run commands on remote servers, track sessions, reuse connections — all from inside Hermes.
+
+```
+/ssh web1 uptime
+ssh_machines add name=web1 host=192.168.1.50
+ssh_sessions list
+```
+
+## Quick Start
+
+> **Requires Python 3.11+** and an OpenSSH client (`ssh`) on the host system.
+
+### Option 1: Deploy script (recommended)
+
+```bash
+git clone https://github.com/TheEpTic/hermes-plugins.git
+cd hermes-plugins/hermes-ssh
+./deploy.sh
+```
+
+Then restart Hermes with `/reset`.
+
+### Option 2: Manual symlink
+
+```bash
+git clone https://github.com/TheEpTic/hermes-plugins.git
+ln -s "$(pwd)/hermes-plugins/hermes-ssh/src/ssh_tools" ~/.hermes/plugins/hermes-ssh
+```
+
+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.
+
+### Option 3: As a Python package
+
+```bash
+pip install git+https://github.com/TheEpTic/hermes-plugins.git#subdirectory=hermes-ssh
+```
+
+Then enable it and restart Hermes:
+
+```bash
+hermes plugins enable hermes-ssh
+```
+
+## Features
+
+### `ssh_terminal` — Run Commands
+
+Execute any command on a remote machine. Commands run through `bash -c` with `pipefail`, so pipelines work correctly.
+
+```bash
+# Synchronous (waits for completion)
+ssh_terminal machine=web1 command="df -h"
+
+# Background (returns immediately)
+ssh_terminal machine=web1 command="tail -f /var/log/syslog" background=true
+
+# With timeout
+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.
+
+```bash
+# Check if still running
+ssh_terminal poll=<session_id>
+
+# Read output from completed command
+ssh_terminal read_output=<session_id>
+
+# Or via ssh_sessions
+ssh_sessions action=poll session_id=<session_id>
+ssh_sessions action=read_output session_id=<session_id>
+```
+
+### `ssh_machines` — Machine Registry
+
+Register servers once, refer to them by name or alias.
+
+```bash
+# Add a server
+ssh_machines action=add name=web1 host=192.168.1.50 user=deploy key=~/.ssh/id_ed25519
+
+# Add with aliases and tags
+ssh_machines action=add name=prod-web host=10.0.0.1 aliases=web1,tags=production,web
+
+# List all machines
+ssh_machines action=list
+
+# Test connectivity
+ssh_machines action=test name=web1
+
+# Get full details
+ssh_machines action=inspect name=web1
+```
+
+Machine names must be alphanumeric with dots, hyphens, or underscores (1-64 chars). Slashes, spaces, and glob characters are rejected.
+
+### `ssh_sessions` — Session Tracking
+
+Every command creates a session. Sessions track the PID, machine, command count, and idle time.
+
+```bash
+# List active sessions
+ssh_sessions action=list
+
+# Kill a session (terminates the SSH process)
+ssh_sessions action=kill session_id=<session_id>
+
+# Clean up all idle sessions (>30 min)
+ssh_sessions action=cleanup
+
+# Remove old closed sessions (>24 hours)
+ssh_sessions action=prune
+```
+
+Idle sessions are automatically killed by a background checker after 30 minutes. Closed sessions are pruned after 24 hours.
+
+### `/ssh` Slash Command
+
+Quick access from chat without remembering tool names:
+
+```
+/ssh                     # List machines and sessions
+/ssh web1                # Inspect a machine
+/ssh web1 uptime         # Run a command
+/ssh web1 docker ps      # Run a command
+/ssh test                # Test connectivity to all machines
+/ssh cleanup             # Kill all idle sessions
+/ssh help                # Show help
+```
+
+## Configuration
+
+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 |
+| `connect_timeout` | 5s | SSH handshake timeout |
+| `command_timeout` | 30s | Command execution timeout |
+| `max_output_chars` | 50,000 | Output truncation threshold |
+| `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 |
+| `strict_host_key_checking` | accept-new | SSH host key verification |
+
+## Architecture
+
+```
+src/ssh_tools/
+├── __init__.py          # Plugin registration + Hermes hooks
+├── config.py            # SSHConfig (immutable dataclass)
+├── manager.py           # SSHManager — all state and operations
+├── models.py            # Machine, Session dataclasses
+├── schemas.py           # Tool schemas (LLM-facing)
+├── utils.py             # ok(), err(), require() helpers
+├── py.typed             # PEP 561 marker
+└── handlers/
+    ├── terminal.py      # ssh_terminal (execute, poll, read_output)
+    ├── machines.py      # ssh_machines (add/list/remove/test/inspect)
+    ├── sessions.py      # ssh_sessions (list/kill/cleanup/prune/poll/read_output)
+    └── slash.py         # /ssh slash command
+```
+
+**Key design decisions:**
+
+- `SSHManager` owns all state. Thread-safe. No module-level mutable state.
+- Handlers are thin closures — validate params, dispatch to manager, return JSON.
+- JSON files use atomic writes (temp file + `os.replace`) for crash safety.
+- Data directory has restricted permissions (0o700). Audit log and output files use 0o600.
+- Machine names are validated to prevent path traversal and glob injection.
+- Connection reuse via `ControlMaster` with 5-minute persist window.
+
+## Security
+
+See [SECURITY.md](SECURITY.md) for the full picture.
+
+**Defaults you should know about:**
+
+- `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.
+- All commands execute with the permissions of the Hermes agent process.
+
+**Hardening applied:**
+
+- Machine names validated against `^[a-zA-Z0-9][a-zA-Z0-9._-]{0,63}$`
+- Output files written with 0o600 permissions
+- Audit log created with 0o600 permissions
+- Atomic JSON writes prevent corruption on crash
+- Orphaned temp files cleaned on startup
+
+## Requirements
+
+- Python 3.11+
+- OpenSSH client (`ssh`)
+- [Hermes Agent](https://github.com/NousResearch/hermes-agent)
+
+## Troubleshooting
+
+**Connection refused**
+The remote host may not be listening on the expected port, or a firewall is blocking the connection. Verify with `ssh -v user@host` outside of Hermes.
+
+**Permission denied (publickey)**
+The SSH key path stored in the machine registry may be incorrect, or the remote host doesn't have the corresponding public key in `~/.ssh/authorized_keys`. Verify with `ssh -i /path/to/key user@host`.
+
+**Command timeout**
+Commands exceeding `command_timeout` (default 30s) are killed. Increase the timeout or use `background=true` for long-running work.
+
+**Output looks truncated**
+This is intentional — large outputs are saved under the restricted plugin output directory and a summary is returned. Use `read_output` or `read_file` on the returned path for the full output.
+
+**Session stuck as "active" after process died**
+If the agent restarted, background process references are lost. Use `ssh_sessions action=cleanup` to kill stale sessions, or `ssh_sessions action=prune` to remove old closed ones.
+
+## Development
+
+```bash
+git clone https://github.com/TheEpTic/hermes-plugins.git
+cd hermes-plugins/hermes-ssh
+python -m venv .venv && source .venv/bin/activate
+pip install -e '.[dev]'
+
+# Run checks
+black --check src/ssh_tools/ tests/
+mypy src/ssh_tools/
+pytest
+```
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
+
+## License
+
+MIT — see [LICENSE](LICENSE).