Add RuleFilter for dynamic rule skipping

Introduces the `types.RuleFilter` interface to allow custom, per-transaction logic for skipping rules based on their metadata.

Adds `Transaction.UseRuleFilter` to apply a filter instance and integrates the filter check at the beginning of the rule evaluation loop in `RuleGroup.Eval`. Includes associated unit tests.

Author: dokzlo13

internal/corazawaf/rulegroup.go

@@ -133,6 +133,16 @@ func (rg *RuleGroup) Eval(phase types.RulePhase, tx *Transaction) bool {
 RulesLoop:
 	for i := range rg.rules {
 		r := &rg.rules[i]
+		// Check if a specific rule filter is applied to this transaction
+		// and if the current rule should be ignored according to the filter.
+		if tx.ruleFilter != nil {
+			if tx.ruleFilter.ShouldIgnore(r) {
+				tx.DebugLogger().Debug().
+					Int("rule_id", r.ID_).
+					Msg("Skipping rule due to RulesFilter")
+				continue RulesLoop
+			}
+		}
 		// if there is already an interruption and the phase isn't logging
 		// we break the loop
 		if tx.interruption != nil && phase != types.PhaseLogging {
@@ -159,8 +169,7 @@ RulesLoop:
 			if trb == r.ID_ {
 				tx.DebugLogger().Debug().
 					Int("rule_id", r.ID_).
-					Msg("Skipping rule")
-
+					Msg("Skipping rule due to ruleRemoveByID")
 				continue RulesLoop
 			}
 		}

internal/corazawaf/rulegroup_test.go

@@ -4,9 +4,11 @@
 package corazawaf
 
 import (
+	"fmt"
 	"testing"
 
 	"github.com/corazawaf/coraza/v3/experimental/plugins/macro"
+	"github.com/corazawaf/coraza/v3/types"
 )
 
 func newTestRule(id int) *Rule {
@@ -85,3 +87,93 @@ func TestRuleGroupDeleteByID(t *testing.T) {
 		t.Fatal("Unexpected remaining rule in the rulegroup")
 	}
 }
+
+// RuleFilterWrapper provides a flexible way to define rule filtering logic for tests.
+type RuleFilterWrapper struct {
+	shouldIgnore func(rule types.RuleMetadata) bool
+}
+
+func (fw *RuleFilterWrapper) ShouldIgnore(rule types.RuleMetadata) bool {
+	if fw.shouldIgnore == nil {
+		return false // Default behavior: don't ignore if no function is provided
+	}
+	return fw.shouldIgnore(rule)
+}
+
+// TestRuleFilterInteraction confirms filter is checked first in Eval loop for all phases.
+func TestRuleFilterInteraction(t *testing.T) {
+	// --- Define Rule (Phase 0 to run in all phases) ---
+	rule := NewRule()
+	rule.ID_ = 1
+	rule.Phase_ = 0     // Phase 0: Always evaluate
+	rule.operator = nil // No operator means it always matches
+	if err := rule.AddAction("deny", &dummyDenyAction{}); err != nil {
+		t.Fatalf("Setup: Failed to add deny action: %v", err)
+	}
+
+	// --- Phases to Test ---
+	phasesToTest := []types.RulePhase{
+		types.PhaseRequestHeaders,
+		types.PhaseRequestBody,
+		types.PhaseResponseHeaders,
+		types.PhaseResponseBody,
+		types.PhaseLogging,
+	}
+
+	// --- Filter Actions ---
+	filterActions := []struct {
+		name               string
+		filterShouldIgnore bool
+		expectInterruption bool // Expect interruption only if filter *allows* the deny rule
+	}{
+		{
+			name:               "Rule Filtered",
+			filterShouldIgnore: true,
+			expectInterruption: false,
+		},
+		{
+			name:               "Rule Allowed",
+			filterShouldIgnore: false,
+			expectInterruption: true,
+		},
+	}
+
+	// --- Iterate through Phases ---
+	for _, currentPhase := range phasesToTest {
+		phaseTestName := fmt.Sprintf("Phase_%d", currentPhase)
+
+		t.Run(phaseTestName, func(t *testing.T) {
+			// --- Iterate through Filter Actions ---
+			for _, fa := range filterActions {
+				filterActionTestName := fa.name
+
+				t.Run(filterActionTestName, func(t *testing.T) {
+					waf := NewWAF()
+					if err := waf.Rules.Add(rule); err != nil {
+						t.Fatalf("Setup: Failed to add rule for %s/%s: %v", phaseTestName, filterActionTestName, err)
+					}
+					tx := waf.NewTransaction()
+
+					var filterCalled bool
+					testFilter := &RuleFilterWrapper{
+						shouldIgnore: func(r types.RuleMetadata) bool {
+							filterCalled = true
+							return fa.filterShouldIgnore
+						},
+					}
+					tx.UseRuleFilter(testFilter)
+
+					interrupted := waf.Rules.Eval(currentPhase, tx)
+					if interrupted != fa.expectInterruption {
+						t.Fatalf("[%s/%s] ShouldFilter is '%t', expecting interruption '%t', but Eval returned '%t'",
+							phaseTestName, filterActionTestName, fa.filterShouldIgnore, fa.expectInterruption, interrupted,
+						)
+					}
+					if !filterCalled {
+						t.Fatalf("[%s/%s] ShouldIgnore was *not* called", phaseTestName, filterActionTestName)
+					}
+				})
+			}
+		})
+	}
+}

internal/corazawaf/transaction.go

@@ -123,6 +123,10 @@ type Transaction struct {
 	variables TransactionVariables
 
 	transformationCache map[transformationKey]*transformationValue
+
+	// ruleFilter allows applying custom rule filtering logic per transaction.
+	// If set, it's used during rule evaluation to determine if a rule should be skipped.
+	ruleFilter types.RuleFilter
 }
 
 func (tx *Transaction) ID() string {
@@ -1598,6 +1602,13 @@ func (tx *Transaction) Close() error {
 	return fmt.Errorf("transaction close failed: %v", errors.Join(errs...))
 }
 
+// UseRuleFilter applies a RuleFilter to the transaction.
+// This filter will be consulted during rule evaluation in each phase
+// to determine if specific rules should be skipped for this transaction.
+func (tx *Transaction) UseRuleFilter(filter types.RuleFilter) {
+	tx.ruleFilter = filter
+}
+
 // String will return a string with the transaction debug information
 func (tx *Transaction) String() string {
 	res := strings.Builder{}

internal/corazawaf/waf.go

@@ -197,6 +197,7 @@ func (w *WAF) newTransaction(opts Options) *Transaction {
 	tx.debugLogger = w.Logger.With(debuglog.Str("tx_id", tx.id))
 	tx.Timestamp = time.Now().UnixNano()
 	tx.audit = false
+	tx.ruleFilter = nil
 
 	// Always non-nil if buffers / collections were already initialized so we don't do any of them
 	// based on the presence of RequestBodyBuffer.

types/rules.go

@@ -20,3 +20,12 @@ type RuleMetadata interface {
 	Raw() string
 	SecMark() string
 }
+
+// RuleFilter provides an interface for filtering rules during transaction processing.
+// Implementations can define custom logic to determine if a specific rule
+// should be ignored for a given transaction based on its metadata.
+type RuleFilter interface {
+	// ShouldIgnore evaluates the provided RuleMetadata and returns true if the rule
+	// should be skipped for the current transaction, false otherwise.
+	ShouldIgnore(RuleMetadata) bool
+}

types/transaction.go

@@ -196,6 +196,11 @@ type Transaction interface {
 	// ID returns the transaction ID.
 	ID() string
 
+	// UseRuleFilter applies a RuleFilter to the transaction.
+	// This filter will be consulted during rule evaluation in each phase
+	// to determine if specific rules should be skipped for this transaction.
+	UseRuleFilter(RuleFilter)
+
 	// Closer closes the transaction and releases any resources associated with it such as request/response bodies.
 	io.Closer
 }