Skip to content
Seerflow

Quick Start

Prerequisites

Section titled “Prerequisites”
  • Python 3.11, 3.12, 3.13, or 3.14
  • uv package manager (recommended) or pip
  • Optional: Docker + Docker Compose for the bundled stack
  • Optional: PostgreSQL 14+ for production storage

Installation

Section titled “Installation”

From PyPI

Section titled “From PyPI”
Terminal window
pip install seerflow
# or
uv add seerflow

From source

Section titled “From source”
Terminal window
git clone https://github.com/seerflow/seerflow.git
cd seerflow
uv sync

Docker

Section titled “Docker”
Terminal window
# Run with SQLite defaults (zero config)
docker compose up -d


# Run with PostgreSQL
export POSTGRES_PASSWORD=your-secure-password
docker compose --profile postgres up -d


# Standalone
docker run -p 4317:4317 -p 514:514/udp seerflow/seerflow

First Run

Section titled “First Run”

Seerflow works out of the box with zero configuration:

Terminal window
seerflow start

This starts Seerflow with:

  • SQLite storage (WAL mode, auto-created at ~/.local/share/seerflow/seerflow.db)
  • Syslog receiver on UDP 514 and TCP 601
  • OTLP gRPC receiver on port 4317
  • OTLP HTTP receiver on port 4318
  • Dashboard + REST API + WebSocket on http://127.0.0.1:8080
    • UI: http://127.0.0.1:8080/
    • REST: http://127.0.0.1:8080/api/v1/
    • WebSocket stream: ws://127.0.0.1:8080/api/v1/ws
  • 63 bundled Sigma rules with MITRE ATT&CK tagging

Configuration

Section titled “Configuration”

Create seerflow.yaml in your working directory:

storage:
  backend: sqlite  # or postgresql


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


detection:
  hst_window_size: 1000
  hst_n_trees: 25


log_level: INFO

Run with a config file:

Terminal window
seerflow --config seerflow.yaml start

Environment variables are supported with ${VAR:-default} syntax:

storage:
  postgresql_url: ${DATABASE_URL:-postgresql://localhost/seerflow}

Tailing Log Files

Section titled “Tailing Log Files”

To tail specific log files, add file_paths to your config:

receivers:
  file_paths:
    - /var/log/syslog
    - /var/log/auth.log

Sending Test Logs

Section titled “Sending Test Logs”

Send syslog messages to test your setup:

Terminal window
# UDP syslog
echo "<14>Mar 25 10:00:00 myhost myapp[1234]: User login from 10.0.1.5" | nc -u localhost 5514


# TCP syslog
echo "<14>Mar 25 10:00:00 myhost myapp[1234]: Connection timeout" | nc localhost 5601

Graceful Shutdown

Section titled “Graceful Shutdown”

Press Ctrl+C to stop. Seerflow will:

  1. Stop all receivers
  2. Flush remaining events to storage
  3. Persist ML model state (Half-Space Trees, Holt-Winters, CUSUM, Markov, biDSPOT)
  4. Print a session summary (events processed, anomalies detected, templates, throughput)

CLI Options

Section titled “CLI Options”
Terminal window
# Core
seerflow --help                          # Show help
seerflow --version                       # Show version
seerflow --config FILE start             # Start with custom config


# Query historical data
seerflow query events --limit 10         # Last N events
seerflow query alerts --since 1h         # Alerts in time window
seerflow query templates --top 20        # Most-seen Drain3 templates


# Sigma rules
seerflow rules list                      # All loaded rules
seerflow rules list --technique T1110    # MITRE technique filter
seerflow rules list --tactic credential-access
seerflow rules list --format json        # Scriptable output


# Natural-language threat hunting (requires llm.backend configured)
seerflow hunt "ssh brute force from 10.0.1.42 in the last 24h"
seerflow hunt "outbound DNS to flagged domains" --limit 100 --json


# Export / import
seerflow export events --since 7d --output events.ndjson
seerflow export events --format csv --output events.csv
seerflow import events.ndjson


# Operational status
seerflow status                          # Live pipeline metrics
seerflow status --json                   # Machine-readable


# Templates inspection
seerflow templates list --top 20
seerflow templates show <template-id>


# Alert feedback (label noise / true positives for offline learning)
seerflow feedback <alert-id> tp
seerflow feedback <alert-id> fp --note "ssh from ops jumphost"


# Entity-graph backend migration (igraph ↔ falkordb ↔ postgres_age)
seerflow graph migrate --from igraph --to falkordb --dry-run

Next Steps

Section titled “Next Steps”