geoblock

README

Geoblock

Block clients based on their country, ASN, or network.

Table of contents

• Introduction
• Features
• Deployment
• Configuration
• Environment variables
• HTTP API
  • GET /v1/forward-auth
  • GET /v1/health
  • GET /v1/metrics
• Attribution

Introduction

Geoblock is a lightweight authorization service that restricts client access based on:

• Client's country
• Client's IP address
• Client's ASN (Autonomous System Number)
• Requested domain
• Requested method

It works as a forward-authentication service that can be used with reverse proxies such as Traefik, NGINX, and Caddy.

Features

• 🔧 Flexible: Allows you to define access control rules based on countries, domains, methods, networks, and ASNs.

• 🔄 Auto-reload: Automatically reloads the configuration file when it changes.

• 📅 Auto-update: Automatically updates the GeoLite2 databases every day.

• 📊 Metrics: Exposes simple metrics to monitor the service and build dashboards.

Deployment

• Example using Traefik
• Example using Caddy
• Example using NGINX

Configuration

Geoblock uses a single configuration file (/etc/geoblock/config.yaml by default) to set access control rules. Rules are evaluated sequentially, applying the first match per request. If no rules match, the default policy applies.

A rule matches if all specified conditions are met. Rules can include one or more of the following criteria:

• countries: List of country codes (ISO 3166-1 alpha-2)
• domains: List of domain names
• methods: List of HTTP methods
• networks: List of IP ranges in CIDR notation
• autonomous_systems: List of ASNs

Example configuration file:

---
access_control:
  # Default action when no rules match ("allow" or "deny").
  default_policy: deny

  # List of access rules, evaluated in order. The first matching rule’s
  # policy is applied. If no rule matches, the default policy is used.
  #
  # IMPORTANT: Replace these example rules with your own rules.
  rules:
    # Allow access from internal/private networks.
    - networks:
        - 10.0.0.0/8
        - 127.0.0.0/8
        - 172.16.0.0/12
        - 192.168.0.0/16
      policy: allow

    # Deny access for clients from ASNs 1234 and 5678.
    - autonomous_systems:
        - 1234
        - 5678
      policy: deny

    # Allow access to example.com and example.org from clients in
    # France (FR) and the United States (US) using the GET or POST HTTP
    # methods.
    - domains:
        - example.com
        - example.org
      countries:
        - FR
        - US
      methods:
        - GET
        - POST
      policy: allow

Environment variables

[!NOTE] Environment variables are intended primarily to be used when running Geoblock locally during development. It is discouraged to set or modify their values when running the Docker image. Instead, use mounts or remap ports as needed.

The following environment variables can be used to configure Geoblock:

Variable	Description	Default
GEOBLOCK_CONFIG	Path to the configuration file	/etc/geoblock/config.yaml
GEOBLOCK_PORT	Port to listen on	8080
GEOBLOCK_LOG_LEVEL	Log level	info

Supported log levels are: trace, debug, info, warn, error, fatal, or panic.

HTTP API

The following HTTP endpoints are exposed by Geoblock.

GET /v1/forward-auth

Check if a client is authorized to access a domain.

Request:

Header	Required	Description
X-Forwarded-For	Yes	Client's IP address
X-Forwarded-Host	Yes	Requested domain
X-Forwarded-Method	Yes	Requested HTTP method

Response:

Status	Description
204	Authorized
403	Forbidden

GET /v1/health

Check if the service is healthy.

Response:

Status	Description
204	Healthy

GET /v1/metrics

Returns metrics in JSON format.

Response:

• MIME type: application/json

• Properties:

  • denied: Number of denied requests
  • allowed: Number of allowed requests
  • invalid: Number of invalid requests
  • total: Total number of requests

• Example:

  { "denied": 0, "allowed": 0, "invalid": 0, "total": 0 }
  

Attribution

• This project uses the GeoLite2 databases provided by MaxMind.

• This project uses the database files provided by the ip-location-db project.