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)

Parameter	Description
message	The human readable log message (typically a message template)
Event label arguments	These are the values required to form the OWASP event label, e.g.: authn_login_success:{userId} and authz_fail:{userId,resource} (depending on the even type). These are all nullable and will not be present in the label if provided as null.
metadata	Additional structured context recommended by OWASP (source IP, host, request URI, etc.) (Only in the metadata method overload)
args	The message template arguments from the 1st parameters

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:

Configuration	Required	Default	Description
AppId	Yes	N/A	Application identifier added to the log message, to ensure logs are easy to find for the given application
DisableSourceIpLogging	No	true	Whether to log the SourceIp if provided (logging user IP address may be useful for detection and response, but may be considered personally identifiable information when combined with other data and subject to regulation or deletion requests)

Supported events

All supported events can be seen in the WIKI

License

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