Engineering Discovery: What needs to be done to best support third party integrations?

Problem to be solved

Engineering Research: What needs to be done to best support third party integrations?

In order for partners to pull and push data to replace one of our scanners, or for us to be able to easily swap our scanner choices, what webhooks and apis or other items need to be done? The outcome should be a list of items needed, and the teams that the asks should be discussed with.

Current state

  1. Push data

Any compatible JSON report can be pushed as a report artifact.

E.g. for Dependency Scanning we document the report format and the job configuration to define a report artifact).

The main issue with this approach is the complexity of the constraints on that report to ensure unique identification of a vulnerability occurrence. This is mandatory for both MR widget (to compare security reports between branches) and for storing vulnerabilities in DB (default_branch only) to display them in the project and group dashboards and use the upcoming first-class vulnerabilities. To make it even harder, these constraints are specific to each report type (with some overlap). This is what prevented us to promote that approach as an official API so far.

  1. Pull data

We currently have a vulnerability API which provide data for a given project (returns the vulnerability Occurrences stored in our DB from the latest pipeline of the default_branch). It was recently improved to also allow to fetch them for any given pipeline (so by parsing artifact on demand, no DB storage here) and there is also an upcoming improvement to do it at group level.

Proposal

Leverage the existing JSON Report artifacts or look for possible HTTP API to directly create first-class vulnerabilities EDIT: this is not achievable as per the engineering discovery (see details below).

Conclusions

Integrate using JSON Report artifacts following the common format as this allows to seamlessly support all our features (Dashboards + MR and Pipeline workflows).

  1. keep moving all security features to the common format that support semantic versioning (DAST migration, Container Scanning migration)
  2. better document the current format: explicit mandatory properties and explain identification scheme (identifiers, location) for each report type. Maybe dedicated documentation would make sense here?
  3. improve format validation with JSON schema (existing issue to find and link here)
  4. possibly start announcing 3rd party integration for SAST since it's architecture migration is the most advanced (stable format, DinD removal done)
Edited by Olivier Gonzalez