feat: add tarpit using http headers

Author: nnathan

config.go

@@ -17,10 +17,11 @@ import (
 	"pkg.jsn.cam/caddy-defender/matchers/whitelist"
 	"pkg.jsn.cam/caddy-defender/ranges/data"
 	"pkg.jsn.cam/caddy-defender/responders"
+	"pkg.jsn.cam/caddy-defender/responders/headertarpit"
 	"pkg.jsn.cam/caddy-defender/responders/tarpit"
 )
 
-var responderTypes = []string{"block", "custom", "drop", "garbage", "ratelimit", "redirect", "tarpit"}
+var responderTypes = []string{"block", "custom", "drop", "garbage", "ratelimit", "redirect", "tarpit", "header_tarpit"}
 
 // UnmarshalCaddyfile sets up the handler from Caddyfile tokens. Syntax:
 //
@@ -150,6 +151,57 @@ func (m *Defender) UnmarshalCaddyfile(d *caddyfile.Dispenser) error {
 					return d.Errf("unknown nested config key: %s", d.Val())
 				}
 			}
+		case "header_tarpit_config":
+			for nesting := d.Nesting(); d.NextBlock(nesting); {
+				switch d.Val() {
+				case "headers":
+					headers := map[string]string{}
+					for nesting := d.Nesting(); d.NextBlock(nesting); {
+						k := d.Val()
+						if !d.NextArg() {
+							return d.ArgErr()
+						}
+						headers[k] = d.Val()
+					}
+					m.HeaderTarpitConfig.Headers = headers
+				case "timeout":
+					if !d.NextArg() {
+						return d.ArgErr()
+					}
+
+					timeout, err := time.ParseDuration(d.Val())
+					if err != nil {
+						return fmt.Errorf("invalid timeout value: '%s'", d.Val())
+					}
+
+					m.HeaderTarpitConfig.Timeout = timeout
+				case "header_per_second":
+					if !d.NextArg() {
+						return d.ArgErr()
+					}
+
+					hps, err := strconv.Atoi(d.Val())
+					if err != nil {
+						return fmt.Errorf("invalid header_per_second value: '%s'", d.Val())
+					}
+
+					m.HeaderTarpitConfig.DelaySecond = hps
+				case "response_code":
+					if !d.NextArg() {
+						return d.ArgErr()
+					}
+
+					responseCode, err := strconv.Atoi(d.Val())
+					if err != nil {
+						return fmt.Errorf("invalid response_code value: '%s'", d.Val())
+					}
+
+					m.HeaderTarpitConfig.ResponseCode = responseCode
+				default:
+					return d.Errf("unknown nested config key: %s", d.Val())
+				}
+			}
+
 		default:
 			return d.Errf("unknown subdirective '%s'", d.Val())
 		}
