feat: Shield attack detection and lockdown plugin

AuthKit.slnx

@@ -12,6 +12,7 @@
     <Project Path="src/Plugins/Solutions/DevTokens/DevTokens.csproj" />
     <Project Path="src/Plugins/Solutions/DevTools/DevTools.csproj" />
     <Project Path="src/Plugins/Solutions/ExamplePlugin/ExamplePlugin.csproj" />
+    <Project Path="src/Plugins/Solutions/Shield/Shield.csproj" />
   </Folder>
   <Folder Name="/Plugins/Integrations/">
     <Project Path="src/Plugins/Integrations/AuthKit.Plugins.Integrations.csproj" />
@@ -20,12 +21,13 @@
     <Project Path="tools/AuthKit.PluginContractValidator/AuthKit.PluginContractValidator.csproj" />
     <Project Path="tools/AuthKit.ManifestGenerator/Core/AuthKit.ManifestGenerator.Core.csproj" />
     <Project Path="tools/AuthKit.ManifestGenerator/CLI/AuthKit.ManifestGenerator.CLI.csproj" />
-  </Folder>     
+  </Folder>
   <Project Path="src/Core/Core.csproj" />
   <Project Path="src/Host/Host.csproj" />
   <Folder Name="/Tests/">
     <Project Path="tests/Host/AuthKit.Host.Tests.csproj" />
     <Project Path="tests/Host.IntegrationTests/AuthKit.Host.IntegrationTests.csproj" />
     <Project Path="tests/Plugins/Abstractions/AuthKit.Plugins.Abstractions.Tests.csproj" />
+    <Project Path="tests/Plugins/Shield/Shield.Tests.csproj" />
   </Folder>
 </Solution>

Dockerfile

@@ -17,13 +17,15 @@ COPY ["src/Core/Core.csproj", "src/Core/"]
 COPY ["src/Plugins/Abstractions/AuthKit.Plugins.Abstractions.csproj", "src/Plugins/Abstractions/"]
 COPY ["src/Plugins/Solutions/DevTokens/DevTokens.csproj", "src/Plugins/Solutions/DevTokens/"]
 COPY ["src/Plugins/Solutions/DevTools/DevTools.csproj", "src/Plugins/Solutions/DevTools/"]
+COPY ["src/Plugins/Solutions/Shield/Shield.csproj", "src/Plugins/Solutions/Shield/"]
 COPY ["src/Plugins/Integrations/AuthKit.Plugins.Integrations.csproj", "src/Plugins/Integrations/"]
 
 COPY ["src/Plugins/Solutions/ExamplePlugin/ExamplePlugin.csproj", "src/Plugins/Solutions/ExamplePlugin/"]
 
 COPY ["tests/Host/AuthKit.Host.Tests.csproj", "tests/Host/"]
 COPY ["tests/Host.IntegrationTests/AuthKit.Host.IntegrationTests.csproj", "tests/Host.IntegrationTests/"]
 COPY ["tests/Plugins/Abstractions/AuthKit.Plugins.Abstractions.Tests.csproj", "tests/Plugins/Abstractions/"]
+COPY ["tests/Plugins/Shield/Shield.Tests.csproj", "tests/Plugins/Shield/"]
 COPY ["tools/AuthKit.PluginContractValidator/AuthKit.PluginContractValidator.csproj", "tools/AuthKit.PluginContractValidator/"]
 COPY ["tools/AuthKit.ManifestGenerator/CLI/AuthKit.ManifestGenerator.CLI.csproj", "tools/AuthKit.ManifestGenerator/CLI/"]
 COPY ["tools/AuthKit.ManifestGenerator/Core/AuthKit.ManifestGenerator.Core.csproj", "tools/AuthKit.ManifestGenerator/Core/"]
@@ -61,6 +63,10 @@ RUN if [ -f src/Plugins/Solutions/DevTools/manifest.json ]; then cp src/Plugins/
 RUN dotnet publish "src/Plugins/Solutions/ExamplePlugin/ExamplePlugin.csproj" -c Release -o /app/publish/plugins/ExamplePlugin
 RUN if [ -f src/Plugins/Solutions/ExamplePlugin/manifest.json ]; then cp src/Plugins/Solutions/ExamplePlugin/manifest.json /app/publish/plugins/ExamplePlugin/manifest.json; else echo "ExamplePlugin manifest.json not in context, skipping"; fi
 
