exposurecheck 0.1.0__py3-none-any.whl

exposurecheck/__init__.py

@@ -0,0 +1,11 @@
+"""exposurecheck — audit your own social-media export for re-identification risk.
+
+Local-first. No-dossier. Bring-your-own-LLM (cloud BYOK or local).
+
+This package never phones home, never scrapes, and never writes a synthesized
+profile of you to disk. It shows you, by category, what a *mosaic* re-identification
+attack could reconstruct from the public history you already published — and points
+you back at your own posts so you can edit or generalize them.
+"""
+
+__version__ = "0.1.0"

exposurecheck/__main__.py

@@ -0,0 +1,4 @@
+from .cli import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())

exposurecheck/audit.py

@@ -0,0 +1,44 @@
+"""Top-level orchestration: parsed exports + a backend -> AuditResult."""
+
+from __future__ import annotations
+
+from typing import Callable, Optional
+
+from .backends.base import Backend
+from .cascade import run_cascade
+from .models import AuditResult, Export
+from .risk import build_cards
+
+
+def run_audit(
+    exports: list[Export],
+    backend: Backend,
+    *,
+    candidate_fraction: float = 1.0,
+    max_candidates: Optional[int] = None,
+    batch_size: int = 10,
+    progress: Optional[Callable[[int, int], None]] = None,
+) -> AuditResult:
+    outcome = run_cascade(
+        exports, backend,
+        candidate_fraction=candidate_fraction,
+        max_candidates=max_candidates,
+        batch_size=batch_size,
+        progress=progress,
+    )
+    cards = build_cards(outcome.findings)
+    return AuditResult(
+        cards=cards,
+        findings=outcome.findings,
+        backend_name=backend.name,
+        post_count=outcome.post_count,
+        candidate_count=outcome.candidate_count,
+        platforms=[ex.platform for ex in exports],
+        meta={
+            "dropped": outcome.dropped_count,
+            "kept": outcome.kept_count,
+            "not_analyzed": outcome.not_analyzed_count,
+            "raw": outcome.raw_count,
+            "media_count": sum(len(ex.media) for ex in exports),
+        },
+    )

exposurecheck/backends/__init__.py

@@ -0,0 +1,57 @@
+"""Pluggable inference backends and a small factory.
+
+  heuristic  - offline regex stub (no key, low recall — dev/CI/demo only)
+  cloud      - OpenAI-compatible endpoint, bring-your-own-key (sends data offsite)
+  local      - local Ollama server (no network egress)
+"""
+
+from __future__ import annotations
+
+from typing import Optional
+
+from .base import Backend, RawInference
+from .heuristic import HeuristicBackend
+from .llm import LLMBackend
+from .transports import CloudTransport, LocalTransport, TransportError
+
+__all__ = [
+    "Backend", "RawInference", "HeuristicBackend", "LLMBackend",
+    "CloudTransport", "LocalTransport", "TransportError", "build_backend",
+]
+
+
+def build_backend(
+    kind: str,
+    *,
+    api_key: Optional[str] = None,
+    base_url: Optional[str] = None,
+    cheap_model: Optional[str] = None,
+    expensive_model: Optional[str] = None,
+    timeout: Optional[float] = None,
+) -> Backend:
+    kind = (kind or "heuristic").lower()
+    if kind == "heuristic":
+        return HeuristicBackend()
+    if kind == "cloud":
+        transport = CloudTransport(
+            api_key or "",
+            base_url=base_url or "https://api.openai.com/v1",
+            timeout=timeout or 60.0,
+        )
+        return LLMBackend(
+            transport,
+            cheap_model=cheap_model or "gpt-4o-mini",
+            expensive_model=expensive_model or "gpt-4o",
+        )
+    if kind == "local":
+        transport = LocalTransport(
+            base_url=base_url or "http://localhost:11434",
+            timeout=timeout or 120.0,
+        )
+        model = expensive_model or cheap_model or "llama3.1"
+        return LLMBackend(
+            transport,
+            cheap_model=cheap_model or model,
+            expensive_model=model,
+        )
+    raise ValueError(f"unknown backend: {kind!r} (use heuristic|cloud|local)")

