jwtlint 0.2.0__py3-none-any.whl

jwtlint/__init__.py

@@ -0,0 +1,3 @@
+"""jwtlint — offline static analysis for JSON Web Tokens (RFC 7519/7515)."""
+
+__version__ = "0.1.0"

jwtlint/checks/__init__.py

@@ -0,0 +1,31 @@
+"""Static analysis checks run against a parsed JWT.
+
+Each check module exposes a `check(parsed, **options) -> list[Finding]`
+function. `run_all` wires them together in a fixed order.
+"""
+
+from __future__ import annotations
+
+from jwtlint.checks import alg_confusion, alg_none, claims, crack, header_injection, sensitive
+from jwtlint.checks.base import Finding
+from jwtlint.parser import ParsedToken
+
+
+def run_all(
+    parsed: ParsedToken,
+    expect_alg: str | None = None,
+    max_lifetime_seconds: int | None = None,
+    crack_wordlist: list[str] | None = None,
+) -> list[dict]:
+    findings: list[Finding] = []
+
+    findings.extend(alg_none.check(parsed))
+    findings.extend(alg_confusion.check(parsed, expect_alg=expect_alg))
+    findings.extend(header_injection.check(parsed))
+    findings.extend(claims.check(parsed, max_lifetime_seconds=max_lifetime_seconds))
+    findings.extend(sensitive.check(parsed))
+
+    if crack_wordlist is not None:
+        findings.extend(crack.check(parsed, wordlist=crack_wordlist))
+
+    return [f.to_dict() for f in findings]

jwtlint/checks/alg_confusion.py

@@ -0,0 +1,80 @@
+"""RS-to-HS algorithm confusion check.
+
+A static analyzer looking only at the token can't know what algorithm the
+server actually expects — that's server-side configuration, not something
+encoded in the token itself. `--expect-alg` lets the caller supply that
+context (e.g. "I know this service is configured for RS256").
+
+The attack: if a server verifies RS256/ES256 tokens using its RSA/EC
+*public* key, and an attacker submits an HS256 token instead, some JWT
+libraries will happily use whatever key material they're handed as the
+HMAC secret. Since the RSA public key is, by definition, public, the
+attacker can compute a valid HMAC signature over a forged token using the
+public key as the secret — and the server verifies it as authentic. This
+only matters if the verifier is naive enough to trust the `alg` from the
+attacker-controlled header instead of pinning the expected algorithm.
+"""
+
+from __future__ import annotations
+
+from jwtlint.checks.base import Finding
+from jwtlint.parser import ParsedToken
+
+CHECK_NAME = "alg-confusion"
+
+_HMAC_ALGS = {"HS256", "HS384", "HS512"}
+_ASYMMETRIC_ALGS = {"RS256", "RS384", "RS512", "ES256", "ES384", "ES512", "PS256", "PS384", "PS512"}
+
+
+def check(parsed: ParsedToken, expect_alg: str | None = None) -> list[Finding]:
+    if not expect_alg:
+        return []
+
+    alg = parsed.header.get("alg")
+    if not isinstance(alg, str):
+        return []
+
+    expect_alg_upper = expect_alg.upper()
+    alg_upper = alg.upper()
+
+    if alg_upper == expect_alg_upper:
+        return []
+
+    if alg_upper in _HMAC_ALGS and expect_alg_upper in _ASYMMETRIC_ALGS:
+        return [
+            Finding(
+                check=CHECK_NAME,
+                title=f"algorithm confusion risk: token uses {alg}, server expects {expect_alg}",
+                description=(
+                    f"This token's header specifies alg={alg} (HMAC), but the "
+                    f"server was told to expect {expect_alg} (RSA/EC, asymmetric). "
+                    "This is the classic RS-to-HS confusion attack: if the "
+                    "verifier passes its RSA/EC *public* key into an HMAC "
+                    "verification routine whenever the header says alg=HS*, an "
+                    "attacker can sign a forged token with HMAC-SHA256 using the "
+                    "public key (which is, by definition, known to the attacker) "
+                    "as the secret, and the server will treat it as validly "
+                    "signed. A safe verifier must pin the expected algorithm "
+                    "server-side and reject any token whose header claims a "
+                    "different one, rather than trusting alg from attacker-"
+                    "controlled input."
+                ),
+                severity="critical",
+                evidence={"token_alg": alg, "expected_alg": expect_alg},
+            )
+        ]
+
+    return [
+        Finding(
+            check=CHECK_NAME,
+            title=f"algorithm mismatch: token uses {alg}, server expects {expect_alg}",
+            description=(
+                f"The token's alg ({alg}) does not match the expected algorithm "
+                f"({expect_alg}). A verifier that doesn't strictly pin/allowlist "
+                "the algorithm may accept tokens signed under a weaker or "
+                "unintended scheme."
+            ),
+            severity="medium",
+            evidence={"token_alg": alg, "expected_alg": expect_alg},
+        )
+    ]

jwtlint/checks/alg_none.py

