Gremlin Docs
Dashboard
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 container-based infrastructure environments, virtual infrastructure environments, and bare-metal environments. The only requirement is that the environment runs on Linux.

General steps deploying to Virtual Machine:

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

General steps deploying to Kubernetes:

  1. Get Credentials - Team ID with secret or certificates
  2. Create Kubernetes secret
  3. Deploy Helm Chart

Virtual Machine

Ubuntu, Debian, etc.

For DEB-based Linux distributions (DEB packages)

# Add the Gremlin repo
echo "deb https://deb.gremlin.com/ release non-free" | sudo tee /etc/apt/sources.list.d/gremlin.list

# Import the GPG key
sudo apt-key adv --keyserver keyserver.ubuntu.com --recv-keys 9CDB294B29A5B1E2E00C24C022E8EF3461A50EF6

# Install Gremlin client and daemon
sudo apt-get update && sudo apt-get install -y gremlin gremlind

Note that you may also need to install the apt-transport-https package to be able to install Gremlin from our repo via HTTPS.

Amazon Linux, RHEL, CentOS, etc.

For RPM-based Linux distributions (RPM packages)

# Add the Gremlin repo
sudo curl https://rpm.gremlin.com/gremlin.repo -o /etc/yum.repos.d/gremlin.repo

# Install Gremlin client and daemon
sudo 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.

sudo adduser gremlin docker

Kubernetes

Gremlin has been tested to work on Kubernetes versions 1.6 and up.

Create a Kubernetes secret

If you do not already have your certificates locally, you can download them by going the teams page and selecting the team for which you'd like to install the client. From there you can select 'Download' to download the current certificate, or 'Create New' if you have not yet created your client certificates.

After downloading your certificate files, they will have a name like YOUR_TEAM_NAME-client.priv_key.pem and YOUR_TEAM_NAME-client.pub_cert.pem. Rename these files to gremlin.key and gremlin.cert respectively.

Once you have renamed the certificate files, create a Kubernetes secret:

kubectl create secret generic gremlin-team-cert --from-file=./gremlin.cert --from-file=./gremlin.key

Installation with Helm

The simplest way to install the Gremlin client on your Kubernetes cluster is to use Helm. If you do not already have Helm installed, go here to get started. Once Helm is installed and configured, add the gremlin repo and install the client:

helm repo add gremlin https://helm.gremlin.com
helm install --set gremlin.teamID=YOUR-TEAM-ID gremlin/gremlin

For more information on the Gremlin Helm chart, including additional configuration options, see the chart on Github.

Installation with kubectl

Here is a sample DaemonSet configuration template for installing Gremlin into your nodes.

apiVersion: extensions/v1beta1
kind: DaemonSet
metadata:
  name: gremlin
  namespace: <namespace where you want to run an attack>
  labels:
    k8s-app: gremlin
    version: v1
spec:
  template:
    metadata:
      labels:
        k8s-app: gremlin
        version: v1
    spec:
      # If you want to enable host-level process-killing, add this flag:
      #hostPID: true
      # If you want to enable host-level network attacks, add this flag:
      #hostNetwork: true
      containers:
      - name: gremlin
        image: gremlin/gremlin
        args: [ "daemon" ]
        imagePullPolicy: Always
        securityContext:
          capabilities:
            add:
              - NET_ADMIN
              - SYS_BOOT
              - SYS_TIME
              - KILL
        env:
          - name: GREMLIN_TEAM_ID
            value: <YOUR TEAM ID GOES HERE>
          - name: GREMLIN_TEAM_PRIVATE_KEY_OR_FILE
            value: file:///var/lib/gremlin/cert/gremlin.key
          - name: GREMLIN_TEAM_CERTIFICATE_OR_FILE
            value: file:///var/lib/gremlin/cert/gremlin.cert
          - name: GREMLIN_IDENTIFIER
            valueFrom:
              fieldRef:
                fieldPath: spec.nodeName
        volumeMounts:
          - name: docker-sock
            mountPath: /var/run/docker.sock
          - name: gremlin-state
            mountPath: /var/lib/gremlin
          - name: gremlin-logs
            mountPath: /var/log/gremlin
          - name: shutdown-trigger
            mountPath: /sysrq
          - name: gremlin-cert
            mountPath: /var/lib/gremlin/cert
            readOnly: true
      volumes:
        # Gremlin uses the Docker socket to discover eligible containers to attack,
        # and to launch Gremlin sidecar containers
        - name: docker-sock
          hostPath:
            path: /var/run/docker.sock
        # The Gremlin daemon communicates with Gremlin sidecars via its state directory.
        # This should be shared with the Kubernetes host
        - name: gremlin-state
          hostPath:
            path: /var/lib/gremlin
        # The Gremlin daemon forwards logs from the Gremlin sidecars to the Gremlin control plane
        # These logs should be shared with the host
        - name: gremlin-logs
          hostPath:
            path: /var/log/gremlin
        # If you want to run shutdown attacks on the host, the Gremlin Daemon requires a /proc/sysrq-trigger:/sysrq mount
        - name: shutdown-trigger
          hostPath:
            path: /proc/sysrq-trigger
        - name: gremlin-cert
          secret:
            secretName: gremlin-team-cert

ECS, Swarm, Mesos

Additional installation tutorials are available in our community site.

After Installation

You can see your installed clients on the clients page

Follow the advanced configuration for additional configuration options.

PreviousNext