- 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
61 lines
3.5 KiB
Markdown
61 lines
3.5 KiB
Markdown
# 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:
|
|
|
|
```bash
|
|
git clone https://git.xlion.tw/xlionjuan/kuri-tool-guard.git \
|
|
~/.hermes/plugins/kuri-tool-guard
|
|
```
|
|
|
|
## Enable
|
|
|
|
```bash
|
|
hermes plugins enable kuri-tool-guard
|
|
```
|
|
|
|
Takes effect after a gateway restart (`/restart` or restart the Hermes gateway service).
|
|
|
|
## Using in other profiles
|
|
|
|
```bash
|
|
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
|
|
|
|
```bash
|
|
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.
|