kuri-tool-guard/README.md
XLion 22b0334b11
refactor: home-root guards with cross-account tests, injectable policy, bounded-output Guard 10
- Pure-function _build_protected_home_roots() with injected username/passwd_home
- Removed mutable-list cache; pwd.getpwuid called each invocation
- _resolve_tilde uses passwd home (not /var/home/xlion) for consistent ~ semantics
- _glob_pattern_starts_with_root: base-extract instead of startswith
- execute_code guard: per-call analysis, not global boolean combos
- Guard 10: bounded-output terminal (find -type f, rg --files, fd)
- 336 tests (cross-account pure builder + tilde + lookup failure)
- just verify exit 0
2026-07-30 22:46:35 +08:00

3.5 KiB

kuri-tool-guard

A Hermes plugin that applies high-friction, good-faith policy checks before tool calls execute. It consolidates ten guard categories into one pre_tool_call hook. It is host-side policy, not a complete sandbox against every shell or tool route.

Guards

  1. Home root search — search_files / search targeting the effective user's Unix home root (via pwd.getpwuid(os.geteuid()), not hardcoded)
  2. Terminal file patterns — direct cat (stdout to terminal), echo >, printf >, heredoc, tee, bare redirect patterns, sed -i, and perl -pi. Pipeline uses of cat (e.g. cat file | head) are allowed.
  3. Write-file on existing file — write_file on a path that already exists
  4. Patch on memory files — patch targeting a path ending with memories/MEMORY.md or memories/USER.md. Plain MEMORY.md / USER.md in other directories is allowed.
  5. GitHub / raw.githubusercontent.com web access — web_extract / browser_navigate targeting github.com or raw.githubusercontent.com; use gh CLI or curl instead
  6. Consecutive process polling — process(action="poll") is blocked on the third consecutive poll with no intervening tool call; any non-poll tool resets the count
  7. cron/jobs.json lockdown — write_file / patch on cron/jobs.json blocked; use cronjob create/update instead. Read access allowed.
  8. Terminal home-root operand — blocks any shell command that uses a protected home root as an operand (e.g. find ~, rg pattern ~, grep -R ~, fd ~, tree ~, du -sh ~, glob ~/*). Also blocks locate/plocate/mlocate. Subpaths (e.g. ~/.hermes) are allowed.
  9. execute_code home-root — per-call AST analysis on each traversal function (os.walk, glob.glob, Path.rglob, subprocess, os.system). Only blocks when the call's own path argument is a protected home root. Dynamic arguments that can't be statically resolved pass as a known limitation.
  10. Bounded-output terminal — blocks commands likely to produce unbounded output: find <dir> -type f without -maxdepth or -print -quit; rg --files --hidden --no-ignore; fd --hidden --no-ignore. find | head is allowed (head limits output). find | sort | head is blocked (sort consumes full output first).

All guards return hard blocks — the tool never executes.

How it works

  • Single pre_tool_call hook dispatches by tool_name The terminal guard uses 9 predicates: 8 file-write predicates (Guard 2) + 1 bounded-output predicate (Guard 10).
  • /dev/null redirects excepted (discard, not a file write)
  • Quoted > inside echo/printf strings correctly ignored
  • Poll state is cleaned lazily after 24 hours and holds at most 1,024 sessions; the least-recently-seen entry is evicted when full

Installation

Clone to the Hermes user plugins directory:

git clone https://git.xlion.tw/xlionjuan/kuri-tool-guard.git \
    ~/.hermes/plugins/kuri-tool-guard

Enable

hermes plugins enable kuri-tool-guard

Takes effect after a gateway restart (/restart or restart the Hermes gateway service).

Using in other profiles

mkdir -p ~/.hermes/profiles/<profile>/plugins
ln -s ../../../plugins/kuri-tool-guard \
    ~/.hermes/profiles/<profile>/plugins/kuri-tool-guard
hermes plugins --profile <profile> enable kuri-tool-guard

Verification

cd ~/.hermes/plugins/kuri-tool-guard
just verify

just verify runs ruff lint and format checks, Bandit, Vulture, ty, and pytest. Run uv sync --group dev once before the first full verification.