Module de.cuioss.http
Package de.cuioss.http.security.validation

Record Class PatternMatchingStage

java.lang.Object
java.lang.Record
de.cuioss.http.security.validation.PatternMatchingStage
Record Components:
config - Security configuration controlling validation behavior.
validationType - Type of validation being performed (URL_PATH, PARAMETER_NAME, etc.).
All Implemented Interfaces:
HttpSecurityValidator
public record PatternMatchingStage(SecurityConfiguration config, ValidationType validationType) extends Record implements HttpSecurityValidator
Pattern matching validation stage for detecting malicious attack patterns.

This stage performs comprehensive pattern-based security validation to detect known attack signatures, injection attempts, and suspicious content patterns. The stage analyzes input against multiple security pattern databases:

  1. Path Traversal Patterns - Detects directory traversal attempts
  2. Suspicious Protocol Patterns - Identifies protocol violations
  3. Suspicious Path Patterns - Detects access to sensitive system locations
  4. Parameter Attack Patterns - Identifies malicious parameter usage

Design Principles

  • Signature-Based Detection - Uses known attack patterns from OWASP and CVE databases
  • Configurable Sensitivity - Behavior controlled by failOnSuspiciousPatterns setting
  • Performance Optimized - Uses pre-compiled patterns and efficient string operations
  • Context Aware - Different pattern sets applied based on validation type

Security Validations

  • Path Traversal - ../,..\\, and encoded variants
  • Protocol Violations - Suspicious URI schemes and protocol handlers
  • File Access - Attempts to access sensitive system files
  • Parameter Pollution - Suspicious parameter names and patterns

Usage Examples

 // Create pattern matching stage
 SecurityConfiguration config = SecurityConfiguration.defaults();
 PatternMatchingStage matcher = new PatternMatchingStage(config, ValidationType.URL_PATH);

 // Detect path traversal attack
 try {
     matcher.validate("/api/users/../../../etc/passwd");
     // Throws UrlSecurityException with PATH_TRAVERSAL_DETECTED
 } catch (UrlSecurityException e) {
     logger.warn("Path traversal blocked: {}", e.getDetail());
 }

 // Path traversal detection
 try {
     matcher.validate("../../../etc/passwd");
 } catch (UrlSecurityException e) {
     logger.warn("Path traversal blocked: {}", e.getDetail());
 }

 // Configurable sensitivity
 SecurityConfiguration strict = SecurityConfiguration.strict(); // failOnSuspiciousPatterns=true
 PatternMatchingStage strictMatcher = new PatternMatchingStage(strict, ValidationType.PARAMETER_VALUE);

 // Legitimate content that might trigger in strict mode
 try {
     strictMatcher.validate("SELECT name FROM contacts WHERE id = 123");
     // May throw if configured to fail on suspicious patterns
 } catch (UrlSecurityException e) {
     // Handle based on security policy
 }

Performance Characteristics

  • O(n*m) time complexity where n = input length, m = number of patterns
  • Early termination on first pattern match
  • Optimized pattern order based on common attack frequency
  • Case-insensitive matching for broader attack detection

Configuration Dependencies

  • failOnSuspiciousPatterns - Controls whether to fail on pattern matches
  • caseSensitiveComparison - Affects pattern matching behavior
  • logSecurityViolations - Controls violation logging

Implements: Task V3 from HTTP verification specification

Since:
1.0
See Also:

  • Constructor Details

  • Method Details

    • validate

      public Optional<String> validate(@Nullable String value) throws UrlSecurityException
      Validates input against comprehensive attack pattern databases.

      Processing stages:

      1. Input validation - handles null/empty inputs
      2. Context-sensitive pattern selection - chooses appropriate patterns for validation type
      3. Pattern matching - tests against known attack signatures
      4. Policy enforcement - applies configured response to pattern matches
      Specified by:
      validate in interface HttpSecurityValidator
      Parameters:
      value - The input string to validate against attack patterns
      Returns:
      The original input wrapped in Optional if validation passes, or Optional.empty() if input was null
      Throws:
      UrlSecurityException - if malicious patterns are detected:
      • PATH_TRAVERSAL_DETECTED - if path traversal patterns found
      • SUSPICIOUS_PATTERN_DETECTED - if suspicious patterns found and policy requires failure

    • when

      public HttpSecurityValidator when(Predicate<String> condition)
      Creates a conditional validator that only processes inputs matching the condition.
      Specified by:
      when in interface HttpSecurityValidator
      Parameters:
      condition - The condition to test before validation
      Returns:
      A conditional HttpSecurityValidator that applies pattern matching conditionally

    • toString

      public final String toString()
      Returns a string representation of this record class. The representation contains the name of the class, followed by the name and value of each of the record components.
      Specified by:
      toString in class Record
      Returns:
      a string representation of this object

    • hashCode

      public final int hashCode()
      Returns a hash code value for this object. The value is derived from the hash code of each of the record components.
      Specified by:
      hashCode in class Record
      Returns:
      a hash code value for this object

    • equals

      public final boolean equals(Object o)
      Indicates whether some other object is "equal to" this one. The objects are equal if the other object is of the same class and if all the record components are equal. All components in this record class are compared with Objects::equals(Object,Object).
      Specified by:
      equals in class Record
      Parameters:
      o - the object with which to compare
      Returns:
      true if this object is the same as the o argument; false otherwise.

    • config

      public SecurityConfiguration config()
      Returns the value of the config record component.
      Returns:
      the value of the config record component

    • validationType

      public ValidationType validationType()
      Returns the value of the validationType record component.
      Returns:
      the value of the validationType record component