frisk-screen 0.0.1__py3-none-any.whl

frisk/__init__.py

@@ -0,0 +1,22 @@
+"""Pre-transaction risk screening for autonomous AI agents."""
+
+from .client import Client, ScreenError
+from .types import (
+    Confidence,
+    Policy,
+    ScreenRequest,
+    ScreenResult,
+    Verdict,
+)
+
+__all__ = [
+    "Client",
+    "ScreenError",
+    "Confidence",
+    "Policy",
+    "ScreenRequest",
+    "ScreenResult",
+    "Verdict",
+]
+
+__version__ = "0.0.1"

frisk/client.py

@@ -0,0 +1,134 @@
+"""Client entry point for screening agent transactions."""
+
+from __future__ import annotations
+
+import json
+import urllib.error
+import urllib.request
+from typing import Optional
+from urllib.parse import urlparse
+
+from .lite import evaluate_lite
+from .types import Confidence, Policy, ScreenRequest, ScreenResult, Verdict
+
+DEFAULT_BASE_URL = "https://api.tryfrisk.dev"
+
+
+class ScreenError(RuntimeError):
+    """Raised when a hosted screening request cannot be completed."""
+
+
+def _normalize_base_url(raw: str) -> str:
+    """Validate and normalize a base URL.
+
+    HTTPS is required so the API key in the Authorization header is never sent
+    in plaintext; http is allowed only for localhost to support local
+    development and tests.
+    """
+    trimmed = raw.rstrip("/")
+    parsed = urlparse(trimmed)
+    is_localhost = parsed.hostname in ("localhost", "127.0.0.1", "::1")
+    if parsed.scheme == "https" or (parsed.scheme == "http" and is_localhost):
+        return trimmed
+    raise ValueError("base_url must use HTTPS (http is allowed only for localhost)")
+
+
+class Client:
+    """Screen agent transactions before they execute.
+
+    Without an API key the client runs in offline ``lite`` mode. Supply an
+    API key to use the hosted service, which adds reputation-graph, model,
+    and threat-feed signals and returns higher-confidence verdicts.
+
+    Example::
+
+        client = Client()  # lite mode
+        result = client.screen("0xabc...", amount=2.5, asset="USDC")
+        if not result.allowed:
+            ...  # hold the payment for review
+    """
+
+    def __init__(
+        self,
+        api_key: Optional[str] = None,
+        *,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: float = 5.0,
+    ) -> None:
+        self._api_key = api_key
+        self._base_url = _normalize_base_url(base_url)
+        self._timeout = timeout
+
+    @property
+    def mode(self) -> str:
+        return "hosted" if self._api_key else "lite"
+
+    def screen(
+        self,
+        counterparty: str,
+        *,
+        endpoint: Optional[str] = None,
+        amount: Optional[float] = None,
+        asset: Optional[str] = None,
+        policy: Optional[Policy] = None,
+        observed_pay_to: Optional[str] = None,
+        strictness: Optional[float] = None,
+    ) -> ScreenResult:
+        request = ScreenRequest(
+            counterparty=counterparty,
+            endpoint=endpoint,
+            amount=amount,
+            asset=asset,
+            policy=policy,
+            observed_pay_to=observed_pay_to,
+            strictness=strictness,
+        )
+        if self._api_key:
+            return self._screen_hosted(request)
+        return evaluate_lite(request)
+
+    def _screen_hosted(self, request: ScreenRequest) -> ScreenResult:
+        payload = {
+            "counterparty": request.counterparty,
+            "endpoint": request.endpoint,
+            "amount": request.amount,
+            "asset": request.asset,
+            "observed_pay_to": request.observed_pay_to,
+            "strictness": request.strictness,
+        }
+        if request.policy is not None:
+            payload["policy"] = {
+                "max_per_call": request.policy.max_per_call,
+                "allowed_assets": request.policy.allowed_assets,
+            }
+
+        http_request = urllib.request.Request(
+            f"{self._base_url}/v1/screen",
+            data=json.dumps(payload).encode("utf-8"),
+            headers={
+                "Content-Type": "application/json",
+                "Authorization": f"Bearer {self._api_key}",
+            },
+            method="POST",
+        )
+        try:
+            with urllib.request.urlopen(
+                http_request, timeout=self._timeout
+            ) as response:
+                data = json.loads(response.read().decode("utf-8"))
+        except urllib.error.HTTPError as exc:
+            raise ScreenError(f"hosted screening failed: HTTP {exc.code}") from exc
+        except urllib.error.URLError as exc:
+            raise ScreenError(f"hosted screening unreachable: {exc.reason}") from exc
+        return _result_from_payload(data)
+
+
+def _result_from_payload(data: dict) -> ScreenResult:
+    return ScreenResult(
+        verdict=Verdict(data["verdict"]),
+        trust_score=int(data["trust_score"]),
+        confidence=Confidence(data.get("confidence", "low")),
+        reasons=list(data.get("reasons", [])),
+        policy_hits=list(data.get("policy_hits", [])),
+        source="hosted",
+    )

