Document third party integration for Security Reports
Problem to solve
We need to create dedicated documentation for 3rd party integrations into our Security Reports.
Further details
We currently expose the JSON format of each report type on their respective documentation:
- SAST: https://docs.gitlab.com/ee/user/application_security/sast/index.html#reports-json-format
- dependency scanning: https://docs.gitlab.com/ee/user/application_security/dependency_scanning/index.html#reports-json-format
Container Scanning and DAST to be done with the corresponding migrations: (DAST migration, Container Scanning migration)
Proposal
Create a new page or section dedicated to integration, to be added to the GitLab Secure documentation.
This documentation should present and explain the JSON properties that are already listed SAST and Dependency Scanning. In particular, it should:
- present the mandatory properties, and explain why they are needed
- explain how identifiers and locations work, and provide examples
It should cover the shared report format as well as what's specific to SAST, DAST, Dependency Scanning, and Container Scanning.
Every type of scanner must be documented. Not available for this scanner
is a valid documentation. For each Not available
scanner type, create a backlog issue to add / update documentation once specified blocker is complete.
If we decide to rename the report format, use To be discussed.Secure Stage Common Report Format
SSCRF
We should also document the standards conventions the CI job definition of the scanners should follow, such as:
- scripts must be in the
script:
section, and leavebefore_script:
andafter_script:
free for user customizations - (to be completed)
The documentation should explain how the job definitions are made available to users, using YAML snippet they include in their CI configuration files.
A further proposal is available in this doc: https://docs.google.com/document/d/1nlChfHQM9cei1h3NNoNnyza9Hfm79kvDLVKYc5awVQ0/edit#heading=h.fq83kn48tw2
Who can address the issue
@fcatteau + @gonzoyumo
-
development documentation !21636 (merged) user documentation
@NicoleSchwartz
partner documentation !21453 (closed)
@stkerr
-
Secure partner onboarding !25926 (merged)
@axil
-
Guidelines about content organization and review.