jwt_tool Guide: Test and Exploit JSON Web Token Vulnerabilities

JSON Web Tokens handle authentication and state exchange across modern microservices and web APIs. When implementation teams fail to validate cryptographic signatures or improperly handle verification algorithms, authentication boundaries collapse completely. jwt_tool is an open-source security framework designed to audit, fuzz, and exploit vulnerabilities in JSON Web Token implementations.

Written by security researcher ticarpi, the tool automates testing for known cryptographic bypasses and signature flaw CVEs. You can inspect source code, wordlists, and updates directly on the official jwt_tool GitHub repository. Penetration testers and bug bounty hunters rely on it to identify broken verification logic in target systems.

Common JWT Vulnerabilities Audited by jwt_tool

A JSON Web Token consists of three base64url-encoded segments separated by dots: header, payload, and cryptographic signature. Vulnerabilities occur when server verification logic trusts user-controlled header parameters without enforcing strict backend validation policies.

Misconfigured decoders sometimes accept unsecured tokens or switch algorithms unexpectedly. Automating these test cases helps analysts uncover privilege escalation paths without constructing raw cryptographic payloads by hand.

Installing jwt_tool with Docker or Native Python

The fastest deployment method uses the pre-configured Docker image. Containerized execution packages all necessary cryptographic libraries without creating conflicts with your host Python packages.

# Run jwt_tool inside a disposable Docker container
docker run -it --network "host" --rm \
  -v "${PWD}:/tmp" \
  -v "${HOME}/.jwt_tool:/root/.jwt_tool" \
  ticarpi/jwt_tool <arguments>

You can also install the utility natively on Linux. Clone the repository and install the dependencies through pip inside your active environment.

# Clone repository and install cryptographic dependencies
git clone https://github.com/ticarpi/jwt_tool
cd jwt_tool
python3 -m pip install -r requirements.txt
chmod +x jwt_tool.py

Running the script for the first time generates local configuration files, logging paths, and RSA/ECDSA key pairs inside your local directory. Windows users running PowerShell or Command Prompt should install colorama to fix ANSI terminal color output issues.

Configuring External Listeners and JWKS Endpoints

Advanced tests like header injection and external JWKS validation require outbound interaction tracking. Open the generated jwtconf.ini file to configure network listener settings.

# Specify a unique Burp Collaborator or RequestBin URL in jwtconf.ini
httplistener = YOUR_SUBDOMAIN.burpcollaborator.net

# Specify the public URL hosting your generated test JWKS keys
jwkloc = https://your-external-server.com/.well-known/jwks.json

Setting up httplistener allows jwt_tool to catch out-of-band DNS lookups and HTTP requests triggered when vulnerable servers attempt to retrieve remote keys from attacker-specified headers.

Analyzing Tokens and Automating Security Scans

Begin analysis by passing the target token to inspect header values, claim payloads, and expiration timestamps. The tool decodes segments and presents formatted claim structures instantly.

# Decode and inspect raw token contents
python3 jwt_tool.py "eyJhbGciOi..."

# Run an automated security scan against a live endpoint
python3 jwt_tool.py "eyJhbGciOi..." -t "https://target-app.com/api/profile" -rh "Authorization: Bearer" -M at

The automated test suite (-M at) runs dozens of security checks against the target endpoint. It checks algorithm tampering, header injection, claim alteration, and signature omission while tracking HTTP response codes to spot authentication discrepancies.

Cracking Weak HMAC Secrets with Dictionary Attacks

Developers frequently use simple passwords or short passphrases as HMAC secrets for symmetric algorithms like HS256. If the signing secret is weak, attackers can calculate valid signatures offline.

# Perform an offline dictionary attack against a captured token
python3 jwt_tool.py "eyJhbGciOi..." -C -d /usr/share/wordlists/rockyou.txt

The cracking engine evaluates thousands of keys per second. If the secret matches an entry in your wordlist, jwt_tool displays the plaintext password and lets you forge new administrative claims.

Forging Administrative Tokens and Tampering Claims

Once you acquire the signing key or confirm an algorithm flaw, you can generate unauthorized tokens. Modify existing claims, grant elevated role permissions, or manipulate token expiration dates.

# Forge an administrative role claim using a known HMAC secret
python3 jwt_tool.py "eyJhbGciOi..." -p "secret123" -T -I -pc "role" -pv "admin"

The -T option enables tampering mode, while -I prompts for custom claim injections. The utility outputs the freshly signed, base64url-encoded string ready for authorization header testing in your requests.