ipfilter - GitLite

KO | EN

gitlite — search

#javascript #ai #typescript #go #golang #android #deep-learning #nodejs #java #awesome #kubernetes #awesome-list #security #pytorch

ipfilter

(★ 399)

A package for IP Filtering in Go (golang)

File Explorer

Download Latest Version (.zip)

- - test.yml
  - update-geolite2.yml
- dependabot.yml
- - main.go
- asn.bin
- asn.bin.gz
- data_gzip.go
- data_raw.go
- ipasn.go
- ipasn_test.go
- ipv4.bin
- ipv4.bin.gz
- ipv4.idx
- ipv4.idx.gz
- ipv6.bin
- ipv6.bin.gz
- ipv6.idx
- ipv6.idx.gz
- orgs.txt
- orgs.txt.gz
- - main.go
  - main_test.go
- iploc.go
- iploc_test.go
- ipv4.bin
- ipv4.txt
- ipv6.bin
- ipv6.txt
- reserved.go
.gitignore
go.mod
go.sum
ipfilter.go
ipfilter_test.go
LICENSE.md
README.md

# Installation Guide

1. Get the code

git clone https://github.com/jpillora/ipfilter

Downloads the entire project code from GitHub to your computer.

cd ipfilter

Moves into the project folder you just downloaded.

2. Go

Medium Recommended

Prerequisites

Git Needed to download the project code from GitHub.
Go The Go compiler and toolchain.

go build ./...

Compiles the Go program into an executable.

go run .

Runs the Go program directly without a separate build step.

✅ If the build finishes without errors, it worked. If you used go run ., check the terminal output.

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# ipfilter

A package for IP Filtering in Go (golang)

[![Go Reference](https://pkg.go.dev/badge/github.com/jpillora/ipfilter.svg)](https://pkg.go.dev/github.com/jpillora/ipfilter) [![Tests](https://github.com/jpillora/ipfilter/actions/workflows/test.yml/badge.svg)](https://github.com/jpillora/ipfilter/actions/workflows/test.yml)

### Install

```
go get github.com/jpillora/ipfilter
```

Requires Go 1.25 or newer.

### Features

* Simple
* Thread-safe
* IPv4 / IPv6 support
* Subnet support
* Location filtering (via embedded [MaxMind GeoLite2-Country](https://dev.maxmind.com/geoip/geolite2-free-geolocation-data) data)
* Simple HTTP middleware

### Usage

**Country-block HTTP middleware**

```go
h := http.Handler(...)
myProtectedHandler := ipfilter.Wrap(h, ipfilter.Options{
    //block requests from China and Russia by IP
    BlockedCountries: []string{"CN", "RU"},
})
http.ListenAndServe(":8080", myProtectedHandler)
```

**Trusted reverse proxy middleware**

Only accept forwarding headers when the direct peer belongs to your proxy
network:

```go
myProtectedHandler := ipfilter.Wrap(h, ipfilter.Options{
    BlockedCountries: []string{"CN", "RU"},
    TrustProxyCIDR:   "10.0.0.0/8",
})
```

`TrustProxy: true` remains supported with its legacy trust-all behavior; its
compatibility CIDR defaults to `0.0.0.0/0` while still accepting IPv6 proxy
peers. Prefer an explicit, narrow `TrustProxyCIDR` for new code. Invalid CIDRs
panic during construction so a proxy configuration typo cannot silently weaken
the filter.

**Country-block stand-alone**

```go
f := ipfilter.New(ipfilter.Options{
    BlockedCountries: []string{"CN"},
})

f.Blocked("116.31.116.51") //=> true (CN)
f.Allowed("216.58.199.67") //=> true (US)
```

**Async allow LAN hosts middleware**

```go
f := ipfilter.New(ipfilter.Options{
    BlockByDefault: true,
})

go func() {
	time.Sleep(15 * time.Second)
	//react to admin change....
	f.AllowIP("192.168.0.23")
}()

h := http.Handler(...)
myProtectedHandler := f.Wrap(h)
http.ListenAndServe(":8080", myProtectedHandler)
```

**Allow your entire LAN only**

```go
f := ipfilter.New(ipfilter.Options{
    AllowedIPs: []string{"192.168.0.0/24"},
    BlockByDefault: true,
})
//only allow 192.168.0.X IPs
f.Allowed("192.168.0.42") //=> true
f.Allowed("10.0.0.42") //=> false
```

... and with dynamic list updates

```go
//and allow 10.X.X.X
f.AllowIP("10.0.0.0/8")
f.Allowed("10.0.0.42") //=> true
f.Allowed("203.25.111.68") //=> false
//and allow everyone in Australia
f.AllowCountry("AU")
f.Allowed("203.25.111.68") //=> true
```

**Check with `net.IP`**

```go
f.NetAllowed(net.IP{203,25,111,68}) //=> true
```

**Low-level single IP to country**

```go
f.IPToCountry("203.25.111.68") //=> "AU"
f.NetIPToCountry(net.IP{203,25,111,68}) //=> "AU"
```

**Advanced HTTP middleware**

Make your own with:

```go
func (m *myMiddleware) ServeHTTP(w http.ResponseWriter, r *http.Request) {
	//use remote addr as it cant be spoofed
	ip, _, _ := net.SplitHostPort(r.RemoteAddr)
	//show simple forbidden text
	if !m.IPFilter.Allowed(ip) {
		http.Error(w, http.StatusText(http.StatusForbidden), http.StatusForbidden)
		return
	}
	//success!
	m.next.ServeHTTP(w, r)
}
```

#### Issues

* Due to the nature of IP address allocation, determining location based of a
  single IP address is quite difficult (if you're not Google) and is therefore
  not very reliable. For this reason `BlockByDefault` is off by default.

#### Todo

* Use a good algorithm to perform faster prefix matches
* Investigate reliability of other detectable attributes
* Add TOR/anonymizer filter options
* Add great-circle distance filter options (e.g. Allow 500KM radius from code/lat,lon)

#### Credits

* This product includes GeoLite2 data created by MaxMind, available from
  https://www.maxmind.com.

#### Change log

* v1.0.0 Use MaxMindDB IP data
* v1.1.0 Use IP2Location LITE IP data
* v1.2.3 Upgrade iploc, requires Go 1.16
* v1.3.0 Replace phuslu/iploc with embedded MaxMind GeoLite2-Country data
* v1.4.0 Add embedded MaxMind GeoLite2-ASN lookups