<!-- The first section "Release notes" is required if you want to have your release post blog MR auto generated. Currently in BETA, details on the **release post item generator** can be found in the handbook: https://about.gitlab.com/handbook/marketing/blog/release-posts/#release-post-item-generator and this video: https://www.youtube.com/watch?v=rfn9ebgTwKg. The next four sections: "Problem to solve", "Intended users", "User experience goal", and "Proposal", are strongly recommended in your first draft, while the rest of the sections can be filled out during the problem validation or breakdown phase. However, keep in mind that providing complete and relevant information early helps our product team validate the problem and start working on a solution. --> ### Release notes GitLab provides a comprehensive set of [security scanning tools](https://docs.gitlab.com/ee/user/application_security/#security-scanning-tools) that can identify all manner of security issues. Scanner findings are presented in merge requests, pipelines, and in a dedicated Vulnerability Report. When available, a recommended solution is given. However, this is not possible for all findings. Presenting security findings without guidance on how to fix identified problems or explaining the problem’s potential impact can be challenging for anyone not familiar with the specific security issue identified. This increases the time and friction involved in assessing and ultimately fixing security issues—especially in developer workflows. We’re pleased to announce the launch of our new integrated security training functionality. Two new partners are providing the training content. GitLab is already where many developers are working so we designed a solution to provide context-aware security training options from inside the GitLab experience. Simply enable security training for your projects and select your preferred content sources. Then, look at the results from a security scan. When you open a vulnerability finding, you will see a direct link to training from the selected vendor. We pull a training that most closely matches the particular security issue and the specific language or framework in which it was detected. Now developers can spend a few quick minutes getting targeted, context-relevant training to address security issues as part of their normal development workflow. ### Problem to solve Our Secure scanners provide visibility and early detection of potential vulnerabilities during the development cycle. This enables developers to find and fix security issues before they make it into the final software. The scanner results give information on what a particular security issue is. This often includes links to source material about a particular CVE or CWE. However, not all developers are security experts. These resources don't necessarily provide background context and are geared more toward security professionals. A developer may not be familiar enough with the security issue presented to understand the implications or how to best fix it from the provided resources alone. This can make it more challenging to resolve security issues quickly—or even worse, cause them to be ignored. Internal security teams can help provide guidance but this isn't always a scalable model as many security teams already have more work than they can easily manage. To truly help organizations unlock the potential of a shift-left security approach, we need to help support elevating overall security knowledge in the development organization. One way we can fill this gap between reporting security findings and developer understanding is to surface highly relevant, self-serve security training as part of the developer's normal workflow. ### User experience goal We will provide a simple, unobtrusive way to access highly-relevant training materials from our partners. Users will see these options in the proper context: when they are reviewing security findings in MRs, in Pipelines, or on a Vulnerability Report. Because we want to have multiple training partner options, the experience should be consistent no matter who is providing content. And because the content lives with a 3rd party, our UI experience will be limited to pointing at the right training; users will be taken to the partner's site to view the actual training. ### Proposal There will be four main interaction points that need design: 1. Configuration area for enabling training integration/picking which integrated vendor to use 1. Links to available training in the findings details modals (MR and Pipeline security tab) 1. Links to available training in the vulnerability details pages 1. A new feature notification telling users about the new capability #### Designs - :crayon: [**UX**](https://www.figma.com/file/ndBDbrHCLSD61qPG3kt4H2/Security-Configuration-Settings?node-id=908%3A1) - :video_camera: [**Walkthrough**](https://www.loom.com/share/2b05d387bcc34d2bb44fc28f864e6a9c?sharedAppSource=team_library) ##### Configuration GitLab will develop and control the training integration and experience so that it is consistent for our users, regardless of which training platform they chose to use. There is a good chance we will add additional partners in the future so we need to consider how to easily switch between options. Training suggestions will be OFF by default. This is because we are introducing zero-configuration integrations that take GitLab users to an external provider. There is a high probability we will launch with more than one provider, so the user must chose which one(s) to enable. Also, historically, many self-managed Ultimate customers are sensitive to any external network connections we make that are not to a GitLab-controlled domain. To not lose visibility of this new feature, we will use the notification detailed below. Training configuration makes sense at both the Group and Project level. It would be much more convenient to enable it at the Group level where users can then disable for any specific child Project it is not wanted. It can also be left off for a Group but selectively enabled on individual Projects. Each partner will have different coverage in terms of which security topics (CWEs) are covered for which languages and frameworks. With more than one potential partner, we should explore different options for leveraging their training beyond simply selecting one or the other. For instance, we might let a user select a Primary training source with the other(s) as fallback options should the Primary vendor not have any available content. This would maximize the chance of having relevant training. On the other hand, a customer may already have an existing relationship with one of our partners and so may want to exclusively use their training, disabling all other options. The two configuration scenarios aren't mutually exclusive; we should consider allowing configuration for either case. ##### Training from MR and Pipeline This is perhaps the most important aspect of the UX experience for this new functionality. Providing relevant training information to developers as they are looking at security findings is at the core of the originally identified research insight. We need to provide a consistent, easily visible yet non-intrusive way to call attention to available training materials that fits with existing developer workflows. To this end, findings detail modals in the MR security widget and on the Pipeline security tab will be where this is presented. Considerations: * Not all security findings will have an available training (language/framework + identifier doesn't match) * Do we attempt to find a training for the same identifier (CWE) in other languages? If so (and if vendors can support this), how does an alternate get chosen? * If there is more than 1 training vendor enabled and the Primary does not have a match (see above section) but a secondary does, do we need to distinguish for the user that the result is from one of these other vendors? * If no match is possible, do we simply not display the training call to action or provide a different "no match" visualization? * If we allow using multiple vendors at once and more than one matches the training need, do we show both? Do we let the user chose? Or do we only show Primary (if available)? * What do we do if a finding has multiple identifiers that could match available trainings? * What if the finding's primary identifier isn't a CWE but one its others is? We don't want to miss showing a training because the primary identifier is something we can't send to the vendor, such as the proprietary Gemnasium ID. ##### Vulnerability Details Page The needs here are essentially the same as for the MR and Pipeline modals. The main difference is we will need to show the same information and a similar experience on the standalone vulnerability pages which have a different layout. ##### New Feature Notification Because this feature will be off by default/need a user to enable, we need to call attention to it. We should leverage existing in-product new feature notification capabilities, where possible. The notification should briefly explain the new functionality and the benefit. It should also either link to the appropriate documentation or take the user directly to the new configuration page (which itself should have a link somewhere to the documentation). We do not want users to get alert fatigue. Showing this for every Group and Project will quickly get annoying so once a user dismissed the notification with the `X` in the upper-right, they should not see this notification again, anywhere. ### Further details It is possible that this feature will launch with only a single vendor partner providing training. However, the ask is to create this with multiple potential providers as the ultimate goal. Not only is this in line with GitLab's "we play nice with anyone" approach, it avoids us getting locked into a single vendor. Down the line, we may even extend this feature to let organizations create their own training resources that could tie into this functionality. ### How can we measure success? There are a few key pieces of information we need to track to help gauge the success of this feature rollout. And unlike many of our features, since the content is provided by partners, it is very important to capture usage metrics so we can keep them informed of the uptake. Metrics to capture: * Enabling training content and the provider(s) enabled (and which project) * Disabling training content and the provider(s) disabled (and which project) * Which provider is marked as Primary, per project * Details about all training links clicked: * The URL of the training link * The GitLab page/context from which it was clicked (e.g. MR, pipeline, vulnerability details page) * **Not required but very nice to have**: identifier(s) of the finding/vulnerability * Any finding modal or vulnerability details page load where a training link is generated (this will be used to determine engagement percentage when comparing to training links clicked) * Clicks on the `Enable training` call to action including which page/context it was clicked from ### Permissions and Security There are no security or permissions requirements. Any Ultimate user with access to vulnerability findings, vulnerability details pages, and the Security & Compliance → Configuration page can access all of this functionality. ### Documentation <!-- See the Feature Change Documentation Workflow https://docs.gitlab.com/ee/development/documentation/workflow.html#for-a-product-change This is all net-new functionality. We should also update the following pages with appropriate screenshots and callouts of the new capability: * https://docs.gitlab.com/ee/user/application_security/vulnerabilities/ ### Availability & Testing <!-- This section needs to be retained and filled in during the workflow planning breakdown phase of this feature proposal, if not earlier. What risks does this change pose to our availability? 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? Please list the test areas (unit, integration and end-to-end) that needs to be added or updated to ensure that this feature will work as intended. Please use the list below as guidance. * Unit test changes * Integration test changes * End-to-end test change See the test engineering planning process and reach out to your counterpart Software Engineer in Test for assistance: https://about.gitlab.com/handbook/engineering/quality/test-engineering/#test-planning --> ## Implementation Plan Expected to ship in |Issue| Description| Type |---|---|---|---| %14.6 | gitlab-org/gitlab#346069 | Security training API Spike| ~frontend %14.6 | gitlab-org/gitlab#346074 | Create secure_vulnerability_training FF| ~frontend %14.6 | gitlab-org/gitlab#346057 | Create configuration security training| ~frontend %14.6 | gitlab-org/gitlab#346593| Create loading state for security training configuration | ~frontend %14.7 |gitlab-org/gitlab#348839 | Spike: Check how to use telemetry | ~frontend %14.7 | gitlab-org/gitlab#346480 | GraphQL query for security training vendors| ~backend %14.7 | gitlab-org/gitlab#348711| Error handling for configuration security training mutation | ~frontend %14.7 | gitlab-org/gitlab#347414| Connect mutation for security training configuration | ~frontend %14.7 | gitlab-org/gitlab#346488 | Create security training description| ~frontend %14.7 | gitlab-org/gitlab#346067 | Create training in vulnerability modal| ~frontend %14.7 | gitlab-org/gitlab#346596 | Use sync tabs for security configuration tabs | ~frontend %14.7 | gitlab-org/gitlab#349670 | Add training loading status to vulnerability details page | ~frontend %14.7 | gitlab-org/gitlab#349669 | Make API call to fetch training from vendor in details page | ~frontend %14.7 | gitlab-org/gitlab#349608 | Hide training section based on config in details page | ~frontend %14.8 | gitlab-org/gitlab#346479| GraphQL mutation for security training configuration| ~"backend" %14.8 | gitlab-org/gitlab#346066 | Create training in vulnerability details page (UI)| ~frontend %14.8 | gitlab-org/gitlab#346063 | Create promo callout on security dashboard| ~frontend %14.8 | gitlab-org/gitlab#346071 | Create security training documentation| ~frontend %14.8 | gitlab-org/gitlab#349916 | Add backend interface to call (redacted) API| ~backend %14.8 | gitlab-org/gitlab#349910 | Add dynamic CSP for using the (redacted) API| ~backend %14.8 | gitlab-org/gitlab#350563 | Update to use real GraphQL mutation: Security Config| ~frontend %14.8 | gitlab-org/gitlab#350562 | Update to use real date from GraphQL query: Vulnerability details page| ~frontend %14.8 | gitlab-org/gitlab#350561 | Update to use real date from GraphQL query: Security Config| ~frontend %14.8 | gitlab-org/gitlab#350731 | Fill database with real provider data| ~"backend" %14.9 | gitlab-org/gitlab#352198 | Implement frontend UI to use Vendor K API| ~"frontend" %14.9 | gitlab-org/gitlab#352681 | Update frontend to use Vendor S API| ~"frontend" %14.9 | gitlab-org/gitlab#346059 | Create configuration security training: add primary training support| ~frontend %14.9 | gitlab-org/gitlab#348835| Integrate primary training with status of provider selection | ~frontend %14.9 | gitlab-org/gitlab#348836| Connect mutation for security primary training support | ~frontend %14.9 | gitlab-org/gitlab#346060 | Create configuration security training: add info popover| ~frontend %14.9 | gitlab-org/gitlab#346896 | Create security training provider logo | ~frontend ## Metrics Issues Expected to ship in |Issue| Description| Type |---|---|---|---| %14.7 | gitlab-org/gitlab#348839 | Spike: Check how to use telemetry (metrics) | ~frontend %14.8 | gitlab-org/gitlab#348587 | Create Metrics for training and provider enable/disable | ~frontend %14.8 | gitlab-org/gitlab#348589 | Create metrics for training links clicked: details page | ~frontend %14.8 | gitlab-org/gitlab#352678 | Create metrics for training links clicked: security config | ~frontend %14.8 | gitlab-org/gitlab#348593 | Create metrics for page load: details page | ~frontend %14.8 | gitlab-org/gitlab#348592 | Create metrics for "Enable Training" CTA | ~frontend %14.9 | gitlab-org/gitlab#352679 | Create metrics for training links clicked: modal | ~frontend %14.9 | gitlab-org/gitlab#352680 | Create metrics for page load: modal | ~frontend %14.9 | gitlab-org/gitlab#348588 | Create metrics for primary provider selection | ~frontend ## Next Iteration Expected to ship in |Issue| Description| Type |---|---|---|---| backlog | gitlab-org/gitlab#346899 | GraphQL query for security training provider logo| ~"backend" backlog | gitlab-org/gitlab#354779| Add provider logo to svg library | ~"UX Product Design" backlog | gitlab-org/gitlab#354781 | Update vulnerability details and modal to use logo from GraphQL query | ~frontend backlog | gitlab-org/gitlab#354780 | Update security config to use logo from GraphQL logo | ~frontend backlog | gitlab-org/gitlab#349035 | Create docs link in security training config | ~frontend backlog|gitlab-org/gitlab#356129|Update learn more links | ~backend backlog | gitlab-org/gitlab#356284 | Update learn more links to use GraphQL query | ~frontend backlog | gitlab-org/gitlab#356279 | Pass doc link as data instead of hardcoding it | ~frontend backlog | gitlab-org/gitlab#353322 | Metric of identifier of clicked training link: vulnerability details page | ~frontend backlog | gitlab-org/gitlab#353323 | Metric of identifier of clicked training link: vulnerability modal| ~frontend backlog | gitlab-org/gitlab#349606 | Support other mapping key | ~backend backlog | gitlab-org/gitlab#356287 | Support other mapping key | ~frontend backlog | gitlab-org/gitlab#346455 | Provide vulnerability file language type| ~backend backlog | gitlab-org/gitlab#356285 | Update training urls to use file type | ~frontend backlog | gitlab-org/gitlab#346064 | Create security training promo to MR widget| ~frontend backlog|gitlab-org/gitlab#355940|Support individual loading of security training urls|~frontend