greylist

README

greylist

package greylist implements a basic whitelisting/blacklisting http.Handler

Greylist is a standalone package that can be used by any go web server. It wraps an http.Handler and protects non-GET requests using 2 text files and an additional in-memory map.

It never writes to the list files. Your go program can do that on its own, and then call g.ReloadLists() manually. If the lists change often, you can set automatic reloads using the third parameter of greylist.New() when making your *List

It reads 2 files (whitelist file, blacklist file) and has option to periodically refresh the lists. It also provides an additional Blacklist(ip) method for temporary bans.

Under the hood, it uses a sync.RWMutex and 3 map[string]struct{}s to keep track of whitelisted and blacklisted and temporary-blacklisted IP addresses. GET requests are not checked.

API Documentation

Documentation

Overview

package greylist implements a basic whitelisting/blacklisting http.Handler

It reads 2 files (whitelist file, blacklist file) and has option to periodically refresh the lists. It also provides an additional Blacklist(ip) method for temporary bans.

Index

• Constants
• type List
  • func New(whitelistFilename, blacklistFilename string, refreshRate time.Duration) *List
  • func (l *List) Blacklist(r *http.Request)
  • func (l *List) Protect(h http.Handler) http.Handler
  • func (l *List) RefreshLists()
  • func (l *List) ServeHTTP(w http.ResponseWriter, r *http.Request)
  • func (l *List) SetAllMethods(b bool)
  • func (l *List) SetTemporaryBlacklistTime(d time.Duration)

Constants

const DefaultTemporaryBlacklistTime = time.Hour

Types

type List

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

List is a greylist instance

func New

func New(whitelistFilename, blacklistFilename string, refreshRate time.Duration) *List

New accepts whitelist filename, blacklist filename, and a refreshrate duration If the files don't exist or are empty, they are not used, and read errors will not be reported. refreshRate can be 0, in which case no automatic refreshing is done. (see RefreshLists())

After calling New(), a program can use l.Protect() to wrap a http.Handler.

By default, only non-GET requests are protected. If your program demands, use l.SetAllMethods(true)

By default, temporary bans are one hour. To change this, call l.SetTemporaryBlacklistTime(time.Duration)

func (*List) Blacklist

func (l *List) Blacklist(r *http.Request)

Blacklist adds a temporary ban to an ip address

func (*List) Protect

func (l *List) Protect(h http.Handler) http.Handler

Protect a http.Handler

http.ListenAndServe(":8080", glist.Protect(myHandler))

func (*List) RefreshLists

func (l *List) RefreshLists()

RefreshLists reads the whitelist and blacklist files and sets new maps (removed ips will not be in new map) Errors are ignored, in case the file doesn't exist or is not readable.

Note: Files must end in an empty newline, and windows newlines are not supported. (Only checks '\n\n')

func (*List) ServeHTTP

func (l *List) ServeHTTP(w http.ResponseWriter, r *http.Request)

ServeHTTP implements http.Handler interface

func (*List) SetAllMethods

func (l *List) SetAllMethods(b bool)

SetAllMethods blocks all requests from blacklisted IPs. Use with caution as it currently slows requests for everyone

func (*List) SetTemporaryBlacklistTime

func (l *List) SetTemporaryBlacklistTime(d time.Duration)

SetTemporaryBlacklistTime sets the duration that offenders will be blacklisted for