ASP.NET Core

Installation

Within your ASP.NET Core project, run:

dotnet add package Centinel.AspNetCore

Setup

1. Configuration

Add your Centinel settings to appsettings.json (or any other configuration provider):

{
  "CentinelConfiguration": {
    "SecretKey": "your_secret_key_here",
    "ValidatorApiUrl": "https://validator.centinelanalytica.com/validate",
    "ProtectedPaths": ["/api", "/dashboard"],
    "ExcludedPaths": ["/health", "/static"],
    "FailOpen": true
  }
}

Note: SecretKey is required. ProtectedPaths controls which routes are validated (all routes are protected when the list is empty) and ExcludedPaths overrides protection. Set FailOpen to false to block traffic when the Centinel API cannot be reached.

2. Register Services

Register Centinel inside Program.cs:

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddCentinel(builder.Configuration);
// Or configure manually:
// builder.Services.AddCentinel(options =>
// {
//     options.SecretKey = Environment.GetEnvironmentVariable("CENTINEL_SECRET_KEY")!;
//     options.ProtectedPaths = new() { "/api", "/admin" };
// });

var app = builder.Build();

3. Add Middleware

Place the Centinel middleware in your request pipeline before endpoint execution:

app.UseRouting();
app.UseCentinel();
app.UseAuthentication();
app.UseAuthorization();

app.MapControllers();

This middleware intercepts each request, calls the Centinel validator, and blocks or redirects suspicious traffic.

Protection

Choose between automatic middleware protection or manual validation for specific endpoints.

Middleware

With app.UseCentinel(), every matching request is validated automatically. Customize which routes are included with ProtectedPaths and which are skipped with ExcludedPaths in your configuration.

Manual validation gives you the opportunity to apply Centinel logic only where you need it (e.g., sensitive APIs) without middleware-wide protection.

Advanced Configuration

Custom Validator Endpoint

Override the validator URL or request timeout when pointing to a self-hosted validator instance:

builder.Services.AddCentinel(options =>
{
    options.SecretKey = Environment.GetEnvironmentVariable("CENTINEL_SECRET_KEY")!;
    options.ValidatorApiUrl = "https://validator.yourdomain.com/validate";
    options.RequestTimeout = TimeSpan.FromSeconds(10);
});

How It Works

Centinel middleware runs before your endpoints, sending request metadata to the Centinel validator API. The validator decides whether the request is allowed, blocked, redirected, or not matched. Blocked or redirected responses return the HTML provided by Centinel, ensuring bots never reach your application code.

Deploy the project

When deploying, ensure your production configuration or environment variables provide the CentinelConfiguration values (especially SecretKey and any custom validator URL). Restart your app after updating keys so the middleware picks up the new settings.