Configuration reference¶
FlareHound reads one JSON file (-config, default config.json). Every key is optional unless marked required; a key left out keeps its default — a missing threshold is never treated as 0. Secrets are never stored in the file: *_env keys name the environment variable that holds the value.
A complete example is config.example.json in the repository. Validation errors stop the process at startup with a message naming the key.
cloudflare¶
| Key | Type | Default | Meaning |
|---|---|---|---|
cloudflare.account_id |
string | "" |
32-char hex account ID. Required when any zone lists workers. Also used by blocking for the account IP list (without it, IP blocks use an expression rule). |
cloudflare.api_token_env |
string | "CF_API_TOKEN" |
Environment variable holding the read token. Startup fails if it is empty. |
cloudflare.zones |
array | — | Required, at least one zone. |
cloudflare.zones[].zone_id |
string | — | Required. 32-char hex zone ID. |
cloudflare.zones[].name |
string | the zone ID | Display name; also the default WAF-audit probe host and the --zone selector. |
cloudflare.zones[].workers |
string[] | [] |
Worker script names to watch (invocations and CPU P50 / P99). Each is evaluated separately. Needs Account Analytics: Read. |
cloudflare.zones[].waf_audit.hosts |
string[] | global hosts in this zone, else the zone name | This zone's WAF-audit probe hosts. Each must be the zone or a subdomain of it. |
cloudflare.zones[].waf_audit.sensitive_paths |
string[] | — | This zone's whole sensitive-path list for the coverage check. When set (even []), the default list is not used for this zone. |
schedule¶
| Key | Type | Default | Meaning |
|---|---|---|---|
schedule.intraday_interval |
duration | "1h" |
Watch interval and window length. Must be a whole number of hours (windows are full clock hours). |
schedule.intraday_offset |
duration | "7m" |
How long after the hour boundary the check runs, absorbing analytics ingestion lag. Must be within [0, 1h). |
schedule.settle_delay |
duration | "3m" |
Wait before re-reading a window that looks collapsed, to tell ingestion lag from a real drop. |
schedule.daily_report_at |
"HH:MM" |
"08:00" |
Local time of the daily report. Empty string disables it. |
schedule.timezone |
string | host local time | IANA name, e.g. "Asia/Shanghai". The image embeds the zone database. |
schedule.max_parallel_zones |
int | 4 |
How many zones are checked at once. Allowed: 1–16. |
Durations use Go syntax (90s, 7m, 2h).
thresholds¶
Detection lines; see Detection for how each is applied.
| Key | Type | Default | Meaning |
|---|---|---|---|
thresholds.total_up_pct |
number | 35 |
Zone requests vs. baseline, % increase. |
thresholds.worker_calls_up_pct |
number | 35 |
Worker invocations, % increase. |
thresholds.cpu_p50_up_pct |
number | 25 |
Worker CPU P50, % increase. |
thresholds.dynamic_up_pct |
number | 50 |
Uncached (dynamic) responses, % increase. |
thresholds.origin_5xx_multiplier |
number | 3 |
Origin 5xx must reach this multiple of the baseline … |
thresholds.origin_5xx_min |
int | 50 |
… and exceed this absolute count. |
thresholds.new_face_min_count |
int | 5000 |
A new user agent / ASN in the Top 10 must exceed this many requests in the window. |
thresholds.collapse_down_pct |
number | 50 |
Requests or invocations, % drop. |
thresholds.min_count |
int | 1000 |
Volume floor for percentage rules: the current window (rises) or baseline (drops) must reach it; CPU P50 needs both windows' invocations ≥ it. |
thresholds.escalation_pct |
number | 25 |
An already reported signal re-alerts only after growing this % past its reported peak. |
thresholds.recovery_clean_rounds |
int | 2 |
Consecutive clean rounds before the "recovered" message. |
thresholds.origin_slow_up_pct |
number | 100 |
Origin latency P95 (first byte, else full response) vs. baseline, % increase … |
thresholds.origin_slow_min_ms |
number | 1000 |
… and the current P95 at least this many ms (40 → 80 ms is not news). |
thresholds.unreachable_min |
int | 10 |
Edge 52x (origin unreachable) per window before it alerts. |
thresholds.baseline_min_samples |
int | 3 |
Measured days of the same hour a new metric's archive baseline needs before its lines (origin_unreachable, origin_slow, the CPU P99 check) may fire — see baseline maturity. 0 turns the gate off. |
path_rules¶
Per-path lines for sensitive, low-volume paths whose anomalies would drown in zone totals.
| Key | Type | Default | Meaning |
|---|---|---|---|
path_rules[].name |
string | the path | Signal name in alerts. |
path_rules[].path |
string | — | Required. Must start with /; * is a wildcard (/login*). |
path_rules[].up_pct |
number | 100 |
% increase vs. baseline. |
path_rules[].min_count |
int | 20 |
Volume floor in the current window. |
path_rules[].dynamic_only |
bool | false |
Count only uncached (dynamic) requests — the path's real rendering load. |
Path rules are also sensitive paths for suggestions and the WAF audit. Each one adds a query per window.
daily¶
Fixed checkpoints of the daily report.
| Key | Type | Default | Meaning |
|---|---|---|---|
daily.paths[].label |
string | the path | Checkpoint name. |
daily.paths[].path |
string | — | Required. Must start with /; * wildcard. Also a sensitive path. |
daily.paths[].max |
int | 0 |
Maximum origin reach (requests not served from edge cache) over 24 h; above it the line is marked ⚠. |
daily.artifacts[].label |
string | "" |
Name of a known accounting artifact. |
daily.artifacts[].path |
string | "" |
Path pattern (* wildcard). |
daily.artifacts[].edge_status |
int | 0 |
Edge status to count (e.g. 504); 0 counts any status. |
known_faces¶
Sources that never count as new faces.
| Key | Type | Default | Meaning |
|---|---|---|---|
known_faces.asns |
int[] | [] |
ASNs (your monitors, partners, your own services). |
known_faces.user_agents |
string[] | [] |
Case-insensitive user-agent substrings. |
rule_names¶
| Key | Type | Default | Meaning |
|---|---|---|---|
rule_names |
object | {} |
Map of firewall rule ID → display name in reports. With WAF: Read, names come from the rule descriptions automatically; this map overrides them. |
report¶
| Key | Type | Default | Meaning |
|---|---|---|---|
report.language |
string | "en" |
"en" or "zh" (Chinese): reports and notifications, and the console's default language (each person can switch the console with its EN / 中文 button). |
report.visuals (bool, default true): attach charts and send email as HTML — see charts and HTML.
notify¶
All channels are optional and can be combined; with none configured, findings appear only in the log. Details per channel: Notification channels.
| Key | Type | Default | Meaning |
|---|---|---|---|
notify.webhook_url_env |
string | "" |
Variable holding a generic webhook URL. Takes precedence over webhook_url. |
notify.webhook_url |
string | "" |
Plain-text webhook URL, kept for compatibility. Prefer webhook_url_env. |
notify.telegram_bot_token_env |
string | "" |
Variable holding the Telegram bot token. |
notify.telegram_chat_id |
string | "" |
Telegram chat ID. Telegram is active only when both are set. |
notify.jsonl_file |
string | "" |
Append every message as one JSON line to this file (mode 0644). Also receives a heartbeat record every round. Rotated at 32 MB, 3 rotated copies kept; charts saved next to it are removed after 90 days (details). |
notify.heartbeat_url_env |
string | "" |
Variable holding a healthchecks.io-style URL pinged after every round (/fail when a zone errored). Startup fails if named but empty. See heartbeat. |
notify.slack_webhook_url_env |
string | "" |
Variable holding a Slack incoming-webhook URL. |
notify.discord_webhook_url_env |
string | "" |
Variable holding a Discord webhook URL. |
notify.wecom_webhook_url_env |
string | "" |
Variable holding a WeCom (企业微信) group-bot URL. |
notify.feishu_webhook_url_env |
string | "" |
Variable holding a Feishu / Lark custom-bot URL. |
notify.feishu_secret_env |
string | "" |
Variable holding the Feishu signing secret (optional). |
notify.email |
object | absent | E-mail channel (SMTP or Resend's HTTP API); see below. |
For Slack, Discord, WeCom and Feishu, naming a variable that is empty is a startup error.
notify.email:
| Key | Type | Default | Meaning |
|---|---|---|---|
provider |
string | "smtp" |
smtp, or resend to send over HTTPS through Resend (for hosts whose outbound SMTP ports are blocked). |
api_key_env |
string | "" |
resend only, required there: variable holding the Resend API key. |
smtp_host |
string | — | Required for smtp; unused by resend (as are smtp_port, tls, username, password_env). |
smtp_port |
int | by tls: 587 / 465 / 25 |
SMTP port. |
tls |
string | "starttls" |
starttls, tls (implicit TLS) or none (local relays only). |
username |
string | "" |
SMTP user; when set, password_env must name a non-empty variable. |
password_env |
string | "" |
Variable holding the SMTP password. |
from |
string | — | Required. Sender address. |
to |
string[] | — | Required, at least one recipient. |
state_file¶
| Key | Type | Default | Meaning |
|---|---|---|---|
state_file |
string | "data/state.json" |
Alert state machine file. With several zones, each zone gets its own file derived from it (data/state-example-com.json). Its directory is the data directory: the notification outbox (outbox.json), rule backups (backups/) and the default archive live there. Relative paths are relative to the working directory (/app in the image). |
blocking¶
| Key | Type | Default | Meaning |
|---|---|---|---|
blocking.write_token_env |
string | "CF_WRITE_TOKEN" |
Variable holding the separate write token. Must differ from cloudflare.api_token_env. Read only by blocking and rule-change commands. |
blocking.never_block |
string[] | [] |
IPs / CIDRs that are never blocked or offered as block candidates. Each must parse as an IP or CIDR. |
blocking.never_block_asns |
int[] | [] |
ASNs never blocked or suggested for blocking. |
waf_audit¶
| Key | Type | Default | Meaning |
|---|---|---|---|
waf_audit.disabled |
bool | false |
Turn the WAF audit off (daily section, re-audit on change, flarehound audit). |
waf_audit.hosts |
string[] | the zone name | Hosts to probe; rules often pin http.host, so coverage is judged per host. |
waf_audit.sensitive_paths |
string[] | [] |
Extra sensitive path patterns, in addition to path_rules and daily.paths. |
With several zones, each zone probes only the waf_audit.hosts that belong to it (the zone or its subdomains). The default sensitive list (path_rules + daily.paths + waf_audit.sensitive_paths) applies only to the zones those hosts belong to — or, with no global hosts, to the first zone. Give every other zone its own list; until then its audit says coverage is not configured instead of scoring another site's paths:
"zones": [
{ "name": "example.com", "zone_id": "…" },
{ "name": "blog.example.org", "zone_id": "…",
"waf_audit": { "sensitive_paths": ["/wp-login.php", "/wp-admin*", "/xmlrpc.php"] } }
]
archive¶
| Key | Type | Default | Meaning |
|---|---|---|---|
archive.disabled |
bool | false |
Turn the local SQLite archive off. -backfill, block --for and the rule-change commands need it. |
archive.file |
string | <data dir>/archive.db |
Archive path. |
archive.hourly_retention_days |
int | 400 |
Days to keep hourly snapshots (about 13 months), archived alerts and faces not seen since. Minimum 30. Daily snapshots, the block log and rule backups/changes are kept forever. See disk space. |
geoip¶
IP location (v1.17): each IP FlareHound shows — the IP board, the drill-down, the block review, the blocks list, alerts, the daily report and flarehound blocks — is followed by the country it is registered or routed in, read from a local MMDB country library. Display only: the country never takes part in detection, alerts, severity or block plans, and it is looked up when shown, never archived (a newer library may place an address differently).
| Key | Type | Default | Meaning |
|---|---|---|---|
geoip.country_db |
string | — | Path of the country library (MMDB). Empty: <data dir>/country.mmdb, then the library the Docker image ships (/usr/share/flarehound/country.mmdb). |
- Library. The default is DB-IP's free IP to Country Lite (monthly, CC BY 4.0 — IP geolocation by DB-IP); the Docker image bundles the month it was built in. MaxMind's GeoLite2-Country also works, but its licence does not allow FlareHound to ship it: download it yourself and point
geoip.country_dbat it. IPv4 and IPv6 are both covered. - Updating.
flarehound geoip updatedownloads the newest DB-IP lite file, checks that it reads as a country library, and atomically replacesgeoip.country_db(or<data dir>/country.mmdb, which outranks the image's copy). It needs no token. Running processes pick the new file up within 10 minutes. Country assignments change slowly: a library a few months old is fine, and nothing forces an update. - Missing or broken library: the feature is off, silently — every IP is shown exactly as before and nothing else changes.
flarehound doctorsays which library is loaded (type, build date, file date, networks), that none was found, or why a file could not be used. - What it means. IP location is where the address is registered or routed, not where its operator is: a residential proxy's exit country says nothing about who drives it, and a data-centre address shows the data centre. It is one cheap piece of context next to the network (ASN) and the volume, not a verdict.
console¶
The web console (v1.3, read-only) — see Web console.
| Key | Type | Default | Meaning |
|---|---|---|---|
console.enabled |
bool | false |
flarehound console refuses to start unless this is true. |
console.listen |
string | 127.0.0.1:8640 |
Listen address. Keep it on loopback and reach it through Tailscale, a TLS reverse proxy or Cloudflare Tunnel: FlareHound does no TLS. |
console.db_file |
string | <data dir>/console.db |
Accounts and sessions (file mode 0600). The watch never opens it. |
console.base_url |
string | — | How people reach the console, e.g. https://hound.example.ts.net. When set, notifications carry a deep link to the matching view, and invitation, password-reset and sign-in callback links use it. Together with notify.email, it turns on password reset by e-mail. |
console.refresh_seconds |
int | 300 |
Auto-refresh of the live views. Minimum 30. |
console.session_hours |
int | 12 |
Idle lifetime of a sign-in session (1–720). |
console.snapshots |
string | admins |
Who may create read-only snapshots (shareable links that need no sign-in): admins, everyone or off. |
console.require_totp |
bool | false |
Every account must set up two-factor sign-in before using the console. |
console.trusted_proxies |
list | [] |
IPs / CIDRs of reverse proxies in front of the console. Only these may set X-Forwarded-For, X-Forwarded-Proto or the proxy identity header. |
console.proxy_auth.header |
string | — | Trust an identity header injected by an authenticating proxy (e.g. Cf-Access-Authenticated-User-Email). Requires trusted_proxies. |
console.proxy_auth.default_role |
string | viewer |
Role for proxy identities that match no local account: viewer or none (refuse). |
console.proxy_auth.disable_login |
bool | false |
Turn the built-in password sign-in off (proxy identities only). |
console.oauth.google |
object | — | Google sign-in: {"client_id": "…", "client_secret_env": "GOOGLE_OAUTH_SECRET"}. Needs base_url. See third-party sign-in. |
console.oauth.github |
object | — | GitHub sign-in: {"client_id": "…", "client_secret_env": "GITHUB_OAUTH_SECRET"}. Needs base_url. |
asn_names¶
Short names for networks, used in notifications and the console instead of the registered name (the network type is still judged from the registered name):
"asn_names": { "45102": "aliyun", "4837": "联通骨干", "207990": "HostRoyale" }
Names can also be set in the console (Settings → Network names, or name it next to any ASN).
Settings changed in the console¶
Notifications (channel switches, non-secret parameters, variable names), thresholds, known_faces additions and asn_names can be changed in the console. Those changes live in settings.json in the data directory and are applied on top of this file at every load; the watch re-reads them before each round. This file is never modified. See Web console → Settings.
Environment variables at a glance¶
| Variable (default name) | Set by key | Used by |
|---|---|---|
CF_API_TOKEN |
cloudflare.api_token_env |
Watchdog and all commands |
CF_WRITE_TOKEN |
blocking.write_token_env |
block, unblock, blocks, enforce, rules, ratelimit, cache |
| (your names) | notify.*_env, notify.email.password_env / api_key_env |
Notification channels; notify.heartbeat_url_env for the heartbeat ping |