6.3 KiB
6.3 KiB
kuri-tool-guard
Consolidated pre_tool_call plugin with high-friction, good-faith policy guards. It is host-side policy rather than a complete hostile-model sandbox.
Author: Kuri
Verification
just verify # full pipeline: lint → format-check → bandit → vulture → ty → pytest
just test # pytest only (fastest smoke test)
Quick smoke test (minimal Python environment)
cd ~/.hermes/plugins/kuri-tool-guard
PYTHONPATH=. python3 -m pytest tests/ -v
For the full just verify pipeline, run uv sync --group dev once.
Completion gate
just verify is the mandatory completion gate for every code, test, fixture, or documentation change in this repository, whether or not a commit is requested.
A task is not complete unless just verify exits with status 0.
- Running individual verification commands does not replace
just verify. - Passing tests alone does not count as completion.
- Failures believed to be pre-existing still make the gate fail.
- Do not silently accept, suppress, baseline, or reclassify failures.
- If the gate fails, fix the failure within the authorized scope or report the exact blocker and leave the task marked incomplete.
- Changing lint configuration, adding broad ignores, adding
noqa, or changing verification policy only to make the gate pass requires explicit owner approval. - The final report must include the exact
just verifyexit status.
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 any operand (e.g.
echo /home/alice,stat /home/alice,find /home/alice). Subpaths (e.g.~/.hermes) are allowed. Also blockslocate/plocate/mlocate. - 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). - Skill directory lockdown —
patch/write_filetargeting any Hermes skill root ($HERMES_HOME/skillsor<home>/.hermes/skills, includingprofiles/*/skills); useskill_manageinstead. Terminal writes are not blocked.
All guards return hard blocks — the tool never executes.
How it works
- Single
pre_tool_callhook dispatches bytool_name - Terminal guard (Guard 2) uses 8 predicate functions in a registry (
_TERMINAL_PREDICATES) - Terminal home-root guard (Guard 8) uses operand-based token checking (no command-name denylist)
- execute_code guard (Guard 9) uses per-call AST analysis — each traversal call's own argument is evaluated in isolation
- Bounded-output guard (Guard 10) runs as a terminal predicate, independent of home-root policy
/dev/nullredirects excepted (discard, not a file write)- Poll state is cleaned lazily after 24 hours and holds at most 1,024 sessions
- Protected home roots determined via
pwd.getpwuid(os.geteuid())— no hardcoded usernames
Adding a New Guard
- Add a
_guard_*function returningOptional[dict[str, str]] - Wire it in
_on_pre_tool_calldispatcher - Add tests in
tests/under the corresponding test file (e.g.test_home_policy.py,test_terminal_guards.py) - Run
just verifybefore finalising
Testing
Tests are organised by guard category across multiple files:
| Test class | Guard(s) | File |
|---|---|---|
TestHomeRootGuard |
Guard 1 — home root (search tools) | tests/test_home_policy.py |
TestTerminalGuardPredicates |
Guard 2 — each terminal predicate in isolation | tests/test_terminal_predicates.py |
TestTerminalGuardCombined |
Guard 2 — _match_terminal_predicate orchestration |
tests/test_terminal_guards.py |
TestTerminalGuardMiddleware |
Guard 2 — _on_pre_tool_call hook interface for terminal |
tests/test_terminal_guards.py |
TestWriteFileGuard |
Guard 3 — write_file on existing files | tests/test_write_file.py |
TestPatchMemoryGuard |
Guard 4 — patch on memory files | tests/test_patch_memory.py |
TestGitHubWebGuard |
Guard 5 — GitHub.com web access | tests/test_github_web.py |
TestProcessPollGuard |
Guard 6 — consecutive poll state, TTL, and capacity | tests/test_process_poll.py |
TestCronJobsJsonGuard |
Guard 7 — cron/jobs.json lockdown | tests/test_cron_jobs.py |
TestTerminalHomeRootGuard |
Guard 8 — terminal home-root operand + locate | tests/test_terminal_home_root.py |
TestExecuteCodeGuard |
Guard 9 — execute_code per-call protection | tests/test_execute_code.py |
TestBoundedOutputPredicate |
Guard 10 — bounded-output terminal filter | tests/test_bounded_output.py |
TestPolicyFixtures |
All — policy fixture integration | tests/test_policy_integration.py |
TestManifestMetadata |
All — manifest and version consistency | tests/test_dispatcher.py |
TestDispatcher |
All — multi-guard orchestration | tests/test_dispatcher.py |