frisk/data/README.md

@@ -0,0 +1,9 @@
+# Seed blocklist
+
+`blocklist_seed.json` is a small, offline subset of known-bad counterparties
+shipped with the package so that lite mode can flag the most obvious cases
+without a network call.
+
+It is **not** the authoritative list. The live, continuously updated
+blocklist and reputation data are served by the hosted API. Entries here are
+only added when independently verifiable from public sources.

frisk/data/blocklist_seed.json

@@ -0,0 +1 @@
+[]

frisk/lite.py

@@ -0,0 +1,115 @@
+"""Offline ("lite") screening.
+
+The lite engine runs entirely on the caller's machine using only public,
+locally available signals. It is intentionally weaker than the hosted
+service and always reports LOW confidence: it has no reputation history, no
+threat feed, and no trained models. Supply an API key to :class:`Client` to
+use the hosted service for graph-, model-, and threat-feed-backed verdicts.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+from typing import Iterable, List, Optional, Set
+
+from .types import Confidence, ScreenRequest, ScreenResult, Verdict
+
+_SEED_BLOCKLIST_PATH = os.path.join(
+    os.path.dirname(__file__), "data", "blocklist_seed.json"
+)
+
+_BASELINE_SCORE = 70  # lite cannot see reputation history, so it starts neutral
+
+
+def _load_seed_blocklist() -> Set[str]:
+    try:
+        with open(_SEED_BLOCKLIST_PATH, "r", encoding="utf-8") as handle:
+            return {str(entry).lower() for entry in json.load(handle)}
+    except (OSError, ValueError):
+        return set()
+
+
+_SEED_BLOCKLIST = _load_seed_blocklist()
+
+
+def evaluate_lite(
+    request: ScreenRequest,
+    blocklist: Optional[Iterable[str]] = None,
+) -> ScreenResult:
+    """Score a request using offline signals only."""
+    block = (
+        _SEED_BLOCKLIST
+        if blocklist is None
+        else {str(entry).lower() for entry in blocklist}
+    )
+
+    score = _BASELINE_SCORE
+    reasons: List[str] = []
+    counterparty = (request.counterparty or "").lower()
+
+    # 1. Seed blocklist. The live, continuously updated list is hosted-only.
+    if counterparty in block:
+        score = 0
+        reasons.append("counterparty on local seed blocklist")
+
+    # 2. Address sanity.
+    if not _looks_like_address(counterparty):
+        score -= 15
+        reasons.append("counterparty is not a well-formed address")
+
+    # 3. Dynamic payTo swap (a documented x402 attack vector).
+    if request.observed_pay_to and request.observed_pay_to.lower() != counterparty:
+        score -= 30
+        reasons.append("payTo differs from the expected counterparty")
+
+    # 4. Insecure endpoint.
+    if request.endpoint and not request.endpoint.lower().startswith("https://"):
+        score -= 20
+        reasons.append("endpoint is not served over HTTPS")
+
+    # 5. Spending policy (deterministic, fully offline).
+    policy_hits = _check_policy(request)
+    if policy_hits:
+        score -= 25
+
+    score = max(0, min(100, score))
+    return ScreenResult(
+        verdict=_verdict_for(score, policy_hits),
+        trust_score=score,
+        confidence=Confidence.LOW,
+        reasons=reasons,
+        policy_hits=policy_hits,
+        source="lite",
+    )
+
+
+def _check_policy(request: ScreenRequest) -> List[str]:
+    hits: List[str] = []
+    policy = request.policy
+    if policy is None:
+        return hits
+    if policy.max_per_call is not None and request.amount is not None:
+        if request.amount > policy.max_per_call:
+            hits.append(
+                f"amount {request.amount} exceeds max_per_call {policy.max_per_call}"
+            )
+    if policy.allowed_assets is not None and request.asset is not None:
+        if request.asset not in policy.allowed_assets:
+            hits.append(f"asset {request.asset} not in allowed_assets")
+    return hits
+
+
+def _verdict_for(score: int, policy_hits: List[str]) -> Verdict:
+    if score < 20:
+        return Verdict.BLOCK
+    if policy_hits or score < 65:
+        return Verdict.REVIEW
+    return Verdict.ALLOW
+
+
+def _looks_like_address(value: str) -> bool:
+    if value.startswith("0x") and len(value) == 42:
+        return all(character in "0123456789abcdef" for character in value[2:])
+    # Non-EVM identifiers (e.g. Solana base58) — length heuristic only.
+    return 32 <= len(value) <= 60

frisk/types.py

@@ -0,0 +1,67 @@
+"""Core data types for the screening SDK."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import List, Optional
+
+
+class Verdict(str, Enum):
+    """Recommended action for a screened transaction."""
+
+    ALLOW = "allow"
+    REVIEW = "review"
+    BLOCK = "block"
+
+
+class Confidence(str, Enum):
+    """How much weight to place on the verdict.
+
+    Offline (lite) screening always reports ``LOW``; the hosted service
+    raises confidence as graph, model, and threat-feed coverage improve.
+    """
+
+    LOW = "low"
+    MEDIUM = "medium"
+    HIGH = "high"
+
+
+@dataclass(frozen=True)
+class Policy:
+    """Caller-supplied spending policy. Every field is optional."""
+
+    max_per_call: Optional[float] = None
+    allowed_assets: Optional[List[str]] = None
+
+
+@dataclass(frozen=True)
+class ScreenRequest:
+    """A transaction an agent is about to perform."""
+
+    counterparty: str
+    endpoint: Optional[str] = None
+    amount: Optional[float] = None
+    asset: Optional[str] = None
+    policy: Optional[Policy] = None
+    # The payTo address the endpoint actually returned this request, if
+    # observed. Used to detect dynamic-payTo swaps.
+    observed_pay_to: Optional[str] = None
+    # Screening "temperature" in [0, 1]: 0 = permissive, 1 = paranoid. Default 0.3.
+    strictness: Optional[float] = None
+
+
+@dataclass(frozen=True)
+class ScreenResult:
+    """The outcome of screening a transaction."""
+
+    verdict: Verdict
+    trust_score: int  # 0-100
+    confidence: Confidence
+    reasons: List[str] = field(default_factory=list)
+    policy_hits: List[str] = field(default_factory=list)
+    source: str = "lite"  # "lite" | "hosted"
+
+    @property
+    def allowed(self) -> bool:
+        return self.verdict is Verdict.ALLOW

