110 lines
4.9 KiB
Python
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))
|