NoBrute 2.3.0

NoBrute (by Malte)

Simple and lightweight brute-force protection for .NET 10.
This library will protect defined actions in your MVC controllers, Minimal API endpoints, and Razor Pages by making them inefficient to brute-force.
It will append request times in milliseconds if a local cache entry on the server is found for the same request & request name & method, and the hit count reaches a defined limit (referred to here as "green requests") within a specific time frame.

Requirements

NoBrute requires at least one IMemoryCache or IDistributedCache to be registered in your application. (For obvious reasons, storing the information in the session won't work because bots will never send cookies along with their requests.)

External Libraries
This library uses the following library to achieve its functionality:

• Shouldly

Install

Using the NuGet package manager:

Install-Package NoBrute

Using the .NET CLI:

dotnet add package NoBrute

Enable it in your application:

// Startup.cs / Program.cs

public IServiceProvider ConfigureServices(IServiceCollection services) {
     
    // Use Memory Cache:
    services.AddMemoryCache();
    // Or a distributed cache (NoBrute will prefer this if both are registered)
    services.AddStackExchangeRedisCache(x =>
    {
        x.Configuration = "... ";
    }); // In this case, we used Redis as an example

    // MVC only (default):
    services.AddNoBrute();

    // Or configure which filters to register:
    services.AddNoBrute(options =>
    {
        options.UseMvc = true;              // Register MVC action filter (default: true)
        options.UseRazorPages = true;       // Register Razor Pages filter (default: false)
        options.MaxTrackedEntries = 50000;  // Circuit breaker (default: from configuration, 0 = unlimited)
        options.ClientIp = new NoBruteClientIpOptions { UseForwardedHeaders = true };
    });
}

Configuration

No configuration is required to use NoBrute. Here is a JSON example for your appsettings.json to configure NoBrute and the default values used if the entry does not exist in your configuration:

{
  "NoBrute": {
    "Enabled": true,
    "GreenRetries": 10,
    "IncreaseRequestTime": 20,
    "MaxIncreaseRequestTime": 0,
    "TimeUntilReset": 2,
    "TimeUntilResetUnit": "H",
    "MaxTrackedEntries": 0,
    "BlockedStatusCode": 429,
    "StatusCodesForAutoProcess": [
      200
    ],
    "ClientIp": {
      "UseForwardedHeaders": false,
      "Headers": [ "CF-Connecting-IP", "X-Forwarded-For" ],
      "ForwardLimit": 1,
      "KnownProxies": [],
      "KnownNetworks": [],
      "TrustLoopback": true
    }
  }
}

Configuration Entries and Their Meanings

Running Behind Cloudflare, a Load Balancer or a Reverse Proxy

NoBrute stores one cache entry per client IP. Behind a proxy, HttpContext.Connection.RemoteIpAddress is the proxy, so without further configuration every visitor shares a single entry and honest customers would be slowed down after a few requests worldwide.

Enable forwarded headers to make NoBrute use the real client address:

{
  "NoBrute": {
    "ClientIp": {
      "UseForwardedHeaders": true,
      "Headers": [ "CF-Connecting-IP", "X-Forwarded-For" ],
      "ForwardLimit": 1,
      "KnownNetworks": [ "173.245.48.0/20", "103.21.244.0/22" ]
    }
  }
}

Security note: forwarded headers are attacker controlled. Always list your proxy in KnownProxies or KnownNetworks (for Cloudflare: their published IP ranges). If both lists are empty, NoBrute accepts the headers from every peer and logs a warning during startup — anyone able to reach the application directly could then send a random client IP per request and bypass the protection completely.

You can also configure this in code, or replace the resolution entirely by registering your own INoBruteClientIpResolver before calling AddNoBrute():

services.AddNoBrute(options =>
{
    options.ClientIp = new NoBruteClientIpOptions
    {
        UseForwardedHeaders = true,
        KnownNetworks = { "173.245.48.0/20" }
    };
});

Circuit Breaker: Limiting Tracked Clients

A botnet using millions of distinct source addresses would otherwise flood the memory cache or Redis with temporary entries. Set MaxTrackedEntries to cap how many clients are tracked at the same time per application instance:

{
  "NoBrute": {
    "MaxTrackedEntries": 50000,
    "BlockedStatusCode": 429
  }
}

Once the limit is reached, already known clients keep being processed normally, while requests from new clients are answered immediately with BlockedStatusCode (default 429 Too Many Requests) without allocating another cache entry. Entries free their slot when they expire (TimeUntilReset) or when they are released via auto-processing.

All cache entries are written with an absolute expiration of TimeUntilReset, so nothing lingers in memory or Redis forever.

The check result exposes this state as NoBruteRequestCheck.IsBlocked / BlockedStatusCode, and all three filters short-circuit the request when it is set. If you need a different strategy, register your own INoBruteEntryLimiter before calling AddNoBrute().

Note: the limit is counted per application instance. In a web farm sharing one Redis, size it per instance (e.g. four instances × 50.000 = up to 200.000 entries in Redis). Because the counter is local, a client that is known to Redis but not to a restarted instance is treated as a new client — while the limit is reached it would be blocked there until it is tracked again.

Usage

The Action Filter Attribute (Web API or MVC)

To protect an action, you can use the NoBruteAttribute.
This is the simple way.

Arguments:

Examples

Generated Name

[NoBrute]
public IHttpActionResult Login() {
    ...
}

Generated Name with Auto Release

[NoBrute(true)]
public IHttpActionResult Login() {
    ...
}

Fixed Name

[NoBrute("MyFixedName")]
public IHttpActionResult Login() {
    ...
}

Fixed Name with Auto Release

[NoBrute("MyFixedName", true)]
public IHttpActionResult Login() {
    ...
}

The Endpoint Filter (Minimal API)

To protect a Minimal API endpoint, use the WithNoBrute() extension method on the route handler builder.

Arguments:

Examples

Generated Name with Auto Release

app.MapPost("/login", (LoginRequest req) => {
    ...
}).WithNoBrute();

Fixed Name

app.MapPost("/login", (LoginRequest req) => {
    ...
}).WithNoBrute("LoginEndpoint");

Fixed Name with Auto Release disabled

app.MapPost("/login", (LoginRequest req) => {
    ...
}).WithNoBrute("LoginEndpoint", false);

The Page Filter (Razor Pages)

To protect a Razor Page, use the NoBrutePageFilter. You can register it globally or apply it to individual pages.

Arguments:

Examples

Register globally for all pages

builder.Services.AddRazorPages(options =>
{
    options.Filters.Add(new NoBrutePageFilter("GlobalPages", true));
});

The Service

If you have a more complex design to decide when a request should be checked or not, you can also use the service.

Inject Service

private readonly INoBrute nobrute;

public MyController(INoBrute nobrute) {
    this.nobrute = nobrute;
}

Use it in the Method:

public async Task<IActionResult> MyAction() {
    if (1 > 0)  // or some if-else logic
    {
        NoBruteRequestCheck check = await this.nobrute.CheckRequestAsync("MyActionRequestName");

        if (check.IsBlocked)
        {
            return StatusCode(check.BlockedStatusCode);
        }

        if (!check.IsGreenRequest)
        {
            await Task.Delay(check.AppendRequestTime, HttpContext.RequestAborted);
        }

        // Some more logic
    }
}

The CheckRequestAsync method will return an object of type NoBruteRequestCheck.
It will contain the flag IsGreenRequest and how much time to append to the request, the IsBlocked flag for the circuit breaker, and some user information like the resolved client IP.

The service checks and releases requests for you but never delays them — that is up to you here. Always use await Task.Delay(...), never Thread.Sleep(...): Thread.Sleep blocks an operating system thread, so a large bot wave would exhaust the Kestrel thread pool (thread starvation) and take the whole application down. Task.Delay releases the thread for other customers while the attacker waits.

All three filters (NoBruteAttribute, NoBruteEndpointFilter, NoBrutePageFilter) already work this way — they only implement the asynchronous filter interfaces, which ASP.NET Core prefers anyway, and they use the asynchronous cache API (GetAsync/SetAsync) so a slow Redis never blocks a thread either.

Synchronous CheckRequest, ReleaseRequest and AutoProcessRequestRelease still exist for compatibility. Avoid them in request pipelines: with an IDistributedCache they block the calling thread while waiting for the cache.

See more at /src/Domain/INoBrute.cs and /src/Models/NoBruteRequestCheck.cs in the GitHub repository.

Contribute / Donations

If you have any ideas to improve my projects, feel free to send a pull request.

If you like my work and want to support me (or want to buy me a coffee/beer), PayPal donations are more than appreciated.

](https://www.nuget.org/packages/NoBrute/)