Enable Special References for Vulnerabilities

Release notes

We introduced vulnerabilities as first-class objects in 12.10. Being a first-class object means each has a unique URL, allowing linking directly to any vulnerability's details. While a big improvement in visibility and consistency, references to vulnerabilities within Issues and Epics must still be copy-pasted as manual markdown links. This makes sharing and referencing vulnerabilities within other areas of GitLab more cumbersome and less efficient than sharing other objects such as Issues.

Vulnerabilities can now be linked via special references. They are the first to use a new [object_type:ID] syntax that will eventually extend to other existing references. You can now quickly insert a link to a vulnerability from anywhere you might normally use a special reference such as an Issue or MR comment. For instance, simply type [vulnerability:123] in an Issue comment to insert a link back to the vulnerability with ID 123 in the same project. You can also prefix the ID with a namespace or project to reference vulnerabilities outside the current project context.

Documentation: https://docs.gitlab.com/ee/user/markdown.html#special-gitlab-references

Problem to solve

Standalone vulnerabilities brought unique URLs per vulnerability but references to them within Issues and Epics must still be copy-pasted as manual markdown links. This makes sharing and referencing vulnerabilities within other areas of GitLab more cumbersome and less efficient than sharing other objects such as Issues.

Intended users

User experience goal

Referencing a vulnerability inside GitLab should be as easy as referencing an Issue or Epic.

Proposal

Create a new Special Reference type to quickly reference vulnerability objects from places such as Issue and Epic descriptions and comments.

Further details

We will need to add a new GitLab Flavored Markdown (GFM) operator for vulnerability quick references that does not collide with other markdown quick actions or references. Vulnerability special references should work in the same locations an Issue special reference works. This includes:

Issue descriptions
Issue comments
Epic descriptions
Epic comments
MR descriptions
MR comments

Permissions and Security

Users can only create references (via markdown quick actions) to vulnerabilities they have at least read permissions for. This of course does not apply to a users manually inserting via markdown vulnerability URLs to which they do not have permission.

When relying on the auto-suggest feature (after typing, for example, ^ and one or more numbers, just like Issue auto-suggest), the user is never shown suggestions for vulnerabilities to which they have no access.

A user that clicks on a special reference to a vulnerability to which they do not have access will receive an error message (403 is acceptable but 404 preferred keeping in line with least information exposed practice).

Documentation

Availability & Testing

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

Success Metrics:

Within 30 days of release, at least 10 users create at least 1 vulnerability special reference
Within 90 days, at least 50 users create at least 1 vulnerability special reference

Acceptance Criteria:

Starting with the new special reference character (e.g. ^) and beginning to type numbers will start auto-suggesting vulnerabilities to which the current user has permission based on the numbers typed. Speed of suggestion and waiting for typing pauses before suggesting should match that for Issue special references.
Manually inserting markdown for a new special reference (e.g. ^13457) properly converts to the appropriate vulnerability page URL when the markdown page/component (e.g. a comment) is "saved"/finalized.
The new special reference works from the same locations in GitLab where an Issue special reference works.
The new special reference is added to all appropriate documentation sections including relevant markdown instructions

Is this a cross-stage feature?

Almost certainly, yes. Will need to evaluate which other Group(s) are affected by adding a new special reference.

Links / references

Implementation plan

Edited Nov 19, 2020 by Alan (Maciej) Paruszewski