README.md

ZeroRedact

A fast, simple, zero allocation redacting library for .NET, with no non-Microsoft dependencies.

Fully or partially redact:

• Strings
• Email addresses
• Credit card numbers
• Dates
• Phone numbers
• IPV4 addresses
• IPV6 addresses
• MAC addresses

Read more in the official docs.

Getting started

Install via NuGet:

dotnet add package Nikouu.ZeroRedact

The following shows example redactions with varying configs. For more see the official docs.

var redactor = new Redactor();

// returns "*************"
var stringResult = redactor.RedactString("Hello, World!");

// returns "*****@*******.***"
var emailAddressResult = redactor.RedactEmailAddress("[email protected]");

// returns "****-****-****-1111"
var creditCardOptions = new CreditCardRedactorOptions { RedactorType = CreditCardRedaction.ShowLastFour };
var creditCardResult = redactor.RedactCreditCard("4111-1111-1111-1111", creditCardOptions);

// returns based on current culture
// en-NZ: "6/**/2023"
// en-US: "*/**/****"
// ja-JP: "2023/06/**"
// InvariantCulture: "06/**/2023"
var dateOptions = new DateRedactorOptions { RedactorType = DateRedaction.Day };
var dateResult = redactor.RedactDate(new DateTime(2023, 10, 5), dateOptions);

// returns "###-###-####"
var phoneNumberOptions = new PhoneNumberRedactorOptions { RedactionCharacter = '#' };
var phoneNumberResult = redactor.RedactPhoneNumber("212-456-7890");

// returns "@@@.@[email protected]"
var ipv4AddressOptions = new IPv4AddressRedactorOptions
{
    RedactionCharacter = '@',
    RedactorType = IPv4AddressRedaction.ShowLastOctet
};
var ipv4Result = redactor.RedactIPv4Address("192.0.2.146", ipv4AddressOptions);

// returns "****:****:****:****:****:****:****:****"
var ipv6Result = redactor.RedactIPv6Address("2001:0000:130F:0000:0000:09C0:876A:130B");

// "**:**:**:**:**:**"
var macResult = redactor.RedactMACAddress("00:B0:D0:63:C2:26");

Or in the case of a service registration with IServiceCollection:

// Default
builder.Services.AddZeroRedact();

// Or to configure
builder.Services.AddZeroRedact(new RedactorOptions
{
    CreditCardRedactorOptions = new CreditCardRedactorOptions { RedactorType = CreditCardRedaction.ShowLastFour },
    EmailAddressRedactorOptions = new EmailAddressRedactorOptions { RedactorType = EmailAddressRedaction.ShowFirstCharacters },
    DateRedactorOptions = new DateRedactorOptions { RedactorType = DateRedaction.Day },
    PhoneNumberRedactorOptions = new PhoneNumberRedactorOptions { RedactorType = PhoneNumberRedaction.ShowLastFour }
});

Configuration

ZeroRedact can be configured in two ways: via constructor, and via a redaction method. Both using the appropriate redactor option object.

Configuration has three layers with least to most priority:

1. Base defaults within the Redactor object.
2. Passed in options to the Redactor object constructor
3. Passed in options to a redaction method at the time of redaction

This example shows changing the base defaults. This will apply to every redaction, whether it's a string or email address, etc.

// Example 1: Changing base defaults
var options = new RedactorOptions
{
    RedactionCharacter = 'X'
};

var redactor = new Redactor(options);

// returns "XXXXXXXXXXXXX"
var result = redactor.RedactString("Hello, World!");

This example shows StringRedactorOptions being passed into the Redactor constructor. Only string redactions will now use 'A' as the redaction character, all others will continue to use the default character of '*'.

// Example 2: Changing specific redaction type options
var options = new RedactorOptions
{
    StringRedactorOptions = new StringRedactorOptions
    {
        RedactionCharacter = 'A'
    }
};

var redactor = new Redactor(options);

// returns "AAAAAAAAAAAAA"
var result = redactor.RedactString("Hello, World!");

This example shows passing in StringRedactorOptions at the time of redaction, which takes precedence over the constructor options.

// Example 3: Changing redaction options at redaction time
var options = new RedactorOptions
{
    StringRedactorOptions = new StringRedactorOptions
    {
        RedactionCharacter = 'A'
    }
};

var redactor = new Redactor(options);
var specificOptions = new StringRedactorOptions { RedactionCharacter = 'B' };

// returns "BBBBBBBBBBBBB"
var result = redactor.RedactString("Hello, World!", specificOptions);

Layered configuration

Users should have a fine grained customization experience which allows for an easy to reuse item that can setup default behaviours but when needed, can adapt to the need of the redaction call at the time.

Error handling

Redacting will not throw exceptions - that is, the string manipulation logic. Any exception during the redacting process will return a fixed length redaction with a default redacting character. This is to avoid disrupting the important real work happening in a user's codebase while still preventing PII from being exposed.

However exceptions can occur by passing invalid options to the redactor, whether that's via the constructor, or via a redaction method.

No external dependencies

Keeps project light, easier to maintain, easier to get approved by having Microsoft-only packages, less supply chain issues.

Microsoft.Extensions.Compliance.Redaction

ZeroRedact can be integrated into Microsoft.Extensions.Compliance.Redaction to provide full and partial redacting.

See Compliance.Redaction-with-ZeroRedact for an example project.

Performance

Benchmarks

See benchmarks.

Contributing

Currently not looking for contributions, however issues for problems or feature suggestions are welcome for consideration.

License

MIT