### Problem to solve At GitLab, we [play well with others](https://about.gitlab.com/handbook/product/#plays-well-with-others). Many of our Security customers are using GitLab as a single-application for their developers but have existing Security tools that they would like to use and receive the benefits of a single application. Today, integrating an existing set of security scanning tools into our CI/CD pipelines is cumbersome if not impossible. Without this integration, we are actually degrading the value of our single application by forcing out-of-band workflows. This is possible today (`npm-audit` [example](https://www.npmjs.com/package/gitlab-npm-audit-parser)) but without proper [documentation of how to add an integration](https://gitlab.com/gitlab-org/gitlab-ee/issues/6239), [JSON format standards](https://gitlab.com/gitlab-org/gitlab-ee/issues/8534) and [enforcement](https://gitlab.com/gitlab-org/gitlab-ee/issues/8443) integrations will be tough to develop and maintain, and brittle. After these first enablement steps we could then consider whether GitLab should [maintain integrations with third party tools such as SonarQube](https://gitlab.com/gitlab-org/gitlab-ee/issues/11344). ### Intended users * [Delaney (Development Team Lead)](https://about.gitlab.com/handbook/marketing/product-marketing/roles-personas/#delaney-development-team-lead) * [Sasha (Software Developer)](https://about.gitlab.com/handbook/marketing/product-marketing/roles-personas/#sasha-software-developer) * [Devon (DevOps Engineer)](https://about.gitlab.com/handbook/marketing/product-marketing/roles-personas/#devon-devops-engineer) * [Sam (Security Analyst)](https://about.gitlab.com/handbook/marketing/product-marketing/roles-personas/#sam-security-analyst) ### Further details As a developer using Gitlab, I want to be able to easily find documentation for and contribute an integration for a security testing tool that I or my company prefers. As a Security Admin, I want to be able to use simple snippets or code to add my preferred security tool integration to a project's `gitlab-ci.yml`. ### Proposal Initial proposal: Create a pluggable interface for stakeholders to easily contribute an integration for a security testing tool. Based on [engineering discovery conclusions](https://gitlab.com/gitlab-org/gitlab/issues/14044#conclusions), here is a plan to provide 3rd party integrations: **Integrate using [JSON Report artifacts](https://docs.gitlab.com/ee/ci/yaml/README.html#artifactsreports) following the common format as this allows to seamlessly support all our features: Dashboards, MR and Pipeline workflows, for all branches.** - [ ] keep moving all security features to the common format that support semantic versioning ([DAST migration](https://gitlab.com/groups/gitlab-org/-/epics/810), [Container Scanning migration](https://gitlab.com/groups/gitlab-org/-/epics/808)) NB: this doesn't include License Compliance which is a different report, there is no plan yet about having such a common format to integrate multiple License scanning tools, and License report won't fit into the Common format of Security Reports. - [ ] Document third party integration for Security Reports. https://gitlab.com/gitlab-org/gitlab/issues/34649 - [ ] Provide a JSON Schema for the Common format of the Security Reports. https://gitlab.com/gitlab-org/gitlab/issues/34652 - [ ] Validate automatically the reports using the JSON Schema. https://gitlab.com/gitlab-org/gitlab/issues/34654 - [ ] possibly start announcing 3rd party integration for SAST since it's architecture migration is the most advanced (stable format, DinD removal done). To be confirmed. ### What does success look like, and how can we measure that? Any customer can find necessary documentation and tooling to integrate a 3rd party scanner into our Security Reports. ### What is the type of buyer? ~"GitLab Ultimate" mostly, could be for `Core` users too for SAST with https://gitlab.com/gitlab-org/gitlab/issues/32602 ### Links / references ### Frequently Asked Questions (FAQ) Question: A user / customer / prospect wants us to integrate company X into the secure stage workflow. Answer: You can record it [in this epic:Enable 3rd-party integrations: Specific Partner Requests](https://gitlab.com/groups/gitlab-org/-/epics/2468) but GitLab generally does not want to write vendor specific integrations, our priority is on the agnostic framework build out. GotLab instead encourages vendors to write the integrations, and GitLab is working to improve that process for vendors to be easier (and vendor agnostic) and would love all feedback related to difficulties so we can prioritize the improvements. Technically any user could write an integration if they want. Question: A vendor wishes, or has been asked by a customer, to integrate (or maybe a user wants to). How do they do it? Answer: They should ideally go through the ecosystem/partner team. Question OK, how do they do that? Answer: It is a work in progress at the moment, but they can view [this MR here](https://gitlab.com/gitlab-org/gitlab/merge_requests/21453) and use it to try and kickstart the process and/or make comments on where I failed to be clear so it can be a good document.