@@ -0,0 +1,60 @@
+"""`alg: none` check (CVE-class: JWT algorithm-none forgery).
+
+Some JWT libraries historically honored `"alg": "none"` (or accepted it
+case-insensitively — `"None"`, `"NONE"`, `"nOnE"`) and skipped signature
+verification entirely. An attacker who can set the header can then forge
+any payload with an empty signature segment. This is check #1 in basically
+every JWT security write-up because it's still found in the wild in custom
+or misconfigured verifiers.
+"""
+
+from __future__ import annotations
+
+from jwtlint.checks.base import Finding
+from jwtlint.parser import ParsedToken
+
+CHECK_NAME = "alg-none"
+
+
+def check(parsed: ParsedToken) -> list[Finding]:
+    alg = parsed.header.get("alg")
+    if not isinstance(alg, str):
+        return []
+
+    if alg.lower() != "none":
+        return []
+
+    findings = [
+        Finding(
+            check=CHECK_NAME,
+            title=f"alg: {alg!r} — unsigned/forgeable token",
+            description=(
+                "The header sets alg to a case-variant of 'none'. Libraries that "
+                "compare this case-insensitively (or that special-case 'none' "
+                "without validating the signature segment) will accept this token "
+                "with any payload and no valid signature — a classic auth bypass. "
+                "A safe verifier must reject 'none' outright and only accept an "
+                "algorithm it was explicitly configured to expect."
+            ),
+            severity="critical",
+            evidence={"alg": alg},
+        )
+    ]
+
+    if parsed.signature_segment.strip():
+        findings.append(
+            Finding(
+                check=CHECK_NAME,
+                title="alg: none token carries a non-empty signature segment",
+                description=(
+                    "alg is 'none' but the signature segment is non-empty. This is "
+                    "unusual — a spec-compliant 'none' token has an empty third "
+                    "segment. The signature bytes present here are ignored by any "
+                    "verifier that honors alg: none, so they provide no protection."
+                ),
+                severity="low",
+                evidence={"alg": alg, "signature_segment_length": len(parsed.signature_segment)},
+            )
+        )
+
+    return findings

jwtlint/checks/base.py

