kuri-tool-guard/__init__.py

110 lines
4.9 KiB
Python

"""kuri-tool-guard — consolidated pre_tool_call guard plugin.
Blocks the following categories of policy-violating tool calls:
1. **Home root search** — ``search_files`` / ``search`` targeting the
effective user's Unix home root (via ``pwd.getpwuid(os.geteuid())``).
2. **Terminal file writes** — direct ``cat`` (stdout to terminal), echo >,
printf >, heredoc, shell redirect, tee, ``sed -i``, ``perl -pi``.
Pipeline uses of ``cat`` (e.g. ``cat file | head``) are allowed;
``cat`` whose stdout goes to a real file
or to the terminal is blocked.
3. **Write-file on existing file** — ``write_file`` with a path that already
exists (use ``patch`` instead).
4. **Patch on memory files** — ``patch`` targeting a path ending with
``memories/MEMORY.md`` or ``memories/USER.md`` (use the ``memory`` tool
instead). 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(action='poll')** — blocks on the 3rd consecutive poll
after no other intervening tool call; resets on any non-poll tool.
7. **cron/jobs.json lockdown** — blocks ``write_file`` and ``patch`` on
``cron/jobs.json``; use ``cronjob create/update`` instead.
Read access (``read_file``, terminal, git) allowed.
8. **Terminal home-root operand** — blocks any shell command that uses
the effective user's protected home root as a filesystem operand,
regardless of the tool being invoked. Also blocks ``locate`` /
``plocate`` / ``mlocate`` (system-wide index, cannot scope).
9. **execute_code home-root** — per-call AST analysis; blocks only when
a traversal call (``os.walk``, ``glob.glob``, ``Path.rglob``,
``subprocess`` / ``os.system``) passes a protected home root as its
own argument. Unrelated home-root references elsewhere are ignored.
Dynamic path arguments that cannot be statically resolved are 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``. Use ``git ls-files``, ``-maxdepth``,
``-print -quit``, or ``| head`` for bounded alternatives.
11. **Skill directory lockdown** — blocks ``patch`` and ``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.
This is a hard block — the tool never executes. There is no opt-out.
"""
from __future__ import annotations
import logging
from typing import Any
# Detects whether we are loaded as a package (relative imports work).
# Hermes plugin loader sets __spec__.submodule_search_locations to the
# plugin directory; direct `python __init__.py` does not.
_IS_PACKAGE = bool(getattr(__spec__, "submodule_search_locations", None))
logger = logging.getLogger(__name__)
if _IS_PACKAGE:
from . import _guards, _state
def _on_pre_tool_call( # noqa: PLR0911,PLR0912
tool_name: str = "",
args: Any = None,
session_id: str = "",
**_: Any,
) -> dict[str, str] | None:
if isinstance(args, dict):
poll_block = _guards._guard_process_poll(tool_name, args, session_id)
if poll_block is not None:
return poll_block
cron_block = _guards._guard_cron_jobs_json(tool_name, args)
if cron_block is not None:
return cron_block
if tool_name not in _state._GUARDED_TOOLS or not isinstance(args, dict):
return None
if tool_name in _state._SEARCH_TOOLS:
return _guards._guard_home_root(args)
if tool_name == "terminal":
block = _guards._guard_terminal(args)
if block:
return block
return _guards._guard_terminal_home_root(args)
if tool_name == "write_file":
block = _guards._guard_skill_dir(tool_name, args)
if block:
return block
return _guards._guard_write_file(args)
if tool_name == "patch":
block = _guards._guard_patch_memory(args)
if block:
return block
return _guards._guard_skill_dir(tool_name, args)
if tool_name in _guards._GITHUB_WEB_TOOLS:
return _guards._guard_github_web(args)
if tool_name == "execute_code":
return _guards._guard_execute_code(args)
return None
__all__ = [
"_on_pre_tool_call",
"register",
]
def register(ctx) -> None:
ctx.register_hook("pre_tool_call", _on_pre_tool_call)
logger.info("kuri-tool-guard registered — %d guarded tools", len(_state._GUARDED_TOOLS))