teler Proxy enabling seamless integration with teler WAF to protect locally running web service against a variety of web-based attacks, such as OWASP Top 10 categories like cross-site scripting (XSS) or SQL injection, known vulnerabilities or exploits, malicious actors, botnets, unwanted crawlers or scrapers, and directory bruteforce attacks.

See also:

• kitabisa/teler: Real-time HTTP Intrusion Detection.
• kitabisa/teler-waf: Go HTTP middleware that provides teler IDS functionality.

Table of Contents

• Architecture
• Install
  • Binary
  • Source
  • Docker
• Usage
  • Options
• Configuration
  • Excludes
  • Whitelists
  • Customs
  • Customs from File
  • Log File
  • No Stderr
  • No Update Check
  • Development
  • In Memory
  • FalcoSidekick URL
  • Verbose
• Demo
• Community
• License

%% ---
%% title: teler WAF proxy architecture
%% ---
sequenceDiagram
    participant internet as Internet 🌐
    box Internal network
        participant proxy as teler-proxy 🔐
        participant server as Server 💻
    end

    internet->>proxy: request 🙋‍♂️

    Note over proxy: analyze request 🔍
    alt if "you're bad! 😈"
        proxy->>internet: early return 🏃
    else else 👍🏻
        proxy->>server: forward request ↪️
    end

    server-->>proxy: respond 💬
    proxy->>internet: "copy that!" ↩️

Simply, download a pre-built binary from releases page. Unpack and run!

Dependencies:

• gcc (GNU Compiler Collection) should be installed & configured to compile teler-waf.

Using Go (v1.20+) compiler:

CGO_ENABLED=1 go install github.com/kitabisa/teler-proxy/cmd/teler-proxy@latest

Manual building executable from source code:

git clone https://github.com/kitabisa/teler-proxy.git
cd teler-proxy/
# git checkout [VERSION TAG]
make build

Pull the Docker image by running:

docker pull ghcr.io/kitabisa/teler-proxy:latest

Simply, teler-proxy can be run with:

teler-proxy -d <ADDR>:<PORT> [OPTIONS...]

Here are all the options it supports.

teler-proxy -h

The configuration is provides a comprehensive set of options to fine-tune and tailor the behavior of the teler Web Application Firewall (WAF). Through the use of the teler WAF configuration (-c/--conf), you gain full control over how the WAF operates and responds to incoming traffic.

In case you opt not to provide a custom configuration file, the teler WAF will seamlessly apply a default configuration, ensuring that your application remains protected with sensible and reasonable settings.

The default configuration options are presented below in YAML format:

excludes: []
whitelists: []
customs: []
customs_from_file: ""
response:
    status: 0
    html: ""
    html_file: ""
log_file: ""
no_stderr: false
no_update_check: false
development: false
in_memory: false
falcosidekick_url: ""
verbose: false

Or the equivalent in JSON format:

{
  "excludes": [],
  "whitelists": [],
  "customs": [],
  "customs_from_file": "",
  "response": {
    "status": 0,
    "html": "",
    "html_file": ""
  },
  "log_file": "",
  "no_stderr": false,
  "no_update_check": false,
  "development": false,
  "in_memory": false,
  "falcosidekick_url": "",
  "verbose": false
}

By leveraging this versatile teler WAF configuration, you can fine-tune the WAF to perfectly align with your specific security requirements, ensuring maximum protection for your web service while enjoying the flexibility and power of teler WAF.

Excludes (excludes) is a list of threat types ([]int) to exclude from the security checks. Please refer to the docs.

Note

• 1 for CommonWebAttack
• 2 for CVE
• 3 for BadIPAddress
• 4 for BadReferrer
• 5 for BadCrawler
• 6 for DirectoryBruteforce

Whitelists (whitelists) is a list of DSL expressions ([]string) that match request elements that should be excluded from the security checks. Please refer to the docs.

Customs (customs) is a list of custom security rules ([]teler.Rule) to apply to incoming requests.

These rules can be used to create custom security checks or to override the default security checks provided by teler-waf. Please refer to the docs.

Customs from file (customs_from_file) specifies the file path or glob pattern (string) for loading custom security rules. These rules can be used to create custom security checks or to override the default security checks provided by teler IDS.

The glob pattern supports wildcards, allowing you to specify multiple files or a directory with matching files. For example, "/path/to/custom/rules/*/.yaml" will load all YAML files in the "rules" directory and its subdirectories. Please refer to the docs.

Response (response) is the configuration for custom error response pages when a request is blocked or rejected. Please refer to the docs.

Log file (log_file) is the file path (string) for the log file to store the security logs. If log_file is specified, log messages will be written to the specified file in addition to stderr (if no_stderr is false).

No stderr (no_stderr) is a boolean flag indicating whether or not to suppress log messages from being printed to the standard error (stderr) stream.

When set to true, log messages will not be printed to stderr. If set to false, log messages will be printed to stderr. By default, log messages are printed to stderr (false).

No update check (no_update_check) is a boolean flag indicating whether or not to disable automatic threat dataset updates.

When set to true, automatic updates will be disabled. If set to false, automatic updates will be enabled. By default, automatic updates are enabled (false). Please refer to the docs.

Development (development) is a boolean flag that determines whether the request is cached or not. By default, development mode is disabled (false) or requests will cached. Please refer to the docs.

In memory (in_memory) is a boolean flag that specifies whether or not to load the threat dataset into memory on initialization.

When set to true, the threat dataset will be loaded into memory, which can be useful when running your service or application on a distroless or runtime image, where file access may be limited or slow. If in_memory is set to false, the threat dataset will be downloaded and stored under the user-level cache directory on the first startup. Subsequent startups will use the cached dataset. Please refer to the docs.

FalcoSidekick URL (falcosidekick_url) is the URL of the FalcoSidekick endpoint to which teler-waf's events will be forwarded.

This field should be set to the URL of your FalcoSidekick instance, including the protocol & port (e.g. "http://localhost:2801"). Please refer to the docs.

Verbose (verbose) is a boolean flag that controls whether verbose logging is enabled. When set to true, it enables detailed and informative logging messages.

To experience the power of the teler WAF Proxy in action, simply follow these steps to set up and run the demo located in the demo/ directory.

We use the Google Groups as our dedicated mailing list. Subscribe to teler-announce via [email protected] 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, 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.

This program is developed and maintained by members of Kitabisa Security Team, and this is not an officially supported Kitabisa product. This program is free software: you can redistribute it and/or modify it under the terms of the Apache-2.0 license. Kitabisa teler-proxy and any contributions are copyright © by Dwi Siswanto 2023.