+RUN dotnet publish "src/Plugins/Solutions/Shield/Shield.csproj" -c Release -o /app/publish/plugins/Shield
+RUN dotnet /tmp/manifest-gen/AuthKit.ManifestGenerator.CLI.dll --input /app/publish/plugins/Shield/Shield.dll --output /app/publish/plugins/Shield/manifest.json
+RUN if [ -f src/Plugins/Solutions/Shield/manifest.json ]; then cp src/Plugins/Solutions/Shield/manifest.json /app/publish/plugins/Shield/manifest.json; fi
+
 FROM base AS final
 WORKDIR /app
 COPY --from=publish /app/publish .

src/Plugins/Solutions/Shield/Composition/ShieldServices.cs

@@ -0,0 +1,36 @@
+using Microsoft.Extensions.Configuration;
+using Microsoft.Extensions.DependencyInjection;
+using Shield.Detection;
+using Shield.Detection.Sensors;
+using Shield.Options;
+using Shield.State;
+
+namespace Shield.Composition;
+
+/// <summary>
+/// Composition root for Shield services: validated options, shared state,
+/// and detector strategies in evaluation order.
+/// </summary>
+public static class ShieldServices
+{
+    /// <summary>
+    /// Registers Shield into the host DI container.
+    /// </summary>
+    public static IServiceCollection AddShield(this IServiceCollection services, IConfiguration configuration)
+    {
+        services.AddOptions<ShieldOptions>()
+            .Bind(configuration)
+            .ValidateDataAnnotations()
+            .ValidateOnStart();
+
+        services.AddSingleton<IShieldState, ShieldState>();
+        services.AddSingleton<IAttackDetector, AttackSignatureDetector>();
+        services.AddSingleton<IAttackDetector, SuspiciousUserAgentDetector>();
+        services.AddSingleton<IAttackDetector, OversizedRequestDetector>();
+        services.AddSingleton<IAttackDetector, RateFloodDetector>();
+        services.AddSingleton<IAttackDetector, AuthBruteForceDetector>();
+        services.AddSingleton<IAttackDetector, EndpointScannerDetector>();
+
+        return services;
+    }
+}

src/Plugins/Solutions/Shield/Detection/ClientIdResolver.cs

@@ -0,0 +1,29 @@
+using Microsoft.AspNetCore.Http;
+using System.Net;
+
+namespace Shield.Detection;
+
+/// <summary>
+/// Resolves the client identifier used for rate counting, lists, and incidents:
+/// the address before the configured number of trusted proxy hops, counted
+/// from the right of <c>X-Forwarded-For</c>, or the transport address.
+/// </summary>
+public static class ClientIdResolver
+{
+    /// <summary>
+    /// Resolves the client id for the request. Never returns null or empty.
+    /// </summary>
+    public static string Resolve(HttpContext context, bool trustForwardedHeader, int trustedProxyHops = 1)
+    {
+        if (trustForwardedHeader
+            && context.Request.Headers.TryGetValue("X-Forwarded-For", out var forwarded))
+        {
+            var entries = forwarded.ToString().Split(',', StringSplitOptions.TrimEntries);
+            var hops = Math.Max(1, trustedProxyHops);
+            if (entries.Length >= hops && IPAddress.TryParse(entries[^hops], out var address))
+                return address.ToString();
+        }
+
+        return context.Connection.RemoteIpAddress?.ToString() ?? "unknown";
+    }
+}

src/Plugins/Solutions/Shield/Detection/IAttackDetector.cs

@@ -0,0 +1,62 @@
+namespace Shield.Detection;
+
+/// <summary>
+/// Normalized input for attack detectors: who is calling, what is targeted,
+/// and when.
+/// </summary>
+public sealed record ShieldRequest(
+    string ClientId,
+    string Path,
+    string Query,
+    DateTimeOffset Timestamp,
+    string UserAgent = "",
+    long? ContentLength = null);
+
+/// <summary>
+/// What the host should do with a tripped signal.
+/// </summary>
+public enum ShieldAction
+{
+    /// <summary>
+    /// Temporarily block the offending client; enough distinct offenders trigger global lockdown.
+    /// </summary>
+    Lockdown,
+
+    /// <summary>
+    /// Block only the offending request, without a global lockdown.
+    /// </summary>
+    BlockRequest,
+}
+
+/// <summary>
+/// A detector verdict. Non-null means the detector tripped and the caller
+/// should apply <see cref="Action"/> with <see cref="Reason"/>.
+/// </summary>
+public sealed record AttackSignal(string Sensor, string Reason, ShieldAction Action = ShieldAction.Lockdown);
+
+/// <summary>
+/// One attack-detection strategy. Implementations are pure policy: per-client
+/// storage lives in <see cref="State.IShieldState"/> so HTTP and gRPC share it.
+/// Detectors run in DI registration order; the first signal wins.
+/// </summary>
+public interface IAttackDetector
+{
+    /// <summary>
+    /// Short sensor name used in incidents and diagnostics (e.g. "rate-flood").
+    /// </summary>
+    string Sensor { get; }
+
+    /// <summary>
+    /// Evaluates the request. Returns a signal when the request trips the
+    /// detector, otherwise null.
+    /// </summary>
+    AttackSignal? Evaluate(ShieldRequest request, Options.ShieldOptions options);
+
+    /// <summary>
+    /// Observes the completed response (e.g. 401/403 counting). Returns a signal
+    /// when the observation trips the detector; the client block then applies to
+    /// subsequent requests. Only <see cref="ShieldAction.Lockdown"/> signals are
+    /// honored here — the response is already sent. Default ignores responses.
+    /// </summary>
+    AttackSignal? ObserveResponse(ShieldRequest request, int statusCode, Options.ShieldOptions options) => null;
+}

