docs: create Netgrimoire/Network/Security/OpnSense_Ntfy

2026-02-23 22:00:50 +00:00 · 2026-02-23 22:00:50 +00:00 · fc05032a7c
commit fc05032a7c
parent 40724dad35
1 changed files with 463 additions and 0 deletions
--- a/Netgrimoire/Network/Security/OpnSense_Ntfy.md
+++ b/Netgrimoire/Network/Security/OpnSense_Ntfy.md
@ -0,0 +1,463 @@
+---
+title: OpnSense - NTFY Integration
+description: Security Notifications
+published: true
+date: 2026-02-23T22:00:37.268Z
+tags: 
+editor: markdown
+dateCreated: 2026-02-23T22:00:37.268Z
+---
+
+# OPNsense ntfy Alerts
+
+**Service:** ntfy push notifications from OPNsense
+**Host:** OPNsense firewall
+**ntfy Server:** Your self-hosted ntfy instance on Netgrimoire
+**Methods:** CrowdSec HTTP plugin · Monit custom script · Suricata EVE watcher
+
+---
+
+## Overview
+
+OPNsense does not have a built-in ntfy notification channel, but there are three distinct integration points that together provide complete coverage:
+
+| Method | What It Alerts On | Priority |
+|---|---|---|
+| **CrowdSec HTTP plugin** | Every IP ban decision CrowdSec makes | 🔴 Best for threat intel alerts |
+| **Monit + curl script** | System health, service failures, Suricata EVE matches, login failures | 🔴 Best for operational alerts |
+| **Suricata EVE watcher** | Suricata high-severity IDS hits (via Monit watching eve.json) | 🟡 Covered via Monit |
+
+All three use your self-hosted ntfy instance. None require external services.
+
+---
+
+## Prerequisites
+
+Before starting, confirm:
+- ntfy is running and reachable at `https://ntfy.netgrimoire.com` (or your internal URL)
+- ntfy topic created: e.g. `opnsense-alerts`
+- If ntfy has auth enabled, have a token ready
+- SSH access to OPNsense as root
+
+---
+
+## Method 1 — CrowdSec HTTP Notification Plugin
+
+This is the cleanest integration for security alerts. CrowdSec has a built-in HTTP notification plugin. Every time it makes a ban decision — whether from community intel, a Suricata match passed through CrowdSec, or a brute-force detection — it POSTs to ntfy.
+
+### Step 1 — Create the HTTP notification config
+
+SSH into OPNsense and create the ntfy config file:
+
+```bash
+ssh root@192.168.3.4
+```
+
+```bash
+cat > /usr/local/etc/crowdsec/notifications/ntfy.yaml << 'EOF'
+# ntfy notification plugin for CrowdSec
+# CrowdSec uses its built-in HTTP plugin pointed at ntfy
+type: http
+name: ntfy_default
+
+log_level: info
+
+# ntfy accepts plain POST body as the notification message
+# format is a Go template — .[]Alert is the list of alerts
+format: |
+  {{range .}}
+  🚨 CrowdSec Decision
+  Scenario: {{.Scenario}}
+  Attacker IP: {{.Source.IP}}
+  Country: {{.Source.Cn}}
+  Action: {{.Decisions | len}} x {{(index .Decisions 0).Type}}
+  Duration: {{(index .Decisions 0).Duration}}
+  {{end}}
+
+url: https://ntfy.netgrimoire.com/opnsense-alerts
+
+method: POST
+
+headers:
+  Title: "CrowdSec Ban — OPNsense"
+  Priority: "high"
+  Tags: "rotating_light,shield"
+  # Uncomment and set token if ntfy auth is enabled:
+  # Authorization: "Bearer YOUR_NTFY_TOKEN"
+
+# skip_tls_verify: false
+EOF
+```
+
+> ⚠ Replace `https://ntfy.netgrimoire.com/opnsense-alerts` with your actual ntfy URL and topic. If ntfy is internal-only and OPNsense can reach it by hostname, the internal URL works fine.
+
+### Step 2 — Register the plugin in profiles.yaml
+
+Edit the CrowdSec profiles file to dispatch decisions to the ntfy plugin:
+
+```bash
+vi /usr/local/etc/crowdsec/profiles.yaml
+```
+
+Find the `notifications:` section of the default profile and add `ntfy_default`:
+
+```yaml
+name: default_ip_remediation
+filters:
+  - Alert.Remediation == true && Alert.GetScope() == "Ip"
+decisions:
+  - type: ban
+    duration: 4h
+notifications:
+  - ntfy_default          # ← add this line
+on_success: break
+```
+
+> ✓ The `ntfy_default` name must match the `name:` field in the yaml file you created above exactly.
+
+### Step 3 — Set correct file ownership
+
+CrowdSec rejects plugins if the configuration file is not owned by the root user and root group. Ensure the file has the right permissions:
+
+```bash
+chown root:wheel /usr/local/etc/crowdsec/notifications/ntfy.yaml
+chmod 600 /usr/local/etc/crowdsec/notifications/ntfy.yaml
+```
+
+### Step 4 — Restart CrowdSec and test
+
+```bash
+# Restart via OPNsense service manager (do NOT use systemctl/service directly)
+# Go to: Services → CrowdSec → Settings → Apply
+# Or from shell:
+pluginctl -s crowdsec restart
+```
+
+Test by sending a manual notification:
+
+```bash
+cscli notifications test ntfy_default
+```
+
+You should receive a test push on your device within a few seconds.
+
+Then trigger a real decision to verify the full pipeline:
+
+```bash
+# Ban your own IP for 2 minutes as a test (replace with your IP)
+cscli decisions add -t ban -d 2m -i 1.2.3.4
+# Watch for ntfy notification
+# Remove the test ban:
+cscli decisions delete -i 1.2.3.4
+```
+
+---
+
+## Method 2 — Monit + curl Script
+
+Monit is OPNsense's built-in service monitor. It can watch processes, files, system resources, and log patterns — and call a custom shell script when a condition is met. The script fires a curl POST to ntfy.
+
+This covers things CrowdSec doesn't — service failures, high CPU, gateway down events, SSH login failures, disk usage, and Suricata EVE alerts.
+
+### Step 2.1 — Create the ntfy alert script
+
+```bash
+cat > /usr/local/bin/ntfy-alert.sh << 'EOF'
+#!/usr/local/bin/bash
+# ntfy-alert.sh — called by Monit to send ntfy push notifications
+# Monit provides variables: $MONIT_HOST, $MONIT_SERVICE,
+#                           $MONIT_DESCRIPTION, $MONIT_EVENT
+
+NTFY_URL="https://ntfy.netgrimoire.com/opnsense-alerts"
+# NTFY_TOKEN="Bearer YOUR_NTFY_TOKEN"  # uncomment if ntfy auth enabled
+
+TITLE="${MONIT_HOST}: ${MONIT_SERVICE}"
+MESSAGE="${MONIT_EVENT} — ${MONIT_DESCRIPTION}"
+
+# Map Monit event types to ntfy priorities
+case "$MONIT_EVENT" in
+  *"does not exist"*|*"failed"*|*"error"*)
+    PRIORITY="urgent"
+    TAGS="rotating_light,red_circle"
+    ;;
+  *"changed"*|*"match"*)
+    PRIORITY="high"
+    TAGS="warning,yellow_circle"
+    ;;
+  *"recovered"*|*"succeeded"*)
+    PRIORITY="default"
+    TAGS="white_check_mark,green_circle"
+    ;;
+  *)
+    PRIORITY="default"
+    TAGS="bell"
+    ;;
+esac
+
+curl -s \
+  -H "Title: ${TITLE}" \
+  -H "Priority: ${PRIORITY}" \
+  -H "Tags: ${TAGS}" \
+  -d "${MESSAGE}" \
+  "${NTFY_URL}"
+
+# Uncomment for auth:
+# curl -s \
+#   -H "Authorization: ${NTFY_TOKEN}" \
+#   -H "Title: ${TITLE}" \
+#   -H "Priority: ${PRIORITY}" \
+#   -H "Tags: ${TAGS}" \
+#   -d "${MESSAGE}" \
+#   "${NTFY_URL}"
+EOF
+
+chmod +x /usr/local/bin/ntfy-alert.sh
+```
+
+### Step 2.2 — Enable Monit
+
+Navigate to **Services → Monit → Settings → General Settings**
+
+| Setting | Value |
+|---|---|
+| Enabled | ✓ |
+| Polling Interval | 30 seconds |
+| Start Delay | 120 seconds |
+| Mail Server | Leave blank (using script instead) |
+
+Click **Save**.
+
+### Step 2.3 — Add Service Tests
+
+Navigate to **Services → Monit → Service Tests Settings** and add the following tests:
+
+**Test 1 — Custom Alert via Script**
+
+| Field | Value |
+|---|---|
+| Name | `ntfy_alert` |
+| Condition | `failed` |
+| Action | Execute |
+| Path | `/usr/local/bin/ntfy-alert.sh` |
+
+This is the reusable action that all other tests will invoke.
+
+**Test 2 — Suricata EVE High Alert**
+
+| Field | Value |
+|---|---|
+| Name | `SuricataHighAlert` |
+| Condition | `content = "\"severity\":1"` |
+| Action | Execute → `/usr/local/bin/ntfy-alert.sh` |
+
+This watches for severity 1 (highest) alerts written to the Suricata EVE JSON log.
+
+**Test 3 — Suricata Process Down**
+
+| Field | Value |
+|---|---|
+| Name | `SuricataRunning` |
+| Condition | `failed` |
+| Action | Execute → `/usr/local/bin/ntfy-alert.sh` |
+
+**Test 4 — CrowdSec Process Down**
+
+| Field | Value |
+|---|---|
+| Name | `CrowdSecRunning` |
+| Condition | `failed` |
+| Action | Execute → `/usr/local/bin/ntfy-alert.sh` |
+
+**Test 5 — SSH Login Failure**
+
+| Field | Value |
+|---|---|
+| Name | `SSHFailedLogin` |
+| Condition | `content = "Failed password"` |
+| Action | Execute → `/usr/local/bin/ntfy-alert.sh` |
+
+**Test 6 — OPNsense Web UI Login Failure**
+
+| Field | Value |
+|---|---|
+| Name | `WebUILoginFail` |
+| Condition | `content = "webgui"` |
+| Action | Execute → `/usr/local/bin/ntfy-alert.sh` |
+
+### Step 2.4 — Add Service Monitors
+
+Navigate to **Services → Monit → Service Settings** and add:
+
+**Monitor 1 — Suricata EVE Log (high alerts)**
+
+| Field | Value |
+|---|---|
+| Name | `SuricataEVE` |
+| Type | File |
+| Path | `/var/log/suricata/eve.json` |
+| Tests | `SuricataHighAlert` |
+
+**Monitor 2 — Suricata Process**
+
+| Field | Value |
+|---|---|
+| Name | `Suricata` |
+| Type | Process |
+| PID File | `/var/run/suricata.pid` |
+| Tests | `SuricataRunning` |
+| Restart Method | /usr/local/etc/rc.d/suricata restart |
+
+**Monitor 3 — CrowdSec Process**
+
+| Field | Value |
+|---|---|
+| Name | `CrowdSec` |
+| Type | Process |
+| Match | `crowdsec` |
+| Tests | `CrowdSecRunning` |
+
+**Monitor 4 — SSH Auth Log**
+
+| Field | Value |
+|---|---|
+| Name | `SSHAuth` |
+| Type | File |
+| Path | `/var/log/auth.log` |
+| Tests | `SSHFailedLogin` |
+
+**Monitor 5 — System Resources (optional)**
+
+| Field | Value |
+|---|---|
+| Name | `System` |
+| Type | System |
+| Tests | `ntfy_alert` (on resource threshold exceeded) |
+
+Click **Apply** after adding all services.
+
+### Step 2.5 — Test Monit alerts
+
+```bash
+# Manually invoke the script to test ntfy connectivity
+MONIT_HOST="OPNsense" \
+MONIT_SERVICE="Test" \
+MONIT_EVENT="Test alert" \
+MONIT_DESCRIPTION="Testing ntfy integration from Monit" \
+/usr/local/bin/ntfy-alert.sh
+```
+
+You should receive a push notification immediately.
+
+---
+
+## Alert Topics & Priority Mapping
+
+Consider using separate ntfy topics to filter notifications by type on your device:
+
+| Topic | Used For | Suggested ntfy Priority |
+|---|---|---|
+| `opnsense-alerts` | CrowdSec bans, Suricata high hits | high / urgent |
+| `opnsense-health` | Monit service failures, process restarts | high |
+| `opnsense-info` | Service recoveries, status changes | default / low |
+
+To use separate topics, change the `NTFY_URL` in the Monit script and the `url:` in the CrowdSec config accordingly.
+
+---
+
+## ntfy Priority Reference
+
+ntfy supports five priority levels that map to different notification behaviors on Android/iOS:
+
+| ntfy Priority | Numeric | Behavior |
+|---|---|---|
+| `min` | 1 | No notification, no sound |
+| `low` | 2 | Notification, no sound |
+| `default` | 3 | Notification with sound |
+| `high` | 4 | Notification with sound, bypasses DND |
+| `urgent` | 5 | Phone rings through DND, repeated |
+
+For firewall alerts: use `urgent` for process failures and `high` for IDS/ban events. Reserve `urgent` sparingly to avoid alert fatigue.
+
+---
+
+## Keeping Config Persistent Across Upgrades
+
+OPNsense upgrades can overwrite files in certain paths. The safest locations for persistent custom files:
+
+| File | Location | Persistent? |
+|---|---|---|
+| ntfy-alert.sh | `/usr/local/bin/ntfy-alert.sh` | ✓ Yes — not touched by upgrades |
+| CrowdSec ntfy.yaml | `/usr/local/etc/crowdsec/notifications/ntfy.yaml` | ✓ Yes — plugin config directory |
+| CrowdSec profiles.yaml | `/usr/local/etc/crowdsec/profiles.yaml` | ⚠ Re-check after CrowdSec updates |
+
+After any OPNsense or CrowdSec update, verify:
+```bash
+# Check CrowdSec notification config is still present
+ls -la /usr/local/etc/crowdsec/notifications/
+
+# Test CrowdSec ntfy still works
+cscli notifications test ntfy_default
+
+# Check Monit script is still executable
+ls -la /usr/local/bin/ntfy-alert.sh
+```
+
+---
+
+## Troubleshooting
+
+**No notification received from CrowdSec test:**
+
+```bash
+# Check CrowdSec logs for plugin errors
+tail -50 /var/log/crowdsec.log | grep -i ntfy
+tail -50 /var/log/crowdsec.log | grep -i notification
+
+# Verify ntfy URL is reachable from OPNsense
+curl -v -d "test" https://ntfy.netgrimoire.com/opnsense-alerts
+
+# Check profiles.yaml has ntfy_default in notifications section
+grep -A5 "notifications:" /usr/local/etc/crowdsec/profiles.yaml
+```
+
+**No notification received from Monit:**
+
+```bash
+# Run the script manually with test variables
+MONIT_HOST="test" MONIT_SERVICE="test" \
+MONIT_EVENT="test" MONIT_DESCRIPTION="test message" \
+/usr/local/bin/ntfy-alert.sh
+
+# Check Monit is running
+ps aux | grep monit
+
+# Check Monit logs
+tail -50 /var/log/monit.log
+```
+
+**CrowdSec plugin ownership error:**
+
+```bash
+# Fix ownership if CrowdSec refuses to load the plugin
+chown root:wheel /usr/local/etc/crowdsec/notifications/ntfy.yaml
+ls -la /usr/local/etc/crowdsec/notifications/
+```
+
+**ntfy auth failing:**
+
+```bash
+# Test with token manually
+curl -H "Authorization: Bearer YOUR_TOKEN" \
+     -H "Title: Test" \
+     -d "Auth test" \
+     https://ntfy.netgrimoire.com/opnsense-alerts
+```
+
+---
+
+## Related Documentation
+
+- [OPNsense Firewall](./opnsense-firewall) — parent firewall documentation
+- [CrowdSec](./crowdsec) — threat intelligence engine sending these alerts
+- [Suricata IDS/IPS](./suricata-ids-ips) — source of EVE alerts watched by Monit
+- [ntfy](./ntfy) — self-hosted notification server on Netgrimoire