Mostlylucid.GeoDetection.Contributor 1.0.0

Mostlylucid.GeoDetection.Contributor

Geographic bot detection contributor for Mostlylucid.BotDetection

This package demonstrates the contributor plugin pattern for extending bot detection with domain-specific signals.

What It Does

• Enriches bot detection with geographic location data
• Verifies bot origins (e.g., Googlebot should come from US)
• Detects geo-inconsistencies (e.g., Russian locale from China)
• Flags hosting/datacenter/VPN IPs
• Identifies suspicious countries

Installation

dotnet add package Mostlylucid.GeoDetection
dotnet add package Mostlylucid.GeoDetection.Contributor

Usage - It's Really This Simple!

1. Register Services

var builder = WebApplication.CreateBuilder(args);

// Add core geo-location services
builder.Services.AddGeoLocationServices();

// Add bot detection with orchestrator
builder.Services.AddBotDetection();

// Add geo-detection contributor (that's it!)
builder.Services.AddGeoDetectionContributor(options =>
{
 options.EnableBotVerification = true; // Verify known bots (Googlebot, etc.)
 options.EnableInconsistencyDetection = true; // Detect locale/geo mismatches
 options.FlagHostingIps = true; // Flag datacenter IPs
 options.FlagVpnIps = true; // Flag VPN/proxy IPs
});

2. Use Middleware

app.UseBotDetection();

That's it! The contributor automatically:

• Runs in the first wave alongside IP detection
• Contributes geographic signals to the blackboard
• Integrates with policy evaluation and early-exit logic

Why This Pattern is Powerful

The GeoDetection integration showcases the extensibility of the bot detection system:

✅ Zero Configuration Integration

Once registered, contributors work automatically with:

• Wave-based parallel execution
• Quorum-based early exit
• Circuit breaker (if contributors fail repeatedly)
• Policy evaluation

✅ Signal-Based Composition

Contributors communicate via typed signals on the blackboard:

// GeoContributor writes
signals.Add(GeoSignalKeys.GeoCountryCode, "US");

// Other contributors/detectors read
var country = state.GetSignal<string>(GeoSignalKeys.GeoCountryCode);

This enables composable detection without tight coupling.

✅ Simple DI Registration

Just one line:

services.TryAddEnumerable(
 ServiceDescriptor.Singleton<IContributingDetector, GeoContributor>());

Creating Your Own Contributor

Want to add custom bot detection logic? Follow this simple pattern:

1. Create Your Contributor

using Mostlylucid.BotDetection.Models;
using Mostlylucid.BotDetection.Orchestration;

public class MyCustomContributor : ContributingDetectorBase
{
 public override string Name => "MyCustom";
 public override int Priority => 150; // Run order (lower = earlier)

 // Optional: Only run after certain signals are available
 public override IReadOnlyList<TriggerCondition> TriggerConditions =>
 [TriggerCondition.RequireSignal(GeoSignalKeys.GeoCountryCode)];

 public override async Task<IReadOnlyList<DetectionContribution>> ContributeAsync(
 BlackboardState state,
 CancellationToken cancellationToken)
 {
 // Read signals from blackboard
 var country = state.GetSignal<string>(GeoSignalKeys.GeoCountryCode);
 var userAgent = state.UserAgent;

 // Your custom detection logic
 if (IsSuspiciousPattern(country, userAgent))
 {
 return Single(DetectionContribution.Bot(
 Name, "MyCustomCheck",
 confidenceDelta: 0.6,
 reason: "Custom rule triggered",
 botType: BotType.Unknown,
 weight: 1.5
 ));
 }

 return None();
 }

 private bool IsSuspiciousPattern(string country, string userAgent) => false;
}

2. Add Extension Method

public static class MyCustomContributorExtensions
{
 public static IServiceCollection AddMyCustomContributor(
 this IServiceCollection services)
 {
 services.TryAddEnumerable(
 ServiceDescriptor.Singleton<IContributingDetector, MyCustomContributor>());
 return services;
 }
}

3. Register It

builder.Services.AddBotDetection();
builder.Services.AddMyCustomContributor(); // Done!

Your contributor automatically:

• Runs in the wave-based pipeline
• Can trigger on signals from other contributors
• Contributes to the final bot probability
• Respects early-exit and circuit breaker logic

