securevector-sdk-hermes 1.0.0__py3-none-any.whl

securevector_sdk_hermes/__init__.py

@@ -0,0 +1,44 @@
+"""SecureVector SDK for Hermes (NousResearch ``hermes-agent``).
+
+Zero-config (recommended) — the Hermes plugin manager auto-loads this
+package's ``hermes_agent.plugins`` entry point on startup::
+
+    pip install securevector-sdk-hermes
+    # then just run `hermes` (or the gateway) as usual.
+    # Enforcement: export SECUREVECTOR_SDK_MODE=enforce
+
+Programmatic / library embeddings (no plugin manager)::
+
+    from securevector_sdk_hermes import install
+    install(mode="enforce")   # wraps Hermes's tool registry dispatch
+
+Either way, every Hermes tool call — built-ins, MCP tools
+(``mcp_<server>_<tool>``), plugin tools — runs the local SecureVector app's
+three controls: tool-call permissions, secret/data-leak detection, and threat
+detection. Each decision is written to the app's tamper-evident audit chain
+with ``runtime_kind="hermes"``. Requires the SecureVector app running locally
+(installed automatically as the ``securevector-ai-monitor`` dependency).
+"""
+
+import logging
+
+from ._version import __version__
+from .config import Config
+from .errors import AppUnreachable, SecureVectorError, ToolBlocked
+from .plugin import install, register
+from .tool_id import HERMES_BUILTINS, RUNTIME_KIND, candidate_tool_ids
+
+log = logging.getLogger("securevector_sdk_hermes")
+
+__all__ = [
+    "__version__",
+    "install",
+    "register",
+    "Config",
+    "RUNTIME_KIND",
+    "HERMES_BUILTINS",
+    "candidate_tool_ids",
+    "SecureVectorError",
+    "ToolBlocked",
+    "AppUnreachable",
+]

securevector_sdk_hermes/_version.py

@@ -0,0 +1,7 @@
+"""Single source of truth for the package version at runtime.
+
+The published version is stamped from pyproject.toml / the release tag by CI;
+this constant is what `securevector_sdk_hermes.__version__` reports.
+"""
+
+__version__ = "1.0.0"

securevector_sdk_hermes/auto.py

@@ -0,0 +1,30 @@
+"""``import securevector_sdk_hermes.auto`` — one-line programmatic attach.
+
+Under the Hermes CLI / gateway this module is unnecessary: the package's
+``hermes_agent.plugins`` entry point attaches the guard automatically at
+startup. ``auto`` exists for library embeddings (driving ``AIAgent`` from your
+own Python process) where the plugin manager never runs::
+
+    import securevector_sdk_hermes.auto  # noqa: F401
+
+Mode comes from ``SECUREVECTOR_SDK_MODE`` (default ``observe``). Best-effort:
+when hermes-agent is not importable this logs a warning instead of raising, so
+a stray import never breaks a process.
+"""
+
+import logging
+import os
+
+from .plugin import install
+
+log = logging.getLogger("securevector_sdk_hermes")
+
+try:
+    install(mode=os.environ.get("SECUREVECTOR_SDK_MODE", "observe").strip().lower())
+except ImportError as exc:  # pragma: no cover - depends on hermes install
+    log.warning(
+        "SecureVector auto-attach skipped (%s). Under the hermes CLI the "
+        "entry-point plugin attaches automatically; for library use, call "
+        "securevector_sdk_hermes.install() after hermes-agent is importable.",
+        exc,
+    )

securevector_sdk_hermes/client.py

