api: drop csrf enforcedFraction in favour of shadowFraction

Partially enforcing an origin check is not a useful security posture: with
enforcedFraction below 100% a fraction of cross-site mutating requests is let
through unvalidated and unobserved. The legitimate use case behind the knob is
dry running the filter before turning it on, which shadowFraction already
covers, so drop enforcedFraction and make shadowFraction the single rollout
control.

Envoy only lets an invalid request through in shadow mode if that request was
not also selected by filter_enabled, so filter_enabled is now derived as the
complement of the shadow fraction. Every request is therefore either enforced
or observed, never neither, and a shadow fraction of 100% is a complete dry
run instead of a no-op.

Signed-off-by: Huabing (Robin) Zhao <zhaohuabing@gmail.com>

Author: zhaohuabing

api/v1alpha1/csrf_types.go

@@ -21,21 +21,16 @@ import (
 //
 // +kubebuilder:validation:XValidation:message="additionalOrigins must be host or host:port values without a scheme or path, for example www.example.com instead of https://www.example.com",rule="!has(self.additionalOrigins) || self.additionalOrigins.all(o, !o.value.contains('/'))"
 type CSRF struct {
-	// EnforcedFraction represents the fraction of requests for which the CSRF
-	// policy is enforced. Requests that are not selected are allowed through
-	// without any origin validation.
-	// Defaults to 100% (all requests are enforced) if not specified.
+	// ShadowFraction represents the fraction of requests for which the CSRF policy is
+	// evaluated in shadow (dry-run) mode. For these requests, the filter records whether
+	// the request would have been allowed or rejected in the `csrf.request_valid` and
+	// `csrf.request_invalid` stats, but always lets the request through. The remaining
+	// requests are enforced, i.e. a mutating request with a missing or non-matching
+	// Origin header is rejected with a 403.
 	//
-	// +optional
-	EnforcedFraction *gwapiv1.Fraction `json:"enforcedFraction,omitempty"`
-
-	// ShadowFraction represents the fraction of requests for which the CSRF
-	// policy is evaluated in shadow (dry-run) mode. In this mode, the filter
-	// evaluates requests and tracks whether they would be allowed or rejected in
-	// the `csrf.request_invalid` and `csrf.request_valid` stats, but does not
-	// enforce the policy. This is useful for rolling out CSRF protection
-	// gradually while monitoring the impact.
-	// Only takes effect for requests that are not selected by EnforcedFraction.
+	// Defaults to 0% (all requests are enforced) if not specified. Set it to 100% to
+	// dry run the filter, watch the stats to find origins that would be rejected, then
+	// lower it to roll enforcement out gradually.
 	//
 	// +optional
 	ShadowFraction *gwapiv1.Fraction `json:"shadowFraction,omitempty"`

api/v1alpha1/zz_generated.deepcopy.go

@@ -730,37 +730,18 @@ spec:
                       type: object
                     maxItems: 16
                     type: array
-                  enforcedFraction:
-                    description: |-
-                      EnforcedFraction represents the fraction of requests for which the CSRF
-                      policy is enforced. Requests that are not selected are allowed through
-                      without any origin validation.
-                      Defaults to 100% (all requests are enforced) if not specified.
-                    properties:
-                      denominator:
-                        default: 100
-                        format: int32
-                        minimum: 1
-                        type: integer
-                      numerator:
-                        format: int32
-                        minimum: 0
-                        type: integer
-                    required:
-                    - numerator
-                    type: object
-                    x-kubernetes-validations:
-                    - message: numerator must be less than or equal to denominator
-                      rule: self.numerator <= self.denominator
                   shadowFraction:
                     description: |-
-                      ShadowFraction represents the fraction of requests for which the CSRF
-                      policy is evaluated in shadow (dry-run) mode. In this mode, the filter
-                      evaluates requests and tracks whether they would be allowed or rejected in
-                      the `csrf.request_invalid` and `csrf.request_valid` stats, but does not
-                      enforce the policy. This is useful for rolling out CSRF protection
-                      gradually while monitoring the impact.
-                      Only takes effect for requests that are not selected by EnforcedFraction.
+                      ShadowFraction represents the fraction of requests for which the CSRF policy is
+                      evaluated in shadow (dry-run) mode. For these requests, the filter records whether
+                      the request would have been allowed or rejected in the `csrf.request_valid` and
+                      `csrf.request_invalid` stats, but always lets the request through. The remaining
+                      requests are enforced, i.e. a mutating request with a missing or non-matching
+                      Origin header is rejected with a 403.
+
+                      Defaults to 0% (all requests are enforced) if not specified. Set it to 100% to
+                      dry run the filter, watch the stats to find origins that would be rejected, then
+                      lower it to roll enforcement out gradually.
                     properties:
                       denominator:
                         default: 100

charts/gateway-crds-helm/templates/generated/gateway.envoyproxy.io_securitypolicies.yaml

@@ -729,37 +729,18 @@ spec:
                       type: object
                     maxItems: 16
                     type: array
-                  enforcedFraction:
-                    description: |-
-                      EnforcedFraction represents the fraction of requests for which the CSRF
-                      policy is enforced. Requests that are not selected are allowed through
-                      without any origin validation.
-                      Defaults to 100% (all requests are enforced) if not specified.
-                    properties:
-                      denominator:
-                        default: 100
-                        format: int32
-                        minimum: 1
-                        type: integer
-                      numerator:
-                        format: int32
-                        minimum: 0
-                        type: integer
-                    required:
-                    - numerator
-                    type: object
-                    x-kubernetes-validations:
-                    - message: numerator must be less than or equal to denominator
-                      rule: self.numerator <= self.denominator
                   shadowFraction:
                     description: |-
-                      ShadowFraction represents the fraction of requests for which the CSRF
-                      policy is evaluated in shadow (dry-run) mode. In this mode, the filter
-                      evaluates requests and tracks whether they would be allowed or rejected in
-                      the `csrf.request_invalid` and `csrf.request_valid` stats, but does not
-                      enforce the policy. This is useful for rolling out CSRF protection
-                      gradually while monitoring the impact.
-                      Only takes effect for requests that are not selected by EnforcedFraction.
+                      ShadowFraction represents the fraction of requests for which the CSRF policy is
+                      evaluated in shadow (dry-run) mode. For these requests, the filter records whether
+                      the request would have been allowed or rejected in the `csrf.request_valid` and
+                      `csrf.request_invalid` stats, but always lets the request through. The remaining
+                      requests are enforced, i.e. a mutating request with a missing or non-matching
+                      Origin header is rejected with a 403.
+
+                      Defaults to 0% (all requests are enforced) if not specified. Set it to 100% to
+                      dry run the filter, watch the stats to find origins that would be rejected, then
+                      lower it to roll enforcement out gradually.
                     properties:
                       denominator:
                         default: 100

charts/gateway-helm/charts/crds/crds/generated/gateway.envoyproxy.io_securitypolicies.yaml

@@ -1758,7 +1758,6 @@ func (t *Translator) buildCSRF(csrf *egv1a1.CSRF) *ir.CSRF {
 		additionalOrigins = append(additionalOrigins, irStringMatch("csrf", origin))
 	}
 	return &ir.CSRF{
-		EnforcedFraction:  csrf.EnforcedFraction,
 		ShadowFraction:    csrf.ShadowFraction,
 		AdditionalOrigins: additionalOrigins,
 	}

internal/gatewayapi/securitypolicy.go

@@ -10,8 +10,6 @@ securityPolicies:
       kind: HTTPRoute
       name: httproute-1
     csrf:
-      enforcedFraction:
-        numerator: 80
       shadowFraction:
         numerator: 20
       additionalOrigins:

internal/gatewayapi/testdata/securitypolicy-with-csrf.in.yaml

@@ -112,8 +112,6 @@ securityPolicies:
         value: .trusted.com
       - type: RegularExpression
         value: .*\.partner\.com$
-      enforcedFraction:
-        numerator: 80
       shadowFraction:
         numerator: 20
     targetRef:
@@ -227,8 +225,6 @@ xdsIR:
             - distinct: false
               name: csrf
               safeRegex: .*\.partner\.com$
-            enforcedFraction:
-              numerator: 80
             shadowFraction:
               numerator: 20
     readyListener:

internal/gatewayapi/testdata/securitypolicy-with-csrf.out.yaml

@@ -1232,10 +1232,8 @@ type CORS struct {
 //
 // +k8s:deepcopy-gen=true
 type CSRF struct {
-	// EnforcedFraction is the fraction of requests for which CSRF is enforced.
-	// nil means 100%.
-	EnforcedFraction *gwapiv1.Fraction `json:"enforcedFraction,omitempty" yaml:"enforcedFraction,omitempty"`
 	// ShadowFraction is the fraction of requests evaluated in shadow/dry-run mode.
+	// The remaining requests are enforced. nil means 0%, i.e. everything is enforced.
 	ShadowFraction *gwapiv1.Fraction `json:"shadowFraction,omitempty" yaml:"shadowFraction,omitempty"`
 	// AdditionalOrigins specifies additional origins that are allowed.
 	AdditionalOrigins []*StringMatch `json:"additionalOrigins,omitempty" yaml:"additionalOrigins,omitempty"`

internal/ir/xds.go

@@ -14,6 +14,8 @@ import (
 	csrfv3 "github.com/envoyproxy/go-control-plane/envoy/extensions/filters/http/csrf/v3"
 	hcmv3 "github.com/envoyproxy/go-control-plane/envoy/extensions/filters/network/http_connection_manager/v3"
 	"google.golang.org/protobuf/types/known/anypb"
+	"k8s.io/utils/ptr"
+	gwapiv1 "sigs.k8s.io/gateway-api/apis/v1"
 
 	"github.com/envoyproxy/gateway/internal/ir"
 	"github.com/envoyproxy/gateway/internal/xds/types"
@@ -142,22 +144,24 @@ func (*csrf) patchResources(*types.ResourceVersionTable, []*ir.HTTPRoute) error
 
 // buildXdsCSRFPolicy builds the full Envoy CSRF policy from the IR.
 func buildXdsCSRFPolicy(csrf *ir.CSRF) *csrfv3.CsrfPolicy {
-	// Default to 100% enforced.
+	// Envoy only lets an invalid request through in shadow mode if that request wasn't
+	// also selected by FilterEnabled, so enforcement is set to the complement of the
+	// shadow fraction: every request is either enforced or observed, never neither.
+	// With no shadow fraction, all requests are enforced.
 	enforcedFraction := fractionalpercent.FromIn32(100)
-	if csrf.EnforcedFraction != nil {
-		enforcedFraction = fractionalpercent.FromFraction(csrf.EnforcedFraction)
+	var shadowEnabled *corev3.RuntimeFractionalPercent
+	if csrf.ShadowFraction != nil {
+		enforcedFraction = fractionalpercent.FromFraction(complementFraction(csrf.ShadowFraction))
+		shadowEnabled = &corev3.RuntimeFractionalPercent{
+			DefaultValue: fractionalpercent.FromFraction(csrf.ShadowFraction),
+		}
 	}
 
 	policy := &csrfv3.CsrfPolicy{
 		FilterEnabled: &corev3.RuntimeFractionalPercent{
 			DefaultValue: enforcedFraction,
 		},
-	}
-
-	if csrf.ShadowFraction != nil {
-		policy.ShadowEnabled = &corev3.RuntimeFractionalPercent{
-			DefaultValue: fractionalpercent.FromFraction(csrf.ShadowFraction),
-		}
+		ShadowEnabled: shadowEnabled,
 	}
 
 	// Values are passed directly to Envoy without transformation. Users must provide
@@ -169,3 +173,13 @@ func buildXdsCSRFPolicy(csrf *ir.CSRF) *csrfv3.CsrfPolicy {
 
 	return policy
 }
+
+// complementFraction returns the remainder of the given fraction, i.e. 1 - fraction.
+// The numerator is never greater than the denominator, so the result is never negative.
+func complementFraction(fraction *gwapiv1.Fraction) *gwapiv1.Fraction {
+	denominator := ptr.Deref(fraction.Denominator, fractionalpercent.Hundred)
+	return &gwapiv1.Fraction{
+		Numerator:   denominator - fraction.Numerator,
+		Denominator: ptr.To(denominator),
+	}
+}