WireGuard is a modern, fast, and extremely simple VPN that uses state-of-the-art cryptography. However, one of its design choices is a minimalist approach to event logging: by default, WireGuard does not write detailed events to a dedicated log file, which can be a challenge for security monitoring.
This guide provides a practical solution to monitor a Linux-based WireGuard server and integrate it with Wazuh. We use rsyslog to capture WireGuard kernel-level events and send them to a custom log file, plus custom Wazuh decoders and rules to analyze these logs and generate meaningful security alerts.
Event monitoring capabilities
This integration lets you monitor events such as:
- 130001: Successful handshake initiations
- 130002: Invalid handshake initiations (possible attacks or misconfigurations)
- 130003: Standard keepalive packets
- 130004: Packets sent from a non-allowed source IP (policy violation, possible attack)
Requirements
- A WireGuard server installed on a Linux host
- A Wazuh agent installed on the same Linux host
- rsyslog service (installed by default on most Linux distributions)
Part 1: Enable log capture via rsyslog on the WireGuard server
First, we need to configure rsyslog to listen for kernel messages containing “wireguard” and forward them to a dedicated log file.
Step 1: Create a new rsyslog config file
vim /etc/rsyslog.d/20-wireguard.conf
Step 2: Add the following rules to the file
This rule matches any message with “wireguard:”, writes it to /var/log/wireguard.log, and then stops further processing to avoid duplicates.
# Rule for WireGuard logs
:msg, contains, "wireguard:" /var/log/wireguard.log
& stop
Step 3: Restart rsyslog
Save the file and restart rsyslog to apply changes.
systemctl restart rsyslog
You should now see WireGuard events in /var/log/wireguard.log. You can verify with:
tail -f /var/log/wireguard.log
Part 2: Configure the Wazuh agent to monitor the log file
Next we configure the Wazuh agent to read our new log file and send events to the Wazuh Manager. We also add a custom prefix to each log line to help our custom decoders identify the logs.
Step 1: Open the Wazuh agent config
vim /var/ossec/etc/ossec.conf
Step 2: Add the localfile block
Add the following <localfile> block inside the <ossec_config> section.
<localfile>
<location>/var/log/wireguard.log</location>
<log_format>syslog</log_format>
<out_format>wireguard-log: $(log)</out_format>
</localfile>
Note: The <out_format> tag is crucial. It adds the prefix wireguard-log: to each log entry before sending it to the manager. Our parent decoder will use this unique string to match incoming events.
Step 3: Restart the Wazuh agent
Save the file and restart the Wazuh agent.
systemctl restart wazuh-agent
Part 3: Import custom rules and decoders on the Wazuh Manager
On your Wazuh Manager server, download and install the custom rule and decoder files.
Step 1: Clone the GitHub repo
git clone https://github.com/jayzielinski/wazuh-wireguard-integration.git
Step 2: Copy decoder and rule files
Copy the decoder and rule files to the correct Wazuh directories.
cp wazuh-wireguard-integration/130000-wireguard_decoders.xml /var/ossec/etc/decoders/
cp wazuh-wireguard-integration/130000-wireguard_rules.xml /var/ossec/etc/rules/
Step 3: Set ownership and permissions
Set correct ownership and permissions so the Wazuh manager can read the new files.
chown wazuh:wazuh /var/ossec/etc/rules/130000-wireguard_rules.xml
chmod 660 /var/ossec/etc/rules/130000-wireguard_rules.xml
Step 4: Restart Wazuh Manager
Restart the Wazuh Manager service to load the new decoders and rules.
systemctl restart wazuh-manager
Part 4: Test the integration
You can test the rules by triggering specific events on a WireGuard client.
Test case 1: Trigger rule 130004 (unallowed IP)
This rule detects when a legitimate peer sends traffic from an IP address that is not listed in its AllowedIPs configuration on the server.
To trigger it, change your WireGuard client config so the client’s Address is an IP not covered by the server’s AllowedIPs for that peer, then try to send traffic.
Result on the WireGuard server (/var/log/wireguard.log):
A log entry will appear indicating a packet with a non-allowed source IP.
Result in the Wazuh Dashboard: An alert will be generated with the description WireGuard: Peer [...] sent a packet with an unallowed source IP [...].
Test case 2: Trigger rule 130002 (Invalid handshake)
This rule detects a failed handshake attempt, which can occur due to a mismatched private/public key pair. This is a critical security event to monitor.
To trigger it, change the PrivateKey in your WireGuard client config to an incorrect value and try to connect to the server.
Result in the Wazuh Dashboard: An alert will be generated with the description WireGuard: Invalid handshake initiation from [...].
Conclusion
Your integration is now complete and actively monitoring your WireGuard server. This setup enables security monitoring of WireGuard VPN connections, helping you detect possible attacks, misconfigurations, and policy violations in real time.
Repository
For the full integration files (decoders and rules), see:
- GitHub repository: https://github.com/jayzielinski/wazuh-wireguard-integration
References
- Original article: https://www.cylenth.blog/posts/wazuh-wireguard-monitoring
- Wazuh documentation: https://documentation.wazuh.com/
- WireGuard documentation: https://www.wireguard.com/