exposurecheck/backends/_mask.py

@@ -0,0 +1,18 @@
+"""Mechanical masked-snippet generation.
+
+The masked snippet shown in a risk card is ALWAYS generated here from post
+metadata (evidence label + where + when) — never from model free-text. This
+guarantees the no-dossier invariant holds regardless of what an LLM returns:
+the resolved value can only ever appear when the user clicks through to their
+OWN original post.
+"""
+
+from __future__ import annotations
+
+from ..models import Post
+
+
+def masked_reference(post: Post, evidence_type: str) -> str:
+    when = post.created_at.date().isoformat() if post.created_at else "?"
+    where = f"r/{post.community}" if post.community else post.platform.value
+    return f"[{evidence_type}] | {where} | {when}"

exposurecheck/backends/base.py

@@ -0,0 +1,52 @@
+"""Backend contract for the leak-inference cascade.
+
+A backend answers two questions about the user's OWN posts:
+
+  route(posts)   -> a 0..1 priority per post (cheap tier). Lower priority never
+                    means "dropped" — it only means "analyze later / sample less".
+  extract(batch) -> structured leak inferences for a small batch (expensive tier).
+
+Backends never return resolved personal values: an inference carries a category,
+a confidence, a MASKED snippet and a reference back to the user's own post.
+"""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from dataclasses import dataclass
+from typing import Optional
+
+from ..models import Confidence, Platform, Post, RiskCategory, Source
+
+
+@dataclass
+class RawInference:
+    """One leak signal, pre-aggregation. Holds a reference + masked text only."""
+    category: RiskCategory
+    confidence: Confidence
+    masked_snippet: str
+    evidence_type: str
+    source: Source = Source.TEXT
+    post_id: Optional[str] = None
+    permalink: Optional[str] = None
+    platform: Optional[Platform] = None   # namespaces post_id across mixed exports
+    rationale: str = ""
+
+
+class Backend(ABC):
+    name: str = "base"
+    is_local: bool = False
+    #: True if running this backend sends the user's posts off their machine.
+    #: Drives the conditional cloud-deanonymization warning.
+    sends_data_offsite: bool = False
+
+    @abstractmethod
+    def route(self, posts: list[Post]) -> list[float]:
+        ...
+
+    @abstractmethod
+    def extract(self, batch: list[Post]) -> list[RawInference]:
+        ...
+
+    def describe(self) -> str:
+        return self.name

exposurecheck/backends/heuristic.py

