atbash-hermes-plugin 0.1.0__tar.gz

atbash_hermes_plugin-0.1.0/LICENSE

@@ -0,0 +1,31 @@
+Atbash CLI -- Proprietary Software License
+
+Copyright (c) 2026 Atbash. All rights reserved.
+
+The full license is available at https://atbash.ai/license
+
+Redistribution and use in source and binary forms, with or without modification,
+are permitted provided that the following conditions are met:
+
+Redistributions of source code must retain the above copyright notice, this list
+of conditions and the following disclaimer.
+
+Redistributions in binary form must reproduce the above copyright notice, this
+list of conditions and the following disclaimer in the documentation and/or other
+materials provided with the distribution.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
+ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
+CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY,
+OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING
+IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY
+OF SUCH DAMAGE.
+
+The views and conclusions contained in the software and documentation are those
+of the authors and should not be interpreted as representing official policies,
+either expressed or implied, of Atbash.

atbash_hermes_plugin-0.1.0/PKG-INFO

@@ -0,0 +1,65 @@
+Metadata-Version: 2.4
+Name: atbash-hermes-plugin
+Version: 0.1.0
+Summary: Atbash safety plugin for Hermes Agent
+Author: atbash
+License-Expression: LicenseRef-Atbash-Proprietary
+Project-URL: Homepage, https://github.com/Atbash-Ai/atbash-hermes-plugin
+Project-URL: Repository, https://github.com/Atbash-Ai/atbash-hermes-plugin
+Keywords: atbash,hermes,hermes-agent,agent-safety,ai-safety,tool-guard,judge,policy
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: atbash-sdk==0.1.3
+Dynamic: license-file
+
+# atbash-hermes-plugin
+
+Atbash guardrail plugin for Hermes Agent using the official Python SDK (`atbash-sdk`).
+
+## What it does
+
+- Intercepts every Hermes tool call in `pre_tool_call`
+- Sends a verdict request to Atbash before the tool executes
+- Blocks tool execution when verdict is denied
+
+## Install
+
+1. Clone/copy this folder into your Hermes plugins directory.
+2. Install dependencies:
+
+```bash
+python3 -m pip install -r requirements.txt
+```
+
+3. Configure env vars:
+
+```bash
+export ATBASH_AGENT_PRIVKEY='{"pubkey":"...","privkey":"..."}'
+# or
+export ATBASH_KEY_PATH="$HOME/.config/atbash/guard-client-key"
+
+# optional
+export ATBASH_ENDPOINT="https://api.atbash.io"
+export ATBASH_ENFORCE_DECISION="true"
+export ATBASH_DEBUG="false"
+export ATBASH_TOOL_MAP_PATH="$HOME/.config/atbash/hermes-tool-map.json"
+```
+
+4. Enable plugin in Hermes config.
+
+## Tool classification
+
+The plugin records previously unseen Hermes tool names in
+`~/.config/atbash/hermes-tool-map.json`. The learned mappings are loaded when
+each Hermes session starts, so tool classifications persist across restarts.
+Set `ATBASH_TOOL_MAP_PATH` to override the location.
+
+## Behavior
+
+- `ALLOW` => tool proceeds
+- `HOLD` => tool is paused and must be reviewed before retrying
+- `BLOCK`/`DENY`/`REJECT` => tool is blocked with a user-facing message
+- Errors talking to Atbash:
+  - if `ATBASH_ENFORCE_DECISION=true` (default): block fail-closed
+  - if `false`: allow fail-open

atbash_hermes_plugin-0.1.0/README.md

