Configuration Reference

Complete reference for all configuration keys in seerflow.yaml. All settings are optional — sensible defaults apply when omitted.

Configuration File

Seerflow loads configuration from seerflow.yaml in the current working directory. If no file is found, sensible defaults are used.

Environment Variables

All string values support ${VAR} and ${VAR:-default} interpolation:

storage:
  postgresql_url: ${DATABASE_URL:-postgresql://localhost/seerflow}
receivers:
  webhooks:
    - auth_token: ${GITHUB_WEBHOOK_SECRET}

Top-level

Key	Type	Default	Description
dashboard_port	int	8080	HTTP port for the Seerflow dashboard UI, REST API, and WebSocket.
health_bind_address	string	"127.0.0.1"	Bind address for the health endpoint. Set 0.0.0.0 for container access.
log_level	string	"INFO"	Application log verbosity. One of DEBUG, INFO, WARNING, ERROR, CRITICAL.

storage

Key	Type	Default	Description
backend	string	"sqlite"	Storage engine. sqlite (zero-config) or postgresql (production scale).
data_dir	string	~/.local/share/seerflow	Root data directory. Respects $XDG_DATA_HOME and $SEERFLOW_DATA_DIR.
sqlite_path	string	<data_dir>/seerflow.db	Absolute path to the SQLite database file. Derived from data_dir when omitted.
postgresql_url	string	""	PostgreSQL DSN, e.g. postgresql://user:pass@host/db. Required when backend=postgresql. Supports ${ENV_VAR} interpolation.
postgresql_pool_min_size	int	2	asyncpg pool floor (>= 1). Only used when backend=postgresql.
postgresql_pool_max_size	int	10	asyncpg pool ceiling (>= pool_min_size).
postgresql_command_timeout_s	float	30.0	Per-query timeout in seconds (must be > 0).
graph_backend	string	"igraph"	Entity-graph backend. One of igraph, falkordb, postgres_age.
falkordb_url	string	""	FalkorDB connection URL, e.g. falkor://host:6379. Required when graph_backend=falkordb. Install with uv sync --extra graph-falkordb.

postgres_age reuses postgresql_url and requires the AGE extension to be installed on the server (CREATE EXTENSION age). Install with uv sync --extra graph-postgres-age. To move a graph between backends use seerflow graph migrate --from <a> --to <b>.

receivers

Network binding

Key	Type	Default	Description
bind_addr	string	"0.0.0.0"	IP address all receivers bind to. Set to 127.0.0.1 to restrict to localhost.
queue_maxsize	int	10000	Maximum events in the internal receiver queue before back-pressure is applied.

Syslog

Key	Type	Default	Description
syslog_enabled	bool	true	Enable the syslog listener (both UDP and TCP when their respective flags are set).
syslog_udp_port	int	514	UDP port for syslog (RFC 3164 / RFC 5424).
syslog_tcp_port	int	601	TCP port for syslog (RFC 6587).
syslog_tcp_enabled	bool	true	Enable TCP syslog. Set false to accept UDP only while syslog_enabled=true.

OpenTelemetry gRPC

Key	Type	Default	Description
otlp_grpc_enabled	bool	true	Enable the OTLP/gRPC receiver.
otlp_grpc_port	int	4317	gRPC port (standard OTLP port).
otlp_grpc_max_workers	int	4	Thread-pool size for the gRPC server.

OpenTelemetry HTTP

Key	Type	Default	Description
otlp_http_enabled	bool	true	Enable the OTLP/HTTP receiver.
otlp_http_port	int	4318	HTTP port (standard OTLP/HTTP port).
otlp_http_max_request_bytes	int	4194304	Maximum allowed request body size in bytes (default 4 MiB). Raise for high-volume batches.

File tailing

Key	Type	Default	Description
file_paths	list[string]	[]	Glob patterns for log files to tail, e.g. /var/log/*.log.
file_checkpoint_dir	string	""	Directory to persist tail offsets across restarts. Empty string disables checkpointing.
file_debounce_ms	int	1600	Milliseconds to wait after the last write event before re-reading a file.
allowed_log_roots	list[string]	[]	Security allowlist: file_paths must fall under one of these directory prefixes.

Webhook HTTP receiver

Key	Type	Default	Description
webhook_enabled	bool	false	Enable the inbound HTTP webhook listener.
webhook_port	int	8081	Port for the webhook HTTP server. Must be 1-65535.
webhooks	list[mapping]	[]	Per-endpoint webhook configurations (see sub-table below).

receivers.webhooks[]

Key	Type	Default	Description
path	string	"/ingest/webhook"	URL path that this endpoint listens on.
auth_header	string	""	HTTP header name used for token authentication. Must be paired with auth_token.
auth_token	string	""	Expected token value. Supports ${ENV_VAR} interpolation. Must be paired with auth_header.
field_mapping	mapping	{}	Maps Seerflow field names to JSON path keys in the incoming payload.
source_id	string	"webhook"	Identifier applied to events received on this endpoint.

detection

Sigma

Key	Type	Default	Description
sigma_rules_dirs	list[string]	[]	Additional directories containing custom Sigma rule YAML files. Loaded alongside the 63 bundled rules.
sigma_custom_upload_dir	string	null	Directory the dashboard upload UI persists Sigma rules into. Always discovered at startup.
attack_mappings	list[mapping]	[]	Per-rule overrides for MITRE ATT&CK tags.

Half-Space Trees (content anomalies)

Key	Type	Default	Description
hst_window_size	int	1000	Sliding window size.
hst_n_trees	int	25	Number of trees in the ensemble.

biDSPOT (auto-thresholds)

Key	Type	Default	Description
dspot.calibration_window	int	1000	Minimum events required before DSPOT activates.
dspot.risk_level	float	0.0001	Target false-positive rate (1 alert per 10,000 normal events).
dspot.initial_percentile	int	98	Percentile used to seed the initial threshold.
dspot_threshold_cap_multiplier	float	5.0	Hard cap on threshold growth (× the initial value). Stops runaway drift.

Holt-Winters (volume anomalies)

Key	Type	Default	Description
hw_seasonal_period	int	1440	Bucket count for one season (minutes in a day).
hw_alpha	float	0.3	Level smoothing factor.
hw_beta	float	0.1	Trend smoothing factor.
hw_gamma	float	0.1	Seasonal smoothing factor.
hw_n_std	float	3.0	Standard-deviation multiplier for the anomaly band.

CUSUM (change points)

Key	Type	Default	Description
cusum_drift	float	0.5	Allowable drift before accumulating a deviation.
cusum_threshold	float	5.0	Cumulative-sum threshold that flags a change.
cusum_ema_alpha	float	0.1	EMA smoothing factor for the baseline.
cusum_warmup_buckets	int	30	Buckets observed before CUSUM is allowed to fire.

Markov (sequence anomalies)

Key	Type	Default	Description
markov_smoothing	float	1e-6	Laplace smoothing applied to transition probabilities.
markov_min_events	int	100	Minimum events per entity before scoring is enabled.
markov_max_entities	int	1000	Per-source cap on entities held in memory.

Blended score weights

DetectionEnsemble blends the four ML scores. Weights do NOT need to sum to 1.0 — the blender divides by their sum.

Key	Type	Default	Purpose
weights_content	float	0.30	Half-Space Trees.
weights_volume	float	0.25	Holt-Winters.
weights_sequence	float	0.25	Markov chain.
weights_pattern	float	0.20	CUSUM.
weights_template_volume	float	0.15	Holt-Winters keyed on Drain3 template.
weights_entity_volume	float	0.15	Holt-Winters keyed on entity.

Risk register + graph cadence

Key	Type	Default	Description
risk_half_life_hours	int	4	Exponential decay half-life on accumulated entity risk.
risk_threshold	float	50.0	Risk score at which an alert fires.
risk_max_entities	int	10000	Cap on entities held in the risk register.
graph_algo_interval	int	500	Re-run graph algorithms (PageRank, Louvain, etc.) every N events.

Throughput knobs

Key	Type	Default	Description
max_sources	int	256	Max distinct sources tracked by detectors.
score_interval	int	1	Score every Nth event per source. 1 = every event.
min_events_for_scoring	int	50	Events observed per source before scoring engages.
max_template_hw	int	500	Max Drain3 templates tracked by per-template volume detector.
max_entity_hw	int	500	Max entities tracked by per-entity volume detector.
model_save_interval_seconds	int	300	Period between ML model state checkpoints.

correlation

Cross-source correlation engine — sliding window + risk register + graph-structural scoring.

Key	Type	Default	Description
window_duration_seconds	int	1800	Per-entity sliding-window duration (30 minutes).
max_events_per_entity	int	1000	Cap on events retained per entity inside the window.
max_entities	int	10000	Cap on entities held in memory by the correlation engine.
late_tolerance_seconds	int	30	Watermark tolerance for out-of-order / late-arriving events.
rule_dirs	list[string]	[]	Extra directories containing custom correlation rule YAMLs.

correlation.graph_structural

Key	Type	Default	Description
community_crossing_enabled	bool	true	Flag edges that cross detected igraph communities.
betweenness_threshold	float	0.3	Minimum normalized betweenness centrality to flag a bridge entity.
fan_out_sigma	float	3.0	Standard-deviation multiplier above per-entity fan-out history to flag.
fan_out_min_floor	int	5	Minimum fan-out value before fan-out scoring engages.
fan_out_history_size	int	20	Rolling history length used for fan-out statistics.

correlation.kill_chain

Key	Type	Default	Description
enabled	bool	true	Enable MITRE ATT&CK tactic-progression detection.
tactic_threshold	int	3	Distinct tactics within window_seconds required to fire.
window_seconds	int	86400	Time window for tactic progression (24h).
max_entities	int	10000	Memory cap.

ueba

User and Entity Behaviour Analytics — per-entity baselines.

Key	Type	Default	Description
enabled	bool	true	Master switch for the UEBA engine.
warmup_days	int	7	Days of observation before scoring kicks in for a new entity.
warmup_min_events	int	50	Minimum events observed before scoring kicks in.
max_entities	int	100000	Entity cap for UEBA state.
ema_alpha	float	0.05	Exponential-moving-average smoothing factor.
source_ip_cap	int	64	Max distinct source IPs tracked per entity.
template_top_k	int	32	Top-K Drain3 templates retained per entity.
score_threshold	float	0.75	Alert threshold for the blended UEBA score.
alert_cooldown_seconds	int	900	Cooldown between UEBA alerts for the same entity.

threat_intel

TAXII 2.1 feeds matched against ingested events via a Bloom-filter IoC matcher.

Key	Type	Default	Description
enabled	bool	false	Master switch.
feeds	list[mapping]	[]	TAXII feeds to poll (see sub-table below).
default_poll_interval_s	int	3600	Default poll cadence per feed (1h).
request_timeout_s	float	30.0	HTTP request timeout.
max_indicators_per_feed	int	1000000	Hard cap to bound memory.
expired_grace_days	int	30	Days to retain indicators after their expiry date.
startup_jitter_s	int	30	Random delay before first poll to spread load.

threat_intel.feeds[]

Key	Type	Default	Description
id	string	required	Stable identifier for the feed.
url	string	required	TAXII server root URL.
collection_id	string	required	TAXII collection ID to poll.
poll_interval_s	int	inherits	Override default_poll_interval_s for this feed.
confidence_floor	int	0	Drop indicators below this confidence score.
enabled	bool	true	Per-feed switch.
allow_insecure	bool	false	Allow http:// (non-TLS) URLs. Use only in lab environments.
allow_private_addresses	bool	false	Allow feed URLs that resolve to private IP ranges (lab only).
auth.kind	string	—	One of api_key or basic.
auth.api_key_env	string	—	Env var name holding the API key.
auth.api_key_header	string	"Authorization"	Header name for the key.
auth.username_env / auth.password_env	string	—	Env vars for basic-auth credentials.

threat_intel.matcher

Key	Type	Default	Description
enabled	bool	false	Enable the Bloom-filter matcher.
fpr	float	0.001	Target false-positive rate (0.1%).
min_capacity	int	100000	Initial filter capacity (indicators).
capacity_growth_factor	float	1.25	Multiplier when the filter is rebuilt with more indicators.
confidence_floor	int	0	Drop indicators below this confidence score from the filter.
rebuild_debounce_ms	int	200	Coalesce rebuilds within this window after feed updates.
enabled_types	list[string]	[ipv4, ipv6, domain, url, md5, sha1, sha256]	IoC types loaded into the filter.

alerting

See the Alerting page for narrative + examples. Every channel below is opt-in — nothing fires until you list a target.

Dedup + dashboard

Key	Type	Default	Description
dedup_window_seconds	int	900	Default dedup window (15 min).
dedup_window_overrides	list[(string, int)]	[]	Per alert_type override, e.g. [["correlation", 300]].
dashboard_url	string	""	Base URL injected into message renderers for deep-links back to the dashboard.

Webhooks (webhooks[])

Key	Type	Default	Description
url	string	required	Webhook URL. Supports ${ENV_VAR}.
format	string	"json"	One of slack, teams, json.
min_severity	int	0	Minimum OCSF severity ID (0–6) to dispatch.

PagerDuty

Key	Type	Default	Description
pagerduty_routing_key	string	""	Events API v2 routing key. Supports ${ENV_VAR}. Hidden from repr.

Email targets (email_targets[])

Key	Type	Default	Description
name	string	required	Identifier referenced from routing_rules.
smtp_host / smtp_port	string / int	required	SMTP server.
use_starttls	bool	required	Enable STARTTLS.
from_address / to_addresses	string / list[string]	required	Envelope.
smtp_user / smtp_password	string	""	Hidden from repr. Read at startup; rotate via restart.
min_severity	int	0	OCSF severity gate.
max_per_minute	int?	null	Token-bucket cap; omit for unlimited.

SMS targets (sms_targets[], Twilio)

Key	Type	Default	Description
name	string	required
account_sid	string	required	Twilio account SID.
auth_token	string	""	Hidden from repr.
from_number / to_numbers	string / list[string]	required	E.164.
min_severity	int	0
rate_per_second / burst	float / int	1.0 / 3	Token-bucket limit.

Telegram targets (telegram_targets[])

Key	Type	Default	Description
name	string	required
bot_token	string	""	Hidden from repr.
chat_id	string	required	User ID or group ID (negative for groups).
min_severity	int	0
rate_per_second / burst	float / int	30.0 / 30	Telegram’s documented limit.

WhatsApp targets (whatsapp_targets[], Cloud API)

Key	Type	Default	Description
name	string	required
phone_number_id	string	required	WhatsApp Cloud phone ID.
template_name / language_code	string	required	Pre-approved template + language.
access_token	string	""	Hidden from repr.
to_numbers	list[string]	required	E.164.
min_severity	int	0
rate_per_second / burst	float / int	10.0 / 20	Token-bucket + internal circuit breaker.

Routing (routing_rules[] + default_routing)

Key	Type	Default	Description
routing_rules[].match.alert_type	string or list	—	sigma, ml, correlation, ueba, ioc.
routing_rules[].match.rule_name	string	—	fnmatch.fnmatchcase glob.
routing_rules[].match.entity_type	string or list	—	ipv4, user, host, etc.
routing_rules[].match.min_severity / max_severity	int	—	Inclusive range.
routing_rules[].notify[].channel	string	required	Reference to a target’s name.
routing_rules[].notify[].mode	string	"immediate"	immediate or digest.
routing_rules[].notify[].digest_window_minutes	int	15	Only used with digest.
default_routing.action	string	"drop"	drop or notify.
default_routing.notify	list[mapping]	[]	Same shape as routing_rules[].notify.

Quiet hours (quiet_hours_by_channel)

Key	Type	Default	Description
quiet_hours_by_channel	list[(string, mapping)]	[]	Pair [channel_name, { start, end, min_severity }]. Times UTC. Severities >= min_severity still break through.

OTLP alert export

Key	Type	Default	Description
otlp_endpoint	string	""	OTel collector endpoint (host:port). Empty disables export.
otlp_protocol	string	"grpc"	grpc or http.
otlp_export_interval_seconds	int	5	Batch flush cadence.
otlp_tls	bool?	null	Override the scheme-derived TLS default.
otlp_tls_ca_file	string	""	Custom CA PEM.
otlp_mtls_cert_file / otlp_mtls_key_file	string	""	Client cert PEMs for mTLS.

llm

See the LLM Overview for narrative.

Backend selection

Key	Type	Default	Description
backend	string	""	llama_cpp, ollama, cloud, or "" to disable.

llama.cpp (local CPU)

Key	Type	Default	Description
model_path	string	""	Path to a GGUF model.
n_ctx	int	4096	Context window in tokens.
n_threads	int?	null	CPU threads; null uses the default.
n_gpu_layers	int	0	Layers to offload to GPU (0 = CPU-only).
max_tokens_default	int	256	Per-request token cap.
temperature_default	float	0.2	Sampling temperature.
seed	int	42	Deterministic sampling seed.

Ollama (local HTTP)

Key	Type	Default	Description
ollama_url	string	"http://localhost:11434"	Ollama server URL.
ollama_model	string	"phi4-mini"	Pulled model name.
ollama_timeout_s	float	30.0	Per-request wall-clock timeout.

Cloud (Anthropic / OpenAI)

Key	Type	Default	Description
cloud_provider	string	""	anthropic or openai.
cloud_api_key	string	""	API key. Hidden from repr.
cloud_model	string	""	Model ID, e.g. claude-sonnet-4-6.
cloud_timeout_s	float	30.0	Per-request wall-clock timeout.
cloud_base_url	string	""	Override provider base URL (proxies, gateways).

Service knobs

Key	Type	Default	Description
explanation_cache_size	int	256	LRU size for AlertExplanationService.

WebSocket tuning

/api/v1/ws is the dashboard’s live feed. These knobs sit at the top level of seerflow.yaml.

Key	Type	Default	Description
ws_max_connections	int	20	Max concurrent client connections.
ws_queue_maxlen	int	1000	Per-connection outbound queue (drops oldest on overflow).
ws_tick_interval_s	float	0.01	Internal flush cadence.
ws_batch_max_events	int	10	Max events grouped into one frame.
ws_status_interval_s	float	5.0	Cadence of pipeline status frames.
ws_allowed_origins	list[string]	[]	Explicit Origin allowlist. Empty = localhost defaults derived from dashboard_port.
ws_filter_min_interval_ms	int	100	Debounce window for filter-change re-subscriptions.

API hardening

Top-level keys controlling REST API rate limits + CORS + reverse-proxy trust.

Key	Type	Default	Description
api_rate_limit_enabled	bool	true	Master switch for endpoint rate limits.
api_rate_limit_redis_url	string?	null	Redis URL for multi-process limit sharing. Hidden from repr. Falls back to per-process in-memory.
api_allowed_origins	list[string]	[]	CORS allowlist. Empty = no CORS (same-origin only).
api_list_rate_limit	string	"60/minute"	Limit for list endpoints (/alerts, /events, /entities/search).
api_detail_rate_limit	string	"300/minute"	Limit for detail endpoints.
api_coverage_rate_limit	string	"10/minute"	Limit for the expensive /attack/coverage endpoint.
api_trust_proxy_headers	bool	false	When true, honour X-Forwarded-For for rate-limit client identity. Enable only behind a trusted reverse proxy.

Example Configuration

storage:
  backend: sqlite
  graph_backend: igraph

receivers:
  bind_addr: "0.0.0.0"
  syslog_enabled: true
  syslog_udp_port: 5514
  syslog_tcp_port: 5601
  otlp_grpc_enabled: true
  otlp_grpc_port: 4317
  otlp_http_enabled: true
  otlp_http_port: 4318
  webhook_enabled: false
  file_paths:
    - /var/log/syslog
    - /var/log/auth.log

detection:
  # sigma_rules_dirs:
  #   - /etc/seerflow/sigma-rules
  hst_window_size: 1000
  hst_n_trees: 25
  dspot:
    calibration_window: 1000
    risk_level: 0.0001
    initial_percentile: 98

correlation:
  window_duration_seconds: 1800
  kill_chain:
    enabled: true
    tactic_threshold: 3

ueba:
  enabled: true
  warmup_days: 7
  score_threshold: 0.75

alerting:
  dedup_window_seconds: 900

dashboard_port: 8080
log_level: INFO

Production example (PostgreSQL + Slack + TAXII)

storage:
  backend: postgresql
  postgresql_url: ${SEERFLOW_PG_URL}
  postgresql_pool_min_size: 4
  postgresql_pool_max_size: 20
  graph_backend: postgres_age

alerting:
  dedup_window_seconds: 900
  pagerduty_routing_key: ${SEERFLOW_PD_KEY}
  webhooks:
    - url: ${SLACK_WEBHOOK_URL}
      format: slack

threat_intel:
  enabled: true
  matcher:
    enabled: true
  feeds:
    - id: otx-malware
      url: https://otx.alienvault.com/taxii2/
      collection_id: malware
      auth:
        kind: api_key
        api_key_env: OTX_API_KEY