Add extension point to perform additional checks on a match to decide whether to mask it

Author: sandermvanvliet

CHANGELOG

@@ -1,5 +1,9 @@
 # Changelog for Serilog.Enrichers.Sensitive
 
+## 1.2.0
+
+- Add `ShouldMaskMatch` to the `RegexMaskingOperator` to allow implementors to perform further checks on the sensitive value in order to decide whether or not to perform masking
+
 ## 1.1.0
 
 - Add support to supply a custom mask value [#6](https://github.com/serilog-contrib/Serilog.Enrichers.Sensitive/issues/6)

Directory.Build.props

@@ -1,6 +1,6 @@
 <Project>
 	<PropertyGroup>
-		<Version>1.1.0.0</Version>
+		<Version>1.2.0.0</Version>
 		<Authors>Sander van Vliet, Huibert Jan Nieuwkamer, Scott Toberman</Authors>
 		<Company>Codenizer BV</Company>
 		<Copyright>2022 Sander van Vliet</Copyright>

README.md

@@ -135,23 +135,24 @@ the rendered log message comes out as: `"This is a sensitive ***MASKED***"`
 
 ## Extending to additional use cases
 
-Extending this enricher is a fairly straight forward process.
+Depending on the type of masking operation you want to perform, the `RegexMaskingOperator` base class is most likely your best starting point. It provides a number of extension points:
 
-1. Create your new class and inherit from the RegexMaskingOperator base class
-    1. Pass your regex pattern to the base constructor
-    2. To control if the regex replacement should even take place, override ShouldMaskInput, returning `true` if the mask should be applied, and `false` if it should not.
-    3. Override PreprocessInput if your use case requires adjusting the input string before the regex match is applied.
-    4. Override PreprocessMask if your use case requires adjusting the mask that is applied (for instance, if your regex includes named groups).  See the [CreditCardMaskingOperator](src/Serilog.Enrichers.Sensitive/CreditCardMaskingOperator.cs) for an example.
-2. When configuring your logger, pass your new encricher in the collection of masking operators
+| Method | Purpose |
+|--------|---------|
+| ShouldMaskInput | Indicate whether the operator should continue with masking the input |
+| PreprocessInput | Perform any operations on the input value before masking the input |
+| PreprocessMask | Perform any operations on the mask before masking the matched value | 
+| ShouldMaskMatch | Indicate whether the operator should continue with masking the matched value from the input | 
+
+To implement your own masking operator, inherit from `RegexMaskingOperator`, supply the regex through the base constructor and where necessary override any of the above extension points.
+
+Then, when configuring your logger, pass your new encricher in the collection of masking operators:
 
 ```csharp
 var logger = new LoggerConfiguration()
-    .Enrich.WithSensitiveDataMasking(MaskingMode.InArea, new IMaskingOperator[]
-    {
-        new EmailAddressMaskingOperator(),
-        new IbanMaskingOperator(),
-        new CreditCardMaskingOperator(false),
-        new YourMaskingOperator()
+    .Enrich.WithSensitiveDataMasking(options => {
+        // Add your masking operator:
+        options.MaskingOperators.Add(new YourMaskingOperator());
     })
     .WriteTo.Console()
     .CreateLogger();

src/Serilog.Enrichers.Sensitive/RegexMaskingOperator.cs

@@ -3,17 +3,22 @@
 
 namespace Serilog.Enrichers.Sensitive
 {
+	/// <summary>
+	/// A masking operator that uses regular expressions to match the value from the input to mask
+	/// </summary>
 	public abstract class RegexMaskingOperator : IMaskingOperator
 	{
 		private readonly Regex _regex;
 
-		protected RegexMaskingOperator(string regexString) : this(regexString, RegexOptions.Compiled)
+		protected RegexMaskingOperator(string regexString) 
+            : this(regexString, RegexOptions.Compiled)
 		{
 		}
 
 		protected RegexMaskingOperator(string regexString, RegexOptions options)
 		{
 			_regex = new Regex(regexString ?? throw new ArgumentNullException(nameof(regexString)), options);
+
 			if (string.IsNullOrWhiteSpace(regexString))
 			{
 				throw new ArgumentOutOfRangeException(nameof(regexString), "Regex pattern cannot be empty or whitespace.");
@@ -23,12 +28,22 @@ protected RegexMaskingOperator(string regexString, RegexOptions options)
 		public MaskingResult Mask(string input, string mask)
 		{
 			var preprocessedInput = PreprocessInput(input);
+
 			if (!ShouldMaskInput(preprocessedInput))
 			{
 				return MaskingResult.NoMatch;
 			}
 
-			var maskedResult = _regex.Replace(preprocessedInput, PreprocessMask(mask));
+            var maskedResult = _regex.Replace(preprocessedInput, match =>
+            {
+                if (ShouldMaskMatch(match))
+                {
+                    return match.Result(PreprocessMask(mask));
+                }
+
+                return match.Value;
+            });
+			
 			var result = new MaskingResult
 			{
 				Result = maskedResult,
@@ -38,10 +53,35 @@ public MaskingResult Mask(string input, string mask)
 			return result;
 		}
 
+		/// <summary>
+		/// Indicate whether the operator should continue with masking the input
+		/// </summary>
+		/// <param name="input">The message template or the value of a property on the log event</param>
+		/// <returns><c>true</c> when the input should be masked, otherwise <c>false</c>. Defaults to <c>true</c></returns>
+		/// <remarks>This method provides an extension point to short-circuit the masking operation before the regular expression matching is performed</remarks>
 		protected virtual bool ShouldMaskInput(string input) => true;
 
+		/// <summary>
+		/// Perform any operations on the input value before masking the input
+		/// </summary>
+        /// <param name="input">The message template or the value of a property on the log event</param>
+		/// <returns>The processed input, defaults to no pre-processing and returns the input</returns>
+		/// <remarks>Use this method if the input is encoded using URL encoding for example</remarks>
 		protected virtual string PreprocessInput(string input) => input;
 
+		/// <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>
+        /// <returns>The processed mask, defaults to no pre-processing and returns the input</returns>
 		protected virtual string PreprocessMask(string mask) => mask;
-	}
+
+		/// <summary>
+		/// Indicate whether the operator should continue with masking the matched value from the input
+		/// </summary>
+		/// <param name="match">The match found by the regular expression of this operator</param>
+        /// <returns><c>true</c> when the match should be masked, otherwise <c>false</c>. Defaults to <c>true</c></returns>
+        /// <remarks>This method provides an extension point to short-circuit the masking operation if the value matches the regular expression but does not satisfy some additional criteria</remarks>
+        protected virtual bool ShouldMaskMatch(Match match) => true;
+    }
 }

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

@@ -0,0 +1,75 @@
+using System.Collections.Generic;
+using System.Text.RegularExpressions;
+using Serilog.Sinks.InMemory;
+using Serilog.Sinks.InMemory.Assertions;
+using Xunit;
+
+namespace Serilog.Enrichers.Sensitive.Tests.Unit
+{
+    public class WhenMaskingWithInputFilter
+    {
+        [Fact]
+        public void GivenTestPropertyHasTestValue_ValueIsMasked()
+        {
+            var inMemorySink = new InMemorySink();
+
+            var logger =  new LoggerConfiguration()
+                .Enrich.WithSensitiveDataMasking(options =>
+                {
+                    options.MaskingOperators = new List<IMaskingOperator>
+                    {
+                        new SpecificValueMaskingOperator("[A-Za-z]*")
+                    };
+                })
+                .WriteTo.Sink(inMemorySink)
+                .CreateLogger();
+
+            logger.Information("TestValue");
+            
+            inMemorySink
+                .Should()
+                .HaveMessage("***MASKED***")
+                .Appearing().Once();
+        }
+
+        [Fact]
+        public void GivenTestPropertyHasSomeOtherValue_ValueIsNotMasked()
+        {
+            var inMemorySink = new InMemorySink();
+
+            var logger =  new LoggerConfiguration()
+                .Enrich.WithSensitiveDataMasking(options =>
+                {
+                    options.MaskingOperators = new List<IMaskingOperator>
+                    {
+                        new SpecificValueMaskingOperator("[A-Za-z]*")
+                    };
+                })
+                .WriteTo.Sink(inMemorySink)
+                .CreateLogger();
+
+            logger.Information("SomeOtherValue");
+            
+            inMemorySink
+                .Should()
+                .HaveMessage("SomeOtherValue")
+                .Appearing().Once();
+        }
+    }
+
+    internal class SpecificValueMaskingOperator : RegexMaskingOperator
+    {
+        public SpecificValueMaskingOperator(string regexString) : base(regexString)
+        {
+        }
+
+        public SpecificValueMaskingOperator(string regexString, RegexOptions options) : base(regexString, options)
+        {
+        }
+
+        protected override bool ShouldMaskMatch(Match match)
+        {
+            return match.Value == "TestValue";
+        }
+    }
+}