crowdsecurity/crowdsec · warning

allowlist reason exceeds maximum length

Error message

allowlist reason exceeds maximum length

What it means

ErrAllowlistReasonSize indicates the operator-supplied allowlist reason string embedded in a challenge cookie exceeds MaxAllowlistReasonLen. The reason travels inside every Set-Cookie/Cookie header, so sealCookieV0 rejects oversize reasons at seal time to guarantee the resulting cookie fits within the cookie size budget.

Source

Thrown at pkg/appsec/challenge/crypto.go:33

	"encoding/base64"
	"encoding/binary"
	"errors"
	"fmt"
	"time"

	"golang.org/x/crypto/hkdf"

	"github.com/crowdsecurity/crowdsec/pkg/appsec/challenge/pb"
	"google.golang.org/protobuf/proto"
)

var (
	ErrCookieMalformed     = errors.New("malformed cookie")
	ErrCookieSignature     = errors.New("invalid cookie signature")
	ErrCookiePayload       = errors.New("invalid cookie payload")
	ErrCookieExpired       = errors.New("cookie expired")
	ErrCookieVersion       = errors.New("unknown cookie version")
	ErrAllowlistReasonSize = errors.New("allowlist reason exceeds maximum length")
	ErrCookieTooLarge      = errors.New("cookie exceeds maximum size")
)

const hkdfInfo = "crowdsec-challenge-cookie"

// MaxAllowlistReasonLen caps the reason string operators pass to
// GrantChallengeCookie. The reason travels inside every Set-Cookie + Cookie
// header round-trip until the cookie expires; bounding it keeps the cookie
// well under the 4 KB browser limit even with the AES-GCM tag + base64
// expansion.
const MaxAllowlistReasonLen = 256

// MaxCookieLen is the DEFAULT per-cookie size (RFC 6265 §6.1: 4096 bytes).
// Can be configured via Config.MaxCookieSize and we reject anything bigger.
const MaxCookieLen = 4096

// Cookie wire format. A single version byte at offset 0 lets us evolve the
// format without flag-day-style cookie invalidation. New formats add a new

View on GitHub (pinned to 909b515798)

Solutions

1. Shorten the allowlist reason to at most MaxAllowlistReasonLen characters before granting the cookie.
2. Truncate or validate the reason at the API/UI boundary before calling GrantChallengeCookie.
3. Reference an external ID instead of embedding the full explanation (e.g. ticket number).

Example fix

// before
cookie, err := sealCookieV0(c, key, notAfter, flag, longReason, ua, maxLen)
// after
if len(reason) > challenge.MaxAllowlistReasonLen {
    reason = reason[:challenge.MaxAllowlistReasonLen]
}
cookie, err := sealCookieV0(c, key, notAfter, flag, reason, ua, maxLen)

if len(reason) > challenge.MaxAllowlistReasonLen {
    return fmt.Errorf("allowlist reason must be <= %d chars", challenge.MaxAllowlistReasonLen)
}

_, err := sealCookieV0(c, key, notAfter, flag, reason, ua, maxLen)
if err != nil {
    if errors.Is(err, challenge.ErrAllowlistReasonSize) {
        reason = reason[:challenge.MaxAllowlistReasonLen]
        _, err = sealCookieV0(c, key, notAfter, flag, reason, ua, maxLen)
    }
    return err
}

When it happens

Trigger: Calling sealCookieV0 (via GrantChallengeCookie) with a reason string longer than MaxAllowlistReasonLen; also exercised by TestCookieV0_AllowlistReasonTooLong, which passes an oversize string from keyring_integration_test.go:367.

Common situations: An operator pastes a long justification or URL into the allowlist reason field; automation generates verbose reasons; a misconfigured UI does not truncate the reason input.

Understand the failure class

Background: "value must be between 0 and 1" / "out of range" / "must not be negative" errors: fixing range-validation failures across open-source libraries — this error's family across 42 libraries.

Related errors

• ErrAllowlistReasonSize
• cookie exceeds maximum size
• invalid challenge cookie: %w
• ErrCookieTooLarge
• invalid schema name

AI-assisted analysis of crowdsecurity/crowdsec@909b515798 (2026-09-06). Data as JSON: /api/errors/095af37dc184202d. Report an issue: GitHub.