@@ -0,0 +1,252 @@
+"""Thin client to the local SecureVector app.
+
+Two transports, on purpose:
+
+* **Tool-permission resolution + audit** go over the local REST API
+  (``/api/tool-permissions/*``) via the stdlib (``urllib``) — no extra HTTP
+  dependency. The permission *decision* is computed client-side by merging the
+  three policy tiers exactly as the app's own OpenClaw hook does:
+  synced (cloud-pushed) > local override > essential registry > default-allow.
+  Hermes MCP names are lossy (``mcp_<server>_<tool>`` with underscores), so a
+  call is resolved against ALL of its candidate ids (raw name plus every
+  ``<server>:<tool>`` split) — tier precedence first, candidate order second.
+
+* **Secret + threat detection** uses the running app's ``/analyze`` REST route
+  — the detection engine lives in the app; the adapter must not reimplement it.
+
+Everything is best-effort and lazy: importing this module never requires the
+app or hermes-agent to be installed, so unit tests run standalone.
+"""
+
+import json
+import logging
+import urllib.error
+import urllib.parse
+import urllib.request
+from dataclasses import dataclass
+from typing import Any, Dict, List, Optional
+
+from .config import Config
+from .errors import AppUnreachable
+from .tool_id import RUNTIME_KIND, candidate_tool_ids
+
+log = logging.getLogger("securevector_sdk_hermes")
+
+_VALID_AUDIT_ACTIONS = ("block", "allow", "log_only")
+
+
+@dataclass
+class Verdict:
+    """Resolved permission decision for one tool id."""
+
+    action: str          # allow | block | log_only
+    risk: str
+    reason: str
+    is_essential: bool
+    tool_id: str
+
+
+@dataclass
+class AnalysisVerdict:
+    """Outcome of a secret/threat scan over a piece of text."""
+
+    is_threat: bool
+    risk_score: int
+    reason: str
+
+
+class LocalAppClient:
+    def __init__(self, cfg: Config):
+        self.cfg = cfg
+
+    # ------------------------------------------------------------------ #
+    # REST transport (stdlib)                                            #
+    # ------------------------------------------------------------------ #
+    def _request(self, method: str, path: str, body: Optional[dict]) -> Any:
+        url = f"{self.cfg.base_url.rstrip('/')}{path}"
+        data = json.dumps(body).encode("utf-8") if body is not None else None
+        headers = {"Content-Type": "application/json"}
+        # Forward a credential to remote, token-gated deployments (no-op for the
+        # default loopback app, which has no inbound auth).
+        if getattr(self.cfg, "api_key", ""):
+            headers["Authorization"] = f"Bearer {self.cfg.api_key}"
+        req = urllib.request.Request(
+            url,
+            data=data,
+            method=method,
+            headers=headers,
+        )
+        timeout = max(self.cfg.timeout_ms / 1000.0, 0.1)
+        with urllib.request.urlopen(req, timeout=timeout) as resp:  # noqa: S310 (localhost)
+            raw = resp.read()
+            return json.loads(raw) if raw else {}
+
+    def _get(self, path: str) -> Any:
+        return self._request("GET", path, None)
+
+    def _post(self, path: str, body: dict) -> Any:
+        return self._request("POST", path, body)
+
+    def reachable(self) -> bool:
+        try:
+            self._get("/api/tool-permissions/essential")
+            return True
+        except Exception:
+            return False
+
+    # ------------------------------------------------------------------ #
+    # (a) Permissions — synced > override > essential > default-allow    #
+    # ------------------------------------------------------------------ #
+    def resolve_permission(self, tool_id: str) -> Verdict:
+        try:
+            essential = self._get("/api/tool-permissions/essential") or {}
+            overrides = self._get("/api/tool-permissions/overrides") or {}
+            synced = self._get(
+                "/api/tool-permissions/synced-overrides?"
+                + urllib.parse.urlencode({"runtime": RUNTIME_KIND})
+            ) or {}
+        except (urllib.error.URLError, OSError, json.JSONDecodeError) as exc:
+            raise AppUnreachable(str(exc)) from exc
+        return self._resolve(tool_id, essential, overrides, synced)
+
+    @staticmethod
+    def _index(arr: Optional[List[dict]], key: str) -> Dict[str, dict]:
+        """Index rows by their id, with a case-insensitive fallback (exact
+        casing wins, mirroring the app's lookup)."""
+        out: Dict[str, dict] = {}
+        for item in arr or []:
+            k = item.get(key)
+            if k is not None:
+                out.setdefault(str(k).lower(), item)
+        for item in arr or []:
+            k = item.get(key)
+            if k is not None:
+                out[str(k)] = item
+        return out
+
+    @staticmethod
+    def _lookup(index: Dict[str, dict], candidates: List[str]) -> Optional[dict]:
+        """First candidate that matches (exact casing, then lowercased)."""
+        for cand in candidates:
+            hit = index.get(cand) or index.get(cand.lower())
+            if hit:
+                return hit
+        return None
+
+    def _resolve(self, tool_id, essential, overrides, synced) -> Verdict:
+        name = tool_id
+        # Tier precedence dominates candidate specificity: a synced rule that
+        # matches ANY candidate beats an override that matches the raw name.
+        candidates = candidate_tool_ids(tool_id)
+        emap = self._index(essential.get("tools"), "tool_id")
+        omap = self._index(overrides.get("overrides"), "tool_id")
+        smap = self._index(synced.get("synced"), "tool_id")
+        in_essential = self._lookup(emap, candidates) is not None
+
+        # 1. Cloud-pushed synced policy wins.
+        s = self._lookup(smap, candidates)
+        if s:
+            effect = str(s.get("effect", "")).lower()
+            action = "allow" if effect == "allow" else "block"
+            policy = s.get("policy_name") or s.get("policy_id") or "synced"
+            ver = f" v{s['policy_version']}" if s.get("policy_version") is not None else ""
+            return Verdict(
+                action, "synced", f"Synced policy '{policy}'{ver}: {effect}",
+                in_essential, name,
+            )
+        # 2. Local user override.
+        o = self._lookup(omap, candidates)
+        if o:
+            return Verdict(
+                o.get("action", "allow"), "overridden",
+                f"User override: {o.get('action')}",
+                in_essential, name,
+            )
+        # 3. Essential registry default.
+        e = self._lookup(emap, candidates)
+        if e:
+            return Verdict(
+                e.get("effective_action") or e.get("default_action") or "allow",
+                e.get("risk", "unknown"), e.get("reason", "Essential tool policy"),
+                True, name,
+            )
+        # 4. Not in registry — allowed by default.
+        return Verdict("allow", "unknown", "Not in registry — allowed by default", False, name)
+
+    # ------------------------------------------------------------------ #
+    # (b)+(c) Secret + threat detection — the running app's /analyze     #
+    # ------------------------------------------------------------------ #
+    # We deliberately use the app's REST `/analyze` (same engine, same HTTP
+    # transport as permissions/audit) rather than constructing an in-process
+    # SecureVectorClient: the SDK already requires the app running, and the
+    # in-process local analyzer needs its own config/license and can raise on
+    # init. Tool input is user→tool ("outgoing"); tool output is fetched
+    # context→model, which is exactly the app's IDPI "incoming" scan mode.
+    _DIRECTION_MODE = {"tool_input": "outgoing", "tool_output": "incoming"}
+
+    def analyze(self, text: str, direction: str) -> AnalysisVerdict:
+        if not text:
+            return AnalysisVerdict(False, 0, "empty")
+        wire_direction = self._DIRECTION_MODE.get(direction, "outgoing")
+        try:
+            # The analyze route is mounted at /analyze (no /api prefix). The
+            # request field is `direction` (AnalysisRequest.direction); `mode`
+            # is also sent for tolerance of older app builds, which ignore
+            # unknown fields either way.
+            res = self._post(
+                "/analyze",
+                {
+                    "text": str(text)[:102400],
+                    "direction": wire_direction,
+                    "mode": wire_direction,
+                },
+            )
+        except (urllib.error.URLError, OSError, json.JSONDecodeError) as exc:
+            raise AppUnreachable(f"analyze failed: {exc}") from exc
+        if not isinstance(res, dict):
+            return AnalysisVerdict(False, 0, "no-result")
+        risk = int(res.get("risk_score") or 0)
+        is_threat = bool(res.get("is_threat", False))
+        # Secrets/data-leaks also surface via redaction: the app sets
+        # redacted_text (and action_taken=redact/block) when it catches a secret.
+        # Control (b) keys on that, control (c) on is_threat. A finding is either.
+        has_secret = bool(res.get("redacted_text")) or (res.get("action_taken") in ("redact", "block"))
+        finding = is_threat or has_secret
+        return AnalysisVerdict(
+            finding, risk,
+            f"{direction} threat={is_threat} secret={has_secret} risk={risk}",
+        )
+
+    # ------------------------------------------------------------------ #
+    # Audit — append to the tamper-evident chain                         #
+    # ------------------------------------------------------------------ #
+    def record_audit(
+        self,
+        *,
+        tool_id: str,
+        function_name: Optional[str],
+        action: str,
+        risk: Optional[str],
+        reason: Optional[str],
+        is_essential: bool,
+        args_preview: Optional[str],
+        session_id: Optional[str] = None,
+        request_id: Optional[str] = None,
+    ) -> None:
+        act = action if action in _VALID_AUDIT_ACTIONS else "log_only"
+        body = {
+            "tool_id": tool_id,
+            "function_name": function_name or tool_id,
+            "action": act,
+            "risk": risk,
+            "reason": reason,
+            "is_essential": bool(is_essential),
+            "args_preview": args_preview,
+            "runtime_kind": RUNTIME_KIND,
+            "session_id": session_id,
+            "request_id": (request_id or None) and str(request_id)[:64],
+        }
+        try:
+            self._post("/api/tool-permissions/call-audit", body)
+        except Exception as exc:  # never let audit failure break the agent
+            log.debug("audit post failed: %s", exc)

