Skip to content

FlareHound

A self-hosted traffic console and watchdog for websites behind Cloudflare. FlareHound polls the Cloudflare Analytics API with a read-only token, compares each clock hour with the same hour yesterday, breaks every anomaly down by path, ASN, user agent and cache status, and sends a short, plain-language report — conclusion first, with evidence and a suggested action — only when something needs your attention.

Cloudflare gives you data. FlareHound gives you the conclusion.

What it does

Feature Summary Page
Hourly watch Zone requests, uncached (dynamic) responses, origin 5xx, origin unreachable (52x) and latency, Worker invocations and CPU P50, new user agents / ASNs, per-path lines Detection
Quiet alerting One alert per anomaly; another only on a new signal or +25% growth; one "recovered" line after two clean rounds Detection
Attribution and suggestions Expensive vs. cheap traffic, hypotheses with confidence and falsifiers, block / challenge / rate-limit / cache suggestions with paste-ready expressions Reports
Daily report Last 24 h vs. the 24 h before, fixed checkpoints, firewall events, block attempts, WAF audit summary, calibration line Reports
Notification channels Webhook, Telegram, JSONL file, Slack, Discord, WeCom, Feishu/Lark, email Channels
Local archive SQLite file with ~13 months of hourly snapshots, a 4-week median baseline, face history, alert history Archive
Calibration How FlareHound's numbers relate to the Cloudflare dashboard Archive
One-click blocking IP / CIDR / ASN / country / user agent, with guard rails, expiry and an audit log (separate write token) Blocking
Rule changes Add, edit, move, delete and restore custom, rate-limit and cache rules with backup and read-back (separate write token) Rule changes
WAF rule audit Coverage gaps on sensitive paths, shadowed rules, forgeable exemptions, zombie rules, quota WAF audit
Web console Live hour vs baseline, movers and drill-down, new faces, history, WAF audit and rules, settings, in-console blocking, snapshots, multi-zone home (admin / viewer accounts, TOTP, Google / GitHub sign-in) Console

Design principles

  • Read-only core. The watchdog process holds only a read token. Blocking and rule changes are separate commands with their own write token and an explicit confirmation.
  • Silence is a feature. No anomaly, no message.
  • Split before concluding. Every spike is attributed before any hypothesis is stated; findings are deterministic and reproducible — no AI sits in the detection path.
  • Your token stays home. Tokens come only from environment variables, are redacted from logs, and are only sent to api.cloudflare.com.

Where to start

  1. Quick start — run it with Docker in a few minutes.
  2. API tokens & permissions — the minimum token you need.
  3. Configuration reference — every key and default.

The full design (in Chinese) is in SPEC.md. A short Chinese overview is on the 中文简介 page.