Redaction code is not proof that sensitive values stayed out of logs. LogLeak lets a test register synthetic sensitive values, exercise the real Microsoft logging path, and fail safely if any registered value survives into supported log fields.
dotnet add package KeelMatrix.LogLeak
dotnet add package Microsoft.Extensions.LoggingThe second package supplies the AddLogging registration API used by the quick start.
using KeelMatrix.LogLeak;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Logging;
using var probe = new LogLeakProbe()
.AddSecret("authorization", "synthetic-test-value");
using var services = new ServiceCollection()
.AddLogging(builder => builder.AddProvider(probe.Provider))
.BuildServiceProvider();
services.GetRequiredService<ILoggerFactory>()
.CreateLogger("PaymentClient")
.LogInformation("request completed");
probe.AssertNoLeaks();LoggerMessage methods use the same provider boundary as ordinary ILogger calls:
using KeelMatrix.LogLeak;
using Microsoft.Extensions.Logging;
namespace KeelMatrix.LogLeak.Documentation;
internal static partial class SourceGeneratedLoggingExample
{
internal static void Run()
{
const string sentinel = "synthetic-logger-value";
using var probe = new LogLeakProbe().AddSecret("token", sentinel);
using var factory = LoggerFactory.Create(builder => builder.AddProvider(probe.Provider));
GeneratedLogging.RequestCompleted(factory.CreateLogger("PaymentClient"));
probe.AssertNoLeaks();
}
private static partial class GeneratedLogging
{
[LoggerMessage(EventId = 42, Level = LogLevel.Information, Message = "request completed")]
internal static partial void RequestCompleted(ILogger logger);
}
}Use synthetic values created only for tests. A planted value produces a safe LogLeakAssertionException containing the registration label, broad leak location, and safe logging metadata. The value, complete message, exception payload, and surrounding state are never included.
Registration labels are safe identifiers limited to 64 characters using letters, digits, -, _, ., and :. No registered label may textually contain a registered value, and no registered value may textually contain a registered label. The rule uses exact ordinal comparison (case-sensitive, with no normalization) and is checked at every registration in either order.
Registration freezes when the first event is captured or verification starts. A later AddSecret call throws LogLeakConfigurationException; this prevents retained findings from being reinterpreted under a changed sentinel set.
The supported boundary is intentionally frozen to:
- formatted message output, including message templates and source-generated
LoggerMessagecalls; - the string representation of a logging exception.
Structured state and scopes are separate supported surfaces:
- structured state inspects direct string values in
IEnumerable<KeyValuePair<string, object?>>andIEnumerable<KeyValuePair<string, string>>, excluding reserved{OriginalFormat}metadata; a state object matching both interfaces is inspected once; - scopes inspect plain strings, templated direct string values such as
logger.BeginScope("Authorization {Token}", value), and direct string values in the same two enumerable shapes, includingDictionary<string, string>andIReadOnlyDictionary<string, string>.
Matching is exact ordinal literal matching. Non-string state or scope values and opaque objects are excluded; LogLeak does not recursively serialize objects, decode, normalize, hash, encode, or infer unregistered secrets. A sentinel held only in an excluded shape such as Dictionary<string, int> can therefore produce a clean result. It does not inspect arbitrary sinks.
The deterministic resource contract is identical on net8.0 and netstandard2.0: by default, at most 128 sentinels may be registered, each sentinel is at most 4,096 UTF-16 characters, each inspected text unit is at most 4,096 UTF-16 characters, each event may inspect 1,024 units and retain 256 findings, the probe may retain 4,096 findings overall, and 4,096 events may complete inspection. LogLeak does not use a process-wide heap delta or transient-allocation measurement. A bound breach returns Inconclusive and never Clean. If a formatter or exception representation synchronously logs through the same probe, the nested capture is rejected without consuming capture or per-event budgets and verification becomes sticky Inconclusive with a safe reentrancy reason.
Verification requested from a formatter, exception representation, state enumeration, or scope enumeration callback returns Inconclusive and does not request telemetry while capture is active. A scope handle returned by BeginScope is opaque and its disposal still removes the observed scope.
Only a clean verification requests best-effort activation and weekly heartbeat signals through KeelMatrix.Telemetry. Detected leaks and inconclusive captures do not request activation or heartbeat telemetry. LogLeak sends no sentinel, log content, exception text, category, event name, or property value. Core verification requires no network. Set KEELMATRIX_NO_TELEMETRY=1 to opt out.
LogLeak verifies only the captured Microsoft.Extensions.Logging provider boundary. It does not inspect arbitrary downstream sinks or discover unregistered sensitive data. The package targets net8.0 and netstandard2.0.
Register probe.Provider before opening any scopes that the probe should observe. Scopes opened before provider registration are outside the declared observed boundary and may result in a clean verification even when they contain a registered sentinel. Within the observed boundary, only the shallow state and scope forms above are inspected. Dictionary support for scopes does not imply dictionary support for state unless the state itself implements one of the two documented enumerable shapes; non-string and opaque shapes remain excluded and can therefore produce a clean result when a sentinel is held only in that value.
An Inconclusive result means LogLeak could not prove a clean result; it is never treated as clean. Check the safe InconclusiveReason before changing limits:
- A capture, payload, inspection-unit, or finding limit was reached: reduce the logged work or increase only the specific
LogLeakOptionslimit when the test can safely handle the additional bounded memory and processing. - Same-probe reentrant logging was detected: remove logging from the formatter, exception representation, state enumeration, or scope enumeration callback that logs through the same probe.
- Verification was requested while capture or one of those callbacks was active: let the logging call and its callbacks finish, then call
Verify()orAssertNoLeaks()afterward. - A formatter, exception representation, structured-state enumeration, or scope enumeration callback failed: correct that callback and rerun the verification; do not expose the original sensitive input while diagnosing it.
MIT
The shipping coverage corpus runs against the shipping KeelMatrix.LogLeak implementation through tests/LogLeak.Probe.Runner:
dotnet run --project tests/LogLeak.Probe.Runner/LogLeak.Probe.Runner.csproj -c Release --no-restore
The shipping package is under src/KeelMatrix.LogLeak. Focused contract tests are under tests/KeelMatrix.LogLeak.Tests; the corpus and package gate are the release-equivalent integration checks.