{"id":23480513,"url":"https://github.com/teler-sh/teler-proxy","last_synced_at":"2025-10-28T03:47:24.148Z","repository":{"id":198635102,"uuid":"662829242","full_name":"teler-sh/teler-proxy","owner":"teler-sh","description":"🔐 teler Proxy enabling seamless integration with teler WAF 🛡️ to protect locally running web service against a web-based attacks. 🥷","archived":false,"fork":false,"pushed_at":"2025-02-24T09:10:35.000Z","size":3373,"stargazers_count":51,"open_issues_count":4,"forks_count":9,"subscribers_count":4,"default_branch":"master","last_synced_at":"2025-10-24T04:31:28.774Z","etag":null,"topics":["firewall","intrusion-detection","intrusion-prevention","proxy-server","reverse-proxy","secure-by-default","teler","teler-proxy","teler-waf","tunnel-server","waf","web-application-firewall","web-application-security"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/teler-sh.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":"CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null},"funding":{"github":["dwisiswant0"]}},"created_at":"2023-07-06T01:32:56.000Z","updated_at":"2025-07-29T13:33:58.000Z","dependencies_parsed_at":"2023-10-24T06:25:20.550Z","dependency_job_id":"2216191d-f582-4c0f-9d37-c37821ef74a4","html_url":"https://github.com/teler-sh/teler-proxy","commit_stats":null,"previous_names":["kitabisa/teler-proxy","teler-sh/teler-proxy"],"tags_count":9,"template":false,"template_full_name":null,"purl":"pkg:github/teler-sh/teler-proxy","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/teler-sh%2Fteler-proxy","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/teler-sh%2Fteler-proxy/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/teler-sh%2Fteler-proxy/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/teler-sh%2Fteler-proxy/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/teler-sh","download_url":"https://codeload.github.com/teler-sh/teler-proxy/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/teler-sh%2Fteler-proxy/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":281381650,"owners_count":26491160,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-28T02:00:06.022Z","response_time":60,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["firewall","intrusion-detection","intrusion-prevention","proxy-server","reverse-proxy","secure-by-default","teler","teler-proxy","teler-waf","tunnel-server","waf","web-application-firewall","web-application-security"],"created_at":"2024-12-24T20:14:48.076Z","updated_at":"2025-10-28T03:47:24.117Z","avatar_url":"https://github.com/teler-sh.png","language":"Go","funding_links":["https://github.com/sponsors/dwisiswant0"],"categories":[],"sub_categories":[],"readme":"# teler Proxy\n\n[![codecov](https://codecov.io/gh/teler-sh/teler-proxy/graph/badge.svg?token=QST60Y6BDD)](https://codecov.io/gh/teler-sh/teler-proxy)\n[![Tests](https://github.com/teler-sh/teler-proxy/actions/workflows/tests.yaml/badge.svg?branch=master)](https://github.com/teler-sh/teler-proxy/actions/workflows/tests.yaml)\n[![Release](https://img.shields.io/github/v/release/teler-sh/teler-proxy?color=violet)](https://github.com/teler-sh/teler-proxy/releases)\n[![Platform](https://img.shields.io/badge/platform-osx%2Flinux%2Fwindows-blueviolet)](#)\n\n\u003cimg src=\"https://user-images.githubusercontent.com/25837540/97091757-7200d880-1668-11eb-82c4-e5c4971d2bc8.png\" align=\"right\" width=\"250px\"/\u003e\n\nteler Proxy enabling seamless integration with [teler WAF](https://github.com/teler-sh/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.\n\n**See also:**\n\n* [teler-sh/teler](https://github.com/teler-sh/teler): Real-time HTTP Intrusion Detection.\n* [teler-sh/teler-waf](https://github.com/teler-sh/teler-waf): Go HTTP middleware that provides teler IDS functionality.\n* [teler-sh/teler-caddy](https://github.com/teler-sh/teler-caddy): teler Caddy integrates the powerful security features of teler WAF into the Caddy web server\n\nhttps://github.com/teler-sh/teler-proxy/assets/25837540/df36af09-080a-4cff-98d8-fd2071f602fa\n\n---\n\n**Table of Contents**\n\n* [Architecture](#architecture)\n* [Install](#installation)\n  * [Binary](#binary)\n  * [Source](#source)\n  * [Docker](#docker)\n* [Usage](#usage)\n  * [Options](#options)\n* [Configuration](#configuration)\n  * [Excludes](#excludes)\n  * [Whitelists](#whitelists)\n  * [Customs](#customs)\n  * [Customs from File](#customs-from-file)\n  * [Log File](#log-file)\n  * [No Stderr](#no-stderr)\n  * [No Update Check](#no-update-check)\n  * [Development](#development)\n  * [In Memory](#in-memory)\n  * [FalcoSidekick URL](#falcosidekick-url)\n  * [Verbose](#verbose)\n* [Demo](#demo)\n* [Community](#community)\n* [License](#license)\n\n## Architecture\n\n```mermaid\n%% ---\n%% title: teler WAF proxy architecture\n%% ---\nsequenceDiagram\n    participant internet as Internet 🌐\n    box Internal network\n        participant proxy as teler-proxy 🔐\n        participant server as Server 💻\n    end\n\n    internet-\u003e\u003eproxy: request 🙋‍♂️\n\n    Note over proxy: analyze request 🔍\n    alt if \"you're bad! 😈\"\n        proxy-\u003e\u003einternet: early return 🏃\n    else else 👍🏻\n        proxy-\u003e\u003eserver: forward request ↪️\n    end\n\n    server--\u003e\u003eproxy: respond 💬\n    proxy-\u003e\u003einternet: \"copy that!\" ↩️\n```\n\n## Installation\n\n### Binary\n\nSimply, download a pre-built binary from [releases page](https://github.com/teler-sh/teler-proxy/releases). Unpack and run!\n\n### Source\n\n**Dependencies**:\n\n* **gcc** (GNU Compiler Collection) should be installed \u0026 configured to compile teler-waf.\n\nUsing [Go](https://golang.org/doc/install) (v1.20+) compiler:\n\n```bash\nCGO_ENABLED=1 go install github.com/teler-sh/teler-proxy/cmd/teler-proxy@latest\n```\n\n### — or\n\nManual building executable from source code:\n\n\u003e [!WARNING]\n\u003e The `master` branch contains the latest code changes and updates, which might not have undergone thorough testing and quality assurance - thus, you may encounter instability and unexpected behavior.\n\n```bash\ngit clone https://github.com/teler-sh/teler-proxy.git\ncd teler-proxy/\n# git checkout [VERSION TAG]\nmake build\n```\n\n\u003e [!TIP]\n\u003e If you're using Go version 1.20 or newer, you can build the executable file with our automatically generated default PGO\u003csup\u003e[\u003ca href=\"https://go.dev/doc/pgo\"\u003e?\u003c/a\u003e]\u003c/sup\u003e profile _(see [pgo branch](https://github.com/teler-sh/teler-proxy/tree/pgo))_ to improve the performance by using `make build-pgo` command.\n\n### Docker\n\nPull the [Docker](https://docs.docker.com/get-docker/) image by running:\n\n```bash\ndocker pull ghcr.io/teler-sh/teler-proxy:latest\n```\n\n## Usage\n\nSimply, `teler-proxy` can be run with:\n\n```bash\nteler-proxy -d \u003cADDR\u003e:\u003cPORT\u003e [OPTIONS...]\n```\n\n### Options\n\n\u003cimg src=\"https://github.com/teler-sh/teler-proxy/assets/25837540/caed92a2-a88b-4708-aa5b-70dc49d84aee\" width=\"50%\"\u003e\n\nHere are all the options it supports.\n\n```bash\nteler-proxy -h\n```\n\n|          **Flag**          |                            **Description**                            |\n| -------------------------- | --------------------------------------------------------------------- |\n| -p, --port `\u003cPORT\u003e`        | Set the local port to listen on **(default: 1337)**                   |\n| -d, --dest `\u003cADDR\u003e:\u003cPORT\u003e` | Set the destination address for forwarding requests                   |\n| -c, --conf `\u003cFILE\u003e`        | Specify the path to the teler WAF configuration file                  |\n| -f, --format `\u003cFORMAT\u003e`    | Specify the configuration file format (json/yaml) **(default: yaml)** |\n| --cert `\u003cFILE\u003e`            | Specify the path to the SSL certificate file                          |\n| --key `\u003cFILE\u003e`             | Specify the path to the SSL private key file                          |\n| -V, --version              | Display the current teler-proxy version                               |\n| -h, --help                 | Display this helps text                                               |\n\n## Configuration\n\nThe 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.\n\n\u003e [!NOTE]\n\u003e When you supply a configuration file and subsequently make alterations to that configuration, teler Proxy will promptly initiate a live reload, ensuring that the updated settings are applied in real-time without the need for manual intervention or restarting the teler Proxy.\n\nIn 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.\n\nThe default configuration options are presented below in YAML format:\n\n```yaml\nexcludes: []\nwhitelists: []\ncustoms: []\ncustoms_from_file: \"\"\nresponse:\n    status: 0\n    html: \"\"\n    html_file: \"\"\nlog_file: \"\"\nno_stderr: false\nno_update_check: false\ndevelopment: false\nin_memory: false\nfalcosidekick_url: \"\"\nverbose: false\n```\n\nOr the equivalent in JSON format:\n\n```json\n{\n  \"excludes\": [],\n  \"whitelists\": [],\n  \"customs\": [],\n  \"customs_from_file\": \"\",\n  \"response\": {\n    \"status\": 0,\n    \"html\": \"\",\n    \"html_file\": \"\"\n  },\n  \"log_file\": \"\",\n  \"no_stderr\": false,\n  \"no_update_check\": false,\n  \"development\": false,\n  \"in_memory\": false,\n  \"falcosidekick_url\": \"\",\n  \"verbose\": false\n}\n```\n\nBy 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.\n\n### Excludes\n\n\u003e [!WARNING]\n\u003e Threat exclusions (`Excludes`) will be deprecated in the upcoming teler-waf release (**v2**), use [`Whitelists`](#whitelists) instead. See [teler-waf#73](https://github.com/teler-sh/teler-waf/discussions/73).\n\nExcludes (**excludes**) is a list of threat types (`[]int`) to exclude from the security checks. Please refer to the [docs](https://pkg.go.dev/github.com/teler-sh/teler-waf/threat#Threat).\n\n\u003e **Note**\n\u003e * **1** for `CommonWebAttack`\n\u003e * **2** for `CVE`\n\u003e * **3** for `BadIPAddress`\n\u003e * **4** for `BadReferrer`\n\u003e * **5** for `BadCrawler`\n\u003e * **6** for `DirectoryBruteforce`\n\n### Whitelists\n\nWhitelists (**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](https://github.com/teler-sh/teler-waf#dsl-expression).\n\n### Customs\n\nCustoms (**customs**) is a list of custom security rules (`[]teler.Rule`) to apply to incoming requests.\n\nThese 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](https://github.com/teler-sh/teler-waf#custom-rules).\n\n### Customs from File\n\nCustoms 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.\n\nThe 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](https://github.com/teler-sh/teler-waf#custom-rules).\n\n### Custom Response\n\nResponse (**response**) is the configuration for custom error response pages when a request is blocked or rejected. Please refer to the [docs](https://github.com/teler-sh/teler-waf#custom-response).\n\n### Log File\n\nLog 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**).\n\n### No Stderr\n\nNo stderr (**no_stderr**) is a boolean flag indicating whether or not to suppress log messages from being printed to the standard error (stderr) stream.\n\nWhen 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`).\n\n### No Update Check\n\nNo update check (**no_update_check**) is a boolean flag indicating whether or not to disable automatic threat dataset updates.\n\nWhen 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](https://github.com/teler-sh/teler-waf#datasets).\n\n### Development\n\nDevelopment (**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](https://github.com/teler-sh/teler-waf#development).\n\n### In Memory\n\nIn memory (**in_memory**) is a boolean flag that specifies whether or not to load the threat dataset into memory on initialization.\n\nWhen 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](https://github.com/teler-sh/teler-waf#datasets).\n\n### FalcoSidekick URL\n\nFalcoSidekick URL (**falcosidekick_url**) is the URL of the FalcoSidekick endpoint to which teler-waf's events will be forwarded.\n\nThis field should be set to the URL of your FalcoSidekick instance, including the protocol \u0026 port (e.g. \"http://localhost:2801\"). Please refer to the [docs](https://github.com/teler-sh/teler-waf#falco-sidekick).\n\n### Verbose\n\nVerbose (**verbose**) is a boolean flag that controls whether verbose logging is enabled. When set to `true`, it enables detailed and informative logging messages.\n\n## Demo\n\nTo 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/](/demo) directory.\n\n## Community\n\nWe use the Google Groups as our dedicated mailing list. Subscribe to [teler-announce](https://groups.google.com/g/teler-announce) via [teler-announce+subscribe@googlegroups.com](mailto: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](https://github.com/teler-sh/teler), [teler WAF](https://github.com/teler-sh/teler-waf), [teler Proxy](https://github.com/teler-sh/teler-proxy), [teler Caddy](https://github.com/teler-sh/teler-caddy) and [teler Resources](https://github.com/teler-sh/teler-resources).\n\nFor any [inquiries](https://github.com/teler-sh/teler-proxy/discussions/categories/q-a), [discussions](https://github.com/teler-sh/teler-proxy/discussions), or [issues](https://github.com/teler-sh/teler-proxy/issues) are being tracked here on GitHub. This is where we actively manage and address these aspects of our community engagement.\n\n## License\n\nThis 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](/LICENSE). Kitabisa teler-proxy and any contributions are copyright © by Dwi Siswanto 2023.","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fteler-sh%2Fteler-proxy","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fteler-sh%2Fteler-proxy","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fteler-sh%2Fteler-proxy/lists"}