Quickstart Guide

This guide provides a step-by-step tutorial for deploying your first phishing campaign with Evilginx Pro. We'll cover essential configuration steps and highlight some of the Pro features to help you get started quickly.

In each section there will be links to get more information about each specific subject.

Prerequisites

Before starting, ensure you have the following:

• An active Evilginx Pro license linked to your BREAKDEV RED account.
• A domain and server to deploy Evilginx Pro.
• A Cloudflare account for DNS management.

If you want to test Evilginx Pro, create phishing scenarios, or set up a demo without using a production environment, you can follow our Local Installation guide first. This guide will show you how to set up a local server, so you can complete the Quickstart guide without needing a domain, server, or Cloudflare account.

Installation

1. Log in to BREAKDEV RED

• Access your BREAKDEV RED account and navigate to the Evilginx Pro product page.

2. Download Evilginx Pro

• Select the appropriate package for your operating system and CPU architecture from the Downloads section and download it.

3. Unpack and Start

• Extract the ZIP file to a directory of your choice.

• Follow the steps below to start Evilginx Pro based on your operating system:

  Windows

  You can now either double-click the evilginx.exe executable file to start Evilginx Pro or open your favourite terminal app e.g. cmd.exe and type in the following:

  cd <directory_where_you_unpacked_evilginx_pro>
  evilginx.exe

  Linux

  Open the terminal and type in the following:

  cd <directory_where_you_unpacked_evilginx_pro>
  chmod 700 ./evilginx
  ./evilginx

  macOS

  If you do not already have a terminal application for macOS, I highly recommend to first download & install iTerm2.

  Open the terminal and type in the following:

  cd <directory_where_you_unpacked_evilginx_pro>
  chmod 700 ./evilginx
  ./evilginx

Account setup

Logging in

When you run Evilginx Pro for the first time, you will be prompted to sign into your BREAKDEV RED account. Please follow these steps:

1. Enter Your Personal Email: Use the same email address you use to log into your BREAKDEV RED account on the website. If your company email is also set as your account’s personal email, it will work as well.

2. Enter Your Password: Provide the password associated with your BREAKDEV RED account.

3. Enter the MFA Code: Use the multi-factor authentication (MFA) code generated by your MFA application.

Once logged in, Evilginx Pro will acquire an OAuth token for your account. This token prevents the need to re-enter your credentials for future sessions and is automatically refreshed in the background every 15 minutes.

If you experience any issues logging in, please contact BREAKDEV RED suppport for assistance.

Logging out

To log out of your account, use the logout command.

tip

• List all commands: Type help to display a list of all available commands in Evilginx Pro.
• Command-specific help: Type help <command> to learn more about a specific command.
• Auto-complete: Use the <Tab> key to quickly auto-complete commands while typing

Deployment

To deploy your first phishing campaign you will need to host Evilginx Pro on an external third-party server.

Server

Good option is either Amazon AWS or Digital Ocean (affiliate link will get you $200 to start with).

Make sure to pick the right server for your needs and follow the recommended specs:

	Minimum	Recommended
OS	Debian 12	Debian 12
CPU	1 core (64-bit)	1 core (64-bit)
RAM	512 MB	2 GB

Evilpuppet usage

If you're considering to extensively use Evilpuppet, pick more than 2 GB of RAM to account for the memory hungry needs of Chrome background browser.

Consider deploying your server with a preconfigured SSH key as it will make it easier to deploy Evilginx Pro later.

Note down your server's IP address and the path where you saved your SSH private key. We will need those in a moment.

For the sake of demonstration let's assume your server's IP address is 4.8.15.16 and your SSH key is saved at path: /home/user/ssh.key

Firewall settings

Before you proceed, make sure your server allows inbound connections to the following ports:

• TCP: 443 (HTTPS), 22 (SSH)
• UDP: 53 (DNS)

This is especially important if you deployed your server to Amazon AWS. On AWS every newly created instance needs to use preconfigured firewall rules, in which ports need to be opened explicitly. Otherwise all inbound traffic is blocked by default.

Evilginx

Now that your server is up and running, we can turn it into an Evilginx Pro phishing server.

Go back into your Evilginx client, running in the terminal, and type:

servers add my-server 4.8.15.16

This will create a new server in Evilginx client. Next step is to register it with the Evilginx license server:

servers register my-server

The server's certificates have now been successfully retrieved and the Evilginx server is ready to be deployed.

info

You can create, register and deploy as many servers as you want with your current Evilginx Pro license.

You're now all set. All you need to do is issue the deployment command with:

servers deploy my-server

Be patient as first deployment may take a few minutes. You will be able to monitor the deployment status in the terminal window.

Once the server finishes deploying, you can connect to it with the command:

servers connect my-server

You should now see command prompt prefix my-server >, which tells you which server you are currently connected to.

Setup

On successful connection to your server, we are ready to start setting it up.

Web spoofing

The most important first step is to set the URL of the website, which your phishing server will spoof. This website will be reverse proxied and shown to every visitor who does not provide a valid phishing lure URL or who gets blocked by botguard.

This will effectively disguise Evilginx as a legitimate web server.

Type:

config unauth_url https://www.wikipedia.org/

warning

Make sure you set the URL, which does to return an HTTP 301/302 redirect or website spoofing will not work properly.

You can confirm if your picked URL does not return a redirect using curl:

This is a BAD URL, which returns a redirect:

curl -I https://wikipedia.org

This is a GOOD URL without a redirect:

curl -I https://www.wikipedia.org

Phishlet

To set up a phishing campaign we first need to pick our first phishing target. For demonstration purposes we will be phishing users for Microsoft 365 Business accounts.

Evilginx Pro now provides access to official phishlets database, managed by the community. You can download and use officially supported phishlets directly from the BREAKDEV database.

info

There is no guarantee that phishlets available in the database will be functional and constantly up-to-date.

To list the available phishlets in the official repository type:

phishlets db list

First let's list the phishlets managed by user mrgretzky:

phishlets db list mrgretzky

Let's download the MS365 phishlet for enterprise accounts:

phishlets db pull mrgretzky ms365ent

The phishlet will be downloaded and saved in: <evilginx_directory>/phishlets/mrgretzky/ms365.yaml

note

If you need to make modifications to any of the downloaded phishlets, first copy them into <evilginx_directory>/phishlets/private/ directory and then modify them in the new location to avoid overwriting them accidently when updating phishlets from the official repository.

You can now list all of the locally and remotely available phishlets using the command:

phishlets

We can see that our downloaded phishlet is available, but its location currently only lists local. This means the phishlet is currently only available locally on our computer.

We now need to upload the phishlet to the Evilginx Pro server we are currently connected to:

phishlets push mrgretzky/ms365ent

When we now list the available phishlets with phishlets command, we see that the location was updated to local / server, which means the phishlet is now also available on the server and is ready to be used for our phishing campaign.

tip

If you're making modifications to your private phishlets and you want to update them on the server, you can use the same phishlets push command to do so.

Unlike the community version of Evilginx, Evilginx Pro does not need to be restarted to reload the phishlets.

DNS & Domain

If you haven't already, now is the time to register the domain for your phishing campaign. You can do so through a variety of domain providers like Namecheap.

The community version of Evilginx was only able to manage DNS records internally, through its own exposed nameserver. This was often not ideal as nameserver hostnames could quickly expose the phishing server with names like ns1.thephish.com. If you wanted to use an external DNS, you had to manage all DNS records manually.

Evilginx Pro now allows you to use automate the management of external DNS through the API provided by the DNS provider. It also supports multiple domains set up for a single phishing server.

There are currently two DNS providers supported with more to come later:

• Cloudflare
• Digital Ocean

For the sake of demonstration let's assume your registered domain is: thephish.com

Let's first add our domain to the list of managed domains for our server:

domains add thephish.com

We can list the added domains with:

domains

As we see the provider for our added domain is internal by default. This means that the DNS records for our newly added domain will be managed by the Evilginx internal nameserver listening on port UDP 53.

If you wanted to use the internal nameserver you'd need to set up custom nameservers for your domain as follows:

hostname	ipv4
ns1.thephish.com	4.8.15.16
ns2.thephish.com	4.8.15.16

This tells your domain registrar to forward all DNS requests to your phishing server where the Evilginx nameserver is listening.

In this quickstart guide, though, we will use Cloudflare as an external DNS provider.

Make sure you have a Cloudflare account and add thephish.com to the list of managed domains in your account.

After you add your domain in Cloudflare, the panel will tell you the nameservers you need to set up as Custom DNS for your domain in your domain registrar.

Set the provided custom nameservers for your domain like in this example (your nameservers may differ):

nameserver
adi.ns.cloudflare.com
elias.ns.cloudflare.com

After that, generate a new API token with permission to edit DNS records for all zones.

Store your generated DNS API token in a secure location as we will need it shortly to set up DNS management through Cloudflare in Evilginx Pro.

Set Cloudflare as the main DNS provider for your domain and provide your API token with this command:

domains config thephish.com cloudflare <api_token>

Now list all configured DNS records to see if everything works:

domains list thephish.com

If you're seeing no dns records found that means everything works and Evilginx Pro is able successfully communicate with Cloudflare using the API token you provided.

info

Evilginx Pro allows you to add more than one domain per server. Each phishlet can then use a different domain.

TLS Certificates & Phishlet Hostname

Now that we have DNS properly configured the Evilginx phishing server should be reachable from the internet.

We can now proceed to set up the hostname for our phishing campaign, which will be used by the phishlet we added in the previous steps.

Let's set the phishing hostname to mso.thephish.com and enable the phishlet with commands:

phishlets set mrgretzky/ms365ent hostname mso.thephish.com
phishlets enable mrgretzky/ms365ent

Once the phishlet is enabled and the hostname is set, Evilginx Pro will automatically generate and retrieve the TLS wildcard certificate from LetsEncrypt. The domain validation challenge is completed through DNS TXT records, using the DNS provider we configured previously. This is why it is so important to configure the domains DNS provider, before we start configuring the phishlets.

Allow Evilginx up to 60 seconds to retrieve the TLS certificate.

Phishing hostname

Your phishing hostname must always end with the name of one of the managed domains. For example if you want to use domain thephish.com, the hostname for your phishlet can be hello.thephish.com.

Lures

Our phishlet is enabled and ready to phish. The last step is to create a valid lure URL, which will be sent out during the phishing engagement and which Evilginx will recognize.

We need to pick a path for our phishing URL, which fits the phishing egagement pretext. Let's use the path /document/shared/invoice.pdf for our example:

lures create mrgretzky/ms365ent /document/shared/invoice.pdf

To get the full URL of our phishing link, let's list all the created lures first:

lures

And retrieve the URL of the lure we created by specifying its correct ID:

lures get-url <id>

We should get the full URL for our lure: https://mso.thephish.com/document/shared/invoice.pdf

This is the URL we can now use in our phishing engagement. Feel free to test it out yourself to see if everything is working properly.

This concludes the quickstart guide. Refer to other sections of the documentation to learn more details about each subject.