Skip to content

Rename and document CI variable GEMNASIUM_DB_UPDATE

Release notes

Problem to solve

The CI variable GEMNASIUM_DB_UPDATE, supported by all Dependency Scanning analyzers based on Gemnasium, is not documented in Dependency Scanning documentation, though it might be useful when configuring offline scanner.

Intended users

User experience goal

As a user, I can easily understand how to use the CI variable to disable fetching the gemnasium DB at runtime.

Proposal

Currently, GEMNASIUM_DB_UPDATE is true by default and it causes Gemnasium-based analyzers to update the local gemnasium-db clone using git.

Since this feature can be useful for community contributors, our engineers, and since the equivalent BUNDLER_AUDIT_UPDATE_DISABLED env var is already documented in our user doc, it is the best place to add this one too.

  1. For consistency we must rename GEMNASIUM_DB_UPDATE to GEMNASIUM_UPDATE_DISABLED, with a default value of false (in other words, by default, the gemnasium DB will be updated when a scan is run).

    1. Rename envVarDBUpdate to envVarDBUpdateDisabled and DB_UPDATE to DB_UPDATE_DISABLED in gemnasium/scanner/scanner.go

    2. Update Usage in gemnasium/scanner/scanner.go to reflect change in behaviour, using similar wording to bundler-audit:

      Do not update the gemnasium-db git repo before scanning (default: false)

    3. Update the gemnasium README to include a section on Running the analyzer in airgapped or internal networks, similar to the description used in bundler-audit

  2. Update the Dependency Scanning docs

    1. Update the Configuring specific analyzers used by dependency scanning section to include details about the GEMNASIUM_UPDATE_DISABLED variable, using similar wording to the BUNDLER_AUDIT_UPDATE_DISABLED variable

    2. Add a new section to document both approaches for users who want to use an alternate DB:

      1. using a local copy of the gemnasium-db repository that can act as a remote for the container and be configured with GEMNASIUM_DB_REMOTE_URL to be fetched at runtime by the container.
      2. using a local copy of the gemnasium-db repository that is not acting as a remote git repository but made available by any other means (before_script or included in the image) to the file system of the container (and possibly configured with GEMNASIUM_DB_LOCAL_PATH).

       

      Note that while this is mainly useful for offline users, this is applicable to other usages, for example, when a user wants to use a custom DB. How we want to describe it in our documentation is to be determined.

Implementation Plan

  • add GEMNASIUM_DB_UPDATE_DISABLED to gemnasium (default: false)
  • remove GEMNASIUM_DB_UPDATE
  • document this variable
  • add a use case for using this variable in restricted network environments
  • add corresponding case for GEMNASIUM_DB_REMOTE_URL

Permissions and Security

Documentation

Available Tier

  • Ultimate/Gold

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

  • GEMNASIUM_DB_UPDATE is renamed to GEMNASIUM_UPDATE_DISABLED
  • GEMNASIUM_UPDATE_DISABLED is documented in our user documentation
  • users clearly understand the both possible approaches to configure a different Gemnasium DB.

What is the type of buyer?

Is this a cross-stage feature?

Links / references

Edited by Igor Frenkel