Eigenverft.Routed.RequestFilters 0.2.0.1-gbd73c3e2b5

🛡️ Eigenverft.Routed.RequestFilters

Composable request filtering, filter evaluation, enforcement, and filter-event storage for ASP.NET Core applications.

Important: This project is currently pre-1.0. Public APIs, option names, defaults, and configuration behavior may change between preview releases.

✨ At a glance

The library is designed for applications that want to compose focused request policies instead of adopting one monolithic request-processing pipeline. Each component is registered explicitly and added to the pipeline explicitly.

🧭 Contents

• Installation
• Quick start
• How filtering works
• Common recipes
• Middleware catalog
• Evaluation and event storage
• Pipeline ordering
• Build from source
• Security notes

📦 Installation

dotnet add package Eigenverft.Routed.RequestFilters

The package provides assets for:

• net8.0
• net10.0

It uses the ASP.NET Core shared framework.

🚀 Quick start

Every middleware follows the same basic pattern:

1. Register it with Add....
2. Configure its matching and enforcement policy.
3. Add it to the request pipeline with Use....

The following example allows only the configured host names.

Program.cs

using Eigenverft.Routed.RequestFilters.Middleware.HostNameFiltering;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddHostNameFiltering();

var app = builder.Build();

app.UseHostNameFiltering();

app.MapGet("/", () => Results.Ok(new { status = "ready" }));

app.Run();

appsettings.json

{
  "HostNameFilteringOptions": {
    "Whitelist": [
      "api.example.com",
      "*.example.com"
    ],
    "Blacklist": [],
    "AllowBlacklistedRequests": false,
    "AllowUnmatchedRequests": false,
    "BlockStatusCode": 403
  }
}

The parameterless AddHostNameFiltering() registration binds the section named HostNameFilteringOptions. The example allows requests matching the whitelist and rejects unmatched or blacklisted hosts.

Caution: Registration alone is not an implicit deny policy. Many filters are intentionally observable by default. Set the relevant Allow... flags explicitly before relying on a filter for enforcement.

🔍 How filtering works

Most filtering middleware classifies an observed request value as one of three results:

The corresponding options then determine whether the request is allowed, recorded, logged, or short-circuited with BlockStatusCode. When a value appears in both lists, FilterPriority controls which result wins.

Option names differ slightly between components, but the recurring controls are:

• Whitelist and Blacklist
• FilterPriority
• AllowBlacklistedRequests
• AllowUnmatchedRequests
• RecordBlacklistedRequests
• RecordUnmatchedRequests
• per-result log levels
• BlockStatusCode

Configuration forms

Most middleware components expose these registration forms:

// Bind the conventional XOptions configuration section.
builder.Services.AddHostNameFiltering();

// Bind configuration, then apply code-based overrides.
builder.Services.AddHostNameFiltering(options =>
{
    options.Whitelist = new() { "api.example.com" };
    options.AllowUnmatchedRequests = false;
});

// Bind from an explicitly supplied configuration root, then override values.
builder.Services.AddHostNameFiltering(
    builder.Configuration,
    options => options.BlockStatusCode = StatusCodes.Status403Forbidden);

Several middleware components also provide UseX(Action<XOptions>). That overload adds a pipeline-local configuration layer on top of the DI-registered options.

Configuration-bound middleware uses options monitoring. Reloadable configuration sources can therefore update values without rebuilding the middleware pipeline.

Pattern syntax

String-based filters use anchored wildcard patterns rather than raw regular expressions:

Examples:

Matching is anchored to the complete observed value. Matching is case-insensitive by default where the corresponding options expose a case-sensitivity switch.

🧩 Common recipes

Configure a filter entirely in code

using Eigenverft.Routed.RequestFilters.Middleware.HttpMethodFiltering;

builder.Services.AddHttpMethodFiltering(options =>
{
    options.Whitelist = new() { "GET", "HEAD" };
    options.AllowBlacklistedRequests = false;
    options.AllowUnmatchedRequests = false;
    options.BlockStatusCode = StatusCodes.Status405MethodNotAllowed;
});

Add the matching middleware before the endpoints it protects:

app.UseHttpMethodFiltering();
app.MapControllers();

Filter client IP addresses behind a reverse proxy

Configure trusted forwarded headers before remote-IP or CIDR filters. The host application remains responsible for defining trusted proxies and networks.

app.UseForwardedHeaders();
app.UseRemoteIpAddressFiltering();
app.UseCidrFiltering();

Never accept arbitrary forwarded headers from untrusted networks. Incorrect proxy trust configuration can make client-IP policies ineffective.

Record filter events and evaluate them later

