No description
- Python 99.5%
- Just 0.5%
| Filename | Latest commit message | Latest commit date |
|---|---|---|
| tests | ||
| .gitignore | ||
| .vulture_whitelist.py | ||
| __init__.py | ||
| _guards.py | ||
| _parser.py | ||
| _predicates.py | ||
| _state.py | ||
| AGENTS.md | ||
| justfile | ||
| plugin.yaml | ||
| pyproject.toml | ||
| README.md | ||
| uv.lock | ||
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
- Home root search —
search_files/searchtargeting the effective user's Unix home root (viapwd.getpwuid(os.geteuid()), not hardcoded) - Terminal file patterns — direct
cat(stdout to terminal),echo >,printf >, heredoc,tee, bare redirect patterns,sed -i, andperl -pi. Pipeline uses ofcat(e.g.cat file | head) are allowed. - Write-file on existing file —
write_fileon a path that already exists - Patch on memory files —
patchtargeting a path ending withmemories/MEMORY.mdormemories/USER.md. PlainMEMORY.md/USER.mdin other directories is allowed. - GitHub / raw.githubusercontent.com web access —
web_extract/browser_navigatetargetinggithub.comorraw.githubusercontent.com; useghCLI orcurlinstead - 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 - cron/jobs.json lockdown —
write_file/patchoncron/jobs.jsonblocked; usecronjob create/updateinstead. Read access allowed. - 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 blockslocate/plocate/mlocate. Subpaths (e.g.~/.hermes) are allowed. - 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. - Bounded-output terminal — blocks commands likely to produce unbounded output:
find <dir> -type fwithout-maxdepthor-print -quit;rg --files --hidden --no-ignore;fd --hidden --no-ignore.find | headis allowed (head limits output).find | sort | headis blocked (sort consumes full output first).
All guards return hard blocks — the tool never executes.
How it works
- Single
pre_tool_callhook dispatches bytool_nameThe terminal guard uses 9 predicates: 8 file-write predicates (Guard 2) + 1 bounded-output predicate (Guard 10). /dev/nullredirects 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.