@@ -0,0 +1,102 @@
+"""Deterministic, offline, dependency-free stub backend.
+
+PURPOSE: let the whole pipeline run end-to-end with no API key and no model, for
+development, tests and CI. It uses keyword/regex matching only.
+
+IMPORTANT — this is NOT real protection. Regex/keyword matching has near-zero
+recall against the actual mosaic threat: the danger is an LLM *reasoning* across
+many weak, individually-innocuous posts, which keywords cannot reproduce. Treat
+heuristic output as a smoke test of the plumbing, never as an audit. The CLI
+prints a loud warning when this backend is selected.
+"""
+
+from __future__ import annotations
+
+import re
+
+from ..models import Confidence, Post, RiskCategory, Source
+from .base import Backend, RawInference
+from ._mask import masked_reference
+
+# (category, evidence_type label, pattern, confidence)
+_LEXICON: list[tuple[RiskCategory, str, re.Pattern, Confidence]] = [
+    (RiskCategory.LOCATION, "location clue",
+     re.compile(r"\b(live|lives|living|moved|move|near|downtown|neighbou?rhood|commute|"
+                r"ferry|station|light-rail|marina|reservoir|uptown|my (block|street))\b", re.I),
+     Confidence.LOW),
+    (RiskCategory.EMPLOYER, "employer mention",
+     re.compile(r"\b(my (company|team|employer|office|boss)|at the startup|we hire|we're hiring|"
+                r"i work (at|for)|as an? (sre|engineer|developer|manager|analyst))\b", re.I),
+     Confidence.MEDIUM),
+    (RiskCategory.SCHEDULE, "routine / timing clue",
+     re.compile(r"\b(\d{1,2}(:\d{2})?\s?(am|pm)|every (weekday|morning|day)|on-call|"
+                r"before work|after work|my (morning|commute) routine)\b", re.I),
+     Confidence.LOW),
+    (RiskCategory.FAMILY, "family reference",
+     re.compile(r"\b(my (daughter|son|kid|kids|child|children|wife|husband|partner|mom|dad)|"
+                r"kindergarten|elementary school|drop-off)\b", re.I),
+     Confidence.MEDIUM),
+    (RiskCategory.FINANCE, "financial disclosure",
+     re.compile(r"\b(\d+(\.\d+)?\s?btc|bitcoin|stacking|cold storage|my (portfolio|salary|income)|"
+                r"net worth|i hold|i own \d)\b", re.I),
+     Confidence.LOW),
+    (RiskCategory.AGE_DOB, "age / DOB clue",
+     re.compile(r"\b(i'?m \d{2}\b|born in (19|20)\d{2}|turned \d{2}|my birthday|\bm\d{2}\b|\bf\d{2}\b)",
+                re.I),
+     Confidence.MEDIUM),
+    (RiskCategory.IDENTITY_LINK, "cross-account / identity clue",
+     re.compile(r"\b(my real name|same (handle|username)|my (other|main) account|on my (blog|site)|"
+                r"my personal (site|website))\b", re.I),
+     Confidence.MEDIUM),
+]
+
+
+def scan_text(text: str) -> list[tuple[RiskCategory, str, Confidence]]:
+    """Run the keyword lexicon over a piece of text. Shared by the heuristic
+    backend (post bodies) and the deterministic layer (profile bio)."""
+    hits = []
+    for category, label, pat, conf in _LEXICON:
+        if pat.search(text or ""):
+            hits.append((category, label, conf))
+    return hits
+
+
+class HeuristicBackend(Backend):
+    name = "heuristic"
+    is_local = True
+    sends_data_offsite = False
+
+    def route(self, posts: list[Post]) -> list[float]:
+        scores = []
+        for p in posts:
+            s = 0.1
+            text = p.text or ""
+            if any(pat.search(text) for _c, _l, pat, _conf in _LEXICON):
+                s += 0.4
+            if p.urls:
+                s += 0.15
+            if p.mentions:
+                s += 0.1
+            if any(m.exif and m.exif.has_location() for m in p.media):
+                s += 0.5
+            scores.append(min(s, 1.0))
+        return scores
+
+    def extract(self, batch: list[Post]) -> list[RawInference]:
+        out: list[RawInference] = []
+        for p in batch:
+            text = p.text or ""
+            for category, label, pat, conf in _LEXICON:
+                if pat.search(text):
+                    out.append(RawInference(
+                        category=category,
+                        confidence=conf,
+                        masked_snippet=masked_reference(p, label),
+                        evidence_type=label,
+                        source=Source.TEXT,
+                        post_id=p.post_id,
+                        permalink=p.permalink,
+                        platform=p.platform,
+                        rationale=f"{label} detected by keyword match (low-recall stub).",
+                    ))
+        return out

exposurecheck/backends/llm.py

