Remote Server Deployment

This guide covers manual deployment of Evilginx Pro servers using SSH and SCP. Manual deployment is useful for air-gapped environments, custom server configurations, or troubleshooting deployment issues.

warning

Automated deployment using servers deploy is the recommended method. Use manual deployment only when necessary.

Prerequisites

System Requirements

Requirement	Specification
Operating System	Debian 12/13 (64-bit) / Ubuntu
Architecture	x86_64 (amd64)
SSH Access	Root or sudo-enabled user
Network Ports	80 (TCP), 443 (TCP), 53 (UDP) accessible

info

Only Debian and Ubuntu Linux distributions are currently supported for server deployment.

Local Requirements

Before starting manual deployment, ensure you have:

1. Evilginx Pro client installed and authenticated with BREAKDEV RED
2. Server registered using servers register <server_name>
3. License file retrieved locally
4. SSH client and SCP client (or rsync) installed

Required Files

The following files from your local Evilginx Pro directory need to be uploaded:

File/Directory	Description
bin/linux_amd64/evilginx	Server binary executable
evilpuppet/	Node.js application (exclude node_modules)
static/	Static data files
redirectors/	Redirector configurations
data/licenses/<server_id>.evilginx	Server license file

Deployment Steps

Step 1: Register Server

Register the server with the BREAKDEV RED licensing server to obtain the license file.

servers add <server_name> <server_ip>
servers register <server_name>

Take note of the server_id from the output (e.g., 9c2afee3a5105f0b.evilginx).

Confirm the license file exists at:

./data/licenses/<server_id>.evilginx

tip

You can view the server details including server_id at any time with:

servers view <server_name>

Step 2: Connect to Server

Connect to your server via SSH:

ssh <user>@<server_ip>

Replace <user> with your SSH username and <server_ip> with your server's IP address.

note

All commands in Steps 3, 5, 6, 7, 8, and 9 are executed on the remote server via SSH.

Commands in Step 4 are executed on your local machine.

Step 3: Prepare System

Update Package Lists

sudo apt update

Disable systemd-resolved DNS Stub Listener

The systemd-resolved DNS stub listener conflicts with Evilginx's DNS server on UDP port 53.

sudo sed -i -e '/^\(DNSStubListener=\).*/{ s//\1no/; :a; n; ba; q }' \
  -e '$aDNSStubListener=no' /etc/systemd/resolved.conf
sudo systemctl restart systemd-resolved

Allow Non-Root Applications to Open Low Ports

Evilginx runs as a non-privileged user but needs to open ports 80, 443, and 53.

Using sysctl.d (preferred):

echo 'net.ipv4.ip_unprivileged_port_start=0' | \
  sudo tee /etc/sysctl.d/99-evilginx-pro.conf
sudo sysctl -p /etc/sysctl.d/99-evilginx-pro.conf

Fallback using sysctl.conf:

sudo sed -i -e '/^\(net.ipv4.ip_unprivileged_port_start=\).*/{ s//\10/; :a; n; ba; q }' \
  -e '$anet.ipv4.ip_unprivileged_port_start=0' /etc/sysctl.conf
sudo sysctl -p

Create evilginx User

If you're not already logged in as the evilginx user, create it:

sudo adduser --home /home/evilginx --shell /bin/bash \
  --gecos "" --disabled-password evilginx
sudo adduser evilginx sudo

Create Directory Structure

Create temporary upload directory:

mkdir -p ~/evilginx-pro/data/licenses

Create final installation directory:

sudo mkdir -p /home/evilginx/evilginx-pro

Step 4: Upload Files

Execute these commands from your local machine in the Evilginx Pro directory.

Evilginx Binary

scp ./bin/linux_amd64/evilginx <user>@<server_ip>:~/evilginx-pro/evilginx

Evilpuppet Directory

Using rsync (recommended - automatically excludes node_modules):

rsync -avz --exclude 'node_modules' ./evilpuppet/ \
  <user>@<server_ip>:~/evilginx-pro/evilpuppet/

Or using scp:

scp -r ./evilpuppet <user>@<server_ip>:~/evilginx-pro/

warning

When using scp, manually ensure node_modules is not included. The node_modules directory is regenerated during installation and should not be uploaded.

License File

scp ./data/licenses/<server_id>.evilginx \
  <user>@<server_ip>:~/evilginx-pro/data/licenses/server.evilginx

info

The license file is renamed from <server_id>.evilginx to server.evilginx on the remote server.

Static Data Files

scp -r ./static <user>@<server_ip>:~/evilginx-pro/

Redirectors

scp -r ./redirectors <user>@<server_ip>:~/evilginx-pro/

Step 5: Set Permissions

Back on the remote server via SSH, set executable permissions:

chmod 700 ~/evilginx-pro/evilginx
chmod 700 ~/evilginx-pro/evilpuppet/evilpuppet
chmod 700 ~/evilginx-pro/evilpuppet/evilchrome

