Skip to content

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_db at it. IPv4 and IPv6 are both covered.
  • Updating. flarehound geoip update downloads the newest DB-IP lite file, checks that it reads as a country library, and atomically replaces geoip.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 doctor says 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