AnointedAutomation.APIMiddlewares 1.0.9

AnointedAutomation.APIMiddlewares

Jesus is King ✝️

ASP.NET Core middleware and filters for protecting small APIs: API key authentication, an in memory IP blacklist, automatic banning of clients that probe for endpoints that do not exist, and optional garbage collection when the API has been idle.

Installation

dotnet add package AnointedAutomation.APIMiddlewares

• Target framework: net10.0
• Framework reference: Microsoft.AspNetCore.App (ASP.NET Core shared framework)
• Dependencies:
  • AnointedAutomation.Logging
  • AnointedAutomation.Memory

Quick start

using System;
using AnointedAutomation.APIMiddleware;
using Microsoft.AspNetCore.Builder;

WebApplicationBuilder builder = WebApplication.CreateBuilder(args);
builder.Services.AddControllers();
WebApplication app = builder.Build();

// Reject blacklisted IPs with 403 before anything else runs.
app.UseMiddleware<IPBlacklistMiddleware>();

// Count 404/401/403 responses per IP and ban repeat offenders.
app.UseMiddleware<InvalidEndpointTrackerMiddleware>();

// Require an API key header on everything under /api (constant-time comparison).
app.UseMiddleware<ApiKeyAuthMiddleware>(
    "X-Api-Key",                                          // header name
    Environment.GetEnvironmentVariable("MY_API_KEY"),     // expected key
    "/api");                                              // protected path prefix

// Track endpoint hits; run a GC when every endpoint has been idle for 10 minutes.
app.UseMiddleware<EndpointAccessMiddleware>((TimeSpan?)TimeSpan.FromMinutes(10), true);

app.MapControllers();
app.Run();

Note the namespace: the code lives in AnointedAutomation.APIMiddleware (singular), even though the package id is AnointedAutomation.APIMiddlewares.

API overview

Middleware (AnointedAutomation.APIMiddleware)

Filters (AnointedAutomation.APIMiddleware.Filters)

Objects (AnointedAutomation.APIMiddleware.Objects)

Utility (AnointedAutomation.APIMiddleware.Utility)

Using the [APIKey] filter

using AnointedAutomation.APIMiddleware.Filters;
using Microsoft.AspNetCore.Mvc;

[APIKey]
[ApiController]
[Route("[controller]")]
public class SecureController : ControllerBase
{
    [HttpGet]
    public IActionResult Get() => Ok("Secure data");
}

Required environment variables:

API_KEY_NAME=X-Api-Key
API_KEY=your-secret-key

ApiKeyAuthMiddleware is the newer option: it takes its values as arguments instead of reading environment variables, and compares keys in constant time.

Persisting and observing bans

The blacklist is in memory and is lost on restart. Use the events to persist bans and reload them at startup:

using System;
using AnointedAutomation.APIMiddleware;
using AnointedAutomation.APIMiddleware.Objects;
using AnointedAutomation.Optimization.Logging;

IPBlacklist.IPBanned += (sender, banned) =>
    Console.WriteLine($"Banned {banned.Ipv4}: {banned.Reason}");

IPBlacklist.AddBannedIP("203.0.113.7", "Loaded from database");

IPBlacklistMiddleware.LogAdded += (sender, e) =>
    Console.WriteLine($"[{e.log.messageType}] {e.log.message}");

IPBlacklistMiddleware.AddLog(LogMessage.Warning("Suspicious activity detected."));

Note that IPBlacklistMiddleware.ClearLogs() and IPBlacklist.ClearBlacklist() also remove every event subscriber, and InvalidEndpointTrackerMiddleware calls ClearLogs() during its 24 hour reset, so resubscribe to IPBlacklistMiddleware.LogAdded if you rely on it long term.

Notes

• The client IP comes from X-Forwarded-For when present. Only trust it behind a reverse proxy that sets it.
• All state (blacklist, attempt counts, logs) is static and per process.

Related packages

• AnointedAutomation.Logging: the LogMessage type used for the middleware log buffer.
• AnointedAutomation.Memory: the garbage collection helper used by EndpointAccessMiddleware.
• AnointedAutomation.Objects.API: ASP.NET Core helpers such as the shared JSON casing convention.

License

MIT. See LICENSE.

Support This Project

This library is free and open source. The best way to support the work is to shop with us:

• Christian items: https://store.anointed.company
• Pets: https://www.animaldander.com
• Everything else: https://www.mart.club

Found a bug or have a request? Open an issue at https://github.com/AnointedAutomation/AnointedAutomation/issues.