Allow access to match when preprocessing mask

Author: sandermvanvliet

Changelog.md

@@ -1,5 +1,9 @@
 # Changelog for Serilog.Enrichers.Sensitive
 
+## 1.6.0
+
+- Pass match to `PreprocessMask` to allow for further customisation of mask value
+
 ## 1.5.1 
 
 - Add support for dictionaries in destructured objects

Directory.Build.props

@@ -1,8 +1,8 @@
 <Project>
 	<PropertyGroup>
-		<Version>1.5.1.0</Version>
+		<Version>1.6.0.0</Version>
 		<Authors>Sander van Vliet, Huibert Jan Nieuwkamer, Scott Toberman</Authors>
 		<Company>Codenizer BV</Company>
-		<Copyright>2022 Sander van Vliet</Copyright>
+		<Copyright>2023 Sander van Vliet</Copyright>
 	</PropertyGroup>
 </Project>

README.md

@@ -118,7 +118,7 @@ new LoggerConfiguration()
                 // etc etc
             };
         });
-```csharp
+```
 
 It is also possible to not use any masking operators but instead mask based on property names. In that case you can configure the enricher to not use any masking operators at all:
 
@@ -130,7 +130,7 @@ new LoggerConfiguration()
         {
             options.MaskingOperators.Clear();
         });
-```csharp
+```
 
 ### Using a custom mask value
 
@@ -149,6 +149,28 @@ A example rendered message would then look like:
 
 You can specify any mask string as long as it's non-null or an empty string.
 
+#### Customising the mask value based on the matched value
+
+In situations where you want to change the mask and have it include parts of the matched value you can override the `PreprocessMask` method that takes both `mask` and `match` parameters. This allows you to perform more masks that are more dynamic.
+
+For example: mask only the "user" part of an e-mail address.
+
+```csharp
+public class CustomizedEmailAddressMaskingOperator : EmailAddressMaskingOperator
+{
+    protected override PreprocessMask(string mask, Match match)
+    {
+        var parts = match.Value.Split('@');
+
+        return mask + "@" + parts[1];
+    }
+}
+```
+
+When the mask is `***MASKED***` and we pass in `[email protected]` the result will be `***MASKED***@universalexports.co.uk`.
+
+Note that this example uses `EmailAddressMaskingOperator` which has a fairly complex regular expression. If possible change your regular expression to have match groups so you can more easily access them through the `match` parameter.
+
 ### Always mask a property
 
 It may be that you always want to mask the value of a property regardless of whether it matches a pattern for any of the masking operators. In that case you can specify that the property is always masked:

src/Serilog.Enrichers.Sensitive/RegexMaskingOperator.cs

@@ -38,7 +38,7 @@ public MaskingResult Mask(string input, string mask)
             {
                 if (ShouldMaskMatch(match))
                 {
-                    return match.Result(PreprocessMask(mask));
+                    return match.Result(PreprocessMask(PreprocessMask(mask), match));
                 }
 
                 return match.Value;
@@ -76,6 +76,14 @@ public MaskingResult Mask(string input, string mask)
         /// <returns>The processed mask, defaults to no pre-processing and returns the input</returns>
 		protected virtual string PreprocessMask(string mask) => mask;
 
+        /// <summary>
+        /// Perform any operations on the mask before masking the matched value
+        /// </summary>
+        /// <param name="mask">The mask value as specified on the <see cref="SensitiveDataEnricherOptions"/></param>
+        /// <param name="match">The regex match</param>
+        /// <returns>The processed mask, defaults to no pre-processing and returns the input</returns>
+        protected virtual string PreprocessMask(string mask, Match match) => mask;
+
 		/// <summary>
 		/// Indicate whether the operator should continue with masking the matched value from the input
 		/// </summary>

test/Serilog.Enrichers.Sensitive.Tests.Unit/WhenMaskingWithRegexOperator.cs

@@ -1,4 +1,5 @@
 using System;
+using System.Text.RegularExpressions;
 using FluentAssertions;
 using Xunit;
 
@@ -7,11 +8,20 @@ namespace Serilog.Enrichers.Sensitive.Tests.Unit
 	public class WhenMaskingWithRegexOperator
 	{
 		private class RegexExtenderWithOptions : RegexMaskingOperator
-		{
-			public RegexExtenderWithOptions(string regexPattern) : base(regexPattern)
-			{
-			}
-		}
+        {
+            private Func<string, Match, string> _preprocessMask;
+
+			public RegexExtenderWithOptions(string regexPattern, Func<string, Match, string>? preprocessMask = null)
+                : base(regexPattern)
+            {
+                _preprocessMask = preprocessMask ?? new Func<string,Match,string>((mask, _) => mask);
+            }
+
+            protected override string PreprocessMask(string mask, Match match)
+            {
+                return _preprocessMask(mask, match);
+            }
+        }
 
 
 		[Fact]
@@ -43,5 +53,22 @@ public void GivenConstructor_EmptyOrWhitespacePatternThrowsException(string rege
 				.Should()
 				.Be("regexString");
 		}
+
+		[Fact]
+        public void GivenPreprocessMaskWithMatchIsUsed_MaskedValueIsModified()
+        {
+			// Regex matches any character and has a match group for the last character.
+			// The mask provided to Mask() is ignored and instead it's set to mask all
+			// characters with '*' except the last one.
+            var result = new RegexExtenderWithOptions(
+                    ".*([a-z])",
+                    (mask, match) => match.Groups[1].Value.PadLeft(match.Value.Length, '*'))
+                .Mask("abc", "**MASK**");
+
+            result
+                .Result
+                .Should()
+                .Be("**c");
+        }
 	}
 }