teler

README

teler Caddy

teler-caddy integrates the robust security features of teler WAF into the Caddy web server. With the teler Caddy module, you can leverage these comprehensive security measures to ensure your web servers remain secure and resilient against OWASP Top 10 threats, known vulnerabilities, malicious actors, botnets, unwanted crawlers, and brute force attacks.

See also:

• teler-sh/teler: Real-time HTTP Intrusion Detection.
• teler-sh/teler-waf: Go HTTP middleware that provides teler IDS functionality.
• teler-sh/teler-proxy: teler Proxy enabling seamless integration with teler WAF.

---

• Usage
  • Configuration
    • load_from subdirective
    • inline subdirective
  • Examples
• Development
• JSON structure
• Demo
• Community
• License

Usage

To use this module, follow these steps:

• Build the caddy core and plug-in this module with xcaddy.

CGO_ENABLED=1 xcaddy build \
    --with github.com/teler-sh/teler-caddy@latest --output dist/caddy

• Add the teler_waf directive within your route configuration.
• Then, run the Caddy server with the specified configuration: ./dist/caddy run --config /path/to/your/Caddyfile.

That's it! By following these steps, you will integrate teler WAF into your Caddy server. The teler WAF now will seamlessly apply a default configuration, ensuring that your site remains protected with sensible and reasonable settings.

Configuration

This module allows for fine-tuning and customization through two subdirectives: load_from and inline. These subdirectives enable you to set various options to tailor the behavior of the teler WAF to meet your specific security needs.

Here is the syntax and usage for each subdirective:

load_from subdirective

Use this subdirective to load teler WAF configuration from a specified file. The configuration file can be in JSON or YAML format.

load_from <format> <filepath>

[!NOTE]

• format: Specifies the format of the teler WAF configuration file. Valid values are json and yaml (case-insensitive).
• filepath: Specifies the location path of the teler WAF configuration file.

inline subdirective

Use this subdirective to define teler WAF configuration options directly within the Caddyfile. The configuration can be provided in JSON or YAML format.

inline <format> <options>

These configuration subdirectives provide flexibility in managing the teler WAF settings, allowing you to either load configurations from an external file or define them directly within your Caddyfile, ensuring that your web servers are adequately protected with tailored security measures.

Examples

Here are examples of how to configure this module using the load_from and inline subdirectives:

• With load_from subdirective

This example demonstrates how to load the teler WAF configuration from a YAML or JSON file.

example.com {
    route {
        teler_waf {
            load_from YAML /path/to/your/teler-waf.conf.yaml
            # or
            load_from JSON /path/to/your/teler-waf.conf.json
        }
    }
}

• With inline subdirective

This example demonstrates how to define the teler WAF configuration directly within the Caddyfile.

[!TIP] For better readability and management of options, write your teler WAF options using backticks or heredoc. See Tokens and quotes.

example.com {
    route {
        teler_waf {
            inline YAML <<--
                excludes: []
                whitelists: []
                customs: []
                customs_from_file: ""
                log_file: ""
                no_stderr: false
                no_update_check: false
                development: false
                in_memory: false
                falcosidekick_url: ""
                verbose: false
                --
        }
    }
}

[!TIP] To apply this module globally as middleware across all routes, reorder the teler WAF module directive to be the first in the Caddy's HTTP handler chain.

{
    order teler_waf first
}

example.com {
    teler_waf {
        # load_from ...
        # inline ...
    }
}

These examples illustrate how to effectively configure the teler WAF in Caddy using different methods, providing flexibility to suit your specific setup and requirements.

Development

Here are the available commands to assist with development:

$ make
help                           Displays this help message
build                          Builds the Caddy core and plug-in teler WAF module (Output: ./dist/caddy)
build-local                    Same as `build` but use teler WAF module locally
adapt                          Converts a Caddyfile to Caddy's native JSON format (Output: ./caddy.example.json)
run                            Runs the Caddy with Caddy's native JSON configuration
run-httpbin                    Runs the httpbin server with port 8081

JSON Structure

Here is how you can configure this module using both the Caddyfile and its equivalent Caddy's native JSON structure.

Caddyfile:

:8080 {
    route {
        teler_waf
    }

    reverse_proxy localhost:8081
}

The same configuration can be expressed in Caddy's native JSON structure as follows:

