CaddyHeaderVerification

README

Caddy Header Verification

Caddy Header Verification is a Caddy addon designed to detect bots and potentially malicious clients by inspecting and validating incoming HTTP headers. It helps identify unusual, malformed, or manipulated headers commonly associated with automated or abusive traffic.

⚠️ This project is licensed under GPL-3.0.

---

✨ Features

• Detects malformed or suspicious HTTP headers
• Helps identify bot or automated traffic
• Integrates as a Caddy middleware
• Includes unit tests for header verification logic

---

🚀 Installation

This module must be compiled into a custom Caddy binary.

Install xcaddy

go install github.com/caddyserver/xcaddy/cmd/xcaddy@latest

Build Caddy with this module

xcaddy build --with github.com/IgnifexLabs/CaddyHeaderVerification

This produces a custom Caddy binary that includes the header verification middleware.

⚙️ Usage

Enable the middleware in your Caddyfile for the sites or routes you want to protect It is important to change the order in the caddy File. for chromium based applications the client hints are a valuable item and should be integrated.

{
    order headerchecker before respond
}

:8080 {
    header {
        Accept-CH "Sec-CH-Device-Memory, Sec-CH-DPR, Sec-CH-Prefers-Color-Scheme, Sec-CH-Prefers-Reduced-Motion, Sec-CH-Prefers-Reduced-Transparency, Sec-CH-UA, Sec-CH-UA-Arch, Sec-CH-UA-Bitness, Sec-CH-UA-Form-Factors, Sec-CH-UA-Full-Version, Sec-CH-UA-Full-Version-List, Sec-CH-UA-Mobile, Sec-CH-UA-Model, Sec-CH-UA-Platform, Sec-CH-UA-Platform-Version, Sec-CH-UA-WoW64, Sec-CH-Viewport-Height, Sec-CH-Viewport-Width, Sec-CH-Width"
        Critical-CH "Sec-CH-Device-Memory, Sec-CH-DPR,Sec-CH-UA, Sec-CH-UA-Arch,Sec-CH-UA-Bitness,Sec-CH-UA-Full-Version, Sec-CH-UA-Full-Version-List, Sec-CH-UA-Mobile, Sec-CH-UA-Model, Sec-CH-UA-Platform, Sec-CH-UA-Platform-Version, Sec-CH-UA-WoW64, Sec-CH-Viewport-Height, Sec-CH-Viewport-Width, Sec-CH-Width"    
    }
    headerchecker
    respond "OK"
}

🧪 Running Tests

Unit tests are included for validating header detection logic.

🤝 Contributing

Contributions are welcome!

Fork the repository

Create a feature or bugfix branch

Submit a pull request with a clear description

Please include tests for new functionality where possible.

📝 License

This project is licensed under the GNU General Public License v3.0. See the LICENSE

Documentation

Index

• Constants
• func CheckCorrectAcceptEncodingCheck(r *http.Request) bool
• func CheckSecCHDeviceMemoryequalto8(r *http.Request) bool
• func IsDevtoolsPath(r *http.Request) bool
• func ValidateClientHintWindowsPlatformVersion(platform string, platformVersion string) bool
• type HeaderChecker
  • func (HeaderChecker) CaddyModule() caddy.ModuleInfo
  • func (h HeaderChecker) DeterminUnRealisticHeaderCount(r *http.Request) bool
  • func (h *HeaderChecker) Provision(ctx caddy.Context) error
  • func (h HeaderChecker) ServeHTTP(w http.ResponseWriter, r *http.Request, next caddyhttp.Handler) error
  • func (h *HeaderChecker) UnmarshalCaddyfile(d *caddyfile.Dispenser) error
  • func (h HeaderChecker) ValidateSecChUaPlatformLinux(r *http.Request) bool

Constants

const DevtoolsPath = "/.well-known/appspecific/com.chrome.devtools.json"

Functions

func CheckCorrectAcceptEncodingCheck

func CheckCorrectAcceptEncodingCheck(r *http.Request) bool

func CheckSecCHDeviceMemoryequalto8

func CheckSecCHDeviceMemoryequalto8(r *http.Request) bool

memSetNot8 returns true if Sec-CH-Device-Memory is present and not "8".

func IsDevtoolsPath

func IsDevtoolsPath(r *http.Request) bool

func ValidateClientHintWindowsPlatformVersion

func ValidateClientHintWindowsPlatformVersion(platform string, platformVersion string) bool

ValidateClientHintWindowsPlatformVersion returns true if either: - platform is not Windows (no check on version), we need to research how to validate other parts - platform is Windows AND version is exactly "19.0.0".

Returns false if platform is Windows but version is missing/incorrect.

Types

type HeaderChecker

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

HeaderChecker checks various UA-related headers and compares their versions.

func (HeaderChecker) CaddyModule

func (HeaderChecker) CaddyModule() caddy.ModuleInfo

CaddyModule returns the Caddy module information.

func (HeaderChecker) DeterminUnRealisticHeaderCount

func (h HeaderChecker) DeterminUnRealisticHeaderCount(r *http.Request) bool

func (*HeaderChecker) Provision

func (h *HeaderChecker) Provision(ctx caddy.Context) error

func (HeaderChecker) ServeHTTP

func (h HeaderChecker) ServeHTTP(w http.ResponseWriter, r *http.Request, next caddyhttp.Handler) error

ServeHTTP inspects the headers and then calls the next handler.

func (*HeaderChecker) UnmarshalCaddyfile

func (h *HeaderChecker) UnmarshalCaddyfile(d *caddyfile.Dispenser) error

func (HeaderChecker) ValidateSecChUaPlatformLinux

func (h HeaderChecker) ValidateSecChUaPlatformLinux(r *http.Request) bool

The following function checks if there is a wrong implementation based on the fact that Linux has a hard implementation of X11; Linux x86_64