Set ownership for the upload directory:

sudo chown -R $USER:$USER ~/evilginx-pro/

Step 6: Create Configuration File

Check if a configuration file already exists:

ls ~/evilginx-pro/data/server.json

If the file doesn't exist, create a new configuration:

cat > ~/evilginx-pro/data/server.json <<'EOF'
{
  "general": {
    "external_ipv4": "<server_ip>"
  }
}
EOF

Replace <server_ip> with your actual server IP address.

tip

If you're redeploying to a server that already has Evilginx Pro installed, the existing configuration will be preserved in Step 7.

Step 7: Move Files to Final Location

If a previous deployment exists, preserve the configuration:

sudo cp ~/evilginx-pro/data/server.json \
  /home/evilginx/evilginx-pro/data/server.json 2>/dev/null || true

Copy all files to the final installation directory:

sudo cp -R ~/evilginx-pro/* /home/evilginx/evilginx-pro/
sudo chown -R evilginx:evilginx /home/evilginx/evilginx-pro/

Clean up the temporary upload directory:

rm -rf ~/evilginx-pro

Step 8: Install Dependencies

Install Evilchrome

sudo /home/evilginx/evilginx-pro/evilpuppet/evilchrome install

warning

This command downloads Google Chrome and may take several minutes.

Install Evilpuppet

sudo /home/evilginx/evilginx-pro/evilpuppet/evilpuppet install

This command installs Node.js dependencies required by Evilpuppet.

Step 9: Set Up and Start Services

Install systemd Daemons

sudo /home/evilginx/evilginx-pro/evilginx install

This creates and configures systemd service units for Evilginx and Evilpuppet.

Start Evilginx

sudo /home/evilginx/evilginx-pro/evilginx start

This starts both the Evilginx server and Evilpuppet services.

Verification

Check Service Status

Verify that services are running:

sudo systemctl status evilginx
sudo systemctl status evilpuppet

Both services should show as active (running).

Connect from Client

From your local machine, connect to the server using the Evilginx Pro client:

servers connect <server_name>

If the connection succeeds, you'll see the server name prefixing the command prompt.

Verify Server Version

Check the server list to confirm deployment:

servers

The server should show the current Evilginx Pro version in the version column.

Troubleshooting

SSH Connection Failures

• Verify SSH key permissions are 600: chmod 600 ~/.ssh/id_rsa
• Check SSH port configuration matches server settings
• Ensure the SSH user is root or has sudo privileges

Permission Errors

Verify file ownership:

ls -la /home/evilginx/evilginx-pro

All files should be owned by evilginx:evilginx. Re-run the ownership command if needed:

sudo chown -R evilginx:evilginx /home/evilginx/evilginx-pro/

Service Startup Failures

Check service logs for errors:

sudo journalctl -a -u evilginx -n 50
sudo journalctl -a -u evilpuppet -n 50

Common issues:

• Missing license file: Verify /home/evilginx/evilginx-pro/data/licenses/server.evilginx exists
• Port conflicts: Ensure no other services are using ports 80, 443, or 53
• Missing dependencies: Re-run installation steps 8 and 9

Connection from Client Fails

Verify network connectivity:

• Ensure firewall allows incoming connections on ports 80, 443, and 53
• Check server license hasn't expired. Running the client through ./evilginx renew command will automatically renew the licenses. If this doesn't help the server may need to be recreated and registered under a new server_id.
• Confirm server_id in the license file matches the server registration

Post-Deployment

Server License Renewal

Server licenses are automatically renewed by the Evilginx Pro client.

If your license expires, renew it by running:

servers deploy <server_name>

Updating the Server

To update to a newer version of Evilginx Pro:

1. Update your local Evilginx Pro client
2. Either run automated update:

   servers deploy <server_name>

3. Or repeat the manual deployment steps with updated files

Server Management Commands

Manage the server from SSH:

Command	Description
sudo /home/evilginx/evilginx-pro/evilginx start	Start services
sudo /home/evilginx/evilginx-pro/evilginx stop	Stop services
sudo /home/evilginx/evilginx-pro/evilginx restart	Restart services
sudo /home/evilginx/evilginx-pro/evilginx status	Check status
sudo systemctl status evilginx	Detailed status

Security Considerations

• License file security: The server license contains sensitive authentication data. Protect it during transfer and storage.
• SSH hardening: Use key-based authentication only. Disable password authentication in /etc/ssh/sshd_config.
• File integrity: Verify checksums of uploaded files if working in high-security environments.
• Access restrictions: Limit SSH access using firewall rules or fail2ban after deployment.
• Regular updates: Keep Evilginx Pro updated to receive security patches.

info

Deployed Evilginx Pro servers never contact the licensing server. All license updates are performed by the client through SSH for OPSEC and privacy.