Signal Keys - Extensible by Design

Signal keys use partial class for extension:

// In Mostlylucid.GeoDetection.Contributor
public static partial class GeoSignalKeys
{
 public const string GeoCountryCode = "geo.country_code";
 public const string GeoIsVpn = "geo.is_vpn";
 // ... more geo signals
}

// In your custom package
public static partial class MySignalKeys
{
 public const string MyCustomSignal = "my.custom_signal";
}

Example: Bot Origin Verification

The GeoContributor verifies known bot origins:

private static readonly Dictionary<string, string[]> KnownBotOrigins = new()
{
 ["googlebot"] = ["US"],
 ["bingbot"] = ["US"],
 ["yandexbot"] = ["RU", "FI", "NL"],
 ["baiduspider"] = ["CN", "HK"]
};

If a User-Agent claims to be "Googlebot" but the IP is from China:

• Confidence Delta: +0.8 (high probability of bot)
• Weight: 2.0 (strong signal)
• Bot Type: Scraper
• Reason: "FAKE Googlebot from China"

This catches bot impersonation attempts.

Geographic Signals Reference

Configuration

{
 "BotDetection": {
 "Geo": {
 "EnableBotVerification": true,
 "EnableInconsistencyDetection": true,
 "FlagHostingIps": true,
 "FlagVpnIps": true,
 "SuspiciousCountries": ["KP", "CN"],
 "TrustedCountries": ["US", "GB", "DE"],
 "VerifiedBotConfidenceBoost": 0.3,
 "BotOriginMismatchPenalty": 0.8,
 "SignalWeight": 1.0,
 "Priority": 100
 }
 }
}

Why GeoDetection is a Separate Package

The contributor pattern allows:

• Optional dependencies - Don't need geo if you don't want it
• Third-party extensions - Anyone can publish contributors
• Clean separation - Core bot detection has no geo coupling

This is the plugin architecture in action!

License

MIT

A bot detection contributor that provides detailed geographic location analysis for request validation. This package bridges Mostlylucid.GeoDetection with Mostlylucid.BotDetection to enable geo-based bot detection.

Features

• Geographic Location Signals: Provides country, region, city, and coordinates for requests
• Geo-Inconsistency Detection: Detects bots claiming to be from one location but IP suggests another
• Bot Verification: Validates that claimed bots (e.g., Googlebot) originate from expected geographic regions
• VPN/Proxy Detection: Flags requests from known VPN/proxy/hosting providers
• Timezone Validation: Detects mismatches between claimed timezone and IP-based location

Installation

dotnet add package Mostlylucid.GeoDetection.Contributor

Usage

// In Program.cs or Startup.cs
services.AddGeoLocationServices(options =>
{
 options.DefaultProvider = GeoProvider.MaxMind;
 options.GeoLite2DatabasePath = "/path/to/GeoLite2-City.mmdb";
});

services.AddBotDetection(options => { /* ... */ });

// Add the geo contributor
services.AddGeoDetectionContributor(options =>
{
 options.EnableBotVerification = true;
 options.EnableInconsistencyDetection = true;
 options.SuspiciousCountries = ["CN", "RU", "KP"]; // Optional
});

Signals Emitted

The contributor emits the following signals to the blackboard:

Geo-Inconsistency Detection

The contributor detects several types of geo-based inconsistencies:

Bot Origin Verification

Known search engine bots should originate from specific countries:

If a User-Agent claims to be Googlebot but the IP is from China, this is flagged as highly suspicious.

Timezone Mismatches

If the Accept-Language header suggests a specific locale (e.g., "en-US") but the IP originates from a different timezone, this is flagged.

Datacenter + Consumer Locale

Browser User-Agents claiming consumer locales from datacenter IPs are flagged.

Configuration Options

public class GeoContributorOptions
{
 // Enable verification that known bots come from expected countries
 public bool EnableBotVerification { get; set; } = true;

 // Enable geo-inconsistency detection
 public bool EnableInconsistencyDetection { get; set; } = true;

 // Countries to flag as suspicious (higher weight)
 public List<string> SuspiciousCountries { get; set; } = [];

 // Countries to always trust (lower weight)
 public List<string> TrustedCountries { get; set; } = [];

 // Priority for this detector (lower = runs earlier)
 public int Priority { get; set; } = 15;
}

License

MIT