@@ -0,0 +1,50 @@
+# atbash-hermes-plugin
+
+Atbash guardrail plugin for Hermes Agent using the official Python SDK (`atbash-sdk`).
+
+## What it does
+
+- Intercepts every Hermes tool call in `pre_tool_call`
+- Sends a verdict request to Atbash before the tool executes
+- Blocks tool execution when verdict is denied
+
+## Install
+
+1. Clone/copy this folder into your Hermes plugins directory.
+2. Install dependencies:
+
+```bash
+python3 -m pip install -r requirements.txt
+```
+
+3. Configure env vars:
+
+```bash
+export ATBASH_AGENT_PRIVKEY='{"pubkey":"...","privkey":"..."}'
+# or
+export ATBASH_KEY_PATH="$HOME/.config/atbash/guard-client-key"
+
+# optional
+export ATBASH_ENDPOINT="https://api.atbash.io"
+export ATBASH_ENFORCE_DECISION="true"
+export ATBASH_DEBUG="false"
+export ATBASH_TOOL_MAP_PATH="$HOME/.config/atbash/hermes-tool-map.json"
+```
+
+4. Enable plugin in Hermes config.
+
+## Tool classification
+
+The plugin records previously unseen Hermes tool names in
+`~/.config/atbash/hermes-tool-map.json`. The learned mappings are loaded when
+each Hermes session starts, so tool classifications persist across restarts.
+Set `ATBASH_TOOL_MAP_PATH` to override the location.
+
+## Behavior
+
+- `ALLOW` => tool proceeds
+- `HOLD` => tool is paused and must be reviewed before retrying
+- `BLOCK`/`DENY`/`REJECT` => tool is blocked with a user-facing message
+- Errors talking to Atbash:
+  - if `ATBASH_ENFORCE_DECISION=true` (default): block fail-closed
+  - if `false`: allow fail-open

atbash_hermes_plugin-0.1.0/atbash_hermes_plugin/__init__.py

