API Reference > Examples

Examples

No items found.

Everything within Gremlin can be done via our API. Explore the Gremlin API with our Interactive API playground.

Authentication and access tokens

All API requests require an API access token provided in the Authorization Header.

Authorization: Bearer ZTczNTJhNmItYTlhMC01MTNjLTgxZTQtOTgwZjY4MGE3MGMzOmdyZW1saW5AZ3JlbWxpbmluYy5jb206NWNhMWFiMWUtZGVhZC1iZWVmLWZmZmYtMDAwMGZmZmYwMDAw

‍

You can access your tokens by providing your gremlin username and password to /users/auth

BASH


curl -X POST --header 'Content-Type: application/x-www-form-urlencoded' \
    --data-urlencode 'email=gremlin@gremlin.com' \
    --data-urlencode 'password=changeit' \
    'https://api.gremlin.com/v1/users/auth?getCompanySession=true'

‍

If you have MFA enabled, include the token from your password authenticator in your call to /users/auth/mfa/auth

BASH


curl -X POST --header 'Content-Type: application/x-www-form-urlencoded' \
    --data-urlencode 'email=gremlin@gremlin.com' \
    --data-urlencode 'password=changeit' \
    --data-urlencode 'token=000000' \
    'https://api.gremlin.com/v1/users/auth/mfa/auth?getCompanySession=true'

‍

If you are a member of more than one company, you can supply the company name with 'companyName=Your Company Name'.

These calls will result in a JSON response containing information about your session and more

JSON


{
  "company_id": "07814fbb-a9a0-81e4-b375-980f680a70c4",
  "company_name": "My Company",
  "roles": ["COMPANY_USER"],
  "privileges": ["COMPANY_DEFAULT"],
  "expires_at": "2099-01-00T00:00:00.000Z",
  "header": "Bearer ZTczNTJhNmItYTlhMC01MTNjLTgxZTQtOTgwZjY4MGE3MGM0OmdyZW1saW5AZ3JlbWxpbmluYy5jb206NWNhMWFiMWUtZGVhZC1iZWVmLWZmZmYtMDAwMGZmZmYwMDAy",
  "identifier": "gremlin@gremlin.com",
  "teams": [
    {
      "identifier": "e7352a6b-a9a0-513c-81e4-980f680a70c4",
      "name": "My Team",
      "company_id": "07814fbb-a9a0-81e4-b375-980f680a70c4",
      "roles": ["TEAM_USER"],
      "privileges": ["READ_TEAM_USERS", "TEAM_DEFAULT"]
    }
  ],
  "last_login": "2098-01-00T00:00:00.000Z",
  "renew_token": "5ca1ab1e-dead-beef-ffff-0000ffff0003",
  "token": "5ca1ab1e-dead-beef-ffff-0000ffff0002"
}

‍

Note the Bearer token from the value of "header".

export bearertoken="Bearer ZTczNTJhNmItYTlhMC01MTNjLTgxZTQtOTgwZjY4MGE3MGM0OmdyZW1saW5AZ3JlbWxpbmluYy5jb206NWNhMWFiMWUtZGVhZC1iZWVmLWZmZmYtMDAwMGZmZmYwMDAy"

‍

Creating Attacks

Note

All options from the CLI are available through the /attacks/new API, by passing them via command.args.

‍

command

The command attribute is used to tell Gremlin which attack should be run, and how it should be run.

subattributes

type: one of the Gremlin types

args: the arguments for the gremlin, identical to those passed via the CLi and UI.

short and long flags

Both the short and long form of arg flags are acceptable:

BASH


# Add 1 core of CPU load to a random host for 30 seconds
curl -X POST \
    --header "Content-Type: application/json" \
    --header "Authorization: $bearertoken" \
    https://api.gremlin.com/v1/attacks/new?teamId=e7352a6b-a9a0-513c-81e4-980f680a70c4 \
    --data '
    {
        "command": { "type": "cpu", "args": ["-c", "1", "--length", "30"] },
        "target": { "type": "Random" }
    }'

‍

no args necessary

Some attacks have no required args so args can be omitted.

BASH


# shutdown a random host
curl -X POST \
    --header "Content-Type: application/json" \
    --header "Authorization: $bearertoken" \
    https://api.gremlin.com/v1/attacks/new?teamId=e7352a6b-a9a0-513c-81e4-980f680a70c4 \
    --data '
    {
        "command": { "type": "shutdown" },
        "target": { "type": "Random" }
    }'

‍

multiple arg values

Some arguments can take multiple values, they can be specified like this:

BASH


# Pick a host at random from all active hosts
curl -X POST \
    --header "Content-Type: application/json" \
    --header "Authorization: $bearertoken" \
    https://api.gremlin.com/v1/attacks/new?teamId=e7352a6b-a9a0-513c-81e4-980f680a70c4 \
    --data '
    {
        "command": { "type": "blackhole", "args": [ "-i", "10.0.0.0/24" ] },
        "target": { "type": "Random" }
    }'

# Pick a host at random from all active hosts with the tage service=api
curl -X POST \
    --header "Content-Type: application/json" \
    --header "Authorization: $bearertoken" \
    https://api.gremlin.com/v1/attacks/new?teamId=e7352a6b-a9a0-513c-81e4-980f680a70c4 \
    --data '
    {
        "command": { "type": "blackhole", "args": [ "-i", "10.0.0.0/24" ] },
        "target": { "type": "Random", "tags": { "service": "api" } }
    }'

‍

target an exact set of hosts

BASH


# Target identifier1 and identifier2
curl -x POST \
    --header "Content-Type: application/json" \
    --header "Authorization: $bearertoken" \
    https://api.gremlin.com/v1/attacks/new?teamId=e7352a6b-a9a0-513c-81e4-980f680a70c4 \
    --data '
    {
        "command": { "type": "blackhole", "args": [ "-i", "10.0.0.0/24" ] },
        "target": { "type": "Exact", "hosts" : { "ids": ["identifier1","identifier2"] } }
    }'

‍

targeting a container

BASH


curl -X POST \
    --header "Content-Type: application/json" \
    --header "Authorization: $bearertoken" \
    https://api.gremlin.com/v1/attacks/new?teamId=e7352a6b-a9a0-513c-81e4-980f680a70c4 \
    --data '
    {
        "command": { "type": "blackhole", "args": [ "-i", "10.0.0.0/24" ] },
        "target": { "type": "Exact", "containers":{"ids":["2d9ddc7a4284cd23d2d2bc21e11af021a84ee5c7536073c5a5d6888adf1f290c"]}}
    }'

‍

target a set of docker containers

BASH


# Target 2 docker containers that have the label "service=api"
curl -X POST \
    --header "Content-Type: application/json" \
    --header "Authorization: $bearertoken" \
    https://api.gremlin.com/v1/attacks/new?teamId=e7352a6b-a9a0-513c-81e4-980f680a70c4 \
    --data '
    {
        "command": { "type": "blackhole", "args": [ "-i", "10.0.0.0/24" ] },
        "target":{ "type": "Random", "exact": 2, "containers": {"labels": {"service":"api"} } }
    }'

API Keys