RequestAnalyzer 1.0.4

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
• Security Detection: VPN detection, suspicious request analysis with confidence scoring
• Bot & Threat Detection: Integrated threat detection from proxy providers (Cloudflare, Azure Front Door)
• 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 Cloudflare, Azure Front Door, or any proxy provider

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;
});

Enabling Geographic Location Features

The geographic location properties (City, Latitude, Longitude, Timezone, etc.) require configuration on your proxy provider:

Cloudflare Setup

1. Log in to your Cloudflare dashboard
2. Select your domain
3. Go to Rules → Transform Rules → Managed Transforms
4. Enable "Add visitor location headers"
5. Save and deploy

This adds headers like CF-IPCity, CF-IPLatitude, CF-IPLongitude, etc. to all requests.

Azure Front Door

Azure Front Door automatically provides geographic headers when configured. No additional setup needed.

Note: Geographic properties return null if the headers are not available. The library works perfectly fine without them - they're optional enhancements.

Usage

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 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,
            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

Geographic Location

Available when behind Cloudflare with "Add visitor location headers" enabled, or Azure Front Door

• 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 bot detection and threat scores from your proxy provider (Cloudflare/Azure) when available, plus additional checks for VPN usage, missing headers, suspicious user agents, and more.

Usage Examples

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.

API Clients:

• ✅ Postman, Insomnia, Paw, Bruno, Apidog, Hoppscotch, Thunder Client

API Documentation:

• ✅ Swagger UI, Swagger Codegen, OpenAPI tools, ReDoc, RapiDoc, Stoplight

Command-Line Tools:

• ✅ curl, HTTPie, wget

IDEs:

• ✅ VS Code, JetBrains (IntelliJ, PyCharm, WebStorm, Rider)

HTTP Libraries:

• ✅ Axios, RestSharp, Guzzle, OkHttp, Alamofire, Node-Fetch, Got, Undici

Swagger/OpenAPI Detection:

• Requests from Swagger UI pages (detected via Referer header)
• Requests from /swagger, /api-docs, /openapi, /redoc paths
• Local development AJAX requests (localhost + XMLHttpRequest)

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