ipfilter

package module
v0.0.1 Latest Latest
Warning

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

 Go to latest Published: Sep 13, 2026 License: Apache-2.0 Imports: 3 Imported by: 0

README

Release Reference DeepWiki Test

Insights Insights

go-ipfilter

IP whitelist, blacklist and net.Listener wrappers for Go.

Features

  • IP whitelist: Whitelist
  • IP blacklist: Blacklist
  • CIDR, or subnet, supported
  • IPv4, IPv6 supported
  • net.Listener wrappers (WhitelistListener, BlacklistListener)
  • Fast (trie tree algorithm)
  • Intuitive interface
  • Zero dependency

Usages

IP whitelist
wl := ipfilter.NewWhitelist()

// Add in netip.Prefix
wl.AllowPrefix(netip.MustParsePrefix("127.0.0.1/32"), netip.MustParsePrefix("192.168.1.1/16"))

// Add in netip.Addr
wl.AllowAddr(netip.MustParseAddr("127.0.0.1"), netip.MustParseAddr("192.168.1.1"))

// Add in string
err := wl.Allow("127.0.0.1", "192.168.1.1/16")
if err != nil {
  panic(err)
}

fmt.Println(wl.Allowed("127.0.0.1"))   // true
fmt.Println(wl.Allowed("127.0.0.2"))   // false
fmt.Println(wl.Allowed("192.168.1.1")) // true
fmt.Println(wl.Allowed("192.168.2.2")) // true
fmt.Println(wl.Allowed("a.b.c.z"))     // false
IP blacklist
bl := ipfilter.NewBlacklist()

// Add in netip.Prefix
bl.DisallowPrefix(netip.MustParsePrefix("127.0.0.1/32"), netip.MustParsePrefix("192.168.1.1/16"))

// Add in netip.Addr
bl.DisallowAddr(netip.MustParseAddr("127.0.0.1"), netip.MustParseAddr("192.168.1.1"))

// Add in string
err := bl.Disallow("127.0.0.1", "192.168.1.1/16")
if err != nil {
  panic(err)
}

fmt.Println(wl.Allowed("127.0.0.1"))   // false
fmt.Println(wl.Allowed("127.0.0.2"))   // true
fmt.Println(wl.Allowed("192.168.1.1")) // false
fmt.Println(wl.Allowed("192.168.2.2")) // false
fmt.Println(wl.Allowed("a.b.c.z"))     // false
IP filter for listener

Use ipfilter.WhitelistListener or ipfilter.BlacklistListener to obtain a net lister with ip whitelist and blacklist.

The following example uses a whitelist.

ln, err := net.Listen("tcp", ":8080")
if err != nil {
  panic(err)
}

// NG >>> curl --interface 127.0.0.1 http://localhost:8080
// OK >>> curl --interface 127.0.0.2 http://localhost:8080
// OK >>> curl --interface 127.0.0.3 http://localhost:8080
ln, err = ipfilter.WhitelistListener(ln, "127.0.0.2", "127.0.0.3")
if err != nil {
  panic(err)
}

svr := &http.Server{
  Handler: http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
    fmt.Fprintln(w, "Hello Gopher!!")
  }),
}

log.Println("server starting at ", ln.Addr().String())
if err := svr.Serve(ln); err != nil {
  panic(err)
}

Docs & Examples

Benchmarks

This benchmark shows the performance of worst case senarios.

See the benchmark_test.go for details.

goos: windows
goarch: amd64
cpu: 11th Gen Intel(R) Core(TM) i5-1135G7 @ 2.40GHz

BenchmarkWhitelist_ipv4-8   18551698    67.41 ns/op   0 B/op   0 allocs/op
BenchmarkBlacklist_ipv4-8   18852510    68.24 ns/op   0 B/op   0 allocs/op
BenchmarkWhitelist_ipv6-8    4235488   273.0  ns/op   0 B/op   0 allocs/op
BenchmarkBlacklist_ipv6-8    3790411   294.5  ns/op   0 B/op   0 allocs/op

References

Documentation

Index

Examples

Constants

This section is empty.

Variables

This section is empty.

Functions

func BlacklistListener 

func BlacklistListener(ln net.Listener, disallow ...string) (net.Listener, error)

BlacklistListener returns a new lister with IP blacklist. Connections are immediately closed when they were not allowed by the blacklist. Given ip addresses must be in valid form for net/netip.ParsePrefix or net/netip.ParseAddr. ln must not be nil.

func WhitelistListener 

func WhitelistListener(ln net.Listener, allow ...string) (net.Listener, error)

