keyhunter/.planning/phases/17-telegram-scheduler/17-CONTEXT.md

Phase 17: Telegram Bot & Scheduled Scanning - Context

Gathered: 2026-04-06 Status: Ready for planning Mode: Auto-generated

## Phase Boundary

Two capabilities:

1. Telegram Bot — Long-polling bot using telego v1.8.0. Commands: /scan, /verify, /recon, /status, /stats, /providers, /help, /key, /subscribe. Runs via keyhunter serve --telegram. Private chat only. Keys always masked except /key <id> which sends full detail.
2. Scheduled Scanning — Cron-based recurring scans using gocron v2.19.1. Stored in SQLite. CLI: keyhunter schedule add/list/remove. Jobs persist across restarts. New findings trigger Telegram notification to subscribers.

## Implementation Decisions

Telegram Bot (TELE-01..07)

• Library: github.com/mymmrac/telego v1.8.0 (already in go.mod from Phase 1 dep planning)
• Package: pkg/bot/
  • bot.go — Bot struct, Start/Stop, command registration
  • handlers.go — command handlers for /scan, /verify, /recon, /status, /stats, /providers, /help, /key
  • subscribe.go — /subscribe handler + subscriber storage (SQLite table)
  • notify.go — notification dispatcher (send findings to all subscribers)
• Long polling: Use telego.WithLongPolling option
• Auth: Bot token from config telegram.token; restrict to allowed chat IDs from telegram.allowed_chats (array, empty = allow all)
• Message formatting: Use Telegram MarkdownV2 for rich output
• Key masking: ALL output masks keys. /key <id> sends full key only to the requesting user's DM (never group chat)
• Command routing: Register each command handler via bot.Handle("/scan", scanHandler) etc.

Scheduled Scanning (SCHED-01..03)

• Library: github.com/go-co-op/gocron/v2 v2.19.1 (already in go.mod)
• Package: pkg/scheduler/
  • scheduler.go — Scheduler struct wrapping gocron with SQLite persistence
  • jobs.go — Job struct + CRUD in SQLite scheduled_jobs table
• Storage: scheduled_jobs table: id, name, cron_expr, scan_command, notify_telegram, created_at, last_run, next_run, enabled
• Persistence: On startup, load all enabled jobs from DB and register with gocron
• Notification: On job completion with new findings, call pkg/bot/notify.go to push to subscribers
• CLI commands: Replace schedule stub in cmd/stubs.go with:
  • keyhunter schedule add --name=X --cron="..." --scan=<path> [--notify=telegram]
  • keyhunter schedule list
  • keyhunter schedule remove <name>
  • keyhunter schedule run <name> (manual trigger)

Integration: serve command

• keyhunter serve [--telegram] [--port=8080]
• If --telegram: start bot in goroutine, start scheduler, block until signal
• If no --telegram: start scheduler + web server only (Phase 18)
• Replace serve stub in cmd/stubs.go

New SQLite Tables

CREATE TABLE IF NOT EXISTS subscribers (
    chat_id INTEGER PRIMARY KEY,
    username TEXT,
    subscribed_at DATETIME DEFAULT CURRENT_TIMESTAMP
);

CREATE TABLE IF NOT EXISTS scheduled_jobs (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    name TEXT UNIQUE NOT NULL,
    cron_expr TEXT NOT NULL,
    scan_command TEXT NOT NULL,
    notify_telegram BOOLEAN DEFAULT FALSE,
    enabled BOOLEAN DEFAULT TRUE,
    last_run DATETIME,
    next_run DATETIME,
    created_at DATETIME DEFAULT CURRENT_TIMESTAMP
);

Dependencies

• github.com/mymmrac/telego — already indirect in go.mod, promote to direct
• github.com/go-co-op/gocron/v2 — already indirect, promote to direct

<code_context>

Existing Code Insights

Reusable Assets

• pkg/engine/ — engine.Scan() for bot /scan command
• pkg/verify/ — verifier for bot /verify command
• pkg/recon/ — Engine.SweepAll() for bot /recon command
• pkg/storage/ — DB for findings, settings
• pkg/output/ — formatters for bot message rendering
• cmd/stubs.go — serve, schedule stubs to replace
• cmd/scan.go — openDBWithKey() helper to reuse

Key Integration Points

• Bot handlers call the same packages as CLI commands
• Scheduler wraps the same scan logic but triggered by cron
• Notification bridges scheduler → bot subscribers

</code_context>

## Specific Ideas

• /status should show: total findings, last scan time, active scheduled jobs, bot uptime
• /stats should show: findings by provider, top 10 providers, findings last 24h
• Bot should rate-limit commands per user (1 scan per 60s)
• Schedule jobs should log last_run and next_run for monitoring

## Deferred Ideas

• Webhook notifications (Slack, Discord) — separate from Telegram
• Inline query mode for Telegram — out of scope
• Multi-bot instances — out of scope
• Job output history (keep last N results) — defer to v2