Wireguard Peer Monitoring

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:

Endpoint's IP
Endpoint's Port
Last keepalive time
Last handshake time

How to

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

Events

There are many Wireguard events that can be captured. You can update the code to handle more events. Here are some of them:

wg_cookie_message_consume: Could not decrypt invalid cookie response
send4: No route to <IP:PORT>, error <ERROR CODE>
send6: No route to <IP:PORT>, error <ERROR CODE>
wg_receive_handshake_packet: Receiving cookie response from <IP:PORT>
wg_receive_handshake_packet: Invalid MAC of handshake, dropping packet from <IP:PORT>
wg_receive_handshake_packet: Invalid handshake initiation from <IP:PORT>
wg_receive_handshake_packet: Receiving handshake initiation from peer <PEER ID> (<IP:PORT>)
wg_receive_handshake_packet: Invalid handshake response from <IP:PORT>
wg_receive_handshake_packet: Receiving handshake response from peer <PEER ID> (<IP:PORT>)
wg_packet_consume_data_done: Receiving keepalive packet from peer <PEER ID> (<IP:PORT>)
wg_packet_consume_data_done: Packet has unallowed src IP <IP> from peer <PEER ID> (<IP:PORT>)
wg_packet_consume_data_done: Packet is neither ipv4 nor ipv6 from peer <PEER ID> (<IP:PORT>)
wg_packet_consume_data_done: Packet has incorrect size from peer <PEER ID> (<IP:PORT>)
wg_packet_rx_poll: Packet has invalid nonce <PEER ID> (max <PEER ID>)
wg_packet_receive: Dropping handshake packet from <IP:PORT>
wg_packet_send_handshake_initiation: Sending handshake initiation to peer <PEER ID> (<IP:PORT>)
wg_packet_send_handshake_response: Sending handshake response to peer <PEER ID> (<IP:PORT>)
wg_packet_send_handshake_cookie: Sending cookie response for denied handshake message for <IP:PORT>
wg_packet_send_keepalive: Sending keepalive packet to peer <PEER ID> (<IP:PORT>)
wg_expired_retransmit_handshake: Handshake for peer <PEER ID> (<IP:PORT>) did not complete after <TRY NUMBER> attempts, giving up
wg_expired_retransmit_handshake: Handshake for peer <PEER ID> (<IP:PORT>) did not complete after <SEC> seconds, retrying (try <TRY NUMBER>)
wg_expired_new_handshake: Retrying handshake with peer <PEER ID> (<IP:PORT>) because we stopped hearing back after <SEC> seconds
wg_queued_expired_zero_key_material: Zeroing out all keys for peer <PEER ID> (<IP:PORT>), since we haven't received a new one in <SEC> seconds
wg_peer_create: Peer <PEER ID> created
kref_release: Peer <PEER ID> (<IP:PORT>) destroyed
wg_xmit: Invalid IP packet
wg_xmit: No peer has allowed IPs matching <IPv4>
wg_xmit: No peer has allowed IPs matching <IPv6>
wg_xmit: No valid endpoint has been configured or discovered for peer <PEER ID>
wg_destruct: Interface destroyed
wg_newlink: Interface created
wg_netns_pre_exit: Creating namespace exiting
keypair_free_kref: Keypair <PEER ID> destroyed for peer <PEER ID>
wg_noise_handshake_begin_session: Keypair <PEER ID> created for peer <PEER ID>

Monitoring

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.

Support 💛

Contributing 🤝

Don't be shy and reach out to us if you want to contribute 😉

Fork it!
Create your feature branch: git checkout -b my-new-feature
Commit your changes: git commit -am 'Add some feature'
Push to the branch: git push origin my-new-feature
Submit a pull request

Issues

Each project may have many problems. Contributing to the better development of this project by reporting them. 👍

hatamiarash7 / Wireguard-Peer-Monitoring