From b18a033f4895c4edb1b9d05f73b186d1b47c52e3 Mon Sep 17 00:00:00 2001 From: scriptos Date: Fri, 13 Mar 2026 19:35:47 +0100 Subject: [PATCH] Add Matrix/Synapse parser whitelist and description --- parsers/s02-enrich/crowdsecurity/matrix-whitelist.md | 10 ++++++++++ parsers/s02-enrich/crowdsecurity/matrix-whitelist.yaml | 9 +++++++++ 2 files changed, 19 insertions(+) create mode 100644 parsers/s02-enrich/crowdsecurity/matrix-whitelist.md create mode 100644 parsers/s02-enrich/crowdsecurity/matrix-whitelist.yaml diff --git a/parsers/s02-enrich/crowdsecurity/matrix-whitelist.md b/parsers/s02-enrich/crowdsecurity/matrix-whitelist.md new file mode 100644 index 00000000000..d20e9a0b2a3 --- /dev/null +++ b/parsers/s02-enrich/crowdsecurity/matrix-whitelist.md @@ -0,0 +1,10 @@ +## Matrix/Synapse whitelist + +### Federation and Client-Server API +Matrix homeservers constantly communicate with each other via the `/_matrix/` endpoint for federation (server-to-server) and client-to-server traffic. These requests can produce a high volume of 4xx responses during normal operation — for example when querying unknown rooms, resolving user profiles across federated servers, or during key exchange. Without this whitelist, scenarios such as `http-probing` or `http-crawl-non_statics` can be triggered, potentially causing legitimate Matrix federation partners or your own clients to get banned. + +### Synapse Admin and internal endpoints +The `/_synapse/` path is used by Synapse-specific administration and internal endpoints (e.g. the admin API or media worker communication). Automated health checks, admin dashboards, and internal service calls to these endpoints may generate responses that look suspicious to CrowdSec. This whitelist prevents those requests from being counted toward attack scenarios. + +### Server Discovery (`.well-known`) +Matrix relies on `/.well-known/matrix/` for server discovery, where clients and remote servers look up the homeserver and identity server configuration. These lightweight requests are a fundamental part of the Matrix protocol and should never be treated as malicious. Without whitelisting, repeated discovery lookups — especially from multiple federated servers — could falsely trigger rate-based or probing-based scenarios. diff --git a/parsers/s02-enrich/crowdsecurity/matrix-whitelist.yaml b/parsers/s02-enrich/crowdsecurity/matrix-whitelist.yaml new file mode 100644 index 00000000000..289a5b8470f --- /dev/null +++ b/parsers/s02-enrich/crowdsecurity/matrix-whitelist.yaml @@ -0,0 +1,9 @@ +name: my/matrix-whitelist +description: "Whitelist Matrix/Synapse requests from NPMplus logs" +filter: "evt.Meta.service == 'http' && evt.Meta.log_type in ['http_access-log', 'http_error-log']" +whitelist: + reason: "Matrix federation/client traffic" + expression: + - "evt.Meta.http_path startsWith '/_matrix/'" + - "evt.Meta.http_path startsWith '/_synapse/'" + - "evt.Meta.http_path startsWith '/.well-known/matrix/'"