ByteGuard.SecurityLogger 1.0.0

ByteGuard.SecurityLogger

ByteGuard.SecurityLogger is a lightweight ILogger wrapper that brings the OWASP Logging Vocabulary to .NET by exposing a set of strongly-typed ILogger methods for common security and audit events.

Instead of ad-hoc log messages like "login ok" or "unauthorized", you log standardized, structured events (e.g. authn_login_success, authz_fail) with consistent property names. This makes your security logs easier to search, alert on, correlate, and reason about, regardless of whether you send logs to Serilog, NLog, Application Insights, Elasticsearch, or something else.

This package is provider-agnostic: it logs through Microsoft.Extensions.Logging so you can keep using your existing logging stack (Serilog, NLog, Application Insights, Seq, etc.) via normal logging providers.

Features

• ✅ OWASP-aligned security event vocabulary
• ✅ Structured logging via ILogger scopes/properties
• ✅ Works with any Microsoft.Extensions.ILogger provider (NLog, Serilog, etc.)

Getting Started

Installation

This package is published and installed via NuGet.

Reference the package in your project:

dotnet add package ByteGuard.SecurityLogger

Usage

Instantiate a new SecurityLogger instance using either the constructor or the ILogger extensions: AsSecurityLogger().

ILogger logger = /* resolve or create ILogger */

var configuration = new SecurityLoggerConfiguration
{
    AppId = "MyApp"
}

// Using constructor
var securityLogger = new SecurityLogger(logger, configuration);

// Using ILogger extensions
var securityLogger = logger.AsSecurityLogger(configuration);

Log your security events:

var user = //...

securityLogger.AuthnLoginSuccess(
    "User {UserId} successfully logged in.",
    userId: user.Id,
    args: user.Id
)

API Design

ByteGuard.SecurityLogger implements the full OWASP Logging Vocabulary: every event type defined by OWASP exists as a corresponding method on SecurityLogger.

One method per event (plus an overload with metadata)

For each OWASP event type, SecurityLogger exposes two overloads:

1. A minimal overload for logging the event with just the event label parameters.

securityLogger.Log{event}(
    string message,
    /* event label arguments (varies by event) */,
    params object?[] args
)

2. An overload that additionally accepts a SecurityEventMetadata object for richer, OWASP-recommended context (client IP, hostname, request URI, etc.).

securityLogger.Log{event}(
    string message,
    /* event label arguments (varies by event) */,
    SecurityEventMetadata metadata,
    params object?[] args
)

Parameter order (always the same)

Example

If an event label requires a userId, the call becomes:

// Providing user ID produces label: authn_login_success:userOne
var userId = "userOne";
securityLogger.LogAuthnLoginSuccess(
    "User {UserId} logged in successfully from {Ip}",   // Message template
    userId,                                             // Label parameters
    userId, ip);                                        // Template args

// Without providing user ID produces label: authn_login_success
securityLogger.LogAuthnLoginSuccess(
    "User {UserId} logged in successfully from {Ip}",   // Message template
    null,                                               // Label parameters
    userId, ip);                                        // Template args

If you want to add OWASP-style context, use the metadata overload:

securityLogger.LogAuthnLoginSuccess(
    "User {UserId} logged in successfully from {Ip}",   // Message template
    userId,                                             // Label parameters
    new SecurityEventMetadata                           // Event metadata
    {
        SourceIp = ip,
        Hostname = host,
        RequestUri = requestUri
    },
    userId, ip);                                        // Template args

ℹ️ Note: The exact label arguments vary per event type, based on the OWASP Logging Vocabulary definition.

Configuration

The SecurityLogger supports the following configurations:

Supported events

All supported events can be seen in the WIKI

License

ByteGuard.SecurityLogger is Copyright © ByteGuard Contributors - Provided under the MIT license.