Restructure documentation to consolidate Vulnerability Management features
Problem to solve
The various features that comprise Vulnerability Management were developed by different teams over a number of months. As the feature set has grown, the definition of what comprises the Vulnerability Management category has also evolved. This has led to the features being documented over several different sections of docs.gitlab.com, making it unclear to a user what features belong to Vulnerability Management and how they are interrelated.
Documentation in scope for this issue
Source: https://docs.gitlab.com/ee/user/application_security/
- Interacting with the vulnerabilities
- View details of a DAST vulnerability
- Hide sensitive information in headers
- View details of a DAST vulnerability
- View details of an API Fuzzing vulnerability
- Dismissing a vulnerability
- Adding a dismissal reason
- Dismissing multiple vulnerabilities
- Creating an issue for a vulnerability
- Automatic remediation for vulnerabilities
- Manually applying the suggested patch
- Creating a merge request from a vulnerability
- Managing related issues for a vulnerability
- Adding a related issue
- Removing a related issue
Source: https://docs.gitlab.com/ee/user/application_security/vulnerability_report/index.html
- Project Vulnerability Report
- Export vulnerabilities
Source: https://docs.gitlab.com/ee/user/application_security/vulnerabilities/
Standalone Vulnerability Pages
- Changing vulnerability status
- Creating an issue for a vulnerability
- Link issues to the vulnerability
- Automatic remediation for vulnerabilities
Source: https://docs.gitlab.com/ee/user/application_security/security_dashboard/
Security Dashboard
- This page includes the pipeline security report/tab but really this should be treated separately as it's not really the same as the other 3 dashboards.
Source: https://docs.gitlab.com/ee/user/application_security/#security-approvals-in-merge-requests
Security approvals in MRs
Source: https://docs.gitlab.com/ee/user/application_security/configuration/
Security Configuration
- The top-level page will be VM's to own but any individual scanner config pages will be owned by the respective scanner team.
Duplicate documentation:
- Vulnerability severity
Proposal
I believe we need to do the following to improve the user's experience:
- Co-locate this documentation into a single section.
- Ensure docs are cross-linked as appropriate.
- Ensure the flow of content is optimised. That is, ensure introductory topics flow into more detailed topics.
- Ideally... restructure content into concept, task, reference, and troubleshooting.
I believe the flow of tactical vulnerability management is as follows:
- Configure GitLab's Secure features to detect vulnerabilities.
- GitLab detects and reports on vulnerabilities.
- User views a vulnerability's details and acts on the information provided.
In parallel with this workflow, the following are strategic vulnerability management topics:
- View details of vulnerabilities, being able to drill down at each level: instance -> group -> project.
- Export details of vulnerabilities as input to external processes (for example, collation with operating system vulnerabilities, summarisation and reporting to upper management).
- Establishing security approval rules.
Who can address the issue
- Technical writer(s)
- Product manager
- Engineering manager(s) should at least be consulted