@@ -0,0 +1,30 @@
+"""Shared types for check modules.
+
+Every check module in this package exposes a `check(parsed, **kwargs) ->
+list[Finding]` function and returns findings shaped like `Finding.to_dict()`.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Literal
+
+Severity = Literal["info", "low", "medium", "high", "critical"]
+
+
+@dataclass
+class Finding:
+    check: str
+    title: str
+    description: str
+    severity: Severity
+    evidence: dict[str, Any] = field(default_factory=dict)
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "check": self.check,
+            "title": self.title,
+            "description": self.description,
+            "severity": self.severity,
+            "evidence": self.evidence,
+        }

jwtlint/checks/claims.py

@@ -0,0 +1,146 @@
+"""Standard claim hygiene checks (RFC 7519 section 4.1).
+
+Covers: missing exp, already-expired exp (informational), missing iat, nbf
+that looks wrong relative to iat, and unreasonably long-lived tokens.
+"""
+
+from __future__ import annotations
+
+import time
+
+from jwtlint.checks.base import Finding
+from jwtlint.parser import ParsedToken
+
+CHECK_NAME = "claims"
+
+# A year, as a round default for "this token lives suspiciously long."
+DEFAULT_MAX_LIFETIME_SECONDS = 365 * 24 * 3600
+
+
+def _numeric_claim(payload: dict, name: str) -> float | None:
+    value = payload.get(name)
+    if isinstance(value, bool):  # bool is a subclass of int, exclude explicitly
+        return None
+    if isinstance(value, (int, float)):
+        return float(value)
+    return None
+
+
+def check(parsed: ParsedToken, max_lifetime_seconds: int | None = None) -> list[Finding]:
+    threshold = max_lifetime_seconds if max_lifetime_seconds is not None else DEFAULT_MAX_LIFETIME_SECONDS
+    payload = parsed.payload
+    findings: list[Finding] = []
+    now = time.time()
+
+    exp = _numeric_claim(payload, "exp")
+    iat = _numeric_claim(payload, "iat")
+    nbf = _numeric_claim(payload, "nbf")
+
+    if "exp" not in payload:
+        findings.append(
+            Finding(
+                check=CHECK_NAME,
+                title="No exp (expiration) claim",
+                description=(
+                    "The token has no exp claim, so it never expires by "
+                    "definition. A stolen or leaked token remains valid "
+                    "indefinitely unless revoked out-of-band. Every token "
+                    "issued to a client should carry a bounded expiration."
+                ),
+                severity="high",
+                evidence={},
+            )
+        )
+    elif exp is None:
+        findings.append(
+            Finding(
+                check=CHECK_NAME,
+                title="exp claim is not a valid NumericDate",
+                description=(
+                    "exp is present but is not a number (RFC 7519 requires exp to "
+                    "be a NumericDate — seconds since the Unix epoch). A verifier "
+                    "that fails to validate this type may treat the token as "
+                    "never expiring."
+                ),
+                severity="medium",
+                evidence={"exp": payload.get("exp")},
+            )
+        )
+    elif exp < now:
+        findings.append(
+            Finding(
+                check=CHECK_NAME,
+                title="Token is expired",
+                description=(
+                    f"exp ({exp:.0f}) is in the past relative to the current time "
+                    f"({now:.0f}). This isn't a vulnerability by itself — an "
+                    "expired token should be rejected by any correct verifier — "
+                    "it's just noted for context."
+                ),
+                severity="info",
+                evidence={"exp": exp, "now": now, "expired_seconds_ago": now - exp},
+            )
+        )
+
+    if "iat" not in payload:
+        findings.append(
+            Finding(
+                check=CHECK_NAME,
+                title="No iat (issued-at) claim",
+                description=(
+                    "The token has no iat claim. iat isn't required by the spec, "
+                    "but without it there's no record of when the token was "
+                    "issued, which makes it harder to reason about token age, "
+                    "detect replay of very old tokens, or audit issuance."
+                ),
+                severity="low",
+                evidence={},
+            )
+        )
+    elif iat is None:
+        findings.append(
+            Finding(
+                check=CHECK_NAME,
+                title="iat claim is not a valid NumericDate",
+                description="iat is present but is not a number (RFC 7519 NumericDate).",
+                severity="low",
+                evidence={"iat": payload.get("iat")},
+            )
+        )
+
+    if nbf is not None and iat is not None and nbf < iat:
+        findings.append(
+            Finding(
+                check=CHECK_NAME,
+                title="nbf predates iat",
+                description=(
+                    f"nbf ({nbf:.0f}) is earlier than iat ({iat:.0f}) — the token "
+                    "claims to be valid before it was issued. This is logically "
+                    "inconsistent and may indicate a clock issue on the issuer or "
+                    "a hand-crafted/forged token."
+                ),
+                severity="low",
+                evidence={"nbf": nbf, "iat": iat},
+            )
+        )
+
+    if exp is not None and iat is not None:
+        lifetime = exp - iat
+        if lifetime > threshold:
+            findings.append(
+                Finding(
+                    check=CHECK_NAME,
+                    title="Unusually long token lifetime",
+                    description=(
+                        f"exp - iat is {lifetime:.0f} seconds (~{lifetime / 86400:.0f} days), "
+                        f"above the {threshold} second (~{threshold / 86400:.0f} day) threshold. "
+                        "Long-lived tokens widen the window an attacker can use a "
+                        "stolen token, and make revocation more important since "
+                        "there's no natural expiry to rely on."
+                    ),
+                    severity="medium",
+                    evidence={"exp": exp, "iat": iat, "lifetime_seconds": lifetime, "threshold_seconds": threshold},
+                )
+            )
+
+    return findings

jwtlint/checks/crack.py

@@ -0,0 +1,100 @@
+"""Offline HMAC secret brute force for HS256/HS384/HS512 tokens.
+
+For each candidate key, recomputes HMAC-SHA{256,384,512} over the token's
+signing input (`base64url(header) + "." + base64url(payload)`, per RFC 7515)
+using Python's `hmac`/`hashlib` directly, and compares it to the token's
+actual signature bytes with a constant-time comparison. This is entirely
+local/offline — no network calls, no interaction with any server.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import hmac
+
+from jwtlint.checks.base import Finding
+from jwtlint.parser import ParsedToken
+
+CHECK_NAME = "hmac-crack"
+
+_HASH_FOR_ALG = {
+    "HS256": hashlib.sha256,
+    "HS384": hashlib.sha384,
+    "HS512": hashlib.sha512,
+}
+
+
+def try_crack(parsed: ParsedToken, wordlist: list[str]) -> str | None:
+    """Return the cracked secret, or None if nothing in the wordlist matches."""
+    alg = parsed.header.get("alg")
+    if not isinstance(alg, str):
+        return None
+
+    hash_fn = _HASH_FOR_ALG.get(alg.upper())
+    if hash_fn is None:
+        return None
+
+    target_sig = parsed.signature_bytes
+    if not target_sig:
+        return None
+
+    signing_input = parsed.signing_input
+
+    for candidate in wordlist:
+        candidate = candidate.strip()
+        if not candidate:
+            continue
+        computed = hmac.new(candidate.encode("utf-8"), signing_input, hash_fn).digest()
+        if hmac.compare_digest(computed, target_sig):
+            return candidate
+
+    return None
+
+
+def check(parsed: ParsedToken, wordlist: list[str]) -> list[Finding]:
+    alg = parsed.header.get("alg")
+    if not isinstance(alg, str) or alg.upper() not in _HASH_FOR_ALG:
+        return [
+            Finding(
+                check=CHECK_NAME,
+                title="HMAC crack skipped: alg is not HS256/HS384/HS512",
+                description=(
+                    f"--crack was passed but the token's alg is {alg!r}, which is "
+                    "not an HMAC algorithm. There is no shared secret to brute "
+                    "force for asymmetric (RS/ES/PS) or none-algorithm tokens."
+                ),
+                severity="info",
+                evidence={"alg": alg},
+            )
+        ]
+
+    cracked = try_crack(parsed, wordlist)
+    if cracked is not None:
+        return [
+            Finding(
+                check=CHECK_NAME,
+                title="HMAC secret cracked",
+                description=(
+                    f"The signing secret was recovered from the wordlist: {cracked!r}. "
+                    "Anyone with this token can now forge arbitrary tokens signed "
+                    "with the same key. Rotate the secret and use a high-entropy, "
+                    "randomly generated key of at least 256 bits."
+                ),
+                severity="critical",
+                evidence={"alg": alg, "secret": cracked},
+            )
+        ]
+
+    return [
+        Finding(
+            check=CHECK_NAME,
+            title="HMAC secret not found in wordlist",
+            description=(
+                f"Tried {len(wordlist)} candidate secret(s) against this {alg} "
+                "token; none matched. This does not mean the secret is strong — "
+                "only that it isn't in the wordlist tried."
+            ),
+            severity="info",
+            evidence={"alg": alg, "attempts": len(wordlist)},
+        )
+    ]

jwtlint/checks/header_injection.py