using Eigenverft.Routed.RequestFilters.Middleware.FilteringEvaluationGate;
using Eigenverft.Routed.RequestFilters.Middleware.HostNameFiltering;
using Eigenverft.Routed.RequestFilters.Services.FilteringEvaluation.FilteringEvaluators;
using Eigenverft.Routed.RequestFilters.Services.FilteringEvent.FilteringStorage;

builder.Services.AddFilteringEventStorage<InMemoryStorage>();
builder.Services.AddFilteringEvaluator(FilteringEvaluatorKind.SimpleFilteringScore);
builder.Services.AddHostNameFiltering();
builder.Services.AddFilteringEvaluationGate();

var app = builder.Build();

app.UseHostNameFiltering();
app.UseFilteringEvaluationGate();

Use NullStorage when events should be discarded, InMemoryStorage for process-local bounded storage, or SqliteStorage when events must survive process restarts. Evaluator and storage selection use a last-call-wins model.

🧰 Middleware catalog

Request classification and filtering

Filter orchestration

Each component has a dedicated namespace below:

Eigenverft.Routed.RequestFilters.Middleware.<ComponentName>

This keeps imports and registrations explicit and lets consumers include only the components they use.

📊 Evaluation and event storage

Individual filters can emit FilteringEvent records. An evaluator can aggregate the events associated with an observed remote address and produce an allow/block decision for FilteringEvaluationGate.

Evaluators

Register exactly one active evaluator:

builder.Services.AddFilteringEvaluator(
    FilteringEvaluatorKind.SourceAndMatchKindWeighted);

Event storage

Register exactly one active storage:

builder.Services.AddFilteringEventStorage<SqliteStorage>();

Configurable backends bind their conventional sections:

• InMemoryFilteringEventStorageOptions
• InSqliteDbFilteringEventStorageOptions
• SourceAndMatchKindWeightedFilteringEvaluatorOptions

FilteringEvaluationGate can enforce the evaluator result or run in allow-through mode. Allow-through mode is useful for observing a new policy before enabling blocking.

🔀 Pipeline ordering

Middleware order is part of the policy. A typical application should consider this sequence:

1. Configure trusted forwarded headers when running behind a reverse proxy.
2. Apply inexpensive request classifiers and filters.
3. Apply FilteringEvaluationGate after the filters whose events it evaluates.
4. Map application endpoints and resources after the filters that should protect them.

A minimal composed pipeline might look like this:

app.UseForwardedHeaders();
app.UseHostNameFiltering();
app.UseUserAgentFiltering();
app.UseFilteringEvaluationGate();

app.MapControllers();

Only include middleware that has been registered and configured for the application. Filters that need the peer address insert the shared ClientNetwork feature once; proxy trust and forwarded-header ordering remain the host application's responsibility.

🧭 Scope boundary

Application hosting, Kestrel/SNI, certificates, configuration-source composition, startup logging, static-file serving, warm-up, health probes, canonical redirects, general request logging, and traffic shaping are intentionally outside this package. Applications that need those capabilities reference their dedicated WebLib or NetLib packages directly; they are not forwarded or transitively exposed by RequestFilters.

🧪 Build from source

git clone https://github.com/eigenverft/Eigenverft.Routed.RequestFilters.git
cd Eigenverft.Routed.RequestFilters

dotnet restore src/Eigenverft.Routed.RequestFilters.slnx
dotnet build src/Eigenverft.Routed.RequestFilters.slnx -c Release --no-restore

Create a local NuGet package with repository pack metadata enabled:

dotnet pack src/prj/Eigenverft.Routed.RequestFilters/Eigenverft.Routed.RequestFilters.csproj -c Release -p:Stage=pack

Main source layout:

src/
├── Eigenverft.Routed.RequestFilters.slnx
└── prj/
    ├── Eigenverft.Routed.RequestFilters/
    │   ├── Middleware/
    │   └── Services/
    └── Eigenverft.Routed.RequestFilters.Tests/

🔐 Security notes

This library provides application middleware, not a complete web application firewall. Review every enabled filter, default, bypass, proxy, and logging setting for the deployment environment.

In particular:

• configure enforcement flags explicitly;
• verify trusted proxies before relying on client-IP information;
• place filters before the endpoints or resources they protect;
• start new evaluator policies in allow-through mode where practical;
• do not expose development unlock behavior in production;
• avoid logging secrets, credentials, or sensitive request data;
• treat preview upgrades as potentially breaking until the project reaches 1.0.

🚢 Project status

Preview packages are produced by the repository's CI/CD workflow. Source, releases, and issue tracking are available in the GitHub repository.

📄 License

Licensed under the MIT License by Eigenverft.

Made with ❤️ by Eigenverft