A MagicMirror² module for CrowdSec: alert and ban counts, a world map of attack sources, a timeline, top countries, top attack types and the latest attacks. Every view can be switched on or off and reordered.
| All sections | Compact (sections: ["stats", "map"]) |
|---|---|
![]() |
![]() |
- Stats: alerts in the time window, currently banned sources, number of source countries
- Attacker map: sources on a world map, banned ones in red, a pulse for attacks in the last hour, optional home marker with attack lines. The map is bundled, nothing is loaded from the internet.
- Timeline: alerts per time slot
- Top countries with flags, top attack types (CrowdSec scenarios), recent attacks
- Source IPs are hidden by default (provider name instead)
- Translations: English, German
cd ~/MagicMirror/modules
git clone https://github.com/meni555/MMM-Crowdsec.gitThere is nothing to npm install. Requires MagicMirror² with Node.js 18 or newer.
The module reads the CrowdSec Local API (LAPI) with a machine account. There are two ways:
A small backend next to CrowdSec holds the credentials and passes on only what the views need.
The mirror needs no credentials and the LAPI can stay bound to 127.0.0.1.
An example backend without dependencies is included in examples/crowdsec-summary-server.py:
# on the CrowdSec host: dedicated machine account (do not reuse the engine's own "localhost" machine)
cscli machines add magicmirror --password '<long random password>' -f /dev/null
CROWDSEC_MACHINE=magicmirror CROWDSEC_PASSWORD='<password>' \
CROWDSEC_URL=http://127.0.0.1:8080 LISTEN_PORT=8088 \
python3 examples/crowdsec-summary-server.pyAs a Docker service next to CrowdSec (same compose project, so crowdsec resolves to the LAPI):
crowdsec-summary:
image: python:3.12-alpine
restart: unless-stopped
user: "65534:65534"
read_only: true
environment:
CROWDSEC_URL: http://crowdsec:8080
CROWDSEC_MACHINE: magicmirror
CROWDSEC_PASSWORD: ${CROWDSEC_SUMMARY_PASSWORD}
LISTEN_PORT: "8088"
volumes:
- ./crowdsec-summary-server.py:/app/server.py:ro
command: ["python", "/app/server.py"]
ports:
- "192.168.0.10:8088:8088" # LAN address of the host, not 0.0.0.0{
module: "MMM-Crowdsec",
position: "top_left",
config: {
summaryUrl: "http://crowdsec-host:8088/api/crowdsec",
}
},The endpoint receives since, limit, details and ips as query parameters and returns
{"alerts24h": 280, "alertsCapped": false, "bans": 13}, with details=1 additionally the lists
alerts and banned ({t, s, n, cn, as, lat, lon, ip?} per alert). You can implement it in any language.
The module logs in to the LAPI itself. The LAPI must be reachable from the mirror.
config: {
url: "http://crowdsec-host:8080",
machineId: "magicmirror",
password: "<password>",
}Use a dedicated machine account: machine accounts can also create alerts and decisions, and anyone who can
read your config.js (for example through other modules' web interfaces) gets the password.
credentialsFile can point to a local_api_credentials.yaml instead of putting the password in the config.
sections selects the views and their order. Remove an entry to hide it.
| Section | Shows |
|---|---|
stats |
Tiles: alerts in the time window, banned sources, source countries |
map |
World map with attack sources |
timeline |
Alerts per time slot as a bar chart |
countries |
Top source countries |
scenarios |
Top attack types |
recent |
Latest alerts: time, flag, attack type, provider or IP |
| Option | Default | Description |
|---|---|---|
summaryUrl |
"" |
Summary endpoint; when set, url and the credentials are not used |
url |
http://localhost:8080 |
LAPI URL for direct mode (http:// is added if missing) |
machineId / password |
"localhost" / "" |
Machine account for direct mode |
credentialsFile |
"" |
Path to a local_api_credentials.yaml for direct mode |
alertsSince |
"24h" |
Time window, e.g. "12h", "24h", "7d" |
alertsLimit |
500 |
Max. alerts fetched; the count is shown as 500+ once reached |
updateInterval |
60000 |
Refresh interval in ms |
timeout |
20000 |
Request timeout in ms |
sections |
all six | Views and their order |
width |
340 |
Module width in px |
showAlerts / showBans / showCountries |
true |
Tiles in stats |
timelineBuckets |
24 |
Number of bars in timeline |
mapHome |
null |
{ lat, lon } of your server: home marker and attack lines |
mapLines |
true |
Attack lines to mapHome |
mapAnimate |
true |
Pulse for sources with attacks in the last hour |
mapShowBanned |
true |
Banned sources in mapBannedColor |
mapPointColor / mapBannedColor / mapLandColor |
orange / red / translucent white | Map colors |
topCountries / topScenarios / recentCount |
5 |
Rows in the lists |
showIp |
false |
recent: IP instead of the provider name |
animationSpeed |
0 |
DOM update animation in ms |
identifier |
"" |
Unique ID when running several instances with the same data source |
Times follow locale and timeFormat of the global MagicMirror² config.
{
module: "MMM-Crowdsec",
position: "top_left",
config: {
summaryUrl: "http://crowdsec-host:8088/api/crowdsec",
alertsSince: "24h",
sections: ["stats", "map", "timeline", "countries", "scenarios", "recent"],
mapHome: { lat: 50.11, lon: 8.68 },
topCountries: 4,
recentCount: 4,
}
},With showIp: false (default) source IPs are not shown and, in summary mode, not even requested.
The summary endpoint returns attacker data (countries, providers, coordinates of the sources),
so expose it only in your LAN.
Inspired by the CrowdSec widget of Homepage, which uses the
same LAPI queries. Land outlines: Natural Earth 1:110m (public domain) via
world-atlas (ISC), pre-converted to an SVG path in world-land.js.
This module is not affiliated with CrowdSec. Licensed under the MIT License.