@@ -0,0 +1,137 @@
+"""Key-selection header checks: jku, x5u, jwk, x5c, kid.
+
+These headers tell the verifier *where to find the key*. They live in the
+header, which the attacker controls, so a verifier that honours them without
+an allowlist lets the attacker pick the key used to check their own forgery.
+
+- jku / x5u: URL to fetch a JWK Set / X.509 chain from. Point it at an
+  attacker-hosted key and sign with the matching private key. Also an SSRF
+  primitive if the server fetches it blindly.
+- jwk: the public key embedded inline (CVE-2018-0114 in node-jose). The
+  attacker embeds their own key and signs with it.
+- x5c: same idea as jwk, with an inline certificate chain.
+- kid: a free-form key id. Often used as a filename or DB lookup key, so
+  path traversal or SQL fragments here point at injection in the key lookup.
+"""
+
+from __future__ import annotations
+
+import re
+from typing import Any
+
+from jwtlint.checks.base import Finding
+from jwtlint.parser import ParsedToken
+
+CHECK_NAME = "header-injection"
+
+_TRAVERSAL = re.compile(r"(\.\./|\.\.\\|^/|^[a-zA-Z]:\\|/dev/null|/etc/|/proc/)")
+_SQL = re.compile(r"('|\"|--|;|\bunion\b|\bselect\b|\bor\s+1\s*=\s*1\b)", re.IGNORECASE)
+_SHELL = re.compile(r"(\$\(|`|\|\||&&|\|)")
+
+
+def check(parsed: ParsedToken) -> list[Finding]:
+    header = parsed.header
+    findings: list[Finding] = []
+
+    for name in ("jku", "x5u"):
+        value = header.get(name)
+        if value is not None:
+            findings.append(_url_header(name, value))
+
+    if "jwk" in header:
+        findings.append(
+            Finding(
+                check=CHECK_NAME,
+                title="embedded jwk header: token carries its own verification key",
+                description=(
+                    "The header embeds a public key (jwk). A verifier that uses "
+                    "this key to check the signature lets anyone sign a token with "
+                    "their own private key and embed the matching public key "
+                    "(CVE-2018-0114). Keys must come from server-side config, "
+                    "never from the token."
+                ),
+                severity="high",
+                evidence={"jwk": header["jwk"]},
+            )
+        )
+
+    if "x5c" in header:
+        findings.append(
+            Finding(
+                check=CHECK_NAME,
+                title="embedded x5c header: token carries its own certificate chain",
+                description=(
+                    "The header embeds an X.509 chain (x5c). Unless the verifier "
+                    "validates that chain against a pinned trust anchor, an "
+                    "attacker can supply a self-signed certificate and sign with "
+                    "its key."
+                ),
+                severity="medium",
+                evidence={"certs": len(header["x5c"]) if isinstance(header["x5c"], list) else None},
+            )
+        )
+
+    if "kid" in header:
+        findings.extend(_kid(header["kid"]))
+
+    return findings
+
+
+def _url_header(name: str, value: Any) -> Finding:
+    return Finding(
+        check=CHECK_NAME,
+        title=f"{name} header present: key is fetched from a URL ({value})",
+        description=(
+            f"The header tells the verifier to fetch its key from {name}={value!r}. "
+            "If the server follows this URL without a strict allowlist, an "
+            "attacker can host their own key and sign forged tokens with it. "
+            "A blind fetch is also a server-side request forgery vector. "
+            "Ignore this header or pin it to a fixed, trusted URL."
+        ),
+        severity="high",
+        evidence={name: value},
+    )
+
+
+def _kid(value: Any) -> list[Finding]:
+    if not isinstance(value, str):
+        return [
+            Finding(
+                check=CHECK_NAME,
+                title=f"kid is not a string ({type(value).__name__})",
+                description=(
+                    "RFC 7515 defines kid as a string. A non-string kid can trip "
+                    "type-confusion bugs in the key lookup."
+                ),
+                severity="low",
+                evidence={"kid": value},
+            )
+        ]
+
+    hits = []
+    if _TRAVERSAL.search(value):
+        hits.append("path traversal")
+    if _SQL.search(value):
+        hits.append("SQL injection")
+    if _SHELL.search(value):
+        hits.append("command injection")
+
+    if not hits:
+        return []
+
+    kinds = ", ".join(hits)
+    return [
+        Finding(
+            check=CHECK_NAME,
+            title=f"suspicious kid value ({kinds}): {value!r}",
+            description=(
+                f"The kid header looks like a {kinds} payload. Servers often use "
+                "kid as a filename or database key when loading the signing "
+                "key. A classic trick is kid=../../dev/null so the key becomes "
+                "an empty string, then signing with an empty HMAC secret. "
+                "Treat kid as an opaque id and look it up in a fixed map."
+            ),
+            severity="high",
+            evidence={"kid": value, "patterns": hits},
+        )
+    ]

jwtlint/checks/sensitive.py

