Real-time access monitor for internet-exposed services. Detects threats via deterministic heuristics + AI (local ONNX / optional LLM), computes a risk level per request/IP, and acts automatically: block, edge challenge (Cloudflare, self-hosted JS proof-of-work, or nginx includes), rate-limit, or webhook alert. Search-engine crawlers are verified via reverse DNS — real Googlebot passes, spoofers don't.
Commercial WAFs cover the obvious. Sentry covers the rest: encoded payloads, sensitive-path scanning, malicious crawlers, anomalous access patterns — combining fast rules (zero known false positives) with AI for the unknown. All in a single Rust binary, running locally, never shipping your logs to a third party.
Every source and action is a plugin behind the Source and Action traits.
The core (sentry-core) is pure: it defines contracts, no heavy I/O.
flowchart TD
S["<b>Sources</b><br/>nginx · syslog · Cloudflare · TCP · edge proxy"]
R["<b>Rules engine</b> (fast path, ~µs)<br/>Allow › Block/Challenge/RateLimit › Log/Tag"]
H["<b>Heuristics</b><br/>SQLi · XSS · traversal · uploads · bot verify"]
A["<b>AI fork</b> (ONNX + LLM)<br/>only raises the score"]
SC["<b>Scorer + Decider</b><br/>geo/ASN · behavior · scan · correlation · escalation"]
E["<b>Actions</b><br/>blocklist · firewall · CF challenge · webhook · SIEM"]
S --> R
R -- verdict --> E
R -- no rule hit --> H
H --> SC
SC <-- "gray-zone only" --> A
SC -- verdict --> E
- Sources ingest events — log tailing, syslog, Cloudflare Logs API, raw TCP capture, or the built-in inline reverse proxy (which sees traffic before it reaches your service and can block it in-path).
- Rules engine is the fast path (~µs): DSL-defined packs
(
sensitive_paths,vpn_proxy,tor, rate-scan, …) short-circuit withAllow/Block/Challenge/RateLimit, or annotate and fall through. - Heuristics run on URL-decoded text with an Aho-Corasick prefilter — encoded payloads don't bypass them. Uploads and request bodies are inspected for SQLi/XSS in filenames/fields, polyglot images, and disguised executables.
- AI (local ONNX model, optional LLM via OpenRouter/Ollama) runs as an async fork on gray-zone traffic and can only raise the score.
- Scorer + decider combine signal weights, geo/ASN, reputation feeds (Tor/Spamhaus), behavioral trackers (brute force, scanning), cross-IP correlation, and repeat-offender escalation into a final verdict.
- Actions enforce it: local blocklist shared across nodes, kernel-level
bans (nftables/ipset/firewalld, OPNsense), CDN/WAF challenges,
webhooks, SIEM export — with a shared
BlockTableso a block on one node denies at the edge of all of them.
Each layer is an independent barrier — a threat that slips one still hits the next. The two deployment modes put Sentry in different places relative to those barriers:
flowchart LR
subgraph passive["Passive mode (default)"]
direction TB
P1["Internet"] --> P2["Cloudflare<br/><b>L7</b> · challenge/block"]
P2 --> P3["Kernel firewall<br/><b>L3/L4</b> · nftables / ipset"]
P3 --> P4["Your service<br/><i>nginx · ssh · etc</i>"]
MON["Sentry pipeline"]
P4 -.->|"logs / syslog"| MON
MON -.->|"challenge"| P2
MON -.->|"bans"| P3
end
subgraph inline["Inline mode — Sentry edge"]
direction TB
I1["Internet"] --> I2["Kernel firewall<br/><b>L3/L4</b> · BlockTable bans"]
I2 --> SEDGE
subgraph SEDGE["Sentry edge (in-path)"]
direction TB
S1["TLS + edge-tcp<br/><b>L4/L6</b> · JA3/JA4 · SNI · port 443"]
S2["Reverse proxy<br/><b>L7</b> · rules · heuristics · uploads · PoW"]
S1 --> S2
end
SEDGE --> I5["Your service<br/><i>nginx · ssh · etc</i>"]
end
passive ~~~ inline
- Passive mode (default): Sentry never touches the traffic. It ingests logs/syslog and enforces out-of-band via providers — Cloudflare API at the CDN edge (L7), kernel firewall bans (L3/L4), nginx includes, webhooks.
- Inline mode (
[deployment] mode = "inline"): traffic flows through Sentry — TLS termination and JA3/JA4 fingerprinting at L4/L6, the full pipeline at L7, with aBlockTablefast-path denying known-bad IPs before the pipeline even runs. - Both modes compose: the CDN challenge filters first (cheapest to serve), kernel bans stop everything below HTTP, and the inline proxy catches what reaches your host.
Full design, phase-by-phase backlog, and performance numbers:
ARCHITECTURE.md. Also available as live docs.
| Mode | How it sees traffic | Enforcement |
|---|---|---|
passive (default) |
Tails logs / receives events | Cloudflare API, firewalls, webhooks |
inline |
Built-in reverse proxy in front of your service (HTTP + optional TLS 443) | 403/429/challenge page in-path, before the backend |
git clone --recurse-submodules <this-repo>
cd sentry
docker compose -f deploy/docker/docker-compose.yml up -dSecrets go in env vars, never in committed config:
export SENTRY_STORAGE__POSTGRES__URL=postgres://sentry:secret@db/sentry
export SENTRY_CF_TOKEN=xxx # Cloudflare API token (optional)
export SENTRY_CF_ZONE=yyy # Cloudflare zone ID (optional)
export SENTRY_LLM_KEY=zzz # OpenRouter key (optional)See BUILD.md for requirements, optional features, and development workflow.
Sentry reads sentry.conf, an nginx-like file: key: value directives,
name [label] { … } blocks, include: and ${ENV} expansion.
config/sentry.example.conf documents every
block (sentry, server, storage, detect, trust, rules, routes,
source, action, dashboard, metrics, http, tcp).
The inline edge routes like nginx. A single backend is one line:
http { proxy_pass: http://127.0.0.1:8080 }. With several domains and paths:
http {
site example.com *.example.com {
"/": http://app:8080
"/api/": [http://api-1:9000, http://api-2:9000] # balanced
"/old/": redirect "https://blog.example.com$request_uri"
location /admin/ { proxy_pass: http://app:8080, allow: [10.0.0.0/8] }
location /api/ { match { query.version: "2" }, proxy_pass: http://api-v2:9000/ }
location = /health { return: 200 ok, inspect: off }
}
}"/path": target covers the common case. A location [=|^~|~|~*] block adds
match {} (query, header, cookie, method, IP), rewrite, request_headers {}
and response_headers {}, plus security settings written inline: inspect
(on/shadow/off), rate_limit, allow/deny, challenge: always,
policy {} and packs {}.
The config can be split across files: include: "sites/*.conf" works
anywhere, conf.d/*.conf next to sentry.conf loads automatically, and
--config <dir> loads every *.conf in a directory. Unlabeled blocks such
as detect {} merge across files. Env still overrides any field:
SENTRY_<SECTION>__<KEY> (e.g. SENTRY_STORAGE__POSTGRES__URL).
sentry config files lists what a load reads, sentry config show prints
the effective config, and sentry config migrate sentry.toml --out sentry.conf
converts an old TOML config.
Production rollout: start rule packs in shadow (log only), watch the
logs, then switch to enforce.
- New source: crate depending only on
sentry-core, implementing theSourcetrait — wire it indaemon.rs. - New edge action (AWS WAF, Fastly, Bunny, …): implement
ChallengeProviderin a new crate + one match arm indaemon::build_challenge_action. Config staystype = "challenge",provider = "<name>"— no changes to rules or verdict filtering. - New protocol schema for non-HTTP ports: a TOML DSL under
[protocol](sentry protocol validate) — compiled to a sandboxed VM, hot-reloaded live.
crates/
├── sentry-core/ # Event, ProtocolData, traits, rules engine
├── sentry-storage/ # Postgres (sqlx) + migrations
├── sentry-ai/ # ThreatModel trait (ONNX) + LlmProvider
├── sentry-geo/ # maxminddb geo/ASN enrichment
├── sentry-source-nginx/ # Source plugin: access.log tail
├── sentry-action-cloudflare/ # ChallengeProvider: block/challenge via CF API
├── sentry-action-webhook/ # Action plugin: alerts
├── sentry-action-blocklist/ # Action plugin: in-memory blocklist
└── sentry-cli/ # binary: clap + ratatui + daemon
Full docs live in a separate repo (IDjinn/sentry-docs), mounted as a
submodule under docs/ and deployed online
(live docs) — Portuguese at /pt,
English at /en; Fumadocs + Next.js 16 + Tailwind v4, Mermaid support.
Read locally:
cd docs
bun install
bun run dev # http://localhost:3000 -> /ptAfter changes merge into sentry-docs, bump the pointer:
git -C docs pull origin main
git add docs
git commit -m "docs: bump sentry-docs"The logo sentry.png at the repo root is the source of truth; a copy lives
in sentry-docs/public/sentry.png.
Licensed under the PolyForm Noncommercial License 1.0.0.
You may use, copy, modify, and distribute this software for noncommercial
purposes only, with attribution. Commercial use requires a separate commercial
license from the copyright holder. See LICENSE for the full terms.