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

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.