X-JWT
jwt_tool
Python toolkit for validating, tampering with, and forging JSON Web Tokens to probe common signing and claim flaws.
OVERVIEW
jwt_tool (github.com/ticarpi/jwt_tool), MIT licensed and written in Python, is a toolkit built specifically around JSON Web Tokens: given a captured token, its scanning mode (-M pb, playbook scan) automatically runs it through a battery of known flaw classes — algorithm confusion (an RS256-to-HS256 downgrade), the 'none' algorithm bypass, weak or default HMAC secrets via a built-in cracking mode, and claim manipulation such as tampering with expiry or role/permission fields — and reports which checks the target's validation logic actually rejects versus silently accepts.
Beyond the automated scan, it exposes each technique individually (forging a token with a chosen key, injecting headers like jku/kid for key-confusion attacks, fuzzing claim values) so a finding from the scan can be reproduced and demonstrated as a standalone, minimal proof rather than relying on the tool's own scoring.
USE CASES
Practical use cases
- 01
Running the automated playbook scan against a captured JWT to triage which flaw classes are worth pursuing.
- 02
Attempting an alg-confusion or 'none'-algorithm downgrade to see if the server actually verifies the signing algorithm.
- 03
Cracking a weak or default HMAC secret to forge arbitrary tokens once a candidate wordlist match is found.
- 04
Tampering with claims (expiry, role, user ID) to test for broken access control enforced only at the token layer.
QUICK START
Once a captured JWT is in hand during a web engagement, to systematically check its signing algorithm, secret strength, and claim handling for common flaws.
- Capture a valid JWT issued by the target application (e.g. from a login response or auth header).
- Install jwt_tool (git clone plus its Python requirements) on the testing machine.
- Run the automated playbook scan against the token and target endpoint to triage flaw classes.
- Follow up on any positive with the specific technique (crack, forge, tamper) to build a minimal reproducible proof.
- Confirm the actual signing key/algorithm the server accepts before reporting a finding as exploitable.
python3 jwt_tool.py <JWT> -t https://target.example.com/api/endpoint -rc "Authorization: Bearer jwttool_test_token" -M pbBEFORE YOU RUN IT
What to check before running it
A scan hit is a lead, not a confirmed vulnerability — always confirm the actual signing key/algorithm the server accepts before reporting alg confusion or a cracked secret as exploitable.
Secret-cracking mode can generate a large number of requests or heavy local CPU use depending on wordlist size; confirm rate limits and authorized load before running it against a live target.
Forged tokens granting elevated access are highly sensitive artifacts — handle and store them per the engagement's evidence-handling rules, and revoke/rotate any real secret recovered during cracking.