WhitelistListener returns a new lister with IP whitelist. Connections are immediately closed when they were not allowed by the whitelist. Given ip addresses must be in valid form for net/netip.ParsePrefix or net/netip.ParseAddr. ln must not be nil.

Types

type Blacklist 

type Blacklist struct {
	// contains filtered or unexported fields
}

Blacklist is the IP blacklist.

Example (Ipv4) 
prefixes := []string{
	"10.0.0.0/8",     // 10.0.0.0–10.255.255.255 Private network
	"100.64.0.0/10",  // 100.64.0.0–100.127.255.255 Private network
	"127.0.0.0/8",    // 127.0.0.0–127.255.255.255 Host
	"172.16.0.0/12",  // 172.16.0.0–172.31.255.255 Private network
	"192.0.0.0/24",   // 192.0.0.0–192.0.0.255 Private network
	"192.168.0.0/16", // 192.168.0.0–192.168.255.255 Private network
	"198.18.0.0/15",  // 198.18.0.0–198.19.255.255 Private network
}

bl := NewBlacklist()
err := bl.Disallow(prefixes...)
if err != nil {
	panic(err)
}

targetIPs := []string{
	"10.255.255.1",  // NG
	"127.0.0.1",     // NG
	"192.168.1.2",   // NG
	"192.88.10.20",  // OK
	"224.10.20.30",  // OK
	"255.255.10.20", // OK
}
for _, ip := range targetIPs {
	fmt.Printf("%s --> %v\n", ip, bl.Allowed(ip))
}

Output:
10.255.255.1 --> false
127.0.0.1 --> false
192.168.1.2 --> false
192.88.10.20 --> true
224.10.20.30 --> true
255.255.10.20 --> true

func NewBlacklist 

func NewBlacklist() *Blacklist

NewBlacklist returns a new instance of Blacklist. Blacklist checks IPv4 and IPv6 addresses with blacklist.

func (*Blacklist) Allowed 

func (bl *Blacklist) Allowed(ip string) bool

Allowed returns if the ip is allowed by the blacklist. Both IPv4 and IPv6 are accepted.

func (*Blacklist) AllowedAddr 

func (bl *Blacklist) AllowedAddr(addr netip.Addr) bool

AllowedAddr returns if the addr is allowed by the blacklist. Both IPv4 and IPv6 are accepted.

func (*Blacklist) Disallow 

func (bl *Blacklist) Disallow(addrs ...string) error

Disallow adds addresses to the blacklist. When an address contains "/" it will be parsed with net/netip.ParsePrefix, others will be parsed with net/netip.ParseAddr. Given addresses must be in valid form for the functions. If parsing an address encounters an error, add immediately returns the error without processing the remaining addresses. When using CIDR, "/0" matches to all IPs and "<IPv4>/32" or "<IPv6>/128" matches to the only specified IP.

func (*Blacklist) DisallowAddr 

func (bl *Blacklist) DisallowAddr(addrs ...netip.Addr)

DisallowAddr adds ipv4 and ipv6 addresses to the blacklist. Invalid, non-ipv4 nor non-ipv6, addresses are ignored.

func (*Blacklist) DisallowPrefix 

func (bl *Blacklist) DisallowPrefix(addrs ...netip.Prefix)

DisallowPrefix adds ipv4 and ipv6 addresses to the blacklist. Invalid, non-ipv4 nor non-ipv6, addresses are ignored.

type Whitelist 

type Whitelist struct {
	// contains filtered or unexported fields
}

Whitelist is the IP whitelist.

Example 
wl := NewWhitelist()
err := wl.Allow("127.0.0.0/8", "192.168.0.0/16", "fd00:0:0::/48")
if err != nil {
	panic(err)
}

targetIPs := []string{
	"127.0.0.1",     // OK
	"192.168.1.1",   // OK
	"126.0.0.1",     // NG
	"192.169.1.1",   // NG
	"fd00:0:0::1",   // OK
	"fd00:0:0:1::1", // OK
	"fd00:0:1::1",   // NG
	"fc00:0:0::1",   // NG

}
for _, ip := range targetIPs {
	fmt.Printf("%s --> %v\n", ip, wl.Allowed(ip))
}

