RequestAnalyzer 1.0.17

RequestAnalyzer

A powerful .NET library for comprehensive HTTP request analysis with built-in security detection, device identification, and proxy chain analysis.

Features

• Comprehensive Request Analysis: Extract IP address, device type, browser information, and more
• Browser Language Detection: Detect user's preferred language from Accept-Language header
• Security Detection: VPN detection, suspicious request analysis with confidence scoring
• Bot & Threat Detection: Integrated threat detection from CDN/proxy providers with smart scoring
• Advanced Geo-Location: Country, city, region, timezone, coordinates (latitude/longitude), postal code, and more
• Proxy Chain Analysis: Detect and analyze proxy chains with trusted proxy support
• Device Detection: Automatic device type identification (Desktop, Mobile, Tablet)
• Correlation ID: Automatic correlation ID generation and discovery
• Development Tool Detection: Identify and optionally allow API testing tools (Postman, curl, Swagger, etc.)
• Easy Integration: Simple dependency injection integration with environment-based configuration
• Provider-Agnostic: Works with any modern CDN or reverse proxy infrastructure

Installation

dotnet add package RequestAnalyzer

Quick Start

Basic Setup

using RequestAnalyzer;

var builder = WebApplication.CreateBuilder(args);

// Add RequestAnalyzer services with default (secure) settings
builder.Services.AddRequestAnalyzer();

var app = builder.Build();

app.Run();

⚠️ Note: Default settings are secure by default and will block development tools (Postman, curl, etc.). For development, use environment-based configuration (recommended) or manually enable dev tools.

Environment-Based Configuration (Recommended)

Automatically configures security settings based on the environment:

// Automatic configuration based on environment
builder.Services.AddRequestAnalyzer(builder.Environment);

// With optional overrides
builder.Services.AddRequestAnalyzer(builder.Environment, options =>
{
    // Override specific settings if needed
    options.VPNConfidenceThreshold = 80;
});

Default Settings by Environment:

What This Means:

• Development: Postman, curl, Swagger, Insomnia → ✅ Allowed (score = 0)
• Staging: Dev tools get scored → ⚠️ May be blocked (15-50 points)
• Production: Dev tools get scored → 🚫 Likely blocked (threshold = 30)

Manual Configuration

// Configure RequestAnalyzer with custom options
builder.Services.AddRequestAnalyzer(options =>
{
    options.AllowDevelopmentTools = true;
    options.EnableVPNDetection = true;
    options.VPNConfidenceThreshold = 80;
    options.SuspiciousRequestScoreThreshold = 70;
});

Inject and Use RequestAnalyzer

using RequestAnalyzer;
using Microsoft.AspNetCore.Mvc;

public class MyController : ControllerBase
{
    private readonly RequestAnalyzer.RequestAnalyzer _requestAnalyzer;

    public MyController(RequestAnalyzer.RequestAnalyzer requestAnalyzer)
    {
        _requestAnalyzer = requestAnalyzer;
    }

    [HttpGet]
    public IActionResult Get()
    {
        // Access request analysis data
        var clientIP = _requestAnalyzer.IP;
        var deviceType = _requestAnalyzer.Device;
        var isSuspicious = _requestAnalyzer.IsSuspiciousRequest;
        var isUsingVPN = _requestAnalyzer.IsUsingVPN;
        var correlationId = _requestAnalyzer.CorrelationId;
        var browser = _requestAnalyzer.Browser;
        var language = _requestAnalyzer.Language;
        var location = new
        {
            Country = _requestAnalyzer.CountryCode,
            City = _requestAnalyzer.City,
            Region = _requestAnalyzer.Region,
            Timezone = _requestAnalyzer.Timezone
        };
        
        return Ok(new { 
            IP = clientIP, 
            Device = deviceType,
            IsSuspicious = isSuspicious,
            SuspiciousScore = _requestAnalyzer.SuspiciousScore,
            IsUsingVPN = isUsingVPN,
            CorrelationId = correlationId,
            Browser = browser.BrowserName,
            OperatingSystem = browser.OperatingSystem,
            Language = language,
            Location = location
        });
    }
}

Available Properties

Basic Information

• IP (string): Client IP address (automatically detects from best source)
• IsPrivateIP (bool?): Whether the IP is private/internal
• CorrelationId (string): Request correlation ID for tracing
• Device (DeviceType): Device type (Unknown, Desktop, Mobile, Tablet)
• RequestTraceId (string?): Unique request trace ID for debugging (from proxy provider)

Browser Information

• Browser (BrowserInfo): Detailed browser and OS information
  • Browser.BrowserName: Browser name (e.g., "Chrome", "Firefox")
  • Browser.OperatingSystem: OS name (e.g., "Windows", "macOS")
  • Browser.OperatingSystemVersion: OS version

Language Detection

• Language (string?): User's preferred language from Accept-Language header (e.g., "en-US", "fr", "es-ES")
• Languages (LanguageInfo[]): All accepted languages with quality scores
  • LanguageInfo.Code: Language code (e.g., "en-US", "fr-FR")
  • LanguageInfo.Quality: Quality value 0.0-1.0 (preference level)
  • LanguageInfo.PrimaryLanguage: Primary language without region (e.g., "en" from "en-US")
  • LanguageInfo.Region: Region code if present (e.g., "US" from "en-US")

Geographic Location

Automatically available when using a CDN/proxy provider that sends geo-location headers

• CountryCode (string?): ISO country code (e.g., "US", "GB") - T1=Tor, XX=Unknown
• City (string?): City name (e.g., "San Francisco")
• Continent (string?): Continent code (e.g., "NA", "EU", "AS")
• Region (string?): State/region name (e.g., "California")
• RegionCode (string?): State/region code (e.g., "CA", "TX")
• PostalCode (string?): ZIP/postal code
• MetroCode (string?): Metro/DMA code (US only)
• Timezone (string?): IANA timezone (e.g., "America/Los_Angeles")
• Latitude (double?): Geographic latitude
• Longitude (double?): Geographic longitude

Proxy Chain Analysis

• ProxyChain (IPAddress[]): Array of proxies in the chain
• ProxyCount (int): Number of proxies in the chain
• FirstProxy (IPAddress): First proxy in the chain
• LastProxy (IPAddress): Last proxy in the chain
• IsFromTrustedProxy (bool): Whether request is from trusted proxy

VPN Detection

• IsUsingVPN (bool): Whether client is using VPN
• VPNConfidenceScore (int): Confidence score 0-100

Security Analysis

• IsSuspiciousRequest (bool): Whether request is suspicious based on multiple factors
• SuspiciousScore (int): Comprehensive security score 0-100 (includes bot detection, VPN, headers, etc.)
• SuspiciousReasons (string): Semicolon-separated list of reasons why request is suspicious
• IsFromDevelopmentTool (bool): Whether request is from development tool (Postman, curl, etc.)
• DevelopmentToolName (string): Name of the development tool if detected

Note: SuspiciousScore automatically incorporates threat intelligence from your CDN/proxy infrastructure when available, plus additional checks for VPN usage, missing headers, suspicious user agents, proxy chains, and more.

Usage Examples

Language Detection

public IActionResult MyAction(RequestAnalyzer analyzer)
{
    // Get the user's preferred language
    var language = analyzer.Language; // e.g., "en-US", "fr", "es-ES"
    
    // Localize content based on language
    if (language?.StartsWith("es") == true)
    {
        return Ok(new { Message = "¡Hola!" });
    }
    else if (language?.StartsWith("fr") == true)
    {
        return Ok(new { Message = "Bonjour!" });
    }
    else
    {
        return Ok(new { Message = "Hello!" });
    }
}

public IActionResult GetAllLanguages(RequestAnalyzer analyzer)
{
    // Get all accepted languages with quality scores
    var languages = analyzer.Languages;
    
    // Example for Accept-Language: en-US,en;q=0.9,es;q=0.8,fr;q=0.7
    foreach (var lang in languages)
    {
        Console.WriteLine($"{lang.Code} (quality: {lang.Quality})");
        // Output:
        // en-US (quality: 1.0)
        // en (quality: 0.9)
        // es (quality: 0.8)
        // fr (quality: 0.7
    }
    
    // Get primary language without region
    if (languages.Length > 0)
    {
        var primaryLang = languages[0].PrimaryLanguage; // "en" from "en-US"
        var region = languages[0].Region; // "US" from "en-US"
    }
    
    return Ok(new { Languages = languages });
}

VPN Detection

public IActionResult MyAction(RequestAnalyzer analyzer)
{
    // Block VPN users
    if (analyzer.IsUsingVPN)
    {
        return Forbid("VPN usage detected");
    }
    
    // Check confidence level
    if (analyzer.VPNConfidenceScore > 80)
    {
        _logger.LogWarning("High confidence VPN from {IP}", analyzer.IP);
    }
    
    return Ok();
}

Geographic Location