securevector_sdk_hermes/config.py

@@ -0,0 +1,72 @@
+"""Adapter configuration — explicit kwargs override environment overrides
+defaults.
+
+Environment variables (all optional):
+    SECUREVECTOR_ENGINE_ENDPOINT    local app / engine base URL — the unified
+                                    variable shared with the native-hook
+                                    plugins (default http://127.0.0.1:8741)
+    SECUREVECTOR_SDK_APP_URL        legacy alias for the base URL, kept for
+                                    parity with the sibling framework SDKs;
+                                    SECUREVECTOR_ENGINE_ENDPOINT wins when
+                                    both are set
+    SECUREVECTOR_SDK_MODE           observe | enforce          (default observe)
+    SECUREVECTOR_SDK_TIMEOUT_MS     per-call verdict timeout   (default 3000)
+    SECUREVECTOR_SDK_RISK_THRESHOLD enforce-block risk cutoff  (default 70)
+    SECUREVECTOR_SDK_DISABLED       set truthy to no-op entirely
+    SECUREVECTOR_API_KEY            credential forwarded to the app as
+                                    Authorization: Bearer — required when the
+                                    app is a remote, token-gated deployment
+                                    (e.g. the Terraform self-host modules);
+                                    unused for the default loopback app
+
+Note: we deliberately do not read the existing SECUREVECTOR_URL — that points
+at the *cloud* API in the rest of the ecosystem, whereas the SDK talks to the
+*local* app.
+"""
+
+import os
+from dataclasses import dataclass
+
+DEFAULT_BASE_URL = "http://127.0.0.1:8741"
+
+
+def _truthy(val: str) -> bool:
+    return str(val).strip().lower() in ("1", "true", "yes", "on")
+
+
+def _base_url_from_env() -> str:
+    return (
+        os.environ.get("SECUREVECTOR_ENGINE_ENDPOINT")
+        or os.environ.get("SECUREVECTOR_SDK_APP_URL")
+        or DEFAULT_BASE_URL
+    )
+
+
+@dataclass
+class Config:
+    base_url: str = DEFAULT_BASE_URL
+    mode: str = "observe"            # observe (fail-open) | enforce (fail-closed)
+    timeout_ms: int = 3000
+    threat_risk_threshold: int = 70  # risk_score >= this blocks in enforce mode
+    enabled: bool = True
+    api_key: str = ""                # forwarded as Authorization: Bearer to the app
+
+    @classmethod
+    def from_env(cls, **overrides) -> "Config":
+        cfg = cls(
+            base_url=_base_url_from_env(),
+            mode=os.environ.get("SECUREVECTOR_SDK_MODE", "observe").strip().lower(),
+            timeout_ms=int(os.environ.get("SECUREVECTOR_SDK_TIMEOUT_MS", "3000")),
+            threat_risk_threshold=int(
+                os.environ.get("SECUREVECTOR_SDK_RISK_THRESHOLD", "70")
+            ),
+            enabled=not _truthy(os.environ.get("SECUREVECTOR_SDK_DISABLED", "")),
+            api_key=os.environ.get("SECUREVECTOR_API_KEY", ""),
+        )
+        # Explicit kwargs win over env, but only when actually provided.
+        for key, value in overrides.items():
+            if value is not None and hasattr(cfg, key):
+                setattr(cfg, key, value)
+        if cfg.mode not in ("observe", "enforce"):
+            cfg.mode = "observe"
+        return cfg

