unbroker

name	unbroker
description	Find and remove authorized personal information exposures from data brokers and people-search sites with a consent-gated local workflow.
version	1.0.0
metadata	{"author":"CoWork OS Contributors <[e-mail]>","source-author":"SHL0MS / Nous Research, ported by CoWork OS"}

unbroker

This CoWork OS bundled port is based on the upstream Hermes Agent unbroker skill: https://github.com/NousResearch/hermes-agent/tree/main/optional-skills/security/unbroker

CoWork runtime mapping:

• Treat terminal as CoWork's shell/run_command capability.
• Treat web_extract as CoWork web search, fetch, or extraction tools.
• Treat browser_* as the available CoWork browser automation tools.
• Treat delegate_task as CoWork multi-agent orchestration when available.
• Treat cronjob as CoWork scheduling/automation.
• The Python engine stores data under $PDD_DATA_DIR when set. Otherwise it prefers $COWORK_HOME/unbroker, then $COWORK_USER_DATA_DIR/unbroker, then the upstream legacy $HERMES_HOME/unbroker / ~/.hermes/unbroker path.

Code is MIT licensed. Broker data includes BADBOOL-derived data under CC BY-NC-SA 4.0; keep the license and attribution notes in LICENSE.txt and the README intact when redistributing.

Find where a person's personal information (name, addresses, phone, email, relatives) is exposed on data brokers and people-search sites, then remove it - automatically where possible, with guided human steps only where a site demands a CAPTCHA, government ID, phone call, or fax. Manages multiple people independently. It does not defeat anti-bot systems, does not act on anyone without recorded consent, and does not remove public records (voter/property/court) or accounts the person controls.

The Python CLI (scripts/pdd.py) owns the deterministic state - config, dossiers + consent, the broker database, tier planning, the ledger, drafts, reports, email sending (SMTP), verification-link polling (IMAP), and the autonomous action queue (next). You (the agent) do the scanning, form-driving, parallel work, and scheduling with the matching CoWork tools.

Autonomy contract

This skill is designed to run hands-off. After intake (+ recorded consent) there are exactly TWO legitimate human touchpoints: (1) the intake conversation itself, and (2) ONE consolidated human-task digest at the end of the run ($PDD tasks). Between those:

• Never ask the operator to choose configuration. $PDD setup --auto detects capabilities and picks the most autonomous valid config itself.
• Never pause before individual submissions when autonomy=full (the default): the consent recorded at intake is standing authorization for T0-T2 opt-outs. (autonomy=assisted restores per-submission confirmation for cautious operators - honor confirm_first flags in next output.)
• Never interrupt the run for human-only work. Record it (record ... human_task_queued --reason "...") and keep going; it all surfaces once in the final digest.
• Drive the whole run as a loop over $PDD next <subject> - it returns the exact ordered actions to take right now (scan, poll verification, re-check, opt out parents-first, requeue blocked), plus the human digest. Execute every action, record outcomes, re-run next, repeat until done_for_now. Then present the digest, report, and schedule the cron.

The hard limits that autonomy never overrides: no acting without recorded consent, no disclosure beyond disclosure_fields, no CAPTCHA/anti-bot bypass, and confirmed_removed only after a verifying re-scan.

When to Use

• "Remove my (or my family member's) data from data brokers / people-search sites."
• "Opt me out", "delete me from Spokeo/Whitepages/etc.", "clean up after a doxxing."
• "Set up recurring privacy monitoring" (brokers re-list people).
• Checking which brokers still expose someone and why.

Operational setup

Before running any command, read references/operations.md for prerequisites, safe command syntax, quick reference, batch sequencing, consent boundaries, and failure recovery. Never infer consent or submit removals outside the recorded scope.

Procedure (the autonomous loop)

1. Setup (once, no questions). Run $PDD setup --auto - it detects capabilities and configures the most autonomous valid combination itself (programmatic email when EMAIL_* creds exist, Browserbase when its key exists, age encryption when the binary exists, autonomy=full). Then $PDD doctor and show the operator the readiness output for information, not as a question - proceed immediately. Mention what would unlock more automation (e.g. email creds) but do not wait.

2. Intake + consent (the ONE human conversation). $PDD intake ... with --consent (and --consent-method). Without consent the engine refuses to plan or act. Collect everything in one pass - names/aliases, current + prior cities, emails, phones - so you never have to come back with questions. For California subjects, also read references/legal/drop.md: next will surface a drop_submit one-shot that deletes from every registered broker (~545) at once, which is the single highest-leverage action. File it, then drop <subject> --filed. For non-CA subjects the registry is covered by targeted CCPA/GDPR emails (registry --search, then send-email); the people-search sites are worked directly in either case.

3. Drain the queue. Loop:

   while true:
     q = $PDD next <subject>
     if q.actions is empty: break
     execute EVERY action in order; record each outcome via $PDD record
   

   next emits, in order: refresh_brokers (stale cache), fanout_scan/scan_inline (Phase 1 crawl - see step 4), poll_verification (in-flight email confirmations), verify_removal (due re-checks), optout_web_form/optout_email_send (Phase 2, parents-first with playbook steps), indirect_email_send, and stealth_rescan. Human-only work never appears as an action - it accumulates in q.human_digest. In autonomy=full, execute actions without pausing; honor confirm_first in assisted mode.

4. Scanning (when next says so). For : run and - do not scan all brokers yourself sequentially. For : scan the few brokers yourself. Either way, each broker gets entry via the ladder (web extraction -> probe -> browser automation -> stealth-capable browser/scraping), a 404 is INCONCLUSIVE (not ), is recorded when is set and no stealth browser is available, and subject vs namesake/relative is confirmed before recording: . The parent re-verifies key claims from subagents before trusting them.

Pitfalls

Apply the safety and recovery rules in references/operations.md, especially around CAPTCHA, verification links, duplicate submissions, rate limits, and evidence capture.

Verification

• scripts/run_tests.sh tests/skills/test_unbroker_skill.py (hermetic; no network), or the dependency-free runner python3 tests/skills/test_unbroker_skill.py.
• Dry run: $PDD setup --auto && $PDD doctor && SID=$($PDD intake --full-name "Test Person" --email [e-mail] --consent | python3 -c 'import sys,json;print(json.load(sys.stdin)["subject_id"])') && $PDD next "$SID" and confirm a readiness summary plus an ordered action queue.