Add vulnerability email de-duplication integration

[leonfullxr]

Summary

Adds integrations/vulnerability_email_dedup/, a drop-in replacement for a custom-email integration that suppresses duplicate vulnerability notifications.

The Vulnerability Detection module emits one alert per (package, CVE) pair. A single package often carries dozens of CVEs, so one scan produces a burst of near-identical alerts for the same package on the same agent. Routed to email through the stock integration, that burst becomes hundreds of near-identical messages.

This integration sends one email per affected package per agent instead of one per CVE. Every subsequent CVE for the same key inside the suppression window is recorded and counted, but not mailed. Non-vulnerability alerts pass through unchanged.

Design notes

• Execution model. wazuh-integratord runs the script once per alert as a separate process, so a 1000-alert burst is 1000 short-lived processes rather than one process handling 1000 items. Correctness under the burst comes from the storage layer, not from concurrency inside the script.
• Concurrency. State lives in a SQLite store in WAL mode with a busy timeout. The check-and-write runs inside a single BEGIN IMMEDIATE transaction, so concurrent processes for the same package serialize on the write lock and exactly one wins.
• Hot path. Suppressed alerts exit on one indexed lookup and never open an SMTP connection. smtplib is imported lazily so the suppression path does not pay the import cost.
• Window anchoring. The suppression window is measured from the first notification, not from the last alert seen. Anchoring on the last alert would let a steady drip of CVEs slide the window forward indefinitely and silence a package permanently.
• Fail open. If the store cannot be opened or the de-duplication check raises, the alert is emailed. A duplicate is preferable to a dropped notification.
• Maintenance. Cleanup is an explicit prune mode driven by a command wodle rather than opportunistic work on the alert hot path. The table is bounded by distinct (agent, package, status) combinations, not by alert volume, so this is housekeeping rather than growth control.

Files

• custom-email.py - integration logic, Python standard library only.
• custom-email - standard Wazuh shell wrapper for the embedded interpreter.
• README.md - installation, configuration table, ossec.conf blocks for both the integration and the prune wodle, testing steps, troubleshooting, provenance.

Testing

Verified end to end against a local SMTP sink on Python 3.11:

• First alert for a package sends one email; a second CVE for the same agent and package is suppressed and increments cve_count.
• Non-vulnerability alerts are emailed unchanged.
• Ageing a row past the window re-notifies, confirming recurring problems stay visible.
• 2,000-alert burst across 300 distinct (agent, package, status) combinations at 64-way concurrency: 300 emails sent, one per distinct key, an 85% reduction. SUM(cve_count) equalled 2,000, confirming no lost updates. No lock errors, ~665 alerts/sec.
• prune mode runs and reports cleanly.

Not yet exercised against a live vulnerability scan on a production manager; the ossec.conf wiring in the README is the documented path for that.

[Copilot]

Pull request overview

Adds a new Wazuh integration (integrations/vulnerability_email_dedup/) that acts as a drop-in custom-email replacement to suppress duplicate Vulnerability Detection emails by de-duplicating on (agent_id, package, status) within a fixed time window, while still passing non-vulnerability alerts through unchanged.

Changes:

• Introduces a SQLite/WAL-backed de-duplication store to suppress duplicate vulnerability emails during bursts.
• Adds a prune maintenance mode intended to be run via a scheduled Wazuh command wodle.
• Provides installation/configuration/testing documentation and a standard Wazuh shell wrapper.

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated 6 comments.

File	Description
integrations/vulnerability_email_dedup/README.md	Documents the integration behavior, configuration, ossec.conf wiring, and testing/maintenance steps.
integrations/vulnerability_email_dedup/custom-email.py	Implements per-alert de-duplication logic with SQLite WAL and a prune maintenance entry point.
integrations/vulnerability_email_dedup/custom-email	Provides the standard Wazuh wrapper to invoke the Python script via the embedded interpreter.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 3 out of 3 changed files in this pull request and generated 3 comments.

[Copilot]

Pull request overview

Copilot reviewed 3 out of 3 changed files in this pull request and generated 2 comments.