ArthaTech.IpGuard 1.0.0

ArthaTech.IpGuard

ASP.NET Core middleware and service for IP-based access control using the IPinfo API.

Features at a glance:

• 🌍 Geo-location lookup (country, city, region, timezone, ASN)
• 🔒 VPN / Proxy / Tor / Hosting detection (requires IPinfo Privacy addon)
• 🚫 Configurable restricted country list
• ✅ IP whitelist
• ⚡ In-memory caching (configurable TTL)
• 🛡️ Fail-open design — allows traffic if IPinfo is unreachable
• 🔌 Works with any ASP.NET Core 6 / 7 / 8 Web API

Installation

dotnet add package ArthaTech.IpGuard

Or via the NuGet Package Manager:

PM> Install-Package ArthaTech.IpGuard

Quick Start

1. Get an IPinfo Token

Sign up at ipinfo.io and copy your API token from the dashboard. Free plan includes 50,000 lookups/month and geo-location data. VPN/Proxy/Tor detection requires the Privacy Detection add-on (paid).

2. Register Services (Program.cs)

Option A — Configuration delegate (code-first):

using IpGuard.Extensions;

builder.Services.AddIpGuard(options =>
{
    options.ApiToken            = "your_ipinfo_token_here";
    options.RestrictedCountries = ["KP", "IR", "CU", "SY"];  // ISO 3166-1 alpha-2
    options.BlockVpn            = true;
    options.BlockProxy          = true;
    options.BlockTor            = true;
});

Option B — From appsettings.json (recommended for production):

builder.Services.AddIpGuard(builder.Configuration);

{
  "IpGuard": {
    "ApiToken": "your_ipinfo_token_here",
    "RestrictedCountries": ["KP", "IR", "CU"],
    "BlockVpn": true,
    "BlockProxy": true,
    "BlockTor": true,
    "BlockHosting": false,
    "WhitelistedIps": ["127.0.0.1", "10.0.0.5"],
    "CacheDurationMinutes": 30,
    "BlockedStatusCode": 403,
    "BlockedMessage": "Access denied from your region or network.",
    "LogBlocked": true,
    "Enabled": true
  }
}

Option B2 — From a custom config section:

builder.Services.AddIpGuard(builder.Configuration.GetSection("Security:IpGuard"));

3. Add Middleware (Program.cs)

app.UseRouting();
app.UseIpGuard();          // ← Place AFTER UseRouting, BEFORE UseAuthentication
app.UseAuthentication();
app.UseAuthorization();

app.MapControllers();
app.Run();

That's it. Every request is now checked against your configured rules.

Configuration Reference

Blocked Response Format

When an IP is blocked, the middleware returns:

HTTP/1.1 403 Forbidden
Content-Type: application/json; charset=utf-8

{
  "error": "Access Denied",
  "message": "Access denied from your region or network.",
  "reason": "Country not permitted: KP",
  "country": "KP",
  "ip": "175.45.176.0"
}

Reading IP Info in Controllers

The middleware attaches the result to HttpContext.Items for use in downstream code:

[ApiController]
[Route("api/[controller]")]
public class OrderController : ControllerBase
{
    [HttpPost]
    public IActionResult CreateOrder([FromBody] OrderRequest req)
    {
        var ipResult = HttpContext.Items["IpGuardResult"] as IpCheckResult;

        if (ipResult != null)
        {
            Console.WriteLine($"Request from: {ipResult.Country} / {ipResult.City}");
            Console.WriteLine($"IsVpn: {ipResult.IsVpn}, IsTor: {ipResult.IsTor}");
            Console.WriteLine($"Org: {ipResult.Org}");
        }

        // ... rest of your logic
        return Ok();
    }
}

IpCheckResult Properties

Using the Service Directly

For manual lookups outside the middleware (e.g. in a background job or controller action):

[ApiController]
[Route("api/[controller]")]
public class CheckController : ControllerBase
{
    private readonly IIpGuardService _ipGuard;

    public CheckController(IIpGuardService ipGuard) => _ipGuard = ipGuard;

    [HttpGet("ip/{ip}")]
    public async Task<IActionResult> CheckIp(string ip)
    {
        var result = await _ipGuard.CheckIpAsync(ip);
        return Ok(result);
    }

    [HttpGet("geo/{ip}")]
    public async Task<IActionResult> GetGeo(string ip)
    {
        var geo = await _ipGuard.GetGeoInfoAsync(ip);
        return geo == null ? NotFound() : Ok(geo);
    }

    [HttpGet("privacy/{ip}")]
    public async Task<IActionResult> GetPrivacy(string ip)
    {
        var privacy = await _ipGuard.GetPrivacyInfoAsync(ip);
        return privacy == null ? NotFound() : Ok(privacy);
    }

    [HttpDelete("cache/{ip}")]
    public IActionResult ClearCache(string ip)
    {
        _ipGuard.InvalidateCache(ip);
        return NoContent();
    }
}

Reverse Proxy / Cloudflare Setup

If your app runs behind Cloudflare, nginx, or a load balancer, configure the real IP headers:

{
  "IpGuard": {
    "RealIpHeaders": ["CF-Connecting-IP", "X-Forwarded-For", "X-Real-IP"]
  }
}

Important: Only trust these headers from your own proxy. Clients can forge them. Use ASP.NET Core's ForwardedHeaders middleware to validate the proxy chain first.

// Program.cs — Add BEFORE UseIpGuard
app.UseForwardedHeaders(new ForwardedHeadersOptions
{
    ForwardedHeaders = ForwardedHeaders.XForwardedFor | ForwardedHeaders.XForwardedProto
});
app.UseIpGuard();

Combining with Cloudflare Country Blocking

For maximum security, use Cloudflare WAF (edge layer) + IpGuard (application layer):

Disabling in Development

// appsettings.Development.json
{
  "IpGuard": {
    "Enabled": false
  }
}

Or with environment-specific configuration:

builder.Services.AddIpGuard(options =>
{
    options.ApiToken = builder.Configuration["IpGuard:ApiToken"]!;
    options.Enabled  = !builder.Environment.IsDevelopment();
    options.RestrictedCountries = ["KP", "IR", "CU"];
    options.BlockVpn = true;
});

IPinfo Plan Comparison

Sign up at ipinfo.io/pricing.

Publishing to NuGet

First time setup

1. Create a NuGet account at nuget.org
2. Generate an API key: Account → API Keys → Create

Pack and publish

# Build in Release mode
dotnet build -c Release

# Create the .nupkg
dotnet pack -c Release -o ./nupkg

# Publish to NuGet.org
dotnet nuget push ./nupkg/ArthaTech.IpGuard.1.0.0.nupkg \
  --api-key YOUR_NUGET_API_KEY \
  --source https://api.nuget.org/v3/index.json

Publish to a private feed (Azure Artifacts / GitHub Packages)

# Azure Artifacts
dotnet nuget push ./nupkg/*.nupkg \
  --api-key az \
  --source https://pkgs.dev.azure.com/{org}/{feed}/nuget/v3/index.json

# GitHub Packages
dotnet nuget push ./nupkg/*.nupkg \
  --api-key YOUR_GITHUB_TOKEN \
  --source https://nuget.pkg.github.com/{owner}/index.json

License

MIT © 2025 ArthaTech