All plugins

hermes-custodian

Local, read-only security-posture monitor for the machine a Hermes agent runs on (Linux, macOS, native Windows): scoped file and permission baselines, evidence-backed findings and a change history, a first-run terminal setup, an optional background monitor and an on-demand authenticated loopback dashboard. Registers four read-only tools (warden_status, warden_findings, warden_changes, warden_scan). Disclosure — reads: regular files and metadata under paths the user approves in setup; Hermes profile config metadata (model, provider, plugin and MCP-server names) only after explicit consent; credential files (.env, auth stores, keys), memory, chat history and SOUL are never opened (metadata only) and only .py/.md files are content-hashed; symlinks and reparse points are not followed. Runs: a foreground or per-user background monitor (systemd user service, LaunchAgent or Task Scheduler task) only when the user starts or installs it; fixed argument-array subprocesses with timeouts, explicit command-specific minimal environments and no shell (systemctl and apt list --upgradable; launchctl and softwareupdate -l; schtasks and a fixed PowerShell Windows Update query); update detection installs nothing; a Linux-only root security-update plan/apply is a separate terminal command with typed confirmation that the AI tools and dashboard cannot reach. Network: no telemetry and no model calls; the dashboard binds 127.0.0.1 only behind a username/password session (scrypt, signed cookie, exact Host and Origin checks); native OS update queries may contact the OS vendor's update service. Stores: paths, fingerprints, findings and the hashed dashboard login in a private per-user state directory; never credential contents. No self-updater, no approval or confirmation arguments for the AI, no root shell. Not an antivirus or EDR: same-user software can change its configuration. Native tests pass on Linux, macOS and Windows with Python 3.11-3.14 at the pinned commit.

Cam-AcitveIceToolsv0.1.1Updated 20 hours ago

About

Local, read-only security-posture monitor for the machine a Hermes agent runs on (Linux, macOS, native Windows): scoped file and permission baselines, evidence-backed findings and a change history, a first-run terminal setup, an optional background monitor and an on-demand authenticated loopback dashboard. Registers four read-only tools (warden_status, warden_findings, warden_changes, warden_scan). Disclosure — reads: regular files and metadata under paths the user approves in setup; Hermes profile config metadata (model, provider, plugin and MCP-server names) only after explicit consent; credential files (.env, auth stores, keys), memory, chat history and SOUL are never opened (metadata only) and only .py/.md files are content-hashed; symlinks and reparse points are not followed. Runs: a foreground or per-user background monitor (systemd user service, LaunchAgent or Task Scheduler task) only when the user starts or installs it; fixed argument-array subprocesses with timeouts, explicit command-specific minimal environments and no shell (systemctl and apt list --upgradable; launchctl and softwareupdate -l; schtasks and a fixed PowerShell Windows Update query); update detection installs nothing; a Linux-only root security-update plan/apply is a separate terminal command with typed confirmation that the AI tools and dashboard cannot reach. Network: no telemetry and no model calls; the dashboard binds 127.0.0.1 only behind a username/password session (scrypt, signed cookie, exact Host and Origin checks); native OS update queries may contact the OS vendor's update service. Stores: paths, fingerprints, findings and the hashed dashboard login in a private per-user state directory; never credential contents. No self-updater, no approval or confirmation arguments for the AI, no root shell. Not an antivirus or EDR: same-user software can change its configuration. Native tests pass on Linux, macOS and Windows with Python 3.11-3.14 at the pinned commit.

Hermes Security Warden

Ask your Hermes agent "what needs attention on this machine?" and get an answer backed by evidence.

Warden watches the machine your Hermes agent runs on. It records what your files and permissions look like, notices when they change, and shows you what needs a look — in the terminal, in a local web dashboard, or through your agent.

  • Evidence, not scores. Every finding shows the path, what's wrong, when it was seen and what to do about it.
  • Change history. A saved baseline turns "something is different" into a dated list of changes.
  • You choose the scope. Nothing is watched until you approve it. Credential files, memory and chat history are never opened.
  • Honest about gaps. If a scan is incomplete or its data can't be read, it says so rather than showing an empty, all-clear screen.
  • Local only. No telemetry, no cloud, no self-updater. The dashboard runs on your machine behind a login, and the agent can't grant itself more access.

Works on Linux, macOS and Windows with Python 3.11 or newer.

Screenshots

Screenshots use synthetic data only.

Overview — what needs attention, coverage and monitor state.

Overview: what needs attention, coverage and monitor state

Findings — evidence, severity and timestamps for each open finding.

Findings list with evidence and severity

Changes — what changed since the previous scan.

Changes since the previous scan

Install

Standalone

Clone the repository and install it into its own virtual environment.

Linux / macOS

git clone https://github.com/Cam-AcitveIce/hermes-custodian.git
cd hermes-custodian
python3 -m venv .venv
.venv/bin/pip install -e .

To run warden from anywhere instead of typing .venv/bin/warden, link it onto your PATH:

ln -s "$PWD/.venv/bin/warden" ~/.local/bin/warden

Windows (PowerShell)

git clone https://github.com/Cam-AcitveIce/hermes-custodian.git
cd hermes-custodian
py -3 -m venv .venv
.\.venv\Scripts\pip install -e .

The command is then .\.venv\Scripts\warden.exe.

To update later, run git pull in the folder. The -e install picks up the new code automatically.

