Detection¶
FlareHound's detection is deterministic: the same two windows always produce the same findings. There is no AI in the detection path.
Windows and schedule¶
- Intraday watch —
schedule.intraday_offset(default 7 min) after every interval boundary, FlareHound compares the last full clock window (default one hour) with the same window yesterday. The state file records the last evaluated window, so a restart never evaluates the same window twice. On start-up it catches up on the newest settled window right away. - Daily report — at
schedule.daily_report_at(default 08:00, inschedule.timezone): the last 24 hours vs. the 24 hours before. See Reports. - Several zones are checked in parallel, at most
schedule.max_parallel_zones(default 4) at a time, each with its own state file.
What is measured¶
Each window, for each zone (Cloudflare GraphQL Analytics, httpRequestsAdaptiveGroups and workersInvocationsAdaptive):
- Zone requests (total).
- Requests with
cacheStatus = "dynamic"— the expensive, uncached part. - Origin 5xx (
originResponseStatus500–599), split by status (502 / 503 / 504 …) and as a share of the requests the origin answered. - Origin unreachable — the edge's own 52x answers (
edgeResponseStatus520–526 and 530): Cloudflare could not reach the origin at all (521 refused, 522/524 timed out, 523 no route, 525/526 TLS). The origin answered nothing, so these never show up as origin 5xx. - Origin latency — P95 time to first byte (
originResponseHeaderReceiveDurationMs: the application computing) and of the full response (originResponseDurationMs: plus transfer), with TCP/TLS connect P95s as detail. Read over the requests the origin actually answered (originResponseStatus > 0); cache hits would pull the quantiles to 0. Available on every plan, Free included; where the API does not answer, latency is "not measured" and the round goes on. - Per configured Worker: invocations and CPU P50 / P99 (one query).
- Top user agents and Top ASNs — Top 10 for the current window, Top 25 for the baseline ("old faces").
- Per
path_rulesentry: requests matching the path (optionallydynamiconly).
Alert lines¶
Any line crossed puts the zone into an anomaly. Defaults (all configurable under thresholds):
| Rule | Fires when | Default |
|---|---|---|
total_up |
Zone requests rise ≥ total_up_pct and the current window ≥ min_count |
+35% |
dynamic_up |
Dynamic responses rise ≥ dynamic_up_pct, current ≥ min_count |
+50% |
worker_calls_up |
A Worker's invocations rise ≥ worker_calls_up_pct, current ≥ min_count |
+35% |
cpu_p50_up |
A Worker's CPU P50 rises ≥ cpu_p50_up_pct; both windows' invocations ≥ min_count. The line carries P50, P99 and calls changes and their reading (see below) |
+25% |
origin_5xx |
Origin 5xx > origin_5xx_min and ≥ origin_5xx_multiplier × baseline |
3× and > 50 |
origin_unreachable |
Edge 52x ≥ unreachable_min and ≥ 2× baseline (normally 0). Against a 522/524 bookkeeping background (Worker zones): ≥ 3× the background, other 52x statuses rising, or the origin no longer answering — see below |
≥ 10 |
origin_slow |
The origin's first-byte P95 rises ≥ origin_slow_up_pct and reaches origin_slow_min_ms; both windows ≥ 100 origin-answered requests. Reported as ttfb — or as total when only the full response slowed (transfer: large bodies, bandwidth) |
+100% and ≥ 1 s |
collapse_total / collapse_worker |
Requests / invocations drop ≥ collapse_down_pct, baseline ≥ min_count |
−50% |
new_face_ua / new_face_asn |
A UA / ASN in the current Top 10, absent from the baseline Top 25, with more than new_face_min_count requests |
> 5,000 |
path_up |
A path_rules path rises ≥ its up_pct, current ≥ its min_count |
+100%, ≥ 20 |
Origin view: Worker sites and VPS sites¶
The same flood costs a Worker site money (the platform absorbs it; the bill comes later) and a site on one VPS behind the proxy its availability (PHP workers fill up, the site goes down). For the VPS the earliest symptom is a slower origin — hours before the first 5xx — and 52x means it is already down. Both lines are high severity; their hypotheses separate slower under more uncached load (dynamic or total up, new faces) from slower with load flat (application, database, the machine itself), and first byte from transfer.
FlareHound only sees the edge: database locks, a full disk or memory pressure on the VPS are visible only as their effect on these numbers. Adaptive data is sampled — fit for trends and alerts, not SLA accounting.
min_count (default 1,000) exists because on a small site 10 → 40 requests is +300%; without a floor, quiet alerting is impossible.
Edge 52x: outage or bookkeeping?¶
On Worker zones the adaptive dataset files Cache API entries with edge statuses; an edge timeout on such an entry reads 522/524. Hundreds an hour are then background while the site is fine. One judgement, shared by the alert line, the console tile and the reports:
- Bookkeeping background — the baseline's 52x are ≥ 90% 522/524 and the window does not depart from it: no alert, a neutral tile (Edge 52x (bookkeeping background)), and a "check: bookkeeping background" line in reports.
- Departure from such a background — ≥ 3× its volume (by at least
unreachable_min), other statuses (521, 523, 530 …) at ≥ 10% and ≥unreachable_min, or origin-answered requests below half the baseline: the line fires, with the status split and the reason. - Any other baseline (normally zero, or led by other statuses) keeps the plain rule.
Hours archived before v1.15 did not measure 52x; the long baseline skips them rather than reading them as zero.
New metrics: baseline maturity¶
A line read against the archive's same-hour median is only as good as the measured hours behind it. When a metric is new (52x and origin latency since v1.15, the CPU P99 since v1.16), the archive holds weeks of hours that never measured it: the median rests on one or two hours, or on none, and any ordinary hour clears the line. So each such line counts the measured same-hour samples behind its baseline (the same hour on earlier days; a measured 0 counts, an hour that did not measure the metric does not):
- Fewer than
thresholds.baseline_min_samples(default 3): immature.origin_unreachable(plain and bookkeeping rule) andorigin_slowdo not fire, even when only yesterday's hour would decide; the watch logs the finding as held. The CPU check treats an immature P99 as not measured. The console tile reads baseline accumulating (N/3 days of this hour measured), neutral; the first daily report after the metric started says so once;doctorlists the counts per zone. - From then on the line is judged by the rules above, with no manual step.
- Alerts archived while their only lines were immature (sent by older versions) are not counted as anomalies in the console and are marked as such on the timeline.
Comparisons of two live windows (yesterday's same hour, the daily report's two days) do not depend on the archive and are not gated — except that the gated lines above need a mature archive baseline before they fire at all. 0 turns the gate off.
Worker CPU: more expensive, or a different mix?¶
A median can rise without any call getting slower: when a flood of cheap calls recedes, the calls left are the heavier ones. Every CPU line therefore carries P50, P99 and calls and reads them:
- P50 and P99 up together, calls not down (more than −10%): really more expensive — a code change, a slower dependency, heavier requests. High severity.
- P50 up, P99 up less than half as much, calls down ≥ 10%: mix change — reported, at low severity, with its own hypothesis.
- Anything else, or no P99 in one window (hours archived before v1.16): undecided; the earlier reading stays.
Collapse needs settled data¶
Fresh windows are under-counted while analytics are still ingesting. When a round shows a collapse, FlareHound waits schedule.settle_delay (default 3 min) and re-reads the window. If the count grew by more than 2%, the data was still arriving: the collapse is withheld this round and noted as "data not settled".
Long baseline¶
Once the archive holds at least 20 same-hour samples from the last 28 days, a volume finding (requests, dynamic, 5xx, Worker, CPU, collapse, path) must cross its line against yesterday and against the per-metric median of those samples. One odd yesterday no longer pages you. New-face findings are not subject to this check. Alerts show the long-baseline values and sample count.
New faces and crawler verification¶
Legitimate crawlers change their UA version strings and look "new". A new UA that claims to be a known crawler is verified before it is excluded:
| Crawler | UA markers include | Own ASNs |
|---|---|---|
| Googlebot | googlebot, adsbot-google, mediapartners-google, … |
15169 |
| Bingbot | bingbot, adidxbot, bingpreview |
8075 |
| Applebot | applebot |
714, 6185 |
| YandexBot | yandexbot, yandex.com/bots |
13238, 208722 |
| Baiduspider | baiduspider |
55967, 38365 |
FlareHound prefers Cloudflare's own verifiedBotCategory; where that is unavailable it falls back to the crawler's ASNs. The claim is accepted when ≥ 90% of the UA's requests pass. A UA that fails with data to judge on is reported as an impostor — a disguised scraper. If neither method is available, nothing is excluded.
Register your own monitors and services under known_faces; they never count as new faces.
Alert discipline¶
The state machine (persisted in state_file) turns findings into at most one message per round:
| Decision | When |
|---|---|
alert |
First finding: an anomaly episode starts. |
changed |
During the episode, a signal appears that the episode has not shown before. |
escalate |
A reported signal grows another escalation_pct (default 25%) past its reported peak. Collapses never escalate — recovering numbers are not worse. |
recovered |
recovery_clean_rounds (default 2) consecutive rounds without any finding. One short line; the episode ends. |
A signal is the rule plus its subject (Worker, path rule, ASN). All new-face UAs share one signal, because crawlers rotate UA strings (three batches in one day in the field); ASNs are stable, so each new ASN is a new signal. A signal dipping below its line and crossing again within the same episode does not re-alert.
Plan capabilities¶
On first use per zone, FlareHound probes which dimensions and datasets the plan exposes and never queries unavailable fields. Missing pieces are logged as not available on this plan, degraded: …:
- No
clientAsn(Free): no ASN Top lists, new-ASN detection off, no ASN suggestions; the daily report says so. - No
clientASNDescription(Free): network type comes from the built-in table only. - No firewall events dataset (Free): firewall events and block attempts show "n/a", never 0.
- If the probe itself fails, FlareHound assumes everything is available and probes again next round.
See Limitations for what this means in practice.