Made in 🇧🇷 |

Clickdetect

Clickdetect is a generic alerting and detection engine that supports any data source and integrates with any webhook. It is vendor-agnostic, with no lock-in, and enables powerful, flexible detection workflows.

Follow the doc: https://clickdetect.souzo.me

Core Concepts

• Runner.yml: The file where you configure everything
• Detector: Component that runs rules based on thresholds
• Rule: File with structured format to define datasource analysis
• Datasource: Where rule queries are executed, like a database or another SIEM engine
• Webhooks: Where alerts are sent
• Plugin: Script that can intercept Clickdetect actions like "on_rule_triggered"

Supported Integrations

Datasources

• Clickhouse
• Loki
• VictoriaLogs
• PostgreSQL
• Elastic
• Opensearch
• Opensearch PPL
• Databricks
• Duckdb

Webhooks

• Generic
• DFIR Iris
• Forgejo
• Email
• Microsoft Teams
• Slack
• Telegram
• Discord
• TheHive
• Opsgenie
• AlertManager

Plugins

• clickagentic: LLM AI Agent that analyzes your alerts

Quick Start

Start by creating a runner.yml file — see the full reference in the documentation.

uv

Follow uv installation in https://docs.astral.sh/uv

uv sync --no-dev
uv run clickdetect --api

Docker/Podman

Local

podman build -t clickdetect .
podman run -v ./runner.yml:/app/runner.yml -p 8080:8080 clickdetect --api -p 8080

GitHub Packages

podman run -v ./runner.yml:/app/runner.yml -p 8080:8080 ghcr.io/clicksiem/clickdetect:latest --api -p 8080

Options

Runner Configuration

datasource:
    type: clickhouse
    host: localhost
    port: 8123
    verify: false
    username: default
    password: default
    database: siem

webhooks:
    generic_webhook:
        type: generic
        url: <webhook_url>
        headers:
          X-Type: test

detectors:
    5m_detector:
        name: "5m interval"
        for: "5m"
        tenant: 'all' 
        description: "detect rules with 5 min interval"
        rules:
            - "<your rule path>"
        sigma: true # threat all rules for this detector as sigma rule
        webhooks:
            - generic_webhook
        data:
          var1: '<var>' # variables to send
plugins:
  clickagentic: # plugin id
    provider: 'openai' # provider: openai, anthropic, google, huggingface, ollama, openrouter, deepseek
    model: 'gpt-5.2' # get model from your provider
    token: 'xxx'
    from_level: 60 # only run for alerts with alert level >= 60
    ids:
      - "id1"

More example of runner in example_rules

High Availability

By default Clickdetect runs as a single process and keeps the detection window of each detector in memory, so two instances sharing a config would emit duplicate alerts.

Adding a top-level redis block turns it into an active-passive, multi-replica setup with automatic failover:

redis:
    url: redis://localhost:6379/0
    namespace: clickdetect # optional
    lock_ttl: 1500 # optional, failover latency in seconds

Every detector run takes a distributed lock, so only one replica evaluates a given window, and the window itself is stored in Redis, so a replica taking over resumes from exactly where the previous one stopped — no gaps, no reprocessing. Run identical replicas against the same runner.yml and the same Redis.

See High Availability for details.

Rule Configuration

id: "00000000-0000-0000-0000-000000000000"
name: "Base rule for help"
level: 50
size: ">0"
active: false
author: 
    - Vinicius Morais <me@souzo.me>
group: < group >
tags: 
    - <tags>
data: # variables sent to rules by jinja
    max_match_time: 5
rule: |-
    < rule >

Severity

A rule's level is an integer from 0 to 100 — anything outside that range makes the rule fail to load. Sigma rules use a textual level (informational, low, medium, high, critical), which is converted to that scale on load.

Since every destination has its own severity vocabulary, the level is first resolved into a band:

Each webhook then translates the band into what its destination expects. The bands are configurable per webhook with severity_map, which sets the minimum rule level of each band — bands left out keep their default:

webhooks:
    opsgenie_hook:
        type: opsgenie
        api_key: 'xxx'
        severity_map:
            high: 70
            critical: 90

See Severity levels for details.

Release

See the latest releases and changelog

Contact

• E-mail: me@souzo.me
• Matrix: @souzo:matrix.org
• Linkedin: https://www.linkedin.com/in/vinicius-m-a76ba51b5/
• Twitter/X: https://x.com/souzomain
• Reddit: https://www.reddit.com/user/_souzo/