docker.mdx

import { Steps, Aside, Tabs, TabItem } from '@/components/docs';

jwtop is published on Docker Hub and GHCR. The entrypoint is the jwtop binary itself, so any CLI command works after the image name.

Quick start

docker run --rm ghcr.io/cerberauth/jwtop decode $TOKEN

docker run --rm cerberauth/jwtop decode $TOKEN

Mounting keys and wordlists

Commands that read a PEM key or a wordlist file (verify --key, create --key, crack --wordlist, ...) need that file inside the container. Mount the containing directory as a volume and reference the in-container path:

docker run --rm -v "$(pwd)":/data ghcr.io/cerberauth/jwtop \
  verify $TOKEN --key /data/public.pem

docker run --rm -v "$(pwd)":/data ghcr.io/cerberauth/jwtop \
  crack $TOKEN --wordlist /data/secrets.txt

Probing a live server

docker run --rm ghcr.io/cerberauth/jwtop \
  crack $TOKEN --url https://api.example.com/protected

When probing a server running in another container, join its network:

docker run --rm --network container:api ghcr.io/cerberauth/jwtop \
  crack $TOKEN --url http://localhost:8080/protected

Docker Compose

Run jwtop as a one-off step alongside a service under test:

services:
  api:
    build: .
    ports:
      - '8080:8080'

  jwtop:
    image: ghcr.io/cerberauth/jwtop
    depends_on:
      - api
    volumes:
      - ./keys:/data
    command: ['crack', '${TOKEN}', '--url', 'http://api:8080/protected', '--key', '/data/public.pem']

docker compose run --rm jwtop

Build from source

1. Clone the repository:

   git clone https://github.com/cerberauth/jwtop.git
   cd jwtop
   

2. Build the image using the dev Dockerfile:

   docker build -f .docker/Dockerfile-build -t jwtop .
   

3. Run it:

   docker run --rm jwtop decode $TOKEN
   

GitHub Actions

To run jwtop in CI without pulling the image manually, see the GitHub Actions guide — cerberauth/jwtop-action handles installation for you. To use the container image directly in a workflow step instead:

- name: Scan for JWT vulnerabilities
  run: docker run --rm ghcr.io/cerberauth/jwtop crack "${{ secrets.TEST_TOKEN }}" --url https://staging.example.com/protected