Distributed security event processing engine for any HTTP server — and far beyond
A smart, universal, distributed security engine: behavioural detection instead of static rules, any log source in, any destination out, any language for your own plugins. Scale from a single VPS to a distributed fleet — collect events on one machine, score them on another, ban on a third — over a built-in encrypted node mesh. Bare-metal, Docker Compose, or Kubernetes DaemonSet.
Eight behavioural detectors score patterns — probing, rate anomalies, bruteforce ratios, sequential crawling — instead of matching static signatures. Legitimate crawlers are verified via rDNS/fDNS and never scored.
Any log source in (file, stdin, syslog, HTTP push/pull across 9 vendor formats), any destination out (Fail2Ban, Cloudflare WAF, MikroTik/OpenWrt/OPNsense firewalls, Loki/Splunk/Datadog), any language for your own plugin via exec+JSON.
One process handles N independent log streams, each with its own pipeline of sources, detectors, and sinks — from a single nginx vhost to a fleet of edge nodes, without spinning up separate processes per site.
Collect on one machine, score on another, ban on a third — over a built-in encrypted QUIC/TLS 1.3 node mesh with Ed25519 identity and TOFU pinning. No message broker, no log shipper, no VPN required.
Six servers supported natively — nginx works without any config. Every other server enables with a single profile line. Works behind any proxy or Cloudflare — always scores the real attacker, never the CDN or load balancer.
nginx combined log format works out of the box — no profile needed.
Standard CLF — no server-side changes required.
Default access log (CLF) — no configuration needed.
Apache CLF by default — no server-side changes required.
Requires xcaddy + transform-encoder plugin for CLF output.
Requires option httplog in haproxy.cfg + rsyslog to write to file.
Rules evaluated first. A matching pass rule short-circuits the entire pipeline — health checks, internal IPs and known-good bots bypass all further processing with zero overhead.
SQLi, path traversal, scanner signatures — matched requests are gated out at line rate and never reach the scorer. No state allocated, no detector CPU spent on known-bad traffic.
Suspicious but ambiguous traffic gets a label and a score delta, then flows into the regular detection pipeline. Combine WAF signals with behavioural detectors for correlated ban decisions.
Extend the rule namespace with your own http.* fields — two Go changes, no recompilation of core logic. Add TLS version, request body length, or any field your log source exposes.
Each detector adds points to an IP's score. Score decays linearly over the observation window — no false bans from old traffic.
Requests to sensitive paths: /.env, /.git/config, /.aws/credentials, /wp-config.php, /phpinfo.php, admin panels, backup archives and 30+ others. Active reconnaissance attempts trigger immediately on the first request.
More than 100 requests per 60 seconds from a single IP. Catches DDoS probes, aggressive vulnerability scanners, credential stuffing bursts and scraping tools trying to stay under static limits.
Case-insensitive substring match against built-in lists: scanners (Nuclei, sqlmap...), grabbers (Scrapy, HTTrack...) and automation clients (python-requests, curl...). Extend via config easily.
More than 60% of responses are 404 with at least 10 requests. Typical signature of path-enumeration tools (dirbuster, gobuster, ffuf) blindly traversing wordlists. min_requests prevents false positives.
Five or more sequentially numbered URLs in a row — /page/1, /page/2, /article/100... Characteristic of automated content scrapers dumping entire site sections at machine speed.
Loads pages but requests CSS, JS or images on fewer than 10% of hits — with at least 3 page views. Real browsers fetch resources; markup-only scrapers skip static assets entirely.
URLs longer than 2048 characters, or containing known WAF evasion keywords: bypass, shell, cmd, eval, exec... Targets buffer overflows and code injections.
Matches User-Agent (and optionally Referer) against a community-maintained blocklist of ~685 known bad bots — scrapers, SEO crawlers, spam bots, vulnerability probes. Updated daily. Powered by nginx-ultimate-bad-bot-blocker by Mitchell Krog.
Googlebot, Bingbot, Yandex, DuckDuckBot, GPTBot and 6 others are verified via reverse + forward DNS. Legitimate crawlers are never scored. Fakes get a penalty instead. Trusted crawlers can be matched by User-Agent only (`ua_only`, no DNS) and given per-bot detector exemptions (`exempt_detectors`) so legitimate automation is never penalised.
Add your office IPs, VPN subnets (CIDR), monitoring services, SEO tools by User-Agent substring, or URL paths. Changes apply instantly on SIGHUP.
All config changes — whitelist, detector scores, thresholds — apply instantly on SIGHUP. No restart. IP state and DNS cache are preserved.
Write threat events to a log file in the classic Fail2Ban format. No new infrastructure — the default output, and still the fastest path to a working ban on any Linux box.
Add threat IPs to a Cloudflare IP List and ban them at the network edge — no iptables, no host firewall. Batch operations, async polling, automatic TTL expiry and cross-instance dedup.
Write banned IPs to a plain blocklist file with TTL auto-expiry and atomic writes. arxsentinel only writes the file; you include it into nginx however suits you. Optional reload command.
Manage a RouterOS firewall address-list over the REST API. TTL-based auto-unban, safe removal of only arxsentinel-owned entries, works on CHR and ARM-based routers.
Ban IPs on an OpenWrt router via ubus (uhttpd-mod-ubus) — no SSH, no exec. Batched UCI edit + a single firewall reload per cycle; TTL is owned by the plugin, not left to nftables timeouts.
Ban IPs on an OPNsense firewall via its native REST API (alias_util) — no batching needed, changes apply immediately to the underlying pfctl table. Independent point add/delete per event, active TTL sweep.
Push raw and scored events straight into Grafana Loki over the Push API. Stream-label any field (job, severity, stream), batch with gzip, optional mTLS — JSON envelope is recommended for log-platform readability.
Forward to a Splunk HTTP Event Collector endpoint with token auth. JSON mode, multi-index, gzip batching, optional mTLS. Events get indexed the moment a verdict crosses the threshold — no separate log shipper required.
Send to Datadog's Logs API v2 over HTTPS — pick the regional intake URL (US, EU, AP1, AP2, UK1, US3, US5, US2 Gov) and tag with arbitrary ddtags. Gzip batching, optional mTLS, works alongside your existing Datadog log pipelines.
Source / Sink / Detector / Processor / Executor — each a small Go interface in pkg/plugin/. Plugins register themselves in init(): no central factory list, the framework discovers them by name. Compose the pipeline from roles, not from internal hooks.
The exec+JSON protocol: a subprocess that reads a JSON object per event from stdin and writes a JSON response to stdout. Extend detection, add a sink, write an executor in Python, Bash, or anything that can speak a byte stream — ArxSentinel owns the subprocess lifecycle (spawn, stdin/stdout wiring, shutdown).
Five shipped executor plugins — Cloudflare, MikroTik, OpenWrt, OPNsense, nginx — and the three observability sinks just added (Loki, Splunk, Datadog) all use the same public plugin interfaces you would. No internal fast path, no privileged access: if it works for the bundled plugins, it works for yours.
One process watches N independent log sources via streams: — each gets its own tracker, scorer, whitelist state, and threat log. A crash or slow scan on one stream never touches another. Backward compatible: a classic single-file config (general.log_file) is silently wrapped into one unnamed stream (stream="" on metrics), no migration needed.
A single stream can define multiple pipelines, each with its own inputs, rule-engine / WAF processors, detectors, and sinks — e.g. one pipeline watching /api/* with a strict WAF gate, another watching /admin/* with different detector thresholds, both inside the same stream config. Prometheus gains a pipeline label on every vector.
tracker_groupPipelines that share a tracker_group value share one IP-state tracker: an attacker probing your API and your admin panel accumulates one combined score instead of two separate ones, crossing the ban threshold sooner than either pipeline would catch alone. Omit tracker_group (or leave it empty) for full isolation instead.
Not using a built-in profile? Define your own regex with named capture groups, or switch to JSON log parsing — both work without recompilation. Any format that captures IP, timestamp, method, path, status and bytes maps to the full detection pipeline.
Ship-ready profiles for popular servers. Override field positions, date formats and delimiter rules per log source without touching core logic.
Deploy alongside any containerised HTTP server via a shared log volume — no changes to your app container. Ready-to-use docker-compose.yml and config in deploy/examples/docker/. Prometheus metrics exposed on :9117 for scraping.
One pod per node reads host access logs via hostPath. Helm chart included with values reference and Prometheus Operator integration. Sidecar topology also supported for managed clusters without host log access.
Run `arxsentinel validate` to check your whole config before deploy. A topology-aware validator models the real data flow and catches broken wiring using static plugin manifests — no live traffic needed.
Buffer executor events through an in-memory, file-based (bbolt), Redis — or transport queue that spans machines over the encrypted node mesh. Pick per executor to fit bare-metal, single-host, Kubernetes, or multi-node setups.
Route events between independent pipelines by name — one pipeline detects while another enforces, fully decoupled. And the same named queue can now terminate on a different machine: Distributed NCS.
The same binary becomes a collector, a detector, or a responder — by config alone, connected over a built-in encrypted event mesh. The only tool in its class with node-to-node security event transport inside the engine itself: no message broker, no log shipper, no agent-server hierarchy, no VPN.
QUIC over one UDP port, TLS 1.3 always on, Ed25519 node keys generated on first start, TOFU fingerprint pinning like SSH. Mutual authentication before a single event flows — a stranger on your port gets nothing.
Every collector forwards into one shared per-IP score. An attacker probing your web tier, API and auth service accumulates one combined score on the detector — and crosses the ban threshold sooner than any single service would catch alone.
Forward raw parsed entries inward for central detection, scored verdicts outward for enforcement — or both into your SIEM. Pre-filter at the edge and let threats, not traffic volume, drive your ingest bill.
Every documented topology — edge fleet aggregation, mixed routing to nginx + MikroTik/OpenWrt/OPNsense responders — runs as a real multi-container test on every merge. The diagrams in the docs are executable.
Read from any log source. Write threats to any destination. Fail2Ban remains the default — now one option among many.
Example input configs
type: file · path: /var/log/nginx/access.log
type: syslog · addr: udp://0.0.0.0:5514 · no shared volume
type: http · protocol: plain|cloudflare|firehose|pubsub|loki|otlp|azure|splunk|ndjson
protocol: loki and protocol: splunk here mean receiving logs already
shaped like Loki's push API or Splunk HEC — unrelated to the Grafana Loki / Splunk HEC outputs
listed above, which send events out to those platforms instead.
40+ ready-to-use recipes across 14 categories: every supported server (nginx, Apache, Caddy, Traefik, HAProxy, LiteSpeed), every executor (Cloudflare, MikroTik, OpenWrt, OPNsense), every observability sink (Loki, Splunk, Datadog), CMS-specific probe paths (WordPress, Laravel, Drupal), and more. Browse the index in cookbook/CookBook.md — every row links straight to a working *.yaml.
5 recipe categories ship a full Docker Compose stack — Cloudflare, nginx executor, syslog, MikroTik, Fail2Ban — plus a full Kubernetes directory. Not just the ArxSentinel config, the whole reference deployment.
3 full working multi-node Distributed NCS examples in cookbook/distributed-ncs/ — base, edge aggregation, and mixed routing. The same topologies documented in the guide above, proven by real multi-container CI runs on every merge.
The package handles everything: binary, systemd unit, Fail2Ban config, and system user.
# Works on Debian, Ubuntu, Fedora, RHEL, AlmaLinux, Rocky Linux, Arch Linux # Auto-detects your distro and architecture (amd64 / arm64) curl -fsSL https://raw.githubusercontent.com/mr-addams/arxsentinel/main/scripts/get.sh | sudo bash
The script downloads the correct package from GitHub Releases, installs it with your package manager, checks for fail2ban, auto-detects your access.log path, and starts the service.
# Requires Go 1.26+ git clone https://github.com/mr-addams/arxsentinel cd arxsentinel sudo ./scripts/install.sh sudo systemctl enable --now arxsentinel
# Docker — distroless image (~12 MB), runs as uid 65532, amd64 + arm64 docker run -d \ -v /var/log/nginx/access.log:/var/log/nginx/access.log:ro \ -v /var/log/arxsentinel:/var/log/arxsentinel \ -p 127.0.0.1:9117:9117 \ ghcr.io/mr-addams/arxsentinel:latest
Prometheus metrics available at :9117/metrics immediately after start.
For Docker Compose and Kubernetes (Helm DaemonSet) setup — see the full guides:
README.docker.md ·
Kubernetes (Helm) README
# Native binary — 386 / amd64 / arm / arm64. Dedicated installer + rc.d service. fetch https://github.com/mr-addams/arxsentinel/releases/latest/download/arxsentinel_<version>_freebsd_<arch>.tar.gz tar xzf arxsentinel_<version>_freebsd_<arch>.tar.gz cd arxsentinel_<version>_freebsd_<arch> sudo sh install.sh sysrc arxsentinel_enable=YES service arxsentinel start
Creates the arxsentinel system user, installs the rc.d service, and seeds a config from the bundled example (never overwrites an existing config on re-run).
Running your web server under podman on FreeBSD? See the full guide — storage driver, firewall setup, and container networking gotchas:
FreeBSD Deployment Cookbook
/etc/arxsentinel/config.yaml and set your log path. nginx works without any profile. For Apache, Traefik, Caddy, HAProxy or LiteSpeed — set parser.profile to the server name. Config reloads on SIGHUP — no restart needed.
Push threat IPs directly into AWS WAF IP set rules. Integrates with existing WAF rule groups — no Lambda or custom infrastructure required.
Parse sshd auth logs (syslog/journald) and score brute-force / credential-stuffing patterns with dedicated detectors — the same scoring and executor pipeline you already use for HTTP.
Push threats to Telegram, Slack and PagerDuty — with built-in deduplication and rate-limiting so a burst never floods your channel.