Local lookup helper used by a private TDESKTOP_OSINT=ON build. Results stay in a local SQLite DB — nothing is uploaded to Telegram servers.

Implemented in Go with:

1. Parallel discovery — gosearch, sherlock, maigret, user-scanner run concurrently (errgroup)
2. Deterministic HTTP validation (always on) — kills 404 / soft-404s / scam hosts / auth walls
3. ADK-Go orchestrator — discovery fan-out, merge/dedupe, HTTP validate, optional OpenAI smart refine

Resolution order for each tool: native binary (*_BIN, bin/<tool>, PATH) → docker image (when present) → skipped.

cd tools/osint
go build -o bin/osint-worker ./cmd/osint-worker

Requires Go 1.26+ (ADK Go). Uses pure-Go SQLite (modernc.org/sqlite, no CGO).

ADK orchestrator (osint_orchestrator)
│
├─ discover_fanout          parallel ADK agents (errgroup inside each username agent)
│     ├─ gosearch           native binary (parallel with others)
│     ├─ sherlock           docker run --rm sherlock/sherlock …
│     ├─ maigret            docker run --rm -v $TMP:/app/reports soxoj/maigret …
│     └─ user-scanner       native (optional)
│     ├─ holehe             docker/native (per --email)
│     └─ phoneinfoga        docker/native (per --phone)
│
├─ merge_dedupe             URL dedupe before HTTP validate
│
├─ http_validate            HEAD→GET, soft-404, blocklist, Reddit about.json
│
└─ smart_pipeline           (when OPENAI_API_KEY / API_KEY set)
      ├─ fanout_prep        parallel prep agents
      ├─ smart_validate     OpenAI classify valid_profile / false_positive / unsure
      ├─ dedupe             merge duplicate site/account rows
      ├─ summarize          short UI snippets
      └─ openai_ready       llmagent health ack

Progress events stream as NDJSON on stderr ({"type":"progress","stage":…}). Final JSON on stdout (and --out) includes progress[] and tool_modes for the C++ UI.

Example tool_modes from a smoke run:

{
  "gosearch": "native",
  "sherlock": "docker",
  "maigret": "docker",
  "user-scanner": "skipped"
}

Cache schema version 4 invalidates older soft-404 / weak “validated” rows.

Never commit real keys. Prefer repo-root .env (gitignored) or tools/osint/.env.

# OpenAI / ADK (optional smart layer)
OPENAI_API_KEY=sk-...
# API_KEY=...                 # alias
OSINT_ADK=1                   # default on when key present; OSINT_ADK=0 to force off
OPENAI_MODEL=gpt-4o-mini
# OPENAI_BASE_URL=http://localhost:11434/v1

# Tool toggles (1=force on, 0=force off; default=auto-detect)
# OSINT_SHERLOCK=1
# OSINT_MAIGRET=1
# OSINT_GOSEARCH=1
# OSINT_HOLEHE=1
# OSINT_PHONEINFOGA=1
# OSINT_USER_SCANNER=1
# OSINT_USERNAME_PROBE=1      # built-in HTTP probes (last resort)

# Docker image overrides
SHERLOCK_DOCKER_IMAGE=sherlock/sherlock
MAIGRET_DOCKER_IMAGE=soxoj/maigret:latest
HOLEHE_DOCKER_IMAGE=mrnonoss/holehe:latest
PHONEINFOGA_DOCKER_IMAGE=sundowndev/phoneinfoga:latest

# Native binary overrides
GOSEARCH_BIN=
SHERLOCK_BIN=
MAIGRET_BIN=
HOLEHE_BIN=
PHONEINFOGA_BIN=
USER_SCANNER_BIN=

Copy placeholders from .env.example / tools/osint/.env.example.

docker pull sherlock/sherlock
docker pull soxoj/maigret:latest
# optional (amd64 hosts):
docker pull mrnonoss/holehe:latest
docker pull sundowndev/phoneinfoga:latest

Verify from worker context:

docker info
cd tools/osint
OSINT_ADK=0 ./bin/osint-worker lookup --peer-id 1 --username compfaculty --refresh --json
# inspect tool_modes in output

mkdir -p tools/osint/bin
GOBIN="$(pwd)/tools/osint/bin" go install github.com/ibnaleem/gosearch@latest

Override with GOSEARCH_BIN=/path/to/gosearch. Worker passes --no-false-positives.

docker pull sherlock/sherlock
docker run --rm sherlock/sherlock USERNAME --print-found --no-color --no-txt

Default on when image present. Force off: OSINT_SHERLOCK=0.

Local fallback: uv pip install sherlock-project or pipx install sherlock-project.

docker pull soxoj/maigret:latest
docker run --rm -v /tmp/reports:/app/reports soxoj/maigret:latest USERNAME \
  --json simple -fo /app/reports --top-sites 50 --no-progressbar

Or: pipx install maigret.

pipx install user-scanner
# USER_SCANNER_BIN=… when installed

No official Docker image exists.

# phoneinfoga — native binary in tools/osint/bin/ (preferred on Apple Silicon)
# or docker pull sundowndev/phoneinfoga:latest (amd64)

# holehe — docker pull mrnonoss/holehe:latest (amd64) or pip install holehe

When configured with -D TDESKTOP_OSINT=ON, CMake bakes TDESKTOP_OSINT_WORKER_DIR to this directory. Profile section runs:

bin/osint-worker lookup … --json --out <tempfile>

Override: TDESKTOP_OSINT_WORKER=/absolute/path/to/osint-worker.

./bin/osint-worker lookup \
  --peer-id 123456 \
  --username someuser \
  --json \
  --out /tmp/osint-result.json \
  --refresh

./bin/osint-worker status --peer-id 123456 --json

Default DB: ~/Library/Application Support/Telegram Desktop/osint_cache.sqlite

1. Build Debug with TDESKTOP_OSINT=ON (and your .env API IDs; API_TEST=OFF).
2. Ensure tools/osint/bin/osint-worker exists (+ gosearch and/or docker images).
3. Launch out/Debug/Telegram.app, open a user profile → OSINT section.
4. Rows are selectable / copyable; snippets show 200 · validated or ADK reasons.
5. After a worker/schema bump, use Refresh OSINT (or --refresh).

• Search-engine URLs dropped early.
• HTTP status must be a real profile success (200 / 203 / 206).
• Soft-404 titles/bodies rejected.
• Scam / parked image hosts blocklisted.
• Reddit: requires about.json user proof.
• Dedup by normalized URL + site+username (best confidence wins).

See python_legacy/ — not invoked by Desktop.

• First username lookup is network-bound (parallel discovery + validation).
• Partial tool failures still store survivors (status: partial).
• Stock builds leave TDESKTOP_OSINT OFF (code compiled out).
• Worker failures must never crash the app.