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.

---

made with <3 by URDev