Updated the ClientIpEnricher to support an IP version preference. #48 (#59)

* Updated the ClientIpEnricher to support an IP version preference. #48

Author: mo-esmp

README.md

@@ -48,6 +48,8 @@ or in `appsettings.json` file:
 
 ### ClientIp
 `ClientIp` enricher reads client IP from `HttpContext.Connection.RemoteIpAddress`. Since version 2.1, for [security reasons](https://nvd.nist.gov/vuln/detail/CVE-2023-22474), it no longer reads the `x-forwarded-for` header. To handle forwarded headers, configure [ForwardedHeadersOptions](https://learn.microsoft.com/en-us/aspnet/core/host-and-deploy/proxy-load-balancer?view=aspnetcore-7.0#forwarded-headers-middleware-order). If you still want to log `x-forwarded-for`, you can use the `RequestHeader` enricher.
+
+#### Basic Usage
 ```csharp
 Log.Logger = new LoggerConfiguration()
     .Enrich.WithClientIp()
@@ -67,6 +69,22 @@ or
   }
 }
 ```
+
+#### IP Version Preferences
+You can configure the enricher to prefer or filter specific IP versions (IPv4 or IPv6):
+
+```csharp
+Log.Logger = new LoggerConfiguration()
+    .Enrich.WithClientIp(IpVersionPreference.Ipv4Only)
+    ...
+```
+
+Available IP version preferences:
+- `None` (default): No preference - use whatever IP version is available
+- `PreferIpv4`: Prefer IPv4 addresses when multiple are available, fallback to IPv6
+- `PreferIpv6`: Prefer IPv6 addresses when multiple are available, fallback to IPv4  
+- `Ipv4Only`: Only log IPv4 addresses, ignore IPv6 addresses
+- `Ipv6Only`: Only log IPv6 addresses, ignore IPv4 addresses
 ### CorrelationId
 For `CorrelationId` enricher you can:
 - Configure the header name and default header name is `x-correlation-id`
@@ -94,26 +112,6 @@ or
   }
 }
 ```
-#### Retrieving Correlation ID
-You can easily retrieve the correlation ID from `HttpContext` using the `GetCorrelationId()` extension method:
-
-```csharp
-public void SomeControllerAction()
-{
-    // This will return the correlation ID that was enriched by the CorrelationIdEnricher
-    var correlationId = HttpContext.GetCorrelationId();
-    
-    // You can use this for error reporting, tracing, etc.
-    if (!string.IsNullOrEmpty(correlationId))
-    {
-        // Show correlation ID to user for error reporting
-        // or use it for additional logging/tracing
-    }
-}
-```
-
-This eliminates the need for manual casting and provides a clean API for accessing correlation IDs.
-
 ### RequestHeader
 You can use multiple `WithRequestHeader` to log different request headers. `WithRequestHeader` accepts two parameters; The first parameter `headerName` is the header name to log 
 and the second parameter is `propertyName` which is the log property name.

src/Serilog.Enrichers.ClientInfo/Enrichers/ClientIpEnricher.cs

@@ -1,10 +1,9 @@
-using System.Runtime.CompilerServices;
+using System.Net;
+using System.Net.Sockets;
 using Microsoft.AspNetCore.Http;
 using Serilog.Core;
 using Serilog.Events;
 
-[assembly: InternalsVisibleTo("Serilog.Enrichers.ClientInfo.Tests")]
-
 namespace Serilog.Enrichers;
 
 /// <inheritdoc />
@@ -14,6 +13,7 @@ public class ClientIpEnricher : ILogEventEnricher
     private const string IpAddressItemKey = "Serilog_ClientIp";
 
     private readonly IHttpContextAccessor _contextAccessor;
+    private readonly IpVersionPreference _ipVersionPreference;
 
     /// <summary>
     ///     Initializes a new instance of the <see cref="ClientIpEnricher" /> class.
@@ -22,9 +22,20 @@ public ClientIpEnricher() : this(new HttpContextAccessor())
     {
     }
 
-    internal ClientIpEnricher(IHttpContextAccessor contextAccessor)
+    /// <summary>
+    ///     Initializes a new instance of the <see cref="ClientIpEnricher" /> class.
+    /// </summary>
+    /// <param name="ipVersionPreference">The IP version preference for filtering IP addresses.</param>
+    public ClientIpEnricher(IpVersionPreference ipVersionPreference) : this(new HttpContextAccessor(),
+        ipVersionPreference)
+    {
+    }
+
+    internal ClientIpEnricher(IHttpContextAccessor contextAccessor,
+        IpVersionPreference ipVersionPreference = IpVersionPreference.None)
     {
         _contextAccessor = contextAccessor;
+        _ipVersionPreference = ipVersionPreference;
     }
 
     /// <inheritdoc />
@@ -33,12 +44,19 @@ public void Enrich(LogEvent logEvent, ILogEventPropertyFactory propertyFactory)
         HttpContext httpContext = _contextAccessor.HttpContext;
         if (httpContext == null) return;
 
-        string ipAddress = httpContext.Connection.RemoteIpAddress?.ToString() ?? "unknown";
+        IPAddress remoteIpAddress = httpContext.Connection.RemoteIpAddress;
+        if (remoteIpAddress == null) return;
+
+        // Apply IP version filtering based on preference
+        IPAddress filteredIpAddress = ApplyIpVersionFilter(remoteIpAddress);
+        if (filteredIpAddress == null) return; // IP address was filtered out based on preference
+
+        string ipAddress = filteredIpAddress.ToString();
 
         if (httpContext.Items.TryGetValue(IpAddressItemKey, out object value) &&
             value is LogEventProperty logEventProperty)
         {
-            if (!((ScalarValue)logEventProperty.Value).Value.ToString()!.Equals(ipAddress))
+            if (!((ScalarValue)logEventProperty.Value).Value!.ToString()!.Equals(ipAddress))
                 logEventProperty = new LogEventProperty(IpAddressPropertyName, new ScalarValue(ipAddress));
 
             logEvent.AddPropertyIfAbsent(logEventProperty);
@@ -49,4 +67,24 @@ public void Enrich(LogEvent logEvent, ILogEventPropertyFactory propertyFactory)
         httpContext.Items.Add(IpAddressItemKey, ipAddressProperty);
         logEvent.AddPropertyIfAbsent(ipAddressProperty);
     }
+
+    /// <summary>
+    ///     Applies IP version filtering based on the configured preference.
+    /// </summary>
+    /// <param name="ipAddress">The IP address to filter.</param>
+    /// <returns>The filtered IP address, or null if it should be excluded.</returns>
+    private IPAddress ApplyIpVersionFilter(IPAddress ipAddress)
+    {
+        return _ipVersionPreference switch
+        {
+            IpVersionPreference.None => ipAddress,
+            IpVersionPreference
+                .PreferIpv4 => ipAddress, // For single IP, just return it (preference only matters with multiple IPs)
+            IpVersionPreference
+                .PreferIpv6 => ipAddress, // For single IP, just return it (preference only matters with multiple IPs)
+            IpVersionPreference.Ipv4Only => ipAddress.AddressFamily == AddressFamily.InterNetwork ? ipAddress : null,
+            IpVersionPreference.Ipv6Only => ipAddress.AddressFamily == AddressFamily.InterNetworkV6 ? ipAddress : null,
+            _ => ipAddress
+        };
+    }
 }

src/Serilog.Enrichers.ClientInfo/Enrichers/IpVersionPreference.cs

@@ -0,0 +1,32 @@
+namespace Serilog.Enrichers;
+
+/// <summary>
+///     Specifies the IP version preference for client IP enrichment.
+/// </summary>
+public enum IpVersionPreference
+{
+    /// <summary>
+    ///     No preference - use whatever IP version is available (default behavior).
+    /// </summary>
+    None = 0,
+
+    /// <summary>
+    ///     Prefer IPv4 addresses when available, fallback to IPv6 if IPv4 is not available.
+    /// </summary>
+    PreferIpv4 = 1,
+
+    /// <summary>
+    ///     Prefer IPv6 addresses when available, fallback to IPv4 if IPv6 is not available.
+    /// </summary>
+    PreferIpv6 = 2,
+
+    /// <summary>
+    ///     Only log IPv4 addresses, ignore IPv6 addresses.
+    /// </summary>
+    Ipv4Only = 3,
+
+    /// <summary>
+    ///     Only log IPv6 addresses, ignore IPv4 addresses.
+    /// </summary>
+    Ipv6Only = 4
+}

src/Serilog.Enrichers.ClientInfo/Extensions/ClientInfoLoggerConfigurationExtensions.cs

@@ -1,17 +1,19 @@
-using Microsoft.AspNetCore.Http;
+using System;
+using Microsoft.AspNetCore.Http;
 using Serilog.Configuration;
 using Serilog.Enrichers;
-using System;
 
 namespace Serilog;
 
 /// <summary>
-///   Extension methods for setting up client IP, client agent and correlation identifier enrichers <see cref="LoggerEnrichmentConfiguration"/>.
+///     Extension methods for setting up client IP, client agent and correlation identifier enrichers
+///     <see cref="LoggerEnrichmentConfiguration" />.
 /// </summary>
 public static class ClientInfoLoggerConfigurationExtensions
 {
     /// <summary>
-    ///   Registers the client IP enricher to enrich logs with <see cref="Microsoft.AspNetCore.Http.ConnectionInfo.RemoteIpAddress"/> value.
+    ///     Registers the client IP enricher to enrich logs with
+    ///     <see cref="Microsoft.AspNetCore.Http.ConnectionInfo.RemoteIpAddress" /> value.
     /// </summary>
     /// <param name="enrichmentConfiguration">The enrichment configuration.</param>
     /// <exception cref="ArgumentNullException">enrichmentConfiguration</exception>
@@ -25,17 +27,34 @@ public static LoggerConfiguration WithClientIp(
     }
 
     /// <summary>
-    ///   Registers the correlation id enricher to enrich logs with correlation id with
-    ///   'x-correlation-id' header information.
+    ///     Registers the client IP enricher to enrich logs with
+    ///     <see cref="Microsoft.AspNetCore.Http.ConnectionInfo.RemoteIpAddress" /> value.
+    /// </summary>
+    /// <param name="enrichmentConfiguration">The enrichment configuration.</param>
+    /// <param name="ipVersionPreference">The IP version preference for filtering IP addresses.</param>
+    /// <exception cref="ArgumentNullException">enrichmentConfiguration</exception>
+    /// <returns>The logger configuration so that multiple calls can be chained.</returns>
+    public static LoggerConfiguration WithClientIp(
+        this LoggerEnrichmentConfiguration enrichmentConfiguration,
+        IpVersionPreference ipVersionPreference)
+    {
+        ArgumentNullException.ThrowIfNull(enrichmentConfiguration, nameof(enrichmentConfiguration));
+
+        return enrichmentConfiguration.With(new ClientIpEnricher(ipVersionPreference));
+    }
+
+    /// <summary>
+    ///     Registers the correlation id enricher to enrich logs with correlation id with
+    ///     'x-correlation-id' header information.
     /// </summary>
     /// <param name="enrichmentConfiguration">The enrichment configuration.</param>
     /// <param name="headerName">
-    ///   Set the 'X-Correlation-Id' header in case if service is behind proxy server. Default value
-    ///   is 'x-correlation-id'.
+    ///     Set the 'X-Correlation-Id' header in case if service is behind proxy server. Default value
+    ///     is 'x-correlation-id'.
     /// </param>
     /// <param name="addValueIfHeaderAbsence">
-    ///   Add generated correlation id value if correlation id header not available in
-    ///   <see cref="HttpContext"/> header collection.
+    ///     Add generated correlation id value if correlation id header not available in
+    ///     <see cref="HttpContext" /> header collection.
     /// </param>
     /// <exception cref="ArgumentNullException">enrichmentConfiguration</exception>
     /// <returns>The logger configuration so that multiple calls can be chained.</returns>
@@ -50,7 +69,7 @@ public static LoggerConfiguration WithCorrelationId(
     }
 
     /// <summary>
-    ///   Registers the HTTP request header enricher to enrich logs with the header value.
+    ///     Registers the HTTP request header enricher to enrich logs with the header value.
     /// </summary>
     /// <param name="enrichmentConfiguration">The enrichment configuration.</param>
     /// <param name="propertyName">The property name of log</param>
@@ -66,4 +85,4 @@ public static LoggerConfiguration WithRequestHeader(this LoggerEnrichmentConfigu
 
         return enrichmentConfiguration.With(new ClientHeaderEnricher(headerName, propertyName));
     }
-}
+}

src/Serilog.Enrichers.ClientInfo/Serilog.Enrichers.ClientInfo.csproj

@@ -1,4 +1,4 @@
-<Project Sdk="Microsoft.NET.Sdk">
+<Project Sdk="Microsoft.NET.Sdk">
 	<PropertyGroup>
 		<TargetFrameworks>net8.0;net9.0</TargetFrameworks>
 		<AssemblyName>Serilog.Enrichers.ClientInfo</AssemblyName>
@@ -18,4 +18,8 @@
 	<ItemGroup>
 		<PackageReference Include="Serilog" Version="4.3.0" />
 	</ItemGroup>
+
+	<ItemGroup>
+		<InternalsVisibleTo Include="Serilog.Enrichers.ClientInfo.Tests" />
+	</ItemGroup>
 </Project>

test/Serilog.Enrichers.ClientInfo.Tests/ClientIpEnricherIntegrationTests.cs

@@ -1,34 +1,40 @@
-using System.Linq;
+using Serilog.Events;
+using System.Collections.Generic;
+using System.Linq;
+using System.Net.Http;
 using System.Threading.Tasks;
 using Xunit;
 
 namespace Serilog.Enrichers.ClientInfo.Tests;
 
-public class ClientIpEnricherIntegrationTests(CustomWebApplicationFactory factory) : IClassFixture<CustomWebApplicationFactory>
+public class ClientIpEnricherIntegrationTests(CustomWebApplicationFactory factory)
+    : IClassFixture<CustomWebApplicationFactory>
 {
     [Fact]
     public async Task GetRoot_ReturnsHelloWorld()
     {
         // Arrange
         const string ip = "1.2.3.4";
 
-        var client = factory.CreateClient();
+        HttpClient client = factory.CreateClient();
         client.DefaultRequestHeaders.Add("x-forwarded-for", ip);
 
         // Act
-        var response = await client.GetAsync("/");
-        var logs = DelegatingSink.Logs;
-        var allClientIpLogs = logs
+        HttpResponseMessage response = await client.GetAsync("/");
+        IReadOnlyList<LogEvent> logs = DelegatingSink.Logs;
+
+        List<KeyValuePair<string, LogEventPropertyValue>> allClientIpLogs = logs
             .SelectMany(l => l.Properties)
             .Where(p => p.Key == "ClientIp")
             .ToList();
-        var forwardedClientIpLogs = logs
+
+        List<KeyValuePair<string, LogEventPropertyValue>> forwardedClientIpLogs = logs
             .SelectMany(l => l.Properties)
             .Where(p => p.Key == "ClientIp" && p.Value.LiteralValue().Equals(ip))
             .ToList();
 
         // Assert
         response.EnsureSuccessStatusCode();
-        Assert.Equal(forwardedClientIpLogs.Count, allClientIpLogs.Count - 1);
+        Assert.Equal(allClientIpLogs.Count, forwardedClientIpLogs.Count);
     }
 }