src/Plugins/Solutions/Shield/Detection/Sensors/AttackSignatureDetector.cs

@@ -0,0 +1,53 @@
+using Shield.State;
+
+namespace Shield.Detection.Sensors;
+
+/// <summary>
+/// Trips when path or query contains known attack fragments (traversal,
+/// SQL injection, XSS, suspicious system paths). Matching is case-insensitive
+/// substring search over the raw (still-encoded) target.
+/// </summary>
+public sealed class AttackSignatureDetector(IShieldState state) : IAttackDetector
+{
+    // Lowercase fragments matched against path + query.
+    private static readonly string[] Signatures =
+    [
+        "../", "..%2f", "..%5c", "%2e%2e",
+        "union select", "union+select",
+        "<script", "javascript:",
+        "/etc/passwd", "xp_cmdshell",
+        "' or '1'='1", "\" or \"1\"=\"1",
+    ];
+
+    /// <summary>
+    /// Short sensor name used in incidents and diagnostics.
+    /// </summary>
+    public string Sensor => "attack-signature";
+
+    /// <summary>
+    /// Evaluates the request against this sensor policy.
+    /// </summary>
+    public AttackSignal? Evaluate(ShieldRequest request, Options.ShieldOptions options)
+    {
+        if (!options.SignatureDetectionEnabled)
+            return null;
+
+        if (!ContainsSignature(request.Path + request.Query, options.ExtraSignatures))
+            return null;
+
+        var hits = state.RecordViolation(request.ClientId, request.Timestamp, options.SignatureWindowSeconds, options.MaxTrackedClients);
+        return hits >= options.MaxSignatureHits
+            ? new AttackSignal(Sensor, $"attack signatures from {request.ClientId} ({hits} hits)")
+            : null;
+    }
+
+    internal static bool ContainsSignature(string target, string[]? extra = null)
+    {
+        if (Signatures.Any(signature => target.Contains(signature, StringComparison.OrdinalIgnoreCase)))
+            return true;
+
+        return extra?.Any(signature =>
+            !string.IsNullOrWhiteSpace(signature) &&
+            target.Contains(signature, StringComparison.OrdinalIgnoreCase)) == true;
+    }
+}

src/Plugins/Solutions/Shield/Detection/Sensors/AuthBruteForceDetector.cs

@@ -0,0 +1,37 @@
+using Microsoft.AspNetCore.Http;
+using Shield.State;
+
+namespace Shield.Detection.Sensors;
+
+/// <summary>
+/// Trips when a single client accumulates too many failed authentications
+/// (401/403 responses) inside the window — the password-spraying / credential
+/// stuffing shape. Observation happens after the endpoint runs, so the
+/// client block applies to subsequent requests.
+/// </summary>
+public sealed class AuthBruteForceDetector(IShieldState state) : IAttackDetector
+{
+    /// <summary>
+    /// Short sensor name used in incidents and diagnostics.
+    /// </summary>
+    public string Sensor => "auth-brute-force";
+
+    /// <summary>
+    /// Evaluates the request against this sensor policy.
+    /// </summary>
+    public AttackSignal? Evaluate(ShieldRequest request, Options.ShieldOptions options) => null;
+
+    /// <summary>
+    /// Observes the completed response for this sensor policy.
+    /// </summary>
+    public AttackSignal? ObserveResponse(ShieldRequest request, int statusCode, Options.ShieldOptions options)
+    {
+        if (statusCode is not (StatusCodes.Status401Unauthorized or StatusCodes.Status403Forbidden))
+            return null;
+
+        var count = state.RecordAuthFailure(request.ClientId, request.Timestamp, options.AuthFailureWindowSeconds, options.MaxTrackedClients);
+        return count >= options.MaxAuthFailures
+            ? new AttackSignal(Sensor, $"authentication failures from {request.ClientId} ({count} in {options.AuthFailureWindowSeconds}s)")
+            : null;
+    }
+}

