scamgate 0.3.3__py3-none-any.whl

scamgate/hook_entry.py

@@ -0,0 +1,15 @@
+"""Fast entry point for the enforcement hook (skips typer/rich startup).
+
+`scamgate-hook` runs once per tool call, so startup time matters. `scamgate hook` does the
+same thing through the full CLI.
+"""
+
+from __future__ import annotations
+
+import sys
+
+
+def main() -> None:
+    from .hook import main as run
+
+    sys.exit(run())

scamgate/hostnorm.py

@@ -0,0 +1,60 @@
+"""Host normalisation shared by the rules and the feed lookups.
+
+Browsers and curl accept hosts that look nothing like the domain they reach:
+percent-encoded letters (`evilsh%6fp.com`), integer IPv4 (`3405803781`), hex or octal parts
+(`0xcb007105`, `0313.0.0.1`). Normalise them so every check sees the real destination.
+"""
+
+from __future__ import annotations
+
+import ipaddress
+import re
+import unicodedata
+from urllib.parse import unquote
+
+_NUM_PART = re.compile(r"^(?:0x[0-9a-f]+|0[0-7]*|[1-9][0-9]*)$", re.I)
+
+
+def _num(part: str) -> int:
+    p = part.lower()
+    if p.startswith("0x"):
+        return int(p, 16)
+    if len(p) > 1 and p.startswith("0"):
+        return int(p, 8)
+    return int(p)
+
+
+def numeric_ipv4(host: str) -> str | None:
+    """'3405803781', '0xcb007105', '0313.0.0.1', '203.0x0.113.5' -> dotted quad, else None.
+
+    Follows inet_aton: 1-4 parts, the last part fills the remaining bytes.
+    """
+    h = host.strip("[]").rstrip(".")
+    parts = h.split(".")
+    if not 1 <= len(parts) <= 4 or not all(_NUM_PART.match(p) for p in parts):
+        return None
+    try:
+        nums = [_num(p) for p in parts]
+    except ValueError:
+        return None
+    *head, last = nums
+    if any(n > 255 for n in head) or last >= 256 ** (4 - len(head)):
+        return None
+    value = 0
+    for n in head:
+        value = value * 256 + n
+    value = value * 256 ** (4 - len(head)) + last
+    return str(ipaddress.IPv4Address(value))
+
+
+# Ideographic and halfwidth full stops: browsers read them as '.' in a host name.
+_DOTS = str.maketrans({"。": ".", "．": ".", "｡": "."})
+
+
+def canon_host(host: str) -> str:
+    """Lowercase, percent-decoded, no trailing dot, numeric IPv4 in dotted form."""
+    h = unicodedata.normalize("NFKC", unquote(host or "")).translate(_DOTS).strip().lower().rstrip(".")
+    if h and not h.startswith("["):
+        if (ip := numeric_ipv4(h)) is not None and h != ip:
+            return ip
+    return h

scamgate/integrity.py

@@ -0,0 +1,85 @@
+"""Check that the installed scamgate code hasn't been modified.
+
+A wheel install has a RECORD file with a SHA-256 for every file. The hook verifies scamgate's
+own Python and config files against it at startup and fails closed if anything changed.
+An editable/dev install (source checkout) has nothing to verify against, so it reports "dev"
+and passes: run the hook from a pinned install (`uv tool install`) to get this protection.
+"""
+
+from __future__ import annotations
+
+import base64
+import hashlib
+from importlib import metadata
+from pathlib import Path
+
+
+def _digest(path: Path) -> str:
+    return base64.urlsafe_b64encode(hashlib.sha256(path.read_bytes()).digest()).rstrip(b"=").decode()
+
+
+def verify(entries: list[tuple[Path, str, str]]) -> tuple[bool, str]:
+    problems = []
+    for path, algo, expected in entries:
+        if algo != "sha256":
+            continue
+        if not path.is_file():
+            problems.append(f"missing: {path.name}")
+        elif _digest(path) != expected:
+            problems.append(f"modified: {path.name}")
+    if problems:
+        return False, "; ".join(problems[:5])
+    return True, f"{len(entries)} files verified"
+
+
+def _is_editable(dist: metadata.Distribution) -> bool:
+    import json
+
+    try:
+        direct = json.loads(dist.read_text("direct_url.json") or "{}")
+    except (FileNotFoundError, json.JSONDecodeError):
+        return False
+    return bool((direct.get("dir_info") or {}).get("editable"))
+
+
+_KNOWN_PTH = {"distutils-precedence.pth", "_virtualenv.pth"}
+
+
+def unexpected_pth(dirs: list[Path]) -> list[str]:
+    """.pth files no installed package owns. Python runs `import` lines in them at every start."""
+    out = []
+    for d in dirs:
+        d = Path(d)
+        if not d.is_dir():
+            continue
+        owned = set()
+        for rec in d.glob("*.dist-info/RECORD"):
+            for line in rec.read_text("utf-8", errors="replace").splitlines():
+                name = line.split(",", 1)[0].replace("\\", "/")
+                if name.endswith(".pth") and "/" not in name:
+                    owned.add(name)
+        for p in sorted(d.glob("*.pth")):
+            if p.name not in owned and p.name not in _KNOWN_PTH and not p.name.startswith("__editable__"):
+                out.append(p.name)
+    return out
+
+
+def check() -> tuple[bool, str]:
+    try:
+        dist = metadata.distribution("scamgate")
+    except metadata.PackageNotFoundError:
+        return True, "dev (not installed as a package)"
+    if _is_editable(dist):
+        return True, "dev (editable install, nothing to verify)"
+    entries = []
+    for f in dist.files or []:
+        s = str(f).replace("\\", "/")
+        if not s.startswith("scamgate/") or not f.hash or not s.endswith((".py", ".yaml", ".txt")):
+            continue
+        entries.append((Path(f.locate()), f.hash.mode, f.hash.value))
+    if not entries:
+        return True, "dev (no RECORD hashes)"
+    ok, why = verify(entries)
+    if ok and (extra := unexpected_pth([Path(dist.locate_file(""))])):
+        return False, f"unknown startup file(s) next to scamgate: {', '.join(extra[:3])}"
+    return ok, why