@@ -0,0 +1,101 @@
+"""Sensitive data in the payload.
+
+A JWS payload is base64url, not encryption. Anyone holding the token (logs,
+browser storage, proxies, referer headers) can read it. Flag claim names and
+values that look like they shouldn't be there.
+"""
+
+from __future__ import annotations
+
+import re
+from typing import Any
+
+from jwtlint.checks.base import Finding
+from jwtlint.parser import ParsedToken
+
+CHECK_NAME = "sensitive-data"
+
+# Matched against the claim name normalised to snake_case, on word edges, so
+# "shipping" doesn't hit "pin" and "token_type" doesn't hit "token".
+_SECRET_KEYS = re.compile(
+    r"(^|_)(pass|password|passwd|pwd|secret|api_?key|private_?key|access_?key|"
+    r"client_?secret|access_?token|refresh_?token|id_?token|session_?id|otp|pin|cvv)(_|$)"
+)
+_PII_KEYS = re.compile(
+    r"(^|_)(ssn|social_?security|tc_?kimlik|tckn|national_?id|passport|"
+    r"iban|card_?number|credit_?card|dob|birth_?date|date_?of_?birth|phone|phone_?number|address)(_|$)"
+)
+
+_VALUE_PATTERNS: list[tuple[str, re.Pattern[str]]] = [
+    ("AWS access key", re.compile(r"\bAKIA[0-9A-Z]{16}\b")),
+    ("GitHub token", re.compile(r"\bgh[pousr]_[A-Za-z0-9]{36,}\b")),
+    ("private key block", re.compile(r"-----BEGIN [A-Z ]*PRIVATE KEY-----")),
+    ("card number", re.compile(r"\b(?:\d[ -]?){13,19}\b")),
+    ("IBAN", re.compile(r"\b[A-Z]{2}\d{2}[A-Z0-9]{11,30}\b")),
+]
+
+
+def check(parsed: ParsedToken) -> list[Finding]:
+    findings: list[Finding] = []
+    for path, raw_key, value in _walk(parsed.payload):
+        key = _snake(raw_key)
+        if _SECRET_KEYS.search(key) and _has_content(value):
+            findings.append(_finding(path, "secret-looking claim", "high"))
+        elif _PII_KEYS.search(key) and _has_content(value):
+            findings.append(_finding(path, "personal data claim", "medium"))
+        elif isinstance(value, str):
+            for label, pattern in _VALUE_PATTERNS:
+                if pattern.search(value) and (label != "card number" or _luhn(value)):
+                    findings.append(_finding(path, f"{label} in claim value", "high"))
+                    break
+    return findings
+
+
+def _finding(path: str, what: str, severity: str) -> Finding:
+    return Finding(
+        check=CHECK_NAME,
+        title=f"{what}: {path}",
+        description=(
+            f"Claim {path!r} looks sensitive. JWT payloads are only base64url "
+            "encoded, so anyone who sees the token can read it. Keep secrets "
+            "and personal data server-side, or use an encrypted JWE."
+        ),
+        severity=severity,
+        evidence={"claim": path},
+    )
+
+
+def _walk(obj: Any, prefix: str = ""):
+    if isinstance(obj, dict):
+        for k, v in obj.items():
+            path = f"{prefix}.{k}" if prefix else str(k)
+            yield path, str(k), v
+            yield from _walk(v, path)
+    elif isinstance(obj, list):
+        for i, v in enumerate(obj):
+            yield from _walk(v, f"{prefix}[{i}]")
+
+
+def _snake(key: str) -> str:
+    key = re.sub(r"(?<=[a-z0-9])(?=[A-Z])", "_", key)
+    return re.sub(r"[^a-z0-9]+", "_", key.lower()).strip("_")
+
+
+def _has_content(value: Any) -> bool:
+    if isinstance(value, (dict, list)):
+        return False
+    return value not in (None, "", False)
+
+
+def _luhn(text: str) -> bool:
+    digits = [int(c) for c in re.sub(r"\D", "", text)]
+    if not 13 <= len(digits) <= 19:
+        return False
+    total = 0
+    for i, d in enumerate(reversed(digits)):
+        if i % 2:
+            d *= 2
+            if d > 9:
+                d -= 9
+        total += d
+    return total % 10 == 0

jwtlint/cli.py

@@ -0,0 +1,152 @@
+"""jwtlint command-line entrypoint.
+
+    jwtlint <token>                        decode + analyze a token
+    jwtlint --file token.txt               read the token from a file
+    echo <token> | jwtlint                 read the token from stdin
+    jwtlint <token> --expect-alg RS256     flag RS-to-HS confusion risk
+    jwtlint <token> --crack                try the built-in weak-secret wordlist
+    jwtlint <token> --crack wordlist.txt   try a custom wordlist
+"""
+
+from __future__ import annotations
+
+import json
+import sys
+
+import click
+from rich.console import Console
+from rich.syntax import Syntax
+from rich.table import Table
+
+from jwtlint.checks import run_all
+from jwtlint.parser import TokenParseError, parse
+from jwtlint.wordlist import DEFAULT_WORDLIST
+
+SEVERITY_STYLE = {
+    "critical": "bold white on red",
+    "high": "bold red",
+    "medium": "bold yellow",
+    "low": "cyan",
+    "info": "dim",
+}
+
+SEVERITY_ORDER = {"critical": 0, "high": 1, "medium": 2, "low": 3, "info": 4}
+
+console = Console()
+
+
+@click.command()
+@click.argument("token", required=False)
+@click.option("--file", "file_path", type=click.Path(exists=True, dir_okay=False), help="Read the token from a file instead of the argument.")
+@click.option("--expect-alg", "expect_alg", help="Algorithm the server is expected to use (e.g. RS256). Flags RS-to-HS confusion risk if the token uses HS*.")
+@click.option("--crack", "crack_target", is_flag=False, flag_value="__default__", default=None, help="Try to brute force the HMAC secret. Pass a wordlist path, or nothing to use the built-in list.")
+@click.option("--max-lifetime-days", "max_lifetime_days", type=int, default=None, help="Flag tokens with exp - iat longer than this many days (default 365).")
+@click.option("--json", "json_out", is_flag=True, help="Print findings as JSON instead of a table.")
+@click.version_option(package_name="jwtlint")
+def main(
+    token: str | None,
+    file_path: str | None,
+    expect_alg: str | None,
+    crack_target: str | None,
+    max_lifetime_days: int | None,
+    json_out: bool,
+) -> None:
+    """Static, offline JWT security analyzer. Parses TOKEN and reports findings."""
+    token_text = _resolve_token(token, file_path)
+
+    try:
+        parsed = parse(token_text)
+    except TokenParseError as exc:
+        console.print(f"[bold red]error:[/] {exc}")
+        sys.exit(2)
+
+    wordlist = None
+    if crack_target is not None:
+        wordlist = DEFAULT_WORDLIST if crack_target == "__default__" else _load_wordlist(crack_target)
+
+    max_lifetime_seconds = max_lifetime_days * 86400 if max_lifetime_days is not None else None
+
+    findings = run_all(
+        parsed,
+        expect_alg=expect_alg,
+        max_lifetime_seconds=max_lifetime_seconds,
+        crack_wordlist=wordlist,
+    )
+    findings.sort(key=lambda f: SEVERITY_ORDER.get(f["severity"], 9))
+
+    if json_out:
+        console.print_json(json.dumps({"header": parsed.header, "payload": parsed.payload, "findings": findings}))
+    else:
+        _print_decoded(parsed)
+        _print_table(findings)
+
+    if any(f["severity"] in ("critical", "high") for f in findings):
+        sys.exit(1)
+
+
+def _resolve_token(token: str | None, file_path: str | None) -> str:
+    if file_path:
+        with open(file_path) as fh:
+            text = fh.read()
+    elif token and token != "-":
+        text = token
+    elif token == "-" or not sys.stdin.isatty():
+        text = sys.stdin.read()
+    else:
+        console.print("[bold red]error:[/] provide a token argument, --file, or pipe it on stdin")
+        sys.exit(2)
+    return _strip_auth_prefix(text.strip())
+
+
+def _strip_auth_prefix(text: str) -> str:
+    """Accept a pasted `Authorization: Bearer <jwt>` line as-is."""
+    if text.lower().startswith("authorization:"):
+        text = text.split(":", 1)[1].strip()
+    if text.lower().startswith("bearer "):
+        text = text[7:].strip()
+    return text
+
+
+def _load_wordlist(path: str) -> list[str]:
+    try:
+        with open(path) as fh:
+            return [line.rstrip("\n") for line in fh]
+    except OSError as exc:
+        console.print(f"[bold red]error:[/] could not read wordlist {path!r}: {exc}")
+        sys.exit(2)
+
+
+def _print_decoded(parsed) -> None:
+    header_json = json.dumps(parsed.header, indent=2, sort_keys=True)
+    payload_json = json.dumps(parsed.payload, indent=2, sort_keys=True)
+    console.print("[bold]header[/]")
+    console.print(Syntax(header_json, "json", theme="ansi_dark", background_color="default"))
+    console.print("[bold]payload[/]")
+    console.print(Syntax(payload_json, "json", theme="ansi_dark", background_color="default"))
+
+
+def _print_table(findings: list[dict]) -> None:
+    table = Table(title="jwtlint findings", show_lines=False, header_style="bold")
+    table.add_column("sev", width=8)
+    table.add_column("check")
+    table.add_column("finding")
+
+    for f in findings:
+        style = SEVERITY_STYLE.get(f["severity"], "")
+        table.add_row(
+            f"[{style}]{f['severity']}[/]",
+            f["check"],
+            f["title"],
+        )
+
+    console.print(table)
+
+    counts: dict[str, int] = {}
+    for f in findings:
+        counts[f["severity"]] = counts.get(f["severity"], 0) + 1
+    summary = "  ".join(f"[{SEVERITY_STYLE.get(sev, '')}]{sev}: {n}[/]" for sev, n in counts.items())
+    console.print(f"\n{len(findings)} findings" + (f" — {summary}" if summary else "") + "\n")
+
+
+if __name__ == "__main__":
+    main()

