Authentication

The Gremlin daemon (gremlind) connects to the Gremlin Control Plane and waits for attack orders from you. When it receives attack orders, it uses the Gremlin client (gremlin) to run the attack.

To connect the Gremlin daemon to the Control Plane, you need your client credentials, provided either via secret-based authentication using TEAM ID and SECRET, or via signature-based authentication using PEM certificates. These credentials are NOT the same as the email/password credentials you use to access the Gremlin Web App. To read about User authentication via the Gremlin Web App, see User Management and Authentication..

Client Authentication Methods

There are two methods for authenticating clients with Gremlin

• secret authentication involves a secret string value that Gremlin clients use to prove their identity. Secrets are created from the Gremlin UI, and are like passwords. They can never be retrieved from Gremlin after creation (only reset)
• signature authentication requires supplying a public and private RSA certificate-key pair to Gremlin clients. This certificate pair is created from the Gremlin UI, and can be redownloaded at any time, but they expire 1 year from the date of creation

Both authentication methods can be configured via configuration file or environment variables. Learn more about how to configure Gremlin from the configuration page.

Secret-based Authentication

Create a Secret

To use secret-based authentication as a new user, sign in to the Gremlin Web App. Go to Team Settings, and click your Team. From the team settings page, on the secret line, click Create to create a new secret.

NOTE: If a secret already exists, you must revoke the existing secret; this will cause a new one to be generated. If you revoke an existing secret and create a new one, you will need to reconfigure any existing clients.

Configure Clients with Secret

To configure Gremlin clients for secret authentication, follow one of the configuration methods:

• set team_id and team_secret in your config.yaml

1team_id: 11111111-1111-1111-1111-111111111111
2team_secret: 11111111-1111-1111-1111-111111111111

• or pass environment variables GREMLIN_TEAM_ID and GREMLIN_TEAM_SECRET directly to the gremlind process.

1# export these to the gremlind process or save them to /etc/default/gremlind (used by Systemd and SysV)
2GREMLIN_TEAM_ID=11111111-1111-1111-1111-111111111111
3GREMLIN_TEAM_SECRET=11111111-1111-1111-1111-111111111111

gremlin init

Additionally, secret authentication can also be set up via gremlin init

1gremlin init --tag service=my-api --tag service-version=1.0.0 --tag service-type=http

If secret-based auth is successful, the client will create a hidden file, .credentials in the gremlin user's home directory. This file contains an authentication token that gremlind uses to connect to the Gremlin Control Plane.

Signature-based Authentication

Download a Certificate Pair

To download your certificate, navigate to Company Settings on the Web UI.

Then click the Team whose client credentials you want to download. (Each team has its own client credentials.)

Each Team page has everything your Gremlin clients need to authenticate to the Control Plane: the Team ID and Certificate.

Click Download to get your Team Certificate.

The downloaded zip file contains both a public-key certificate and a matching private key. Unzip the file, and register Gremlin clients to the Control Plane with the included certificate, private key, and your Team ID.

Configure Clients with Certificate Pair

To configure Gremlin clients for signature authentication, follow one of the configuration methods:

• set team_id, team_certificate, and team_private_key in your config.yaml

1#/etc/gremlin/config.yaml
2team_id: 11111111-1111-1111-1111-111111111111
3team_certificate: file:///var/lib/gremlin/cert.pem
4team_private_key: file:///var/lib/gremlin/key.pem

• or pass environment variables GREMLIN_TEAM_ID, GREMLIN_TEAM_CERTIFICATE_OR_FILE, and GREMLIN_TEAM_PRIVATE_KEY_OR_FILE directly to the gremlind process

1# export these to the gremlind process or save them to /etc/default/gremlind (used by Systemd and SysV)
2GREMLIN_TEAM_ID=11111111-1111-1111-1111-111111111111
3GREMLIN_TEAM_CERTIFICATE_OR_FILE=file:///var/lib/gremlin/cert.pem
4GREMLIN_TEAM_PRIVATE_KEY_OR_FILE=file:///var/lib/gremlin/key.pem

Rotating Expiring Certificates

You must be a Team or Company Manager of your Gremlin account to manage certificates.

All certificates expire one year after creation. Before the expiration date, you must create a new certificate, reconfigure all clients with it, and delete the old certificate. As the expiration date draws near, the Gremlin Web App will display a warning about it.

