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.

1Authorization: Bearer ZTczNTJhNmItYTlhMC01MTNjLTgxZTQtOTgwZjY4MGE3MGMzOmdyZW1saW5AZ3JlbWxpbmluYy5jb206NWNhMWFiMWUtZGVhZC1iZWVmLWZmZmYtMDAwMGZmZmYwMDAw

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

bash

1curl -X POST --header 'Content-Type: application/x-www-form-urlencoded' \
2    --data-urlencode 'email=gremlin@gremlin.com' \
3    --data-urlencode 'password=changeit' \
4    '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

1curl -X POST --header 'Content-Type: application/x-www-form-urlencoded' \
2    --data-urlencode 'email=gremlin@gremlin.com' \
3    --data-urlencode 'password=changeit' \
4    --data-urlencode 'token=000000' \
5    '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

1{
2  "company_id": "07814fbb-a9a0-81e4-b375-980f680a70c4",
3  "company_name": "My Company",
4  "roles": ["COMPANY_USER"],
5  "privileges": ["COMPANY_DEFAULT"],
6  "expires_at": "2099-01-00T00:00:00.000Z",
7  "header": "Bearer ZTczNTJhNmItYTlhMC01MTNjLTgxZTQtOTgwZjY4MGE3MGM0OmdyZW1saW5AZ3JlbWxpbmluYy5jb206NWNhMWFiMWUtZGVhZC1iZWVmLWZmZmYtMDAwMGZmZmYwMDAy",
8  "identifier": "gremlin@gremlin.com",
9  "teams": [
10    {
11      "identifier": "e7352a6b-a9a0-513c-81e4-980f680a70c4",
12      "name": "My Team",
13      "company_id": "07814fbb-a9a0-81e4-b375-980f680a70c4",
14      "roles": ["TEAM_USER"],
15      "privileges": ["READ_TEAM_USERS", "TEAM_DEFAULT"]
16    }
17  ],
18  "last_login": "2098-01-00T00:00:00.000Z",
19  "renew_token": "5ca1ab1e-dead-beef-ffff-0000ffff0003",
20  "token": "5ca1ab1e-dead-beef-ffff-0000ffff0002"
21}

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

1export 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

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

no args necessary

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

bash

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

multiple arg values

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

bash

1# Add latency to all DNS requests to DNS servers
2curl -X POST \
3    --header "Content-Type: application/json" \
4    --header "Authorization: $bearertoken" \
5    https://api.gremlin.com/v1/attacks/new?teamId=e7352a6b-a9a0-513c-81e4-980f680a70c4 \
6    --data '
7    {
8        "command": { "type": "latency", "args": [ "-i", "8.8.8.8", "-i", "8.8.4.4" ] },
9        "target": { "type": "Random" }
10    }'

target

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

randomly target an active host

bash

1# Pick a host at random from all active hosts
2curl -X POST \
3    --header "Content-Type: application/json" \
4    --header "Authorization: $bearertoken" \
5    https://api.gremlin.com/v1/attacks/new?teamId=e7352a6b-a9a0-513c-81e4-980f680a70c4 \
6    --data '
7    {
8        "command": { "type": "blackhole", "args": [ "-i", "10.0.0.0/24" ] },
9        "target": { "type": "Random" }
10    }'
11
12# Pick a host at random from all active hosts with the tage service=api
13curl -X POST \
14    --header "Content-Type: application/json" \
15    --header "Authorization: $bearertoken" \
16    https://api.gremlin.com/v1/attacks/new?teamId=e7352a6b-a9a0-513c-81e4-980f680a70c4 \
17    --data '
18    {
19        "command": { "type": "blackhole", "args": [ "-i", "10.0.0.0/24" ] },
20        "target": { "type": "Random", "tags": { "service": "api" } }
21    }'

target an exact set of hosts

bash

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

targeting a container

bash

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

target a set of docker containers

bash

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