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.)

All Gremlin clients authenticate to the Gremlin Control Plane using a public-key certificate and private key. We call this signature-based authentication. This page shows how to download and create these credentials, and answers some FAQs about them.

To read about User authentication via the Gremlin Web App, see User Management and Authentication..

Secret-based Authentication

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 must update any running clients by running gremlin init on each client to have the new secret entered on each.

Finally, run gremlin init, passing in any tags you want to associate with this client:

$ gremlin 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

First, configure your Team ID:

$ echo 'GREMLIN_TEAM_ID="<YOUR_TEAM_ID>"' >> /etc/default/gremlind

Then, add your certificate and private key to two separate files in the gremlin user's home directory (e.g., /var/lib/gremlin/gremlin.pub_cert.pem and /var/lib/gremlin/gremlin.priv_key.pem), and configure the client with them either via configuration file:

$ echo 'GREMLIN_TEAM_CERTIFICATE_OR_FILE="file:///var/lib/gremlin/gremlin.pub_cert.pem"' >> /etc/default/gremlind
$ echo 'GREMLIN_TEAM_PRIVATE_KEY_OR_FILE="file:///var/lib/gremlin/gremlin.priv_key.pem"' >> /etc/default/gremlind

Then set the ownership and restrict the permissions on both files:

sudo chown gremlin:gremlin /var/lib/gremlin/gremlin.p*
sudo chmod 600 /var/lib/gremlin/gremlin.p*

Finally, reload the Gremlin daemon:

sudo systemctl reload gremlind

Downloading the Certificate

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.

Creating a New Certificate

You must be a superuser 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.

FAQ

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.