@@ -0,0 +1,274 @@
+from __future__ import annotations
+
+import json
+import logging
+import os
+from pathlib import Path
+from typing import Any, Dict, Optional
+
+logger = logging.getLogger("atbash-hermes-plugin")
+
+DEFAULT_TOOL_CLASS_MAP = {
+    "browser_click": "browser_interaction",
+    "browser_navigate": "network",
+    "browser_type": "browser_interaction",
+    "read_file": "filesystem_read",
+    "skill_view": "skill_read",
+    "terminal": "command_execution",
+    "write_file": "filesystem_write",
+}
+
+
+def _default_tool_map_path() -> Path:
+    return Path("~/.config/atbash/hermes-tool-map.json").expanduser()
+
+
+def _load_tool_map(path: Path) -> Dict[str, str]:
+    try:
+        raw = json.loads(path.read_text(encoding="utf-8"))
+    except FileNotFoundError:
+        return {}
+    except Exception as e:
+        logger.warning("Could not read Atbash Hermes tool map path=%s err=%s", path, e)
+        return {}
+
+    if not isinstance(raw, dict):
+        logger.warning("Ignoring invalid Atbash Hermes tool map path=%s", path)
+        return {}
+    return {
+        str(tool_name): str(action_class)
+        for tool_name, action_class in raw.items()
+        if isinstance(tool_name, str) and isinstance(action_class, str)
+    }
+
+
+def _save_tool_map(path: Path, tool_map: Dict[str, str]) -> None:
+    try:
+        path.parent.mkdir(parents=True, exist_ok=True)
+        temp_path = path.with_suffix(f"{path.suffix}.tmp")
+        temp_path.write_text(
+            json.dumps(dict(sorted(tool_map.items())), indent=2) + "\n",
+            encoding="utf-8",
+        )
+        temp_path.replace(path)
+    except Exception as e:
+        logger.warning("Could not persist Atbash Hermes tool map path=%s err=%s", path, e)
+
+
+
+
+def _extract_command(tool_name: str, tool_args: Dict[str, Any]) -> str:
+    if not isinstance(tool_args, dict):
+        return ""
+    for key in ("command", "cmd", "shell_command", "bash_command", "zsh_command", "script"):
+        v = tool_args.get(key)
+        if isinstance(v, str) and v.strip():
+            return v.strip()
+    # Hermes terminal/shell tools sometimes nest payloads
+    for key in ("input", "args", "payload"):
+        v = tool_args.get(key)
+        if isinstance(v, dict):
+            for k in ("command", "cmd"):
+                vv = v.get(k)
+                if isinstance(vv, str) and vv.strip():
+                    return vv.strip()
+    return ""
+
+def _infer_action_class(tool_name: str) -> str:
+    t = (tool_name or "").lower()
+    if any(k in t for k in ("write", "edit", "delete", "create", "mv", "cp")):
+        return "filesystem_write"
+    if any(k in t for k in ("read", "list", "ls", "glob", "find", "search")):
+        return "filesystem_read"
+    if any(k in t for k in ("shell", "terminal", "exec", "command", "bash", "zsh")):
+        return "command_execution"
+    if any(k in t for k in ("http", "web", "fetch", "request", "browser", "mcp")):
+        return "network"
+    if any(k in t for k in ("image", "video", "audio")):
+        return "media_generation"
+    return "unknown"
+
+
+def _as_bool(value: Optional[str], default: bool) -> bool:
+    if value is None:
+        return default
+    return value.strip().lower() in {"1", "true", "yes", "on"}
+
+
+def _normalize_verdict(raw: Any) -> str:
+    # atbash-sdk JudgeResult object path
+    verdict_attr = getattr(raw, "verdict", None)
+    if verdict_attr is None:
+        verdict_attr = getattr(raw, "decision", None)
+    if isinstance(verdict_attr, str) and verdict_attr.strip():
+        return verdict_attr.strip().upper()
+
+    if raw is None:
+        return "ERROR"
+    if isinstance(raw, str):
+        return raw.strip().upper()
+    if isinstance(raw, dict):
+        for key in ("verdict", "decision", "status", "result"):
+            v = raw.get(key)
+            if isinstance(v, str) and v.strip():
+                return v.strip().upper()
+    return str(raw).strip().upper()
+
+
+def _extract_reason(raw: Any) -> str:
+    reason_attr = getattr(raw, "reason", None)
+    if reason_attr is None:
+        reason_attr = getattr(raw, "message", None)
+    if isinstance(reason_attr, str) and reason_attr.strip():
+        return reason_attr
+
+    if isinstance(raw, str):
+        return raw
+    if isinstance(raw, dict):
+        for key in ("reason", "message", "explanation", "details"):
+            v = raw.get(key)
+            if isinstance(v, str) and v.strip():
+                return v
+        try:
+            return json.dumps(raw, ensure_ascii=True)
+        except Exception:
+            return str(raw)
+    return str(raw)
+
+
+class AtbashHermesGuard:
+    def __init__(self) -> None:
+        self.debug = _as_bool(os.getenv("ATBASH_DEBUG"), False)
+        self.fail_closed = _as_bool(os.getenv("ATBASH_ENFORCE_DECISION"), True)
+        self.endpoint = os.getenv("ATBASH_ENDPOINT")
+        self.key_path = os.getenv("ATBASH_KEY_PATH")
+        self.privkey = os.getenv("ATBASH_AGENT_PRIVKEY")
+        self.provider = os.getenv("HERMES_PROVIDER")
+        self.model = os.getenv("HERMES_MODEL")
+        self.tool_map_path = Path(
+            os.getenv("ATBASH_TOOL_MAP_PATH", str(_default_tool_map_path()))
+        ).expanduser()
+        self.tool_map = {**DEFAULT_TOOL_CLASS_MAP, **_load_tool_map(self.tool_map_path)}
+
+        self.client = self._build_client()
+
+    def _action_class(self, tool_name: str) -> str:
+        mapped = self.tool_map.get(tool_name)
+        if mapped:
+            return mapped
+
+        action_class = _infer_action_class(tool_name)
+        self.tool_map[tool_name or "unknown"] = action_class
+        _save_tool_map(self.tool_map_path, self.tool_map)
+        logger.info(
+            "Atbash learned tool mapping tool=%s action_class=%s path=%s",
+            tool_name or "unknown",
+            action_class,
+            self.tool_map_path,
+        )
+        return action_class
+
+    def _build_client(self):
+        try:
+            from atbash import Atbash, ToolCallInput  # type: ignore
+        except Exception as e:
+            try:
+                from atbash import Atbash  # type: ignore
+                from atbash.types import ToolCallInput  # type: ignore
+            except Exception:
+                raise RuntimeError("atbash-sdk is required. Install with: pip install atbash-sdk==0.1.3") from e
+
+        self.ToolCallInput = ToolCallInput
+        judge_cfg = {"endpoint": self.endpoint} if self.endpoint else None
+
+        # Prefer explicit key material if provided.
+        if self.privkey:
+            try:
+                return Atbash(self.privkey, endpoint=self.endpoint or "https://atbash.ai")
+            except TypeError:
+                return Atbash(self.privkey)
+
+        # Use SDK-native config loader for key file/env/config.
+        return Atbash.from_config(
+            key_path=self.key_path,
+            judge=judge_cfg,
+            fail_closed=self.fail_closed,
+        )
+
+    def _judge(self, tool_name: str, tool_args: Dict[str, Any], session_id: str = "", task_id: str = "", tool_call_id: str = "") -> Any:
+        action_class = self._action_class(tool_name)
+        command = _extract_command(tool_name, tool_args or {})
+
+        # Mirror OpenClaw plugin semantics: pass toolName + full args.
+        # Keep context concise but informative; args already carry command/body.
+        context = json.dumps(
+            {
+                "tool_name": tool_name,
+                "action_class": action_class,
+                "session_id": session_id or None,
+                "task_id": task_id or None,
+                "tool_call_id": tool_call_id or None,
+                "command": command or None,
+                "cwd": os.getcwd(),
+            },
+            ensure_ascii=True,
+        )
+
+        # Make action payload explicit so Atbash UI shows tool name, not only raw args.
+        action_payload = {
+            "tool_name": tool_name or "unknown",
+            "args": tool_args or {},
+        }
+
+        return self.client.audit_tool_call(
+            self.ToolCallInput(
+                tool_name=tool_name or "unknown",
+                args=action_payload,
+                context=context,
+            )
+        )
+
+    def pre_tool_call(self, *, tool_name: str = "", args: Dict[str, Any] | None = None, task_id: str = "", session_id: str = "", tool_call_id: str = ""):
+        if self.debug:
+            logger.info("Atbash pre_tool_call enter tool=%s session_id=%s task_id=%s tool_call_id=%s", tool_name, session_id, task_id, tool_call_id)
+        try:
+            verdict_raw = self._judge(
+                tool_name=tool_name,
+                tool_args=args or {},
+                session_id=session_id,
+                task_id=task_id,
+                tool_call_id=tool_call_id,
+            )
+            verdict = _normalize_verdict(verdict_raw)
+            reason = _extract_reason(verdict_raw)
+
+            if self.debug:
+                logger.info("Atbash verdict tool=%s verdict=%s reason=%s", tool_name, verdict, reason)
+
+            if verdict == "HOLD":
+                return {
+                    "action": "block",
+                    "message": f"Held by Atbash for operator review: {reason}",
+                }
+
+            if verdict in {"BLOCK", "DENY", "REJECT", "DISALLOW"}:
+                return {
+                    "action": "block",
+                    "message": f"Blocked by Atbash policy: {reason}",
+                }
+
+            return None
+        except Exception as e:
+            logger.warning("Atbash guard error tool=%s err=%s", tool_name, e)
+            if self.fail_closed:
+                return {
+                    "action": "block",
+                    "message": f"Blocked (Atbash unavailable): {e}",
+                }
+            return None
+
+
+def register(ctx):
+    guard = AtbashHermesGuard()
+    ctx.register_hook("pre_tool_call", guard.pre_tool_call)
+    logger.info("[atbash-hermes-plugin] registered pre_tool_call hook")

