Vpn Rotate Skill

Bypass API rate limits by rotating VPN servers. Works with any OpenVPN-compatible VPN (ProtonVPN, NordVPN, Mullvad, etc.). Automatically rotates to new server every N requests for fresh IPs. Use for high-volume scraping, government APIs, geo-restricted data.

Security Scan

The skill appears to implement what it claims (rotating OpenVPN configs to change IPs), but its setup/instructions ask you to add a passwordless sudoers entry (including kill permissions), store plaintext VPN credentials, and run system-level commands — these are security-sensitive and warrant caution.

Purpose & Capability

The name/description match the implementation: the package manipulates OpenVPN (.ovpn) configs, connects/disconnects OpenVPN, rotates servers, and exposes a decorator + CLI for integration. There are no unrelated credentials or external services requested, and code operates on expected files (~/.vpn/servers, creds file, ProtonVPN fallback paths).

Instruction Scope

SKILL.md and setup.sh instruct the user to create a credentials file with username/password in plaintext, move provider .ovpn files into a config directory, and add a sudoers entry to allow passwordless openvpn and kill operations. The setup also looks for and may reuse ProtonVPN config/credential paths. These instructions expand scope to system configuration changes and persistent credential storage beyond merely invoking OpenVPN.

Install Mechanism

There is no formal install spec (instruction-only), so nothing is pulled from remote sources; code files are bundled with the skill. The included setup.sh can install OpenVPN via apt (uses sudo), which is expected but means the script will perform system package installs when run.

Credentials

The skill does not request environment variables or external secrets, which matches its purpose. However, it writes VPN credentials to a local plaintext file (~/.vpn/creds.txt) and may read ProtonVPN credential/config paths; storing credentials on disk is necessary for OpenVPN but increases risk if the host is compromised.

Persistence & Privilege

The setup wizard adds a /etc/sudoers.d/vpn-rotate entry granting NOPASSWD for /usr/sbin/openvpn, /usr/bin/killall, and /bin/kill. Allowing passwordless sudo for these commands (especially general kill utilities) gives elevated power that could be abused if configs or binaries are tampered with. The skill does not request always: true and does not alter other skills, but the sudoers modification is a permanent, system-wide privileged change.

What to consider before installing

This skill is coherent with its stated purpose (rotating OpenVPN configs) but asks you to make security-sensitive system changes. Before installing or running it, consider the following: - Review the code yourself (you have the files) and confirm there are no remote endpoints or hidden behaviors beyond those documented. The included code is local and readable. - Do NOT blindly add the sudoers entry: granting NOPASSWD for openvpn and especially for kill/killall gives root-level capabilities that could be abused if an attacker can control the OpenVPN configs or the openvpn binary. If you need passwordless operation, prefer a tightly-scoped wrapper script with a fixed PID file or use sudoers argument restrictions, or run the skill in an isolated environment. - Store credentials securely: the skill writes username/password to ~/.vpn/creds.txt. If you must use a creds file, ensure strict permissions (chmod 600) and prefer OS credential stores or ephemeral credentials where possible. - Run in isolation: consider running this code inside a disposable VM, container, or dedicated machine — do not run on multi-user or sensitive hosts. - Consider alternatives: provider-approved APIs, paid proxy/rotating-IP services, or sanctioned rate-limit strategies may be safer and reduce legal/TOS risk. - If you proceed, limit the sudoers entry to the minimum required and audit it (review /etc/sudoers.d/vpn-rotate). Remove the sudoers entry and creds when you no longer need the skill. If you want, I can: (1) show specifically where the sudoers line is added and suggest a safer sudoers line or wrapper script; (2) highlight the exact places credentials are written/read so you can modify them to use a secure store; or (3) suggest how to run the skill inside a container with minimal privileges.

Rotate VPN servers to bypass API rate limits. Works with any OpenVPN-compatible VPN.

Setup

1. Run Setup Wizard

./scripts/setup.sh

This will:

• Check OpenVPN is installed
• Help you configure your VPN provider
• Set up passwordless sudo
• Test the connection

2. Manual Setup

If you prefer manual setup:

# Install OpenVPN
sudo apt install openvpn

# Create config directory
mkdir -p ~/.vpn/servers

# Download .ovpn files from your VPN provider
# Put them in ~/.vpn/servers/

# Create credentials file
echo "your_username" > ~/.vpn/creds.txt
echo "your_password" >> ~/.vpn/creds.txt
chmod 600 ~/.vpn/creds.txt

# Enable passwordless sudo for openvpn
echo "$USER ALL=(ALL) NOPASSWD: /usr/sbin/openvpn, /usr/bin/killall" | sudo tee /etc/sudoers.d/openvpn

Usage

Decorator (Recommended)

from scripts.decorator import with_vpn_rotation

@with_vpn_rotation(rotate_every=10, delay=1.0)
def scrape(url):
    return requests.get(url).json()

# Automatically rotates VPN every 10 calls
for url in urls:
    data = scrape(url)

VPN Class

from scripts.vpn import VPN

vpn = VPN()

# Connect
vpn.connect()
print(vpn.get_ip())  # New IP

# Rotate (disconnect + reconnect to different server)
vpn.rotate()
print(vpn.get_ip())  # Different IP

# Disconnect
vpn.disconnect()

Context Manager

from scripts.vpn import VPN

vpn = VPN()

with vpn.session():
    # VPN connected
    for url in urls:
        vpn.before_request()  # Handles rotation
        data = requests.get(url).json()
# VPN disconnected

CLI

python scripts/vpn.py connect
python scripts/vpn.py status
python scripts/vpn.py rotate
python scripts/vpn.py disconnect
python scripts/vpn.py ip

Configuration

Decorator Options

@with_vpn_rotation(
    rotate_every=10,      # Rotate after N requests
    delay=1.0,            # Seconds between requests
    config_dir=None,      # Override config directory
    creds_file=None,      # Override credentials file
    country=None,         # Filter servers by country prefix (e.g., "us")
    auto_connect=True,    # Connect automatically on first request
)

VPN Class Options

VPN(
    config_dir="~/.vpn/servers",
    creds_file="~/.vpn/creds.txt", 
    rotate_every=10,
    delay=1.0,
    verbose=True,
)

Recommended Settings

API Aggressiveness	rotate_every	delay
Aggressive (Catastro, LinkedIn)	5	2.0s
Standard	10	1.0s
Lenient	20-50	0.5s

Files

vpn-rotate-skill/
├── SKILL.md              # This file
├── README.md             # Overview
├── scripts/
│   ├── vpn.py            # VPN controller
│   ├── decorator.py      # @with_vpn_rotation
│   └── setup.sh          # Setup wizard
├── examples/
│   └── catastro.py       # Spanish property API example
└── providers/
    ├── protonvpn.md      # ProtonVPN setup
    ├── nordvpn.md        # NordVPN setup
    └── mullvad.md        # Mullvad setup

Troubleshooting

"sudo: a password is required"

Run the setup script or manually add sudoers entry:

echo "$USER ALL=(ALL) NOPASSWD: /usr/sbin/openvpn, /usr/bin/killall" | sudo tee /etc/sudoers.d/openvpn

Connection fails

1. Check credentials are correct
2. Test manually: sudo openvpn --config ~/.vpn/servers/server.ovpn --auth-user-pass ~/.vpn/creds.txt
3. Check VPN provider account is active

Still getting blocked

1. Lower rotate_every (try 5 instead of 10)
2. Increase delay (try 2-3 seconds)
3. Check if API blocks VPN IPs entirely

No .ovpn files

Download from your VPN provider:

• ProtonVPN: https://protonvpn.com/support/vpn-config-download/
• NordVPN: https://nordvpn.com/ovpn/
• Mullvad: https://mullvad.net/en/account/#/openvpn-config