Skip to content

Notifications

Jump to bottom
homelabforge edited this page Feb 8, 2026 · 2 revisions

Notifications

Configure smart alerting with 7 notification services for critical vulnerability findings.

Table of Contents

Overview

VulnForge sends notifications for:

  • Critical vulnerability discoveries
  • High-severity vulnerabilities exceeding threshold
  • Scan completions
  • Compliance check failures
  • KEV (Known Exploited Vulnerability) detections

Notification Rules: Configure custom rules with threshold logic, provider selection, and message templates in Settings → Notifications → Notification Rules.

Supported Services

VulnForge supports 7 notification providers:

Service Type Best For
ntfy Push notifications Self-hosted, privacy-focused alerts
Gotify Push notifications Self-hosted Android notifications
Pushover Push notifications iOS/Android with rich features
Slack Team chat Team collaboration and channels
Discord Community chat Discord servers and webhooks
Telegram Messaging Personal or group chats
Email SMTP Traditional email alerts

Configuration

Navigate to Settings → Notifications to enable and configure services.

Global Settings

Setting Description Default
Notifications Enabled Master toggle for all notifications true

Notification Rules

Create custom rules with:

  • Name: Rule identifier
  • Event Type: scan_completed, compliance_scan_completed, vulnerability_found, kev_detected
  • Enabled: Toggle rule on/off
  • Conditions: Min critical/high/medium/low thresholds
  • Providers: Select which services to notify (ntfy, gotify, pushover, slack, discord, telegram, email)
  • Message Template: Custom message with variables like $container_name, $critical_count, $high_count

Example Rule:

Name: Critical Vulnerability Alert
Event Type: scan_completed
Enabled: true
Min Critical: 1
Providers: ntfy, slack, email
Template: 🚨 Critical vulnerabilities found in $container_name: $critical_count critical, $high_count high

Service Setup Guides

ntfy

Self-hosted or public service (ntfy.sh)

Option 1: Use ntfy.sh (Public)

  1. Visit https://ntfy.sh
  2. Choose a unique topic (e.g., vulnforge-homelab-xyz)
  3. Subscribe via mobile app or web

Configuration:

  • ntfy Enabled: true
  • ntfy URL: https://ntfy.sh
  • ntfy Topic: vulnforge-homelab-xyz
  • ntfy Token: (optional, for auth)

Option 2: Self-Hosted

services:
  ntfy:
    image: binwiederhier/ntfy:latest
    command: serve
    ports:
      - "8080:80"
    volumes:
      - ntfy-cache:/var/cache/ntfy

Configuration:

  • ntfy Enabled: true
  • ntfy URL: http://ntfy:80
  • ntfy Topic: vulnforge

Gotify

Self-hosted Android push notifications

Setup

services:
  gotify:
    image: gotify/server:latest
    ports:
      - "8081:80"
    volumes:
      - gotify-data:/app/data
  1. Access Gotify UI at http://localhost:8081
  2. Create application
  3. Copy application token

Configuration:

  • Gotify Enabled: true
  • Gotify URL: http://gotify:80
  • Gotify Token: <application-token>

Pushover

Commercial push notification service ($5 one-time)

Setup

  1. Create account at https://pushover.net
  2. Create application
  3. Note User Key and API Token

Configuration:

  • Pushover Enabled: true
  • Pushover User Key: <user-key>
  • Pushover API Token: <api-token>

Features:

  • iOS and Android apps
  • Priority levels (critical = emergency)
  • Rich notifications with links

Slack

Team collaboration platform

Setup

  1. Go to https://api.slack.com/apps
  2. Create new app → "From scratch"
  3. Navigate to Incoming Webhooks
  4. Activate Incoming Webhooks
  5. Add webhook to workspace
  6. Copy webhook URL

Configuration:

  • Slack Enabled: true
  • Slack Webhook URL: https://hooks.slack.com/services/T00000000/B00000000/XXXXXXXXXXXXXXXXXXXX

Features:

  • Channel notifications
  • Threaded conversations
  • Rich formatting with markdown

Discord

Community chat platform

Setup

  1. Open Discord server settings
  2. Go to Integrations → Webhooks
  3. Create webhook
  4. Copy webhook URL

Configuration:

  • Discord Enabled: true
  • Discord Webhook URL: https://discord.com/api/webhooks/1234567890/XXXXXXXXXXXXXXXXXXXX

Features:

  • Channel notifications
  • @mentions support
  • Embedded rich messages

