atbash-hermes-plugin 0.4.5.dev0__py3-none-any.whl → 0.4.5.dev2__py3-none-any.whl

atbash_hermes_plugin/__init__.py

@@ -4,6 +4,7 @@ import atexit
 import hashlib
 import json
 import logging
+import inspect
 import os
 import re
 import time
@@ -336,6 +337,134 @@ def _resolve_asset(token: str) -> str:
     return "other"
 
 
+_STATEMENT_SEP_RE = re.compile(r"[;&|<>$`\r\n]")
+
+def _flag_values(command: str, name: str) -> list:
+    return [
+        value.strip("'\"")
+        for value in re.findall(rf"--{re.escape(name)}[= ]+(\S+)", command)
+    ]
+
+def _numeric_amount(value: Optional[str]) -> Optional[str]:
+    """Return ``value`` only if it is a plain ASCII decimal, else ``None``.
+
+    ``[0-9]`` rather than ``\\d``: in Python ``\\d`` matches every Unicode
+    decimal digit, so ``--amount ١٢٣`` passed the check and was forwarded
+    verbatim into the un-redacted ``resolved`` block. Callers must treat a
+    ``None`` here as "unparsable", not as "no amount given" — see
+    ``_canonicalize_financial``.
+    """
+    if value is None or len(value) > 64:
+        return None
+    return value if re.fullmatch(r"(?:[0-9]+(?:\.[0-9]*)?|\.[0-9]+)", value) else None
+
+
+_TRUE_VALUES = {"1", "true", "yes", "on"}
+
+_FALSE_VALUES = {"0", "false", "no", "off"}
+
+def _enforcement_enabled(value: Optional[str]) -> bool:
+    """Parse ATBASH_ENFORCE_DECISION as opt-OUT, not opt-in.
+
+    This flag guards every fail-open branch in the guard, so it must take an
+    explicit, recognised falsey value to switch off. Read with the truthy
+    matching used for the other flags, an empty string — which is what
+    docker-compose passes for `ATBASH_ENFORCE_DECISION=${VAR}` when the host
+    variable is unset — or a typo like "y" or "strict" silently put the guard
+    in fail-open mode with nothing in the log to show for it.
+    """
+    if value is None:
+        return True
+    normalized = value.strip().lower()
+    if normalized in _FALSE_VALUES:
+        return False
+    if normalized and normalized not in _TRUE_VALUES:
+        logger.error(
+            "ATBASH_ENFORCE_DECISION=%r is not a recognized value; "
+            "keeping enforcement on (fail-closed)",
+            value,
+        )
+    return True
+
+
+def _strict_reading(
+    command: str,
+    recipient_allowlist: set,
+    may_hide_other_actions: bool,
+) -> Dict[str, Any]:
+    """The most conservative concrete facts that survive an ambiguous command.
+
+    Replacing every fact with "ambiguous" makes asset-specific policy ("never
+    lifts ETH or ATBASH rules") unreachable for any command carrying a
+    separator. So report every asset named, the largest amount named (or
+    "unparsable"), and whether *every* recipient named is allowlisted.
+
+    Every field describes only the text that was parsed. When the command can
+    expand or chain into statements this never saw, `may_hide_other_actions` is
+    True and none of these facts bound what actually runs — which is why they
+    are named "…_named" and why nothing here may be read as permission.
+    """
+    recipients = _flag_values(command, "to") + _flag_values(command, "recipient")
+    lowered_recipients = {r.lower() for r in recipients}
+    tokens = _flag_values(command, "token")
+    addresses = [
+        address
+        for address in _ERC20_RE.findall(command)
+        if address.lower() not in lowered_recipients
+    ]
+    assets = sorted({_resolve_asset(t) for t in tokens + addresses}) or ["ETH"]
+
+    raw_amounts = _flag_values(command, "amount") + _flag_values(command, "max-usd")
+    parsed = [_numeric_amount(v) for v in raw_amounts]
+    if any(p is None for p in parsed):
+        max_amount: Optional[str] = "unparsable"
+    elif parsed:
+        max_amount = max(parsed, key=lambda v: float(v))
+    else:
+        max_amount = None
+
+    return {
+        "assets_named": assets,
+        "max_amount_named": max_amount,
+        "recipients_named": len(recipients),
+        "all_named_recipients_allowlisted": bool(recipients)
+        and all(r.lower() in recipient_allowlist for r in recipients),
+        "may_hide_other_actions": may_hide_other_actions,
+    }
+
+
+def _assert_sdk_capabilities(
+    sdk: Any,
+    atbash_class: Any,
+    tool_call_input_class: Any,
+) -> None:
+    guard_api_version = getattr(sdk, "GUARD_API_VERSION", 0)
+    if not isinstance(guard_api_version, int) or guard_api_version < 1:
+        raise RuntimeError(
+            "atbash-sdk does not expose hardened guard API version 1; "
+            "install atbash-sdk==0.2.0"
+        )
+    if not callable(getattr(atbash_class, "from_config", None)):
+        raise RuntimeError("atbash-sdk is missing Atbash.from_config")
+    if not callable(getattr(atbash_class, "audit_tool_call", None)):
+        raise RuntimeError("atbash-sdk is missing Atbash.audit_tool_call")
+    try:
+        from_config_parameters = inspect.signature(
+            atbash_class.from_config
+        ).parameters
+        parameters = inspect.signature(tool_call_input_class).parameters
+    except (TypeError, ValueError) as error:
+        raise RuntimeError("cannot inspect atbash-sdk guard APIs") from error
+    for required_parameter in ("judge", "org_name", "fail_closed"):
+        if required_parameter not in from_config_parameters:
+            raise RuntimeError(
+                "atbash-sdk Atbash.from_config is missing "
+                f"{required_parameter} support"
+            )
+    if "resolved" not in parameters:
+        raise RuntimeError("atbash-sdk ToolCallInput is missing resolved support")
+
+
 def _canonicalize_financial(command: str, recipient_allowlist: set) -> Optional[Dict[str, Any]]:
     if not command:
         return None
