README
¶
Cerberus
Caddy plugin version of Anubis.
This plugin provides a Caddy handler that blocks unwanted requests using a sha256 PoW challenge. It's not a full replacement for Anubis, but most of the features are there.
Usage
- Install Caddy with the plugin:
caddy add-package github.com/Juijote/caddy-cerberus - Add the handler directive to your Caddyfile. Refer to the Caddyfile for an example configuration.
Comparison with Anubis
- Anubis is a standalone server that can be used with any web server, while Cerberus is a Caddy plugin.
- No support for custom rules: use caddy matchers instead.
- No custom UI or anime girls.
- Scripts and parameters are inlined in HTML.
- No separate endpoint for challenge response: any query with
?cerberuswill be treated as a challenge response.
Configuration
Check Caddyfile for an example configuration.
WARNING: Each cerberus directive will create a new instance of the handler. This means that if you have multiple cerberus directives, each one will have its own internal state and consume memory. Please use the cerberus directive only once per site.
Development
If you modified the js file, you need to run the following command to rebundle the js file:
$ devenv tasks js:bundle
Also, you need to run the following command to recompile the template if modified:
$ devenv tasks go:codegen
Please run tests and lints before submitting a PR:
$ direnv test # or go test
$ golangci-lint run
Documentation
¶
Overview ¶
templ: version: v0.3.833
Index ¶
- Constants
- func BasicPage(title string, content string, challenge string, difficulty int, jscode string) templ.Component
- func ValidateIPBlockConfig(cfg IPBlockConfig) error
- type Cerberus
- func (Cerberus) CaddyModule() caddy.ModuleInfo
- func (c *Cerberus) Provision(context caddy.Context) error
- func (c *Cerberus) ServeHTTP(w http.ResponseWriter, r *http.Request, next caddyhttp.Handler) error
- func (c *Cerberus) UnmarshalCaddyfile(d *caddyfile.Dispenser) error
- func (c *Cerberus) Validate() error
- type IPBlock
- type IPBlockConfig
Constants ¶
const ( VarName = "cerberus-block" DefaultCookieName = "cerberus-auth" DefaultHeaderName = "X-Cerberus-Status" DefaultDifficulty = 4 DefaultMaxPending = 128 DefaultBlockTTL = time.Hour * 24 // 1 day DefaultPendingTTL = time.Hour // 1 hour DefaultMaxMemUsage = 1 << 29 // 512MB DefaultTitle = "PoW 质询" DefaultDescription = "" /* 269-byte string literal not displayed */ DefaultIPV4Prefix = 32 DefaultIPV6Prefix = 64 CacheInternalCost = 16 + int64(unsafe.Sizeof(time.Time{})) PendingItemCost = 4 + int64(unsafe.Sizeof(&atomic.Int32{})) + CacheInternalCost BlocklistItemCost = CacheInternalCost )
Variables ¶
This section is empty.
Functions ¶
func ValidateIPBlockConfig ¶
func ValidateIPBlockConfig(cfg IPBlockConfig) error
Types ¶
type Cerberus ¶
type Cerberus struct {
// Challenge difficulty (number of leading zeroes in the hash).
Difficulty int `json:"difficulty,omitempty"`
// When set to true, the handler will drop the connection instead of returning a 403 if the IP is blocked.
Drop bool `json:"drop,omitempty"`
// MaxPending is the maximum number of pending (and failed) requests.
// Any IP block (prefix configured in prefix_cfg) with more than this number of pending requests will be blocked.
MaxPending int32 `json:"max_pending,omitempty"`
// BlockTTL is the time to live for blocked IPs.
BlockTTL time.Duration `json:"block_ttl,omitempty"`
// PendingTTL is the time to live for pending requests when considering whether to block an IP.
PendingTTL time.Duration `json:"pending_ttl,omitempty"`
// MaxMemUsage is the maximum memory usage for the pending and blocklist caches.
MaxMemUsage int64 `json:"max_mem_usage,omitempty"`
// CookieName is the name of the cookie used to store signed certificate.
CookieName string `json:"cookie_name,omitempty"`
// HeaderName is the name of the header used to store cerberus status ("PASS-BRIEF", "PASS-FULL", "BLOCK", "FAIL").
HeaderName string `json:"header_name,omitempty"`
// Title is the title of the challenge page.
Title string `json:"title,omitempty"`
// Description is the description of the challenge page.
Description string `json:"description,omitempty"`
// PrefixCfg is to configure prefixes used to block users in these IP prefix blocks, e.g., /24 /64.
PrefixCfg IPBlockConfig `json:"prefix_cfg,omitempty"`
// contains filtered or unexported fields
}
func (Cerberus) CaddyModule ¶
func (Cerberus) CaddyModule() caddy.ModuleInfo
func (*Cerberus) UnmarshalCaddyfile ¶
type IPBlock ¶
type IPBlock struct {
// contains filtered or unexported fields
}
IPBlock represents either an IPv4 or IPv6 block Data representation: v6: Stored as first 8 bytes of the address v4: Stored as 2001:db8:<v4>
func NewIPBlock ¶
func NewIPBlock(ip net.IP, cfg IPBlockConfig) (IPBlock, error)
NewIPBlock creates a new IPBlock from an IP address
type IPBlockConfig ¶
type IPBlockConfig struct {
// V4Prefix is the prefix length for IPv4 blocks
V4Prefix int `json:"v4_prefix"`
// V6Prefix is the prefix length for IPv6 blocks
V6Prefix int `json:"v6_prefix"`
}
IPBlockConfig represents the configuration for an IPBlock. It's used to specify the prefix length for IPv4 and IPv6 blocks for IP blocking.
func (IPBlockConfig) IsEmpty ¶
func (c IPBlockConfig) IsEmpty() bool
Source Files