Output:
127.0.0.1 --> true
192.168.1.1 --> true
126.0.0.1 --> false
192.169.1.1 --> false
fd00:0:0::1 --> true
fd00:0:0:1::1 --> true
fd00:0:1::1 --> false
fc00:0:0::1 --> false
Example (Ipv4) 
prefixes := []string{
	"10.0.0.0/8",     // 10.0.0.0–10.255.255.255 Private network
	"100.64.0.0/10",  // 100.64.0.0–100.127.255.255 Private network
	"127.0.0.0/8",    // 127.0.0.0–127.255.255.255 Host
	"172.16.0.0/12",  // 172.16.0.0–172.31.255.255 Private network
	"192.0.0.0/24",   // 192.0.0.0–192.0.0.255 Private network
	"192.168.0.0/16", // 192.168.0.0–192.168.255.255 Private network
	"198.18.0.0/15",  // 198.18.0.0–198.19.255.255 Private network
}

wl := NewWhitelist()
err := wl.Allow(prefixes...)
if err != nil {
	panic(err)
}

targetIPs := []string{
	"10.255.255.1",  // OK
	"127.0.0.1",     // OK
	"192.168.1.2",   // OK
	"192.88.10.20",  // NG
	"224.10.20.30",  // NG
	"255.255.10.20", // NG
}
for _, ip := range targetIPs {
	fmt.Printf("%s --> %v\n", ip, wl.Allowed(ip))
}

Output:
10.255.255.1 --> true
127.0.0.1 --> true
192.168.1.2 --> true
192.88.10.20 --> false
224.10.20.30 --> false
255.255.10.20 --> false
Example (Ipv4Only) 
wl := NewWhitelist()
err := wl.Allow("0.0.0.0/0")
if err != nil {
	panic(err)
}

targetIPs := []string{
	"127.0.0.1", "192.168.1.1", "126.0.0.1", "192.169.1.1",
	"fd00:0:0::1", "fd00:0:0:1::1", "fd00:0:1::1", "fc00:0:0::1",
}
for _, ip := range targetIPs {
	fmt.Printf("%s --> %v\n", ip, wl.Allowed(ip))
}

Output:
127.0.0.1 --> true
192.168.1.1 --> true
126.0.0.1 --> true
192.169.1.1 --> true
fd00:0:0::1 --> false
fd00:0:0:1::1 --> false
fd00:0:1::1 --> false
fc00:0:0::1 --> false
Example (Ipv6Only) 
wl := NewWhitelist()
err := wl.Allow("::/0")
if err != nil {
	panic(err)
}

targetIPs := []string{
	"127.0.0.1", "192.168.1.1", "126.0.0.1", "192.169.1.1",
	"fd00:0:0::1", "fd00:0:0:1::1", "fd00:0:1::1", "fc00:0:0::1",
}
for _, ip := range targetIPs {
	fmt.Printf("%s --> %v\n", ip, wl.Allowed(ip))
}

Output:
127.0.0.1 --> false
192.168.1.1 --> false
126.0.0.1 --> false
192.169.1.1 --> false
fd00:0:0::1 --> true
fd00:0:0:1::1 --> true
fd00:0:1::1 --> true
fc00:0:0::1 --> true

func NewWhitelist 

func NewWhitelist() *Whitelist

NewWhitelist returns a new instance of Whitelist. Whitelist checks IPv4 and IPv6 addresses with whitelist.

func (*Whitelist) Allow 

func (wl *Whitelist) Allow(addrs ...string) error

Allow adds addresses to the whitelist. When an address contains "/" it will be parsed with net/netip.ParsePrefix, others will be parsed with net/netip.ParseAddr. Given addresses must be in valid form for the functions. If parsing an address encounters an error, add immediately returns the error without processing the remaining addresses. When using CIDR, "/0" matches to all IPs and "<IPv4>/32" or "<IPv6>/128" matches to the only specified IP.

func (*Whitelist) AllowAddr 

func (wl *Whitelist) AllowAddr(addrs ...netip.Addr)

AllowAddr adds ipv4 and ipv6 addresses to the whitelist. Invalid, non-ipv4 nor non-ipv6, addresses are ignored.

func (*Whitelist) AllowPrefix 

func (wl *Whitelist) AllowPrefix(addrs ...netip.Prefix)

AllowPrefix adds ipv4 and ipv6 addresses to the whitelist. Invalid, non-ipv4 nor non-ipv6, addresses are ignored.

func (*Whitelist) Allowed 

func (wl *Whitelist) Allowed(ip string) bool

Allowed returns if the addr is allowed by the whitelist. Both IPv4 and IPv6 are accepted.

func (*Whitelist) AllowedAddr 

func (wl *Whitelist) AllowedAddr(addr netip.Addr) bool

AllowedAddr returns if the addr is allowed by the whitelist. Both IPv4 and IPv6 are accepted.

Source Files

View all Source files

Directories

Path Synopsis
examples
blacklist command
blacklist-server command
whitelist command
whitelist-server command

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.