atbash_hermes_plugin-0.1.0/atbash_hermes_plugin.egg-info/PKG-INFO

@@ -0,0 +1,65 @@
+Metadata-Version: 2.4
+Name: atbash-hermes-plugin
+Version: 0.1.0
+Summary: Atbash safety plugin for Hermes Agent
+Author: atbash
+License-Expression: LicenseRef-Atbash-Proprietary
+Project-URL: Homepage, https://github.com/Atbash-Ai/atbash-hermes-plugin
+Project-URL: Repository, https://github.com/Atbash-Ai/atbash-hermes-plugin
+Keywords: atbash,hermes,hermes-agent,agent-safety,ai-safety,tool-guard,judge,policy
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: atbash-sdk==0.1.3
+Dynamic: license-file
+
+# atbash-hermes-plugin
+
+Atbash guardrail plugin for Hermes Agent using the official Python SDK (`atbash-sdk`).
+
+## What it does
+
+- Intercepts every Hermes tool call in `pre_tool_call`
+- Sends a verdict request to Atbash before the tool executes
+- Blocks tool execution when verdict is denied
+
+## Install
+
+1. Clone/copy this folder into your Hermes plugins directory.
+2. Install dependencies:
+
+```bash
+python3 -m pip install -r requirements.txt
+```
+
+3. Configure env vars:
+
+```bash
+export ATBASH_AGENT_PRIVKEY='{"pubkey":"...","privkey":"..."}'
+# or
+export ATBASH_KEY_PATH="$HOME/.config/atbash/guard-client-key"
+
+# optional
+export ATBASH_ENDPOINT="https://api.atbash.io"
+export ATBASH_ENFORCE_DECISION="true"
+export ATBASH_DEBUG="false"
+export ATBASH_TOOL_MAP_PATH="$HOME/.config/atbash/hermes-tool-map.json"
+```
+
+4. Enable plugin in Hermes config.
+
+## Tool classification
+
+The plugin records previously unseen Hermes tool names in
+`~/.config/atbash/hermes-tool-map.json`. The learned mappings are loaded when
+each Hermes session starts, so tool classifications persist across restarts.
+Set `ATBASH_TOOL_MAP_PATH` to override the location.
+
+## Behavior
+
+- `ALLOW` => tool proceeds
+- `HOLD` => tool is paused and must be reviewed before retrying
+- `BLOCK`/`DENY`/`REJECT` => tool is blocked with a user-facing message
+- Errors talking to Atbash:
+  - if `ATBASH_ENFORCE_DECISION=true` (default): block fail-closed
+  - if `false`: allow fail-open

