GitHub Actions

Run jwtop in your GitHub Actions workflows to catch JWT misconfigurations before they reach production.

cerberauth/jwtop-action

The official action — no setup required, just add it to your workflow.

Raw CLI

Install jwtop directly and run any command in a workflow step.

Using cerberauth/jwtop-action

The cerberauth/jwtop-action action installs jwtop and runs the command you specify.

- uses: cerberauth/jwtop-action@v1
  with:
    args: crack ${{ env.TOKEN }} --url https://api.example.com/protected

Inputs

Input	Description	Required
args	Arguments passed directly to jwtop	Yes

Example: scan on pull request

name: JWT security scan

on:
  pull_request:

jobs:
  jwt-scan:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6

      - name: Scan for JWT vulnerabilities
        uses: cerberauth/jwtop-action@v1
        with:
          args: crack ${{ secrets.TEST_TOKEN }} --url ${{ vars.API_URL }}/protected

Attention

Store tokens and target URLs in encrypted secrets, never in plain workflow files.

---

Using the CLI directly

If you need more control, install jwtop as a step and run commands directly.

Setup step

- name: Install jwtop
  run: go install github.com/cerberauth/jwtop@latest

Or use the Docker image to avoid needing Go:

- name: Scan JWT vulnerabilities
  run: |
    docker run --rm ghcr.io/cerberauth/jwtop \
      crack "$TOKEN" --url "$API_URL"
  env:
    TOKEN: ${{ secrets.TEST_TOKEN }}
    API_URL: ${{ vars.API_URL }}

---

Common use cases

Fail the build when a vulnerability is found

jwtop crack exits 0 if at least one exploit succeeds. Use a negation to fail the build:

- name: Assert no JWT vulnerabilities
  run: |
    if jwtop crack "$TOKEN" --url "$API_URL"; then
      echo "::error::JWT vulnerability detected"
      exit 1
    fi
  env:
    TOKEN: ${{ secrets.TEST_TOKEN }}
    API_URL: ${{ vars.API_URL }}

Generate a test token for integration tests

- name: Generate test JWT
  run: |
    TOKEN=$(jwtop create --alg HS256 \
      --secret "$TEST_SECRET" \
      --sub ci-runner \
      --exp 1h)
    echo "TEST_TOKEN=$TOKEN" >> "$GITHUB_ENV"
  env:
    TEST_SECRET: ${{ secrets.TEST_SECRET }}

- name: Run integration tests
  run: go test ./integration/...
  env:
    TEST_TOKEN: ${{ env.TEST_TOKEN }}

Verify a token fetched from a staging environment

- name: Verify staging token
  run: jwtop verify "$TOKEN" --jwks "$JWKS_URI"
  env:
    TOKEN: ${{ steps.fetch-token.outputs.token }}
    JWKS_URI: https://staging.example.com/.well-known/jwks.json

Run all exploit probes with a public key

- name: Full JWT security scan
  uses: cerberauth/jwtop-action@v1
  with:
    args: >
      crack ${{ secrets.TEST_TOKEN }}
      --url ${{ vars.API_URL }}/protected
      --key public.pem
      --wordlist wordlists/secrets.txt