securevector_sdk_hermes/core.py

@@ -0,0 +1,181 @@
+"""Control routing — the three checks on every tool call.
+
+This is the framework-agnostic engine. Detection already exists in the app; the
+job here is **routing + the observe/enforce state machine**. The public surface
+is deliberately non-raising so each adapter can choose how to *act* on a block:
+
+* the Hermes ``pre_tool_call`` plugin hook returns Hermes's documented block
+  directive (``{"action": "block", "message": ...}``);
+* the ``install()`` dispatch wrap returns a registry-style error string
+  instead of executing the tool.
+
+Per intercepted call, in order:
+
+    (a) PERMISSIONS  — resolve allow/block for the tool id
+    (b) SECRET scan  — \\
+    (c) THREAT scan  — // over the serialized tool input (and, on end, output)
+
+``observe`` (default) is fail-open: everything is logged, nothing is blocked,
+and an unreachable app degrades to allow. ``enforce`` is fail-closed: a policy
+block, a high-risk input finding, or an unreachable app all mark the decision
+``blocked``.
+"""
+
+import logging
+import re
+import sys
+from dataclasses import dataclass
+from typing import Optional
+
+from .client import LocalAppClient
+from .config import Config
+from .errors import AppUnreachable, ToolBlocked
+
+log = logging.getLogger("securevector_sdk_hermes")
+
+# Belt-and-braces preview redaction (the app redacts too; this keeps obvious
+# secrets out of the args_preview we send).
+_REDACTIONS = [
+    (re.compile(r"AKIA[A-Z0-9]{16}"), "AKIA[REDACTED]"),
+    (re.compile(r"ghp_[A-Za-z0-9]{36}"), "ghp_[REDACTED]"),
+    (re.compile(r"sk-[A-Za-z0-9]{20,}"), "sk-[REDACTED]"),
+    (re.compile(r"(?i)(password\"?\s*[:=]\s*\")[^\"]+(\")"), r"\1[REDACTED]\2"),
+]
+
+
+def redact(text: object, limit: int = 500) -> str:
+    if not text:
+        return ""
+    s = str(text)
+    for pattern, repl in _REDACTIONS:
+        s = pattern.sub(repl, s)
+    return s[:limit]
+
+
+@dataclass
+class Decision:
+    """Result of evaluating a tool call's input. ``blocked`` already accounts
+    for mode — it is only True when the call should actually be stopped (i.e.
+    enforce mode + a deny). ``action`` is the audited action."""
+
+    blocked: bool
+    action: str          # allow | block | log_only
+    reason: str
+    risk: str
+
+
+class Interceptor:
+    def __init__(self, cfg: Config, client: Optional[LocalAppClient] = None):
+        self.cfg = cfg
+        self.client = client or LocalAppClient(cfg)
+        self._disclosed = False
+
+    @property
+    def enforce(self) -> bool:
+        return self.cfg.mode == "enforce"
+
+    def _disclose_once(self) -> None:
+        if self.enforce and not self._disclosed:
+            self._disclosed = True
+            sys.stderr.write(
+                "[SecureVector] SDK is in ENFORCE mode — tool calls will be "
+                "BLOCKED if a policy denies them or the local app is unreachable.\n"
+            )
+
+    # ------------------------------------------------------------------ #
+    # Primary, non-raising API                                           #
+    # ------------------------------------------------------------------ #
+    def evaluate_input(
+        self,
+        tool_id: str,
+        args_text: str,
+        *,
+        session_id: Optional[str] = None,
+        request_id: Optional[str] = None,
+    ) -> Decision:
+        """Run the three controls on a tool's input and return a Decision.
+        Records the audit row as a side effect. Never raises."""
+        if not self.cfg.enabled:
+            return Decision(False, "allow", "sdk disabled", "")
+        self._disclose_once()
+        preview = redact(args_text)
+
+        # (a) PERMISSIONS
+        try:
+            verdict = self.client.resolve_permission(tool_id)
+        except AppUnreachable:
+            if self.enforce:
+                return Decision(True, "block", "local app unreachable (fail-closed)", "unreachable")
+            log.warning("app unreachable; observe mode allows %s", tool_id)
+            return Decision(False, "allow", "app unreachable (observe, fail-open)", "unreachable")
+
+        if verdict.action == "block":
+            self.client.record_audit(
+                tool_id=tool_id, function_name=tool_id, action="block",
+                risk=verdict.risk, reason=verdict.reason,
+                is_essential=verdict.is_essential, args_preview=preview,
+                session_id=session_id, request_id=request_id,
+            )
+            return Decision(self.enforce, "block", verdict.reason, verdict.risk)
+
+        # (b)+(c) SECRET + THREAT on the tool input
+        a_in = None
+        try:
+            a_in = self.client.analyze(args_text, "tool_input")
+        except AppUnreachable:
+            a_in = None  # analysis best-effort; permissions already passed
+
+        if a_in and a_in.is_threat:
+            should_block = self.enforce and a_in.risk_score >= self.cfg.threat_risk_threshold
+            act = "block" if should_block else "log_only"
+            self.client.record_audit(
+                tool_id=tool_id, function_name=tool_id, action=act,
+                risk=str(a_in.risk_score),
+                reason=f"Input secret/threat detected (risk={a_in.risk_score})",
+                is_essential=verdict.is_essential, args_preview=preview,
+                session_id=session_id, request_id=request_id,
+            )
+            return Decision(should_block, act, f"input secret/threat risk={a_in.risk_score}", str(a_in.risk_score))
+
+        # Allowed — record the decision.
+        self.client.record_audit(
+            tool_id=tool_id, function_name=tool_id, action="allow",
+            risk=verdict.risk, reason=verdict.reason,
+            is_essential=verdict.is_essential, args_preview=preview,
+            session_id=session_id, request_id=request_id,
+        )
+        return Decision(False, "allow", verdict.reason, verdict.risk)
+
+    def scan_output(
+        self,
+        tool_id: str,
+        output_text: str,
+        *,
+        session_id: Optional[str] = None,
+        request_id: Optional[str] = None,
+    ) -> None:
+        """Scan the tool RESULT for secrets / exfiltration (observe-only — the
+        tool already ran). Records a row if anything is found. Never raises."""
+        if not self.cfg.enabled:
+            return
+        try:
+            a_out = self.client.analyze(output_text, "tool_output")
+        except AppUnreachable:
+            return
+        if a_out and a_out.is_threat:
+            self.client.record_audit(
+                tool_id=tool_id, function_name=tool_id, action="log_only",
+                risk=str(a_out.risk_score),
+                reason=f"Output secret/threat detected (risk={a_out.risk_score})",
+                is_essential=False, args_preview=redact(output_text),
+                session_id=session_id, request_id=request_id,
+            )
+
+    # ------------------------------------------------------------------ #
+    # Raising convenience (adapters where blocking == raising)           #
+    # ------------------------------------------------------------------ #
+    def guard_input(self, tool_id: str, args_text: str, **kwargs) -> Decision:
+        decision = self.evaluate_input(tool_id, args_text, **kwargs)
+        if decision.blocked:
+            raise ToolBlocked(tool_id, decision.reason)
+        return decision

securevector_sdk_hermes/errors.py

@@ -0,0 +1,27 @@
+"""Exceptions raised by the SecureVector Hermes adapter.
+
+``ToolBlocked`` is available for callers using ``Interceptor.guard_input``
+directly; the shipped Hermes attach paths never raise into the agent loop —
+the plugin hook blocks via Hermes's own block directive and the ``install()``
+dispatch wrap returns a registry-style error string. In ``observe`` mode
+nothing is ever blocked — every call is logged and allowed through.
+"""
+
+
+class SecureVectorError(Exception):
+    """Base class for all adapter errors."""
+
+
+class ToolBlocked(SecureVectorError):
+    """Raised in enforce mode to abort a tool call (policy block, input threat,
+    or fail-closed when the local app is unreachable)."""
+
+    def __init__(self, tool_id: str, reason: str):
+        self.tool_id = tool_id
+        self.reason = reason
+        super().__init__(f"SecureVector blocked tool '{tool_id}': {reason}")
+
+
+class AppUnreachable(SecureVectorError):
+    """The local SecureVector app could not be reached. Mode decides the
+    consequence: observe → allow (fail-open); enforce → deny (fail-closed)."""