agenthacker 0.1.0__py3-none-any.whl

firewall_sdk/client.py

@@ -0,0 +1,676 @@
+# SPDX-License-Identifier: Apache-2.0
+# Copyright 2026 AgentHacker
+
+"""High-level ``Firewall`` client — the simplest way to protect an agent.
+
+This is the *cloud tier* (Tier 1): a thin, friendly wrapper over the backend
+API. You instantiate it once, call :meth:`Firewall.check` before your LLM, and
+:meth:`Firewall.log` after. No local ML, no boilerplate.
+
+Constructed **without an API key** it runs in **local mode**: the four local
+checkpoints (``scan_input``/``scan_data``/``scan_tool_call``/``scan_output``)
+work fully offline, ``check()`` falls back to the deterministic CP-1 input scan,
+and the cloud-only features degrade gracefully. Set ``AGENTHACKER_API_KEY`` (or
+pass ``api_key=``) to enable the cloud tier.
+
+    from firewall_sdk import Firewall
+
+    fw = Firewall(                       # api_key defaults to AGENTHACKER_API_KEY
+        agent="support_bot",
+        agent_intents=["Answer account questions", "Help reset passwords"],
+    )
+
+    check = fw.check(user_msg, user_id="user@acme.com", session_id=sid)
+    if check.blocked:
+        return check.reason              # e.g. "prompt_injection"
+
+    answer = my_llm(user_msg)            # your own model — unchanged
+
+    fw.log(user_msg, answer, user_id="user@acme.com", session_id=sid,
+           tokens=512, latency_ms=210)
+
+Every layer is a switch (see :mod:`firewall_sdk.features`). The constructor
+exposes the cloud-relevant ones; pass ``None`` to leave a flag at its
+default/env value, or ``True``/``False`` to force it.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import logging
+import os
+from collections import OrderedDict
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING, Any
+
+from firewall_sdk import features
+from firewall_sdk.cloud_client import CloudClient
+from firewall_sdk.context_summarizer import ConversationState, local_summary
+from firewall_sdk.schemas import CLEAN, ScanResult
+
+if TYPE_CHECKING:
+    import re
+    from collections.abc import Callable
+
+logger = logging.getLogger(__name__)
+
+_USER_HASH_LEN = 16
+_RISK_ENFORCEMENT_MODES = ("off", "restrict", "block")
+# Cap on per-session conversation state held in memory. Oldest sessions are
+# evicted first so a long-running process can't grow this without bound.
+_MAX_SESSIONS = 1000
+
+
+@dataclass
+class CheckResult:
+    """The verdict for a single message.
+
+    ``allowed`` is the inverse of ``blocked``; the object is truthy when it is
+    safe to proceed, so ``if fw.check(msg):`` reads naturally.
+    """
+
+    blocked: bool
+    allowed: bool
+    reason: str | None = None  # threat_type when blocked, else None
+    confidence: float = 0.0
+    intents: list[dict] = field(default_factory=list)
+    continuation: bool = False  # True when this message continued an in-progress task
+    risk_level: str | None = None  # set only when risk_enforcement is on
+    restricted: bool = False  # True when a HIGH-risk user should be limited
+    raw: dict = field(default_factory=dict)
+
+    def __bool__(self) -> bool:
+        return self.allowed
+
+
+def derive_hash(user_id: str | None) -> str | None:
+    """Stable, config-free identity hash for risk tracking.
+
+    Returns ``sha256(user_id)[:16]`` — the same scheme documented in the
+    customer API guide. It needs no shared salt, so the same user maps to the
+    same hash on every server. Pass ``user_hash=`` to :meth:`Firewall.check`
+    if you'd rather supply your own (e.g. a salted HMAC) for irreversibility.
+    """
+    if not user_id:
+        return None
+    return hashlib.sha256(user_id.encode("utf-8")).hexdigest()[:_USER_HASH_LEN]
+
+
+class Firewall:
+    """One object that fronts the AgentHacker backend for an agent."""
+
+    def __init__(
+        self,
+        api_key: str | None = None,
+        *,
+        api_url: str | None = None,
+        http_timeout: float | None = None,
+        agent: str | None = None,
+        agent_intents: list[str] | None = None,
+        risk_enforcement: str = "off",
+        bedrock_system_prompt: str | None = None,
+        # Defaults for the local-checkpoint methods (scan_input/scan_data/
+        # scan_tool_call/scan_output). Each is overridable per call.
+        max_input_length: int = 8000,
+        allowed_tools: set[str] | None = None,
+        id_resolver: "Callable[[str, dict], set[str]] | None" = None,
+        allow_data_urls: bool = False,
+        entity_pattern: "re.Pattern | None" = None,
+        leakage_label: str = "Cross-Entity Data Leakage",
+        # Feature switches — None = leave at default/env, True/False = force.
+        intent_check: bool | None = None,
+        risk_tracking: bool | None = None,
+        multilingual: bool | None = None,
+        input_scan: bool | None = None,
+        data_field_scan: bool | None = None,
+        output_guard: bool | None = None,
+        output_judge: bool | None = None,
+        tool_auth: bool | None = None,
+        audit_log: bool | None = None,
+    ) -> None:
+        key = api_key or os.environ.get("AGENTHACKER_API_KEY")
+        url = api_url or os.environ.get("AGENTHACKER_API_URL")
+        if key:
+            # CloudClient defaults api_url to the production gateway; only
+            # override when we actually have a value (passing None would break
+            # .rstrip()).
+            self._client: CloudClient | None = (
+                CloudClient(key, url, timeout=http_timeout)
+                if url
+                else CloudClient(key, timeout=http_timeout)
+            )
+        else:
+            # Keyless LOCAL mode. The four local checkpoints
+            # (scan_input/scan_data/scan_tool_call/scan_output) run fully
+            # offline; cloud-only features (the Bedrock intent/output judges,
+            # centralized risk scoring, event logging, reports) are disabled and
+            # degrade gracefully. Set AGENTHACKER_API_KEY to enable the cloud tier.
+            self._client = None
+            logger.info(
+                "Firewall running in LOCAL mode (no API key): local checkpoints "
+                "active; cloud judges / risk / events / reports disabled. Set "
+                "AGENTHACKER_API_KEY to enable the cloud tier."
+            )
+
+        self._agent = agent
+        self._agent_intents = list(agent_intents) if agent_intents else None
+        self._bedrock_system_prompt = bedrock_system_prompt
+
+        # Defaults for the local-checkpoint convenience methods.
+        self._max_input_length = max_input_length
+        self._allowed_tools = allowed_tools
+        self._id_resolver = id_resolver
+        self._allow_data_urls = allow_data_urls
+        self._entity_pattern = entity_pattern
+        self._leakage_label = leakage_label
+
+        if risk_enforcement not in _RISK_ENFORCEMENT_MODES:
+            raise ValueError(
+                f"risk_enforcement must be one of {_RISK_ENFORCEMENT_MODES}, "
+                f"got {risk_enforcement!r}"
+            )
+        self._risk_enforcement = risk_enforcement
+
+        # Per-session conversation state for multi-turn continuation. Bounded
+        # (oldest-evicted) so a long-lived process can't leak memory across the
+        # many session_ids it serves. ConversationState never stores raw user
+        # text, so this is safe to retain.
+        self._sessions: "OrderedDict[str, ConversationState]" = OrderedDict()
+        self._active_task: "OrderedDict[str, str]" = OrderedDict()
+
+        # Apply only the flags the caller set explicitly to the shared registry.
+        explicit = {
+            "intent_check": intent_check,
+            "risk_tracking": risk_tracking,
+            "multilingual": multilingual,
+            "input_scan": input_scan,
+            "data_field_scan": data_field_scan,
+            "output_guard": output_guard,
+            "output_judge": output_judge,
+            "tool_auth": tool_auth,
+            "audit_log": audit_log,
+        }
+        overrides = {k: v for k, v in explicit.items() if v is not None}
+        if overrides:
+            features.configure_features(**overrides)
+
+    # ── Core flow ─────────────────────────────────────────────────────
+
+    def check(
+        self,
+        message: str,
+        *,
+        user_id: str | None = None,
+        user_hash: str | None = None,
+        session_id: str = "",
+        agent: str | None = None,
+        agent_intents: list[str] | None = None,
+    ) -> CheckResult:
+        """Run a message through the Bedrock intent judge before your LLM.
+
+        Returns a :class:`CheckResult`. ``check.blocked`` is True for an attack
+        or out-of-scope request; ``check.reason`` is the threat type.
+
+        **Open-ended agents:** leave ``agent_intents`` unset (None). The judge
+        still runs full attack/jailbreak detection; it just doesn't scope the
+        message against a fixed intent list, which would otherwise block
+        legitimate open-ended steps. Declare ``agent_intents`` only for bounded
+        agents with a known menu of actions (e.g. a support bot).
+
+        **Multi-turn:** pass a stable ``session_id`` and the firewall threads the
+        in-progress task + a secure local summary into the judge, so a bare
+        follow-up detail ("June 3rd" while booking) is recognised as a
+        continuation instead of being blocked as out-of-scope. Call
+        :meth:`note_response` after the agent replies to enrich that context.
+        """
+        if not features.is_enabled("intent_check"):
+            return CheckResult(blocked=False, allowed=True, confidence=1.0)
+
+        if self._client is None:
+            # Local mode: no Bedrock judge. Fall back to the deterministic CP-1
+            # input scan (a strict subset, but real protection with no network).
+            return self._local_check(message)
+
+        uhash = user_hash or derive_hash(user_id) or ""
+        intents = agent_intents if agent_intents is not None else self._agent_intents
+
+        # Multi-turn context: what task is in progress and what has been confirmed.
+        active_task = self._active_task.get(session_id) if session_id else None
+        summary = ""
+        if session_id and session_id in self._sessions:
+            summary = local_summary(self._sessions[session_id])
+
+        result = (
+            self._client.classify_intent(
+                message,
+                session_id=session_id,
+                user_hash=uhash,
+                agent=agent or self._agent,
+                agent_intents=intents,
+                system_prompt_suffix=self._bedrock_system_prompt,
+                active_task=active_task,
+                conversation_summary=summary or None,
+            )
+            or {}
+        )
+
+        blocked = result.get("decision") == "block"
+        out = CheckResult(
+            blocked=blocked,
+            allowed=not blocked,
+            reason=(result.get("threat_type") or "policy_violation")
+            if blocked
+            else None,
+            confidence=float(result.get("confidence", 0.0) or 0.0),
+            intents=result.get("intents") or [],
+            continuation=bool(result.get("continuation", False)),
+            raw=result,
+        )
+
+        # Opt-in risk enforcement: also weigh the user's accumulated risk.
+        if not blocked and self._risk_enforcement != "off" and uhash:
+            risk = self._client.get_risk_score(uhash) or {}
+            level = risk.get("level")
+            out.risk_level = level
+            if self._risk_enforcement == "block" and level == "CRITICAL":
+                out.blocked = True
+                out.allowed = False
+                out.reason = "high_risk_user"
+            elif self._risk_enforcement == "restrict" and level in ("HIGH", "CRITICAL"):
+                out.restricted = True
+
+        # Record the accepted action so the NEXT turn has continuation context.
+        if session_id and not out.blocked:
+            self._record_accepted(session_id, out.intents)
+        return out
+
+    def _local_check(self, message: str) -> CheckResult:
+        """Local-mode fallback for :meth:`check` (no backend configured).
+
+        Runs the deterministic CP-1 input scan (regex rules) in place of the
+        Bedrock intent judge. Narrower coverage than the cloud judge, but it
+        still blocks known prompt-injection / jailbreak patterns with no network
+        call. Risk enforcement is skipped (no centralized risk data locally).
+        """
+        result = self.scan_input(message)
+        if result.clean:
+            return CheckResult(blocked=False, allowed=True, confidence=1.0)
+        return CheckResult(
+            blocked=True,
+            allowed=False,
+            reason=result.rule_id or "prompt_injection",
+            confidence=1.0,
+            raw={
+                "source": "local",
+                "rule_id": result.rule_id,
+                "rule_name": result.rule_name,
+                "matched_text": result.matched_text,
+            },
+        )
+
+    # ── Multi-turn session state ──────────────────────────────────────
+
+    def _session_state(self, session_id: str) -> ConversationState:
+        """Get-or-create the bounded ConversationState for a session (LRU)."""
+        state = self._sessions.get(session_id)
+        if state is None:
+            state = ConversationState()
+            self._sessions[session_id] = state
+            while len(self._sessions) > _MAX_SESSIONS:
+                self._sessions.popitem(last=False)
+        else:
+            self._sessions.move_to_end(session_id)
+        return state
+
+    def _record_accepted(self, session_id: str, intents: list[dict]) -> None:
+        """Record the primary in-scope intent as the session's active task."""
+        in_scope = [
+            i.get("text", "")
+            for i in intents
+            if isinstance(i, dict) and i.get("in_scope", True) and i.get("text")
+        ]
+        if not in_scope:
+            return
+        primary = in_scope[0]
+        self._session_state(session_id).record_accepted_intent(primary)
+        self._active_task[session_id] = primary
+        self._active_task.move_to_end(session_id)
+        while len(self._active_task) > _MAX_SESSIONS:
+            self._active_task.popitem(last=False)
+
+    def note_response(
+        self,
+        session_id: str,
+        response_text: str,
+        *,
+        intent_name: str | None = None,
+    ) -> None:
+        """Feed the agent's reply back into session context (no network call).
+
+        Call this after your agent answers an allowed message. The reply (which
+        never contains raw user text) sharpens the local summary passed to the
+        next :meth:`check`, so follow-up details are judged with full context.
+        Optionally pass ``intent_name`` to also set the active task explicitly.
+        """
+        if not session_id or not response_text:
+            return
+        state = self._session_state(session_id)
+        state.record_agent_response(response_text)
+        if intent_name:
+            self._active_task[session_id] = intent_name
+            self._active_task.move_to_end(session_id)
+
+    def clear_session(self, session_id: str) -> None:
+        """Forget a session's conversation state (e.g. on logout / task complete)."""
+        self._sessions.pop(session_id, None)
+        self._active_task.pop(session_id, None)
+
+    def log(
+        self,
+        message: str | None = None,
+        response: str | None = None,
+        *,
+        blocked: bool = False,
+        user_id: str | None = None,
+        user_hash: str | None = None,
+        session_id: str | None = None,
+        agent: str | None = None,
+        checkpoint: str | None = None,
+        rule_id: str | None = None,
+        rule_name: str | None = None,
+        tokens: int = 0,
+        tool_calls: int = 0,
+        latency_ms: float = 0.0,
+    ) -> None:
+        """Record an invocation (fire-and-forget). Powers stats, risk, reports.
+
+        Never blocks or raises — a logging failure must not break your agent.
+        """
+        if not features.is_enabled("audit_log"):
+            return
+
+        agent_name = agent or self._agent
+        # Honor risk_tracking by omitting the identity when it's off — the
+        # backend then won't build a per-user risk profile.
+        uhash = None
+        if features.is_enabled("risk_tracking"):
+            uhash = user_hash or derive_hash(user_id)
+
+        invocation: dict[str, Any] = {
+            "blocked": blocked,
+            "tokens": tokens,
+            "tool_calls": tool_calls,
+            "latency_ms": latency_ms,
+            "agent": agent_name,
+        }
+        if checkpoint:
+            invocation["checkpoint"] = checkpoint
+        if rule_id:
+            invocation["rule_id"] = rule_id
+        if message:
+            invocation["question_preview"] = message[:500]
+
+        batch: dict[str, Any] = {
+            "user_hash": uhash,
+            "agent": agent_name,
+            "invocation": invocation,
+            "firewall_events": [],
+        }
+        if session_id:
+            batch["session_id"] = session_id
+        if blocked:
+            batch["firewall_events"] = [
+                {
+                    "checkpoint": checkpoint,
+                    "rule_id": rule_id,
+                    "rule_name": rule_name,
+                    "excerpt": (message or "")[:100],
+                    "agent": agent_name,
+                }
+            ]
+        if message and agent_name:
+            batch["s3_chat_line"] = {
+                "role": "user",
+                "content": message,
+                "agent": agent_name,
+            }
+        if self._client is not None:  # local mode: nowhere to submit
+            self._client.submit_events(batch)
+
+    # ── Local checkpoints for the agent loop ──────────────────────────
+    #
+    # An agent isn't a request/response chatbot. Wire these at the loop's
+    # chokepoints — no need to import the low-level scan_* functions:
+    #
+    #   think   →  fw.check(goal)   /   fw.scan_input(text)
+    #   act     →  fw.scan_tool_call(name, args)
+    #   ingest  →  fw.scan_data(tool_output, allow_urls=...)
+    #   respond →  fw.scan_output(answer)
+    #
+    # All four run locally (sub-millisecond, no network) and return a
+    # ``ScanResult`` whose ``.clean`` is True when it's safe to proceed.
+
+    def scan_input(
+        self, text: str, *, max_input_length: int | None = None
+    ) -> ScanResult:
+        """CP-1: scan a user message / agent input for injection (the *think* step)."""
+        from firewall_sdk.scan_engine import scan_input as _scan_input
+
+        return _scan_input(
+            text, max_input_length=max_input_length or self._max_input_length
+        )
+
+    def scan_data(self, text: str, *, allow_urls: bool | None = None) -> ScanResult:
+        """CP-2: scan tool output / retrieved data before it re-enters the loop.
+
+        Catches indirect (data-borne) injection and leaked secrets. Set
+        ``allow_urls=True`` (or construct ``Firewall(allow_data_urls=True)``) for
+        a web-browsing agent whose results legitimately contain links.
+        """
+        au = self._allow_data_urls if allow_urls is None else allow_urls
+        from firewall_sdk.scan_engine import scan_data_field as _scan_data_field
+
+        return _scan_data_field(text, allow_urls=au)
+
+    # The *ingest* step reads naturally as "guard this tool output".
+    guard_tool_output = scan_data
+
+    def scan_tool_call(
+        self,
+        name: str,
+        args: dict,
+        *,
+        allowed_ids: set[str] | None = None,
+        allowed_tools: set[str] | None = None,
+        id_resolver: "Callable[[str, dict], set[str]] | None" = None,
+    ) -> ScanResult:
+        """CP-3: authorize a tool call before it runs (the *act* step).
+
+        Uses the constructor's ``allowed_tools`` / ``id_resolver`` unless
+        overridden here. With no allowlist configured anywhere this is a
+        documented no-op (returns CLEAN) — set ``allowed_tools`` to enforce it.
+        """
+        tools = allowed_tools if allowed_tools is not None else self._allowed_tools
+        if tools is None:
+            return CLEAN
+        from firewall_sdk.tool_guard import scan_tool_call as _scan_tool_call
+
+        return _scan_tool_call(
+            name,
+            args,
+            allowed_ids,
+            allowed_tools=tools,
+            id_resolver=id_resolver if id_resolver is not None else self._id_resolver,
+        )
+
+    def scan_output(
+        self,
+        text: str,
+        *,
+        system_prompt: str = "",
+        requester_email: str = "",
+        allowed_ids: set[str] | None = None,
+        all_user_emails: set[str] | None = None,
+        entity_pattern: "re.Pattern | None" = None,
+        leakage_label: str | None = None,
+    ) -> ScanResult:
+        """CP-4: scan the agent's final answer before returning it (the *respond* step).
+
+        Called bare (``fw.scan_output(answer)``) it checks for leaked secrets and
+        offensive content. Supply ``system_prompt`` / entity inputs to also catch
+        system-prompt and cross-entity data leakage.
+        """
+        from firewall_sdk.output_guard import scan_output as _scan_output
+
+        return _scan_output(
+            text,
+            system_prompt=system_prompt,
+            requester_email=requester_email,
+            allowed_ids=allowed_ids,
+            all_user_emails=all_user_emails,
+            entity_pattern=entity_pattern
+            if entity_pattern is not None
+            else self._entity_pattern,
+            leakage_label=leakage_label
+            if leakage_label is not None
+            else self._leakage_label,
+        )
+
+    def check_output(
+        self,
+        text: str,
+        *,
+        user_request: str = "",
+        persona: str = "",
+        user_id: str | None = None,
+        user_hash: str | None = None,
+        session_id: str = "",
+        agent: str | None = None,
+        agent_intents: list[str] | None = None,
+        # Inputs forwarded to the deterministic regex scan_output (CP-4):
+        system_prompt: str = "",
+        requester_email: str = "",
+        allowed_ids: set[str] | None = None,
+        all_user_emails: set[str] | None = None,
+        entity_pattern: "re.Pattern | None" = None,
+        leakage_label: str | None = None,
+    ) -> ScanResult:
+        """CP-4 (full): deterministic regex scan FIRST, then the Bedrock output judge.
+
+        The cheap, deterministic ``scan_output`` runs first (leaked secrets,
+        system-prompt shingle overlap, cross-entity leakage, slurs). If it flags
+        anything, that verdict is returned immediately — no model call. Otherwise,
+        when the ``output_judge`` feature is on, the Bedrock judge inspects the
+        output for *clear* prompt-injection success (refusal-suppression, persona
+        break, intent-deviation, tool-abuse, data-exfiltration) and blocks on a
+        high-confidence signal. Fail-open: a backend error leaves the
+        already-passed regex verdict in place.
+
+        Pass ``system_prompt`` (the verbatim prompt) for the regex S-01 leak check,
+        and ``persona`` (a short non-secret description) for the judge's
+        persona-break detection — the verbatim prompt is deliberately NOT sent to
+        the judge. Pass ``user_request`` so the judge can spot intent-deviation.
+        """
+        local = self.scan_output(
+            text,
+            system_prompt=system_prompt,
+            requester_email=requester_email,
+            allowed_ids=allowed_ids,
+            all_user_emails=all_user_emails,
+            entity_pattern=entity_pattern,
+            leakage_label=leakage_label,
+        )
+        if not local.clean:
+            return local
+        if not features.is_enabled("output_judge"):
+            return local
+        if self._client is None:
+            return local  # local mode: regex verdict only, no judge
+
+        uhash = user_hash or derive_hash(user_id) or ""
+        intents = agent_intents if agent_intents is not None else self._agent_intents
+        verdict = (
+            self._client.classify_output(
+                text,
+                session_id=session_id,
+                user_hash=uhash,
+                agent=agent or self._agent,
+                user_request=user_request or None,
+                system_prompt=persona
+                or None,  # redacted persona, never the verbatim prompt
+                agent_intents=intents,
+            )
+            or {}
+        )
+        if verdict.get("decision") == "block":
+            signal = verdict.get("signal") or "injection"
+            reasoning = verdict.get("reasoning") or ""
+            return ScanResult(
+                clean=False,
+                rule_id="BEDROCK_OUTPUT",
+                rule_name=f"Bedrock Output Judge: {signal}",
+                matched_text=(reasoning or signal)[:100],
+            )
+        return CLEAN
+
+    # ── Startup check ─────────────────────────────────────────────────
+
+    def preflight(self, *, raise_on_error: bool = False) -> dict:
+        """Verify the API key + URL at startup so misconfiguration is caught early.
+
+        Cloud calls fail open, so a bad key/URL is otherwise invisible: the agent
+        looks protected while nothing is checked. Call this once at startup.
+
+        Returns ``{"ok", "status", "url", "detail"}``. By default it logs a loud
+        warning on failure and returns (so a transient blip doesn't crash boot);
+        pass ``raise_on_error=True`` to hard-fail startup on an auth/config error.
+
+        In local mode (no API key) there is nothing to verify, so this reports
+        ``{"ok": True, "status": "local"}``.
+        """
+        if self._client is None:
+            return {
+                "ok": True,
+                "status": "local",
+                "url": None,
+                "detail": "local mode (no API key): cloud checks disabled, "
+                "local checkpoints active",
+            }
+        result = self._client.preflight()
+        if not result.get("ok"):
+            msg = (
+                f"AgentHacker preflight failed (status={result.get('status')}, "
+                f"url={result.get('url')}): {result.get('detail')}. The firewall will "
+                f"FAIL OPEN — verify AGENTHACKER_API_KEY / AGENTHACKER_API_URL."
+            )
+            if raise_on_error:
+                raise RuntimeError(msg)
+            logger.warning(msg)
+        return result
+
+    # ── Convenience reads ─────────────────────────────────────────────
+
+    def risk(
+        self, user_id: str | None = None, *, user_hash: str | None = None
+    ) -> dict | None:
+        """Return a user's current risk score dict, or None (None in local mode)."""
+        if self._client is None:
+            return None
+        uhash = user_hash or derive_hash(user_id)
+        if not uhash:
+            return None
+        return self._client.get_risk_score(uhash)
+
+    def report(self, date_range: str = "30d", agent: str | None = None) -> dict | None:
+        """Generate a security audit report (HTML + JSON). See CloudClient.generate_report.
+
+        Returns None in local mode (no backend).
+        """
+        if self._client is None:
+            return None
+        return self._client.generate_report(
+            date_range=date_range, agent=agent or self._agent
+        )
+
+
+__all__ = ["Firewall", "CheckResult", "derive_hash"]