Enable Special References for Vulnerabilities
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.
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.
- Parker (Product Manager)
- Delaney (Development Team Lead)
- Sasha (Software Developer)
- Devon (DevOps Engineer)
- Sam (Security Analyst)
- Alex (Security Operations Engineer)
User experience goal
Referencing a vulnerability inside GitLab should be as easy as referencing an Issue or Epic.
Create a new Special Reference type to quickly reference vulnerability objects from places such as Issue and Epic descriptions and comments.
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).
Availability & Testing
What does success look like, and how can we measure that?
- 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
- 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
backend Create placeholder model in CE for
Vulnerability, move logic from
EE::Vulnerabilitymodule and prepend it in the model defined in CE. This is needed to reserve
^as a special reference in GitLab,
frontend Add entry for vulnerability to
backend Enable support for
^and enable autocomplete for vulnerabilities:
ee/app/controllers/groups/autocomplete_sources_controller.rb: Add method to load
ee/app/finders/security/vulnerabilities_finder.rb: Add ability to filter vulnerabilities that are visible for given user,
autocomplete_data_sourceswith path for
ee/app/services/groups/autocomplete_service.rb: Add new method to load
ee/config/routes/project.rb: Add routes to
lib/banzai/filter/vulnerability_reference_filter.rb: Add new reference filter for Vulnerability,
lib/banzai/reference_parser/vulnerability_parser.rb: Add new reference parser for Vulnerability,
parserswith proper values for Vulnerability,
reference_filtersmethod with filter class name for Vulnerability,