Self-hosted traffic console and watchdog for Cloudflare sites: anomaly alerts, WAF audit, in-console
4.2K
English | 中文
A self-hosted traffic console and watchdog for websites behind Cloudflare. It polls the Cloudflare Analytics API with a read-only token, detects traffic anomalies hour by hour, breaks them down by path / ASN / user agent / cache status, and sends you a short, plain-language report — conclusion first, with the evidence and a suggested action — only when something actually needs your attention.
Cloudflare gives you data. FlareHound gives you the conclusion.
Status: v1.17.0 — IP location (country) next to every IP — block review, IP board, blocks, alerts and reports — from a local DB-IP library, display only; new metrics stay quiet until their baseline has measured days behind it (console: "baseline accumulating"); edge 52x judged once for alerts, tiles and reports (Worker bookkeeping vs real outage); expired blocks lifted by the console; block rules placed after skip rules and ahead of challenges, with a bypass warning at review; live hourly check per block and approximate attempts on Free; Worker CPU alerts check themselves (P50 vs P99 vs calls); origin view for VPS sites behind the proxy (origin unreachable 52x, origin latency P95, 5xx rate and status split); IP board (who keeps hitting, last hour and 24 h; verified bots folded, ranges summed), client IPs in the drill-down; "what is rising now": blocked board, trend strip vs yesterday, live faces; e-mail over HTTPS (Resend) where SMTP is blocked; per-zone WAF audit coverage; cross-zone home, block verdicts in the daily report, rule-covered faces marked, audit/rule snapshots; settings in the console (notifications with test sends, alert lines with a replay preview, known faces, network names); console in English or Chinese; WAF basics, rule recipes and plain-words rules; live hour and movers drill-down; web console with in-console blocking, undo, before/after, read-only snapshots and Google / GitHub sign-in; mark-as-known as a compact link. Documentation: https://playwjj.github.io/flarehound/ · Changelog: CHANGELOG.md
Direction: the built-in web console (since v1.3) is the centre of the product — live movers, new faces, history against the long-term baseline, the WAF audit and rules, settings, and in-console blocking with per-account audit. Notifications are the alerting layer that brings you to the console. See the web console revision note.
The detection model, thresholds and alert discipline are ported from a real incident response (a residential-proxy crawler flood, 2026-11-17).
FlareHound watches the traffic itself:
dynamic) responses, origin 5xx, origin reachability and latency (for sites on a VPS behind the proxy), Worker invocations and CPU P50.HEALTHCHECK, so a dead watchdog never looks like a quiet site.data/archive.db, ~13 months of hourly snapshots, daily rollups forever), building the long memory the platform lacks. Once four weeks are archived, a spike must beat both yesterday and the 4-week same-hour median before it alerts — one odd yesterday no longer pages you. New ASNs and user agents are reported with their first-seen date, and every alert is kept in a history table.Releases are published to Docker Hub as multi-arch images (linux/amd64, linux/arm64) on every v* tag, e.g. passport888/flarehound:1.12.0. The docker-compose.yml in this repo pulls the published image (or builds it locally from source if you prefer).
docker compose up -d
config.example.json to config.json, fill in your zone ID and Worker names.export CF_API_TOKEN=...
notify.webhook_url_env at an environment variable holding any endpoint that accepts a JSON POST (Telegram/Slack/Discord bridges included), or configure the Telegram bot.
Native channels (v0.8): Slack, Discord, WeCom (企业微信), Feishu/Lark (飞书, optional signing secret) and email (SMTP with STARTTLS or TLS, or Resend's HTTPS API where SMTP ports are blocked) — set notify.slack_webhook_url_env, discord_webhook_url_env, wecom_webhook_url_env, feishu_webhook_url_env (+ feishu_secret_env), or a notify.email block; every URL and password comes from an environment variable. Long reports are split to each service's size limit, and bot errors returned inside an HTTP 200 count as failures (retried, then queued).
To feed alerts into your own tooling instead, set notify.jsonl_file (e.g. data/alerts.jsonl): every message is appended as one JSON line with kind, zone, decision, the window, the fired rules and the text."report": {"language": "en"} or "zh" (Chinese).Optionally fill the local archive with the last four weeks right away (Cloudflare keeps ~31 days), so the 4-week baseline works from day one instead of week five. It is paced to ~1 query/second and takes about an hour per zone:
flarehound -config config.json -backfill 28
Check the installation — what each token can do, with any missing permission named:
flarehound -config config.json doctor
Try it before going live — this prints the messages instead of sending them:
flarehound -config config.json -once -dry-run # one hourly check
flarehound -config config.json -daily -dry-run # today's daily report
FlareHound · example.com — anomaly
Worker web calls +52.0%, Worker web CPU P50 +50.0%, dynamic +75.0%, zone requests +52.0% (+1 more)
Window 2026-11-17 08:00–09:00 (Asia/Shanghai)
Attribution:
- expensive (Worker/origin) 40,000 → 70,000 (+30,000); cheap (edge cache) 60,000 → 82,000 (+22,000)
- top dynamic paths: /rank 35,000 (was 20,000)
- AS207990 hits: /rank 35,000
Hypotheses:
- [high] Crawler/bot surge: new source AS207990 carries ~87% of the excess.
Falsified if its path mix matches normal visitors and it comes from residential/mobile networks …
Sources are dispersed (top IP < 1% of the excess): per-IP blocking will not help — act at ASN or path level (challenge).
Suggestions (read-only — FlareHound never applies them; do it in the Cloudflare dashboard):
1. Block AS207990 (EXAMPLE-HOSTING-AS, hosting network)
where: Security → WAF → Custom rules, action Block
expression: (ip.geoip.asnum in {207990}) and not cf.client.bot
why: 45,000 requests vs 0 yesterday, ~87% of the excess; a hosting network, where no human visitors are expected.
gain: ~45,000 fewer requests per window, of which ~20,723 expensive (estimate)
impact: anything legitimately running on that network (your own monitors, partner APIs, uptime checkers) is blocked too; …
rollback: disable or delete the rule (takes effect in seconds)
Suggestions come with evidence, expected gain, blast radius, rollback and a paste-ready rule expression. Only cloud/datacenter ASNs are ever suggested for blocking; residential, mobile, backbone and unknown networks get a challenge suggestion instead. No suggestion is made when the evidence is thin, or when the surge is mostly cheap edge-cached traffic.
Create the token at Cloudflare Dashboard → My Profile → API Tokens → Create Token → Custom token:
Optional add-ons — grant only when you enable the feature:
Worker metrics (workers listed in the config): add Account → Account Analytics: Read.
WAF rule audit (v0.6): add Zone → WAF: Read to the same token (optionally Zone: Read for the quota check).
One-click blocking (v0.5) and rule changes (v0.7): create a separate write token — Account → Account Filter Lists: Edit; Zone → WAF: Edit (custom rules; IP Access Rules too on some accounts), DNS: Read, Zone: Read (+ Cache Rules: Edit for cache rules). Put it in CF_WRITE_TOKEN. Never merge it into the read token; the watchdog process never holds it.
Permission names: custom rules always need Zone → WAF. IP Access Rules vary by account — covered by Zone → WAF on some, Firewall Services on others, not grantable on some; they are optional and FlareHound degrades without them. flarehound doctor shows what your tokens can actually reach.
The watchdog makes GraphQL Analytics calls only (api.cloudflare.com/client/v4/graphql), which is why Analytics: Read is enough; older versions of this README also asked for Logs, Zone and Workers Scripts read access, which no code path uses. (This minimum is derived from the code's call sites; a quick check with your own token: create one with only Zone → Analytics: Read and run flarehound -once -dry-run.) The audit will additionally read rulesets through the REST API on the same host. Your token never leaves your machine and is never written to disk or logs by the program.
# config.json: "console": {"enabled": true}
flarehound -config config.json console init-admin --user you # or use the one-time setup link it logs
flarehound -config config.json console # http://127.0.0.1:8640
A separate process from the watch, reading the same archive: the newest hour against the 28-day baseline, biggest risers and fallers by user agent / ASN / uncached path, new faces, history with alerts and blocks on a timeline, the WAF audit and the block list. Built for a phone first. Accounts (admin / viewer) with TOTP; it binds to loopback — reach it through Tailscale, a TLS reverse proxy or Cloudflare Tunnel.
Give the write token to the console process (never the watch) and admins block from it: prefilled from the movers, the same guard rails and review as the CLI, a fresh two-factor code per change, audit under the account before anything is touched, read-back, one-click undo and an automatic before/after comparison. Any view can be frozen into a read-only snapshot with an expiring, revocable share link. People can also sign in with Google or GitHub once they have linked it to their account. See docs/console.md.
With several zones, the home page lists them all, ranked by which needs attention first. Settings live in the console as well — notification channels with test sends (sent by the watch, with its own environment), alert lines previewed against the last 7 days before they apply, known faces and per-ASN network names — and the console speaks English or 中文. Forgotten passwords can be reset by e-mail when mail (SMTP or Resend) and a public base URL are configured.
Alerts name the culprit and print the command that blocks it:
flarehound block asn 207990 --action block --for 24h
flarehound block ip 45.13.7.9
flarehound block country XX --action challenge
flarehound block ua "BadBot/1.0" --for 7d --reason "scraper, 11-17 incident"
flarehound unblock asn 207990
flarehound blocks # everything blocked, with 7-day attempts and expiry
flarehound enforce # optional: lifts expired blocks without a console
Before anything changes you see the exact plan — the rule it edits and the expression afterwards, the custom-rule quota, the target's measured share of the last hour's excess, and every warning — and confirm once. FlareHound only ever edits its own objects (rules named flarehound-…, the IP list flarehound_block), merges each target type into one rule so your quota is barely touched, keeps verified search bots allowed on ASN and country rules, and reads the result back to verify. It refuses to block Cloudflare's ranges, your origin IPs (from DNS), private ranges and anything on your blocking.never_block list. Blocking a residential/backbone ASN or a whole country requires retyping the ASN or country code. Every action lands in an append-only audit log, and the daily report lists each block's attempts — lift a block when the attempts stop, not when it gets quiet.
A console holding the write token lifts expired blocks itself (every 5 minutes); without a console, run flarehound enforce — in Docker docker compose --profile admin up -d starts it with the write token, and docker compose run --rm flarehound-admin block … runs commands.
New to WAF rules? WAF basics (中文) covers order, verified bots, block vs challenge and narrow skips, and the recipes do it for you:
flarehound rules recipes
flarehound rules recipe protect-paths --path '/login*, /admin*'
flarehound audit # ends with "How to fix"
Every rule is explained in plain words (flarehound rules list, the console's WAF rules page), and every change is shown in full, confirmed, backed up and read back.
Suggestions that are rule changes come with the command that applies them, and you can manage custom, rate-limit and cache rules directly:
flarehound rules list [--phase custom|ratelimit|cache]
flarehound rules add --action managed_challenge --expr 'starts_with(http.request.uri.path, "/login")' --desc "challenge login" [--before 1]
flarehound rules edit 3 --enabled false
flarehound rules move 3 --before 1 # or --last
flarehound rules delete 3
flarehound ratelimit add --path '/rank' --requests 20 --period 10
flarehound cache add --path '/assets/*' --ttl 1d
flarehound rules backups # snapshots taken before each change
flarehound rules restore 12 # put a phase back as it was
flarehound rules log # who changed what, verified or not
Every change is shown in full (field-by-field old → new for edits), confirmed by you — there is deliberately no --yes — backed up first (to the archive and to data/backups/<zone>/*.json), read back and compared field by field and by position, and appended to an audit log. Expressions are syntax-checked locally before they are sent; quotas are checked per plan; rules owned by the blocking module are off limits. Cache rules additionally need Zone → Cache Rules: Edit on the write token.
flarehound audit (and a section of every daily report) reads your custom rules — read-only — and checks them like a reviewer would:
path_rules, daily.paths, waf_audit.sensitive_paths, or the zone's own zones[].waf_audit.sensitive_paths) covered by a block/challenge rule? Fully, only conditionally (e.g. only for one user agent), or not at all — or exempted by a skip rule placed ahead of it.MyMonitor in the UA skips your WAF".It ships its own parser for the Cloudflare rules language and evaluates rules with three-valued logic against probe requests, so it only claims what it can show. When the ruleset version changes, the next hourly round re-audits and reports any problem.
FlareHound reads Cloudflare's adaptive analytics, which are sampled and also count Worker subrequests and cache operations; the dashboard does not. Expect FlareHound to count more — on a live zone ≈ 1.29× the dashboard's requests. All thresholds are in FlareHound's units. flarehound calibrate --days 7 shows the ratio per day (requests, cache hits, edge 5xx, sampling) and what min_count means in dashboard terms; every daily report carries a one-line ratio.
Default alert lines (all configurable — these are the battle-tested values from the incident the tool is based on):
| Signal | Default |
|---|---|
| Worker invocations vs. yesterday | +35% |
| Zone requests vs. yesterday | +35% |
| Worker CPU P50 vs. yesterday | +25% |
| Dynamic (uncached) responses vs. yesterday | +50% |
| Origin 5xx | 3× baseline and > 50 |
| Origin unreachable (edge 52x) | ≥ 10 per hour (a healthy origin has none) |
| Origin latency P95 (first byte) | +100% and ≥ 1 s |
| New face in Top 10 (UA or ASN) | > 5,000 requests/hour |
| Collapse in requests or invocations | −50% (re-read after 3 min; still-arriving data is never called a collapse) |
| Volume floor for percentage rules | 1,000 requests per window |
Per-path overrides (path_rules) put a tighter line on sensitive low-volume paths like /login*.
Known false-positive class handled out of the box: legitimate crawlers (Googlebot, Bingbot, Applebot, YandexBot, Baiduspider) bump their user-agent version strings and trip "new face" — FlareHound checks that ≥ 90% of that UA's traffic comes from the crawler's own ASN before excluding it, so impostors still alert. Register your own monitors and services under known_faces.
Alert discipline: one alert when an anomaly starts; one more only if it shows a new signal or a reported signal grows another 25%; one line when two clean rounds pass. Failed deliveries are retried 3 times and then queued on disk for the next round.
Daily report (default 08:00 local): last 24 h vs the 24 h before, cache-cost split, top paths / ASNs / user agents with new ones marked, firewall events per rule, and your fixed checkpoints (daily.paths origin-reach limits, daily.artifacts known accounting artifacts).
The primary form factor is a single Go binary in a Docker container, running on your own VPS, home server or NAS — deliberately not on Cloudflare itself, so the watchdog has no blind spot when the platform it watches is the thing in trouble. The engine only needs outbound HTTPS and a local state file; a Cloudflare Workers (Cron Triggers) deployment adapter is on the roadmap as an alternative.
v0.2 — daily digest (24 h comparison + fixed checkpoints) ✅
v0.3 — full intraday watch (new-face detection, escalation/recovery state machine, attribution queries) ✅
v0.4 — suggestion engine (block / challenge / rate-limit / cache candidates) + local SQLite archive ✅
v0.5 — one-click blocking (IP / CIDR / ASN / country / user-agent — block from an alert or the CLI, expiring blocks, guard rails, audit log) ✅
v0.6 — WAF rule audit (coverage gaps on sensitive paths, ordering/redundancy issues, per-rule hit stats, over-broad exemptions) ✅
v0.7 — general action module (execute approved suggestions with a separate write token, pre-change backup, read-back verification) ✅
v0.8 — more notification channels (Slack, Discord, WeCom, Feishu, email), parallel multi-zone checks ✅
v1.0 — calibration against the dashboard (flarehound calibrate), documentation site, first stable release ✅
v1.3 — read-only web console (overview vs baseline, movers, new faces, history, WAF audit, blocks) with built-in accounts and two-factor sign-in ✅
v1.4 — blocking from the console (write token only in the console process, guard-rail confirmation, before/after effect, undo, read-only snapshots) ✅
v1.5 — Google / GitHub sign-in bound to local accounts ✅
v1.7 — WAF basics and rule recipes, plain-words rule explanations; live hour and movers drill-down; TOTP setup by QR code and password reset by e-mail ✅
v1.8 — console language switch (English / 中文) ✅
v1.9 — settings in the console (notifications with test sends, alert lines with a replay preview, known faces) and network names ✅
v1.10 — cross-zone home, block verdicts, rule-covered faces marked, snapshots of the WAF audit and the rules ✅
v1.11 — WAF audit coverage per zone (each zone's own hosts and sensitive paths) ✅
v1.12 — e-mail over HTTPS (Resend) where outbound SMTP is blocked ✅
verifiedBotCategory instead.MIT © 2026 playwjj
Content type
Image
Digest
sha256:b25307d75…
Size
20.6 MB
Last updated
about 1 hour ago
docker pull passport888/flarehound