Directly create vulnerability records via API

Release Notes

GitLab's vulnerability management capabilities make it easy to triage and remediate security issues detected by our security scanning tools or from integrated 3rd-party tools. One limitation of this approach is that the vulnerability data can only come from the output of one of these tools. Organizations wishing to pull in other vulnerability source information currently do not have a simple option for doing so.

We are addressing this limitation with the introduction of a new GraphQL endpoint for vulnerability object creation. You now have a way to programmatically add vulnerability records directly to your projects. Combined with our existing GraphQL capabilities for vulnerability management, this opens up many new automation opportunities such as syncing with an external bug bounty program or adding findings from security tools that may not be suitable for pipeline jobs.

https://docs.gitlab.com/ee/api/graphql/reference/

Problem to solve

Users want to add their vulnerabilities via API, so they can integrate any source of report.

This is currently not possible, but could work if we provide an API to create vulnerability objects.

Target audience

• Sam, Security Analyst, https://about.gitlab.com/handbook/marketing/product-marketing/roles-personas#sam-security-analyst

Proposal

Allow creating standalone vulnerability objects via GraphQL. The simplest case is to limit creation to only the default branch on a given Project. However, we must consider that some users will want to create vulnerability objects outside the default branch such as in other protected branches or even tags.

Vulnerability objects created via API need to support all publicly available standalone vulnerability data fields such as:

• Vulnerability name
• Location
• Description
• Severity
• Identifier
• Status
• Solution

Vulnerability objects created via API should be clearly identifiable as such. For example, we might make the scan type Manual (as opposed to SAST, DAST, etc). This will not necessarily be exposed to the user in the UI, at least not the direct field value. Users should also be able to specify a free-text name to identify the source of the vulnerability creation. For example, I might integrate a feed from my company's bug bounty program. It would be helpful if I can specify something like source_type: HackerOne so that I can distinguish this later. Consider that it may be better to provide a more user-friendly API field name here that actually gets mapped to our backend field that currently contains a given Secure scanner's/analyzer's name (e.g. ZAP, Brakeman).

Permissions and Security

Only users with rights to view and modify vulnerability information on a Project's Vulnerability Report can use this API functionality. That should be Developer and above.

Documentation

Add new API endpoint details to the existing GraphQL documentation page. Ideally, include an example to help users understand how to properly use any new methods.

What does success look like, and how can we measure that?

A successful implementation will:

• Create a new vulnerability when provided all necessary valid data through a GraphQL mutation
• Will return a useful error when a vulnerability cannot be created

What is the type of buyer?

GitLab Ultimate

Relevant links

• Design Issue

Non-functional requirements

• Documentation: Update GraphQL Documentation
• Testing: Add specs for new GraphQL route

Implementation plan

This should be done in multiple MRs

• backend Update Vulnerabilities::CreateService to create finding if none exists
  • Use Security::FindingsFinder#build_vulnerability_finding as a starting point
• backend Create new mutation for creating a vulnerability createVulnerability
  • Use Vulnerabilities::CreateService to create the Vulnerability
  • Required fields:
    • Project
    • Title
    • Description
    • Scanner Type
    • Scanner Name
    • Primary Identifier (CVE)
    • Location
  • Optional fields:
    • Severity (defaults to Unknown)
    • Status (defaults to Detected)
    • Solution
    • Message
    • Detected At (defaults to Vulnerability creation time)
    • Confirmed/Resolved/Dismissed at (defaults to Vulnerability creation time if status is not Detected)

Possible follow-on issues:

• Add field to create an issue from vulnerability
• Add field to create an MR from vulnerability