frisk_screen-0.0.1.dist-info/METADATA

@@ -0,0 +1,114 @@
+Metadata-Version: 2.4
+Name: frisk-screen
+Version: 0.0.1
+Summary: Pre-transaction risk screening for autonomous AI agents.
+Project-URL: Homepage, https://github.com/Jiangw2718i/frisk
+Project-URL: Source, https://github.com/Jiangw2718i/frisk
+Author: Frisk contributors
+License: MIT License
+        
+        Copyright (c) 2026 Frisk contributors
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+License-File: LICENSE
+Keywords: agent-payments,ai-agents,mcp,risk,trust,x402
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Security
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
+# Frisk
+
+Pre-transaction risk screening for autonomous AI agents.
+
+Before your agent pays an x402 seller or calls an unfamiliar tool, ask Frisk
+whether the counterparty is trustworthy and whether the transaction fits your
+policy. Frisk returns a verdict — `allow`, `review`, or `block` — with a
+trust score and human-readable reasons. It is advisory: your agent stays in
+control of the decision.
+
+## Install
+
+```bash
+pip install frisk-screen
+```
+
+## Usage
+
+```python
+from frisk import Client, Policy
+
+client = Client()  # lite mode, no key required
+
+result = client.screen(
+    "0x9a3f1b2c3d4e5f60718293a4b5c6d7e8f9a0bc12",
+    endpoint="https://api.seller.x402/quote",
+    amount=2.50,
+    asset="USDC",
+    policy=Policy(max_per_call=5.00),
+)
+
+if not result.allowed:
+    print(result.verdict, result.trust_score, result.reasons)
+    # hold the payment for review
+```
+
+## Lite mode vs. hosted
+
+| | Lite (default) | Hosted (API key) |
+| --- | --- | --- |
+| Runs | Locally, offline | Frisk API |
+| Signals | Public, structural checks only | Reputation graph, trained models, live threat feed |
+| Confidence | Always `low` | Rises with coverage |
+| Cost | Free | Usage-based |
+
+Lite mode catches obvious problems — malformed counterparties, `payTo` swaps,
+insecure endpoints, policy violations, and a small seed blocklist. For
+reputation history and continuously updated threat intelligence, pass an API
+key:
+
+```python
+client = Client(api_key="...")
+```
+
+## Design
+
+- **Zero runtime dependencies.** The SDK uses only the standard library.
+- **Advisory, not in-path.** Frisk never holds your funds or blocks a
+  payment itself; it returns a verdict and your code decides.
+- **Typed.** Ships with type hints (`py.typed`).
+
+## Development
+
+This project uses [uv](https://docs.astral.sh/uv/).
+
+```bash
+uv sync
+uv run pytest
+```
+
+## License
+
+MIT — see [LICENSE](LICENSE). Security disclosures: see [SECURITY.md](SECURITY.md).

frisk_screen-0.0.1.dist-info/RECORD

@@ -0,0 +1,11 @@
+frisk/__init__.py,sha256=1nUC7qJnx94kgNtIZBo5pjRRlKQYQPoNPGptLCxr2vk,364
+frisk/client.py,sha256=OGKIn1FbZeIh7agcLckJ1hY09PAjur72gejC58neaGg,4452
+frisk/lite.py,sha256=bxzBUHu8xaSvk5ETtLqaI4tc3ZToe6jirm7g3BB53t8,3755
+frisk/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+frisk/types.py,sha256=fT7mRimOafZsNMVyGDTGh4tjHF-vcVxFYdG3vA_aJJA,1787
+frisk/data/README.md,sha256=4s0nzKA6G9sSilxCodUIJdQ4MnL37lvPPbFsrnW5y3s,403
+frisk/data/blocklist_seed.json,sha256=N1F-Xz3GaBn2H1p7uKzhkhKCQV8QVR0t76XD6wmFtXA,3
+frisk_screen-0.0.1.dist-info/METADATA,sha256=-X3A26kF4ScWqAHXx-XZxWLtrUrslqymQe1EjFG32b0,3954
+frisk_screen-0.0.1.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+frisk_screen-0.0.1.dist-info/licenses/LICENSE,sha256=2te30sP0itpLLXhFtzNRs-9KbkBhgNuQsw_oW2R-Dvc,1075
+frisk_screen-0.0.1.dist-info/RECORD,,

frisk_screen-0.0.1.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.30.1
+Root-Is-Purelib: true
+Tag: py3-none-any

frisk_screen-0.0.1.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Frisk contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.