As a Hermes plugin

Installing as a plugin also gives your agent four read-only tools: warden_status, warden_findings, warden_changes and warden_scan.

hermes plugins install https://github.com/Cam-AcitveIce/hermes-custodian
hermes warden setup

Hermes asks before installing the plugin's Python dependencies. Inside Hermes, every command below is run as hermes warden <command>.

Get started

warden setup       # choose your Hermes profiles and the folders to watch
warden scan        # run a first scan
warden findings    # see what needs attention
warden dashboard   # open the web dashboard

Setup asks for your consent at each step and offers to create a dashboard login at the end. It doesn't start monitoring or install anything that runs in the background — those are separate steps you choose.

Commands

CommandWhat it does
warden setupGuided setup: find Hermes profiles and choose watched folders
warden tuiFull-screen terminal control centre
warden scanScan the approved folders once
warden statusMonitoring health and coverage
warden findingsOpen findings with their evidence
warden eventsRecent changes
warden monitorKeep scanning in the foreground (--once for one cycle)
warden dashboardStart the local web dashboard (--port to choose a port)
warden dashboard-credentialsSet or reset the dashboard login
warden service install | start | status | stop | uninstallRun the monitor as a background service
warden updatesCheck for OS updates without installing anything

setup, tui and dashboard-credentials need an interactive terminal. custodian still works as an alias for warden.

Web dashboard

warden dashboard serves a read-only view of findings and changes on 127.0.0.1 only. You sign in with a username and password set during setup, or with warden dashboard-credentials (12 characters minimum, entered at a hidden prompt).

The password is stored only as a salted scrypt hash. Sessions expire, sign-in attempts are rate-limited, and there is no MFA. It's built for use on the same machine; to reach it from elsewhere, use SSH port forwarding.

Background monitoring

warden service install --enable   # install and enable at login
warden service start              # start it now

This uses a systemd user service on Linux, a LaunchAgent on macOS and a per-user Task Scheduler task on Windows. Installing doesn't start it, and nothing is installed unless you run these commands. User services start when you log in; starting before login isn't guaranteed.

Hermes profiles and where data is stored

Warden keeps its settings, findings and history in a state folder:

SituationLocation
HERMES_HOME is set (including inside Hermes)$HERMES_HOME/plugin-data/hermes-custodian/
Linux$XDG_STATE_HOME/hermes-custodian (default ~/.local/state/hermes-custodian)
macOS~/Library/Application Support/hermes-custodian
Windows%LOCALAPPDATA%\hermes-custodian

If you use the standalone install alongside the plugin for a named Hermes profile, set HERMES_HOME to that profile first so both share the same data. To pick a folder yourself, put --state-dir /some/path before the command.

The state folder must not be writable by other users. A group-writable parent folder (the default on Ubuntu and Raspberry Pi OS) is accepted only if you own it and nobody else is in its group. Otherwise, run chmod g-w on the parent or choose a private folder with --state-dir.

OS updates

warden updates only reports what's available. It reads the APT cache on Linux, runs softwareupdate -l on macOS and queries Windows Update on Windows.

On Debian and Ubuntu there are also commands to preview and apply a security-updates-only unattended-upgrades policy:

warden updates security-plan --enable    # preview only, writes nothing
warden updates security-apply --plan-id <PLAN_ID> --enable

security-apply runs only as real root, from a root-owned installation, and asks you to type a confirmation phrase. It never reboots the machine, and it can't be triggered by the agent or the dashboard.

What it checks, and what it doesn't

  • Content fingerprints only for .py and .md files. Other files get metadata checks only (permissions, owner, size, modified time).
  • Sensitive files such as .env files, keys, OAuth stores and browser data are checked by permissions only. Their contents are never read, hashed or shown to the agent.
  • Private Hermes areas (memories, sessions, chat history) are never listed or read.
  • Symlinks and special files are never followed. Hitting a scan limit shows up as incomplete coverage.
  • Permission findings come from mode bits, so they don't account for ACLs, group membership or parent folder access. Each finding says this.
  • A changed file is not proof of malware.
  • Not a sandbox, antivirus or EDR. Anything running as your user could stop Warden or rewrite its data.
  • The dashboard cookie isn't tied to a port, so other local web servers in the same browser could receive it. Treat other local users as trusted.

Privacy

  • Nothing is scanned or started when the plugin loads. Scans happen only when you or your agent ask, or when you start the monitor.
  • Stored data contains paths, fingerprints, findings and change history — never credential contents.
  • There is no telemetry, and monitoring never calls an AI model.
  • System tools (systemctl, APT, launchctl, schtasks and so on) are run with fixed arguments, timeouts and a minimal environment. API keys, proxy settings and PATH/PYTHONPATH overrides are not passed on.

Development

.venv/bin/pip install -e '.[test]'
.venv/bin/python -m pytest -q

CI runs the tests on Linux, macOS and Windows with Python 3.11–3.14.

The plugin and package are still named hermes-custodian, the Python package is custodian, and the state folder and services keep those names so existing installs don't need migrating.

Status

Release candidate (0.1.1). The Hermes plugin catalog still lists 0.1.0.

README from the reviewed commit ec523a2; it updates when the author re-pins.

Developer Mode

Explore built-in Hermes toolsets and actions.

HermesAgent

Developer?

Create a Hermes extension for Desktop or agent workflows.

Developer Section