Telegram

Messaging platform

Setup

  1. Message @BotFather on Telegram
  2. Create bot with /newbot command
  3. Copy bot token
  4. Start chat with your bot
  5. Get your Chat ID: 
    curl https://api.telegram.org/bot<TOKEN>/getUpdates
# Look for "chat":{"id":123456789}

Configuration:

  • Telegram Enabled: true
  • Telegram Bot Token: <bot-token>
  • Telegram Chat ID: <chat-id>

Features:

  • Personal or group chats
  • Rich formatting with markdown
  • Inline buttons (future feature)

Email (SMTP)

Traditional email notifications

Setup

Configure your SMTP server details.

Configuration:

  • Email Enabled: true
  • SMTP Host: smtp.gmail.com (or your provider)
  • SMTP Port: 587 (TLS) or 465 (SSL)
  • SMTP Username: your-email@gmail.com
  • SMTP Password: your-app-password
  • SMTP From: vulnforge@yourdomain.com
  • SMTP To: admin@yourdomain.com (comma-separated for multiple)
  • SMTP Use TLS: true

Gmail Example:

  1. Enable 2FA on Google Account
  2. Generate App Password at https://myaccount.google.com/apppasswords
  3. Use app password in SMTP Password field

Features:

  • Multiple recipients
  • HTML email formatting
  • Attachment support (future feature)

Notification Types

Critical Vulnerability Alert

Triggered when: Container scan finds ≥ threshold critical CVEs or KEV detected

Priority: 5 (Urgent)

Example Message:

🚨 Critical Vulnerabilities Found

Container: nginx:latest
Critical: 3
High: 12
KEVs: 1

View: https://vulnforge.yourdomain.com/vulnerabilities

High Vulnerability Alert

Triggered when: Container scan finds ≥ threshold high CVEs

Priority: 4 (High)

Example Message:

⚠️ High Vulnerabilities Found

Container: postgres:15
Critical: 0
High: 15
Medium: 42

View: https://vulnforge.yourdomain.com/vulnerabilities

Scan Complete

Triggered when: Scan finishes successfully with no critical/high findings

Priority: 3 (Default)

Example Message:

✅ Scan Complete

Container: redis:alpine
Total: 8 vulnerabilities
Critical: 0
High: 0

View: https://vulnforge.yourdomain.com/scans

KEV Detection

Triggered when: CVE matches CISA Known Exploited Vulnerabilities catalog

Priority: 5 (Max Urgent)

Batched Notifications: During scheduled/batch scans, VulnForge sends one summary notification instead of per-container alerts to prevent notification spam.

Example Message (Batch Scan):

🚨 Exploited CVEs Detected!

Batch scan found 42 actively exploited CVEs (CISA KEV) across 15 containers:
nginx, postgres, redis, mysql, mongodb and 10 more

View: https://vulnforge.yourdomain.com/vulnerabilities?kev=true

Example Message (Single Container Scan):

🚨 Exploited CVEs Detected!

apache:2.4: 3 actively exploited CVEs found (CISA KEV)

View: https://vulnforge.yourdomain.com/vulnerabilities?kev=true

Note: Manual single-container scans still send per-container notifications. Only automated batch scans use the batched format to reduce noise.

Thresholds

How Thresholds Work

Notifications only send when vulnerabilities exceed configured thresholds per rule.

Example Rule:

  • Min Critical: 1
  • Min High: 10

Scenarios:

Critical High Notify? Reason
3 5 ✅ Yes Critical ≥ 1
0 15 ✅ Yes High ≥ 10
0 8 ❌ No Below both thresholds
1 0 ✅ Yes Critical ≥ 1

Recommended Threshold Strategies

Conservative (many alerts):

  • Critical: 1, High: 1

Balanced (moderate alerts):

  • Critical: 1, High: 10

Aggressive (few alerts):

  • Critical: 3, High: 20

KEV Only (minimal alerts):

  • Critical: 100, High: 100
  • (KEVs always trigger regardless)

Testing

Test Notifications

  1. Navigate to Settings → Notifications
  2. Enable desired service(s)
  3. Click "Test" button next to service

Expected behavior:

  • ntfy: Push notification on subscribed device
  • Gotify: Push notification in app
  • Pushover: Push notification with sound
  • Slack: Message in configured channel
  • Discord: Message in configured channel
  • Telegram: Message in bot chat
  • Email: Email to configured recipient

