001/* 002 * Copyright © 2025 CUI-OpenSource-Software (info@cuioss.de) 003 * 004 * Licensed under the Apache License, Version 2.0 (the "License"); 005 * you may not use this file except in compliance with the License. 006 * You may obtain a copy of the License at 007 * 008 * http://www.apache.org/licenses/LICENSE-2.0 009 * 010 * Unless required by applicable law or agreed to in writing, software 011 * distributed under the License is distributed on an "AS IS" BASIS, 012 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 013 * See the License for the specific language governing permissions and 014 * limitations under the License. 015 */ 016package de.cuioss.http.security.monitoring; 017 018import de.cuioss.tools.logging.LogRecord; 019import de.cuioss.tools.logging.LogRecordModel; 020 021/** 022 * Structured log messages for HTTP security validation events. 023 * 024 * <p>This class provides predefined, structured log messages for all types of HTTP security 025 * events that can occur during URL validation. It follows the CUI LogRecord pattern to ensure 026 * consistent, parseable, and actionable security logs.</p> 027 * 028 * <h3>Design Principles</h3> 029 * <ul> 030 * <li><strong>Structured Logging</strong> - All messages follow consistent format with identifiers</li> 031 * <li><strong>Security Focus</strong> - Messages designed for security monitoring and alerting</li> 032 * <li><strong>Actionable</strong> - Each message provides context needed for response</li> 033 * <li><strong>Standardized</strong> - Uses CUI LogRecord pattern for consistency</li> 034 * </ul> 035 * 036 * <h3>Message Categories</h3> 037 * <ul> 038 * <li><strong>WARN</strong> - Security violations that were blocked but indicate potential attacks</li> 039 * <li><strong>ERROR</strong> - Critical security failures or system errors during validation</li> 040 * <li><strong>INFO</strong> - Security-relevant events that don't indicate attacks</li> 041 * <li><strong>DEBUG</strong> - Detailed validation information for troubleshooting</li> 042 * </ul> 043 * 044 * <h3>Usage Examples</h3> 045 * <pre> 046 * // Log a path traversal attack 047 * logger.warn(URLSecurityLogMessages.WARN.PATH_TRAVERSAL_DETECTED.format("../../../etc/passwd")); 048 * 049 * // Log a validation failure with details 050 * logger.error(URLSecurityLogMessages.ERROR.VALIDATION_FAILED.format( 051 * "PATH_TRAVERSAL_DETECTED", "/api/../admin")); 052 * 053 * // Log configuration information 054 * logger.info(URLSecurityLogMessages.INFO.VALIDATION_ENABLED.format("PATH", "strict")); 055 * 056 * // Log detailed validation steps 057 * logger.debug(URLSecurityLogMessages.DEBUG.VALIDATION_STEP.format("DecodingStage", "url encoded")); 058 * </pre> 059 * 060 * <h3>Message Format</h3> 061 * <p>All messages follow the pattern: <code>URLSecurity-[ID]: [message with parameters]</code></p> 062 * <p>This format enables easy parsing by log analysis tools and SIEM systems for security monitoring.</p> 063 * 064 * Implements: Task S2 from HTTP verification specification 065 * 066 * @since 1.0 067 * @see LogRecord 068 * @see LogRecordModel 069 * @see SecurityEventCounter 070 */ 071public final class URLSecurityLogMessages { 072 073 /** 074 * Log message prefix for all URL security related messages. 075 */ 076 private static final String PREFIX = "URLSecurity"; 077 078 /** 079 * Private constructor to prevent instantiation of utility class. 080 */ 081 private URLSecurityLogMessages() { 082 // Utility class - no instances 083 } 084 085 /** 086 * Warning level messages for security violations that were detected and blocked. 087 * These messages indicate potential attacks that should be monitored and may trigger alerts. 088 */ 089 public static final class WARN { 090 091 /** 092 * Path traversal attack detected and blocked. 093 * Parameters: [0] = the malicious input that was detected 094 */ 095 public static final LogRecord PATH_TRAVERSAL_DETECTED = LogRecordModel.builder() 096 .prefix(PREFIX) 097 .identifier(301) 098 .template("Path traversal attempt detected and blocked: {}") 099 .build(); 100 101 /** 102 * Double encoding attack detected and blocked. 103 * Parameters: [0] = the double-encoded input that was detected 104 */ 105 public static final LogRecord DOUBLE_ENCODING_DETECTED = LogRecordModel.builder() 106 .prefix(PREFIX) 107 .identifier(302) 108 .template("Double encoding attack detected and blocked: {}") 109 .build(); 110 111 /** 112 * Unicode normalization attack detected and blocked. 113 * Parameters: [0] = the Unicode input, [1] = normalized form 114 */ 115 public static final LogRecord UNICODE_ATTACK_DETECTED = LogRecordModel.builder() 116 .prefix(PREFIX) 117 .identifier(303) 118 .template("Unicode normalization attack detected - Original: {}, Normalized: {}") 119 .build(); 120 121 /** 122 * Null byte injection attack detected and blocked. 123 * Parameters: [0] = the input containing null bytes 124 */ 125 public static final LogRecord NULL_BYTE_DETECTED = LogRecordModel.builder() 126 .prefix(PREFIX) 127 .identifier(304) 128 .template("Null byte injection detected and blocked: {}") 129 .build(); 130 131 /** 132 * Control character injection detected and blocked. 133 * Parameters: [0] = the input containing control characters 134 */ 135 public static final LogRecord CONTROL_CHARACTERS_DETECTED = LogRecordModel.builder() 136 .prefix(PREFIX) 137 .identifier(305) 138 .template("Control character injection detected and blocked: {}") 139 .build(); 140 141 /** 142 * Input length exceeded maximum allowed limits. 143 * Parameters: [0] = validation type, [1] = actual length, [2] = maximum allowed 144 */ 145 public static final LogRecord LENGTH_LIMIT_EXCEEDED = LogRecordModel.builder() 146 .prefix(PREFIX) 147 .identifier(306) 148 .template("{} length limit exceeded - Actual: {}, Maximum: {}") 149 .build(); 150 151 /** 152 * Suspicious pattern detected in input. 153 * Parameters: [0] = validation type, [1] = detected pattern, [2] = input 154 */ 155 public static final LogRecord SUSPICIOUS_PATTERN_DETECTED = LogRecordModel.builder() 156 .prefix(PREFIX) 157 .identifier(307) 158 .template("Suspicious pattern detected in {} - Pattern: {}, Input: {}") 159 .build(); 160 161 /** 162 * Known attack signature detected and blocked. 163 * Parameters: [0] = signature type, [1] = input that matched 164 */ 165 public static final LogRecord ATTACK_SIGNATURE_DETECTED = LogRecordModel.builder() 166 .prefix(PREFIX) 167 .identifier(308) 168 .template("Known attack signature detected - Type: {}, Input: {}") 169 .build(); 170 171 /** 172 * Malformed input structure detected. 173 * Parameters: [0] = validation type, [1] = description of malformation 174 */ 175 public static final LogRecord MALFORMED_INPUT_DETECTED = LogRecordModel.builder() 176 .prefix(PREFIX) 177 .identifier(309) 178 .template("Malformed {} input detected: {}") 179 .build(); 180 181 /** 182 * Rate limit exceeded for security violations. 183 * Parameters: [0] = failure type, [1] = current count, [2] = time window 184 */ 185 public static final LogRecord RATE_LIMIT_EXCEEDED = LogRecordModel.builder() 186 .prefix(PREFIX) 187 .identifier(310) 188 .template("Security violation rate limit exceeded - Type: {}, Count: {} in {}") 189 .build(); 190 191 private WARN() { 192 // Utility class - no instances 193 } 194 } 195 196 /** 197 * Error level messages for critical security failures or system errors during validation. 198 * These messages indicate serious problems that require immediate attention. 199 */ 200 public static final class ERROR { 201 202 /** 203 * URL validation failed due to security violation. 204 * Parameters: [0] = failure type, [1] = input that failed validation 205 */ 206 public static final LogRecord VALIDATION_FAILED = LogRecordModel.builder() 207 .prefix(PREFIX) 208 .identifier(401) 209 .template("URL validation failed - Failure: {}, Input: {}") 210 .build(); 211 212 /** 213 * Security validator configuration error. 214 * Parameters: [0] = validator type, [1] = error description 215 */ 216 public static final LogRecord VALIDATOR_CONFIG_ERROR = LogRecordModel.builder() 217 .prefix(PREFIX) 218 .identifier(402) 219 .template("Security validator configuration error - Validator: {}, Error: {}") 220 .build(); 221 222 /** 223 * Security pipeline execution error. 224 * Parameters: [0] = pipeline stage, [1] = error message 225 */ 226 public static final LogRecord PIPELINE_EXECUTION_ERROR = LogRecordModel.builder() 227 .prefix(PREFIX) 228 .identifier(403) 229 .template("Security pipeline execution failed - Stage: {}, Error: {}") 230 .build(); 231 232 /** 233 * Critical security system failure. 234 * Parameters: [0] = system component, [1] = failure description 235 */ 236 public static final LogRecord SECURITY_SYSTEM_FAILURE = LogRecordModel.builder() 237 .prefix(PREFIX) 238 .identifier(404) 239 .template("Critical security system failure - Component: {}, Description: {}") 240 .build(); 241 242 /** 243 * Security event counter overflow. 244 * Parameters: [0] = failure type, [1] = current count 245 */ 246 public static final LogRecord EVENT_COUNTER_OVERFLOW = LogRecordModel.builder() 247 .prefix(PREFIX) 248 .identifier(405) 249 .template("Security event counter overflow - Type: {}, Count: {}") 250 .build(); 251 252 private ERROR() { 253 // Utility class - no instances 254 } 255 } 256 257 /** 258 * Info level messages for security-relevant events that don't indicate attacks. 259 * These messages provide operational information about the security system. 260 */ 261 public static final class INFO { 262 263 /** 264 * Security validation system enabled. 265 * Parameters: [0] = validation type, [1] = security level 266 */ 267 public static final LogRecord VALIDATION_ENABLED = LogRecordModel.builder() 268 .prefix(PREFIX) 269 .identifier(201) 270 .template("Security validation enabled - Type: {}, Level: {}") 271 .build(); 272 273 /** 274 * Security configuration loaded successfully. 275 * Parameters: [0] = configuration source, [1] = validator count 276 */ 277 public static final LogRecord CONFIG_LOADED = LogRecordModel.builder() 278 .prefix(PREFIX) 279 .identifier(202) 280 .template("Security configuration loaded - Source: {}, Validators: {}") 281 .build(); 282 283 /** 284 * Security validation passed successfully. 285 * Parameters: [0] = validation type, [1] = input (truncated for safety) 286 */ 287 public static final LogRecord VALIDATION_PASSED = LogRecordModel.builder() 288 .prefix(PREFIX) 289 .identifier(203) 290 .template("Security validation passed - Type: {}, Input: {}") 291 .build(); 292 293 /** 294 * Security system initialized. 295 * Parameters: [0] = system version, [1] = active validators 296 */ 297 public static final LogRecord SYSTEM_INITIALIZED = LogRecordModel.builder() 298 .prefix(PREFIX) 299 .identifier(204) 300 .template("Security system initialized - Version: {}, Validators: {}") 301 .build(); 302 303 /** 304 * Security metrics summary. 305 * Parameters: [0] = time period, [1] = total validations, [2] = violations 306 */ 307 public static final LogRecord METRICS_SUMMARY = LogRecordModel.builder() 308 .prefix(PREFIX) 309 .identifier(205) 310 .template("Security metrics - Period: {}, Validations: {}, Violations: {}") 311 .build(); 312 313 private INFO() { 314 // Utility class - no instances 315 } 316 } 317 318 /** 319 * Debug level messages for detailed validation information used in troubleshooting. 320 * These messages are verbose and intended for development and debugging purposes. 321 */ 322 public static final class DEBUG { 323 324 /** 325 * Individual validation stage execution. 326 * Parameters: [0] = stage name, [1] = input status, [2] = execution time (ms) 327 */ 328 public static final LogRecord VALIDATION_STAGE = LogRecordModel.builder() 329 .prefix(PREFIX) 330 .identifier(101) 331 .template("Validation stage executed - Stage: {}, Status: {}, Time: {}ms") 332 .build(); 333 334 /** 335 * Detailed validation step information. 336 * Parameters: [0] = validator name, [1] = step description 337 */ 338 public static final LogRecord VALIDATION_STEP = LogRecordModel.builder() 339 .prefix(PREFIX) 340 .identifier(102) 341 .template("Validation step - Validator: {}, Step: {}") 342 .build(); 343 344 /** 345 * Pattern matching debug information. 346 * Parameters: [0] = pattern name, [1] = input sample, [2] = match result 347 */ 348 public static final LogRecord PATTERN_MATCH = LogRecordModel.builder() 349 .prefix(PREFIX) 350 .identifier(103) 351 .template("Pattern matching - Pattern: {}, Input: {}, Result: {}") 352 .build(); 353 354 /** 355 * Character validation debug information. 356 * Parameters: [0] = character set, [1] = invalid characters found, [2] = position 357 */ 358 public static final LogRecord CHARACTER_VALIDATION = LogRecordModel.builder() 359 .prefix(PREFIX) 360 .identifier(104) 361 .template("Character validation - Set: {}, Invalid: {}, Position: {}") 362 .build(); 363 364 /** 365 * URL decoding debug information. 366 * Parameters: [0] = original input, [1] = decoded output, [2] = encoding type 367 */ 368 public static final LogRecord URL_DECODING = LogRecordModel.builder() 369 .prefix(PREFIX) 370 .identifier(105) 371 .template("URL decoding - Original: {}, Decoded: {}, Type: {}") 372 .build(); 373 374 /** 375 * Configuration parameter debug information. 376 * Parameters: [0] = parameter name, [1] = parameter value, [2] = source 377 */ 378 public static final LogRecord CONFIG_PARAMETER = LogRecordModel.builder() 379 .prefix(PREFIX) 380 .identifier(106) 381 .template("Configuration parameter - Name: {}, Value: {}, Source: {}") 382 .build(); 383 384 private DEBUG() { 385 // Utility class - no instances 386 } 387 } 388}