GitLab Next

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 from ee/models/vulnerability.rb to EE::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 and atwho callback on ^ to ee/app/assets/javascripts/gfm_auto_complete.js.
• backend Enable support for ^ and enable autocomplete for vulnerabilities:
  • app/helpers/notes_helper.rb: Add vulnerabilities entry to initial_notes_data in enableGFM,
  • app/models/concerns/mentionable/reference_regexes.rb: Add Vulnerability to link_patterns in default_pattern,
  • ee/app/controllers/ee/projects/autocomplete_sources_controller.rb, ee/app/controllers/groups/autocomplete_sources_controller.rb: Add method to load vulnerabilities for autocomplete 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: Extend autocomplete_data_sources with path for vulnerabilities,
  • ee/app/models/concerns/ee/mentionable/reference_regexes.rb: Add Vulnerability to other_patterns method,
  • ee/app/services/ee/projects/autocomplete_service.rb, ee/app/services/groups/autocomplete_service.rb: Add new method to load vulnerabilities,
  • ee/config/routes/group.rb, ee/config/routes/project.rb: Add routes to vulnerabilities in autocomplete_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: Extend reference_types and parsers with proper values for Vulnerability,
  • ee/lib/ee/banzai/pipeline/gfm_pipeline.rb, ee/lib/ee/banzai/pipeline/single_line_pipeline.rb: Extend reference_filters method with filter class name for Vulnerability,
  • lib/gitlab/reference_extractor.rb: Add vulnerability to REFERABLES