Skip to content

Add Matrix/Synapse parser whitelist and description #1726

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
pscriptos wants to merge 2 commits into
base: master
Choose a base branch
from
+19 −0
Open

Add Matrix/Synapse parser whitelist and description #1726

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
b18a033
Add Matrix/Synapse parser whitelist and description
Mar 13, 2026
13fb69c
Merge branch 'master' into matrix-whitelist
pscriptos Mar 30, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
10 changes: 10 additions & 0 deletions parsers/s02-enrich/crowdsecurity/matrix-whitelist.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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.
9 changes: 9 additions & 0 deletions parsers/s02-enrich/crowdsecurity/matrix-whitelist.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,9 @@
name: my/matrix-whitelist
Copy link

Copilot AI Mar 30, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

name is set to my/matrix-whitelist, but all other parsers in parsers/s02-enrich/crowdsecurity/ use the crowdsecurity/ namespace (e.g. parsers/s02-enrich/crowdsecurity/actual-budget-whitelist.yaml:1). Using a different namespace is likely to fail hub conventions/linting and makes the parser harder to discover; rename it to crowdsecurity/matrix-whitelist (and keep it consistent with the file path).

Suggested change
name: my/matrix-whitelist
name: crowdsecurity/matrix-whitelist

Copilot uses AI. Check for mistakes.
description: "Whitelist Matrix/Synapse requests from NPMplus logs"
Copy link

Copilot AI Mar 30, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The description says "from NPMplus logs", but the filter matches any event with evt.Meta.service == 'http' and the standard http_access-log/http_error-log log types. Either scope the filter to NPMplus-specific events (if that’s the intent) or update the description to reflect that this whitelist applies to generic HTTP logs.

Suggested change
description: "Whitelist Matrix/Synapse requests from NPMplus logs"
description: "Whitelist Matrix/Synapse HTTP requests from generic http_access-log/http_error-log entries"

Copilot uses AI. Check for mistakes.
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/'"
Comment on lines +7 to +9
Copy link

Copilot AI Mar 30, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This whitelists all requests to /_matrix/ and /_synapse/ purely by path prefix. Unlike other HTTP app whitelists in this directory (which typically narrow by verb/status and specific endpoints), this creates a broad blind spot where probing/bruteforce against Synapse/Matrix endpoints would no longer contribute to remediation decisions. Consider narrowing the whitelist conditions (e.g., to specific verbs/statuses/endpoints known to FP) or moving the exception into the specific scenarios that FP (so Matrix-specific attacks can still be detected).

Suggested change
- "evt.Meta.http_path startsWith '/_matrix/'"
- "evt.Meta.http_path startsWith '/_synapse/'"
- "evt.Meta.http_path startsWith '/.well-known/matrix/'"
- "evt.Meta.http_verb == 'GET' && evt.Meta.http_path startsWith '/.well-known/matrix/'"

Copilot uses AI. Check for mistakes.
Comment on lines +1 to +9
Copy link

Copilot AI Mar 30, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

A new whitelist parser is added, but there is no corresponding .tests/matrix-whitelist/ (most existing whitelists here have dedicated tests, e.g. .tests/actual-budget-whitelist/, .tests/calibre-web-whitelist/, .tests/nextcloud-whitelist/). Add a minimal test fixture asserting that Matrix/Synapse paths are marked whitelisted and that non-Matrix paths are not.

Copilot uses AI. Check for mistakes.
Loading