scamgate 0.3.3__py3-none-any.whl

scamgate/config.py

@@ -0,0 +1,62 @@
+"""Load rules config (weights, thresholds, word lists) and the local blocklist."""
+
+from __future__ import annotations
+
+import os
+from functools import lru_cache
+from importlib import resources
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+ENV_CONFIG = "SCAMGATE_CONFIG"
+ENV_BLOCKLIST = "SCAMGATE_BLOCKLIST"
+
+
+def _default_config_text() -> str:
+    return resources.files(__package__).joinpath("config/rules.yaml").read_text("utf-8")
+
+
+@lru_cache(maxsize=8)
+def load_config(path: str | None = None) -> dict[str, Any]:
+    path = path or os.environ.get(ENV_CONFIG)
+    text = Path(path).read_text("utf-8") if path else _default_config_text()
+    return yaml.safe_load(text)
+
+
+def _blocklist_candidates() -> list[Path]:
+    out: list[Path] = []
+    if env := os.environ.get(ENV_BLOCKLIST):
+        out.append(Path(env))
+    # Bundled example list, inside the package (wheel, source checkout and Hermes plugin alike)
+    out.append(Path(__file__).resolve().parent / "data" / "blocklist.txt")
+    return out
+
+
+def _parse_domains(text: str) -> set[str]:
+    domains = set()
+    for line in text.splitlines():
+        line = line.split("#", 1)[0].strip().lower().rstrip(".")
+        if line:
+            domains.add(line)
+    return domains
+
+
+@lru_cache(maxsize=8)
+def load_blocklist(path: str | None = None) -> frozenset[str]:
+    domains: set[str] = set()
+    candidates = [Path(path)] if path else _blocklist_candidates()
+    for p in candidates:
+        if p.is_file():
+            domains |= _parse_domains(p.read_text("utf-8"))
+            break
+    return frozenset(domains)
+
+
+def rule_cfg(config: dict[str, Any], rule_id: str) -> dict[str, Any]:
+    return config.get("rules", {}).get(rule_id, {}) or {}
+
+
+def lst(config: dict[str, Any], name: str) -> Any:
+    return config.get("lists", {}).get(name, [])

scamgate/data/blocklist.txt

@@ -0,0 +1,9 @@
+# scamgate local blocklist: one domain per line, '#' for comments.
+# A listed domain also blocks its subdomains.
+# These are made-up EXAMPLE entries on the reserved .example TLD, for tests and demos.
+# Pull real community feeds into data/feeds/ with scripts/fetch_feeds.py (not bundled).
+free-iphone-giveaway.example
+revolut-unlock-account.example
+aib-secure-verify.example
+crypto-doubler.example
+parcel-redelivery-fee.example

scamgate/domainage.py

