### Problem to solve GitLab provides WAF with OWASP default rules. This provides a powerful set of out-of-the-box controls. However, some users will need to tune the configuration to fit the specific needs of their application's security requirements in order to tune the rules for false positives (blocking legitimate requests), false negatives (missed attacks), and performance impact (as WAF rules can introduce latency even if they don't detect an issue - [example](https://blog.cloudflare.com/cloudflare-outage/)). This is especially relevant for those users who will be using the blocking mode of the WAF as false positives can break normal functionality of the application. Additionally, the WAF rules may need to be tuned over time as the applications protected by the WAF change. ### Intended users <!-- Who will use this feature? If known, include any of the following: types of users (e.g. Developer), personas, or specific company roles (e.g. Release Manager). It's okay to write "Unknown" and fill this field in later. Personas can be found at https://about.gitlab.com/handbook/marketing/product-marketing/roles-personas/ --> * [Sam (Security Analyst)](https://about.gitlab.com/handbook/marketing/product-marketing/roles-personas/#sam-security-analyst) ### Further details <!-- Include use cases, benefits, and/or goals (contributes to our vision?) --> This is our users first opportunity to provide custom rules. This will be done in parallel with additional ~UX work to uncover & validate the long-term experience we want to provide around WAF rules. As such, we should focus on the minimal way to provide custom WAF rules in case we decide to go a different direction after discovery completes. In context of this issue, custom rules means the [SecRule](https://github.com/SpiderLabs/ModSecurity/wiki/Reference-Manual-%28v2.x%29#SecRule) objects that `ModSecurity` is parsing. ### Proposal Provide a way for users to specify a set of custom rules that `ModSecurity` should use for their project specifically. 1. Allow users to specify a list of custom `ModSecurity` rules for apps deployed via AutoDevops pipeline 1. ~~Usage ping & GitLab.com reporting~~ * ~~Report when a custom rule has been provided.~~ * Usage reporting is not supported yet for CI-based installation/management of apps. see ~"devops::configure" https://gitlab.com/gitlab-org/gitlab/issues/195428 1. A ~"GitLab Ultimate" license is required to use this functionality 1. A "wizard"-like experience to define WAF custom rules ### Permissions and Security <!-- What permissions are required to perform the described actions? Are they consistent with the existing permissions as documented for users, groups, and projects as appropriate? Is the proposed behavior consistent between the UI, API, and other access methods (e.g. email replies)? --> ### What does success look like, and how can we measure that? <!-- Define both the success metrics and acceptance criteria. Note that success metrics indicate the desired business outcomes, while acceptance criteria indicate when the solution is working correctly. If there is no way to measure success, link to an issue that will implement a way to measure this. --> 1. At least 20% of WAF installations using customized rules, beyond the default Core Rule Set. 1. This will measure if the capability is being adopted or not. 1. First customized rule introduced within 30 days (median time) of enabling the WAF. 1. This will measure if the problem custom rules solves is urgent enough to immediately adopt it and that customers are able to do so successfully. ### Documentation <!-- See the Feature Change Documentation Workflow https://docs.gitlab.com/ee/development/documentation/feature-change-workflow.html Add all known Documentation Requirements here, per https://docs.gitlab.com/ee/development/documentation/feature-change-workflow.html#documentation-requirements --> Documentation should cover: 1. A description of what a WAF rule is 1. A description of why a user would want to provide a custom WAF rule 1. A description of the different things that can be part of a custom WAF rule 1. An example of adding a custom rule 1. Describe how to configure custom WAF rules for multiple projects in the same cluster. 1. Describe how to configure custom WAF rules for multiple environments in the same project. * Some possibly helpful discussion is [here](https://gitlab.com/gitlab-org/gitlab/issues/8557#note_243617342) ### Testing <!-- What risks does this change pose? How might it affect the quality of the product? What additional test coverage or changes to tests will be needed? Will it require cross-browser testing? See the test engineering process for further guidelines: https://about.gitlab.com/handbook/engineering/quality/guidelines/test-engineering/ --> Testing should cover: * (If per-project rules are possible) Multiple applications hosted in the same Kubernetes cluster, each with a different set of rules ### What is the type of buyer? <!-- Which leads to: in which enterprise tier should this feature go? See https://about.gitlab.com/handbook/product/pricing/#four-tiers --> Custom rules require a ~"GitLab Ultimate" license. ### Links / references /label ~feature * `nginx.ingress.kubernetes.io/modsecurity-snippet` documentation for specifying WAF rules (https://kubernetes.github.io/ingress-nginx/user-guide/nginx-configuration/annotations/#modsecurity) ### Technical discovery Custom [SecRule](https://github.com/SpiderLabs/ModSecurity/wiki/Reference-Manual-%28v2.x%29#SecRule) definitions are already supported by the nginx ingress via [nginx.ingress.kubernetes.io/modsecurity-snippet](https://kubernetes.github.io/ingress-nginx/user-guide/nginx-configuration/annotations/#modsecurity) annotation on the ingress object. We already utilize this annotation in the [auto-deploy](https://gitlab.com/gitlab-org/charts/auto-deploy-app/blob/master/templates/ingress.yaml#L15-19) helm charts. We can extend auto-deploy helm chart to allow installation of custom `SecRule` definitions via AutoDevops pipelines. AutoDevops installation script supports custom helm value injection from the [.gitlab/auto-deploy-values.yaml](https://gitlab.com/gitlab-org/cluster-integration/auto-deploy-image/blob/master/src/bin/auto-deploy#L153). We can use this file as a source for custom `SecRule` definitions, these values will be available to the auto-deploy helm chart.