teler-sh / teler-waf Goto Github PK

Here are some patterns that won't compile based on threat category.

1. CommonWebAttack:

{Description:Detects hash-contained xss payload attacks, setter usage and property overloading ID:5 Impact:5 Rule:(?:\W\s*hash\s*[^\w\s-])|(?:\w+=\W*[^,]*,[^\s(]\s*\()|(?:\?"[^\s"]":)|(?:(?<!\/)__[a-z]+__)|(?:(?:^|[\s)\]\}])(?:s|g)etter\s*=) Tags:map[tag:[xss csrf]] pattern:<nil>}
{Description:Detects self-executing JavaScript functions ID:8 Impact:5 Rule:(?:\/\w*\s*\)\s*\()|(?:\([\w\s]+\([\w\s]+\)[\w\s]+\))|(?:(?<!(?:mozilla\/\d\.\d\s))\([^)[]+\[[^\]]+\][^)]*\))|(?:[^\s!][{([][^({[]+[{([][^}\])]+[}\])][\s+",\d]*[}\])])|(?:"\)?\]\W*\[)|(?:=\s*[^\s:;]+\s*[{([][^}\])]+[}\])];) Tags:map[tag:[xss csrf]] pattern:<nil>}
{Description:Detects JavaScript DOM/miscellaneous properties and methods ID:15 Impact:6 Rule:([^*:\s\w,.\/?+-]\s*)?(?<![a-z]\s)(?<![a-z\/_@\-\|])(\s*return\s*)?(?:create(?:element|attribute|textnode)|[a-z]+events?|setattribute|getelement\w+|appendchild|createrange|createcontextualfragment|removenode|parentnode|decodeuricomponent|\wettimeout|(?:ms)?setimmediate|option|useragent)(?(1)[^\w%"]|(?:\s*[^@\s\w%",.+\-])) Tags:map[tag:[xss csrf id rfe]] pattern:<nil>}
{Description:Detects possible includes and typical script methods ID:16 Impact:5 Rule:([^*\s\w,.\/?+-]\s*)?(?<![a-mo-z]\s)(?<![a-z\/_@])(\s*return\s*)?(?:alert|inputbox|showmod(?:al|eless)dialog|showhelp|infinity|isnan|isnull|iterator|msgbox|executeglobal|expression|prompt|write(?:ln)?|confirm|dialog|urn|(?:un)?eval|exec|execscript|tostring|status|execute|window|unescape|navigate|jquery|getscript|extend|prototype)(?(1)[^\w%"]|(?:\s*[^@\s\w%",.:\/+\-])) Tags:map[tag:[xss csrf id rfe]] pattern:<nil>}
{Description:Detects JavaScript object properties and methods ID:17 Impact:4 Rule:([^*:\s\w,.\/?+-]\s*)?(?<![a-z]\s)(?<![a-z\/_@])(\s*return\s*)?(?:hash|name|href|navigateandfind|source|pathname|close|constructor|port|protocol|assign|replace|back|forward|document|ownerdocument|window|top|this|self|parent|frames|_?content|date|cookie|innerhtml|innertext|csstext+?|outerhtml|print|moveby|resizeto|createstylesheet|stylesheets)(?(1)[^\w%"]|(?:\s*[^@\/\s\w%.+\-])) Tags:map[tag:[xss csrf id rfe]] pattern:<nil>}
{Description:Detects JavaScript array properties and methods ID:18 Impact:4 Rule:([^*:\s\w,.\/?+-]\s*)?(?<![a-z]\s)(?<![a-z\/_@\-\|])(\s*return\s*)?(?:join|pop|push|reverse|reduce|concat|map|shift|sp?lice|sort|unshift)(?(1)[^\w%"]|(?:\s*[^@\s\w%,.+\-])) Tags:map[tag:[xss csrf id rfe]] pattern:<nil>}
{Description:Detects JavaScript string properties and methods ID:19 Impact:4 Rule:([^*:\s\w,.\/?+-]\s*)?(?<![a-z]\s)(?<![a-z\/_@\-\|])(\s*return\s*)?(?:set|atob|btoa|charat|charcodeat|charset|concat|crypto|frames|fromcharcode|indexof|lastindexof|match|navigator|toolbar|menubar|replace|regexp|slice|split|substr|substring|escape|\w+codeuri\w*)(?(1)[^\w%"]|(?:\s*[^@\s\w%,.+\-])) Tags:map[tag:[xss csrf id rfe]] pattern:<nil>}
{Description:Detects JavaScript language constructs ID:20 Impact:4 Rule:(?:\)\s*\[)|([^*":\s\w,.\/?+-]\s*)?(?<![a-z]\s)(?<![a-z_@\|])(\s*return\s*)?(?:globalstorage|sessionstorage|postmessage|callee|constructor|content|domain|prototype|try|catch|top|call|apply|url|function|object|array|string|math|if|for\s*(?:each)?|elseif|case|switch|regex|boolean|location|(?:ms)?setimmediate|settimeout|setinterval|void|setexpression|namespace|while)(?(1)[^\w%"]|(?:\s*[^@\s\w%".+\-\/])) Tags:map[tag:[xss csrf id rfe]] pattern:<nil>}
{Description:Detects very basic XSS probings ID:21 Impact:3 Rule:(?:,\s*(?:alert|showmodaldialog|eval)\s*,)|(?::\s*eval\s*[^\s])|([^:\s\w,.\/?+-]\s*)?(?<![a-z\/_@])(\s*return\s*)?(?:(?:document\s*\.)?(?:.+\/)?(?:alert|eval|msgbox|showmod(?:al|eless)dialog|showhelp|prompt|write(?:ln)?|confirm|dialog|open))\s*(?:[^.a-z\s\-]|(?:\s*[^\s\w,.@\/+-]))|(?:java[\s\/]*\.[\s\/]*lang)|(?:\w\s*=\s*new\s+\w+)|(?:&\s*\w+\s*\)[^,])|(?:\+[\W\d]*new\s+\w+[\W\d]*\+)|(?:document\.\w) Tags:map[tag:[xss csrf id rfe]] pattern:<nil>}
{Description:Detects data: URL injections, VBS injections and common URI schemes ID:27 Impact:5 Rule:(?:(?:vbs|vbscript|data):.*[,+])|(?:\w+\s*=\W*(?!https?)\w+:)|(jar:\w+:)|(=\s*"?\s*vbs(?:ript)?:)|(language\s*=\s?"?\s*vbs(?:ript)?)|on\w+\s*=\*\w+\-"? Tags:map[tag:[xss rfe]] pattern:<nil>}
{Description:Detects possible event handlers ID:32 Impact:4 Rule:(?:[^\w\s=]on(?!g\&gt;)\w+[^=_+-]*=[^$]+(?:\W|\&gt;)?) Tags:map[tag:[xss csrf]] pattern:<nil>}
{Description:Detects obfuscated script tags and XML wrapped HTML ID:33 Impact:4 Rule:(?:\<\w*:?\s(?:[^\>]*)t(?!rong))|(?:\<scri)|(<\w+:\w+) Tags:map[tag:xss] pattern:<nil>}
{Description:Detects classic SQL injection probings 2/2 ID:43 Impact:6 Rule:(?:"\s*\*.+(?:or|id)\W*"\d)|(?:\^")|(?:^[\w\s"-]+(?<=and\s)(?<=or\s)(?<=xor\s)(?<=nand\s)(?<=not\s)(?<=\|\|)(?<=\&\&)\w+\()|(?:"[\s\d]*[^\w\s]+\W*\d\W*.*["\d])|(?:"\s*[^\w\s?]+\s*[^\w\s]+\s*")|(?:"\s*[^\w\s]+\s*[\W\d].*(?:#|--))|(?:".*\*\s*\d)|(?:"\s*or\s[^\d]+[\w-]+.*\d)|(?:[()*<>%+-][\w-]+[^\w\s]+"[^,]) Tags:map[tag:[sqli id lfi]] pattern:<nil>}
{Description:Detects MySQL comment-/space-obfuscated injections and backtick termination ID:57 Impact:5 Rule:(?:,.*[)\da-f"]"(?:".*"|\Z|[^"]+))|(?:\Wselect.+\W*from)|((?:select|create|rename|truncate|load|alter|delete|update|insert|desc)\s*\(\s*space\s*\() Tags:map[tag:[sqli id]] pattern:<nil>}
{Description:Detects basic XSS DoS attempts ID:65 Impact:5 Rule:(?:(^|\W)const\s+[\w\-]+\s*=)|(?:(?:do|for|while)\s*\([^;]+;+\))|(?:(?:^|\W)on\w+\s*=[\w\W]*(?:on\w+|alert|eval|print|confirm|prompt))|(?:groups=\d+\(\w+\))|(?:(.)\1{128,}) Tags:map[tag:[rfe dos]] pattern:<nil>}

2. BadCrawler, just Yandex(?!Search)

Is your feature request related to a problem? Please describe.
A clear and concise description of what the problem is. Ex. I'm always frustrated when [...]

Describe the solution you'd like
A clear and concise description of what you want to happen.

Describe alternatives you've considered
A clear and concise description of any alternative solutions or features you've considered.

Additional context
Add any other context or screenshots about the feature request here.

Is your feature request related to a problem? Please describe.
A clear and concise description of what the problem is. Ex. I'm always frustrated when [...]

Describe the solution you'd like
A clear and concise description of what you want to happen.

Describe alternatives you've considered
A clear and concise description of any alternative solutions or features you've considered.

Additional context
Add any other context or screenshots about the feature request here.

System Information
Operating System: Linux
Architecture: amd64
CPU: 11th Gen Intel(R) Core(TM) i9-11900H @ 2.50GHz
GOMAXPROCS: 4
teler-waf version: v1.1.7

Compilation

Note
teler WAF result of BenchmarkInitializeDefault, run yours with make bench-initalize command.
OWASP Coraza WAF v3 result of BenchmarkCRSCompilation.

Analyzed requests

Note
teler WAF result of BenchmarkAnalyzeDefault, run yours with make bench-analyze command.
OWASP Coraza WAF v3 result of BenchmarkCRSSimplePOST.

Note
teler WAF result of go-wrk -c 25 -d 10 "http://localhost:3000/path?query=value#fragments" -H "Referrer: https://teler.sh/" -H "User-Agent: X" -body "some=body".
OWASP Coraza WAF v2, v3, and ModSecurity results of Simple URLENCODED Request according to https://coraza.io/docs/reference/benchmarks/.

Conclusion

In conclusion, the benchmark results clearly indicate that teler WAF outperforms OWASP Coraza WAF v3 in terms of both compilation and request analysis. teler WAF demonstrates significantly lower values in the compilation phase, highlighting its efficiency in preparing and initializing the threat rules.

Moreover, teler WAF excels with remarkable lower values in the analysis of requests compared to OWASP Coraza WAF v3. This indicates that teler WAF is highly efficient at processing incoming requests, offering faster response times and lower memory consumption. Additionally, teler WAF maintains a substantially higher throughput with an impressive request per second rate and it operates at approx. 80x faster than OWASP Coraza WAF v3. This impressive performance can be attributed to teler WAF default behavior of caching all analyzed requests, a crucial feature for applications that demand high-speed traffic handling.

In summary, based on these benchmark results, teler WAF stands out as a high-performance web application firewall solution, providing faster compilation times and superior request handling performance when compared to OWASP Coraza WAF v3. These findings make teler WAF a compelling choice for organizations seeking enhanced security without compromising on speed and resource efficiency in their web applications.

Is your feature request related to a problem? Please describe.
A clear and concise description of what the problem is. Ex. I'm always frustrated when [...]

Describe the solution you'd like
A clear and concise description of what you want to happen.

Describe alternatives you've considered
A clear and concise description of any alternative solutions or features you've considered.

Additional context
Add any other context or screenshots about the feature request here.

Is your feature request related to a problem? Please describe.
A clear and concise description of what the problem is. Ex. I'm always frustrated when [...]

Describe the solution you'd like
A clear and concise description of what you want to happen.

Describe alternatives you've considered
A clear and concise description of any alternative solutions or features you've considered.

Additional context

Is your feature request related to a problem? Please describe.
A clear and concise description of what the problem is. Ex. I'm always frustrated when [...]

Describe the solution you'd like
A clear and concise description of what you want to happen.

Describe alternatives you've considered
A clear and concise description of any alternative solutions or features you've considered.

Additional context
Add any other context or screenshots about the feature request here.

Description

Currently, the configuration for handling threat exclusions in our package involves the use of Excludes option along with a slice of threat.Threat that should be excluded from the security checks. While this approach has served its purpose, we have identified some limitations and complexities associated with it. To improve the configuration's clarity, flexibility, and consistency, we propose deprecating the in favor of a new approach using Whitelists option.

Proposed Solution

Deprecating Excludes

In the current configuration, threat exclusions are defined using the Excludes field, as shown in the example below:

teler.Options{
	Excludes: []threat.Threat{
		threat.BadIPAddress,
		threat.BadCrawler,
	},
}

To replace the Excludes option, we propose using an option called Whitelists. The Whitelists field will allow users to define a list of items that should be included or allowed for security check processes by using DSL expression. This approach provides better clarity and makes it easier to manage the threat exclusions.

Advantages of Whitelists

1. Clarity: Since v1.0.0-alpha.1, the use of Whitelists explicitly states "[...] DSL expressions that match request elements that should be excluded from the security checks", improving the readability and understanding of the configuration.

2. Flexibility: With Whitelists, users can easily manage and customize the threat exclusions with DSL (Domain Specific Language) expressions, allowing for more fine-grained control over the allowed items.

3. Consistency: By standardizing the configuration approach, we can simplify the maintenance process and reduce user confusion.

Example Workaround

To aid users during the transition from Excludes to Whitelists, we can provide an example of how the new configuration would work. Given the original Excludes configuration:

teler.Options{
	Excludes: []threat.Threat{
		threat.BadIPAddress,
		threat.BadCrawler,
	},
}

The equivalent configuration using Whitelists would be:

teler.Options{
	Whitelists: []string{
		`threat in [BadCrawler, BadIPAddress]`, // or
		`threat == BadCrawler && threat == BadIPAddress`,
	},
}

Impact on Existing Implementations

To ensure a smooth transition for our users, we will provide clear documentation and guidelines on how to migrate from Excludes to Whitelists. Additionally, we can include documentation to assist users in updating their configurations.

Recommended Timeline

To give users sufficient time to adapt to the new configuration approach, we propose the following timeline:

1. Deprecation Announcement: We will announce the deprecation of Excludes and the introduction of Whitelists in the next minor release, v1.1.*.

2. Deprecation Warning: Starting from the subsequent minor release, we will provide deprecation warnings whenever the Excludes field is used, encouraging users to migrate to Whitelists.

3. End of Support: After version v2.*.* release, we will officially remove support for the Excludes field and provide support solely for Whitelists.

Conclusion

By deprecating the use of Excludes in favor of Whitelists, we can enhance the clarity, flexibility, and consistency of our package's configuration. This change will benefit both new and existing users, making it easier to manage and understand the threat exclusions.

Please feel free to share your thoughts and feedback on this proposal. We are open to discussing any concerns or suggestions regarding this configuration update.

Thank you for your attention.

Summary

The dsl package will be removed from the codebase and migrated into a new repository, https://github.com/teler-sh/dsl.

Motivation

The current codebase has become too complex, and maintaining the dsl package within it has become increasingly difficult. Migrating the dsl package into its own repository will help in better organization, management, and versioning of this specific functionality. It will also facilitate easier collaboration and contribution from external parties who may only be interested in the DSL aspect.

Design

The dsl package will be extracted from the existing codebase and placed into its own repository. This will involve creating a new repository dedicated to the dsl (done at https://github.com/teler-sh/dsl) package and transferring all relevant code, documentation, and tests into it. The package will then be published as a standalone module, allowing it to be independently versioned and distributed.

Drawbacks

• Increased complexity in managing multiple repositories.
• Potential fragmentation of documentation and contribution efforts.
• Additional overhead in maintaining separate versions for the dsl package.

Alternative Approaches

An alternative approach would be to refactor the existing codebase to simplify the dsl package within it. However, given the current complexity of the codebase, this may not be a feasible solution and could lead to further complications.

Unresolved Questions

What parts of the design are still undecided? Are there any outstanding questions or concerns that need to be addressed? For instance:

Is your feature request related to a problem? Please describe.
A clear and concise description of what the problem is. Ex. I'm always frustrated when [...]

Describe the solution you'd like
A clear and concise description of what you want to happen.

Describe alternatives you've considered
A clear and concise description of any alternative solutions or features you've considered.

Additional context
Add any other context or screenshots about the feature request here.

Is your feature request related to a problem? Please describe.
A clear and concise description of what the problem is. Ex. I'm always frustrated when [...]

Describe the solution you'd like
A clear and concise description of what you want to happen.

Describe alternatives you've considered
A clear and concise description of any alternative solutions or features you've considered.

Additional context
Add any other context or screenshots about the feature request here.

Is your feature request related to a problem? Please describe.
A clear and concise description of what the problem is. Ex. I'm always frustrated when [...]

Describe the solution you'd like
A clear and concise description of what you want to happen.

Describe alternatives you've considered
A clear and concise description of any alternative solutions or features you've considered.

Additional context
Add any other context or screenshots about the feature request here.

Is your feature request related to a problem? Please describe.
A clear and concise description of what the problem is. Ex. I'm always frustrated when [...]

Describe the solution you'd like
A clear and concise description of what you want to happen.

Describe alternatives you've considered
A clear and concise description of any alternative solutions or features you've considered.

Additional context
Add any other context or screenshots about the feature request here.

Is your feature request related to a problem? Please describe.
I want to view the logs in the browser, so I need to write the logs to the mysql database, but the logs in teler-waf can only be output to files. Can you provide more output methods ?

Describe the solution you'd like
provide more output methods

Describe alternatives you've considered
teler.Options Provider custom log output field, like LogOutput, It needs to implement the io.Writer interface

Additional context
no

Is your feature request related to a problem? Please describe.
A clear and concise description of what the problem is. Ex. I'm always frustrated when [...]

Describe the solution you'd like
A clear and concise description of what you want to happen.

Describe alternatives you've considered
A clear and concise description of any alternative solutions or features you've considered.

Additional context
Add any other context or screenshots about the feature request here.

Describe the bug

A clear and concise description of what the bug is.

To Reproduce

Steps to reproduce the behavior:

Your teler usage & options...

Expected behavior

A clear and concise description of what you expected to happen.

Screenshots

If applicable, add screenshots to help explain your problem.

Environment (please complete the following information):

• OS: [e.g. mac, linux]
• OS version: [uname -a]
• teler Version [see go.mod]

Additional context

Add any other context about the problem here. Full output log is probably a helpful thing to add here.

Is your feature request related to a problem? Please describe.

The problem is that when using a whitelist, any request that matches it will be returned early, regardless of the type of threat it may contain. This means that some requests with payloads that could potentially be harmful may not be thoroughly analyzed for common web attack threats.

Describe the solution you'd like

One solution could be to implement the whitelist in each function of the respective threat type. This would allow for more targeted whitelisting and ensure that requests with payloads are thoroughly analyzed for common web attack threats. For example, the proposed solution could involve modifying the whitelist to include a threat type associated with each whitelist entry, as shown in the following code snippet:

		Whitelists: []teler.Whitelist{
			{`(curl|Go-http-client|okhttp)/*`, threat.BadCrawler},
			{`^/wp-login\.php`, threat.DirectoryBruteforce},
			{`(?i)Referer: https?:\/\/www\.facebook\.com`, threat.BadReferrer},
			{`192\.168\.0\.1`, threat.BadIPAddress},
		},

Describe alternatives you've considered

An alternative solution could be to implement the whitelist like a custom rules format. This would allow for more granular control over which requests are allowed through the teler-waf, and would enable the specification of complex rules based on various request elements (e.g. URI, headers, body). The proposed implementation includes a Customs field that would contain an array of custom rules that the teler-waf would follow.

Additional context

Warning: Implementing this solution would require changes to existing code and may potentially break existing functionality.

It is essential to balance the need for security with the need for efficient processing of requests. Adding too many checks can slow down the analysis process, while insufficient checks can increase the risk of security breaches. Therefore, any proposed solution should aim to strike a balance between these two competing needs.

Is your feature request related to a problem? Please describe.

caching requests before further analysis

Describe the solution you'd like

Added a Cache field that has a value of time.Duration, and a Development mode that has a bool value to the Options.

Describe alternatives you've considered
A clear and concise description of any alternative solutions or features you've considered.

Additional context
Add any other context or screenshots about the feature request here.

Background

Currently, teler-waf utilizes two different regexp engines for pattern matching: one from the built-in regexp and another from go-pcre. However, to enhance maintainability and performance, we're considering the transition to a single regexp engine. This decision is driven by the need to streamline our codebase and ensure consistent behavior across our library.

Objective

The primary objective of this proposal is to select a single regexp engine that best aligns with our requirements. It's crucial that the chosen engine supports PCRE patterns, as these patterns are integral to our use cases, specifically to check the CommonWebAttack threat.

Options

We have evaluated several alternative regexp engines that are commonly used:

• go-pcre (by @\scorpionknifes)
• go-pcre (by @\GRbit)
• go-re2
• gohs (Chimera)
• rure-go
• go-regex

Criteria

To make an informed decision, we should consider the following criteria:

1. PCRE Pattern Support: The selected engine must fully support PCRE patterns, as they are a fundamental part of our library's functionality.
2. Performance: Evaluate the performance of each engine, particularly in scenarios where our library is used intensively.
3. Community and Maintenance: Consider the activity and responsiveness of the engine's maintainers and community. A vibrant community often leads to quicker issue resolution and ongoing improvements.
4. Documentation: Well-documented engines simplify integration, troubleshooting, and future maintenance.
5. Compatibility: Ensure that the chosen engine aligns with our library's other dependencies and doesn't introduce conflicts.

Proposed Steps

1. Evaluate Engines: Assess the proposed engines based on the criteria outlined above. This evaluation should include hands-on testing and performance benchmarking.
2. Engine Selection: Based on the comparison and community judgment, decide on the most suitable regexp engine for our library's needs.
3. Implementation Plan: Once an engine is chosen, outline a clear plan for migrating our existing codebase to the selected engine. This should include steps for modifying and testing the code, as well as addressing any compatibility issues that may arise.
4. Testing and Validation: Rigorously test the migration to ensure that the chosen engine behaves as expected and doesn't introduce regressions or new issues.

Conclusion

By transitioning to a single regexp engine that supports PCRE patterns, we can simplify our codebase, improve maintainability, and ensure consistent behavior. This proposal outlines the steps to evaluate and select the most appropriate engine for our library's needs. Let's work collaboratively to make this transition successful and beneficial for our users and the longevity of our project.

Note
This issue proposal is meant to serve as a starting point for discussion. Feel free to contribute by suggesting modifications or adjustments as required. Your input is highly appreciated.

Is your feature request related to a problem? Please describe.
A clear and concise description of what the problem is. Ex. I'm always frustrated when [...]

Describe the solution you'd like
A clear and concise description of what you want to happen.

Describe alternatives you've considered
A clear and concise description of any alternative solutions or features you've considered.

Additional context
Add any other context or screenshots about the feature request here.

How do I configure it so that Teler can work with fail2ban?
because I am doing this configuration for a case study in my thesis
I have tried to configure according to https://dwisiswant0.medium.com/empowering-teler-http-intrusion-detection-as-waf-with-fail2ban-35c40618890 but when looking at fail2ban-client the status does not change to teler

Is your feature request related to a problem? Please describe.
A clear and concise description of what the problem is. Ex. I'm always frustrated when [...]

Describe the solution you'd like
A clear and concise description of what you want to happen.

Describe alternatives you've considered
A clear and concise description of any alternative solutions or features you've considered.

Additional context
Add any other context or screenshots about the feature request here.

Summary

The current issue pertains to the process of benchmarking and initializing the *Teler instance within the codebase. The proposed solution suggests that benchmarking should be conducted by directly invoking the corresponding threat check functions (e.g., checkCommonWebAttack, checkCVE, checkDirectoryBruteforce, etc.), instead of employing the http.Client{}.Do method approach, which incorporates the use of httptest.NewServer function.

Motivation

Documenting this change in the benchmarking process is essential to clarify how benchmarking should be performed and to ensure that the process is consistent and well understood-by all contributors. This documentation will benefit both existing and future developers who work on the codebase. It will provide clear instructions on how to conduct benchmarking, leading to better code quality and more streamlined development processes.

Summary

This proposal outlines the design changes for configuration related to custom response handling. The primary modifications involve introducing a new structure for custom response headers and replacing the html and html_file fields with content and content_file, and expression support for dynamic content generation. Additionally, it suggests the inclusion of placeholders for dynamic content generation in the response.

Motivation

The motivation behind this proposal is to enhance the flexibility and functionality of custom response configuration for rejected requests. Users can set custom headers as needed by introducing response headers as a map. The shift from html to content and content_file allows for arbitrary content types by enabling users to specify the Content-Type header. Introducing placeholders in the response content empowers users to create dynamic responses tailored to specific conditions, improving the versatility of teler-waf.

Design

The proposed design changes are as follows:

1. Custom Response Headers

Introduce a new field in the configuration called headers, which is of type map[string]string. Users can define custom response headers using this map. This change allows for greater control over the HTTP response.

2. Content Handling

Substitute the existing html and html_file fields with content and content_file. The content field is designed to accommodate response content as a string, while content_file provides the flexibility for users to specify a file from which the response content can be sourced. These updates enhance the configuration's ability to effectively manage a wide range of content types. Furthermore, these changes introduce support for expressions, enabling the creation of dynamic response content that can be tailored to specific conditions.

Consequently, the use of the DefaultHTMLResponse will be deprecated.

3. New Placeholders

To support dynamic content generation, introduce placeholders within the response content. Placeholders like {{request.Method}}, {{request.Path}}, {{request.URI}}, {{request.Headers}}, and {{request.IP}} can be used to inject request-related information into the response. This enhances the ability to tailor responses based on specific conditions.

Example

Marshalled in YAML.

# ...
response:
    status: 403
    headers:
        X-Custom-Header: foo
        X-New-Header: bar
        Content-Type: text/html
    content: |
        {{ if request.Path == "/login" && request.Method == "POST" }}
            Your request has been denied for security reasons. Ref ID: {{ID}}.
        {{ else }}
            You have been blocked from accessing our website. Contact support to unblock. (IP: {{request.IP}})
        {{ end }}
    content_file: ""
# ...

Drawbacks

The primary drawback is that these changes may require existing users to update their configurations to align with the new structure. This may temporarily cause compatibility issues for those upgrading from older versions.

Alternative Approaches

An alternative approach would be to keep the existing configuration structure as it is. However, this would limit the flexibility and customization options available to users. The proposed changes aim to provide a more versatile.

Unresolved Questions

TBD

Describe the bug

A clear and concise description of what the bug is.

To Reproduce

Steps to reproduce the behavior:

Your teler usage & options...

Expected behavior

A clear and concise description of what you expected to happen.

Screenshots

If applicable, add screenshots to help explain your problem.

Environment (please complete the following information):

• OS: [e.g. mac, linux]
• OS version: [uname -a]
• teler Version [see go.mod]

Additional context

Add any other context about the problem here. Full output log is probably a helpful thing to add here.

Describe the bug

I can't running code because i got some error, it likes screenshoot

To Reproduce

Steps to reproduce the behavior:

• first i install the library
• second i install the echo framework
• third i copy the code it likes code in folder example/integration/echo
• fourth if i running the code i got the error it likes screenshoot

go run main.go

Expected behavior

A clear and concise description of what you expected to happen.

Screenshots

If applicable, add screenshots to help explain your problem.

Environment (please complete the following information):

• OS: [windows]
• OS version: [11]
• teler Version [v0.5.0]

Additional context

Add any other context about the problem here. Full output log is probably a helpful thing to add here.

Description

Currently, the configuration for handling threat exclusions in our package involves the use of Excludes option along with a slice of threat.Threat that should be excluded from the security checks. While this approach has served its purpose, we have identified some limitations and complexities associated with it. To improve the configuration's clarity, flexibility, and consistency, we propose deprecating the in favor of a new approach using Whitelists option.

Proposed Solution

Deprecating Excludes

In the current configuration, threat exclusions are defined using the Excludes field, as shown in the example below:

teler.Options{
	Excludes: []threat.Threat{
		threat.BadIPAddress,
		threat.BadCrawler,
	},
}

To replace the Excludes option, we propose using an option called Whitelists. The Whitelists field will allow users to define a list of items that should be included or allowed for security check processes by using DSL expression. This approach provides better clarity and makes it easier to manage the threat exclusions.

Advantages of Whitelists

1. Clarity: Since v1.0.0-alpha.1, the use of Whitelists explicitly states "[...] DSL expressions that match request elements that should be excluded from the security checks", improving the readability and understanding of the configuration.

2. Flexibility: With Whitelists, users can easily manage and customize the threat exclusions with DSL (Domain Specific Language) expressions, allowing for more fine-grained control over the allowed items.

3. Consistency: By standardizing the configuration approach, we can simplify the maintenance process and reduce user confusion.

Example Workaround

To aid users during the transition from Excludes to Whitelists, we can provide an example of how the new configuration would work. Given the original Excludes configuration:

teler.Options{
	Excludes: []threat.Threat{
		threat.BadIPAddress,
		threat.BadCrawler,
	},
}

The equivalent configuration using Whitelists would be:

teler.Options{
	Whitelists: []string{
		`threat in [BadCrawler, BadIPAddress]`, // or
		`threat == BadCrawler || threat == BadIPAddress`,
	},
}

Impact on Existing Implementations

To ensure a smooth transition for our users, we will provide clear documentation and guidelines on how to migrate from Excludes to Whitelists. Additionally, we can include documentation to assist users in updating their configurations.

Recommended Timeline

To give users sufficient time to adapt to the new configuration approach, we propose the following timeline:

1. Deprecation Announcement: We will announce the deprecation of Excludes and the introduction of Whitelists in the next minor release, v1.1.*.

2. Deprecation Warning: Starting from the subsequent minor release, we will provide deprecation warnings whenever the Excludes field is used, encouraging users to migrate to Whitelists.

3. End of Support: After version v2.*.* release, we will officially remove support for the Excludes field and provide support solely for Whitelists.

Conclusion

By deprecating the use of Excludes in favor of Whitelists, we can enhance the clarity, flexibility, and consistency of our package's configuration. This change will benefit both new and existing users, making it easier to manage and understand the threat exclusions.

Please feel free to share your thoughts and feedback on this proposal. We are open to discussing any concerns or suggestions regarding this configuration update.

Thank you for your attention.