ipaccess

package
v14.0.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 12, 2026 License: BSD-3-Clause Imports: 6 Imported by: 0

README

IP Access Control Middleware

This middleware decides who reaches your application based on the client's IP address. Allowed and blocked patterns can be exact addresses, CIDR ranges, or regular expressions.

Installation

To use the IP Access Control middleware, you need to import it in your Iris application:

import "github.com/kataras/iris/v14/middleware/ipaccess"

Usage

IP Whitelisting and Blacklisting

The IP Access Control middleware allows access only to the specified IP patterns and denies access to the specified blocked IP patterns. Requests from IP addresses that do not match any of the allowed patterns or match any of the blocked patterns will be denied with a 403 Forbidden status.

allowedPatterns := []string{
    "127.0.0.1",          // Exact match.
    "192.168.1.0/24",     // CIDR notation.
    `^10\.0\.\d{1,3}\.\d{1,3}$`, // Regex pattern.
}
blockedPatterns := []string{
    "10.0.0.1",           // Exact match.
    `^172\.16\.\d{1,3}\.\d{1,3}$`, // Regex pattern.
}

ipAccessMiddleware, err := ipaccess.New(allowedPatterns, blockedPatterns)
if err != nil {
    log.Fatalf("Error creating IP access middleware: %v", err)
}
app.Use(ipAccessMiddleware)

// Or, when the patterns are literals or startup configuration and a bad one
// means a broken deployment, let it panic:
app.Use(ipaccess.Must(allowedPatterns, blockedPatterns))

IP Pattern Matching

The middleware supports three types of IP pattern matching:

Exact Match

An exact match pattern specifies a single IP address that must match exactly.

Example:

"127.0.0.1"
CIDR Notation

CIDR notation specifies a range of IP addresses.

Example:

"192.168.1.0/24"
Regular Expressions

A regular expression matches whatever an exact address and a CIDR range cannot express.

Example:

`^10\.0\.\d{1,3}\.\d{1,3}$`

Example

Here's a complete example of how to use the IP Access Control middleware in your Iris application:

package main

import (
	"log"

	"github.com/kataras/iris/v14"
	"github.com/kataras/iris/v14/middleware/ipaccess"
)

func main() {
	app := iris.New()

	// Define allowed and blocked IP patterns.
	allowedPatterns := []string{
		"127.0.0.1",          // Exact match.
		"192.168.1.0/24",     // CIDR notation.
		`^10\.0\.\d{1,3}\.\d{1,3}$`, // Regex pattern.
	}
	blockedPatterns := []string{
		"10.0.0.1",           // Exact match.
		`^172\.16\.\d{1,3}\.\d{1,3}$`, // Regex pattern.
	}

	// Use the IP Access middleware.
	ipAccessMiddleware := ipaccess.Must(allowedPatterns, blockedPatterns)
	app.Use(ipAccessMiddleware)

	app.Get("/", func(ctx iris.Context) {
		ctx.WriteString("Hello, World!")
	})

	app.Listen(":8080")
}

Documentation

Overview

Package ipaccess allows or blocks requests by the client's IP address, given as literals, CIDR blocks or ranges.

Its entry point is New(allowed, blocked []string) (Handler, error), which reports a malformed pattern; Must(allowed, blocked) is the panicking companion.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func Must

func Must(allowedPatterns []string, blockedPatterns []string) context.Handler

Must is New for a caller that has nothing to do with a malformed pattern: it panics instead of reporting one, so a registration stays a single expression.

app.Use(ipaccess.Must([]string{"127.0.0.1", "10.0.0.0/8"}, nil))

The patterns are usually literals or configuration read at startup, and a bad one there is a broken deployment rather than a request-time failure. Use New when they come from somewhere that can be wrong at run time.

func New

func New(allowedPatterns []string, blockedPatterns []string) (context.Handler, error)

New returns a middleware that allows or blocks requests by client IP address.

An empty "allowedPatterns" means "allow everything that is not blocked"; a non-empty one means "allow only these".

SECURITY WARNING: the client IP comes from Context.Addr, which returns the FIRST entry of the first configured Options.RemoteAddrHeaders header - a value the client writes.

If your application sets RemoteAddrHeaders (the usual "behind a proxy" setup), you MUST terminate every request at a proxy that OVERWRITES that header. Otherwise any caller can send

X-Forwarded-For: 10.0.0.1

and walk straight through an admin allowlist. Iris has no trusted-proxy list yet, so this middleware cannot verify it for you.

Addr is used rather than RemoteAddr on purpose: RemoteAddr skips private subnets while walking the header chain, which would make it impossible to allowlist internal addresses - the main thing this middleware is for.

Types

This section is empty.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL