JWT Tool for JSON Web Token Security Testing

May 18, 2019

JWT Tool : A Toolkit For Testing, Tweaking & Cracking JSON Web Tokens

JWT Tool is an open-source Python toolkit for analyzing, testing, modifying, and validating JSON Web Tokens (JWTs). Security professionals use it to identify weak signing secrets, investigate signature-validation flaws, test token claims, and assess whether a web application accepts improperly constructed tokens.

JWTs commonly support authentication and authorization in web applications and APIs. However, insecure algorithm handling, weak secrets, and incorrect token validation can expose applications to authentication bypasses or privilege escalation. JWT Tool helps penetration testers investigate these weaknesses in authorized test environments.

Key Features of JWT Tool

JWT Tool provides several capabilities for examining token structure and testing how applications process signed tokens.

Token inspection: Decode and display JWT headers and payload claims to examine fields such as alg, typ, sub, exp, and role.
Signature and key testing: Verify tokens against available keys and investigate weak HMAC secrets through dictionary attacks.
Algorithm-confusion testing: Assess implementations that incorrectly handle symmetric and asymmetric signing algorithms, including historical RS/HS256 confusion vulnerabilities.
Signature-bypass testing: Check for insecure handling of unsigned tokens and other known signature-validation weaknesses.
Token tampering: Modify header fields and payload claims, then test how the application responds to the altered token.
Automated assessments: Use scanning modes and claim fuzzing to investigate common JWT implementation errors.

These capabilities help testers determine whether a weakness exists in the application rather than simply identifying suspicious token contents. A successful test depends on the target’s JWT library, configuration, signing keys, and validation logic.

Who Should Use JWT Tool?

JWT Tool is intended primarily for penetration testers, application security engineers, and developers who need to evaluate JWT-based authentication. It is also useful for security training, capture-the-flag challenges, and controlled vulnerability research.

Developers can use it to verify that applications reject modified claims, enforce expiration, validate signatures, and accept only explicitly permitted algorithms. For broader web reconnaissance, see our guide to WhatWeb, a web application fingerprinting tool.

JWT Tool Requirements and Installation

The current JWT Tool project uses Python 3. Clone the official repository and install its dependencies before running the script.

git clone https://github.com/ticarpi/jwt_tool.git
cd jwt_tool
python3 -m pip install -r requirements.txt

Check the available command-line options with:

python3 jwt_tool.py -h

Refer to the project’s official GitHub repository for current installation requirements, supported options, and updates. Older versions used Python 2, but the current project is based on Python 3.

How to Analyze a JWT

Start with a JWT captured from an application you own or are authorized to assess. A standard JWT commonly contains three Base64URL-encoded sections separated by periods: the header, payload, and signature.

Pass the token to JWT Tool to inspect its decoded contents:

python3 jwt_tool.py "YOUR_JWT_HERE"

Replace YOUR_JWT_HERE with the token from your test environment. The tool displays the available header and payload information, helping you review the declared signing algorithm and claims before choosing a test.

To interactively modify token fields, use tampering mode:

python3 jwt_tool.py "YOUR_JWT_HERE" -T

For a controlled weak-secret assessment, provide a test dictionary:

python3 jwt_tool.py "YOUR_JWT_HERE" -C -d wordlist.txt

Dictionary attacks are relevant to HMAC-signed tokens when the signing secret is weak or predictable. Use an approved test wordlist and account for the performance and resource requirements of the assessment.

Testing JWT Security Weaknesses

JWT Tool includes options for investigating historical vulnerabilities and implementation-specific weaknesses. For example, its exploit modes can test certain algorithm-confusion and unsigned-token scenarios. Other checks can examine key handling, token claims, and application responses to modified values.

Use the tool’s help output and the JWT Tool usage guide to select the appropriate option for each test. A decoded token alone does not prove that its signature is valid, and changing a claim does not automatically bypass server-side validation.

For additional background, read the JWT introduction and review the research on critical vulnerabilities in JWT libraries. These resources explain token structure and why incorrect algorithm or signature handling can create security risks.

Finding JWTs in Burp Suite

During an authorized web application assessment, Burp Suite’s search functionality can help locate token-like strings in captured traffic. The following regular expressions can be used as starting points, although matches must be checked manually because they can produce false positives.

For common URL-safe JWT patterns:

[= ]ey[A-Za-z0-9_-]*\.[A-Za-z0-9._-]*

For a broader search that also allows standard Base64 characters:

[= ]ey[A-Za-z0-9_\/+-]*\.[A-Za-z0-9._\/+-]*

Enable the regex option in Burp’s search interface. A match is only a candidate, not confirmation of a valid JWT. Review tokens carefully and avoid exposing live credentials or sensitive claims in logs, screenshots, or shared reports.