mullvadshal 1.0.1

Mullvadshål is utomated server-hopping for Mullvad VPN for WireGuard and Linux

Mullvadshål

Mullvadshål (mullvadshal) is an automated server-hopping tool for Mullvad VPN using WireGuard on Linux. It allows you to automatically switch to different Mullvad servers, enhancing security and privacy.

Why?

When using a VPN, staying connected to the same server for prolonged periods introduces certain risks. Mullvadshål mitigates these by allowing you to automate periodic server changes, reducing exposure to various attack vectors:

• Minimizing Traffic Correlation Attacks: Attackers attempting to track users often analyze incoming and outgoing traffic to correlate activity. Frequent server switching disrupts patterns, making it harder to establish a link between a user and their online actions.
• Disrupting Long-Term Tracking: Some ISPs, adversaries, or malicious actors attempt to profile VPN users based on consistent IP usage. Changing VPN servers frequently obfuscates user activity and makes long-term tracking more difficult.
• Reducing Exposure to Compromised Servers: VPN servers can be compromised by attackers or monitored by authorities. Regularly switching reduces the risk of prolonged exposure to any single compromised endpoint.
• Enhancing Anonymity in Shared Exit Nodes: Mullvad VPN servers act as shared exit nodes, meaning multiple users are assigned the same IP. By switching servers, a user benefits from additional layers of obfuscation and blends in with different traffic groups over time.
• Bypassing Geo-Restrictions & Network Censorship: Some websites and services impose restrictions based on VPN server IPs. Rotating through servers increases the chances of maintaining access without detection.

For privacy-conscious users, journalists, activists, and those in restrictive environments, automating server hops can be a crucial tool for reducing digital footprints and maintaining operational security.

OS support

Only modern Linux distributions are supported. There are no plans to support other operating systems.

Mullvadshål might work on Mac, if you try hard enough.

Recommended Use

To maximize effectiveness, Mullvadshål should be automated using cron or/and triggered by user actions. It is recommended to:

• Update the server list at least once per day to ensure the latest Mullvad VPN servers are available (mullvadshal update).
• Perform server jumps during periods of inactivity to minimize disruption. A good approach is to run it at times when the user is away, such on cron schedule when the screen is locked, when the screen is unlocked, or/and whenever the system resumes from suspension (e.g. After=suspend.target as a Systemd service). (mullvadshal jump)

Features

• Automated Server Updates: Fetches the latest Mullvad WireGuard server list.
• Periodic Server Hopping: Switches to a random Mullvad server to reduce tracking.
• Configurable Network Modes: Supports IPv4, IPv6, and dual-stack configurations.
• Persistent Configuration: Stores WireGuard settings securely.
• Lightweight & CLI-Based: Ideal for cron jobs and automation.

TODO

• Support for multi-hop
• Kill-switch while jumping

Installation

Ensure you have Python and WireGuard installed:

pip install mullvadshal

Or install manually by cloning the repository:

git clone https://github.com/Addvilz/mullvadshal.git
cd mullvadshal
pip install .

Usage

Authenticate with Mullvad

Before using the tool, authenticate your WireGuard interface with your Mullvad account:

mullvadshal auth

This will prompt for your Mullvad account number.

Update Mullvad Server List

To fetch the latest Mullvad WireGuard servers, run:

mullvadshal update --filter se,de,fi

This command filters servers by Sweden (se), Germany (de), and Finland (fi). You can also specify a location, like se-got.

Perform a Server Hop

To switch to a new random server (within the previously filtered server list):

mullvadshal jump [--sudo]

Warning: Jumping servers disrupts your network connection momentarily.

Jump command should generally be either run as root, or with no password sudoers configured.

If you do not use cron, you can also simply run it with --sudo and type in your sudo password.

Automating with Cron

To automate server updates and jumps:

1. Open your crontab:

   crontab -e
   

2. Add the following lines:

   # Update server list daily at 3 AM
   0 3 * * * mullvadshal update --filter se,de,fi
   
   # Jump to a new server every hour
   0 * * * * mullvadshal jump
   

Troubleshooting

Ensure wg-quick is installed on your system:

For Debian/Ubuntu-based distributions (APT package manager):

sudo apt update && sudo apt install -y wireguard-tools

For RHEL/CentOS/Fedora-based distributions (RPM package manager):

sudo dnf install -y wireguard-tools   # For Fedora, RHEL 8+, and CentOS 8+
sudo yum install -y wireguard-tools   # For older RHEL/CentOS versions

For Arch Linux and Manjaro (Pacman package manager):

sudo pacman -S wireguard-tools

For OpenSUSE (Zypper package manager):

sudo zypper install -y wireguard-tools

• Run with --debug to get detailed error messages.
• If an error occurs during jump, verify that the WireGuard interface is correctly configured.

License

Mullvadshål is licensed under the Apache License Version 2.0

Contributing

Pull requests and bug reports are welcome. Please submit issues on GitHub.

Disclaimer

Mullvadshål is an independent project and is not affiliated with, endorsed by, or associated with Mullvad VPN AB. All trademarks, service marks, and company names belong to their respective owners.

This software is provided "as is," without any warranties or guarantees. The authors are not responsible for any misuse, legal issues, or damages resulting from the use of this project. Use at your own risk and ensure compliance with applicable laws and regulations.