Email notifications

Email notifications#

Vulnerability-Lookup provides two independent email notification mechanisms:

  • Watchlist notifications: scheduled digests for vendors, products, and organizations watched by users. Delivered by a dedicated notification service that must be launched separately (instructions below).

  • KEV catalog subscriptions: near real-time alerts when new entries are recorded in a Known Exploited Vulnerabilities catalog. Built into the web application — no additional service required.

Both mechanisms use the mail settings (MAIL_SERVER, MAIL_DEFAULT_SENDER, PLATFORM_URL, etc.) from config/website.py and require user accounts to be enabled.

Watchlist notification service#

This section provides instructions for activating the email notification service.

Launching the service with poetry#

From the directory used to install Vulnerability-Lookup:

poetry run flask --app website.app notify_users

Launching the service with systemd#

Create the file /etc/systemd/system/vulnerability-lookup-notify.service:

[Unit]
Description=Vulnerability-Lookup notification service
After=vulnerability-lookup-web.service
Requires=vulnerability-lookup-web.service

[Service]
Type=simple
User=<system user used to install Vulnerability-Lookup>
Group=<group of the user used to install Vulnerability-Lookup>
WorkingDirectory=<path to the cloned repository>
Environment="VULNERABILITYLOOKUP_HOME=<path to the cloned repository>"
ExecStart=<path to poetry> run python -m flask \
    --app website.app notify_users
StandardOutput=append:/var/log/vulnerability-lookup_notify_message.log
StandardError=append:/var/log/vulnerability-lookup_notify_error.log
Restart=on-failure
RestartSec=15s

[Install]
WantedBy=multi-user.target

Note

Use Requires only if the web service is managed by systemd on the same host, otherwise just use After to ensure the web service starts before the notification service when both are enabled on the same host.

Then reload and enable the service:

sudo systemctl daemon-reload
sudo systemctl enable vulnerability-lookup-notify.service
sudo systemctl start vulnerability-lookup-notify.service
systemctl status vulnerability-lookup-notify.service

To follow the service logs live:

sudo journalctl -u vulnerability-lookup-notify.service -f

Error logs:

tail -f logs/vulnerability-lookup_notify_error.log

Messages:

tail -f logs/vulnerability-lookup_notify_message.log

KEV catalog email subscriptions#

Authenticated users can subscribe to any Known Exploited Vulnerabilities catalog from its page (/known-exploited-vulnerabilities-catalog/). Whenever new KEV entries are recorded in a subscribed catalog — via the web interface, the API, or synchronization with a remote instance — subscribers receive a digest email (HTML and plain-text parts) linking to each KEV entry and its vulnerability page. Subscriptions can be reviewed and removed on the /user/notifications page, and the number of subscribers per catalog is shown on the /kev-catalogs page.

Unlike the watchlist service above, this mechanism runs inside the web application itself: new entries are queued in the Redis cache and a background worker sends one digest per catalog and subscriber once a short batching window has elapsed. Nothing needs to be launched or scheduled separately.

Configuration#

The behavior is controlled by the following settings in config/website.py:

# #### KEV catalog e-mail digests ####
# Subscribers of a KEV catalog receive one digest e-mail per catalog covering
# all entries recorded during the batching window.
KEV_DIGEST_ENABLED = True
KEV_DIGEST_BATCH_WINDOW = 120  # seconds entries accumulate before a digest is sent
KEV_DIGEST_FLUSH_INTERVAL = 30  # seconds between flush-worker wakeups
KEV_DIGEST_MAX_ENTRIES_PER_EMAIL = 100  # digest links to the catalog for the rest

The batching window protects subscribers from email floods during bulk imports or synchronizations: all entries recorded in a catalog within the window are grouped into a single digest, and a digest never lists more than KEV_DIGEST_MAX_ENTRIES_PER_EMAIL entries (the email links to the catalog page for the rest).

Set KEV_DIGEST_ENABLED = False to disable the feature entirely; the subscribe buttons remain functional but no emails are sent.

Delivery activity is logged by the web application under the website.notifications.kev_digest logger. When the application runs in debug mode, emails are written to the sent-emails/ directory instead of being sent over SMTP.