@@ -0,0 +1,153 @@
+"""Domain age from RDAP, for `url.domain_age`. Off by default; opt in with SCAMGATE_RDAP.
+
+New domains are a strong scam-shop signal, but looking one up means asking the domain's registry,
+which tells the registry which site you're about to visit. So it's your call:
+
+- `SCAMGATE_RDAP=off` (default): no lookups, the rule never fires.
+- `SCAMGATE_RDAP=cache`: use ages already in the cache (from `scamgate domain-age HOST` or an
+  earlier live lookup); never go online.
+- `SCAMGATE_RDAP=live`: look up unknown domains (3 s timeout) and cache the result.
+
+The registry list comes from IANA's RDAP bootstrap file (data.iana.org/rdap/dns.json), cached for
+30 days. Ages are cached for a year; failed or unknown lookups for 7 days, so a domain that won't
+answer doesn't slow every call. Any error means "no answer", never a verdict.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import re
+from datetime import datetime, timedelta, timezone
+from pathlib import Path
+from typing import Callable
+
+ENV_RDAP = "SCAMGATE_RDAP"
+_HOSTNAME = re.compile(r"^(?=.{1,253}$)[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?(?:\.[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?)+$")
+BOOTSTRAP_URL = "https://data.iana.org/rdap/dns.json"
+TIMEOUT_S = 3
+BOOTSTRAP_TTL = timedelta(days=30)
+KNOWN_TTL = timedelta(days=365)
+UNKNOWN_TTL = timedelta(days=7)
+
+
+def mode() -> str:
+    m = (os.environ.get(ENV_RDAP) or "off").strip().lower()
+    return m if m in ("off", "cache", "live") else "off"
+
+
+def _cache_path() -> Path:
+    from .feeds import cache_dir
+
+    return cache_dir() / "rdap.json"
+
+
+def _now() -> datetime:
+    return datetime.now(timezone.utc)
+
+
+def _load() -> dict:
+    try:
+        data = json.loads(_cache_path().read_text("utf-8"))
+        return data if isinstance(data, dict) else {}
+    except (OSError, ValueError):
+        return {}
+
+
+def _save(data: dict) -> None:
+    p = _cache_path()
+    try:
+        p.parent.mkdir(parents=True, exist_ok=True)
+        tmp = p.with_suffix(".json.tmp")
+        tmp.write_text(json.dumps(data, indent=1, sort_keys=True), "utf-8")
+        tmp.replace(p)
+    except OSError:
+        pass  # a read-only cache just means no caching
+
+
+def _http_get(url: str) -> str:
+    import urllib.request
+
+    from .feeds import USER_AGENT
+
+    req = urllib.request.Request(url, headers={"User-Agent": USER_AGENT, "Accept": "application/rdap+json"})
+    with urllib.request.urlopen(req, timeout=TIMEOUT_S) as resp:  # noqa: S310
+        return resp.read(2_000_000).decode("utf-8", "replace")
+
+
+def _parse_ts(s: str) -> datetime | None:
+    try:
+        d = datetime.fromisoformat(s.replace("Z", "+00:00"))
+        return d if d.tzinfo else d.replace(tzinfo=timezone.utc)
+    except (TypeError, ValueError):
+        return None
+
+
+def _rdap_base(tld: str, data: dict, fetch: Callable[[str], str]) -> str | None:
+    boot = data.get("_bootstrap") or {}
+    fetched = _parse_ts(boot.get("fetched_at", ""))
+    if not boot.get("services") or not fetched or _now() - fetched > BOOTSTRAP_TTL:
+        try:
+            services = json.loads(fetch(BOOTSTRAP_URL)).get("services", [])
+            boot = {"fetched_at": _now().isoformat(timespec="seconds"), "services": services}
+            data["_bootstrap"] = boot
+        except Exception:
+            if not boot.get("services"):
+                return None
+    for tlds, urls in boot.get("services", []):
+        if tld in tlds and urls:
+            https = [u for u in urls if u.startswith("https://")]
+            return (https or urls)[0].rstrip("/") + "/"
+    return None
+
+
+def registration_date(rdap_json: str) -> datetime | None:
+    try:
+        doc = json.loads(rdap_json)
+    except ValueError:
+        return None
+    for ev in doc.get("events", []) if isinstance(doc, dict) else []:
+        if isinstance(ev, dict) and ev.get("eventAction") == "registration":
+            return _parse_ts(ev.get("eventDate", ""))
+    return None
+
+
+def lookup(domain: str, *, live: bool | None = None, fetch: Callable[[str], str] | None = None) -> int | None:
+    """Age of `domain` in days, or None if unknown. `live` overrides SCAMGATE_RDAP."""
+    domain = (domain or "").strip().lower().rstrip(".")
+    if not domain.isascii():
+        try:
+            ascii_name = domain.encode("idna").decode("ascii")  # registries take the xn-- form
+            if ascii_name.encode("ascii").decode("idna") != domain:
+                return None  # Python's IDNA 2003 rules would ask about another name ('faß' -> 'fass')
+        except UnicodeError:
+            return None
+        domain = ascii_name
+    if not _HOSTNAME.match(domain):
+        return None  # only a plain host name goes into the registry URL
+    m = mode()
+    allow_net = m == "live" if live is None else live
+    if m == "off" and live is None:
+        return None
+    data = _load()
+    hit = data.get(domain)
+    if isinstance(hit, dict):
+        checked = _parse_ts(hit.get("checked_at", ""))
+        created = _parse_ts(hit.get("created") or "")
+        ttl = KNOWN_TTL if created else UNKNOWN_TTL
+        if checked and _now() - checked < ttl:
+            return (_now() - created).days if created else None
+    if not allow_net:
+        return None
+    fetch = fetch or _http_get
+    created = None
+    base = _rdap_base(domain.rsplit(".", 1)[1], data, fetch)
+    if base:
+        try:
+            created = registration_date(fetch(base + "domain/" + domain))
+        except Exception:
+            created = None
+    data[domain] = {"created": created.isoformat(timespec="seconds") if created else None,
+                    "checked_at": _now().isoformat(timespec="seconds")}
+    _save(data)
+    return (_now() - created).days if created else None

scamgate/engine.py

@@ -0,0 +1,145 @@
+"""Run registered rules and turn hits into a verdict."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from . import feeds as feeds_mod
+from . import overrides as overrides_mod
+from . import payees as payees_mod
+from .config import load_blocklist, load_config, rule_cfg
+from .models import Decision, PaymentCheck, Reason, UrlCheck, Verdict
+from .registry import Hit, Kind, RuleContext, rules_for
+
+
+def _apply_overrides(url: str, reasons: list[Reason], items: list[dict], warnings: list[str]) -> list[Reason]:
+    from .rules.url import parse
+
+    host = parse(url).host
+    if not host:
+        return reasons
+    if o := overrides_mod.deny_match(host, items):
+        reasons.append(Reason(rule_id="url.override", weight=100,
+                              explanation=f"You added a deny rule for {o['host']} on {o['added_at'][:10]}."))
+    waived = overrides_mod.waived_rules(host, items)
+    kept = [r for r in reasons if r.rule_id not in waived]
+    if len(kept) != len(reasons):
+        names = sorted({r.rule_id for r in reasons} & waived)
+        warnings.append(f"Your allow rule for {host} waived: {', '.join(names)}.")
+    return kept
+
+
+def _run(kind: Kind, check: Any, config: dict[str, Any] | None,
+         blocklist: frozenset[str] | None, feeds: Any = None,
+         extra_warnings: list[str] | None = None) -> Verdict:
+    config = config or load_config()
+    blocklist = load_blocklist() if blocklist is None else blocklist
+    warnings: list[str] = []
+    if kind == "url":
+        feeds = feeds_mod.current_index() if feeds is None else feeds
+        if not feeds:
+            warnings.append("No known-bad-link feeds are cached. " + feeds_mod.REFRESH_HINT)
+        elif stale := feeds.stale_feeds():
+            warnings.append(f"Feed cache older than {feeds_mod.STALE_AFTER_HOURS}h for: "
+                            f"{', '.join(sorted(stale))}. " + feeds_mod.REFRESH_HINT)
+    unreadable, checked_host = False, None
+    if kind == "url":
+        from .rules.url import parse
+
+        parsed = parse(check.url)
+        # Nothing else can judge a link scamgate can't read, and its text must not reach a reason.
+        unreadable = bool(parsed.unreadable)
+        checked_host = parsed.host or None
+    reasons: list[Reason] = []
+    for rule in rules_for(kind):
+        if unreadable and rule.rule_id != "url.unreadable":
+            continue
+        rc = rule_cfg(config, rule.rule_id)
+        if not rc.get("enabled", False):
+            continue
+        out = rule.fn(check, RuleContext(config=config, rule_config=rc, blocklist=blocklist, feeds=feeds))
+        hits: list[Hit] = [] if out is None else (out if isinstance(out, list) else [out])
+        for h in hits:
+            w = h.weight if h.weight is not None else int(rc.get("weight", 0))
+            if w <= 0:
+                continue
+            reasons.append(Reason(rule_id=rule.rule_id, explanation=h.explanation, weight=min(w, 100)))
+
+    if kind == "url":
+        items, bad = overrides_mod.load_checked()
+        if bad:
+            warnings.append(f"{bad} of your scamgate override rules can't be verified (its signing key is missing or "
+                            "was changed, or the line was edited by hand), so they're ignored. Check the scamgate "
+                            "state dir.")
+        if items and not unreadable:
+            reasons = _apply_overrides(check.url, reasons, items, warnings)
+    warnings += extra_warnings or []
+
+    reasons.sort(key=lambda r: r.weight, reverse=True)
+    score = min(100, sum(r.weight for r in reasons))
+    th = config.get("thresholds", {})
+    if score >= int(th.get("deny", 70)):
+        decision = Decision.deny
+    elif score >= int(th.get("ask", 25)):
+        decision = Decision.ask
+    else:
+        decision = Decision.allow
+    return Verdict(decision=decision, risk_score=score, reasons=reasons,
+                   summary=_summary(kind, decision, reasons), checked_host=checked_host, warnings=warnings)
+
+
+def _summary(kind: Kind, decision: Decision, reasons: list[Reason]) -> str:
+    thing = "link" if kind == "url" else "payment"
+    if decision is Decision.allow and not reasons:
+        return f"No scam signals found for this {thing}."
+    top = reasons[0].explanation if reasons else ""
+    if decision is Decision.allow:
+        return f"Low risk {thing}, but note: {top}"
+    if decision is Decision.ask:
+        return f"Check with the human before this {thing}. Main concern: {top}"
+    return f"Do not proceed with this {thing}. Main concern: {top}"
+
+
+def check_url(url: str, intent: str | None = None, *, config: dict[str, Any] | None = None,
+              blocklist: frozenset[str] | None = None, feeds: Any = None) -> Verdict:
+    """feeds: a FeedIndex; defaults to the local cache (pass FeedIndex() for none)."""
+    return _run("url", UrlCheck(url=url, intent=intent), config, blocklist, feeds)
+
+
+def check_payment(check: PaymentCheck, *, config: dict[str, Any] | None = None,
+                  use_history: bool = True) -> Verdict:
+    """Payee facts come from local history (`scamgate record-payment`), not the agent's claims."""
+    warnings: list[str] = []
+    if use_history:
+        check, warnings = _with_history(check)
+    return _run("payment", check, config, frozenset(), extra_warnings=warnings)
+
+
+def _with_history(check: PaymentCheck) -> tuple[PaymentCheck, list[str]]:
+    facts = payees_mod.lookup(check.payee_name, check.payee_account)
+    warnings: list[str] = []
+    claimed_known = False
+    if facts.history_broken:
+        new, changed = True, True
+        warnings.append("Your payee history can't be verified (its key or salt is missing or was changed), so "
+                        "every payee is treated as new with changed details. Check the scamgate state dir.")
+    elif facts.known_account:
+        new, changed = False, bool(check.bank_details_changed)
+    elif facts.name_seen_with_other_account:
+        new, changed = False, True
+        warnings.append(f"You've paid '{check.payee_name}' before, but never to this account.")
+    elif facts.near_name:
+        new, changed = True, True
+        warnings.append(f"'{check.payee_name}' looks like a payee you've paid before, but this name and account "
+                        "are new. Lookalike payee names are a common invoice-redirection trick.")
+    else:
+        new, changed = True, bool(check.bank_details_changed)
+        if check.is_new_payee is False:
+            claimed_known = True
+            warnings.append(f"The agent said '{check.payee_name}' is a known payee, but you've never paid them "
+                            "from here (no record). Treating them as new.")
+    if facts.account_under_other_name:
+        changed = True
+        warnings.append("You've paid this account before under a different name. Confirm who really owns it.")
+    upd = {"is_new_payee": new, "bank_details_changed": changed, "agent_claim_unbacked": claimed_known}
+    return check.model_copy(update=upd), warnings

scamgate/entry.py

@@ -0,0 +1,19 @@
+"""The `scamgate` console script.
+
+`scamgate hook` runs once per agent tool call (the Claude Code plugin calls `uvx scamgate==X hook`), so it
+skips the typer/rich command line and goes straight to the hook. Every other command loads the full CLI.
+"""
+
+from __future__ import annotations
+
+import sys
+
+
+def main() -> None:
+    if sys.argv[1:] == ["hook"]:
+        from .hook import main as run_hook
+
+        sys.exit(run_hook())
+    from .cli import app
+
+    app()