jwtlint/parser.py

@@ -0,0 +1,101 @@
+"""Raw JWT structure parsing.
+
+Deliberately does not use a JWT library. A security analyzer needs to reason
+about the raw three-segment structure (including cases a permissive decoder
+library would normalize away or refuse to touch, e.g. `alg: none`), so the
+base64url decode and JSON parse are done by hand here per RFC 7519 / RFC 7515.
+"""
+
+from __future__ import annotations
+
+import base64
+import binascii
+import json
+from dataclasses import dataclass
+from typing import Any
+
+
+class TokenParseError(Exception):
+    """Raised when input cannot be parsed as a structurally valid JWT."""
+
+
+@dataclass
+class ParsedToken:
+    raw: str
+    header_segment: str
+    payload_segment: str
+    signature_segment: str
+    header: dict[str, Any]
+    payload: dict[str, Any]
+
+    @property
+    def signing_input(self) -> bytes:
+        """`base64url(header) + "." + base64url(payload)` — the exact bytes
+        that are signed/verified per RFC 7515."""
+        return f"{self.header_segment}.{self.payload_segment}".encode("ascii")
+
+    @property
+    def signature_bytes(self) -> bytes:
+        return _b64url_decode(self.signature_segment) if self.signature_segment else b""
+
+
+def _b64url_decode(segment: str) -> bytes:
+    """base64url-decode a JWT segment, restoring the padding JWTs omit."""
+    padding_needed = (-len(segment)) % 4
+    padded = segment + ("=" * padding_needed)
+    try:
+        return base64.urlsafe_b64decode(padded)
+    except (binascii.Error, ValueError) as exc:
+        raise TokenParseError(f"invalid base64url encoding: {exc}") from exc
+
+
+def _b64url_decode_json(segment: str, part_name: str) -> dict[str, Any]:
+    raw_bytes = _b64url_decode(segment)
+    try:
+        text = raw_bytes.decode("utf-8")
+    except UnicodeDecodeError as exc:
+        raise TokenParseError(f"{part_name} is not valid UTF-8: {exc}") from exc
+    try:
+        data = json.loads(text)
+    except json.JSONDecodeError as exc:
+        raise TokenParseError(f"{part_name} is not valid JSON: {exc}") from exc
+    if not isinstance(data, dict):
+        raise TokenParseError(f"{part_name} JSON must be an object, got {type(data).__name__}")
+    return data
+
+
+def parse(token: str) -> ParsedToken:
+    """Split and decode a compact-serialization JWT into its three segments.
+
+    Raises TokenParseError with a clear, non-stack-trace message for any
+    malformed input: wrong segment count, bad base64url, bad JSON, or a
+    non-object header/payload.
+    """
+    token = token.strip()
+    if not token:
+        raise TokenParseError("empty input")
+
+    segments = token.split(".")
+    if len(segments) != 3:
+        raise TokenParseError(
+            f"expected 3 dot-separated segments (header.payload.signature), got {len(segments)}"
+        )
+
+    header_segment, payload_segment, signature_segment = segments
+
+    if not header_segment:
+        raise TokenParseError("header segment is empty")
+    if not payload_segment:
+        raise TokenParseError("payload segment is empty")
+
+    header = _b64url_decode_json(header_segment, "header")
+    payload = _b64url_decode_json(payload_segment, "payload")
+
+    return ParsedToken(
+        raw=token,
+        header_segment=header_segment,
+        payload_segment=payload_segment,
+        signature_segment=signature_segment,
+        header=header,
+        payload=payload,
+    )

