Skip to main content

Local Installation Guide

This guide provides step-by-step instructions for installing and running the Evilginx Pro client, server, and related dependencies on a local machine. This setup is useful for testing Evilginx Pro, creating phishing scenarios, or setting up a demo without requiring a production server or domain.

Installation​

Evilginx Pro comes as a precompiled binary:

  • evilginx for Linux/macOS
  • evilginx.exe for Windows

It can function as either a server or a client, depending on the launch parameters.

To run the Evilginx Pro server properly, you need to install Evilpuppet, an external module running as a Node.js application. Evilpuppet requires:

  • node.js (version 18)
  • Google Chrome

Follow the steps below to install these dependencies.

Install Node.js​

The recommended way to install node.js is through nvm (Node Version Manager).

  1. Download and install the latest version of nvm-windows.

  2. Open cmd.exe and install node.js:

    nvm install 18
    nvm use 18

  3. Verify that node.js is now installed with required version:

    node -v

Install Evilpuppet​

  1. Open the terminal and change the directory to the one where you installed Evilginx Pro.

  2. Install all the required NPM packages for Evilpuppet:

    cd evilpuppet
    npm install

Install Google Chrome​

  1. Install Google Chrome if it's not already installed.

  2. Copy the path to the Chrome executable, e.g. /Applications/Google Chrome.app/Contents/MacOS/Google Chrome

Setup​

To run Evilginx Pro, you must first install a server license and import the Certificate Authority (CA).

Obtain a Server License​

  1. Run Evilginx Pro in client mode:

    evilginx.exe

  2. Log in to your BREAKDEV RED account when prompted.

  3. Create and register a local server:

    servers add local 127.0.0.1
    servers register local

  4. Copy the generated server_id (e.g.: 0a1b2c3d4e5f6079.evilginx) from the output.

    tip

    If you missed the command output, you can display the server parameters any time with command: servers view local

  5. Open a new terminal window and locate the directory to which you unpacked Evilginx Pro

  6. Copy the generated licence file from ./data/licenses/ to server.evilginx (rembember to replace the server ID you copied earlier):

    copy .\data\licenses\0a1b2c3d4e5f6079.evilginx .\data\licenses\server.evilginx
info

The reason why it is the Evilginx Pro client retrieving the license from the license server and not the server downloading the license, is because Evilginx servers are designed to never make any outbound connections to the licensing server for OPSEC reasons. Evilginx client needs to always retrieve the license and upload it to the server on its own.

Import Certificate Authority​

The phishing links you will be generating for local tests will not open in your local web browser if the TLS certificates served by Evilginx Pro web server are not signed by a trusted certificate authority. When Evilginx Pro is deployed remotely in production state this is handled automatically by retrieving TLS certificates signed by LetsEncrypt CA, but for self-signed certificates to work locally, we need our locally trusted certificate authority.

Evilginx Pro on its first run in server mode, will generate a new CA root certificate, which you need to import as a trusted CA.

  1. Run Evilginx Pro in server mode to generate a root CA certificate:

    evilginx.exe -server -developer -debug

  2. Enter your password when prompted. The root CA certificate is stored at: ./data/crt/ca.crt.

  3. Close the server by pressing <Control+C>.

  4. Import the certificate into your trusted CA certificate storage with the following command:

    Make sure to start cmd.exe with Run as Administrator.

    certutil -addstore -f "ROOT" .\data\crt\ca.crt

After importing, browsers like Chrome will recognize TLS certificates generated by Evilginx Pro as trusted.

Launch Evilginx Pro Locally​

To run Evilginx Pro locally, open four separate terminal windows, one for each module:

  • Evilpuppet
  • Google Chrome
  • Evilginx Pro Server
  • Evilginx Pro Client

Evilpuppet​

  1. Open the terminal and change the directory to the one where you installed Evilginx Pro.

  2. Run Evilpuppet:

    cd evilpuppet
    npm start

Google Chrome​

  1. Open the terminal and change the directory to the one where you installed Evilginx Pro.

  2. Type the following commands to set up the variables (replace the first path with the directory where Google Chrome is installed):

    set CHROME_EXEC_PATH="C:\Program Files (x86)\Google\Chrome\Application\chrome.exe"
    set CHROME_USER_DIR="C:\tools\evilginx-pro\evilpuppet\profile"
    variabledescription
    CHROME_EXEC_PATHPath to chrome.exe executable in directory where Google Chrome is installed.
    CHROME_USER_DIRPath to directory, which will store the Chrome profile.

  3. Start Google Chrome with a provided script from ./evilpuppet directory:

    cd evilpuppet
    chrome_run.bat

Evilginx Server​

  1. Open the terminal and change the directory to the one where you installed Evilginx Pro.

  2. Start the Evilginx Pro in server mode:

    evilginx.exe -P 127.0.0.1:44500 -server -developer -debug

    See below description of the parameters available to use:

    parameterdescription
    -P <address:port>Address and port on which Evilpuppet is listening. Evilginx will communicate with Evilpuppet over this connection.
    -serverMakes Evilginx start as a server and not as a client.
    -developerTells Evilginx that we are running the server locally and that it should disable features like TLS certificate retrieval.
    -debugEnables additional debug output, which may be helpful during phishlet development.
    -d <path>Change the directory path for storing local data (default: ./data)
    -w <path>Change the working directory (default: .)

Evilginx Client​

  1. Open the terminal and change the directory to the one where you installed Evilginx Pro.

  2. Start the Evilginx Pro in client mode:

    evilginx.exe

  1. Connect to your local Evilginx Pro server by entering the command:

    servers connect local
info

Remember that in order to have your local phishing hostnames resolved to your local IP address, you will need to modify the /etc/hosts file.