Infrastructure Layer

Installation

Gremlin must be installed on each host you wish to attack. In order for your hosts (and containers within the hosts) to be targetable, the installed gremlin must be registered with the Gremlin Control Plane.

Gremlin can be deployed into bare-metal environments running either Linux or Windows, into container-based infrastructure environments running on Linux, and into virtual infrastructure environments.

General steps deploying to Virtual Machine:

  • Get credentials - Team ID with secret or certificates
  • Install Gremlin packages: gremlin and gremlind
  • Register to the Control Plane

General steps deploying to Kubernetes:

Virtual machine

Before installing look at our caveats page to see if there are additional steps needed for your distribution during installation.

Ubuntu, Debian, etc.

For DEB-based Linux distributions (DEB packages)

bash
1# Add packages needed to install and verify gremlin (already on many systems)
2sudo apt update && sudo apt install -y apt-transport-https dirmngr
3
4# Add the Gremlin repo
5echo "deb https://deb.gremlin.com/ release non-free" | sudo tee /etc/apt/sources.list.d/gremlin.list
6
7# Import the GPG key
8sudo apt-key adv --keyserver keyserver.ubuntu.com --recv-keys 9CDB294B29A5B1E2E00C24C022E8EF3461A50EF6
9
10# Install Gremlin client and daemon
11sudo apt update && sudo apt install -y gremlin gremlind

Amazon Linux, RHEL, CentOS, etc.

For RPM-based Linux distributions (RPM packages)

bash
1# Install dependencies
2sudo yum install -y iproute-tc
3
4# Add the Gremlin repo
5sudo curl https://rpm.gremlin.com/gremlin.repo -o /etc/yum.repos.d/gremlin.repo
6
7# Install Gremlin client and daemon
8sudo yum install -y gremlin gremlind

Docker image

Alternatively, instead of installing Gremlin directly on the host operating system, you can deploy Gremlin from the Docker image on DockerHub.

For gremlind to attack Docker containers, you need to add the gremlin user to the docker group after installing Gremlin and Docker.

bash
1sudo adduser gremlin docker

Kubernetes

Gremlin allows targeting objects within your Kubernetes clusters. After selecting a cluster, you can filter the visible set of objects by selecting a namespace. Select any of your Deployments, ReplicaSets, StatefulSets, DaemonSets, or Pods. When one object is selected, all child objects will also be targeted. For example, when selecting a DaemonSet, all of the pods within will be selected.

Installation

The Gremlin Kubernetes client can be installed in place of—or in addition to—installing the Gremlin client on a host. You can install the Kubernetes client using either kubectl or helm. Both methods are outlined here.

Create a Kubernetes secret from Gremlin certificates

When using signature-based authentication, we recommend storing your certificates as a Kubernetes secret. This section will walk you through this process.

  • Download the Gremlin certificates (your role must either be Team Manager or Team Credential Manager).

  • Unzip certificates.zip.

  • Rename the files in the certificates folder. Team Name.pub_cert.pem becomes gremlin.cert. Team Name.priv_key.pem becomes gremlin.key.

  • Create a gremlin namespace:

    bash
    1kubectl create namespace gremlin
  • Create a kubernetes secret by running the following:

    bash
    1kubectl -n gremlin create secret generic gremlin-team-cert --from-file=/path/to/gremlin.cert --from-file=/path/to/gremlin.key
kubectl
  • Download the Gremlin configuration manifest by running the following:

    bash
    1wget https://k8s.gremlin.com/resources/gremlin-conf.yaml
  • Open the file and update the following:

    • Replace <YOUR TEAM ID GOES HERE> with your Gremlin team ID.
    • Replace <YOUR TEAM SECRET GOES HERE> with your Gremlin team secret (If you are using certificate-based authentication, remove this line.)
    • Replace <YOUR UNIQUE CLUSTER NAME GOES HERE> with a unique name for your cluster. This can be any name you want, and will appear in Gremlin in the Kubernetes client list.
  • Apply the manifest with this command:

    bash
    1kubectl apply -f gremlin-conf.yaml

If you are using certificate-based authentication, download and apply the gremlin client manifest for your Kubernetes cluster by running the following:

bash
1kubectl apply -f https://k8s.gremlin.com/resources/gremlin-client.yaml
2kubectl apply -f https://k8s.gremlin.com/resources/gremlin-chao.yaml

If you are using secret-based authentication, download and apply the gremlin client manifest for your Kubernetes cluster by running the following:

bash
1kubectl apply -f https://k8s.gremlin.com/resources/gremlin-client-secret.yaml
2kubectl apply -f https://k8s.gremlin.com/resources/gremlin-chao-secret.yaml
Helm

To deploy Gremlin using Helm, first add the Gremlin Helm chart repository:

bash
1helm repo remove gremlin
2helm repo add gremlin https://helm.gremlin.com

Next, create a new gremlin namespace. The Helm chart will be deployed to this namespace:

bash
1kubectl create namespace gremlin

Create three environment variables: one for your Gremlin team ID, another fir your Gremlin secret key, and a third for your Kubernetes cluster name. If you are using certificate-based authentication or are managing your secrets in Kubernetes, see the Chart readme for more information.

bash
1GREMLIN_TEAM_ID="my_gremlin_team_id"
2GREMLIN_CLUSTER_ID="my_cluster_name"
3GREMLIN_TEAM_SECRET="my_gremlin_team_secret"

Lastly, deploy the Helm chart:

shell
1helm install gremlin/gremlin \
2 --name gremlin \
3 --namespace gremlin \
4 --set gremlin.secret.managed=true \
5 --set gremlin.secret.type=secret \
6 --set gremlin.hostPID=true \
7 --set gremlin.container.driver=any \
8 --set gremlin.secret.teamID=$GREMLIN_TEAM_ID \
9 --set gremlin.secret.clusterID=$GREMLIN_CLUSTER_ID \
10 --set gremlin.secret.teamSecret=$GREMLIN_TEAM_SECRET

To verify that the installation was successful, or to learn about additional configuration options, see the Kubernetes page.

ECS, Swarm, Mesos

Additional installation tutorials are available in our community site.

Windows

For Microsoft Windows run the following from an elevated command prompt.

PowerShell
1msiexec /quiet /package https://windows.gremlin.com/installer/latest/gremlin_installer.msi

After installation

After installing the agent:

  • authenticate the agent with the Gremlin Control Plane. See Authentication for more information.
  • verify that the agent is active in the Clients list. If the agent is unhealthy, it may not have been installed or configured correctly.

An image showing a healthy agent and an unhealthy agent in the Clients view

For additional configuration options, such as using the Gremlin configuration file and environment variables, see Advanced Configuration.

Other considerations

Customize Gremlin's Linux user and group

By default on Linux, Gremlin installs a gremlin Linux user and group, and sets the suid bit on /usr/bin/gremlin so that all users can run the Gremlin executable. These defaults can be overridden at installation time by supplying environment variables to the installer.

For example, to run Gremlin as root and restrict executable access to root:root, you would run:

shell
1GREMLIN_INSTALL_USER=root GREMLIN_INSTALL_GROUP=root GREMLIN_INSTALL_BIN_MODE=0770 \
2 sudo -E yum install gremlin gremlind

The full list of variables available at install time, and their defaults are as follows:

VariableDefaultDescription
GREMLIN_INSTALL_USERgremlinThe Linux user to own all file installed by Gremlin. This user is created if it does not exist
GREMLIN_INSTALL_GROUPgremlinThe Linux group to own all file installed by Gremlin. This group is created if it does not exist
GREMLIN_INSTALL_BIN_MODE6111The file mode for executable files installed by Gremlin.