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
- 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.
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
-
backend Create placeholder model in CE for Vulnerability
, move logic fromee/models/vulnerability.rb
toEE::Vulnerability
module 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 app/assets/javascripts/behaviors/markdown/gfm_auto_complete.js
,app/assets/javascripts/gfm_auto_complete.js
,app/assets/javascripts/shared/milestones/form.js
,app/assets/javascripts/snippet/snippet_edit.js
,app/assets/javascripts/vue_shared/components/markdown/field.vue
andatwho
callback on^
toee/app/assets/javascripts/gfm_auto_complete.js
. -
backend Enable support for ^
and enable autocomplete for vulnerabilities:-
app/helpers/notes_helper.rb
: Addvulnerabilities
entry toinitial_notes_data
inenableGFM
, -
app/models/concerns/mentionable/reference_regexes.rb
: AddVulnerability
tolink_patterns
indefault_pattern
, -
ee/app/controllers/ee/projects/autocomplete_sources_controller.rb
,ee/app/controllers/groups/autocomplete_sources_controller.rb
: Add method to loadvulnerabilities
forautocomplete
widget, -
ee/app/finders/security/vulnerabilities_finder.rb
: Add ability to filter vulnerabilities that are visible for given user, -
ee/app/helpers/ee/application_helper.rb
: Extendautocomplete_data_sources
with path forvulnerabilities
, -
ee/app/models/concerns/ee/mentionable/reference_regexes.rb
: AddVulnerability
toother_patterns
method, -
ee/app/services/ee/projects/autocomplete_service.rb
,ee/app/services/groups/autocomplete_service.rb
: Add new method to loadvulnerabilities
, -
ee/config/routes/group.rb
,ee/config/routes/project.rb
: Add routes tovulnerabilities
inautocomplete_sources
, -
ee/lib/ee/banzai/filter/vulnerability_reference_filter.rb
,lib/banzai/filter/vulnerability_reference_filter.rb
: Add new reference filter for Vulnerability, -
ee/lib/ee/banzai/reference_parser/vulnerability_parser.rb
,lib/banzai/reference_parser/vulnerability_parser.rb
: Add new reference parser for Vulnerability, -
ee/lib/ee/banzai/issuable_extractor.rb
: Extendreference_types
andparsers
with proper values for Vulnerability, -
ee/lib/ee/banzai/pipeline/gfm_pipeline.rb
,ee/lib/ee/banzai/pipeline/single_line_pipeline.rb
: Extendreference_filters
method with filter class name for Vulnerability, -
lib/gitlab/reference_extractor.rb
: Addvulnerability
toREFERABLES
-