scamgate/models.py

@@ -0,0 +1,77 @@
+"""Shared input and verdict models."""
+
+from __future__ import annotations
+
+from enum import Enum
+
+from pydantic import BaseModel, Field
+
+
+class Decision(str, Enum):
+    allow = "allow"
+    ask = "ask"  # stop and ask the human
+    deny = "deny"
+
+
+class PaymentMethod(str, Enum):
+    card = "card"
+    bank_transfer = "bank_transfer"
+    crypto = "crypto"
+    gift_card = "gift_card"
+    other = "other"
+
+
+class VopResult(str, Enum):
+    """Verification of Payee (name vs account) result, if the caller has one."""
+
+    match = "match"
+    close_match = "close_match"
+    no_match = "no_match"
+    unavailable = "unavailable"
+
+
+class Reason(BaseModel):
+    rule_id: str
+    explanation: str = Field(description="Plain-English reason a human can read")
+    weight: int = Field(ge=0, le=100)
+
+
+class Verdict(BaseModel):
+    decision: Decision
+    risk_score: int = Field(ge=0, le=100)
+    reasons: list[Reason] = Field(default_factory=list)
+    summary: str
+    checked_host: str | None = Field(
+        default=None,
+        description="For links: the host scamgate judged, the one a browser would open. If it isn't where you "
+                    "expected the link to go, treat that as a warning. Empty for payments and unreadable links.",
+    )
+    warnings: list[str] = Field(default_factory=list, description="Notes about the check itself, e.g. a stale feed cache")
+    advisory: str = (
+        "scamgate is advisory. It can miss scams and flag legitimate actions; "
+        "a human should make the final call on anything flagged."
+    )
+
+
+class UrlCheck(BaseModel):
+    url: str
+    intent: str | None = None
+
+
+class PaymentCheck(BaseModel):
+    payee_name: str
+    payee_account: str = Field(description="IBAN, wallet address, card merchant id, etc.")
+    amount: float = Field(ge=0, allow_inf_nan=False)
+    currency: str
+    method: PaymentMethod
+    context_text: str | None = Field(
+        default=None, description="Messages or page text that led to this payment"
+    )
+    is_new_payee: bool | None = None
+    agent_claim_unbacked: bool = Field(
+        default=False, exclude=True,
+        description="Set by scamgate, not the caller: the agent called a payee known with no record of it",
+    )
+    bank_details_changed: bool | None = None
+    budget: float | None = Field(default=None, ge=0, allow_inf_nan=False)
+    vop_result: VopResult | None = None

scamgate/overrides.py

