jwt

Documentation

Overview

Package jwt implements JWT (JSON Web Token) security analysis.

Source reference: jwt_tool (MIT, ticarpi) + jwt-auditor (MIT) + PortSwigger JWT attacks research + RFC 7519. Detection logic reimplemented from scratch.

JWT vulnerabilities detected:

1. "none" algorithm attack: modify header to alg=none, strip signature
2. Algorithm confusion (RS256→HS256): use public key as HMAC secret
3. Weak secret brute-force: try common/default secrets (HS256/384/512)
4. Empty password HS256: sign with empty string secret
5. Header injection: inject kid=/dev/null or jwk/jku pointing to attacker
6. Expiry analysis: token already expired, or very long-lived (> 30 days)
7. Sensitive claims: sub/email/admin/role fields in payload
8. Missing or weak algorithm in header

Input modes:

• Token via Options["token"]
• Token extracted from Authorization: Bearer header (from target URL response)
• Cookie values starting with "eyJ" (base64 JWT prefix)
• RawContent containing JWT-like strings

Architecture:

• Check struct: ID, Run func, Severity, Tags
• parseJWT: base64url decode header + payload (no signature verification)
• No external JWT libraries — pure stdlib base64/json
• errgroup.SetLimit(Parallelism) fan-out per check
• log/slog observability
• sync.Mutex protecting findings slice
• NewWithClient(*http.Client) for testability

Index

• Constants
• type Check
• type JWTHeader
• type JWTPayload
• type Module
  • func New() *Module
  • func NewWithClient(c *http.Client) *Module
  • func (m *Module) Name() string
  • func (m *Module) Run(ctx context.Context, input module.Input) ([]module.Finding, error)
• type ParsedJWT

Constants

const (
	DefaultTimeout     = 10 * time.Second
	DefaultParallelism = 10
)

Types

type Check

type Check struct {
	ID       string
	Severity module.Severity
	Tags     []string
	Run      func(ctx context.Context, parsed *ParsedJWT, target string) *module.Finding
}

Check defines a JWT security test.

type JWTHeader

type JWTHeader struct {
	Alg string      `json:"alg"`
	Typ string      `json:"typ"`
	Kid string      `json:"kid,omitempty"`
	Jwk interface{} `json:"jwk,omitempty"`
	Jku string      `json:"jku,omitempty"`
}

JWTHeader represents a decoded JWT header.

type JWTPayload

type JWTPayload struct {
	Sub string                     `json:"sub,omitempty"`
	Iss string                     `json:"iss,omitempty"`
	Aud interface{}                `json:"aud,omitempty"`
	Exp int64                      `json:"exp,omitempty"`
	Iat int64                      `json:"iat,omitempty"`
	Nbf int64                      `json:"nbf,omitempty"`
	JTI string                     `json:"jti,omitempty"`
	Raw map[string]json.RawMessage `json:"-"`
}

JWTPayload represents a decoded JWT payload.

type Module

type Module struct {
	// contains filtered or unexported fields
}

Module implements JWT security analysis.

func New

func New() *Module

New returns a Module with default settings.

func NewWithClient

func NewWithClient(c *http.Client) *Module

NewWithClient returns a Module using the supplied HTTP client.

func (*Module) Name

func (m *Module) Name() string

Name returns the module name.

func (*Module) Run

func (m *Module) Run(ctx context.Context, input module.Input) ([]module.Finding, error)

Run analyzes JWT tokens for security issues.

Options:

• "token" — explicit JWT to analyze
• "parallelism" — max concurrent checks (default: 10)

type ParsedJWT

type ParsedJWT struct {
	Raw        string
	Header     JWTHeader
	Payload    JWTPayload
	PayloadRaw map[string]interface{}
	Signature  string
}

ParsedJWT holds all decoded parts.