AnointedAutomation.APIMiddlewares
1.2.1
See the version list below for details.
dotnet add package AnointedAutomation.APIMiddlewares --version 1.2.1
NuGet\Install-Package AnointedAutomation.APIMiddlewares -Version 1.2.1
<PackageReference Include="AnointedAutomation.APIMiddlewares" Version="1.2.1" />
<PackageVersion Include="AnointedAutomation.APIMiddlewares" Version="1.2.1" />
<PackageReference Include="AnointedAutomation.APIMiddlewares" />
paket add AnointedAutomation.APIMiddlewares --version 1.2.1
#r "nuget: AnointedAutomation.APIMiddlewares, 1.2.1"
#:package AnointedAutomation.APIMiddlewares@1.2.1
#addin nuget:?package=AnointedAutomation.APIMiddlewares&version=1.2.1
#tool nuget:?package=AnointedAutomation.APIMiddlewares&version=1.2.1
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:
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)
| Type | What it does |
|---|---|
ApiKeyAuthMiddleware |
Constructor (RequestDelegate next, string headerName, string expectedKey, string protectedPathPrefix). Requests whose path starts with the prefix must send the header with the exact key or get 401. Uses CryptographicOperations.FixedTimeEquals. Also exposes static bool IsAuthorized(string presentedKey, byte[] expectedKey). The prefix must start with /. Since 1.2.0 a null or empty expectedKey throws ArgumentException when the pipeline is built, so a missing key crashes at startup instead of answering 401 to every request. |
IPBlacklistMiddleware |
Returns 403 for any client IP in IPBlacklist. Also owns the shared middleware log buffer: static AddLog(LogMessage), static GetLogs(), static ClearLogs(), and the static events LogAdded and LogCleared. |
InvalidEndpointTrackerMiddleware |
Returns 403 for blacklisted IPs. After the rest of the pipeline runs, records a failed attempt for a 404 with an empty body (except /), a 401 or a 403. An IP is banned after 10 failed attempts, or immediately if it requests a path ending in .env. Attempt counts and logs reset every 24 hours. static ClearFailedAttempts() resets counts. |
AttemptInfo |
Attempt record for one IP: int Count, HashSet<string> Paths. |
EndpointAccessMiddleware |
Constructor (RequestDelegate next, TimeSpan? timeout, bool cleanMem = false). Records the last access time per path. When cleanMem is true, a one minute timer runs AnointedAutomation.Optimization.Memory.GarbageCollection.PerformGarbageCollection once every endpoint has been idle longer than timeout. static bool HasBeenHitRecently(string path) reports whether a path was hit in the last 5 minutes. |
Filters (AnointedAutomation.APIMiddleware.Filters)
| Type | What it does |
|---|---|
APIKeyAttribute |
[APIKey] action filter for controllers or actions. Reads the header name from the API_KEY_NAME environment variable and the expected key from API_KEY; a missing or wrong key returns 401 and logs a warning with the client IP. |
Objects (AnointedAutomation.APIMiddleware.Objects)
| Type | What it does |
|---|---|
IPBlacklist |
Static in memory blacklist: AddBannedIP(string ip, string reason), RemoveBannedIP(string ip), IsIPBlocked(string ipAddress), GetBlockReason(string ipAddress), ClearBlacklist(), and the events IPBanned (EventHandler<BannedIP>) and IPUnbanned (EventHandler<string>). |
BannedIP |
_id, Ipv4, Ipv6, Reason. Handy as a persistence shape for bans. |
Utility (AnointedAutomation.APIMiddleware.Utility)
| Type | What it does |
|---|---|
APIUtility |
GetClientPublicIPAddress(HttpContext) and GetClientPublicIPAddress(ActionExecutingContext). Uses the first X-Forwarded-For value, then RemoteIpAddress. Returns 198.51.100.255 for ::1 or when no IP is available, and logs why. |
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.
Honeypot and bot defense
Reusable, opt in pieces. Nothing is active until you turn it on, and every block is logged at Warning with the IP, the rule and the path (no silent drops).
Middleware: honeypot routes, User-Agent rules, rate limits
{
"BotDefense": {
"Enabled": true,
"ExemptPaths": [ "/health" ],
"HoneypotPaths": { "Enabled": true, "BanDuration": "1.00:00:00" },
"UserAgent": { "Enabled": true, "BlockEmpty": false },
"RateLimit": {
"Enabled": true,
"PerIpLimit": 300,
"PerIpWindow": "00:01:00",
"Routes": [ { "PathPrefix": "/api/auth", "Limit": 10, "Window": "00:05:00" } ]
},
"ClientIp": { "TrustedProxyProviders": [ "Cloudflare" ], "HonorCfConnectingIp": true }
}
}
using AnointedAutomation.APIMiddleware.BotDefense;
builder.Services.AddBotDefense(builder.Configuration.GetSection("BotDefense"));
app.UseBotDefense();
- Order: exempt paths, verified crawlers, ban check, honeypot routes, User-Agent rules, rate limits.
- Lists you configure (
HoneypotPaths.Paths,HoneypotPaths.FileNames,UserAgent.GoodCrawlers) REPLACE the built-in defaults; leave one empty to use the defaults. - Honeypot routes: a hit on
/wp-admin,/wp-login.php,/xmlrpc.php,/phpmyadmin,/.git,/cgi-bin(setPaths) or on a file named.env,.gitor.awsat any depth (setFileNames) bans that IP forBanDurationand answersResponseStatus(404). Paths match by segment, so/wp-administratoris not a hit. Only enable this on routes your own site never uses. - Zip bomb: set
HoneypotPaths.ServeEnvZipBombto answer a honeypot hit on a.env*file with a generated zip (one.enventry ofZipBombExpandedByteszeros, default 512 MiB, about 0.5 MB on the wire) instead of the empty response. It is built in code on first use and cached; no binary is stored in the repo. - User-Agent rules: blocks a built-in list of scanner tools (sqlmap, nikto, nmap, masscan, nuclei and similar; generic clients such as curl and python-requests are deliberately not listed), your own
BlockedFragments, and optionally an empty User-Agent.GoodCrawlers(Googlebot, Bingbot, Applebot, YandexBot, Baiduspider by default) pass every rule, honeypots and bans included, only after reverse DNS confirms them (the PTR name must end in the crawler's documented domain and resolve forward to the same IP; results are cached for 12 hours, at most 10,000 entries). A request that claims to be one but fails the check is blocked as spoofed. A DNS failure is logged at Warning and counts as unverified. - Rate limits: fixed window per IP (
PerIpLimit) and per route prefix (longest matching prefix wins). Over the limit returns429withRetry-After. The table is capped at 50,000 keys; when it is full of live windows, expired ones are swept (at most every 30 seconds), and new keys are admitted uncounted with a logged Warning rather than growing memory. - Ban store:
IBanStore(GetBanAsync,BanAsync,UnbanAsync). The defaultInMemoryBanStoreis per process and capped at 100,000 bans. For bans that survive restarts or are shared between instances, implementIBanStoreover Mongo, Redis or any store and register it beforeAddBotDefense. If the store throws, the failure is logged at Error andBlockWhenBanStoreFailsdecides (false lets the request through, true answers503). - Client IP and exempt paths follow the same trusted proxy rules as the IP allowlist.
Form honeypot field and timing check
builder.Services.AddFormBotGuard(options =>
{
options.Enabled = true;
options.HoneypotFieldName = "website";
options.MinSubmitSeconds = 3;
options.SigningKey = Environment.GetEnvironmentVariable("FORM_GUARD_KEY"); // at least 16 characters, from your secret store
});
// Render: put guard.CreateTimingToken() in a hidden "t" field, and a "website" input hidden with CSS.
// Submit:
FormBotCheckResult result = guard.Check(HttpContext, form["website"], form["t"]);
if (result != FormBotCheckResult.Ok)
{
return Ok(new { success = true }); // fake success: the bot learns nothing. The attempt is already logged.
}
A filled honeypot field is a bot, a form submitted faster than MinSubmitSeconds is a bot, and a missing, forged (HMAC signed) or expired timing token counts as a bot when the timing check is on.
Captcha verification
builder.Services.AddCaptchaVerifier(options =>
{
options.Provider = CaptchaProvider.ReCaptchaV3; // or Turnstile, HCaptcha
options.SecretKey = Environment.GetEnvironmentVariable("CAPTCHA_SECRET");
options.MinScore = 0.5;
});
CaptchaResult verdict = await captcha.VerifyAsync(token, remoteIp, cancellationToken);
if (!verdict.Success) { /* reject, verdict.Reason says why */ }
reCAPTCHA v3, Cloudflare Turnstile and hCaptcha share the same siteverify protocol, so ICaptchaVerifier covers all three. When the provider returns a score (reCAPTCHA v3 always does) it must be at or above MinScore. A provider outage, HTTP error or unreadable answer logs at Error and fails closed.
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.
IP allowlist (IpAllowlistMiddleware)
Blocks every request from an IP that is not on the allowlist (403, logged at Warning with the IP, method, path and reason). Off by default. Entries are single IPs or CIDR ranges, IPv4 and IPv6 (IPv4 must be a full dotted quad: short forms such as 10.1 are rejected at startup), and you can add provider presets for CDNs.
{
"IpAllowlist": {
"Enabled": true,
"Allowlist": [ "203.0.113.0/24", "2001:db8::/32" ],
"Providers": [ "Cloudflare" ],
"ExemptPaths": [ "/health", "/api/webhooks" ],
"ClientIp": { "TrustedProxyProviders": [ "Cloudflare" ], "HonorCfConnectingIp": true },
"RefreshEnabled": true,
"RefreshInterval": "1.00:00:00"
}
}
using AnointedAutomation.APIMiddleware.Security;
builder.Services.AddIpAllowlist(builder.Configuration.GetSection("IpAllowlist"));
// or: builder.Services.AddIpAllowlist(options => { options.Enabled = true; options.Allowlist.Add("203.0.113.7"); });
app.UseIpAllowlist(); // first in the pipeline
- Enabled with an empty
Allowlistand noProviders, an invalid entry or an unknown provider throws whenUseIpAllowlist()runs, so a bad configuration crashes at startup instead of failing open or blocking everyone silently. Allowlistentries are matched against the resolved client IP.Providerspresets are matched against the DIRECT peer: "accept only traffic that arrives through this CDN". WithProviders: ["Cloudflare"]every request that comes through Cloudflare is allowed, whoever the visitor is, and a request that does not come from a Cloudflare address is blocked even if it forges a Cloudflare address in a header. Do not useProviderswhen you want to restrict which visitors get in; useAllowlistfor that (with the CDN as a trusted proxy so the visitor's address is resolved).- Provider presets (shipped ranges, with the source URL and fetch date in
Security/IpProviderPresets.Data.cs):
| Preset | Official source |
|---|---|
Cloudflare |
https://www.cloudflare.com/ips-v4 and https://www.cloudflare.com/ips-v6 |
Fastly |
https://api.fastly.com/public-ip-list |
CloudFront |
https://ip-ranges.amazonaws.com/ip-ranges.json (service CLOUDFRONT) |
Evaluated and not shipped: Google Cloud (cloud.json lists every Google Cloud customer address, not just the CDN, so it is far too broad for an allowlist), Akamai, Vercel and Railway (no official public range list found). Add those through Allowlist yourself.
- Scheduled refresh (
RefreshEnabled,RefreshInterval,RefreshTimeout): the shipped list is the starting set; each interval the provider's published list is downloaded and swapped in only if the whole download parses. Any failure (network, HTTP status, malformed or empty list) is logged at Error with the exception and the last good list stays in use. It never empties the list and never allows everyone. The refresh covers bothProvidersandClientIp.TrustedProxyProviders, so trusted proxy ranges do not go stale. - Client IP:
X-Forwarded-ForandCF-Connecting-IPare honored only when the direct peer is inClientIp.TrustedProxiesor one of theClientIp.TrustedProxyProvidersranges.X-Forwarded-Foris read from the right, skipping trusted hops, so a client cannot forge an earlier entry. With no trusted proxies configured the headers are never used. A request with no resolvable client address is blocked.CF-Connecting-IP(withHonorCfConnectingIp) is believed only when the direct peer is a Cloudflare edge address (the Cloudflare ranges, refreshed when theCloudflarepreset is in use), never from another trusted proxy, which would pass a client's forged header straight through. - Shared CDN ranges are shared: trusting a CDN preset such as
FastlyorCloudFrontas a proxy (or allowing it inProviders) means any customer of that CDN can put a service in front of your origin and supply whateverX-Forwarded-Forit likes. Only trust a shared CDN's ranges when the origin also verifies the CDN is yours (an origin secret header, mutual TLS, or a private origin). ExemptPathsare path prefixes matched by segment, case-insensitively (/healthmatches/health/live, not/healthz).
Notes
- The client IP comes from
X-Forwarded-Forwhen present. Only trust it behind a reverse proxy that sets it. - All state (blacklist, attempt counts, logs) is static and per process.
Country blocking (CountryBlockMiddleware)
Blocks (403) requests by country of origin. Off by default. Mode and UnknownCountry have no default: when enabled you must choose them, so the behavior for unknown countries is always an explicit decision. Every block is logged at Warning with the IP, country and path.
{
"CountryBlock": {
"Enabled": true,
"Mode": "Block",
"Countries": [ "RU", "KP" ],
"UnknownCountry": "Allow",
"ExemptPaths": [ "/health" ],
"UseCfIpCountryHeader": true,
"ClientIp": { "TrustedProxyProviders": [ "Cloudflare" ], "HonorCfConnectingIp": true }
}
}
using AnointedAutomation.APIMiddleware.Security;
builder.Services.AddCountryBlock(builder.Configuration.GetSection("CountryBlock"));
app.UseCountryBlock();
Mode:Blockblocks the listed countries;AllowOnlyallows only the listed ones.Countriesare ISO 3166-1 alpha-2 codes (case-insensitive).UnknownCountry:BlockorAllow, for requests whose country cannot be determined (including a request with no client address and, until the first data load, every request).- Data source: the public "delegated extended" statistics files that the five Regional Internet Registries publish (ARIN, RIPE NCC, APNIC, LACNIC, AFRINIC). No key, no account, and nothing is committed to this repository: the package downloads them at startup and then every
RefreshInterval(7 days by default;RetryInterval15 minutes while nothing has loaded). SetDataUrlsto use mirrors: whatever you list there replaces the five defaults (leave it out to use the defaults). The lookup is built in memory (about 240k IPv4 and 55k IPv6 ranges, a couple of seconds to build). The country is where the registry allocated the block, which is coarser than commercial geolocation: it is good for blocking whole countries, not for finding a city, and a block can be used abroad. - Failure handling: if any file fails to download or has no ranges, the whole refresh is discarded, logged at Error with the exception, and the last good data keeps serving. Until a first successful load the
UnknownCountrysetting decides. - Other data sources considered: MaxMind GeoLite2 (free, but needs an account and license key to download, and its EULA restricts redistribution), DB-IP Lite (CC BY 4.0, needs attribution), IP2Location LITE (account and attribution). To use one, implement
ICountryLookup(one method,string Lookup(IPAddress)), register it beforeAddCountryBlock, and setDownloadRirDatato false. Keep any database file out of source control and point your implementation at its path from your own configuration. UseCfIpCountryHeader: behind Cloudflare, uses theCF-IPCountryheader, but only when the direct peer is a trusted proxy (ClientIp.TrustedProxiesorTrustedProxyProviders) AND a Cloudflare edge address (the refreshed Cloudflare list whenAddIpAllowlistis registered, otherwise the ranges shipped with the package); from any other peer, including a trusted non-Cloudflare load balancer, the header is ignored.XXandT1mean unknown and fall back to the lookup.- Client IP resolution,
ExemptPathsand trusted proxy rules are the same as the IP allowlist (ClientIp,ExemptPaths). Loopback and private-network clients have no country and skip the check unless you setAllowPrivateAddressesto false.
Related packages
- AnointedAutomation.Logging: the
LogMessagetype 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.
| Product | Versions Compatible and additional computed target framework versions. |
|---|---|
| .NET | net10.0 is compatible. net10.0-android was computed. net10.0-browser was computed. net10.0-ios was computed. net10.0-maccatalyst was computed. net10.0-macos was computed. net10.0-tvos was computed. net10.0-windows was computed. |
-
net10.0
- AnointedAutomation.Logging (>= 1.1.0)
- AnointedAutomation.Memory (>= 1.0.8)
NuGet packages
This package is not used by any NuGet packages.
GitHub repositories
This package is not used by any popular GitHub repositories.
| Version | Downloads | Last Updated |
|---|---|---|
| 1.2.2 | 0 | 11/18/2026 |
| 1.2.1 | 542 | 11/13/2026 |
| 1.2.0 | 1,044 | 11/6/2026 |
| 1.1.0 | 384 | 11/4/2026 |
| 1.0.9 | 591 | 10/26/2026 |
| 1.0.8 | 457 | 10/1/2026 |
| 1.0.7 | 136 | 10/1/2026 |
| 1.0.6 | 245 | 9/25/2026 |
| 1.0.5 | 420 | 8/23/2026 |
| 1.0.4 | 733 | 6/23/2026 |
| 1.0.3 | 200 | 6/20/2026 |
| 1.0.2 | 330 | 5/30/2026 |
| 1.0.0 | 653 | 3/15/2026 |
| 0.0.18 | 236 | 3/13/2026 |
| 0.0.17 | 144 | 3/11/2026 |
| 0.0.16 | 539 | 2/20/2026 |
| 0.0.15 | 204 | 2/17/2026 |