{"id":23480514,"url":"https://github.com/teler-sh/teler-caddy","last_synced_at":"2025-04-14T22:55:11.305Z","repository":{"id":245154836,"uuid":"817488336","full_name":"teler-sh/teler-caddy","owner":"teler-sh","description":"teler Caddy integrates the powerful security features of teler WAF into the Caddy web server, ensuring your web servers remain secure and resilient against web-based attacks.","archived":false,"fork":false,"pushed_at":"2025-02-24T20:59:50.000Z","size":216,"stargazers_count":13,"open_issues_count":2,"forks_count":2,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-04-14T22:55:05.915Z","etag":null,"topics":["caddy","caddy-module","caddy-plugin","caddyserver","teler","teler-caddy","teler-proxy","teler-resources","teler-waf"],"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":null,"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}},"created_at":"2024-06-19T20:28:34.000Z","updated_at":"2025-04-14T15:52:28.000Z","dependencies_parsed_at":"2024-06-20T05:49:36.479Z","dependency_job_id":"1ad323e6-3908-4bcb-8ff5-3c490219deab","html_url":"https://github.com/teler-sh/teler-caddy","commit_stats":null,"previous_names":["teler-sh/teler-caddy"],"tags_count":3,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/teler-sh%2Fteler-caddy","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/teler-sh%2Fteler-caddy/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/teler-sh%2Fteler-caddy/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/teler-sh%2Fteler-caddy/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/teler-sh","download_url":"https://codeload.github.com/teler-sh/teler-caddy/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248975330,"owners_count":21192208,"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","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":["caddy","caddy-module","caddy-plugin","caddyserver","teler","teler-caddy","teler-proxy","teler-resources","teler-waf"],"created_at":"2024-12-24T20:14:48.097Z","updated_at":"2025-04-14T22:55:11.278Z","avatar_url":"https://github.com/teler-sh.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# teler Caddy\n\n**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.\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-proxy](https://github.com/teler-sh/teler-proxy): teler Proxy enabling seamless integration with teler WAF.\n\n---\n\n* [Usage](#usage)\n  * [Configuration](#configuration)\n    * [`load_from` subdirective](#load_from-subdirective)\n    * [`inline` subdirective](#inline-subdirective)\n  * [Examples](#examples)\n* [Development](#development)\n* [JSON structure](#json-structure)\n* [Demo](#demo)\n* [Community](#community)\n* [License](#license)\n\n## Usage\n\nTo use this module, follow these steps:\n\n* Build the `caddy` core and plug-in this module with [xcaddy](https://github.com/caddyserver/xcaddy).\n\n```bash\nCGO_ENABLED=1 xcaddy build \\\n    --with github.com/teler-sh/teler-caddy@latest --output dist/caddy\n```\n\n* Add the **`teler_waf`** directive within your `route` configuration.\n* Then, run the Caddy server with the specified configuration: `./dist/caddy run --config /path/to/your/Caddyfile`.\n\nThat'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.\n\n### Configuration\n\nThis 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.\n\nHere is the syntax and usage for each subdirective:\n\n#### `load_from` subdirective\n\nUse this subdirective to load teler WAF configuration from a specified file. The configuration file can be in JSON or YAML format.\n\n```caddy\nload_from \u003cformat\u003e \u003cfilepath\u003e\n```\n\n\u003e [!NOTE]\n\u003e * **format**: Specifies the format of the teler WAF configuration file. Valid values are **`json`** and **`yaml`** *(case-insensitive)*.\n\u003e * **filepath**: Specifies the location path of the teler WAF configuration file.\n\n#### `inline` subdirective\n\nUse this subdirective to define teler WAF configuration options directly within the Caddyfile. The configuration can be provided in JSON or YAML format.\n\n```caddy\ninline \u003cformat\u003e \u003coptions\u003e\n```\n\nThese 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.\n\n### Examples\n\nHere are examples of how to configure this module using the **`load_from`** and **`inline`** subdirectives:\n\n* With **load_from** subdirective\n\nThis example demonstrates how to load the teler WAF configuration from a YAML or JSON file.\n\n```caddy\nexample.com {\n    route {\n        teler_waf {\n            load_from YAML /path/to/your/teler-waf.conf.yaml\n            # or\n            load_from JSON /path/to/your/teler-waf.conf.json\n        }\n    }\n}\n```\n\n* With **inline** subdirective\n\nThis example demonstrates how to define the teler WAF configuration directly within the Caddyfile.\n\n\u003e [!TIP]\n\u003e For better readability and management of options, write your teler WAF options using backticks or heredoc. See [Tokens and quotes](https://caddyserver.com/docs/caddyfile/concepts#tokens-and-quotes).\n\n```caddy\nexample.com {\n    route {\n        teler_waf {\n            inline YAML \u003c\u003c--\n                excludes: []\n                whitelists: []\n                customs: []\n                customs_from_file: \"\"\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    }\n}\n```\n\n\u003e [!TIP]\n\u003e 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.\n\n```caddy\n{\n    order teler_waf first\n}\n\nexample.com {\n    teler_waf {\n        # load_from ...\n        # inline ...\n    }\n}\n```\n\nThese examples illustrate how to effectively configure the teler WAF in Caddy using different methods, providing flexibility to suit your specific setup and requirements.\n\n## Development\n\nHere are the available commands to assist with development:\n\n```console\n$ make\nhelp                           Displays this help message\nbuild                          Builds the Caddy core and plug-in teler WAF module (Output: ./dist/caddy)\nbuild-local                    Same as `build` but use teler WAF module locally\nadapt                          Converts a Caddyfile to Caddy's native JSON format (Output: ./caddy.example.json)\nrun                            Runs the Caddy with Caddy's native JSON configuration\nrun-httpbin                    Runs the httpbin server with port 8081\n```\n\n## JSON Structure\n\nHere is how you can configure this module using both the Caddyfile and its equivalent Caddy's native JSON structure.\n\nCaddyfile:\n\n```caddy\n:8080 {\n    route {\n        teler_waf\n    }\n\n    reverse_proxy localhost:8081\n}\n```\n\nThe same configuration can be expressed in Caddy's native JSON structure as follows:\n\n```json\n{\n  \"apps\": {\n    \"http\": {\n      \"servers\": {\n        \"srv0\": {\n          \"listen\": [\n            \":8080\"\n          ],\n          \"routes\": [\n            {\n              \"handle\": [\n                {\n                  \"handler\": \"subroute\",\n                  \"routes\": [\n                    {\n                      \"handle\": [\n                        {\n                          \"format\": \"\",\n                          \"handler\": \"teler\",\n                          \"inline\": \"\",\n                          \"load_from\": \"\"\n                        }\n                      ]\n                    }\n                  ]\n                },\n                {\n                  \"handler\": \"reverse_proxy\",\n                  \"upstreams\": [\n                    {\n                      \"dial\": \"localhost:8081\"\n                    }\n                  ]\n                }\n              ]\n            }\n          ]\n        }\n      }\n    }\n  }\n}\n```\n\n## Demo\n\nTo demonstrate the teler Caddy module in action, follow these steps:\n\n```bash\n# in: tty1\n$ make build-local\n$ make run-httpbin\n\n# in: tty2\n$ make run\n\n# in: tty3\n$ curl localhost:8080\n\n# out: tty2\n2024/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}\n```\n\nThis 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.\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-caddy/discussions/categories/q-a), [discussions](https://github.com/teler-sh/teler-caddy/discussions), or [issues](https://github.com/teler-sh/teler-caddy/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 module is free software: you can redistribute it and/or modify it under the terms of the [Apache-2.0 license](/LICENSE). teler-caddy and any contributions are copyright © by Dwi Siswanto 2024.","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fteler-sh%2Fteler-caddy","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fteler-sh%2Fteler-caddy","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fteler-sh%2Fteler-caddy/lists"}