agenthacker 0.1.0__py3-none-any.whl

firewall_sdk/cloud_client.py

@@ -0,0 +1,753 @@
+# SPDX-License-Identifier: Apache-2.0
+# Copyright 2026 AgentHacker
+
+"""CloudClient — bridges the local SDK and the AgentHacker AWS backend.
+
+When AGENTHACKER_API_KEY is set (or configure() is called explicitly), the SDK
+automatically routes cloud features to the backend:
+
+- IntentGuard.classify() consults Bedrock via /v1/intent/classify
+- check_user_risk() reads/writes centralized Aurora via /v1/risk/{user_hash}
+- log_firewall_event() / log_agent_invocation() send events to /v1/events
+
+All HTTP calls are fail-open: a network error or non-200 response never
+crashes the caller — the SDK silently falls back to its local behavior.
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+import re
+from concurrent.futures import ThreadPoolExecutor
+from typing import Any
+from urllib.parse import quote
+
+logger = logging.getLogger(__name__)
+
+_DEFAULT_API_URL = "https://vhdzhows74.execute-api.us-west-2.amazonaws.com/prod"
+
+# user_hash is produced by hash_email() as a lowercase hex string (8–64 chars).
+# Reject anything outside this alphabet to prevent path traversal.
+_USER_HASH_RE = re.compile(r"^[0-9a-f]{8,64}$")
+
+
+def _safe_hash(user_hash: str) -> str:
+    """Validate and percent-encode user_hash for use in a URL path segment.
+
+    Raises ValueError for values that don't match the expected hex format so
+    that callers can log-and-skip rather than emit a malformed request.
+    """
+    if not _USER_HASH_RE.match(user_hash):
+        raise ValueError(
+            f"user_hash must be a lowercase hex string (8-64 chars), got {user_hash!r}"
+        )
+    return quote(user_hash, safe="")
+
+
+# Default HTTP timeout (seconds) for cloud calls. Overridable via the
+# AGENTHACKER_HTTP_TIMEOUT env var or a per-client ``timeout=``. The backend's
+# Bedrock-judge endpoint can be slow on a cold start and cloud calls fail open,
+# so a too-small timeout silently drops protection until the backend warms —
+# raise it (or warm the backend at startup) for latency-variable deployments.
+try:
+    _TIMEOUT_S = float(os.environ.get("AGENTHACKER_HTTP_TIMEOUT", "3"))
+except ValueError:
+    _TIMEOUT_S = 3.0
+
+_executor = ThreadPoolExecutor(max_workers=4, thread_name_prefix="cloud-client")
+
+# Module-level singleton
+_client: CloudClient | None = None
+
+
+class CloudClient:
+    """HTTP client that calls the AgentHacker backend API.
+
+    Instantiate via configure() or use the module-level configure() helper.
+    """
+
+    def __init__(
+        self,
+        api_key: str,
+        api_url: str = _DEFAULT_API_URL,
+        *,
+        timeout: float | None = None,
+    ) -> None:
+        self._api_key = api_key
+        self._url = api_url.rstrip("/")
+        # Per-client HTTP timeout; defaults to the (env-configurable) module value.
+        self._timeout = float(timeout) if timeout is not None else _TIMEOUT_S
+        self._headers = {
+            "x-api-key": api_key,
+            "Content-Type": "application/json",
+        }
+        # Paths we've already warned about an auth failure for — so a rejected
+        # key produces one loud warning per endpoint, not a flood (or silence).
+        self._auth_warned: set[str] = set()
+        # Same one-warning-per-endpoint treatment for throttling (HTTP 429).
+        self._throttle_warned: set[str] = set()
+
+    # ── Intent classification ─────────────────────────────────────────
+
+    def classify_intent(
+        self,
+        message: str,
+        *,
+        session_id: str = "",
+        user_hash: str = "",
+        agent: str | None = None,
+        actor_role: str | None = None,
+        agent_intents: list[str] | None = None,
+        semantic_miss: bool = False,
+        llm_guard_injection: bool = False,
+        system_prompt_suffix: str | None = None,
+        active_task: str | None = None,
+        conversation_summary: str | None = None,
+    ) -> dict:
+        """POST /v1/intent/classify — returns {decision, confidence, threat_type, continuation, intents}.
+
+        intents is a list of {"text": str, "in_scope": bool} objects when
+        agent_intents is supplied; Bedrock scopes each split intent to the
+        declared list. Returns safe defaults on any error (fail-open).
+
+        semantic_miss=True signals that the caller's local semantic-similarity
+        gate was enabled and the message failed to match any known-good intent.
+        It is forwarded as a weak suspicion hint so the cloud judge scrutinizes
+        the message more carefully; it is never on its own grounds to block.
+
+        llm_guard_injection=True signals that a dedicated prompt-injection
+        classifier (LLM Guard) flagged this message upstream. It is a stronger
+        suspicion hint than semantic_miss, but is still advisory — the judge
+        makes the final call so the classifier never hard-refuses on its own.
+
+        system_prompt_suffix is appended to the Bedrock system prompt after
+        the base instructions and agent-intents block. Use it to add
+        domain-specific context (e.g. "Also block requests about competitor
+        products") without replacing the core security classification logic.
+
+        active_task / conversation_summary carry multi-turn context: when set,
+        the judge can treat a bare follow-up detail (a date, a name) as
+        continuing the in-progress task instead of an out-of-scope fragment, and
+        sets continuation=True in the response. Both are optional — omit them for
+        a stateless check.
+        """
+        body: dict = {
+            "message": message,
+            "session_id": session_id,
+            "user_hash": user_hash,
+        }
+        if agent:
+            body["agent"] = agent
+        if actor_role:
+            body["actor_role"] = actor_role
+        if agent_intents:
+            body["agent_intents"] = agent_intents
+        if semantic_miss:
+            body["semantic_miss"] = True
+        if llm_guard_injection:
+            body["llm_guard_injection"] = True
+        if system_prompt_suffix:
+            body["system_prompt_suffix"] = system_prompt_suffix
+        if active_task:
+            body["active_task"] = active_task
+        if conversation_summary:
+            body["conversation_summary"] = conversation_summary
+        return self._post("/v1/intent/classify", body) or {
+            "decision": "allow",
+            "confidence": 0.5,
+            "threat_type": None,
+            "continuation": False,
+            "intents": [],
+        }
+
+    # ── Output classification (Bedrock output judge) ──────────────────
+
+    def classify_output(
+        self,
+        output: str,
+        *,
+        session_id: str = "",
+        user_hash: str = "",
+        agent: str | None = None,
+        actor_role: str | None = None,
+        user_request: str | None = None,
+        system_prompt: str | None = None,
+        agent_intents: list[str] | None = None,
+    ) -> dict:
+        """POST /v1/output/classify — returns {decision, confidence, signal, reasoning}.
+
+        Asks the Bedrock judge whether an agent OUTPUT shows clear evidence of a
+        successful prompt injection (system-prompt leak, refusal-suppression,
+        persona break, intent-deviation, tool-abuse, data-exfiltration). Returns
+        safe defaults on any error (fail-open).
+
+        user_request and agent_intents give the judge the context it needs to
+        spot an output that answers a different task than the user asked.
+        system_prompt should be a short PERSONA DESCRIPTION, not the verbatim
+        secret prompt — verbatim-leak detection stays the job of the local
+        output-guard shingle check.
+        """
+        body: dict = {
+            "output": output,
+            "session_id": session_id,
+            "user_hash": user_hash,
+        }
+        if agent:
+            body["agent"] = agent
+        if actor_role:
+            body["actor_role"] = actor_role
+        if user_request:
+            body["user_request"] = user_request
+        if system_prompt:
+            body["system_prompt"] = system_prompt
+        if agent_intents:
+            body["agent_intents"] = agent_intents
+        return self._post("/v1/output/classify", body) or {
+            "decision": "allow",
+            "confidence": 0.5,
+            "signal": None,
+            "reasoning": None,
+        }
+
+    # ── Risk scoring ──────────────────────────────────────────────────
+
+    def get_risk_score(self, user_hash: str) -> dict | None:
+        """GET /v1/risk/{user_hash} — returns risk score dict or None on error."""
+        try:
+            safe = _safe_hash(user_hash)
+        except ValueError as exc:
+            logger.warning("get_risk_score: %s", exc)
+            return None
+        return self._get(f"/v1/risk/{safe}")
+
+    def record_invocation(
+        self,
+        user_hash: str,
+        *,
+        blocked: bool,
+        checkpoint: str | None = None,
+        rule_id: str | None = None,
+        latency_ms: float = 0.0,
+        tool_calls: int = 0,
+        tokens: int = 0,
+        session_id: str | None = None,
+        question_preview: str | None = None,
+        agent: str | None = None,
+        actor_role: str | None = None,
+    ) -> None:
+        """POST /v1/risk/{user_hash} — fire-and-forget invocation record."""
+        body: dict[str, Any] = {
+            "blocked": blocked,
+            "latency_ms": latency_ms,
+            "tool_calls": tool_calls,
+            "tokens": tokens,
+        }
+        if checkpoint:
+            body["checkpoint"] = checkpoint
+        if rule_id:
+            body["rule_id"] = rule_id
+        if session_id:
+            body["session_id"] = session_id
+        if question_preview:
+            body["question_preview"] = question_preview
+        if agent:
+            body["agent"] = agent
+        if actor_role:
+            body["actor_role"] = actor_role
+        try:
+            safe = _safe_hash(user_hash)
+        except ValueError as exc:
+            logger.warning("record_invocation: %s", exc)
+            return
+        self._post_bg(f"/v1/risk/{safe}", body)
+
+    # ── Event logging ─────────────────────────────────────────────────
+
+    def submit_events(self, batch: dict) -> None:
+        """POST /v1/events — fire-and-forget batch event log."""
+        self._post_bg("/v1/events", batch)
+
+    # ── Reports ───────────────────────────────────────────────────────
+
+    def generate_report(
+        self,
+        date_range: str = "30d",
+        agent: str | None = None,
+    ) -> dict | None:
+        """GET /v1/reports/generate — build and return a full security audit report.
+
+        Args:
+            date_range: Window to cover. One of "7d", "30d", "90d", "365d", "1y".
+            agent: Scope to a single agent name. Omit for a company-wide report.
+
+        Returns:
+            Dict with keys: report_id, generated_at, evidence_hash, s3_url,
+            data (full JSON bundle including narrative), html (styled HTML string).
+            Returns None on any error.
+        """
+        params: dict[str, str] = {"date_range": date_range}
+        if agent:
+            params["agent"] = agent
+        return self._get("/v1/reports/generate", params=params, timeout=90)
+
+    def list_reports(
+        self,
+        agent: str | None = None,
+        limit: int = 20,
+    ) -> list[dict] | None:
+        """GET /v1/reports — list past reports, most recent first.
+
+        Args:
+            agent: Filter to a specific agent. Omit for all.
+            limit: Max number of results (1–100).
+
+        Returns:
+            List of report metadata dicts, or None on error.
+        """
+        params: dict[str, str] = {"limit": str(limit)}
+        if agent:
+            params["agent"] = agent
+        result = self._get("/v1/reports", params=params)
+        return result.get("reports") if result else None
+
+    def get_report(self, report_id: str) -> dict | None:
+        """GET /v1/reports/{report_id} — retrieve a stored report by ID.
+
+        Args:
+            report_id: UUID of the report (returned by generate_report).
+
+        Returns:
+            Full report dict including data and html, or None on error.
+        """
+        safe_id = quote(report_id, safe="")
+        return self._get(f"/v1/reports/{safe_id}")
+
+    # ── Low-level HTTP helpers ────────────────────────────────────────
+
+    def _warn_auth_once(self, path: str, status: int) -> None:
+        """Emit a single loud warning when the backend rejects our key.
+
+        Cloud calls are fail-open by design — an outage must never take the
+        agent down. But a *configuration* failure (a key the URL won't accept)
+        is not an outage: silently failing open there means the firewall looks
+        installed while protecting nothing. So 401/403 gets a one-time WARNING
+        per endpoint, distinct from the debug-level noise of transient errors.
+        """
+        if path in self._auth_warned:
+            return
+        self._auth_warned.add(path)
+        logger.warning(
+            "AgentHacker: %s was rejected with HTTP %d (authentication/authorization "
+            "failed). The firewall is FAILING OPEN — requests are NOT being checked. "
+            "The API key may be invalid for this URL (%s) or not yet provisioned for it. "
+            "Verify AGENTHACKER_API_KEY / AGENTHACKER_API_URL, or call Firewall.preflight() "
+            "at startup to surface this before serving traffic.",
+            path,
+            status,
+            self._url,
+        )
+
+    def _warn_throttle_once(self, path: str) -> None:
+        """Warn once per endpoint when the backend throttles us (HTTP 429).
+
+        Like an auth failure, throttling is not a transient blip to swallow: the
+        cloud call fails open, so a rate-limited agent is silently *unchecked*
+        until the limit clears. Distinct from the debug-level noise of ordinary
+        transient errors so it is visible in logs.
+        """
+        if path in self._throttle_warned:
+            return
+        self._throttle_warned.add(path)
+        logger.warning(
+            "AgentHacker: %s was throttled with HTTP 429 (rate limited). The firewall "
+            "is FAILING OPEN — requests are NOT being checked until the limit clears. "
+            "Consider raising your usage-plan limit or adding client-side backoff.",
+            path,
+        )
+
+    def _post(self, path: str, body: dict) -> dict | None:
+        try:
+            import requests
+
+            resp = requests.post(
+                self._url + path,
+                json=body,
+                headers=self._headers,
+                timeout=self._timeout,
+            )
+            if resp.status_code < 300:
+                return resp.json()
+            if resp.status_code in (401, 403):
+                self._warn_auth_once(path, resp.status_code)
+            elif resp.status_code == 429:
+                self._warn_throttle_once(path)
+            else:
+                logger.debug("Cloud backend %s returned %d", path, resp.status_code)
+        except Exception as exc:
+            logger.debug("Cloud client POST %s failed: %s", path, exc)
+        return None
+
+    def _get(
+        self,
+        path: str,
+        params: dict[str, str] | None = None,
+        timeout: float | None = None,
+    ) -> dict | None:
+        try:
+            import requests
+
+            resp = requests.get(
+                self._url + path,
+                headers=self._headers,
+                params=params,
+                timeout=self._timeout if timeout is None else timeout,
+            )
+            if resp.status_code < 300:
+                return resp.json()
+            if resp.status_code in (401, 403):
+                self._warn_auth_once(path, resp.status_code)
+            elif resp.status_code == 429:
+                self._warn_throttle_once(path)
+            else:
+                logger.debug("Cloud backend %s returned %d", path, resp.status_code)
+        except Exception as exc:
+            logger.debug("Cloud client GET %s failed: %s", path, exc)
+        return None
+
+    def preflight(self, *, timeout: float | None = None) -> dict:
+        """Verify the API key + URL are usable, without failing open.
+
+        Sends a benign classification request to the live backend and reports
+        what actually happened, so misconfiguration can be caught at startup
+        instead of silently swallowed at request time. Never raises.
+
+        Returns a dict ``{"ok", "status", "url", "detail"}`` where ``ok`` is
+        True only on a 2xx response.
+        """
+        try:
+            import requests
+
+            resp = requests.post(
+                self._url + "/v1/intent/classify",
+                json={"message": "preflight", "session_id": "", "user_hash": ""},
+                headers=self._headers,
+                timeout=self._timeout if timeout is None else timeout,
+            )
+            if resp.status_code in (401, 403):
+                return {
+                    "ok": False,
+                    "status": resp.status_code,
+                    "url": self._url,
+                    "detail": "authentication failed — the key is not accepted by this URL",
+                }
+            if resp.status_code >= 300:
+                return {
+                    "ok": False,
+                    "status": resp.status_code,
+                    "url": self._url,
+                    "detail": f"unexpected status {resp.status_code}",
+                }
+            return {
+                "ok": True,
+                "status": resp.status_code,
+                "url": self._url,
+                "detail": "ok",
+            }
+        except Exception as exc:
+            return {
+                "ok": False,
+                "status": None,
+                "url": self._url,
+                "detail": f"backend unreachable: {exc}",
+            }
+
+    def _post_bg(self, path: str, body: dict) -> None:
+        """Submit HTTP POST in a background thread — never blocks the caller."""
+        _executor.submit(self._post, path, body)
+
+
+# ── CloudStore — implements EventStore protocol ───────────────────────
+
+
+class CloudStore:
+    """EventStore implementation that ships all events to the AWS backend.
+
+    Registered as the active store by setup_logging() when a cloud client
+    is configured, so all log_firewall_event() / log_agent_invocation()
+    calls automatically flow to Aurora.
+    """
+
+    def __init__(self, client: CloudClient) -> None:
+        self._client = client
+
+    def record_firewall_event(
+        self,
+        *,
+        checkpoint,
+        rule_id,
+        rule_name,
+        excerpt=None,
+        user_hash=None,
+        ip=None,
+        agent=None,
+        source="runtime",
+        actor_role=None,
+        invocation_id=None,
+        **_,
+    ) -> None:
+        self.submit_firewall_event(
+            checkpoint=checkpoint,
+            rule_id=rule_id,
+            rule_name=rule_name,
+            excerpt=excerpt,
+            user_hash=user_hash,
+            ip=ip,
+            agent=agent,
+            source=source,
+            actor_role=actor_role,
+            invocation_id=invocation_id,
+        )
+
+    def record_invocation(
+        self,
+        *,
+        invocation_id=None,
+        user_hash=None,
+        question_preview=None,
+        question_full=None,
+        blocked,
+        checkpoint=None,
+        rule_id=None,
+        tool_calls=0,
+        tokens=0,
+        latency_ms=0.0,
+        trace=None,
+        agent=None,
+        source="runtime",
+        actor_role=None,
+        session_id=None,
+        **_,
+    ) -> None:
+        self.submit_invocation(
+            invocation_id=invocation_id,
+            user_hash=user_hash,
+            question_preview=question_preview,
+            question_full=question_full,
+            blocked=blocked,
+            checkpoint=checkpoint,
+            rule_id=rule_id,
+            tool_calls=tool_calls,
+            tokens=tokens,
+            latency_ms=latency_ms,
+            trace=trace,
+            agent=agent,
+            source=source,
+            actor_role=actor_role,
+            session_id=session_id,
+        )
+
+    def submit_firewall_event(
+        self,
+        *,
+        checkpoint,
+        rule_id,
+        rule_name,
+        excerpt=None,
+        user_hash=None,
+        ip=None,
+        agent=None,
+        source="runtime",
+        actor_role=None,
+        invocation_id=None,
+        **_,
+    ) -> None:
+        self._client.submit_events(
+            {
+                "user_hash": user_hash,
+                "firewall_events": [
+                    {
+                        "checkpoint": checkpoint,
+                        "rule_id": rule_id,
+                        "rule_name": rule_name,
+                        "excerpt": excerpt,
+                        "ip": ip,
+                        "agent": agent,
+                        "source": source,
+                        "actor_role": actor_role,
+                        "invocation_id": invocation_id,
+                    }
+                ],
+            }
+        )
+
+    def submit_invocation(
+        self,
+        *,
+        invocation_id=None,
+        user_hash=None,
+        question_preview=None,
+        question_full=None,
+        blocked,
+        checkpoint=None,
+        rule_id=None,
+        tool_calls=0,
+        tokens=0,
+        latency_ms=0.0,
+        trace=None,
+        agent=None,
+        source="runtime",
+        actor_role=None,
+        bedrock_decision=None,
+        bedrock_confidence=None,
+        session_id=None,
+        **_,
+    ) -> None:
+        batch: dict[str, Any] = {
+            "user_hash": user_hash,
+            "invocation": {
+                "invocation_id": invocation_id,
+                "question_preview": question_preview,
+                "blocked": blocked,
+                "checkpoint": checkpoint,
+                "rule_id": rule_id,
+                "tool_calls": tool_calls,
+                "tokens": tokens,
+                "latency_ms": latency_ms,
+                "trace": trace,
+                "agent": agent,
+                "source": source,
+                "actor_role": actor_role,
+                "bedrock_decision": bedrock_decision,
+                "bedrock_confidence": bedrock_confidence,
+            },
+            "firewall_events": [],
+        }
+        if session_id:
+            batch["session_id"] = session_id
+        if question_full and agent:
+            batch["s3_chat_line"] = {
+                "role": "user",
+                "content": question_full,
+                "agent": agent,
+            }
+        self._client.submit_events(batch)
+
+
+# ── Module API ────────────────────────────────────────────────────────
+
+
+def configure(
+    api_key: str | None = None,
+    api_url: str | None = None,
+    *,
+    timeout: float | None = None,
+) -> None:
+    """Configure the global cloud client.
+
+    Called automatically on SDK import if AGENTHACKER_API_KEY is set.
+    Can also be called explicitly in agent startup code.
+
+    Args:
+        api_key: AgentHacker API key. If None, reads AGENTHACKER_API_KEY env var.
+        api_url: Backend URL override. If None, reads the AGENTHACKER_API_URL env
+            var, then falls back to the production API Gateway URL. Set
+            AGENTHACKER_API_URL=http://localhost:8000 to point at a local backend.
+    """
+    global _client
+    key = api_key or os.environ.get("AGENTHACKER_API_KEY")
+    url = api_url or os.environ.get("AGENTHACKER_API_URL") or _DEFAULT_API_URL
+    if key:
+        _client = CloudClient(api_key=key, api_url=url, timeout=timeout)
+        logger.info("AgentHacker cloud client configured (url=%s)", url)
+    else:
+        _client = None
+
+
+def get_client() -> CloudClient | None:
+    """Return the active cloud client, or None if not configured."""
+    return _client
+
+
+def reset() -> None:
+    """Clear the active client. For test isolation only."""
+    global _client
+    _client = None
+
+
+def generate_report(
+    date_range: str = "30d",
+    agent: str | None = None,
+) -> dict | None:
+    """Generate a security audit report via the AgentHacker backend.
+
+    Requires the cloud client to be configured (AGENTHACKER_API_KEY set or
+    configure() called). Returns None if not configured or on any error.
+
+    Args:
+        date_range: "7d", "30d", "90d", "365d", or "1y".
+        agent: Scope to one agent name; omit for a company-wide report.
+
+    Returns:
+        Dict with report_id, data (JSON bundle + narrative), and html
+        (self-contained styled HTML page ready for display). None on error.
+
+    Example::
+
+        from firewall_sdk import generate_report
+
+        result = generate_report(date_range="30d")
+        if result:
+            with open("report.html", "w") as f:
+                f.write(result["html"])
+            print("Report ID:", result["report_id"])
+    """
+    client = get_client()
+    if not client:
+        logger.warning(
+            "generate_report: cloud client not configured — set AGENTHACKER_API_KEY"
+        )
+        return None
+    return client.generate_report(date_range=date_range, agent=agent)
+
+
+def list_reports(
+    agent: str | None = None,
+    limit: int = 20,
+) -> list[dict] | None:
+    """List past reports from the AgentHacker backend.
+
+    Args:
+        agent: Filter to a specific agent. Omit for all.
+        limit: Max results to return (1–100).
+
+    Returns:
+        List of report metadata dicts (report_id, agent, period_start,
+        period_end, generated_at, evidence_hash, narrative_source).
+        None if not configured or on error.
+    """
+    client = get_client()
+    if not client:
+        logger.warning(
+            "list_reports: cloud client not configured — set AGENTHACKER_API_KEY"
+        )
+        return None
+    return client.list_reports(agent=agent, limit=limit)
+
+
+def get_report(report_id: str) -> dict | None:
+    """Retrieve a previously generated report by ID.
+
+    Args:
+        report_id: UUID returned by generate_report().
+
+    Returns:
+        Full report dict including data and html, or None on error.
+    """
+    client = get_client()
+    if not client:
+        logger.warning(
+            "get_report: cloud client not configured — set AGENTHACKER_API_KEY"
+        )
+        return None
+    return client.get_report(report_id)