@@ -0,0 +1,90 @@
+"""Human-approved overrides, promoted from the ask log with `scamgate promote`.
+
+Rules for overrides, so the gate can't be trained by an attacker:
+- Only a person can add them: `add()` refuses agent environments and non-interactive callers,
+  whether it's called from the CLI or imported directly.
+- Every line is signed (see guard.py). Lines written any other way are ignored.
+- `deny` covers an exact host and its subdomains.
+- `allow` is narrow: one exact host (no subdomains) AND one named rule. It waives only that rule's
+  points for that host. It never waives known-bad feeds, the blocklist, intent checks or your own deny.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+from datetime import datetime, timezone
+from pathlib import Path
+
+from . import guard
+from .state import state_dir
+
+NEVER_WAIVED = {"url.known_bad_feed", "url.blocklist", "url.override", "url.intent_mismatch"}
+_HOST = re.compile(r"^(?=.{1,253}$)([a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\.)+[a-z0-9-]{2,63}$")
+_interactive = guard._interactive
+
+
+def overrides_path() -> Path:
+    return state_dir() / "overrides.jsonl"
+
+
+def _check_host(host: str) -> str:
+    h = (host or "").strip().lower().rstrip(".")
+    if not _HOST.match(h):
+        raise ValueError(f"not an exact host name: {host!r} (no wildcards, schemes or paths)")
+    return h
+
+
+def add(host: str, decision: str, *, rule: str | None = None, note: str = "") -> dict:
+    h = _check_host(host)
+    if decision not in ("allow", "deny"):
+        raise ValueError("decision must be 'allow' or 'deny'")
+    if decision == "allow" and not rule:
+        raise ValueError("an allow override needs --rule: it waives one rule on one host")
+    if decision == "allow" and rule in NEVER_WAIVED:
+        raise ValueError(f"{rule} can't be waived: known-bad lists, your blocklist and intent checks always apply")
+    guard.require_human("Adding a scamgate override", interactive=lambda: _interactive())
+    rec = guard.sign({"host": h, "decision": decision, "rule": rule if decision == "allow" else None,
+                      "note": note[:200], "added_by": "human-cli",
+                      "added_at": datetime.now(timezone.utc).isoformat(timespec="seconds")})
+    guard.append_private(overrides_path(), json.dumps(rec))
+    return rec
+
+
+def load() -> list[dict]:
+    return load_checked()[0]
+
+
+def load_checked() -> tuple[list[dict], int]:
+    """(rules that verify, number of lines that don't). A missing or changed key fails every line,
+    and the engine says so rather than dropping your rules silently."""
+    p = overrides_path()
+    if not p.exists():
+        return [], 0
+    out, bad = [], 0
+    for line in p.read_text("utf-8").splitlines():
+        if not line.strip():
+            continue
+        try:
+            rec = json.loads(line)
+        except json.JSONDecodeError:
+            bad += 1
+            continue
+        if (isinstance(rec, dict) and rec.get("host") and rec.get("decision") in ("allow", "deny")
+                and guard.verify(rec)):
+            out.append(rec)
+        else:
+            bad += 1
+    return out, bad
+
+
+def deny_match(host: str, items: list[dict]) -> dict | None:
+    for o in items:
+        if o["decision"] == "deny" and (host == o["host"] or host.endswith("." + o["host"])):
+            return o
+    return None
+
+
+def waived_rules(host: str, items: list[dict]) -> set[str]:
+    return {o["rule"] for o in items
+            if o["decision"] == "allow" and o.get("rule") and host == o["host"]} - NEVER_WAIVED

scamgate/payees.py

@@ -0,0 +1,141 @@
+"""Local payee history, so payment checks don't rely on what the agent claims.
+
+Stores salted hashes of the normalized payee name and account, never the values, plus hashes of
+one-letter-deletion variants of the name's first word, so near-names ("Acme Trading Ltd",
+"Acmee Ltd", Cyrillic "Acmе") still match a payee you've paid before without storing the name.
+Only a person can add a payee (`scamgate record-payment`), and every line is signed.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import re
+import secrets
+import unicodedata
+from dataclasses import dataclass
+from datetime import datetime, timezone
+from pathlib import Path
+
+from . import guard
+from .state import state_dir
+
+_SUFFIXES = r"\b(ltd|limited|llc|inc|plc|gmbh|teoranta|dac|co|company|the|and|of)\b"
+_GENERIC = {"bank", "the", "mr", "mrs", "ms", "dr", "st", "saint", "group", "services", "payments", "account"}
+# Letters that look Latin in most fonts.
+_CONFUSABLE = str.maketrans({
+    "а": "a", "е": "e", "о": "o", "р": "p", "с": "c", "у": "y", "х": "x", "і": "i", "ј": "j", "ѕ": "s",
+    "ԁ": "d", "ɡ": "g", "һ": "h", "ӏ": "l", "ο": "o", "α": "a", "ε": "e", "ι": "i", "κ": "k", "ν": "v",
+    "ρ": "p", "τ": "t", "υ": "u", "χ": "x", "ϲ": "c", "0": "o", "1": "l",
+})
+_interactive = guard._interactive
+
+
+def history_path() -> Path:
+    return state_dir() / "payees.jsonl"
+
+
+def _salt_path() -> Path:
+    return state_dir() / "payees.salt"
+
+
+def _salt(create: bool = False) -> bytes | None:
+    p = _salt_path()
+    if not p.exists():
+        if not create:
+            return None
+        guard.create_once(p, secrets.token_hex(16))
+    return p.read_text("utf-8").strip().encode()
+
+
+def _fold(name: str) -> str:
+    n = unicodedata.normalize("NFKC", name or "").lower().translate(_CONFUSABLE)
+    n = "".join(c for c in unicodedata.normalize("NFKD", n) if not unicodedata.combining(c))
+    return re.sub(_SUFFIXES, " ", n)
+
+
+def norm_name(name: str) -> str:
+    return re.sub(r"[^a-z0-9]", "", _fold(name))
+
+
+def core_word(name: str) -> str:
+    words = [w for w in re.split(r"[^a-z0-9]+", _fold(name)) if len(w) >= 3 and w not in _GENERIC]
+    return words[0] if words else norm_name(name)
+
+
+def _variants(word: str) -> set[str]:
+    return {word} | {word[:i] + word[i + 1:] for i in range(len(word))} if len(word) >= 4 else {word}
+
+
+def _salt_id(salt: bytes) -> str:
+    return hashlib.sha256(b"scamgate-salt-id\0" + salt).hexdigest()[:16]
+
+
+def norm_account(account: str) -> str:
+    return re.sub(r"[^A-Z0-9]", "", (account or "").upper())
+
+
+def _h(kind: str, value: str, salt: bytes | None = None) -> str:
+    s = salt if salt is not None else (_salt() or b"")
+    return hashlib.sha256(s + kind.encode() + b"\0" + value.encode()).hexdigest()[:32]
+
+
+@dataclass
+class PayeeFacts:
+    has_history: bool
+    known_name: bool
+    known_account: bool
+    name_seen_with_other_account: bool
+    near_name: bool = False
+    account_under_other_name: bool = False
+    history_broken: bool = False
+
+
+def _rows() -> list[dict]:
+    p = history_path()
+    if not p.exists():
+        return []
+    out = []
+    for line in p.read_text("utf-8").splitlines():
+        try:
+            rec = json.loads(line)
+        except json.JSONDecodeError:
+            continue
+        if isinstance(rec, dict) and guard.verify(rec):
+            out.append(rec)
+    return out
+
+
+def lookup(name: str, account: str) -> PayeeFacts:
+    p = history_path()
+    if p.exists() and p.stat().st_size and (_salt() is None or not guard.key_exists()):
+        return PayeeFacts(True, False, False, False, history_broken=True)
+    rows = _rows()
+    if not rows:
+        return PayeeFacts(False, False, False, False)
+    sid = _salt_id(_salt() or b"")
+    if any(r.get("salt_id") not in (None, sid) for r in rows):
+        return PayeeFacts(True, False, False, False, history_broken=True)
+    nh, ah = _h("name", norm_name(name)), _h("acct", norm_account(account))
+    near = {_h("core", v) for v in _variants(core_word(name))}
+    exact_name = [r for r in rows if r.get("name") == nh]
+    near_name = [r for r in rows if r.get("name") != nh and near & set(r.get("core") or [])]
+    same_acct = [r for r in rows if r.get("account") == ah]
+    known_account = any(r in exact_name or r in near_name for r in same_acct)
+    return PayeeFacts(
+        has_history=True,
+        known_name=bool(exact_name),
+        known_account=known_account,
+        name_seen_with_other_account=bool(exact_name) and not known_account,
+        near_name=bool(near_name) and not exact_name and not known_account,
+        account_under_other_name=bool(same_acct) and not known_account,
+    )
+
+
+def record(name: str, account: str) -> None:
+    guard.require_human("Recording a payee", interactive=lambda: _interactive())
+    salt = _salt(create=True)
+    rec = guard.sign({"v": 2, "salt_id": _salt_id(salt), "name": _h("name", norm_name(name), salt), "account": _h("acct", norm_account(account), salt),
+                      "core": sorted(_h("core", v, salt) for v in _variants(core_word(name))),
+                      "ts": datetime.now(timezone.utc).isoformat(timespec="seconds")})
+    guard.append_private(history_path(), json.dumps(rec))