Close gaps in the Secure documentation
Issue #297 (closed) identified gaps in the Secure documentation. This issue is to implement whatever's required to close those gaps. Depending on the scope and scale of the work, this issue may be converted into an epic.
-
Add more information on the what and why in the introduction to Secure -
Add content for those who have oversight of security -
Add general guidance on how to rectify vulnerabilities -
Add information about using Secure's features at scale -
Resolve potential for confusion over docs navigation -
Add terms which are alternate names for Secure features -
Add comparative table of SAST and DAST analysers -
Add DAST demonstration projects
Problem and implementation
Gap: Insufficient context provided in the introduction of each Secure's features. This makes it difficult for someone new to the topic to understand what each feature provides, and where it fits into the development life cycle. Feedback from @stkerr was that although we provide sufficient detail as to how, detail on what and why is lacking.
Implementation:
- Ensure each of Secure's features has an appropriate introduction.
- Optionally, add a diagram to the Secure main page, and each feature's pages, which illustrates where the feature fits into the development life cycle.
- Describe the problem the tools solve, how they interact and compare to each other (for example, SAST and DAST).
Issue: gitlab#216671 (%14.2)
Gap: Secure's documentation is largely aimed at the Developer persona. We should also be providing content for those who monitor, manage, and report on projects' security status.
Implementation:
- Highlight the vulnerability oversight features available in GitLab:
- Security Dashboard
- Vulnerability Report
- Security Center
This content could be added to the introductory Secure docs page.
Issue: gitlab#323281 (closed) (%14.0)
Gap: While the analyzers identify vulnerabilities, we don't provide enough guidance on how to rectify them.
Implementation:
- Add general documentation on how to rectify common types of vulnerabilities, including:
- Vulnerability in a dependency (Issue: gitlab#323282) (%13.12)
- Secret committed to a project (Issue: gitlab#323284 (closed)) (%13.12)
Gap: We are missing information that helps customers operating above the SME scale. Such companies are left to determine by themselves how to scale the various Secure configurations to hundreds or more projects. For example, the SAST offline documentation includes instructions on implementing a change per project. This is a very inefficient method of applying changes. Instead, the instructions should instruct the user to implement these changes at the instance level.
Implementation:
- Add documentation on how companies can implement Secure's features efficiently and effectively. Example:
- Add documentation on how settings can be used at the instance and group level, to make settings deployment more efficient.
Issue: gitlab#323290 (%14.0)
Gap: There is a disconnect between the naming "Secure" and its docs navigation naming "Application Security". The naming "Application Security" is appropriate, but it's not clear if this terms relates to security of the user's application or security controls within GitLab. The GitLab application security controls are listed in the documentation navigation under the title "Security".
Implementation:
- Move the existing "Secure" navigation item to elsewhere, likely the section aimed at the administrator.
- Rename the "Application Security" navigation item
- Move the "Application Security" navigation item to be a top-level item.
Issue: gitlab#323287 (closed) (%13.10)
Gap: The terms by which users know specific features may be different from the terms they're already familiar with. This makes it difficult to find the matching documentation because they may search for a familiar term, not find anything, and assume we don't provide that functionality.
Implementation:
- Consult PMs, marketing, and other stakeholders to create a list of terms applicable to Secure and Protect.
- Identify other terms users may know these terms by.
- In the matching GitLab documentation, make mention of the alternate terms.
Issue: gitlab#323291 (%14.2)
Gap: For Secure features such as SAST and DAST we allow the user to choose which analyzers they want to run. This presents a problem because anyone not already familiar with them is not able to make an informed choice.
Implementation:
- Create a comparative table for all analyzers.
Issue: A comparative list of Secure features is available in https://docs.gitlab.com/ee/user/application_security/#security-scanning-tools.
Gap: The DAST documentation has grown organically as features have been added. This has resulted in documentation with poor structure.
Implementation: The existing structure should be reviewed, improved, and gaps filled.
Issue: gitlab#300508 (closed) (%13.11)
Gap: For anyone not already familiar with DAST, enabling it on an existing project may be daunting. They may be concerned about the potential harm to an existing project, and so decide the potential costs outweigh the potential benefits. To help overcome this issue, we could provide example projects that the user could clone. They would be preconfigured to scan the most common project languages, for example: Java and Ruby.
Implementation:
- Create one example project per project type. Each project would be preconfigured with DAST enabled. Included would be a README which provided a brief description, and a link to the DAST docs for more information.
Issue: This was completed by Isaac Dawson as part of an MR which added application deployment instructions to the DAST documentation. The example projects are hosted at: https://gitlab.com/gitlab-org/security-products/demos/dast/.