Gremlin Docs
Dashboard
API Reference

Examples

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

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

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

{
  "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:

# 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, and so args can be omitted.

# 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:

# Add latency to all DNS requests to DNS servers
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": "latency", "args": [ "-i", "8.8.8.8", "-i", "8.8.4.4" ] },
        "target": { "type": "Random" }
    }'

target

The target attribute is used to tell Gremlin what clients should be targeted by the attack.

randomly target an active host
# 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
# 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
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
# 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"} } }
    }'
Previous