To create a new certificate, simply click the Create New button next to your existing certificate (see the previous screenshot). Now that you have two certificates, you cannot download the older certificate (though all clients still configured with it may still use it to authenticate), and you cannot create a third certificate.

If you did not mean to create the newer certificate yet, just destroy it. Otherwise, move all clients to the newer certificate, then destroy the old one.

Verifying Agent Authentication

To verify that your agents are connected to the Gremlin Control Plane, first make sure that the Gremlin daemon is running.

For hosts running System V (RHEL 6, CentOS 6, Amazon Linux 1, etc.), use the service command:

1sudo service gremlind status

For hosts running systemd (RHEL 7+, CentOS 7+, Amazon Linux 2, Ubuntu/Debian, etc.), use the systemctl command:

1sudo systemctl status gremlind

Next, use gremlin check auth to check the agent's authentication status:

1gremlin check auth

If the agent authenticated successfully, the output will be similar to the following:

1auth
2====================================================
3Auth Input Type                      : Certificate                        
4API Response                         : OK

If not, the output will explain why the agent was unable to authenticate:

1auth
2====================================================
3Auth Input Type                      : No valid auth found
4========= Identification ============:
5Team ID Source                       : Team ID not found
6Gremlin Identifier                   : [Host identifier]
7Gremlin Identifier Source            : Not supplied explicitly, using the default
8========= Secret/Token Info =========:
9Team Secret Source                   : Team Secret not found
10.credentials valid                   : /var/lib/gremlin/.credentials file not found
11========= Certificate Info ==========:
12Team Certificate Source              : Team Certificate not found
13========= Private Key Info ==========:
14Team Private Key Source              : Team Private Key not found

If you're having trouble authenticating, see the FAQ for possible causes and solutions.

Releasing Client Certificates

There are three different methods you can use to release client certificates:

• Gremlin Logout command - From the host, you can log out of the client using the command "gremlin logout". This method allows you to remove the authorization from our server but keep the binaries in place for future use. Once logged out, the license should be released within a few minutes for consumption by other clients.
• WebUI deactivation option - From the WebUI, you can deactivate the client to release the license. This will prevent the host from being used in future attacks until it is reactivated.
• Uninstalling Gremlin client from the host - This method is similar to option 1. By removing the binaries, the host will no longer communicate with our service and the license will be released for future consumption.

Once any of these options have been performed, it may take a few minutes for new clients to use the newly released entitlements. You can view the details of which teams have active clients for a given month by navigating to Gremlin Reports within the WebUI. The Active Clients metric on this page is cumulative for any active clients that may have authenticated.

FAQ

Why are my agents not showing up in the Gremlin web app?

Log into the host where the agent is installed and run gremlin auth check to see the possible causes. If you're using secret-based authentication, use gremlin init to re-enter your team ID and secret key. If you're using signature-based authentication, make sure that the Gremlin agent can read your certificates and that the file paths are correct. Then, restart the Gremlin agent using sudo service gremlind restart or sudo systemctl restart gremlind.

Can I create one certificate for my whole Company?

No. Every Team within the Company must use its own certificate.

Can I create one certificate per Gremlin client?

No. Every Gremlin client within a Team uses the same shared certificate. When that certificate is about to expire, you must create a new certificate. For a brief time, you may have some clients configured with the older certificate and some with the newer one. But before the older certificate expires, you must move all clients to the newer certificate.

Is it OK for some clients to use secret-based auth while others use signature-based auth?

Yes, but if you are still using secret-based auth, you should move all clients to signature-based auth as soon as possible.

What does signature-based authentication have to do with SSL?

Nothing. Signature-based auth is independent of the SSL layer, but both are important. The purpose of SSL is to 1) encrypt the client-to-server connection, and 2) let the client authenticate the server (i.e. the Gremlin Control Plane). Signature-based auth lets the Gremlin Control Plane authenticate the client.

Before the client connects to the backend, it signs the payload using $GREMLIN_TEAM_PRIVATE_KEY_OR_FILE. Then it initiates an SSL handshake with the backend, verifying the backend's SSL certificate in the process. After the SSL tunnel has been established the backend verifies that the payload was signed by a Gremlin-issued key.

What cryptographic standard does signature-based authentication use?

It uses 256-bit ECDSA (prime256v1) for keys, with SHA 256-bit ECDSA for signatures. The recommended lifespan for anything secured by these standards is two years, but we are intentionally being more conservative, opting instead for one-year expiration.