Troubleshooting Tests

Test fails with "Connection refused":

  • Verify service URL is correct
  • Check service is running: docker ps | grep <service>
  • Test connectivity: docker exec vulnforge curl <service-url>

Test succeeds but no notification received:

  • Verify credentials/tokens are correct
  • Check service logs: docker logs <service>
  • Verify topic/channel/chat ID matches subscription
  • Check spam folder (email)

Best Practices

Multi-Provider Strategy

Use different providers for different purposes:

Critical Alerts (immediate action):

  • Pushover - Reliable iOS/Android delivery
  • Telegram - Personal messaging
  • Slack - Team awareness

High Alerts (review within hours):

  • ntfy - Self-hosted push
  • Discord - Community channel
  • Email - Audit trail

Scan Complete (informational):

  • ntfy - Low-priority push
  • Email - Daily digest

Alert Fatigue Prevention

  1. Start conservative: Low thresholds initially
  2. Monitor volume: Adjust thresholds to reduce noise
  3. Use triage: Mark false positives to reduce repeat alerts
  4. Separate environments: Different rules for prod vs dev
  5. Time-based rules: Schedule scans during business hours

Security Considerations

  • Don't use public services for sensitive data (prefer self-hosted)
  • Rotate tokens/API keys quarterly
  • Use HTTPS for all webhook URLs
  • Limit access to notification channels/topics
  • Audit logs regularly

Message Templates

Customize notification messages with variables:

Available Variables:

  • $container_name - Container name
  • $image_name - Image name
  • $critical_count - Critical vulnerability count
  • $high_count - High vulnerability count
  • $medium_count - Medium vulnerability count
  • $low_count - Low vulnerability count
  • $total_count - Total vulnerability count
  • $kev_count - KEV count
  • $scan_id - Scan ID
  • $scan_date - Scan timestamp

Example Custom Template:

🔍 Scan Results: $container_name

Severity Breakdown:
🔴 Critical: $critical_count
🟠 High: $high_count
🟡 Medium: $medium_count
⚪ Low: $low_count

KEVs: $kev_count
Total: $total_count

Scanned: $scan_date
View: https://vulnforge.yourdomain.com/scans/$scan_id

Provider Comparison

Feature ntfy Gotify Pushover Slack Discord Telegram Email
Cost Free Free $5 Free Free Free Free*
Self-Hosted ✅ ✅ ❌ ❌ ❌ ❌ Depends
iOS App ✅ ❌ ✅ ✅ ✅ ✅ ✅
Android App ✅ ✅ ✅ ✅ ✅ ✅ ✅
Rich Formatting ✅ ⚠️ ✅ ✅ ✅ ✅ ✅
Priority Levels ✅ ✅ ✅ ⚠️ ⚠️ ⚠️ ❌
Delivery Guarantee ⚠️ ⚠️ ✅✅ ✅ ✅ ✅ ✅
Rate Limits Low None High Medium Medium High Varies

*Email SMTP server costs vary

Legend:

  • ✅ Full support
  • ⚠️ Partial support
  • ❌ Not supported

Advanced Configuration

Priority Mapping

VulnForge maps alert severity to provider-specific priorities:

VulnForge Severity ntfy Gotify Pushover Others
KEV Detection 5 (Max) 10 2 (Emergency) High
Critical 5 (Urgent) 8 1 (High) High
High 4 (High) 5 0 (Normal) Normal
Scan Complete 3 (Default) 3 0 (Normal) Low

Retry Logic

VulnForge automatically retries failed notifications:

  • Max retries: 3
  • Backoff: Exponential (1s, 2s, 4s)
  • Timeout: 10 seconds per attempt

Rate Limiting

Provider Limits:

  • ntfy.sh: 100 req/hour per IP
  • Pushover: 10,000 req/month
  • Slack: 1 req/second per webhook
  • Discord: 30 req/minute per webhook
  • Telegram: 30 req/second per bot

VulnForge Behavior:

  • Queues notifications when rate-limited
  • Spreads notifications across providers if multiple enabled
  • Logs failed deliveries in notification history

Troubleshooting

See Troubleshooting Guide for detailed solutions.

Quick Diagnostics:

# Check notification service connectivity
docker exec vulnforge curl -v <service-url>

# View notification logs
docker logs vulnforge | grep -i notif

# Test specific provider
curl -X POST http://localhost:8787/api/v1/notifications/test/ntfy

Next Steps

Clone this wiki locally