@@ -0,0 +1,205 @@
+"""LLM-driven backend: the real mosaic-inference engine.
+
+Wraps a Transport (cloud or local). The model only ever decides *which* post
+leaks *which* category, at what confidence — it is never asked for, and never
+trusted to produce, the masked snippet or rationale (we generate those). That
+keeps the no-dossier guarantee independent of model behaviour.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+from typing import Optional
+
+from ..models import Confidence, Post, RiskCategory, Source
+from .base import Backend, RawInference
+from ._mask import masked_reference
+from .transports import Transport
+
+_CATS = [c.value for c in RiskCategory]
+_CAT_BY_VALUE = {c.value: c for c in RiskCategory}
+
+# Generic, developer-controlled evidence labels. The model is NEVER trusted to
+# supply display text: it only chooses category/confidence/post_id, and the label
+# shown on the card and inside the masked snippet is looked up here. This keeps
+# the no-dossier guarantee independent of model behaviour (a model that tries to
+# smuggle a resolved value into `evidence_type` cannot reach the output surface).
+_LLM_EVIDENCE_LABEL: dict[RiskCategory, str] = {
+    RiskCategory.LOCATION: "location signal",
+    RiskCategory.EMPLOYER: "employer signal",
+    RiskCategory.EDUCATION: "education signal",
+    RiskCategory.FAMILY: "family signal",
+    RiskCategory.AGE_DOB: "age / DOB signal",
+    RiskCategory.HEALTH: "health signal",
+    RiskCategory.FINANCE: "financial signal",
+    RiskCategory.REAL_NAME: "real-name signal",
+    RiskCategory.SCHEDULE: "routine / timing signal",
+    RiskCategory.RELATIONSHIPS: "relationship signal",
+    RiskCategory.POLITICS_RELIGION: "affiliation signal",
+    RiskCategory.IDENTITY_LINK: "account-linkage signal",
+}
+_CAT_ALIASES = {
+    "dob": RiskCategory.AGE_DOB, "age": RiskCategory.AGE_DOB,
+    "job": RiskCategory.EMPLOYER, "work": RiskCategory.EMPLOYER, "company": RiskCategory.EMPLOYER,
+    "name": RiskCategory.REAL_NAME, "identity": RiskCategory.REAL_NAME,
+    "link": RiskCategory.IDENTITY_LINK, "account": RiskCategory.IDENTITY_LINK,
+    "money": RiskCategory.FINANCE, "financial": RiskCategory.FINANCE,
+    "politics": RiskCategory.POLITICS_RELIGION, "religion": RiskCategory.POLITICS_RELIGION,
+    "home": RiskCategory.LOCATION, "address": RiskCategory.LOCATION, "city": RiskCategory.LOCATION,
+    "school": RiskCategory.EDUCATION,
+}
+
+_ROUTE_SYS = (
+    "You rank a user's OWN social-media posts by how much identifying personal "
+    "information they could leak when AGGREGATED with the rest (location, employer, "
+    "family, schedule, finances, identity links, etc.). Output strict JSON only: an "
+    'array of {"i": <index int>, "s": <float 0..1>}. Higher s = more identifying '
+    "signal. Include every index given. Short or weak posts can still score moderate; "
+    "only truly empty or boilerplate posts score near 0."
+)
+
+_EXTRACT_SYS = (
+    "You are a privacy auditor helping a user reduce their OWN re-identification risk. "
+    "You see only the user's own posts. Acting as a careful adversary, decide which "
+    "posts leak which categories of personal information when aggregated across the "
+    "whole history, including weak individually-innocuous signals.\n"
+    "Output STRICT JSON only: an array of objects "
+    '{"post_id": str, "category": one of ' + json.dumps(_CATS) + ', '
+    '"confidence": "low"|"medium"|"high"}.\n'
+    "HARD RULES:\n"
+    "- Do NOT output any resolved value (no real city, neighbourhood, street, employer "
+    "name, person name, handle, exact age, or coordinates). Return only the structured "
+    "fields above; the tool generates all displayed text itself.\n"
+    "- Only use post_id values that appear in the input.\n"
+    "- One object per (post, category) you find. Omit posts that leak nothing."
+)
+
+
+class LLMBackend(Backend):
+    def __init__(self, transport: Transport, *, cheap_model: str, expensive_model: str,
+                 route_chunk: int = 25, name: Optional[str] = None):
+        self.transport = transport
+        self.cheap_model = cheap_model
+        self.expensive_model = expensive_model
+        self.route_chunk = route_chunk
+        self.name = name or f"llm:{transport.name}"
+        self.is_local = transport.is_local
+        self.sends_data_offsite = transport.sends_data_offsite
+
+    # -- cheap tier -------------------------------------------------------- #
+    def route(self, posts: list[Post]) -> list[float]:
+        scores = [0.3] * len(posts)  # recall-preserving default: nothing starts at 0
+        for start in range(0, len(posts), self.route_chunk):
+            chunk = posts[start:start + self.route_chunk]
+            payload = [{"i": i, "t": (p.text or "")[:280]} for i, p in enumerate(chunk)]
+            try:
+                raw = self.transport.complete(
+                    _ROUTE_SYS, json.dumps(payload), self.cheap_model,
+                    max_tokens=400, temperature=0.0)
+            except Exception:
+                continue  # keep defaults for this chunk on transport failure
+            for obj in _loads_array(raw):
+                try:
+                    i = int(obj["i"])
+                    s = float(obj["s"])
+                except (KeyError, TypeError, ValueError):
+                    continue
+                if 0 <= i < len(chunk):
+                    scores[start + i] = max(0.0, min(1.0, s))
+        return scores
+
+    # -- expensive tier ---------------------------------------------------- #
+    def extract(self, batch: list[Post]) -> list[RawInference]:
+        by_id = {p.post_id: p for p in batch}
+        payload = [{
+            "post_id": p.post_id,
+            "community": p.community or "",
+            "date": p.created_at.date().isoformat() if p.created_at else "",
+            "text": (p.text or "")[:600],
+        } for p in batch]
+        try:
+            raw = self.transport.complete(
+                _EXTRACT_SYS, json.dumps(payload), self.expensive_model,
+                max_tokens=900, temperature=0.0)
+        except Exception:
+            return []
+
+        out: list[RawInference] = []
+        for obj in _loads_array(raw):
+            if not isinstance(obj, dict):
+                continue
+            cat = _to_category(obj.get("category"))
+            pid = obj.get("post_id")
+            post = by_id.get(pid)
+            if cat is None or post is None:
+                continue  # ignore hallucinated ids / unknown categories
+            # label is mechanical (never the model's free text) — see _LLM_EVIDENCE_LABEL
+            label = _LLM_EVIDENCE_LABEL.get(cat, "personal signal")
+            out.append(RawInference(
+                category=cat,
+                confidence=_to_conf(obj.get("confidence")),
+                masked_snippet=masked_reference(post, label),   # we generate it
+                evidence_type=label,
+                source=Source.TEXT,
+                post_id=post.post_id,
+                permalink=post.permalink,
+                platform=post.platform,
+            ))
+        return out
+
+
+# --------------------------------------------------------------------------- #
+#  parsing helpers
+# --------------------------------------------------------------------------- #
+
+def _strip_fences(s: str) -> str:
+    s = s.strip()
+    if s.startswith("```"):
+        s = re.sub(r"^```[a-zA-Z0-9]*\s*", "", s)
+        s = re.sub(r"\s*```$", "", s)
+    return s.strip()
+
+
+def _loads_array(text: str) -> list:
+    text = _strip_fences(text or "")
+    try:
+        v = json.loads(text)
+        if isinstance(v, list):
+            return v
+        if isinstance(v, dict):
+            for k in ("inferences", "results", "items", "data"):
+                if isinstance(v.get(k), list):
+                    return v[k]
+    except json.JSONDecodeError:
+        pass
+    i, j = text.find("["), text.rfind("]")
+    if 0 <= i < j:
+        try:
+            v = json.loads(text[i:j + 1])
+            return v if isinstance(v, list) else []
+        except json.JSONDecodeError:
+            return []
+    return []
+
+
+def _to_category(s) -> Optional[RiskCategory]:
+    if not s:
+        return None
+    key = str(s).strip().lower().replace(" ", "_").replace("/", "_").replace("-", "_")
+    if key in _CAT_BY_VALUE:
+        return _CAT_BY_VALUE[key]
+    # whole-token match so "accountant" != "account", "worker" != "work"
+    tokens = set(key.split("_"))
+    for alias, cat in _CAT_ALIASES.items():
+        if alias in tokens:
+            return cat
+    return None
+
+
+def _to_conf(s) -> Confidence:
+    key = str(s or "").strip().lower()
+    return {
+        "low": Confidence.LOW, "medium": Confidence.MEDIUM, "med": Confidence.MEDIUM,
+        "high": Confidence.HIGH,
+    }.get(key, Confidence.LOW)

exposurecheck/backends/transports.py

@@ -0,0 +1,114 @@
+"""HTTP transports for LLM backends, standard-library only (urllib, no requests).
+
+Two shapes, both selected by the user:
+  CloudTransport  - any OpenAI-compatible /chat/completions endpoint (OpenAI,
+                    OpenRouter, or a self-hosted gateway). Bring your own key.
+  LocalTransport  - a local Ollama server (/api/chat). No network egress.
+
+A local OpenAI-compatible server (llama.cpp, LM Studio) can also be driven by
+CloudTransport pointed at http://localhost:... with any placeholder key.
+"""
+
+from __future__ import annotations
+
+import json
+import urllib.error
+import urllib.request
+from abc import ABC, abstractmethod
+from typing import Optional
+
+
+class TransportError(RuntimeError):
+    pass
+
+
+class Transport(ABC):
+    name: str = "transport"
+    is_local: bool = False
+    sends_data_offsite: bool = False
+
+    @abstractmethod
+    def complete(self, system: str, user: str, model: str, *,
+                 max_tokens: int = 800, temperature: float = 0.0) -> str:
+        ...
+
+
+def _post_json(url: str, payload: dict, headers: dict, timeout: float) -> dict:
+    body = json.dumps(payload).encode("utf-8")
+    req = urllib.request.Request(url, data=body, method="POST")
+    req.add_header("Content-Type", "application/json")
+    for k, v in headers.items():
+        req.add_header(k, v)
+    try:
+        with urllib.request.urlopen(req, timeout=timeout) as resp:
+            return json.loads(resp.read().decode("utf-8", "replace"))
+    except urllib.error.HTTPError as e:
+        detail = e.read().decode("utf-8", "replace")[:500] if e.fp else ""
+        raise TransportError(f"HTTP {e.code} from {url}: {detail}") from e
+    except urllib.error.URLError as e:
+        raise TransportError(f"cannot reach {url}: {e.reason}") from e
+
+
+class CloudTransport(Transport):
+    is_local = False
+    sends_data_offsite = True
+
+    def __init__(self, api_key: str, *, base_url: str = "https://api.openai.com/v1",
+                 timeout: float = 60.0, name: Optional[str] = None):
+        if not api_key:
+            raise TransportError("cloud backend needs an API key (set it via env, never on the CLI)")
+        self.api_key = api_key
+        self.base_url = base_url.rstrip("/")
+        self.timeout = timeout
+        self.name = name or f"cloud({self.base_url})"
+
+    def complete(self, system, user, model, *, max_tokens=800, temperature=0.0) -> str:
+        data = _post_json(
+            f"{self.base_url}/chat/completions",
+            {
+                "model": model,
+                "messages": [
+                    {"role": "system", "content": system},
+                    {"role": "user", "content": user},
+                ],
+                "temperature": temperature,
+                "max_tokens": max_tokens,
+            },
+            {"Authorization": f"Bearer {self.api_key}"},
+            self.timeout,
+        )
+        try:
+            return data["choices"][0]["message"]["content"]
+        except (KeyError, IndexError, TypeError) as e:
+            raise TransportError(f"unexpected response shape: {str(data)[:300]}") from e
+
+
+class LocalTransport(Transport):
+    is_local = True
+    sends_data_offsite = False
+
+    def __init__(self, *, base_url: str = "http://localhost:11434",
+                 timeout: float = 120.0, name: Optional[str] = None):
+        self.base_url = base_url.rstrip("/")
+        self.timeout = timeout
+        self.name = name or f"local({self.base_url})"
+
+    def complete(self, system, user, model, *, max_tokens=800, temperature=0.0) -> str:
+        data = _post_json(
+            f"{self.base_url}/api/chat",
+            {
+                "model": model,
+                "messages": [
+                    {"role": "system", "content": system},
+                    {"role": "user", "content": user},
+                ],
+                "stream": False,
+                "options": {"temperature": temperature, "num_predict": max_tokens},
+            },
+            {},
+            self.timeout,
+        )
+        try:
+            return data["message"]["content"]
+        except (KeyError, TypeError) as e:
+            raise TransportError(f"unexpected Ollama response: {str(data)[:300]}") from e

exposurecheck/cascade/__init__.py

@@ -0,0 +1,6 @@
+"""Recall-preserving tiered cascade."""
+
+from .pipeline import CascadeOutcome, run_cascade
+from .prefilter import prefilter
+
+__all__ = ["run_cascade", "CascadeOutcome", "prefilter"]