## Customer needs When designing their security programs or evaluating security tools, users need to know what their tools will cover. When existing customers update their version of GLAS, there are times when they run into issues (such as performance degradations) and want to investigate what GLAS rules have changed in the version they upgraded to as part of their troubleshooting process. We should be able to answer these questions effectively without requiring users to contact GitLab for help. ## Scope of coverage For now, we will focus on publishing Advanced SAST rules only. ## What content to publish As an initial solution to this problem, we should add new documentation content that enumerates the available rules. Similar docs exist today for Secret Detection and Dynamic Analysis, though each of these existing solutions has some differences from how SAST works. We can start by focusing on surfacing the following information about Advanced SAST rules: * Rule ID = the identifier we have assigned to the rule * Rule Description = the attack type covered by the rule * CWE = the primary CWE associated with the rule * The CWEs should link to their associated MITRE page * OWASP Category = which of the OWASP 10 categories the rule is associated with, if any * Status = for the given version of the SAST engine, which rules have been updated/removed/added * If a rule hasn't been changed in a given version, we could consider just leaving the status blank Example: | Rule ID | Rule Description | CWE | OWASP Top 10 | Status | |---------|------------------|-----|--------------|--------| | javascript-playwright-ssrf-taint | Server-Side Request Forgery (SSRF) | [CWE-918](https://cwe.mitre.org/data/definitions/918.html) | A03:2021-Injection (2021) | Updated | Our rules are associated with languages and we currently have about 556 rules in total. We may want to consider having sub-pages for each language, but i'm open to your suggestions on presentation @rdickenson. ## Automation Feedback from @dabeles on automating rule changes in our documentation: On every rules release, we also add a database with all the rule metadata. An example of that database can be viewed by navigating to https://sast-rules-dashboard-0098aa.gitlab.io/rules.db. Any consumer can take that and use it, it could be a job on the docs page that scrapes it and updates the docs accordingly. ## Alternatives considered 1. In-product visibility would be convenient, but is problematic because we don't have a way of tying analyzers' rules to the platform release. That is, we can have cases like: - Old self-managed releases with new analyzer versions. - Old (pinned) analyzer versions used in a newer self-managed release, or on GitLab.com. 2. Publishing rules outside of docs could avoid some of the logistical challenges of deploying in the docs site. However: - This would require establishing and hosting a separate site, similar to how we maintain https://advisories.gitlab.com or how Sonar maintains https://rules.sonarsource.com/. - Content from the docs site is automatically packaged up and included in the self-managed release. This makes it possible for offline customers to have the same content. - The [SAST rules overview](https://docs.gitlab.com/ee/user/application_security/sast/rules.html) is in docs already. - Having the rules in our docs site would be consistent with other AppSec vendors, like Black Duck and Snyk