JWT Inspector

Decode and audit JSON Web Tokens with no third-party dependencies. It splits the token, decodes header + payload, evaluates them against a set of security checks, and (for HMAC tokens) tries a fast offline crack of the signing secret against a wordlist.

When to use this skill

• "Decode / inspect this JWT."
• "Is this token configured securely?"
• "Does this JWT use a weak/guessable secret?"
• Auditing auth tokens during a security review.

Checks performed

• alg=none (critical) — unsigned, forgeable token.
• Symmetric alg (HS)* — HMAC verification key == signing secret; HS/RS confusion and brute-force risk.
• Missing exp / token never expires; excessively long lifetime.
• iat in the future, missing nbf, missing iss/aud/sub.
• Weak HMAC secret (critical) — cracked from a built-in or supplied wordlist.

How to run it

# Decode + audit
python skills/jwt-inspector/inspector.py "<token>"

# Read token from stdin
echo "<token>" | python skills/jwt-inspector/inspector.py -

# Try cracking the HMAC secret with a custom wordlist
python skills/jwt-inspector/inspector.py "<token>" --secret-list rockyou.txt

# JSON output
python skills/jwt-inspector/inspector.py "<token>" --json

# Only fail CI on high/critical (claim-hygiene notes are LOW)
python skills/jwt-inspector/inspector.py "<token>" --min-severity high

Exit codes: 0 clean · 1 issues reported · 2 malformed input. Every reported issue fails the build. The default reports everything down to info (including exp-past); raise --min-severity to low/medium/high to filter advisory notes out of both the report and the exit code.

Recommended workflow for Claude

1. Run the inspector and read the decoded payload to understand the token.
2. Report findings ordered by severity; explain the impact of each.
3. If a secret was cracked, stress that the key is compromised — rotate it and move to an asymmetric algorithm (RS256/ES256) where feasible.
4. Never treat a decoded payload as trusted: decoding ≠ verifying. Remind the user that signature verification with the correct key is what matters.

Note

Cracking only runs for HMAC algorithms and only against the provided wordlist — it is a weak-key detector, not a brute-forcer. Only inspect tokens you are authorized to handle.