@@ -345,18 +474,90 @@ def _canonicalize_financial(command: str, recipient_allowlist: set) -> Optional[
         return None
 
     def _flag(name: str) -> Optional[str]:
-        m = re.search(rf"--{name}[= ]+(\S+)", command)
-        return m.group(1).strip("'\"") if m else None
+        values = _flag_values(command, name)
+        return values[0] if values else None
+
+    op = (
+        "swap" if re.search(r"\bswap\b", command, re.IGNORECASE)
+        else "approve" if re.search(r"\b(approve|erc20)\b", command, re.IGNORECASE)
+        else "transfer"
+    )
+
+    # The judge rules on this block rather than on the raw command — the SDK
+    # redacts every 0x address out of args before it is sent — so reading only
+    # the first occurrence of a flag lets a prompt-injected command assert an
+    # allowlisted 1-unit transfer while what actually executes is a second one.
+    # CLI parsers are last-flag-wins and a shell runs every `;`-separated
+    # statement. When the text can mean more than one thing, say so instead of
+    # picking a reading and asserting it.
+    repeated_recipient = len(_flag_values(command, "to")) + len(
+        _flag_values(command, "recipient")
+    ) > 1
+    repeated_flag = any(
+        len(_flag_values(command, name)) > 1
+        for name in ("token", "amount", "max-usd")
+    )
+    multi_statement = bool(_STATEMENT_SEP_RE.search(command))
+
+    # "absent" and "present but unparsable" must not collapse to the same
+    # signal. `--amount 1e9` parses as no plain decimal, and reporting it as
+    # amount=None next to recipient_status="allowlisted" hands the judge
+    # "allowlisted recipient, no amount stated" for a command that names a very
+    # large one — which is exactly what an "allow allowlisted USDT under N"
+    # policy would let through.
+    raw_amount = _flag("amount")
+    raw_max_usd = _flag("max-usd")
+    amount = _numeric_amount(raw_amount)
+    max_usd = _numeric_amount(raw_max_usd)
+    amount_unparsed = (raw_amount is not None and amount is None) or (
+        raw_max_usd is not None and max_usd is None
+    )
+
+    if repeated_recipient or repeated_flag or multi_statement or amount_unparsed:
+        return {
+            "operation": op,
+            "asset": "ambiguous",
+            "amount": None,
+            "max_usd": None,
+            "recipient_status": "ambiguous",
+            "ambiguous": True,
+            "amount_unparsed": amount_unparsed,
+            "ambiguous_reason": (
+                "multiple statements, redirection or substitution"
+                if multi_statement
+                else "repeated flag"
+                if (repeated_recipient or repeated_flag)
+                else "amount is not a plain decimal number"
+            ),
+            # Conservative facts, so an asset-specific rule is still reachable.
+            # Never grant on these: recipient_status above stays "ambiguous".
+            "strict_reading": _strict_reading(
+                command, recipient_allowlist, multi_statement
+            ),
+            "allowlist_scope": "USDT transfers/approvals only; never lifts ETH or ATBASH rules",
+            "note": (
+                "canonicalization withheld: the command carries more than one "
+                "transfer or flag value, an unreadable amount, or text that a "
+                "shell would expand, so no asset/amount/recipient claim here "
+                "can be trusted"
+            ),
+        }
 
+    to = _flag("to") or _flag("recipient")
     token = _flag("token")
     if not token:
-        m = _ERC20_RE.search(command)
-        if m:
-            token = m.group(1)
+        # Only an address that is not the recipient can be the token contract.
+        # Taking the first 0x in the command picked up the RECIPIENT of a
+        # native send, resolved it to "other", and made the stricter ETH rule
+        # unreachable for every command that names an address.
+        candidates = [
+            address
+            for address in _ERC20_RE.findall(command)
+            if not to or address.lower() != to.lower()
+        ]
+        if candidates:
+            token = candidates[0]
 
-    to = _flag("to") or _flag("recipient")
-    amount = _flag("amount")
-    max_usd = _flag("max-usd")
     asset = _resolve_asset(token or "")
 
     on_allow = bool(to) and to.lower() in recipient_allowlist
@@ -365,18 +566,16 @@ def _canonicalize_financial(command: str, recipient_allowlist: set) -> Optional[
     else:
         recipient_status = "external" if to else "unspecified"
 
-    op = (
-        "swap" if re.search(r"\bswap\b", command, re.IGNORECASE)
-        else "approve" if re.search(r"\b(approve|erc20)\b", command, re.IGNORECASE)
-        else "transfer"
-    )
-
     return {
         "operation": op,
         "asset": asset,
         "amount": amount,
         "max_usd": max_usd,
         "recipient_status": recipient_status,
+        "ambiguous": False,
+        # Always present so that its absence is never the thing that has to be
+        # noticed: here it is False, so amount=None really does mean "not given".
+        "amount_unparsed": False,
         "allowlist_scope": "USDT transfers/approvals only; never lifts ETH or ATBASH rules",
         "note": "canonicalized pre-judge; raw 0x addresses omitted (redacted upstream)",
     }
@@ -416,9 +615,29 @@ def _infer_action_class(tool_name: str) -> str:
 
 
 def _as_bool(value: Optional[str], default: bool) -> bool:
+    """Parse a boolean env var, refusing to guess.
+
+    This used to be ``value.strip().lower() in {"1","true","yes","on"}``, so
+    every value outside that set read as False. ``ATBASH_ENFORCE_DECISION=``
+    (empty, the normal shape when a .env entry is left blank) or a typo like
+    ``enabled`` therefore turned enforcement OFF silently, on the one setting
+    that decides whether this plugin blocks anything at all. An unrecognised
+    value now keeps the default and says so.
+    """
     if value is None:
         return default
-    return value.strip().lower() in {"1", "true", "yes", "on"}
+    v = value.strip().lower()
+    if v in {"1", "true", "yes", "on"}:
+        return True
+    if v in {"0", "false", "no", "off"}:
+        return False
+    logger.warning(
+        "Atbash: unrecognized boolean value %r; keeping the default (%s). "
+        "Use one of 1/true/yes/on or 0/false/no/off.",
+        value,
+        default,
+    )
+    return default
 
 
 def _normalize_verdict(raw: Any) -> str:
@@ -550,7 +769,7 @@ def _setup_telemetry() -> None:
 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.fail_closed = _enforcement_enabled(os.getenv("ATBASH_ENFORCE_DECISION"))
         self.endpoint = os.getenv("ATBASH_ENDPOINT")
         self.judge_endpoint_policy = os.getenv("ATBASH_JUDGE_ENDPOINT_POLICY")
         self.judge_verify_pubkey = os.getenv("ATBASH_JUDGE_VERIFY_PUBKEY")
@@ -1033,6 +1252,31 @@ class AtbashHermesGuard:
                     }
                 return None
 
+            # Strict allowlist. _normalize_verdict passes any unrecognised
+            # string straight through (it only maps None to ERROR), and this
+            # used to end in a bare `return None`, i.e. run the tool. So a
+            # renamed verdict, a typo, an SDK newer than this plugin, or a
+            # response the SDK itself marked allow=False all executed the
+            # call. Only an exact ALLOW that the SDK also vouches for runs;
+            # a missing allow flag is not permission.
+            allow_flag = _extract_allow(verdict_raw)
+            if verdict == "ALLOW" and allow_flag is True:
+                return None
+
+            logger.warning(
+                "Atbash unusable verdict tool=%s verdict=%s allow=%s reason=%s",
+                tool_name,
+                verdict,
+                allow_flag,
+                reason,
+            )
+            if self.fail_closed:
+                return {
+                    "action": "block",
+                    "message": (
+                        f"Blocked (unusable Atbash verdict {verdict!r}): {reason}"
+                    ),
+                }
             return None
         except Exception as e:
             logger.warning("Atbash guard error tool=%s err=%s", tool_name, e)
@@ -1046,7 +1290,34 @@ class AtbashHermesGuard:
 
 def register(ctx):
     _setup_telemetry()
-    guard = AtbashHermesGuard()
-    guard._run_boot_probe()
-    ctx.register_hook("pre_tool_call", guard.pre_tool_call)
-    logger.info("[atbash-hermes-plugin] registered pre_tool_call hook")
+    state: Dict[str, Any] = {"guard": None, "error": "guard initialization incomplete"}
+
+    def fail_closed_pre_tool_call(**kwargs: Any):
+        guard = state["guard"]
+        if guard is None:
+            return {
+                "action": "block",
+                "message": f"Blocked (Atbash guard unavailable): {state['error']}",
+            }
+        return guard.pre_tool_call(**kwargs)
+
+    # Hermes isolates plugin-load exceptions and continues startup, so install
+    # the blocking hook before any SDK/config initialization can fail.
+    ctx.register_hook("pre_tool_call", fail_closed_pre_tool_call)
+    try:
+        state["guard"] = AtbashHermesGuard()
+    except Exception as error:
+        state["error"] = str(error)
+        logger.error(
+            "[atbash-hermes-plugin] guard initialization failed; "
+            "pre_tool_call remains fail-closed err=%s",
+            error,
+        )
+        return
+    # Say which mode actually registered — operators read this line as
+    # confirmation that enforcement is on, so it must not claim fail-closed
+    # when ATBASH_ENFORCE_DECISION turned enforcement off.
+    logger.info(
+        "[atbash-hermes-plugin] registered pre_tool_call hook mode=%s",
+        "fail-closed" if state["guard"].fail_closed else "fail-open",
+    )

{atbash_hermes_plugin-0.4.5.dev0.dist-info → atbash_hermes_plugin-0.4.5.dev2.dist-info}/METADATA

@@ -1,16 +1,16 @@
 Metadata-Version: 2.4
 Name: atbash-hermes-plugin
-Version: 0.4.5.dev0
+Version: 0.4.5.dev2
 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.13,>=3.10
+Requires-Python: <3.13,>=3.9
 Description-Content-Type: text/markdown
 License-File: LICENSE
-Requires-Dist: atbash-sdk==0.4.5.dev0
+Requires-Dist: atbash-sdk==0.5.1.dev0
 Requires-Dist: httpx<1,>=0.27
 Requires-Dist: opentelemetry-exporter-otlp-proto-http<2,>=1.29
 Requires-Dist: opentelemetry-sdk<2,>=1.29
@@ -48,6 +48,9 @@ If Hermes is installed in a virtual environment, use that environment's Python:
 /path/to/hermes/venv/bin/python -m pip install --pre atbash-hermes-plugin==0.4.3.dev0
 ```
 
+Maintainers: releases use clean staged source, live PyPI monotonic checks, and
+Trusted Publishing. See [the release process](docs/release.md).
+
 ## Configure Atbash
 
 The plugin needs an Atbash agent key. Configure either `ATBASH_KEY_PATH` or
@@ -233,13 +236,21 @@ Hermes sessions.
 
 ## Verdict Behavior
 
-- `ALLOW`: the tool proceeds.
+- `ALLOW` with `allow is True`: the tool proceeds. A missing `allow` flag is denied.
 - `HOLD`: the tool is blocked with a review message.
 - `BLOCK`, `DENY`, `REJECT`, `DISALLOW`: the tool is blocked.
 - Atbash API error:
   - `ATBASH_ENFORCE_DECISION=true`: fail closed and block.
   - `ATBASH_ENFORCE_DECISION=false`: fail open and allow.
 
+Atbash ships fail-closed on every tier. Setting `ATBASH_ENFORCE_DECISION=false`
+inverts that for this agent: a judge outage becomes a silent allow, and the
+governance layer stops governing for as long as it lasts. That is supported, but
+record a written risk acceptance in the deployment's security summary before
+turning it off, so the trade-off is auditable after an incident rather than
+discovered during one. See decision 0003 (fail-closed default) in the dashboard
+repo.
+
 For `HOLD`, the user-facing block message is:
 
 ```text

atbash_hermes_plugin-0.4.5.dev2.dist-info/RECORD

@@ -0,0 +1,7 @@
+atbash_hermes_plugin/__init__.py,sha256=vd7kxSnqMGrU3oYttRM6bLw5WwU4Rg5UsDXFXtO0pt8,53307
+atbash_hermes_plugin-0.4.5.dev2.dist-info/licenses/LICENSE,sha256=1vOJDJvAuOLDHJ8-Q0qDdOXZJJVli6Lr9mKKaFsOa5w,1600
+atbash_hermes_plugin-0.4.5.dev2.dist-info/METADATA,sha256=YEa0nl1uNmuRiNmw3FALxr5b5BME-RdmnQIvnoTqIG0,8068
+atbash_hermes_plugin-0.4.5.dev2.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+atbash_hermes_plugin-0.4.5.dev2.dist-info/entry_points.txt,sha256=YezkmasjRBXrSlXpqhSJdFhDCdBbENp-_THYtkcRTBo,67
+atbash_hermes_plugin-0.4.5.dev2.dist-info/top_level.txt,sha256=0nT35m8jNxzbQB3CerGf5kgH7hm_pc6GLadlf69w_JM,21
+atbash_hermes_plugin-0.4.5.dev2.dist-info/RECORD,,

atbash_hermes_plugin-0.4.5.dev0.dist-info/RECORD

@@ -1,7 +0,0 @@
-atbash_hermes_plugin/__init__.py,sha256=itcws37jMHaOv09bXKMzqnyIQBnKPA39CKUPkC4yu6A,41659
-atbash_hermes_plugin-0.4.5.dev0.dist-info/licenses/LICENSE,sha256=1vOJDJvAuOLDHJ8-Q0qDdOXZJJVli6Lr9mKKaFsOa5w,1600
-atbash_hermes_plugin-0.4.5.dev0.dist-info/METADATA,sha256=9cWzIdxD8ieKRXT-3uI0Dy1V5S--O1LsKTw0rN3Olps,7393
-atbash_hermes_plugin-0.4.5.dev0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
-atbash_hermes_plugin-0.4.5.dev0.dist-info/entry_points.txt,sha256=YezkmasjRBXrSlXpqhSJdFhDCdBbENp-_THYtkcRTBo,67
-atbash_hermes_plugin-0.4.5.dev0.dist-info/top_level.txt,sha256=0nT35m8jNxzbQB3CerGf5kgH7hm_pc6GLadlf69w_JM,21
-atbash_hermes_plugin-0.4.5.dev0.dist-info/RECORD,,