JWTelescope

🇺🇸 English | 🇪🇸 Español

🔭 JWTelescope is an advanced CLI tool for decoding, inspecting, and performing security analysis on JSON Web Tokens (JWTs). It is designed for bug bounty hunters, pentesters, and developers who want fast insight into JWT structure, claims, and common misconfigurations.

The tool focuses on read-only analysis and risk assessment, making it safe to use during reconnaissance and triage phases.

✨ Features

Decode JWT header and payload (Base64URL)
Pretty, colorized terminal output
Automatic detection of common JWT security issues
Risk scoring system: Low / Medium / High
Human-readable timestamp conversion (exp, iat, nbf)
Detection of dangerous patterns:
- alg: none
- Missing or expired exp
- Very long-lived tokens
- Weak or generic aud
- Suspicious kid values (path traversal, predictability)
- Symmetric algorithm confusion risk (HS256)
- Dangerous custom claims (admin, role, scope, etc.)
- External jku / x5u URLs
Structured JSON output for reports and automation
Pipe-friendly modes (--raw, --stdin)
Minimal dependencies (Python standard library only)

🧠 Use Cases

Bug bounty reconnaissance
JWT misconfiguration detection
Token triage during API testing
Security reporting (HackerOne / Bugcrowd)
Learning and understanding JWT internals

📦 Installation

Clone the repository:

git clone https://github.com/urdev4ever/jwtelescope.git
cd jwtelescope

Make the script executable (optional):

chmod +x jwtelescope.py

Requirements:

Python 3.8+
No external libraries required

🚀 Usage

Read a JWT directly

./jwtelescope.py -r "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

Read from a file

./jwtelescope.py -f token.jwt

Read from stdin (piping)

echo "JWT_TOKEN" | ./jwtelescope.py --stdin

Raw JSON output (no colors, no analysis)

./jwtelescope.py -r "JWT_TOKEN" --raw

Show only security warnings

./jwtelescope.py -r "JWT_TOKEN" --only-warnings

Show risk score

./jwtelescope.py -r "JWT_TOKEN" --score

Generate structured JSON report

./jwtelescope.py -r "JWT_TOKEN" --json > report.json

[ ! ] Note: You can only use ./jwtelescope.py if you made it executable, otherwise you will need to use:

python jwtelescope.py

🧪 Example Output (using authorized JWT from anytask.com)

Decoded header
Decoded payload
Signature Details
Token metadata (length, algorithm, key ID)
Common claims overview
Security findings with severity
Overall risk score

⚠️ Risk Scoring Logic (Simplified)

Issue	Severity
`alg: none`	Critical
Missing `exp`	High
Expired token	High
Expiration > 10 years	High
Weak `aud`	Medium
HS256 confusion risk	Medium
Dangerous custom claims	Medium
Missing `nbf`	Low

Final risk levels:

Low: Mostly informational issues
Medium: Potential security weakness
High: Likely exploitable misconfiguration

📄 JSON Output Structure

{
  "metadata": {},
  "token_info": {},
  "header": {},
  "payload": {},
  "security_analysis": {},
  "common_claims": {}
}

Designed for easy ingestion into scripts, CI pipelines, or reports.

🔒 Security Philosophy

JWTelescope:

Does NOT modify tokens
Does NOT brute-force secrets
Does NOT bypass authentication

It is a passive analysis tool intended for legitimate security testing.

🚧 Disclaimer

This tool is intended for educational purposes and authorized security testing only.
Always test against systems you own or have explicit permission to test.

⭐ Contributing

Pull requests are welcome if they:

Improve JWT security detection logic or add new misconfiguration patterns
Enhance CLI usability, output clarity, or reporting formats (JSON / piping workflows)
Maintain the read-only, passive analysis philosophy of the tool and keep dependencies minimal

Made with <3 by URDev

URDev4ever/jwtelescope