91 lines
6.3 KiB
Markdown
91 lines
6.3 KiB
Markdown
# 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
|
|
|
|
```bash
|
|
just verify # full pipeline: lint → format-check → bandit → vulture → ty → pytest
|
|
just test # pytest only (fastest smoke test)
|
|
```
|
|
|
|
### Quick smoke test (minimal Python environment)
|
|
|
|
```bash
|
|
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 verify` exit status.
|
|
|
|
## 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 any operand (e.g. `echo /home/alice`, `stat /home/alice`, `find /home/alice`). Subpaths (e.g. `~/.hermes`) are allowed. Also blocks `locate`/`plocate`/`mlocate`.
|
|
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).
|
|
11. **Skill directory lockdown** — `patch` / `write_file` targeting any Hermes skill root (`$HERMES_HOME/skills` or `<home>/.hermes/skills`, including `profiles/*/skills`); use `skill_manage` instead. Terminal writes are not blocked.
|
|
|
|
All guards return hard blocks — the tool never executes.
|
|
|
|
## How it works
|
|
|
|
- Single `pre_tool_call` hook dispatches by `tool_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/null` redirects 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
|
|
|
|
1. Add a `_guard_*` function returning `Optional[dict[str, str]]`
|
|
2. Wire it in `_on_pre_tool_call` dispatcher
|
|
3. Add tests in `tests/` under the corresponding test file (e.g. `test_home_policy.py`, `test_terminal_guards.py`)
|
|
4. Run `just verify` before 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` |
|