src/Plugins/Solutions/Shield/Detection/Sensors/EndpointScannerDetector.cs

@@ -0,0 +1,37 @@
+using Microsoft.AspNetCore.Http;
+using Shield.State;
+
+namespace Shield.Detection.Sensors;
+
+/// <summary>
+/// Trips when a single client collects too many 404s inside the window — the
+/// directory-enumeration / vulnerability-probing shape
+/// (<c>/.git/</c>, <c>/wp-admin/</c>, <c>/.env</c>). Observation happens after
+/// the endpoint runs, so the client block applies to subsequent requests.
+/// </summary>
+public sealed class EndpointScannerDetector(IShieldState state) : IAttackDetector
+{
+    /// <summary>
+    /// Short sensor name used in incidents and diagnostics.
+    /// </summary>
+    public string Sensor => "endpoint-scanner";
+
+    /// <summary>
+    /// Evaluates the request against this sensor policy.
+    /// </summary>
+    public AttackSignal? Evaluate(ShieldRequest request, Options.ShieldOptions options) => null;
+
+    /// <summary>
+    /// Observes the completed response for this sensor policy.
+    /// </summary>
+    public AttackSignal? ObserveResponse(ShieldRequest request, int statusCode, Options.ShieldOptions options)
+    {
+        if (!options.ScannerDetectionEnabled || statusCode != StatusCodes.Status404NotFound)
+            return null;
+
+        var count = state.RecordProbe(request.ClientId, request.Timestamp, options.ScannerWindowSeconds, options.MaxTrackedClients);
+        return count >= options.MaxNotFoundProbes
+            ? new AttackSignal(Sensor, $"endpoint probing from {request.ClientId} ({count} missing paths in {options.ScannerWindowSeconds}s)")
+            : null;
+    }
+}

src/Plugins/Solutions/Shield/Detection/Sensors/OversizedRequestDetector.cs

@@ -0,0 +1,34 @@
+namespace Shield.Detection.Sensors;
+
+/// <summary>
+/// Blocks (without a global lockdown) requests whose declared body or query
+/// string exceeds the configured limits — the cheap-DoS / buffer-probe shape.
+/// A single oversized request harms no one else, so it never trips a lockdown.
+/// </summary>
+public sealed class OversizedRequestDetector : IAttackDetector
+{
+    /// <summary>
+    /// Short sensor name used in incidents and diagnostics.
+    /// </summary>
+    public string Sensor => "oversized-request";
+
+    /// <summary>
+    /// Evaluates the request against this sensor policy.
+    /// </summary>
+    public AttackSignal? Evaluate(ShieldRequest request, Options.ShieldOptions options)
+    {
+        if (request.ContentLength is { } body && body > options.MaxBodyBytes)
+            return new AttackSignal(
+                Sensor,
+                $"oversized body from {request.ClientId} ({body} bytes)",
+                ShieldAction.BlockRequest);
+
+        if (request.Query.Length > options.MaxQueryLength)
+            return new AttackSignal(
+                Sensor,
+                $"oversized query from {request.ClientId} ({request.Query.Length} chars)",
+                ShieldAction.BlockRequest);
+
+        return null;
+    }
+}

src/Plugins/Solutions/Shield/Detection/Sensors/RateFloodDetector.cs

@@ -0,0 +1,26 @@
+using Shield.State;
+
+namespace Shield.Detection.Sensors;
+
+/// <summary>
+/// Trips when a single client exceeds the configured request rate inside the
+/// sliding window.
+/// </summary>
+public sealed class RateFloodDetector(IShieldState state) : IAttackDetector
+{
+    /// <summary>
+    /// Short sensor name used in incidents and diagnostics.
+    /// </summary>
+    public string Sensor => "rate-flood";
+
+    /// <summary>
+    /// Evaluates the request against this sensor policy.
+    /// </summary>
+    public AttackSignal? Evaluate(ShieldRequest request, Options.ShieldOptions options)
+    {
+        var count = state.RecordRequest(request.ClientId, request.Timestamp, options.WindowSeconds, options.MaxTrackedClients);
+        return count > options.MaxRequestsPerWindow
+            ? new AttackSignal(Sensor, $"request flood from {request.ClientId} ({count} requests in {options.WindowSeconds}s)")
+            : null;
+    }
+}