Monitor Wireguard peers using kernel events
MIT License
This project uses Linux kernel dynamic debug features to capture and process Wireguard events and monitor peer activity.
This assumes that debugfs
is mounted under /sys/kernel/debug
.
The main purpose of this project is monitor Wireguard peers. Currently, It can be used to detect and handle handshake
and keepalive
events (You can handle more events, check Events section).
All peer's information will be stored in Redis for further analysis. Also, notify the user when a peer's endpoint (IP, PORT) is updated.
These data will be stored in Redis for each peer:
First, you need to enable Wireguard debug logs. You can do this by running the following command:
echo 'module wireguard +p' | sudo tee /sys/kernel/debug/dynamic_debug/control
Configure rsyslog to capture the logs. You can do this by adding the following line to /etc/rsyslog.d/99-wireguard.conf
:
kern.* @127.0.0.1:9999
Create a new config file and fill it will proper data:
cp config.example.toml config.toml
Run project to capture and handle events:
CONFIG_FILE="config.toml" make run
Or using Docker
docker run -d -v $(pwd)/config.toml:/app/config.toml -p 9999:9999/udp -p 9998:9998 hatamiarash7/wg-peer-monitoring:latest
# Or
docker compose up -d
There are many Wireguard events that can be captured. You can update the code to handle more events. Here are some of them:
Could not decrypt invalid cookie response
No route to <IP:PORT>, error <ERROR CODE>
No route to <IP:PORT>, error <ERROR CODE>
Receiving cookie response from <IP:PORT>
Invalid MAC of handshake, dropping packet from <IP:PORT>
Invalid handshake initiation from <IP:PORT>
Receiving handshake initiation from peer <PEER ID> (<IP:PORT>)
Invalid handshake response from <IP:PORT>
Receiving handshake response from peer <PEER ID> (<IP:PORT>)
Receiving keepalive packet from peer <PEER ID> (<IP:PORT>)
Packet has unallowed src IP <IP> from peer <PEER ID> (<IP:PORT>)
Packet is neither ipv4 nor ipv6 from peer <PEER ID> (<IP:PORT>)
Packet has incorrect size from peer <PEER ID> (<IP:PORT>)
Packet has invalid nonce <PEER ID> (max <PEER ID>)
Dropping handshake packet from <IP:PORT>
Sending handshake initiation to peer <PEER ID> (<IP:PORT>)
Sending handshake response to peer <PEER ID> (<IP:PORT>)
Sending cookie response for denied handshake message for <IP:PORT>
Sending keepalive packet to peer <PEER ID> (<IP:PORT>)
Handshake for peer <PEER ID> (<IP:PORT>) did not complete after <TRY NUMBER> attempts, giving up
Handshake for peer <PEER ID> (<IP:PORT>) did not complete after <SEC> seconds, retrying (try <TRY NUMBER>)
Retrying handshake with peer <PEER ID> (<IP:PORT>) because we stopped hearing back after <SEC> seconds
Zeroing out all keys for peer <PEER ID> (<IP:PORT>), since we haven't received a new one in <SEC> seconds
Peer <PEER ID> created
Peer <PEER ID> (<IP:PORT>) destroyed
Invalid IP packet
No peer has allowed IPs matching <IPv4>
No peer has allowed IPs matching <IPv6>
No valid endpoint has been configured or discovered for peer <PEER ID>
Interface destroyed
Interface created
Creating namespace exiting
Keypair <PEER ID> destroyed for peer <PEER ID>
Keypair <PEER ID> created for peer <PEER ID>
You can use Prometheus to scrape internal metrics. You can configure your metric configuration in config.toml
file.
metrics_host
: The host that the metrics server will listen on.metrics_port
: The port that the metrics server will listen on.Check http://localhost:9998. The following metrics are available:
wg_peer_monitoring_app_version_info
: The version information of the application.wg_peer_monitoring_wg_wireguard_events_total
: The total number of Wireguard events per event's title and peer's ID.wg_peer_monitoring_wg_wireguard_events_created
: The latest timestamp of Wireguard events that have been created. per event's title and peer's ID.Don't be shy and reach out to us if you want to contribute 😉
git checkout -b my-new-feature
git commit -am 'Add some feature'
git push origin my-new-feature
Each project may have many problems. Contributing to the better development of this project by reporting them. 👍