ossrules.md

unbroker

Autonomously remove your info from data-broker sites.

  • privacy
  • data-broker
  • opt-out
  • ccpa
  • gdpr
  • security
  • doxxing

Declared platforms: linux · macos · windows

Install
npx skills add 'https://github.com/NousResearch/hermes-agent/tree/main/optional-skills/security/unbroker'
Download bundle ↓
main · 24fd22b ↗Scanned 2026-09-15

Contributors

GitHub-linked commit authors for this SKILL.md at the saved revision. Co-authors and history before file renames are not included.

File history ↗

scripts/autopilot.py

scripts/autopilot.pyBrowse 56 files
View on GitHub
5,019 tokens

21,978 bytes
Token encoding: o200k_base
Snapshot 24fd22b

← Back to SKILL.md
"""Autonomous action queue: what should the agent do RIGHT NOW for this subject? `next_actions` turns (dossier, broker DB, config, ledger) into an ordered queue ofconcrete agent actions plus a human digest. The agent's whole run becomes a loop:     while True:        q = pdd.py next <subject>        if not q["actions"]: break        execute each action, record outcomes    present q["human_digest"] once; schedule cron at q["next_wake_at"] Policy (cfg["autonomy"]):  full     - intake consent is standing authorization; T0-T2 agent actions are             executed without pausing. Humans appear only in the digest.  assisted - same queue, but every submission action carries confirm_first=True. The queue is deterministic and side-effect free: it never mutates the ledger, itonly reads. Executing + recording stays with the agent (and the record command)."""from __future__ import annotations import datetime as _dtimport osfrom pathlib import Path import brokers as brokers_modimport emailerimport ledger as ledger_modimport pathsimport registryimport tiers CACHE_STALE_DAYS = 7          # refresh the live broker list after thisFANOUT_THRESHOLD = 8          # above this many unscanned brokers, use delegate_task fan-out # States with nothing left to do (absent a due recheck)._TERMINAL = {"not_found", "confirmed_removed"}_IN_FLIGHT = {"submitted", "verification_pending", "awaiting_processing"}  def cache_age_days(now: float | None = None) -> float | None:    """Age of the live BADBOOL cache in days, or None if never pulled."""    p: Path = paths.brokers_cache_path()    if not p.exists():        return None    now = now if now is not None else _dt.datetime.now().timestamp()    return max(0.0, (now - p.stat().st_mtime) / 86400.0)  def _now_iso() -> str:    return _dt.datetime.now(_dt.timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")  def _min_future_recheck(ledger: dict, at: str) -> str | None:    future = [c.get("next_recheck_at") for c in ledger.values()              if c.get("next_recheck_at") and c["next_recheck_at"] > at]    return min(future) if future else None  def _digest(broker_row: dict, reason: str, steps: list[str], prep: list[str] | None = None) -> dict:    return {        "broker_id": broker_row.get("broker_id"),        "broker_name": broker_row.get("broker_name"),        "reason": reason,        "agent_prep": prep or [],     # commands the agent runs BEFORE handing this to the human        "steps": steps,               # what the human actually does        "withhold": ["SSN", "full driver's-license / passport numbers"],    }  def request_kind(dossier: dict, allowed: list[str] | None = None) -> str:    """Pick the honest legal basis for a deletion request from the subject's residency.     ccpa only for California residents, gdpr only for EU/UK residents, generic otherwise.    `allowed` (from the broker's deletion.kinds) can restrict DOWN to generic but never    upgrades to a law the subject can't truthfully claim.    """    res = (dossier.get("residency_jurisdiction") or "US").upper()    if res.startswith("US-CA"):        kind = "ccpa"    elif res.startswith(("EU", "UK", "GB")):        kind = "gdpr"    else:        kind = "generic"    if allowed and kind not in allowed and "generic" in allowed:        kind = "generic"    return kind  _HUMAN_GATES = ("gov_id", "fax", "mail", "phone_voice", "phone_callback", "account")  def _email_lane(row: dict) -> tuple[str | None, str]:    """(address, why) for the autonomous email lane of this broker, if one exists.     Lane rules:      1. the broker's primary opt-out method IS email;      2. the record marks its deletion lane email-preferred (deletion.via == "email");      3. RESCUE: the primary flow is human-gated (gov ID / fax / phone / account) but a         right-to-delete email exists - the email lane restores full autonomy (this is the         verified Whitepages pattern: privacyrequest@ accepts requests precisely so people         don't have to do the phone-callback tool).    """    deletion = row.get("deletion") or {}    req = row.get("optout_requires") or {}    if row.get("method") == "email":        addr = row.get("optout_email") or deletion.get("email")        return (addr, "primary opt-out method is email") if addr else (None, "")    if deletion.get("via") == "email" and deletion.get("email"):        return deletion["email"], "record prefers the right-to-delete email lane"    if (row.get("tier") == "T3" or any(req.get(k) for k in _HUMAN_GATES)) and deletion.get("email"):        return deletion["email"], "rescue: primary flow is human-gated; deletion email restores autonomy"    return None, ""  def _optout_action(row: dict, playbook: dict[str, dict], subject_id: str, dossier: dict,                   email_mode: str, smtp_ok: bool, confirm_first: bool) -> tuple[dict | None, dict | None]:    """Map one actionable `found` row to (agent_action, human_digest_entry).     Routing order maximizes autonomy: (1) the email lane (primary email method, preferred    right-to-delete email, or rescue from a human-gated form) beats everything when SMTP is    up; (2) genuinely human-only flows go to the digest; (3) web forms are driven with the    record's own field-verified playbook steps.    """    bid = row["broker_id"]    req = row.get("optout_requires") or {}    tier = row.get("tier")    deletion = row.get("deletion") or {}     # 1) The autonomous EMAIL LANE (right-to-delete by email + confirm the reply).    # Autonomous when SMTP is configured (programmatic/alias) OR in browser mode (agent sends via    # the operator's logged-in webmail; no password needed).    email_addr, lane_why = _email_lane(row)    can_email = (email_mode in ("programmatic", "alias") and smtp_ok) or email_mode == "browser"    if email_addr and can_email:        kind = request_kind(dossier, deletion.get("kinds"))        via = "browser" if email_mode == "browser" else "smtp"        then = ("send-email records it + returns a recipient-locked payload; compose and send it in "                "the operator's webmail via browser_*, then `verify-link` on the reply and open the link"                if via == "browser" else                "state auto-records as submitted; poll-verification picks up their verification reply, "                "open its link, then record")        return {            "type": "optout_email_send",            "broker_id": bid, "broker_name": row.get("broker_name"), "tier": tier,            "confirm_first": confirm_first, "send_via": via,            "to": email_addr, "kind": kind, "why": lane_why,            "command": f"python3 scripts/pdd.py send-email {subject_id} {bid} --kind {kind} "                       f"--to {email_addr} --listing <confirmed-url>",            "then": then,        }, None    if row.get("method") == "email":        return None, _digest(row, "email opt-out (draft mode: a human must hit send)",                             ["Send the rendered draft from your own mail client",                              f"Then: python3 scripts/pdd.py record {subject_id} {bid} submitted "                              f"--disclosed contact_email --channel email"],                             prep=[f"python3 scripts/pdd.py render-email {subject_id} {bid} --listing <confirmed-url>"])     # 2) Genuinely human-only work goes to the digest (no email lane could rescue it).    if tier == "T3":        return None, _digest(row, "human-only opt-out (gov ID / fax / mail / voice phone)",                             [f"Follow the broker's process at {row.get('optout_url') or row.get('optout_email')}",                              "Provide only the fields the listing already shows; cross out ID numbers on any document"])    if req.get("phone_callback"):        return None, _digest(row, "phone-callback verification (operator must be on the phone)",                             [f"Open {row.get('optout_url')} and submit with only the planned fields",                              "Answer the automated call and enter the 4-digit code to finish"],                             prep=[f"python3 scripts/pdd.py plan {subject_id} --batch  # confirm fields first"])    if req.get("account"):        return None, _digest(row, "requires creating/holding an account with the broker",                             [f"Create/log in at {row.get('optout_url')} and submit the opt-out",                              "Use the subject's contact email; no extra PII beyond the planned fields"])     # 3) web_form: drive the browser with the record's own playbook steps.    steps = (playbook.get(bid) or {}).get("steps") or list(row.get("optout_playbook") or []) \        or tiers.synthesize_steps(row)    action = {        "type": "optout_web_form",        "broker_id": bid, "broker_name": row.get("broker_name"), "tier": tier,        "confirm_first": confirm_first,        "optout_url": row.get("optout_url"),        "clears_children": row.get("clears_children") or [],        "steps": steps,        "after": f"python3 scripts/pdd.py record {subject_id} {bid} submitted "                 f"--disclosed <field>... --channel web_form",    }    if deletion:        if deletion.get("prefer", True):            action["prefer_deletion"] = ("this record has a right-to-delete lane -- complete the "                                         "DELETION flow, not just suppression"                                         + (f" ({deletion.get('notes')})" if deletion.get("notes") else ""))        else:            # Some brokers invert the usual rule: deleting the account removes suppressions and            # does not stop public-records re-listing (e.g. PeopleConnect). Suppress and maintain.            action["prefer_suppression"] = (deletion.get("notes")                                            or "suppression (maintained) is what removes you here; "                                               "deleting undoes it and does not stop re-listing")    if req.get("captcha"):        action["note"] = ("CAPTCHA-gated: attempt with the configured browser backend once; if it "                          "does not clear, record blocked (do NOT retry-loop or bypass)")    return action, None  def next_actions(dossier: dict, brokers_list: list[dict], cfg: dict,                 ledger: dict | None = None, env: dict | None = None) -> dict:    env = os.environ if env is None else env    ledger = ledger or {}    subject_id = dossier.get("subject_id", "")    autonomy = cfg.get("autonomy", "full")    confirm_first = autonomy == "assisted"    email_mode = cfg.get("email_mode", "draft_only")    mail = emailer.available(env)    at = _now_iso()     batch = tiers.batch_plan(dossier, brokers_list, cfg, ledger,                             browser_clears_captcha=cfg.get("browser_backend") == "browserbase"                             or bool(env.get("BROWSERBASE_API_KEY")))    groups = batch["groups"]    playbook = {p["broker_id"]: p for p in batch.get("parent_playbook") or []}    by_id = {b.get("id"): b for b in brokers_list}     actions: list[dict] = []    digest: list[dict] = []     # 0) keep the broker DB fresh (autonomously)    age = cache_age_days()    if age is None or age > CACHE_STALE_DAYS:        actions.append({            "type": "refresh_brokers",            "why": "live broker cache missing" if age is None else f"cache is {age:.0f} days old",            "command": "python3 scripts/pdd.py refresh-brokers",        })     # 0b) DROP one-shot: for a CA resident, ONE request deletes from every registered    # broker (the whole CA Data Broker Registry) -- the highest-leverage removal there is.    registry_recs = brokers_mod.load_registry_cache()    residency = (dossier.get("residency_jurisdiction") or "US").upper()    drop_filed = bool((dossier.get("preferences") or {}).get("drop_filed_at"))    if registry_recs and residency.startswith("US-CA") and not drop_filed:        actions.append({            "type": "drop_submit",            "one_shot": True,            "registry_count": len(registry_recs),            "url": registry.DROP_URL,            "command": f"python3 scripts/pdd.py drop {subject_id}",            "why": f"CA resident: one DROP request deletes from all {len(registry_recs)} registered "                   "data brokers at once (superset of what commercial services cover).",            "after": f"python3 scripts/pdd.py drop {subject_id} --filed",        })     # 1) Phase 1 crawl: everything unscanned (read-only, parallel-safe)    unscanned = groups.get("unscanned") or []    if unscanned:        ids = [r["broker_id"] for r in unscanned]        if len(ids) > FANOUT_THRESHOLD:            actions.append({                "type": "fanout_scan",                "broker_ids": ids,                "command": f"python3 scripts/pdd.py fanout {subject_id}",                "how": "spawn ONE delegate_task subagent per batch IN PARALLEL with each batch's brief; "                       "parent re-verifies key `found` claims before trusting them",            })        else:            actions.append({                "type": "scan_inline",                "broker_ids": ids,                "command": f"python3 scripts/pdd.py plan {subject_id}",                "how": "run every search_vector per broker via the methods.md ladder "                       "(web_extract -> site: probe -> browser), record a verdict per broker",            })     # 2) in-flight email verifications: poll the inbox (or hand to the human in draft mode)    for st in ("submitted", "verification_pending"):        for bid, case in sorted(ledger.items()):            if case.get("state") != st:                continue            broker = by_id.get(bid) or {}            if not ((broker.get("optout") or {}).get("requires") or {}).get("email_verification"):                continue            if mail["imap"]:                actions.append({                    "type": "poll_verification", "via": "imap",                    "broker_id": bid,                    "command": f"python3 scripts/pdd.py poll-verification {subject_id} --broker {bid}",                    "then": "browser_navigate the returned link IN THE SAME AGENT BROWSER (sessions are "                            "browser-bound), complete the flow, then record: awaiting_processing",                })            elif email_mode == "browser":                actions.append({                    "type": "poll_verification", "via": "browser", "broker_id": bid,                    "how": "open the broker's confirmation email in the operator's logged-in webmail "                           f"(browser_*), then `python3 scripts/pdd.py verify-link {subject_id} {bid} "                           "--text '<email body>'` to score the link, browser_navigate it in the SAME "                           "browser, then record awaiting_processing",                })            else:                digest.append(_digest(                    {"broker_id": bid, "broker_name": (broker.get("name") or bid)},                    "verification email must be opened by a human (draft mode, no inbox access)",                    ["Open the broker's verification email in the subject's inbox and click the link",                     f"Then: python3 scripts/pdd.py record {subject_id} {bid} awaiting_processing"]))     # 3) due rechecks: processing windows elapsed / reappearance sweeps    for case in ledger_mod.due(subject_id, at=at, ledger=ledger):        bid = case.get("broker_id")        st = case.get("state")        if st in ("awaiting_processing", "confirmed_removed"):            actions.append({                "type": "verify_removal",                "broker_id": bid,                "why": "processing window elapsed" if st == "awaiting_processing" else "periodic reappearance re-scan",                "how": "re-run this broker's search_vectors; if gone record confirmed_removed; "                       "if still listed record reappeared and requeue the opt-out",            })        elif st in ("submitted", "verification_pending") and not mail["imap"]:            pass  # already covered by the digest entry above     # 4) Phase 2 opt-outs: parents first (batch_plan already ordered them)    for row in groups.get("found") or []:        action, task = _optout_action(row, playbook, subject_id, dossier,                                      email_mode, mail["smtp"], confirm_first)        if action:            actions.append(action)        if task:            digest.append(task)     # 5) indirect exposure: targeted delete-my-PII requests    for row in groups.get("indirect_exposure") or []:        bid = row["broker_id"]        has_email = bool(row.get("optout_email") or (row.get("deletion") or {}).get("email"))        if not has_email and row.get("optout_url"):            # No email lane (e.g. ThatsThem is web-form-only): drive the opt-out FORM, submitting            # ONLY the subject's own identifiers to scrub from the third party's record.            actions.append({                "type": "indirect_web_form",                "broker_id": bid, "confirm_first": confirm_first,                "optout_url": row.get("optout_url"),                "steps": [f"browser_navigate {row.get('optout_url')}",                          "submit ONLY the subject's own identifiers (the fields the form requires) to "                          "remove them from the third party's record; disclose nothing extra",                          "confirm the success state, screenshot into evidence/"],                "after": f"python3 scripts/pdd.py record {subject_id} {bid} submitted --channel web_form",            })        elif (email_mode in ("programmatic", "alias") and mail["smtp"]) or email_mode == "browser":            actions.append({                "type": "indirect_email_send",                "broker_id": bid, "confirm_first": confirm_first,                "send_via": "browser" if email_mode == "browser" else "smtp",                "command": f"python3 scripts/pdd.py send-email {subject_id} {bid} --kind ccpa_indirect "                           f"--listing <third-party-listing-url>",            })        else:            digest.append(_digest(row, "indirect-exposure request (draft mode: a human must hit send)",                                  ["Send the rendered ccpa_indirect draft",                                   f"Then: python3 scripts/pdd.py record {subject_id} {bid} submitted "                                   f"--disclosed contact_email --channel email"],                                  prep=[f"python3 scripts/pdd.py render-email {subject_id} {bid} "                                        f"--kind ccpa_indirect --listing <url>"]))     # 6) blocked sites: stealth pass if we have one, else the operator-browser path    blocked = groups.get("blocked") or []    if blocked:        ids = [r["broker_id"] for r in blocked]        if bool(env.get("BROWSERBASE_API_KEY")):            actions.append({                "type": "stealth_rescan",                "broker_ids": ids,                "how": "retry these with the cloud/stealth browser backend, then record real verdicts",            })        else:            for r in blocked:                digest.append(_digest(r, "site blocks automated access (anti-bot); a human browser gets through",                                      ["Open the paste-ready search URL from `plan` in your everyday browser",                                       "Report the verdict (or a screenshot) back to the agent",                                       f"Agent records: python3 scripts/pdd.py record {subject_id} "                                       f"{r['broker_id']} <found|not_found|indirect_exposure>"]))     # 7) anything already parked as a human task    for bid, case in sorted(ledger.items()):        if case.get("state") == "human_task_queued":            broker = by_id.get(bid) or {}            digest.append(_digest({"broker_id": bid, "broker_name": broker.get("name") or bid},                                  case.get("human_task_reason") or "queued manual step",                                  ["See `pdd.py tasks` for the exact steps recorded with this case"]))     # registry coverage summary (breadth beyond the scannable people-search sites)    coverage = None    if registry_recs:        coverage = {            "people_search_sites": len(brokers_list),            "registered_data_brokers": len(registry_recs),            "worked_via": "CA DROP one-shot" if residency.startswith("US-CA") else "targeted CCPA/GDPR email",        }        if not residency.startswith("US-CA"):            coverage["note"] = ("DROP is CA-only; for this subject the registry is covered by targeted "                                "CCPA/GDPR deletion emails (`registry --search` then `send-email`), "                                "not a single portal request.")        elif drop_filed:            coverage["note"] = "DROP already filed; registry deletions are in the brokers' hands."     next_wake = _min_future_recheck(ledger, at)    return {        "subject": subject_id,        "autonomy": autonomy,        "phase": batch.get("phase"),        "counts": batch.get("counts"),        "actions": actions,        "human_digest": digest,        "coverage": coverage,        "done_for_now": not actions,        "fully_done": not actions and not digest and not next_wake,        "next_wake_at": next_wake,        "note": ("assisted mode: pause for operator confirmation on every action with confirm_first=true"                 if confirm_first else                 "full autonomy: recorded intake consent authorizes these submissions; do not pause. "                 "Present human_digest ONCE at the end of the run, not per item."),    }
← All Hermes Agent skillsProject instructions →