https://github.com/nikouu/zeroredact
A fast, simple, zero allocation redacting library for .NET, with no extra dependencies.
https://github.com/nikouu/zeroredact
benchmarking csharp dotnet mask masking nuget performance redact redaction
Last synced: 8 months ago
JSON representation
A fast, simple, zero allocation redacting library for .NET, with no extra dependencies.
- Host: GitHub
- URL: https://github.com/nikouu/zeroredact
- Owner: nikouu
- License: mit
- Created: 2024-09-23T08:46:17.000Z (about 1 year ago)
- Default Branch: main
- Last Pushed: 2025-01-23T07:07:25.000Z (9 months ago)
- Last Synced: 2025-02-05T07:03:29.799Z (8 months ago)
- Topics: benchmarking, csharp, dotnet, mask, masking, nuget, performance, redact, redaction
- Language: C#
- Homepage: https://nikouu.github.io/ZeroRedact/
- Size: 9.14 MB
- Stars: 6
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Funding: .github/FUNDING.yml
- License: LICENSE
Awesome Lists containing this project
README
# ZeroRedact
[](https://www.nuget.org/packages/Nikouu.ZeroRedact)
[](https://www.nuget.org/packages/Nikouu.ZeroRedact)
[](https://github.com/nikouu/ZeroRedact/releases)
[](https://nikouu.github.io/ZeroRedact/)
[](https://nikouu.github.io/ZeroRedact/demo/)
[](https://github.com/nikouu/ZeroRedact/blob/main/LICENSE)
[](https://www.nikouusitalo.com/)
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](https://nikouu.github.io/ZeroRedact/).
## Getting started
Install via [NuGet](https://www.nuget.org/packages/Nikouu.ZeroRedact/):
```
dotnet add package Nikouu.ZeroRedact
```
The following shows example redactions with varying configs. For more see the [official docs](https://nikouu.github.io/ZeroRedact/).
```csharp
var redactor = new Redactor();
// returns "*************"
var stringResult = redactor.RedactString("Hello, World!");
// returns "*****@*******.***"
var emailAddressResult = redactor.RedactEmailAddress("email@example.com");
// 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: "*/06/2023"
// en-US: "6/*/2023"
// 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 "@@@.@.@.146"
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`:
```csharp
// 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.
```csharp
// 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 '*'.
```csharp
// 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.
```csharp
// 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](https://learn.microsoft.com/en-us/dotnet/api/microsoft.extensions.compliance.redaction) to provide full and partial redacting.
See [Compliance.Redaction-with-ZeroRedact](https://github.com/nikouu/Compliance.Redaction-with-ZeroRedact) for an example project.
## Performance
### Benchmarks
See [benchmarks](benchmarks).
## Contributing
Currently not looking for contributions, however issues for problems or feature suggestions are welcome for consideration.
## License
[MIT](LICENSE)