{
  "apps": {
    "http": {
      "servers": {
        "srv0": {
          "listen": [
            ":8080"
          ],
          "routes": [
            {
              "handle": [
                {
                  "handler": "subroute",
                  "routes": [
                    {
                      "handle": [
                        {
                          "format": "",
                          "handler": "teler",
                          "inline": "",
                          "load_from": ""
                        }
                      ]
                    }
                  ]
                },
                {
                  "handler": "reverse_proxy",
                  "upstreams": [
                    {
                      "dial": "localhost:8081"
                    }
                  ]
                }
              ]
            }
          ]
        }
      }
    }
  }
}

Demo

To demonstrate the teler Caddy module in action, follow these steps:

# in: tty1
$ make build-local
$ make run-httpbin

# in: tty2
$ make run

# in: tty3
$ curl localhost:8080

# out: tty2
2024/06/19 23:15:29.580 ERROR   http.log.error  bad crawler {"request": {"remote_ip": "::1", "remote_port": "59510", "client_ip": "::1", "proto": "HTTP/1.1", "method": "GET", "host": "localhost:8080", "uri": "/", "headers": {"User-Agent": ["curl/8.6.0"], "Accept": ["*/*"]}}, "duration": 0.004394569}

This demo showcases the module's ability to detect and defend against various forms of cyber threats, providing an example of its protective capabilities in a real-world scenario.

Community

We use the Google Groups as our dedicated mailing list. Subscribe to teler-announce via teler-announce+subscribe@googlegroups.com for important announcements, such as the availability of new releases. This subscription will keep you informed about significant developments related to teler IDS, teler WAF, teler Proxy, teler Caddy, and teler Resources.

For any inquiries, discussions, or issues are being tracked here on GitHub. This is where we actively manage and address these aspects of our community engagement.

License

This module is free software: you can redistribute it and/or modify it under the terms of the Apache-2.0 license. teler-caddy and any contributions are copyright © by Dwi Siswanto 2024.

Documentation

Overview

Package teler offers middleware that integrates the robust security features of teler WAF into the Caddy server. It provides comprehensive protection against a wide range of web-based threats, ensuring that web servers remain secure and resilient. This package includes configuration options and tools to customize the behavior of teler WAF to meet specific security needs within the Caddy server environment.

Index

• Variables
• type Loader
• type Middleware
  • func (Middleware) CaddyModule() caddy.ModuleInfo
  • func (m *Middleware) Provision(ctx caddy.Context) error
  • func (m Middleware) ServeHTTP(w http.ResponseWriter, r *http.Request, next caddyhttp.Handler) error
  • func (m *Middleware) UnmarshalCaddyfile(d *caddyfile.Dispenser) error
  • func (m *Middleware) Validate() error

Variables

var (
	ErrNoTelerInstance = errors.New("no Teler instance initialized")
)

exported

Types

type Loader

type Loader func(string) (teler.Options, error)

Loader is a function type that loads teler WAF options from a file path or string.

type Middleware

type Middleware struct {
	// Options holds the settings for teler WAF.
	teler.Options `json:"-"`

	// Format is the type of configuration file, either "json" or "yaml".
	Format string `json:"format"`

	// LoadFrom is the path to the configuration file.
	LoadFrom string `json:"load_from"`

	// Inline is the configuration options written directly as a string.
	Inline string `json:"inline"`
	// contains filtered or unexported fields
}

Middleware integrates the robust security features of teler WAF into the Caddy web server, ensuring your web servers remain secure and resilient against web-based attacks.

func (Middleware) CaddyModule

func (Middleware) CaddyModule() caddy.ModuleInfo

CaddyModule returns the Caddy module information.

func (*Middleware) Provision

func (m *Middleware) Provision(ctx caddy.Context) error

Provision implements caddy.Provisioner.

func (Middleware) ServeHTTP

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

ServeHTTP implements caddyhttp.MiddlewareHandler.

func (*Middleware) UnmarshalCaddyfile

func (m *Middleware) UnmarshalCaddyfile(d *caddyfile.Dispenser) error

UnmarshalCaddyfile implements caddyfile.Unmarshaler.

func (*Middleware) Validate

func (m *Middleware) Validate() error

Validate implements caddy.Validator.