public IActionResult MyAction(RequestAnalyzer analyzer)
{
    // Get location data
    var country = analyzer.CountryCode;
    var city = analyzer.City;
    var timezone = analyzer.Timezone;
    
    if (country != null)
    {
        _logger.LogInformation("Request from {City}, {Country} (Timezone: {Timezone})", 
            city ?? "Unknown", country, timezone ?? "Unknown");
    }
    
    // Location-based content
    if (analyzer.Latitude.HasValue && analyzer.Longitude.HasValue)
    {
        var distance = CalculateDistance(
            analyzer.Latitude.Value, 
            analyzer.Longitude.Value, 
            targetLat, targetLon);
    }
    
    return Ok();
}

Tor Network Detection

public IActionResult MyAction(RequestAnalyzer analyzer)
{
    // Block Tor traffic
    if (analyzer.CountryCode == "T1")
    {
        return Forbid("Tor network not allowed");
    }
    
    // Block unknown/suspicious origins
    if (analyzer.CountryCode == "XX")
    {
        _logger.LogWarning("Request from unknown origin");
    }
    
    return Ok();
}

Suspicious Request Detection

public IActionResult MyAction(RequestAnalyzer analyzer)
{
    if (analyzer.IsSuspiciousRequest)
    {
        _logger.LogWarning("Suspicious request from {IP}: {Reasons}", 
            analyzer.IP, analyzer.SuspiciousReasons);
        return BadRequest("Suspicious activity detected");
    }
    
    return Ok();
}

Development Tool Detection

public IActionResult MyAction(RequestAnalyzer analyzer)
{
    // Check if request is from a dev tool
    if (analyzer.IsFromDevelopmentTool)
    {
        _logger.LogInformation(
            "Dev tool: {Tool} | Score: {Score} | Reasons: {Reasons}", 
            analyzer.DevelopmentToolName, 
            analyzer.SuspiciousScore,
            analyzer.SuspiciousReasons
        );
        // Output: "Dev tool: Postman | Score: 0 | Reasons: Development tool detected: Postman (Score: 0 - Allowed)"
        // or:     "Dev tool: curl | Score: 60 | Reasons: Development tool detected: curl (Score: 60 - Blocked)"
        
        // Optionally restrict to internal network only
        if (analyzer.IsPrivateIP == false && analyzer.SuspiciousScore == 0)
        {
            return Forbid($"{analyzer.DevelopmentToolName} only allowed from internal network");
        }
    }
    
    return Ok();
}

Get Client IP

public IActionResult MyAction(RequestAnalyzer analyzer)
{
    // Get client IP - automatically handles proxies and load balancers
    string clientIp = analyzer.IP;
    
    Console.WriteLine($"Client IP: {clientIp}");
    
    return Ok();
}

Configuration Options

public class RequestAnalyzerOptions
{
    // Detection toggles
    public bool EnableVPNDetection { get; set; } = true;
    
    // Allow development tools (Postman, curl, Swagger, etc.)
    // Default: false (secure by default)
    public bool AllowDevelopmentTools { get; set; } = false;
    
    // Thresholds (0-100)
    public int VPNConfidenceThreshold { get; set; } = 65;
    public int SuspiciousRequestScoreThreshold { get; set; } = 30;
    
    // Custom VPN range provider
    public IVpnRangeProvider? VpnRangeProvider { get; set; }
}

Default Values Explained

What This Means:

• 🔒 Secure by default: Production-ready out of the box
• ⚠️ Blocks dev tools: Postman, curl, etc. get score 60 (blocked by default)
• ✅ Allows browsers: Normal users get score 0 (allowed)
• 🎯 Binary scoring: Dev tools get score 0 when allowed, 60 when not
• 📊 Easy monitoring: Use IsFromDevelopmentTool flag to track dev tools
• ⚖️ Use environment-based config: Automatically adjusts per environment

Development Tools Detection

When AllowDevelopmentTools = true, the following tools receive a score of 0 (treated as legitimate):
When AllowDevelopmentTools = false, the following tools receive a score of 60 (to ensure blocking):

Use the IsFromDevelopmentTool property to identify and track dev tool usage.

Device Types

public enum DeviceType
{
    Unknown = 0,
    Desktop = 1,
    Mobile = 2,
    Tablet = 3
}

Support

For support, bug reports, feature requests, or any inquiries:

📧 Email: info@waelelazizy.com

We're here to help! Don't hesitate to reach out.

License

MIT

Requirements

• .NET 9.0 or higher
• ASP.NET Core