atbash_hermes_plugin-0.1.0/atbash_hermes_plugin.egg-info/SOURCES.txt

@@ -0,0 +1,10 @@
+LICENSE
+README.md
+pyproject.toml
+atbash_hermes_plugin/__init__.py
+atbash_hermes_plugin.egg-info/PKG-INFO
+atbash_hermes_plugin.egg-info/SOURCES.txt
+atbash_hermes_plugin.egg-info/dependency_links.txt
+atbash_hermes_plugin.egg-info/entry_points.txt
+atbash_hermes_plugin.egg-info/requires.txt
+atbash_hermes_plugin.egg-info/top_level.txt

atbash_hermes_plugin-0.1.0/atbash_hermes_plugin.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

atbash_hermes_plugin-0.1.0/atbash_hermes_plugin.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[hermes_agent.plugins]
+atbash-hermes-plugin = atbash_hermes_plugin

atbash_hermes_plugin-0.1.0/atbash_hermes_plugin.egg-info/requires.txt

@@ -0,0 +1 @@
+atbash-sdk==0.1.3

atbash_hermes_plugin-0.1.0/atbash_hermes_plugin.egg-info/top_level.txt

@@ -0,0 +1 @@
+atbash_hermes_plugin

atbash_hermes_plugin-0.1.0/pyproject.toml

@@ -0,0 +1,38 @@
+[build-system]
+requires = ["setuptools>=69", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "atbash-hermes-plugin"
+version = "0.1.0"
+description = "Atbash safety plugin for Hermes Agent"
+readme = "README.md"
+requires-python = ">=3.10"
+authors = [
+  { name = "atbash" }
+]
+license = "LicenseRef-Atbash-Proprietary"
+license-files = ["LICENSE"]
+keywords = [
+  "atbash",
+  "hermes",
+  "hermes-agent",
+  "agent-safety",
+  "ai-safety",
+  "tool-guard",
+  "judge",
+  "policy"
+]
+dependencies = [
+  "atbash-sdk==0.1.3"
+]
+
+[project.urls]
+Homepage = "https://github.com/Atbash-Ai/atbash-hermes-plugin"
+Repository = "https://github.com/Atbash-Ai/atbash-hermes-plugin"
+
+[project.entry-points."hermes_agent.plugins"]
+atbash-hermes-plugin = "atbash_hermes_plugin"
+
+[tool.setuptools.packages.find]
+include = ["atbash_hermes_plugin*"]

atbash_hermes_plugin-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+