Skip to content

TLS fingerprinting enablement #7325

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
gtriggiano wants to merge 3 commits into
base: main
Choose a base branch
from
Open

TLS fingerprinting enablement #7325

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
40bf1ce
Enable TLS Fingerprinting
gtriggiano Dec 2, 2025
39885d7
refactor: simplify parameters in secureProxyProtocol function
gtriggiano Dec 2, 2025
0ba5900
refactor: implement different toggles for JA3/JA4 enablements
gtriggiano Dec 3, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
18 changes: 18 additions & 0 deletions apis/projectcontour/v1alpha1/contourconfig.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -508,6 +508,24 @@ type EnvoyTLS struct {
// Note: This list is a superset of what is valid for stock Envoy builds and those using BoringSSL FIPS.
// +optional
CipherSuites []string `json:"cipherSuites,omitempty"`

// EnableJA3Fingerprinting enables JA3 TLS fingerprinting in the
// TLS Inspector listener filter. When enabled, Envoy will extract JA3
// fingerprints from TLS client hellos.
// Note: JA3 fingerprinting requires Envoy 1.21.0 or later.
//
// Contour's default is false.
// +optional
EnableJA3Fingerprinting *bool `json:"enableJA3Fingerprinting,omitempty"`

// EnableJA4Fingerprinting enables JA4 TLS fingerprinting in the
// TLS Inspector listener filter. When enabled, Envoy will extract JA4
// fingerprints from TLS client hellos.
// Note: JA4 fingerprinting requires Envoy 1.35.0 or later.
//
// Contour's default is false.
// +optional
EnableJA4Fingerprinting *bool `json:"enableJA4Fingerprinting,omitempty"`
}

// EnvoyListener defines parameters for an Envoy Listener.
Expand Down
10 changes: 10 additions & 0 deletions apis/projectcontour/v1alpha1/zz_generated.deepcopy.go
View file
Open in desktop

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

5 changes: 5 additions & 0 deletions cmd/contour/serve.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -138,6 +138,9 @@ func registerServe(app *kingpin.Application) (*kingpin.CmdClause, *serveContext)
serve.Flag("disable-feature", "Do not start an informer for the specified resources.").PlaceHolder("<extensionservices,tlsroutes,grpcroutes,tcproutes,backendtlspolicies>").EnumsVar(&ctx.disabledFeatures, "extensionservices", "tlsroutes", "grpcroutes", "tcproutes", "backendtlspolicies")
serve.Flag("disable-leader-election", "Disable leader election mechanism.").BoolVar(&ctx.LeaderElection.Disable)

serve.Flag("enable-ja3-fingerprinting", "Enable JA3 fingerprinting in the TLS Inspector filter (requires Envoy 1.21.0+).").BoolVar(&ctx.enableJA3Fingerprinting)
serve.Flag("enable-ja4-fingerprinting", "Enable JA4 fingerprinting in the TLS Inspector filter (requires Envoy 1.35.0+).").BoolVar(&ctx.enableJA4Fingerprinting)
Comment on lines +141 to +142
Copy link
Member

@tsaarni tsaarni Dec 5, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thank you @gtriggiano for your contribution!

I haven’t had a chance to look into this topic yet, but one quick note, something you’ve probably noticed yourself also since I saw you added config file and CRD support: we now generally avoid adding new command-line switches unless absolutely necessary, and we prefer using the config file and ContourConfiguration instead. I think we don't need to add command line flags for this one.


