/sast-jwt

name: sast-jwt
description: >-
  Detect insecure JWT (JSON Web Token) implementations in a codebase using a
  two-phase approach: first map all JWT issuance and verification sites to
  understand the token lifecycle and signing configuration, then check each
  verification site for exploitable weaknesses such as algorithm confusion,
  missing signature verification, weak secrets, header injection, and missing
  claim validation. Requires sast/architecture.md (run sast-analysis first).
  Outputs findings to sast/jwt-results.md. If no JWT usage is found in Phase 1,
  Phase 2 is skipped. Use when asked to find JWT, token forgery, or
  authentication bypass bugs.

JWT Vulnerability Detection

You are performing a focused security assessment to find insecure JSON Web Token (JWT) implementations. This skill uses a two-phase approach with subagents: **recon** (map the full JWT lifecycle — issuance, verification, and configuration) then **analysis** (identify every exploitable weakness in those verification sites).

**Prerequisites**: `sast/architecture.md` must exist. Run the analysis skill first if it doesn't.

---

What is an Insecure JWT Implementation

JWTs consist of three Base64URL-encoded parts: `header.payload.signature`. The header declares the signing algorithm (`alg`), the payload carries claims (e.g., `sub`, `role`, `exp`), and the signature is a cryptographic proof of integrity. Vulnerabilities arise when the server trusts the token's own claims about how it was signed, fails to verify the signature at all, uses a guessable secret, or trusts attacker-controlled key material embedded in the token itself.

The core pattern: *the server does not fully verify the JWT's authenticity and integrity before trusting its claims.*

What JWT Vulnerabilities ARE

**1. Algorithm confusion — `alg: none`** The server accepts a JWT whose header declares `"alg": "none"`, bypassing signature verification entirely. An attacker crafts an arbitrary payload, sets `alg` to `none`, and omits the signature. If the library processes it, the forged token is accepted.

**2. Algorithm confusion — RS256 → HS256** A server configured for RS256 (asymmetric: sign with private key, verify with public key) can be tricked into HS256 mode if the library allows the algorithm to be specified by the token. Since the public key is often retrievable, the attacker signs a forged token with HS256 using the server's public key as the HMAC secret. The server verifies the HMAC using the same public key and accepts the token.

**3. Missing or disabled signature verification** The server decodes the JWT payload without actually verifying the signature. Common patterns:

• Python (PyJWT): `jwt.decode(token, options={"verify_signature": False})`
• Node.js (jsonwebtoken): `jwt.decode(token)` instead of `jwt.verify(token, secret)`
• Manual base64 decode of the payload with no signature check
• `algorithms=["none"]` accepted in the decode call

**4. Weak or hardcoded HMAC secret** The server signs tokens with a short, guessable, or hardcoded secret (e.g., `"secret"`, `"password"`, `"changeme"`, `"jwt-secret-key"`). An attacker who captures a valid token can brute-force the secret offline with tools like `hashcat` or `jwt_tool`, then forge arbitrary tokens.

**5. Embedded JWK (`jwk` header injection)** The token header contains an embedded JSON Web Key (`jwk` parameter). If the verification code trusts the embedded key to verify the token's own signature, an attacker generates their own key pair, signs a forged token with their private key, and embeds their public key in the header. The server verifies the signature using the attacker's embedded public key and accepts the token.

**6. JKU / X5U header injection** The `jku` (JWK Set URL) or `x5u` (X.509 certificate URL) header value is used to fetch the verification key from a URL. If the server does not validate the URL against an allowlist, the attacker can point it to their own server hosting a crafted key set.

**7. Key ID (`kid`) header injection** The `kid` header is used to look up the signing key, often from a database or the filesystem. If the `kid` value is interpolated into a SQL query without sanitization, it becomes an SQL injection vector. If it is concatenated into a file path, it becomes a path traversal vector.

**8. Missing claim validation**

• `exp` not checked → expired tokens remain valid forever
• `iss` (issuer) not checked → tokens issued by other services are accepted
• `aud` (audience) not checked → tokens intended for other services are accepted
• `nbf` (not-before) not checked → tokens used before their valid window

**9. No token revocation** There is no token blacklist or revocation mechanism. Stolen or logged-out tokens remain valid until they expire. This matters most when token lifetimes are long.

What JWT Vulnerabilities are NOT

Do not flag these as JWT vulnerabilities:

• **IDOR**: Changing a `user_id` claim to access another user's data is an authorization flaw, not a JWT forgery — only flag if the token itself can be forged
• **XSS via JWT payload**: Injecting `<script>` into a claim that is later rendered unescaped — that's XSS, not a JWT bug
• **CSRF**: JWT in cookies without `SameSite` — that's a CSRF concern, not a JWT integrity issue
• **Properly restricted verification**: `jwt.verify(token, secret, { algorithms: ['HS256'] })` with a strong secret — not vulnerable

Patterns That Prevent JWT Vulnerabilities

**1. Algorithm allowlist in verification call**

# Python — PyJWT: explicitly specify allowed algorithms
payload = jwt.decode(token, secret, algorithms=["HS256"])

# Node.js — jsonwebtoken: restrict algorithms
jwt.verify(token, secret, { algorithms: ['HS256'] })

# Java — jjwt: specify expected algorithm
Jwts.parserBuilder().setSigningKey(key).build().parseClaimsJws(token)
# (jjwt does not use the header's alg; it uses the key type)

**2. Strong, randomly generated secret**

# Strong secret: at le