jwtlint/wordlist.py

@@ -0,0 +1,63 @@
+"""Built-in wordlist of common weak HMAC secrets used with `--crack` when no
+wordlist file is given. Sourced from the usual suspects: default/placeholder
+values shipped in tutorials and boilerplate, plus generically weak passwords
+that show up in every leaked-credential list.
+"""
+
+from __future__ import annotations
+
+DEFAULT_WORDLIST: list[str] = [
+    "secret",
+    "Secret",
+    "secret123",
+    "password",
+    "Password",
+    "password123",
+    "changeme",
+    "changethis",
+    "changeit",
+    "your-256-bit-secret",
+    "your-secret-key",
+    "your-secret-key-here",
+    "supersecret",
+    "super-secret",
+    "supersecretkey",
+    "mysecret",
+    "my-secret",
+    "jwtsecret",
+    "jwt-secret",
+    "jwt_secret",
+    "signingkey",
+    "signing-key",
+    "test",
+    "testing",
+    "dev",
+    "development",
+    "development-secret",
+    "development-only-secret",
+    "local",
+    "localhost",
+    "admin",
+    "administrator",
+    "letmein",
+    "qwerty",
+    "12345678",
+    "123456789",
+    "0123456789",
+    "abcdefgh",
+    "default",
+    "defaultsecret",
+    "key",
+    "apikey",
+    "api-key",
+    "api_key",
+    "token",
+    "authsecret",
+    "auth-secret",
+    "companyname",
+    "acme",
+    "acme-secret",
+    "insecure",
+    "notsecure",
+    "not-a-secret",
+]

jwtlint-0.2.0.dist-info/METADATA

@@ -0,0 +1,149 @@
+Metadata-Version: 2.4
+Name: jwtlint
+Version: 0.2.0
+Summary: Offline static security analysis for JWTs.
+Author: Baran Ayaztas
+License: MIT
+Project-URL: Homepage, https://github.com/ReazGan/jwtlint
+Project-URL: Issues, https://github.com/ReazGan/jwtlint/issues
+Keywords: jwt,security,pentest,bug-bounty,appsec,static-analysis,jws
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Information Technology
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Security
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: click>=8.1
+Requires-Dist: rich>=13.7
+Dynamic: license-file
+
+# jwtlint
+
+[![CI](https://github.com/ReazGan/jwtlint/actions/workflows/ci.yml/badge.svg)](https://github.com/ReazGan/jwtlint/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/jwtlint)](https://pypi.org/project/jwtlint/)
+
+Offline static security analysis for JWTs (RFC 7519 / RFC 7515). Paste a
+token from Burp, a log line or an `Authorization` header and get a list of
+what's wrong with it. Parses the three base64url segments itself, no JWT
+library in the analysis path, no network calls.
+
+![jwtlint flagging a token with a jku header, a kid path traversal and a weak secret](https://raw.githubusercontent.com/ReazGan/jwtlint/main/docs/screenshot.svg)
+
+## Install
+
+```
+pip install jwtlint
+```
+
+or from source:
+
+```
+git clone https://github.com/ReazGan/jwtlint
+cd jwtlint
+pip install -e .
+```
+
+## Usage
+
+```
+$ jwtlint eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJ1c2VyLTQyIiwiaWF0IjoxNzg3MjY5OTY5LCJleHAiOjE3ODcyNzM1Njl9.0RVnIJ29GLfYPK3YfZNbLuhf_19F4nI71aeg0ZvZSr4
+header
+{
+  "alg": "HS256",
+  "typ": "JWT"
+}
+payload
+{
+  "exp": 1787273569,
+  "iat": 1787269969,
+  "sub": "user-42"
+}
+       jwtlint findings
+┏━━━━━━━━━━┳━━━━━━━┳━━━━━━━━━┓
+┃ sev      ┃ check ┃ finding ┃
+┡━━━━━━━━━━╇━━━━━━━╇━━━━━━━━━┩
+└──────────┴───────┴─────────┘
+
+0 findings
+```
+
+An `alg: none` forgery attempt (see the screenshot above for the full run):
+
+```
+$ jwtlint eyJhbGciOiAibm9uZSIsICJ0eXAiOiAiSldUIn0.eyJzdWIiOiAiYXR0YWNrZXIiLCAiYWRtaW4iOiB0cnVlLCAiaWF0IjogMTcwMDAwMDAwMH0.
+critical  alg-none  alg: 'none' — unsigned/forgeable token
+high      claims    No exp (expiration) claim
+
+2 findings — critical: 1  high: 1
+```
+
+Other flags:
+
+```
+jwtlint --file token.txt                 # read the token from a file instead of argv
+pbpaste | jwtlint                        # read from stdin ("Bearer ..." prefix is fine)
+jwtlint <token> --expect-alg RS256       # flag RS-to-HS confusion if the token uses HS*
+jwtlint <token> --crack                  # try the built-in weak-secret wordlist
+jwtlint <token> --crack wordlist.txt     # try a custom wordlist
+jwtlint <token> --json                   # findings as JSON instead of a table
+```
+
+Exit code is `1` if any finding is `critical` or `high` — usable as a CI gate.
+Malformed input (wrong segment count, bad base64url, bad JSON) exits `2` with
+a plain error message, not a stack trace.
+
+## Checks
+
+- **alg-none** — header specifies `alg: none` (case-insensitively — `None`,
+  `NONE`, etc. are all caught), the classic unsigned-token forgery.
+- **alg-confusion** — with `--expect-alg RS256` (or any RS/ES/PS algorithm),
+  flags a token that instead uses HS256/384/512 as a possible RS-to-HS key
+  confusion attack: a verifier that feeds its RSA/EC public key into HMAC
+  verification whenever the header says `alg: HS*` can be tricked into
+  accepting a token forged with that (public, therefore attacker-known) key
+  as the HMAC secret.
+- **header-injection** — key-selection headers the attacker controls:
+  `jku` / `x5u` (verifier fetches the key from a URL, also an SSRF vector),
+  an embedded `jwk` (CVE-2018-0114 style self-signed tokens), an embedded
+  `x5c` chain, and `kid` values that look like path traversal
+  (`../../dev/null`), SQL or shell injection.
+- **sensitive-data** — payload claims that look like passwords, API keys,
+  session ids or personal data (national id, IBAN, phone, card numbers with
+  a Luhn check). Payloads are base64url, not encrypted: anyone holding the
+  token can read them.
+- **claims** — missing `exp` (high, token never expires), an already-expired
+  `exp` (info, just noted), missing `iat` (low), `nbf` earlier than `iat`
+  (low), and unreasonably long-lived tokens — `exp - iat` over a year by
+  default, configurable with `--max-lifetime-days`.
+- **hmac-crack** (`--crack`, opt-in, fully offline) — for HS256/384/512
+  tokens, recomputes the HMAC signature for each line of a wordlist and
+  compares against the token's actual signature. Ships a built-in list of
+  ~50 common weak secrets used by default when `--crack` is passed with no
+  file.
+
+## In CI
+
+Exit code `1` on critical/high makes it a one-line gate, e.g. to make sure
+the tokens your test suite issues never carry secrets or skip `exp`:
+
+```yaml
+- run: pip install jwtlint
+- run: python scripts/issue_test_token.py | jwtlint
+```
+
+## Scope
+
+A lean, non-interactive, single-purpose static analyzer — decode a token,
+report what's wrong with it, exit. It doesn't talk to a server, doesn't try
+exploits, and doesn't cover every JWT attack technique.
+[`ticarpi/jwt_tool`](https://github.com/ticarpi/jwt_tool) is the heavier
+reference tool if you need full interactive exploitation tooling.
+
+## License
+
+MIT

jwtlint-0.2.0.dist-info/RECORD

@@ -0,0 +1,18 @@
+jwtlint/__init__.py,sha256=97FNMXtEELbOxFmWqt4YflQ-NjATEcX5SQON1bUV3Ao,102
+jwtlint/cli.py,sha256=HKKw4sdiwb32bWpldax7OM6vOdDQ1_zZyinbpTlh0D8,5431
+jwtlint/parser.py,sha256=Jj6WTYBoLwrgTI8l5wVTNBVMf3j9rgl0Qe1puD__aSQ,3321
+jwtlint/wordlist.py,sha256=ZmeKmXMmHw4BqG3ukYqPOHQB4F1zPvBdX3CEuC2wuWI,1278
+jwtlint/checks/__init__.py,sha256=fME76sMA_5xyZyDiF_vwWz3UNM8DAVcnYEEpjBIFNBk,1062
+jwtlint/checks/alg_confusion.py,sha256=fFcvHOo2yo7BqyqWAGjtumBNvRY5fdlHauPZHke6txA,3456
+jwtlint/checks/alg_none.py,sha256=lQxtmcsuC8hgt682dtRZ6EEjcEAtBIyn1dcsWvfJOEY,2292
+jwtlint/checks/base.py,sha256=j4eqrs5RP8Je_mxFqgM8IdGQevZ1VsF8HyciyVVZB_s,785
+jwtlint/checks/claims.py,sha256=XTwhpOda43KPUsKQUOrjajvLVoNafTk5Hi0-kslYkM8,5569
+jwtlint/checks/crack.py,sha256=dvdNRWn2Zm36rPYPklw9U3vAvlGUfSesiwHxQ4QDY-Q,3358
+jwtlint/checks/header_injection.py,sha256=xXZN2sjHebtJ54adAAhkdP1SCGBKxTnCNKcVrzX25Ag,5065
+jwtlint/checks/sensitive.py,sha256=vsxlGVy02D2wf-Eqww1X5sjlVKScEiHhxN5RwRap6qk,3554
+jwtlint-0.2.0.dist-info/licenses/LICENSE,sha256=SEdP_gAHRti-TMtzheXQfj2LIyT4MefoS7rOSb06f6g,1071
+jwtlint-0.2.0.dist-info/METADATA,sha256=UVY4mLvHIGD9tOUrsp_DuKLTyECUHicqCU47awaO-dI,5704
+jwtlint-0.2.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+jwtlint-0.2.0.dist-info/entry_points.txt,sha256=_f47NOkKl5PefboTv1_whkKZ7WUQGyrWkbSFO94QtYU,45
+jwtlint-0.2.0.dist-info/top_level.txt,sha256=I20O2br316iyv9ClvYKvD1YIQiSWOaCk3Urq4HF-mjs,8
+jwtlint-0.2.0.dist-info/RECORD,,

jwtlint-0.2.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

jwtlint-0.2.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+jwtlint = jwtlint.cli:main

jwtlint-0.2.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Baran Ayaztaş
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

jwtlint-0.2.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+jwtlint