serve.Flag("envoy-http-access-log", "Envoy HTTP access log.").PlaceHolder("/path/to/file").StringVar(&ctx.httpAccessLog)
serve.Flag("envoy-https-access-log", "Envoy HTTPS access log.").PlaceHolder("/path/to/file").StringVar(&ctx.httpsAccessLog)
serve.Flag("envoy-service-http-address", "Kubernetes Service address for HTTP requests.").PlaceHolder("<ipaddr>").StringVar(&ctx.httpAddr)
Expand Down Expand Up @@ -444,6 +447,8 @@ func (s *Server) doServe() error {
listenerConfig := xdscache_v3.ListenerConfig{
Compression: contourConfiguration.Envoy.Listener.Compression,
UseProxyProto: *contourConfiguration.Envoy.Listener.UseProxyProto,
EnableJA3Fingerprinting: *contourConfiguration.Envoy.Listener.TLS.EnableJA3Fingerprinting,
EnableJA4Fingerprinting: *contourConfiguration.Envoy.Listener.TLS.EnableJA4Fingerprinting,
HTTPAccessLog: contourConfiguration.Envoy.HTTPListener.AccessLog,
HTTPSAccessLog: contourConfiguration.Envoy.HTTPSListener.AccessLog,
AccessLogType: contourConfiguration.Envoy.Logging.AccessLogFormat,
Expand Down
12 changes: 8 additions & 4 deletions cmd/contour/servecontext.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -75,7 +75,9 @@ type serveContext struct {
statsPort int

// envoy's listener parameters
useProxyProto bool
useProxyProto bool
enableJA3Fingerprinting bool
enableJA4Fingerprinting bool

// envoy's http listener parameters
httpAddr string
Expand Down Expand Up @@ -558,9 +560,11 @@ func (ctx *serveContext) convertToContourConfigurationSpec() contour_v1alpha1.Co
HTTP2MaxConcurrentStreams: ctx.Config.Listener.HTTP2MaxConcurrentStreams,
MaxConnectionsPerListener: ctx.Config.Listener.MaxConnectionsPerListener,
TLS: &contour_v1alpha1.EnvoyTLS{
MinimumProtocolVersion: ctx.Config.TLS.MinimumProtocolVersion,
MaximumProtocolVersion: ctx.Config.TLS.MaximumProtocolVersion,
CipherSuites: cipherSuites,
MinimumProtocolVersion: ctx.Config.TLS.MinimumProtocolVersion,
MaximumProtocolVersion: ctx.Config.TLS.MaximumProtocolVersion,
CipherSuites: cipherSuites,
EnableJA3Fingerprinting: &ctx.enableJA3Fingerprinting,
EnableJA4Fingerprinting: &ctx.enableJA4Fingerprinting,
},
SocketOptions: &contour_v1alpha1.SocketOptions{
TOS: ctx.Config.Listener.SocketOptions.TOS,
Expand Down
6 changes: 4 additions & 2 deletions cmd/contour/servecontext_test.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -411,8 +411,10 @@ func defaultContourConfiguration() contour_v1alpha1.ContourConfigurationSpec {
DisableMergeSlashes: ptr.To(false),
ServerHeaderTransformation: contour_v1alpha1.OverwriteServerHeader,
TLS: &contour_v1alpha1.EnvoyTLS{
MinimumProtocolVersion: "",
MaximumProtocolVersion: "",
MinimumProtocolVersion: "",
MaximumProtocolVersion: "",
EnableJA3Fingerprinting: ptr.To(false),
EnableJA4Fingerprinting: ptr.To(false),
},
SocketOptions: &contour_v1alpha1.SocketOptions{
TOS: 0,
Expand Down
64 changes: 64 additions & 0 deletions examples/contour/01-crds.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -200,6 +200,22 @@ spec:
items:
type: string
type: array
enableJA3Fingerprinting:
description: |-
EnableJA3Fingerprinting enables JA3 TLS fingerprinting in the
TLS Inspector listener filter. When enabled, Envoy will extract JA3
fingerprints from TLS client hellos.
Note: JA3 fingerprinting requires Envoy 1.21.0 or later.
Contour's default is false.
type: boolean
enableJA4Fingerprinting:
description: |-
EnableJA4Fingerprinting enables JA4 TLS fingerprinting in the
TLS Inspector listener filter. When enabled, Envoy will extract JA4
fingerprints from TLS client hellos.
Note: JA4 fingerprinting requires Envoy 1.35.0 or later.
Contour's default is false.
type: boolean
maximumProtocolVersion:
description: |-
MaximumProtocolVersion is the maximum TLS version this vhost should
Expand Down Expand Up @@ -438,6 +454,22 @@ spec:
items:
type: string
type: array
enableJA3Fingerprinting:
description: |-
EnableJA3Fingerprinting enables JA3 TLS fingerprinting in the
TLS Inspector listener filter. When enabled, Envoy will extract JA3
fingerprints from TLS client hellos.
Note: JA3 fingerprinting requires Envoy 1.21.0 or later.
Contour's default is false.
type: boolean
enableJA4Fingerprinting:
description: |-
EnableJA4Fingerprinting enables JA4 TLS fingerprinting in the
TLS Inspector listener filter. When enabled, Envoy will extract JA4
fingerprints from TLS client hellos.
Note: JA4 fingerprinting requires Envoy 1.35.0 or later.
Contour's default is false.
type: boolean
maximumProtocolVersion:
description: |-
MaximumProtocolVersion is the maximum TLS version this vhost should
Expand Down Expand Up @@ -4147,6 +4179,22 @@ spec:
items:
type: string
type: array
enableJA3Fingerprinting:
description: |-
EnableJA3Fingerprinting enables JA3 TLS fingerprinting in the
TLS Inspector listener filter. When enabled, Envoy will extract JA3
fingerprints from TLS client hellos.
Note: JA3 fingerprinting requires Envoy 1.21.0 or later.
Contour's default is false.
type: boolean
enableJA4Fingerprinting:
description: |-
EnableJA4Fingerprinting enables JA4 TLS fingerprinting in the
TLS Inspector listener filter. When enabled, Envoy will extract JA4
fingerprints from TLS client hellos.
Note: JA4 fingerprinting requires Envoy 1.35.0 or later.
Contour's default is false.
type: boolean
maximumProtocolVersion:
description: |-
MaximumProtocolVersion is the maximum TLS version this vhost should
Expand Down Expand Up @@ -4385,6 +4433,22 @@ spec:
items:
type: string
type: array
enableJA3Fingerprinting:
description: |-
EnableJA3Fingerprinting enables JA3 TLS fingerprinting in the
TLS Inspector listener filter. When enabled, Envoy will extract JA3
fingerprints from TLS client hellos.
Note: JA3 fingerprinting requires Envoy 1.21.0 or later.
Contour's default is false.
type: boolean
enableJA4Fingerprinting:
description: |-
EnableJA4Fingerprinting enables JA4 TLS fingerprinting in the
TLS Inspector listener filter. When enabled, Envoy will extract JA4
fingerprints from TLS client hellos.
Note: JA4 fingerprinting requires Envoy 1.35.0 or later.
Contour's default is false.
type: boolean
maximumProtocolVersion:
description: |-
MaximumProtocolVersion is the maximum TLS version this vhost should
Expand Down
64 changes: 64 additions & 0 deletions examples/render/contour-deployment.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -419,6 +419,22 @@ spec:
items:
type: string
type: array
enableJA3Fingerprinting:
description: |-
EnableJA3Fingerprinting enables JA3 TLS fingerprinting in the
TLS Inspector listener filter. When enabled, Envoy will extract JA3
fingerprints from TLS client hellos.
Note: JA3 fingerprinting requires Envoy 1.21.0 or later.
Contour's default is false.
type: boolean
enableJA4Fingerprinting:
description: |-
EnableJA4Fingerprinting enables JA4 TLS fingerprinting in the
TLS Inspector listener filter. When enabled, Envoy will extract JA4
fingerprints from TLS client hellos.
Note: JA4 fingerprinting requires Envoy 1.35.0 or later.
Contour's default is false.
type: boolean
maximumProtocolVersion:
description: |-
MaximumProtocolVersion is the maximum TLS version this vhost should
Expand Down Expand Up @@ -657,6 +673,22 @@ spec:
items:
type: string
type: array
enableJA3Fingerprinting:
description: |-
EnableJA3Fingerprinting enables JA3 TLS fingerprinting in the
TLS Inspector listener filter. When enabled, Envoy will extract JA3
fingerprints from TLS client hellos.
Note: JA3 fingerprinting requires Envoy 1.21.0 or later.
Contour's default is false.
type: boolean
enableJA4Fingerprinting:
description: |-
EnableJA4Fingerprinting enables JA4 TLS fingerprinting in the
TLS Inspector listener filter. When enabled, Envoy will extract JA4
fingerprints from TLS client hellos.
Note: JA4 fingerprinting requires Envoy 1.35.0 or later.
Contour's default is false.
type: boolean
maximumProtocolVersion:
description: |-
MaximumProtocolVersion is the maximum TLS version this vhost should
Expand Down Expand Up @@ -4366,6 +4398,22 @@ spec:
items:
type: string
type: array
enableJA3Fingerprinting:
description: |-
EnableJA3Fingerprinting enables JA3 TLS fingerprinting in the
TLS Inspector listener filter. When enabled, Envoy will extract JA3
fingerprints from TLS client hellos.
Note: JA3 fingerprinting requires Envoy 1.21.0 or later.
Contour's default is false.
type: boolean
enableJA4Fingerprinting:
description: |-
EnableJA4Fingerprinting enables JA4 TLS fingerprinting in the
TLS Inspector listener filter. When enabled, Envoy will extract JA4
fingerprints from TLS client hellos.
Note: JA4 fingerprinting requires Envoy 1.35.0 or later.
Contour's default is false.
type: boolean
maximumProtocolVersion:
description: |-
MaximumProtocolVersion is the maximum TLS version this vhost should
Expand Down Expand Up @@ -4604,6 +4652,22 @@ spec:
items:
type: string
type: array
enableJA3Fingerprinting:
description: |-
EnableJA3Fingerprinting enables JA3 TLS fingerprinting in the
TLS Inspector listener filter. When enabled, Envoy will extract JA3
fingerprints from TLS client hellos.
Note: JA3 fingerprinting requires Envoy 1.21.0 or later.
Contour's default is false.
type: boolean
enableJA4Fingerprinting:
description: |-
EnableJA4Fingerprinting enables JA4 TLS fingerprinting in the
TLS Inspector listener filter. When enabled, Envoy will extract JA4
fingerprints from TLS client hellos.
Note: JA4 fingerprinting requires Envoy 1.35.0 or later.
Contour's default is false.
type: boolean
maximumProtocolVersion:
description: |-
MaximumProtocolVersion is the maximum TLS version this vhost should
Expand Down
Loading
Loading