Skip to content

About

CrowdSec dashboard for MagicMirror²: alerts, bans, attacker map, timeline, top countries and attack types

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

MMM-Crowdsec

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.

🇩🇪 Deutsche Anleitung

All sections Compact (sections: ["stats", "map"])
All sections Compact

Features

  • 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

Installation

cd ~/MagicMirror/modules
git clone https://github.com/meni555/MMM-Crowdsec.git

There is nothing to npm install. Requires MagicMirror² with Node.js 18 or newer.

Getting the data

The module reads the CrowdSec Local API (LAPI) with a machine account. There are two ways:

Summary mode (recommended)

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.py

As 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.

Direct mode

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.

Configuration

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.

Full example

{
    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,
    }
},

Privacy

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.

Credits

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.

About

CrowdSec dashboard for MagicMirror²: alerts, bans, attacker map, timeline, top countries and attack types

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages