Clients

Running Gremlin on Windows


Windows Support Matrix

This is the latest Windows platform and attack support matrix.

Type Version CPU Disk IO Memory Process
Killer
Shut
down
Time
Travel
Black
hole
DNS Latency Packet
Loss
Server 2008 + ✔️ ✔️ ✔️ ✔️
Client Vista + ✔️ ✔️ ✔️ ✔️

Installing Windows agent

The following instructions guide you to install the Gremlin agent on your Windows devices. If you wish to launch a fresh Windows Server instance on EC2, and prepare it for Gremlin installation and use, the instructions are later in this page.

Running the installer

  1. Download the gremlin_installer.exe
  2. Run that executable by double-clicking on the downloaded file.

    1. Windows, by default, prevents this from running, and shows a "Windows protected your PC" dialog box.
    2. Proceed with the installation by clicking on "More info". This will display another button at the bottom, "Run anyway". Click that button to continue.
  3. The Gremlin agent installer may start behind other windows. Please minimize them to see the installer window.
  4. When the installer dialog box is displayed click "I agree to the license terms and conditions" then click "Install".
  5. A dialog box asking to escalate privileges may be displayed. Click "Yes".
  6. A dialog box prompting to install the Visual C Runtime should be displayed. Click "I agree to the license terms and conditions" then click "Install".
  7. When the first installer finishes click "Close".
  8. When the second agent installer is displayed click "Next", "Next", "Install", "Finish".
  9. Click "Close" on the bundler installer.
  10. At this point, the Windows agent is installed, but not yet configured nor running. Continue to the next section.

Configuring the Gremlin service

There are two ways to configure Gremlin:

  • Option 1: Use global environment variables to pass a certificate key-pair and any other optional configuration
  • Option 2: Use gremlin.exe init from a command line to pass a secret token and any other optional configuration from environment variables, or directly from terminal input.

Option 1: Use global environment variables to pass a certificate key-pair

First, copy over the certificate key-pair:

  1. Navigate to the Gremlin website

  2. Download the Certificate Pair for your team
  3. Place the certificate and private key in the following directory:

    • C:\ProgramData\Gremlin\Agent
  4. Rename the certificate so it has the following name:

    • cert.pem
  5. Rename the private key so it has the following name:

    • key.pem
    • Next, set the necessary environment
  6. Open the control panel, and navigate to Control Panel\System and Security\System
  7. Under Computer name, domain, and workgroup settings, click "Change settings"
  8. The System Properties dialog box should be displayed. Navigate to the "Advanced" tab.
  9. Click the "Environment Variables" button, close to the bottom of the dialog box.
  10. Under the System variables list click the "New" button.

    • For Variable name copy-then-paste the following:

      • GREMLIN_IDENTIFIER
    • For Variable value enter

      • {value of your choosing}. The value can be anything you want. It's displayed in the Gremlin web app. A meaningful value is very helpful when targeting attacks.
    • Click the "OK" button
  11. Under the System variables list click the "New" button.

    • For Variable name copy-then-paste the following:

      • GREMLIN_TEAM_ID
    • For Variable value enter

      • {your team GUID}. The value is the GUID assigned to your team by the Gremlin user interface.
    • Click the "OK" button
  12. Under the System variables list click the "New" button.

    • For Variable name copy-then-paste the following:

      • GREMLIN_TEAM_CERTIFICATE_OR_FILE
    • For Variable value enter

      • file://C:/ProgramData/Gremlin/Agent/cert.pem
    • Click the "OK" button
  13. Under the System variables list click the "New" button.

    • For Variable name copy-then-paste the following:

      • GREMLIN_TEAM_PRIVATE_KEY_OR_FILE
    • For Variable value enter

      • file://C:/ProgramData/Gremlin/Agent/key.pem
    • Click the "OK" button
  14. Click "OK" on the Environment Variables dialog box.
  15. Click "OK" on the System Properties dialog box.
  16. Close Control Panel.

Option 2: Use gremlin.exe init to pass a secret token

Open a command prompt and run gremlin.exe init. You will be prompted to enter the following values

  • Please input your Team ID:
  • Please input your Team Secret:

Alternatively, you can set up your shell to include these as environment variables to bypass the prompts.

Starting, Stopping and Restarting the Gremlin service

The last step is to start the Gremlin Service.

  1. Press Ctrl then Esc to display the Start Menu
  2. Start typing services
  3. When Services is selected press Enter or click it
  4. Navigate to the Gremlin Daemon entry.
  5. Right click on it, and click "Start"

    • It can take up to 40 seconds for the service to start. The progress dialog box automatically closes when the Gremlin Daemon is ready.

The host is ready to be attacked!

Creating a Windows Server

These instructions are for creating a Windows Server on AWS.

Login to the AWS console then navigate to All services / Compute / EC2. Click "Launch Instance" (bright orange button on the left about half way down) then click "Launch instance" to open the Launch instance wizard.

  • Choose an Amazon Machine Image (AMI): Find Microsoft Windows Server 2019 Base. Click the "Select" button.
  • Choose Instance Type: Select t2.medium as 2 cores help with testing. While t2.micro works it is slow. Select an instance type then click "Next: Configure Instance Details."
  • Configure Instance Details: Keep the defaults. Click "Next: Add Storage."
  • Add Storage: The defaults (Root 30 GB) work well. Click "Next: Add Tags."
  • Add Tags: Adding Name and Purpose tags helps identify the host in your list of instances. Please add both (click Add Tag to start the process). Click "Next: Configure Security Group."
  • Configure Security Group: Create a new group here. Have at least want to allow RDP (3389) incoming from your IP address (under "Source" select My IP). This is the port to open a Remote Desktop Session. Click "Review and Launch."
  • Review and Launch: When you click the "Launch" button, you'll be prompted to select an SSH key to use for the instance. Create a new one to use for just Windows servers, that's because you'll need to copy the private key contents to your clipboard later (explained in detail in Connecting to the Windows Server). To do this, select Create a new key pair in the first drop down, give it a name, then click "Download Key Pair" to save the key-pair. Finally, click "Launch Instances."

Connecting to the Windows Server

The list of EC2 instances should be displayed. Included in the list should be the new instance with the "Name" added in Step 5 above.

  • Get the Public DNS Name: Select your instance in the EC2 Console. In the bottom pane, on the right side, at the top of the list is Public DNS (IPv4). That domain name is needed to connect to your instance. Hovering the mouse over the URL reveals a Copy to clipboard button. The address should look something like ec2-18-144-40-35.us-west-1.compute.amazonaws.com.
  • Option 1 - Connecting using Remote Desktop app:

    • Add PC in Remote Desktop
    • Open your Remote Desktop client and click "Add PC".
    • For the PC Name field, add the Public DNS name from the step above, and accept the rest of the defaults.
    • Cick "Save"
    • Getting the password for your server
    • Copy the entire contents of your SSH private key (including the -----BEGIN RSA PRIVATE KEY----- boundary lines). If you created a new key when launching the instance, this will be the file you downloaded.
    • Then, while selecting EC2 instance from the EC2 console, click the "Connect" button at the top of the AWS console page.
    • Click the "Get Password" button which will then prompt you to paste your private key.
    • Click "Decrypt Password", which will produce a password for you to copy.
    • Authenticating to the Server
    • Back on your Remote Desktop Client, double-click the newly created server in your Remote Desktop client.
    • You'll be prompted for credentials, use 'Administrator' for the username and the copied password for your password.

      Note

      Unfortunately, Amazon does not protect these sessions with a trusted certificate. This means at this point you'll likely see a dialog that says "The certificate couldn't be verified back to a root certificate". You have no choice but to accept this.

  • Option 2 - Connecting using Windows Remote Desktop Connection: This section applies if you are connecting to your server instance from a Windows computer.

    • Start by copying the Public DNS (IPv4). Click the "Copy to clipboard" button next to the Public DNS (IPv4).
    • Next, open the Start menu, and type remote desktop connection. When Remote Desktop Connection is displayed in the menu click it or press Enter.
    • Paste the Public DNS (IPv4) into the Computer edit box then click the "Show Options" button in the lower left corner. For User name enter Administrator click "Connect". After a short delay a prompt for the password is displayed.
    • Return to the AWS console, ensure your new instance is selected, then click the "Actions" button towards the top left then click "Get Windows Password".
    • A dialog box labeled Retrieve Default Windows Administrator Password should be displayed. Towards the middle of the dialog box is a button labeled "Browse"; click it.
    • Select the key-pair you saved in Step 7 of 'Creating a Windows Server' then click "Open". The Key Name is displayed in the dialog box. The edit box should be filled with random looking text that starts with the -----BEGIN RSA PRIVATE KEY-----. Click "Decrypt Password".
    • The password is displayed near the bottom of the dialog box. Hover the mouse over the password reveals a "Copy to clipboard" button; click it
    • Click "Close".
    • Navigate back to the Remote Desktop Connection / Windows Security dialog box. Paste the administrator password into the password edit box, optionally click "Remember me", then click "OK".
    • The server uses a "self signed" digital certificate for identification. In the displayed dialog box click "Don't ask me again for connections to this computer" then click "Yes". You should be immediately connected to the server computer. The computer will go through about 30 seconds of initialization.

Installing Firefox

Windows Server comes with a locked-down version of Internet Explorer. It is difficult-to-impossible to use. Arguably, Firefox is a better choice. This is a good time to install Firefox. Unfortunately, Internet Explorer has to be used initially. Be prepared for an endless stream of "are you sure" prompts.

  • Start Internet Explorer. When the first "are you sure" prompt is displayed click "OK".
  • Navigate to the Firefox download page. In the Internet Explorer prompt, click "In the future, do not show this warning" then click "OK". Internet Explorer displays dialog boxes for every website you try to directly or indirectly access.
  • Click "Add" then click "Add" then click "Close" whenever that dialog box is displayed.

    • You may have to refresh / retry multiple times to get to where you want to go.
  • Once on the Firefox Download page just following the instructions to install Firefox. After Firefox is installed close Internet Explorer. Your host is now ready to install the Windows Agent!