@@ -162,7 +214,7 @@ func (m *Defender) UnmarshalCaddyfile(d *caddyfile.Dispenser) error {
 func (m *Defender) UnmarshalJSON(b []byte) error {
 	type rawDefender Defender
 	var rawConfig rawDefender
-	var excludedKeys = []string{"responder"}
+	excludedKeys := []string{"responder"}
 
 	if err := json.Unmarshal(b, &rawConfig); err != nil {
 		return err
@@ -194,6 +246,10 @@ func (m *Defender) UnmarshalJSON(b []byte) error {
 		m.responder = &tarpit.Responder{
 			Config: &m.TarpitConfig,
 		}
+	case "header_tarpit":
+		m.responder = &headertarpit.Responder{
+			Config: &m.HeaderTarpitConfig,
+		}
 
 	default:
 		return fmt.Errorf("unknown responder type: %s", rawConfig.RawResponder)

plugin.go

@@ -12,6 +12,7 @@ import (
 	"go.uber.org/zap"
 	"pkg.jsn.cam/caddy-defender/matchers/ip"
 	"pkg.jsn.cam/caddy-defender/responders"
+	"pkg.jsn.cam/caddy-defender/responders/headertarpit"
 	"pkg.jsn.cam/caddy-defender/responders/tarpit"
 )
 
@@ -25,13 +26,20 @@ func init() {
 var (
 	// DefaultRanges is the default ranges to block if none are specified.
 	DefaultRanges = []string{"aws", "gcloud", "azurepubliccloud", "openai", "deepseek", "githubcopilot"}
+
 	// Tarpit Defaults
 	// defaultTarpitTimeout is the default duration for a request to be closed after.
 	defaultTarpitTimeout = time.Second * 30
 	// defaultTarpitBytesPerSecond is the default amount of bytes to stream per second.
 	defaultTarpitBytesPerSecond = 24
 	// defaultTarpitResponseCode is the default HTTP respond code for the tarpit responder.
 	defaultTarpitResponseCode = http.StatusOK
+
+	// Header Tarpit Defaults
+	// defaultHeaderTarpitTimeout is the default duration for a request to be closed after.
+	defaultHeaderTarpitTimeout = time.Second * 30
+	// defaultTarpitHeaderDelaySecond is the default delay between each successive header responses
+	defaultHeaderTarpitDelaySecond = 4
 )
 
 // Defender implements an HTTP middleware that enforces IP-based rules to protect your site from AIs/Scrapers.
@@ -85,7 +93,7 @@ type Defender struct {
 	URL string `json:"url,omitempty"`
 
 	// RawResponder defines the response strategy for blocked requests.
-	// Required. Must be one of: "block", "custom", "drop", "garbage", "redirect", "tarpit"
+	// Required. Must be one of: "block", "custom", "drop", "garbage", "redirect", "tarpit", "headertarpit"
 	RawResponder string `json:"raw_responder,omitempty"`
 
 	// Ranges specifies IP ranges to block, which can be either:
@@ -103,6 +111,10 @@ type Defender struct {
 	// Default: {Headers: {}, timeout: 30s, ResponseCode: 200}
 	TarpitConfig tarpit.Config `json:"tarpit_config,omitempty"`
 
+	// An optional configuration for the 'tarpit' responder
+	// Default: {Headers: {}, timeout: 30s, ResponseCode: 200}
+	HeaderTarpitConfig headertarpit.Config `json:"header_tarpit_config,omitempty"`
+
 	// StatusCode specifies the HTTP status code for 'custom' responder type.
 	// Optional. Default: 200
 	StatusCode int `json:"status_code,omitempty"`
@@ -150,6 +162,16 @@ func (m *Defender) Provision(ctx caddy.Context) error {
 		}
 	}
 
+	if m.RawResponder == "header_tarpit" {
+		if m.HeaderTarpitConfig.Timeout == 0 {
+			m.HeaderTarpitConfig.Timeout = defaultHeaderTarpitTimeout
+		}
+
+		if m.HeaderTarpitConfig.DelaySecond == 0 {
+			m.HeaderTarpitConfig.DelaySecond = defaultHeaderTarpitDelaySecond
+		}
+	}
+
 	return nil
 }
 

responders/headertarpit/headertarpit.go

@@ -0,0 +1,78 @@
+package headertarpit
+
+import (
+	"errors"
+	"fmt"
+	"math/rand/v2"
+	"net/http"
+	"time"
+
+	"github.com/caddyserver/caddy/v2/modules/caddyhttp"
+)
+
+// Config holds the tarpit responder's configuration.
+type Config struct {
+	Headers      map[string]string `json:"headers"`
+	Timeout      time.Duration     `json:"timeout"`
+	DelaySecond  int               `json:"header_per_second"`
+	ResponseCode int               `json:"code"`
+}
+
+// Responder returns a custom response.
+type Responder struct {
+	Config *Config
+}
+
+func (r *Responder) ServeHTTP(w http.ResponseWriter, req *http.Request, _ caddyhttp.Handler) error {
+	hj, ok := w.(http.Hijacker)
+	if !ok {
+		http.Error(w, "webserver doesn't support hijacking", http.StatusInternalServerError)
+		return errors.New("webserver doesn't support hijacking")
+	}
+
+	conn, bufrw, err := hj.Hijack()
+	if err != nil {
+		http.Error(w, err.Error(), http.StatusInternalServerError)
+		return err
+	}
+
+	defer conn.Close()
+
+	h := fmt.Sprintf("HTTP/1.1 %d %s\n", r.Config.ResponseCode, http.StatusText(r.Config.ResponseCode))
+	bufrw.WriteString(h)
+	bufrw.Flush()
+
+	// Write any prelude headers
+	for key, value := range r.Config.Headers {
+		bufrw.WriteString(fmt.Sprintf("%s: %s\n", key, value))
+	}
+
+	bufrw.Flush()
+
+	// Write successive headers per delay
+	ticker := time.NewTicker(time.Duration(r.Config.DelaySecond) * time.Second)
+	defer ticker.Stop()
+
+	timeout := time.After(r.Config.Timeout)
+
+	for {
+		select {
+		case <-ticker.C:
+			s := fmt.Sprintf("X-%016x: %016x\n", rand.Uint64(), rand.Uint64())
+			bufrw.WriteString(s)
+			bufrw.Flush()
+		case <-timeout:
+			return nil
+		}
+	}
+}
+
+func (r *Responder) Validate() error {
+	if r.Config.Timeout <= 0 {
+		return errors.New("header_tarpit timeout must be greater than 0")
+	}
+	if r.Config.DelaySecond <= 0 {
+		return errors.New("header_tarpit header_per_second must be greater than 0")
+	}
+	return nil
+}

responders/headertarpit/headertarpit_test.go

@@ -0,0 +1,17 @@
+package headertarpit
+
+import (
+	"time"
+)
+
+// Helper function to create a new responder
+func newTestResponder(content Content, timeout time.Duration) *Responder {
+	return &Responder{
+		Config: &Config{
+			Content:        content,
+			Timeout:        timeout,
+			DelayPerSecond: 4,
+			ResponseCode:   200,
+		},
+	}
+}

responders/tarpit/tarpit.go

@@ -25,11 +25,12 @@ type Content struct {
 
 // Config holds the tarpit responder's configuration.
 type Config struct {
-	Headers        map[string]string `json:"headers"`
-	Content        Content
-	Timeout        time.Duration `json:"timeout"`
-	BytesPerSecond int           `json:"bytes_per_second"`
-	ResponseCode   int           `json:"code"`
+	Headers         map[string]string `json:"headers"`
+	Content         Content
+	Timeout         time.Duration `json:"timeout"`
+	HeaderPerSecond int           `json:"header_per_second"`
+	BytesPerSecond  int           `json:"bytes_per_second"`
+	ResponseCode    int           `json:"code"`
 }
 
 // ConfigureContentReader checks the content protocol configuration