[proposal] deprecating `Excludes` with `Whitelists`

[Dwi Siswanto]

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.