{"id":13523431,"url":"https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium","last_synced_at":"2025-04-01T00:31:51.469Z","repository":{"id":49975640,"uuid":"9450192","full_name":"gitlab-org/security-products/analyzers/gemnasium","owner":"gitlab-org","description":"Dependency Scanning Analyzer based on Gemnasium.","archived":false,"fork":false,"pushed_at":null,"size":null,"stargazers_count":24,"open_issues_count":null,"forks_count":36,"subscribers_count":null,"default_branch":"master","last_synced_at":"2024-02-17T10:37:23.811Z","etag":null,"topics":["Dependency Scanning","GL-Secure","GL-Secure Analyzer","hacktoberfest"],"latest_commit_sha":null,"homepage":null,"language":null,"has_issues":false,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://gitlab.com/uploads/-/system/project/avatar/9450192/gemnasium.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2018-11-17T07:37:16.449Z","updated_at":"2024-02-17T06:42:21.437Z","dependencies_parsed_at":"2022-08-23T16:41:04.790Z","dependency_job_id":null,"html_url":"https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium","commit_stats":null,"previous_names":[],"tags_count":121,"template":null,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/gitlab.com/repositories/gitlab-org%2Fsecurity-products%2Fanalyzers%2Fgemnasium","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/gitlab.com/repositories/gitlab-org%2Fsecurity-products%2Fanalyzers%2Fgemnasium/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/gitlab.com/repositories/gitlab-org%2Fsecurity-products%2Fanalyzers%2Fgemnasium/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/gitlab.com/repositories/gitlab-org%2Fsecurity-products%2Fanalyzers%2Fgemnasium/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/gitlab.com/owners/gitlab-org","download_url":"https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/archive/master/gemnasium-master.zip","host":{"name":"gitlab.com","url":"https://gitlab.com","kind":"gitlab","repositories_count":4518466,"owners_count":6905,"icon_url":"https://github.com/gitlab.png","version":null,"created_at":"2022-05-30T11:31:42.605Z","updated_at":"2024-07-18T11:24:13.055Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/gitlab.com","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/gitlab.com/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/gitlab.com/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/gitlab.com/owners"}},"keywords":["Dependency Scanning","GL-Secure","GL-Secure Analyzer","hacktoberfest"],"created_at":"2024-08-01T06:01:00.016Z","updated_at":"2025-04-01T00:31:51.456Z","avatar_url":"https://gitlab.com/uploads/-/system/project/avatar/9450192/gemnasium.png","language":null,"funding_links":[],"categories":["CI/CD","OSS and Dependency management","Software Composition Analysis"],"sub_categories":["Dependency Management"],"readme":"This project's issue tracker has been disabled, if you wish to [create an issue or bug please follow these directions](/CONTRIBUTING.md#issue-tracker).\n\n[TOC]\n\n# Gemnasium analyzer\n\nDependency Scanning analyzer that uses the [GitLab Advisory Database](https://gitlab.com/gitlab-org/security-products/gemnasium-db).\n\nThis analyzer is written in Go using the [common library] shared by most Secure analyzers.\n\nIf you wish to [create an issue or bug please follow these directions](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/master/CONTRIBUTING.md#issue-tracker) but do not create an issue or bug in this project.\n\n## Status\n\nDevelopment of this analyzer is moving to a new [dependency-scanning](https://gitlab.com/gitlab-org/security-products/analyzers/dependency-scanning) project.\nFor more information see [epic 14484](https://gitlab.com/groups/gitlab-org/-/epics/14484).\n\n## Usage\n\nThe [common library] documents\n[how to use the analyzer](https://gitlab.com/gitlab-org/security-products/analyzers/common/#how-to-use-the-analyzers).\n\n## Testing\n\nThe [common library] documents [how to test the Docker image](https://gitlab.com/gitlab-org/security-products/analyzers/common/#analyzers-development) of the analyzer using `docker run`.\n\nIn addition, this project also provides image integration tests.\n\n### Image integration tests\n\nImage integration tests are executed on CI to check the Docker image of the analyzer using [RSpec](https://rspec.info/).\nThey check the output and exit code of the analyzer, as well as the Dependency Scanning report it generates.\nThe image integration tests can also be executed locally, for example, to check an image that was built locally using `docker build`\u003csup\u003e[3](#unable-to-build-image)\u003c/sup\u003e.\n\nThere are two ways of running the image integration tests locally:\n\n1. Using the `integration-test` Docker image\u003csup\u003e\u003cb\u003e[1](#running-image-integration-tests-using-the-integration-test-docker-image)\u003c/b\u003e\u003c/sup\u003e (recommended)\n1. Directly on your local machine using ruby\u003csup\u003e\u003cb\u003e[2](#running-image-integration-tests-using-ruby)\u003c/b\u003e\u003c/sup\u003e\n\n#### Running image integration tests using the integration-test Docker image\n\nSee the [instructions](https://gitlab.com/gitlab-org/security-products/analyzers/integration-test/-/blob/main/README.md#how-to-run-the-integration-test-docker-container-locally) from the `integration-test` project.\n\n#### Running image integration tests using ruby\n\nTo run the image integration tests, you need ruby, bundler, as well as some ruby extensions.\nYou also need git in order to fetch some test projects locally.\n\nHere's how to install these packages on Alpine Linux:\n\n```shell\napk add ruby ruby-bundler ruby-json ruby-bigdecimal git\n```\n\nOnce ruby and bundler are installed, change to the root directory of the analyzer project, and install the gems needed to run RSpec:\n\n```shell\nbundle install --path vendor/ruby\n```\n\nThen copy the [Dependency Scanning Report schema](https://gitlab.com/gitlab-org/security-products/security-report-schemas/-/blob/master/dist/dependency-scanning-report-format.json) to the analyzer project.\nThis schema is used to perform JSON schema validation.\nHere's how to fetch the latest version of the schema using curl:\n\n```shell\ncurl -o dependency-scanning-report-format.json https://gitlab.com/gitlab-org/security-products/security-report-schemas/-/raw/master/dist/dependency-scanning-report-format.json\n```\n\nFinally, you can test the Docker image you've built using bundler and the `rspec` command.\nThe name of the image being tested should be set in the environment variable `TMP_IMAGE`.\n\n```shell\nTMP_IMAGE=gemnasium:latest bundle exec rspec\n```\n\n## Implementation\n\nGemnasium is a CLI written using the [urfave/cli](https://github.com/urfave/cli) package.\n\nThe CLI exposes a `run` command that proceeds as follows:\n1. check whether the target directory is supported\n1. scan the supported dependency files, and build a list of vulnerabilities\n1. look for solutions for these vulnerabilities (auto-remediation)\n1. generate a JSON report\n\nThe generated JSON report describes:\n- the dependency files and their dependencies\n- the vulnerabilities found in these files\n- the solutions to these vulnerabilities (remediations), if any\n\nCurrently, Gemnasium is NOT built on top of the `command` package of the [common library],\neven though its `run` command is very similar to `command.Run`.\n\nThe scan itself is implemented in the [`scanner`](scanner) package.\nThe `Scanner` proceeds as follows:\n1. **configure** the advisory repository, and update it if requested\n1. **find** the supported dependency files, along with the compatible parsers\n1. **parse** these dependency files, and build a list of dependencies (type, name, and version)\n1. **match** the dependencies with the advisories, and add affections to dependency files\n\nAn `Affection` is a struct that combines a security advisory with a dependency affected by it.\n\nThe scanner relies on several sub-packages to perform the scan:\n- [parser](scanner/parser) to find supported dependency files, and parse them\n- [advisory](advisory) to find security advisories, and read them\n- [vrange](vrange) to evaluate the affected range, and tell whether a version is affected\n\n## Development\n\nThe [common library] covers the generic aspects\nof [analyzers development](https://gitlab.com/gitlab-org/security-products/analyzers/common/#analyzers-development).\n\nSupporting a new package manager generally involves:\n1. adding a new [dependency file parser](#dependency-file-parsers)\n1. adding a specific package name resolver to the [advisory repository](#advisory-repository)\n1. adding a new [version range solver](#version-range-evaluation) or reusing an existing one\n1. adding QA jobs to the CI pipeline\n\n### Dependency file parsers\n\nThe [parser](scanner/parser) package implements a collection of dependency file parsers.\nA parser is registered with the filenames and package type it supports.\nIt reads a lock file or a dependency graph, or any file that lists the transient project dependencies,\nalong with the exact versions of these dependencies.\n\nA parser generates a list of dependencies.\nEach dependency has a name and version. The list is unordered and contains no duplicates.\n\n#### Implementing a parser\n\nBefore implementing a new dependency file parser,\nit might be necessary to declare a new `PackageType` in the [parser](scanner/parser) package.\nNote that the package type might already be declared if it's already supported via another file parser.\n\nImplementing a new dependency file parser consists of the following:\n1. create sub-package under the [parser](scanner/parser) package\n1. create a struct that implements the `parser.Parser` interface\n1. register the struct using `parser.Register`, in the `init` function of the new package\n1. provide fixtures and unit tests\n\nThe parser must detect whether the version of the dependency file syntax is supported,\nand return a specific error if it's not.\n\nA package implementing a parser should only export symbols that are absolutely necessary for external packages.\n\nThe parser is registered with:\n- a name\n- the filenames it supports, used when scanning a directory\n- a package type, used to match the dependencies with security advisories\n- a package manager reported in the dependency list\n\nThe package type and the filenames a parser is registered with,\nare thus critical to dependency scanning,\nbut the name of the parser and the supported package manager are not.\n\nThe unit tests should cover at least two cases:\n- file is successfully parsed and returns a list of dependencies that contains no duplicate\n- file is not supported (incompatible version of the syntax)\n\nUnit tests can be written simply by copying the test of another parser (e.g. [gemfile_test.go](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/master/scanner/parser/gemfile/gemfile_test.go)) and by supplying a fixture lock file (e.g. [Gemfile.lock](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/master/scanner/parser/gemfile/fixtures/simple/Gemfile.lock)) and the expectation for the parsed data (e.g. [dependencies.json](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/master/scanner/parser/gemfile/expect/simple/packages.json)).\n\nNote: For a parser that returns the parsed packages and the graph of dependencies, both expectations must be supplied (e.g. [expectations](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/tree/master/scanner/parser/nuget/expect/duplicates)).\n\nTo enable a parser in the analyzer CLI, import it as an anonymous package in [main.go](main.go).\nIf not enabled, the dependency files supported by the parser are ignored during the scan.\n\n### Advisory repository\n\nThe [advisory](advisory) package is used to interact with the [vulnerability database],\na GitLab project that contains security advisories in the form of YAML files.\n\nMain features:\n- update a git clone of the vulnerability database\n- list the advisory files matching a given package\n- parse advisory files\n\n#### Advisory path resolution\n\nA dependency file parser is registered with a package type, and it returns package names when parsing a file.\nCombined together, the type and name are used to find the directory that contains the advisories for a given package.\nIn most cases, the type and name match the directory path.\nFor instance, the advisories of a `gem` named `rails` are the YAML files found\nin the `gem/rails` directory of the vulnerability database.\n\nHowever, some parsers might return package names\nthat don't necessarily match directories of the vulnerability database.\nFor instance, the parser that handles `Pipfile.lock` (Python) returns non-canonical package names,\nand these must be resolved in accordance with [PEP 0426](https://www.python.org/dev/peps/pep-0426/#name).\n\nIf the package type and name don't directly match a directory of the vulnerability database,\nthis exception has to be implemented in `Repo.PackageAdvisories`.\n\n### Version range evaluation\n\nThe [vrange](vrange) package is used to determine whether a version matches a version range.\nIt's composed of sub-packages that cover the various version syntaxes used by the package managers Gemnasium supports.\nMost of of these sub-packages are wrappers around simple CLIs implemented using the language to support.\nFor instance, [vrange/gem](vrange/gem) evaluates Ruby gem versions,\nand it's built on top of a Ruby script. The exceptions are Conan and Maven, with Conan supported with the npm sub-package and Maven supported with the semver sub-package. See [version range modules](#version-range-modules) for supported languages/package managers.\n\n#### Version range modules\n\n| Language/Package Manager | Supporting sub-package |\n|--------------------------|------------------------|\n| Conan (C, C++)           | `vrange/npm`           |\n| Gem (Ruby)               | `vrange/gem`           |\n| Golang                   | `vrange/golang`        |\n| npm                      | `vrange/npm`           |\n| NuGet (C#)               | `vrange/nuget`         |\n| PHP                      | `vrange/php`           |\n| Python                   | `vrange/python`        |\n| Maven                    | `vrange/semver`        |\n\n#### Implementing a CLI-based resolver\n\nImplementation steps:\n\n1. create a sub-package under the [vrange](vrange) package\n1. implement a CLI that implements the vrange API\n1. register the CLI using the `RegisterCmd` function, or register the Go native resolver with `Register`\n1. make the path of the vrange CLI configurable by setting an environment variable or a CLI flag\n1. check the [Dockerfile](Dockerfile) and make sure the vrange CLI is part of the Docker image\n1. if needed, update the [Dockerfile](Dockerfile) to install the dependencies of the vrange CLI\n1. provide unit tests\n\nIf the vrange CLI is compiled to a binary, you can either:\n- update the [CI config](.gitlab-ci.yml) and add a job that compiles the binary, and passes it as an artifact\n- update the [Dockerfile](Dockerfile) and add a stage that compiles the binary, which is then copied to the final image\n\nThe unique argument of the vrange CLI is the path of a JSON document.\nThis document is an array of query objects.\nA query has two keys:\n- `version` (string, required)\n- `range` (string, required)\n\nThe output of the vrange CLI is a JSON document.\nThis document is an array of result objects.\nA result has three keys:\n- `version` (string)\n- `range` (string)\n- `satisfies` (boolean) tells if the version is in range\n- `error` (string) reports a parsing error for the version or the range\n\nThe `satisfies` and `error` keys are exclusive.\n\nThe output document must contain results for every query of the input document.\n\nThe order of the result objects doesn't have to match the order of the query objects.\n\nThe vrange CLI fails when it cannot process the input document,\nbut it musn't fail when it cannot parse a version or a range\n(it must report an error instead).\n\n#### Implementing a Go-native resolver\n\nImplementation steps:\n\n1. create a sub-package under the [vrange](vrange) package\n1. create a Go struct that implements the `Resolver` interface\n1. register the resolver using the `Register` function\n1. provide unit tests\n\n## Lefthook\n\n[Lefthook](https://github.com/Arkweid/lefthook) is a Git hooks manager that allows custom logic to be executed prior to Git committing or pushing. This project comes with a `lefthook.yml` configuration file, but there are two steps that must be performed before it can be used:\n\n### Installing Lefthook\n\n1. Install the Lefthook Git hook manager. Please follow [these directions](https://github.com/evilmartians/lefthook/blob/master/docs/other.md) to install the Lefthook binary for your environment. On Mac OS X or Linux, this can be achieved using the following command:\n\n   ```shell\n   $ go install github.com/evilmartians/lefthook@latest\n   ```\n\n   Note: Before installing the Lefthook binary, check to see if it's already installed by using `which lefthook`, since if you're using the [GitLab Development Kit (GDK)](https://gitlab.com/gitlab-org/gitlab-development-kit) or have contributed to the [gitlab-org/gitlab](https://gitlab.com/gitlab-org/gitlab) project, you may have already installed Lefthook.\n\n1. Install Lefthook managed Git hooks:\n\n   ```shell\n   $ lefthook install\n   ```\n\n   This command will create new Git hook files in the `.git/hooks/` directory that will execute the commands specified in the `lefthook.yml` file for the given Git hook event, such as `pre-push` or `pre-commit`.\n\n1. Confirm that Lefthook is working by running the Lefthook `pre-push` Git hook:\n\n   ```shell\n   $ lefthook run pre-push\n\n   Lefthook v0.7.7\n   RUNNING HOOKS GROUP: pre-push\n\n     EXECUTE \u003e go-mod-tidy\n     EXECUTE \u003e go-lint\n     EXECUTE \u003e go-test\n\n   SUMMARY: (done in 3.16 seconds)\n   ✔️  go-mod-tidy\n   ✔️  go-test\n   ✔️  go-lint\n   ```\n\nPlease see the [Pre-push static analysis with Lefthook](https://docs.gitlab.com/ee/development/contributing/style_guides.html#pre-push-static-analysis-with-lefthook) docs for more details.\n\n### Updating the lefthook scripts\n\n```shell\n$ lefthook install\n```\n\n## Conditionally triggering child pipelines using labels\n\nYou can conditionally trigger different child pipelines by assigning the following labels to a merge request before pushing new code or running a pipeline:\n\n- ~\"trigger-gemnasium\"\n- ~\"trigger-gemnasium-python\"\n- ~\"trigger-gemnasium-maven\"\n- ~\"trigger-docs-only\" To be used when making changes to _documentation only_, such as the [`README.md`](README.md) or [`CHANGELOG.md`](CHANGELOG.md) files.\n\nOnly the child pipelines matching the applied labels will be triggered.\n\nMultiple child pipelines can be triggered at once by applying a combination of labels.\n\nConditionally triggering child pipelines may result in failed container scanning jobs. This is because there's no easy way to skip the container scanning jobs for the images we're not building.\n\n## Release Process\n\n`gemnasium` uses scripts from the [ci-templates](https://gitlab.com/gitlab-org/security-products/ci-templates/) project to automate the release of new analyzer images.\n\nThe process works as follows:\n\n1. An MR is merged to `gemnasium`. This kicks off a pipeline in the `master branch`, for example [this pipeline](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/pipelines/787699855).\n1. The `master branch pipeline` executed in step `1.` above triggers child pipelines for the following analyzer and SBOM-generation tools:\n\n   - `gemnasium`\n   - `gemnasium-maven`\n   - `gemnasium-python`\n\n1. Child pipelines for each analyzer are executed:\n\n   1. The `build-image` stage is executed which triggers the [build tmp image](https://gitlab.com/gitlab-org/security-products/ci-templates/blob/d37268e/includes-dev/docker.yml#L31-42) job from the `ci-templates` project.\n\n      The `build tmp image` job builds, tags, and pushes new `tmp` Docker images for each analyzer. For example:\n\n      - `gemnasium`\n         - `registry.gitlab.com/gitlab-org/security-products/analyzers/gemnasium/tmp/main:\u003cgit-commit-sha\u003e`\n         - `registry.gitlab.com/gitlab-org/security-products/analyzers/gemnasium/tmp/main:\u003cgit-commit-sha\u003e-fips`\n      - `gemnasium-maven`\n         - `registry.gitlab.com/gitlab-org/security-products/analyzers/gemnasium/tmp/maven:\u003cgit-commit-sha\u003e`\n         - `registry.gitlab.com/gitlab-org/security-products/analyzers/gemnasium/tmp/maven:\u003cgit-commit-sha\u003e-fips`\n      - `gemnasium-python`\n         - `registry.gitlab.com/gitlab-org/security-products/analyzers/gemnasium/tmp/python:\u003cgit-commit-sha\u003e`\n         - `registry.gitlab.com/gitlab-org/security-products/analyzers/gemnasium/tmp/python:\u003cgit-commit-sha\u003e-python-3.10`\n         - `registry.gitlab.com/gitlab-org/security-products/analyzers/gemnasium/tmp/python:\u003cgit-commit-sha\u003e-fips`\n\n   1. The `test` stage is executed for each child pipeline, using the `tmp` Docker images produced in step `3.1` above.\n\n      1. The [check analyzer version](https://gitlab.com/gitlab-org/security-products/ci-templates/blob/d37268e/includes-dev/docker-test.yml#L94-124) job ensures that the latest version in the changelog matches the version reported by executing the analyzer.\n\n      1. The [check image size](https://gitlab.com/gitlab-org/security-products/ci-templates/blob/d37268e/includes-dev/docker-test.yml#L28-47) job ensures that the size of the newly built Docker image doesn't exceed a given threshold.\n\n      1. The `image test` and `image test fips` jobs use the [integration-test](https://gitlab.com/gitlab-org/security-products/analyzers/integration-test/) project to execute the Docker images against fixture files in the `qa/fixtures` directory and check their output against expectation files located in the `qa/expect` directory.\n\n      1. Various `*-qa` and `*-qa fips` downstream QA jobs are triggered for tests that cannot be implemented using the `image integration-test` approach above.\n\n   1. The `release-version` stage is executed, which tags `edge` versions of the analyzers, for example:\n\n      - `gemnasium`\n         - `registry.gitlab.com/security-products/gemnasium:edge`\n      - `gemnasium-maven`\n         - `registry.gitlab.com/security-products/gemnasium-maven:edge`\n      - `gemnasium-python`\n         - `registry.gitlab.com/security-products/gemnasium-python:edge`\n\n1. The `test` stage is executed for the parent pipeline, which runs various static analysis, container scanning and dependency scanning analyzers against the repository and newly built analyzer Docker images.\n\n1. The `tag` stage is executed, which runs the [upsert git tag](https://gitlab.com/gitlab-org/security-products/ci-templates/blob/d37268e/includes-dev/upsert-git-tag.yml#L1-60) job.\n\n   The `upsert git tag` job creates a new [release](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/releases) of `gemnasium` using the [GitLab Releases API](https://docs.gitlab.com/ee/api/releases/#create-a-release).\n\n   When the new release is created, a new `git tag` is automatically created using the latest version from the [`CHANGELOG.md`](CHANGELOG.md) file, which points to the `SHA` for the git merge commit of the MR merged in step `1.`.\n\n1. When the new `git tag` is created in step `5.` above, a new `git tag pipeline` is executed, for example [this pipeline](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/pipelines/787734943) for the `v3.11.3` git tag.\n\n   The `git tag pipeline` is executed by the [`gl-service-dev-secure-analyzers-automation`](https://gitlab.com/gl-service-dev-secure-analyzers-automation) service account.\n\n   This pipeline repeats _all of the above steps_ (there's an [open issue](https://gitlab.com/gitlab-org/gitlab/-/issues/350448) to remove this duplication), except for the following differences:\n\n   - It does not execute the `test` or `tag` stages that were previously executed in step `4.` and `5.` respectively.\n\n   - Instead of executing the `release-version` stage of step `3.3`, it executes a `release-major` stage which tags and pushes the following Docker images:\n\n      - `gemnasium`\n         - `release latest`\n            - `registry.gitlab.com/security-products/gemnasium:latest`\n         - `release major`\n            - `registry.gitlab.com/security-products/gemnasium:3`\n         - `release major fips`\n            - `registry.gitlab.com/security-products/gemnasium:3-fips`\n         - `release minor`\n            - `registry.gitlab.com/security-products/gemnasium:3.11`\n         - `release minor fips`\n            - `registry.gitlab.com/security-products/gemnasium:3.11-fips`\n         - `release patch`\n            - `registry.gitlab.com/security-products/gemnasium:3.11.3`\n         - `release patch fips`\n            - `registry.gitlab.com/security-products/gemnasium:3.11.3-fips`\n      - `gemnasium-maven`\n         - same pattern as above, using `gemnasium-maven` as the image name.\n      - `gemnasium-python`\n         - same pattern as above, using `gemnasium-python` as the image name.\n\n   - Special permissions are needed to execute the pipeline. Please see [Permissions required for running a release pipeline](#permissions-required-for-running-a-release-pipeline) for more details about the required permissions.\n\n### Permissions required for running a release pipeline\n\nBecause the `git tag pipeline` described in the [Release Process](#release-process) section above is run by the `gl-service-dev-secure-analyzers-automation` service account, it needs special permissions to:\n\n- `Run CI/CD pipeline for a protected branch`\n\n   This requires the `Allowed to merge` permission for the `master` branch in [`Settings -\u003e Repository -\u003e Protected branches`](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/settings/repository) for `gemnasium`:\n\n   \u003cimg src=\"docs/images/gemnasium-protected-branches-permissions.png\" width=\"50%\" height=\"50%\" /\u003e\n\n   See [GitLab CI/CD permissions](https://docs.gitlab.com/ee/user/permissions.html#gitlab-cicd-permissions) for more details.\n\n- `Create release for project`\n\n   This requires the `Allowed to create` permission in [`Settings -\u003e Repository -\u003e Protected tags`](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/settings/repository) for `gemnasium`:\n\n   \u003cimg src=\"docs/images/gemnasium-protected-tags-permissions.png\" width=\"50%\" height=\"50%\" /\u003e\n\n   See [Project members permissions](https://docs.gitlab.com/ee/user/permissions.html#project-members-permissions) for more details.\n\n- `trigger downstream QA jobs`\n\n    In order to trigger the downstream QA jobs, the `GITLAB_TOKEN` variable for the [gitlab-org/security-products/analyzers](https://gitlab.com/groups/gitlab-org/security-products/analyzers/-/settings/ci_cd) group must be set to the Personal Access Token for the `gl-service-dev-secure-analyzers-automation` service account, a member of the `gitlab-org/security-products` group.\n\n    `gemnasium` inherits this `GITLAB_TOKEN` value as a group variable, so as long as it's set correctly for the `gitlab-org/security-products/analyzers` group, then there's no need to configure it explicitly as a [CI/CD project variable](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/settings/ci_cd).\n\n    **NOTE:** The `GITLAB_TOKEN` has an expiration date. In order to prevent these pipelines from breaking, we need to ensure that the `GITLAB_TOKEN` is rotated before it expires. See [Token rotation](https://docs.gitlab.com/ee/development/sec/analyzer_development_guide.html#token-rotation-for-service-account) for more details.\n\n### Permissions required for running downstream QA jobs in a release pipeline\n\nIn addition to the permissions listed in the [Permissions required for running a release pipeline](#permissions-required-for-running-a-release-pipeline) section above, the `gl-service-dev-secure-analyzers-automation` service account must also have the `Allowed to merge` permission in `Settings -\u003e Repository -\u003e Protected branches` for the given `Protected Branch` values in the following `Downstream QA Jobs`:\n\nFor example:\n\n\u003cimg src=\"docs/images/js-npm-protected-branches-permissions.png\" width=\"50%\" height=\"50%\" /\u003e\n\nThese same settings must be configured for the rest of the `Protected Branches` below.\n\n\u003ctable\u003e\n  \u003cthead\u003e\n    \u003ctr\u003e\n      \u003cth\u003eAnalyzer\u003c/th\u003e\n      \u003cth\u003eDownstream QA Job\u003c/th\u003e\n      \u003cth\u003eProtected Branch\u003c/th\u003e\n      \u003cth\u003eTriggered by\u003c/th\u003e\n    \u003c/tr\u003e\n  \u003c/thead\u003e\n  \u003ctbody\u003e\n    \u003ctr\u003e\n      \u003ctd rowspan=\"3\"\u003e\u003ccode\u003egemnasium\u003c/code\u003e\u003c/td\u003e\n      \u003ctd rowspan=\"2\"\u003e[js-npm](https://gitlab.com/gitlab-org/security-products/tests/js-npm/-/settings/repository)\u003c/td\u003e\n      \u003ctd\u003e\u003ccode\u003emaster\u003c/code\u003e\u003c/td\u003e\n      \u003ctd\u003e\n        \u003cul\u003e\n          \u003cli\u003e\n            [js-npm-qa](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/blob/2200bfdd/.gitlab/ci/gemnasium.gitlab-ci.yml#L32-38)\n          \u003c/li\u003e\n          \u003cli\u003e\n            [js-npm-qa fips](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/blob/2200bfdd/.gitlab/ci/gemnasium.gitlab-ci.yml#L40-43)\n          \u003c/li\u003e\n        \u003c/ul\u003e\n      \u003c/td\u003e\n    \u003c/tr\u003e\n    \u003ctr\u003e\n      \u003ctd\u003e\u003ccode\u003e*-FREEZE\u003c/code\u003e\u003c/td\u003e\n      \u003ctd\u003e\n        \u003cul\u003e\n          \u003cli\u003e\n            [js-npm-offline-qa](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/blob/d3c99b11/.gitlab/ci/gemnasium.gitlab-ci.yml#L31-37)\n          \u003c/li\u003e\n          \u003cli\u003e\n            [js-npm-offline-qa fips](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/blob/d3c99b11/.gitlab/ci/gemnasium.gitlab-ci.yml#L39-42)\n          \u003c/li\u003e\n        \u003c/ul\u003e\n      \u003c/td\u003e\n    \u003c/tr\u003e\n    \u003ctr\u003e\n      \u003ctd\u003e[js-yarn](https://gitlab.com/gitlab-org/security-products/tests/js-yarn/-/settings/repository)\u003c/td\u003e\n      \u003ctd\u003e\u003ccode\u003eds-remediate-top-level\u003c/code\u003e\u003c/td\u003e\n      \u003ctd\u003e[js-yarn-ds-remediate-top-level-qa](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/blob/d3c99b11/.gitlab/ci/gemnasium.gitlab-ci.yml#L47-54)\u003c/td\u003e\n    \u003c/tr\u003e\n    \u003ctr\u003e\n      \u003ctd rowspan=\"3\"\u003e\u003ccode\u003egemnasium-python\u003c/code\u003e\u003c/td\u003e\n      \u003ctd\u003e[python-pip](https://gitlab.com/gitlab-org/security-products/tests/python-pip/-/settings/repository)\u003c/td\u003e\n      \u003ctd\u003e\u003ccode\u003emaster\u003c/code\u003e\u003c/td\u003e\n      \u003ctd\u003e\n        \u003cul\u003e\n          \u003cli\u003e\n            [python-pip-qa](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/blob/2200bfdd/.gitlab/ci/gemnasium-python.gitlab-ci.yml#L119-125)\n          \u003c/li\u003e\n          \u003cli\u003e\n            [python-pip-qa fips](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/blob/2200bfdd/.gitlab/ci/gemnasium-python.gitlab-ci.yml#L127-130)\n          \u003c/li\u003e\n        \u003c/ul\u003e\n      \u003c/td\u003e\n    \u003c/tr\u003e\n    \u003ctr\u003e\n      \u003ctd rowspan=\"2\"\u003e[python-pipenv](https://gitlab.com/gitlab-org/security-products/tests/python-pipenv/-/settings/repository)\u003c/td\u003e\n      \u003ctd\u003e\u003ccode\u003emaster\u003c/code\u003e\u003c/td\u003e\n      \u003ctd\u003e\n        \u003cul\u003e\n          \u003cli\u003e\n            [python-pipenv-qa](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/blob/2200bfdd/.gitlab/ci/gemnasium-python.gitlab-ci.yml#L94-101)\n          \u003c/li\u003e\n          \u003cli\u003e\n            [python-pipenv-qa fips](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/blob/2200bfdd/.gitlab/ci/gemnasium-python.gitlab-ci.yml#L103-106)\n          \u003c/li\u003e\n        \u003c/ul\u003e\n      \u003c/td\u003e\n    \u003c/tr\u003e\n    \u003ctr\u003e\n      \u003ctd\u003e\u003ccode\u003e*-FREEZE\u003c/code\u003e\u003c/td\u003e\n      \u003ctd\u003e[python-pipenv-offline-qa](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/blob/2200bfdd/.gitlab/ci/gemnasium-python.gitlab-ci.yml#L108-115)\u003c/td\u003e\n    \u003c/tr\u003e\n    \u003ctr\u003e\n      \u003ctd rowspan=\"3\"\u003e\u003ccode\u003egemnasium-maven\u003c/code\u003e\u003c/td\u003e\n      \u003ctd\u003e[java-gradle](https://gitlab.com/gitlab-org/security-products/tests/java-gradle/-/settings/repository)\u003c/td\u003e\n      \u003ctd\u003e\u003ccode\u003emaster\u003c/code\u003e\u003c/td\u003e\n      \u003ctd\u003e[java-gradle-qa](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/blob/2200bfdd/.gitlab/ci/gemnasium-maven.gitlab-ci.yml#L90-98)\u003c/td\u003e\n    \u003c/tr\u003e\n    \u003ctr\u003e\n      \u003ctd\u003e[java-maven](https://gitlab.com/gitlab-org/security-products/tests/java-maven/-/settings/repository)\u003c/td\u003e\n      \u003ctd\u003e\u003ccode\u003e*-FREEZE\u003c/code\u003e\u003c/td\u003e\n      \u003ctd\u003e[java-maven-offline-qa](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/blob/2200bfdd/.gitlab/ci/gemnasium-maven.gitlab-ci.yml#L74-81)\u003c/td\u003e\n    \u003c/tr\u003e\n    \u003ctr\u003e\n      \u003ctd\u003e[scala-sbt](https://gitlab.com/gitlab-org/security-products/tests/scala-sbt/-/settings/repository)\u003c/td\u003e\n      \u003ctd\u003e\u003ccode\u003e*-FREEZE\u003c/code\u003e\u003c/td\u003e\n      \u003ctd\u003e\n        \u003cul\u003e\n          \u003cli\u003e\n            [scala-sbt-offline-qa](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/blob/2200bfdd/.gitlab/ci/gemnasium-maven.gitlab-ci.yml#L100-109)\n          \u003c/li\u003e\n          \u003cli\u003e\n            [scala-sbt-java-21-offline-qa](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/blob/2200bfdd/.gitlab/ci/gemnasium-maven.gitlab-ci.yml#L111-121)\n          \u003c/li\u003e\n        \u003c/ul\u003e\n      \u003c/td\u003e\n    \u003c/tr\u003e\n    \u003ctr\u003e\n      \u003ctd\u003eall \u003ccode\u003egemnasium\u003c/code\u003e analyzers\u003c/td\u003e\n      \u003ctd\u003e[custom-ca](https://gitlab.com/gitlab-org/security-products/tests/custom-ca/-/settings/repository)\u003c/td\u003e\n      \u003ctd\u003e\u003ccode\u003emaster\u003c/code\u003e\u003c/td\u003e\n      \u003ctd\u003e[test-custom-ca-bundle](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/blob/2200bfdd/.gitlab/ci/image.gitlab-ci.yml#L85-90)\u003c/td\u003e\n    \u003c/tr\u003e\n  \u003c/tbody\u003e\n\u003c/table\u003e\n\nFor more details on the required permissions, please see the following issues:\n\n   - https://gitlab.com/gitlab-org/gitlab/-/issues/374032\n   - https://gitlab.com/gitlab-org/gitlab/-/issues/396973\n\n### Manually triggering a failed release\n\nIf the release process doesn't work for some reason, for example, the permissions are incorrect which causes the tag to be created, but the Docker images for the analyzer are not pushed, you can manually release an existing version of the analyzer doing one of the following:\n\n- Manually run the [Republish images](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/pipeline_schedules) scheduled job.\n- Run a `master` pipeline in `gemnasium` and set the `PUBLISH_IMAGES` variable to \"true\".\n\n## Backports\n\nWe target the last two major releases when backporting bug fixes. For example, if we're on `v4` we should merge bug fixes into the `master` and `v3` branches. In this example, the `master` branch holds all code used in `v4.x.x` releases, and `v3` is used by us to backport fixes for customers that have not yet upgraded to the latest GitLab major milestone, e.g. 16.0.\n\n## Disabling the danger-review job\n\nSometimes the `ci-templates` [danger-review](https://gitlab.com/gitlab-org/security-products/ci-templates/blob/a784f5d/includes-dev/go.yml#L70-93) job fails because we need to manually edit the changelog to fix an incorrect entry, which disagrees with the `danger-review` logic, for example [here](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/merge_requests/920#note_2270918660).\n\nTo disable the `danger-review` job, add the ~\"danger-disabled\" label to your MR and run a new [merge request pipelines](https://docs.gitlab.com/ee/ci/pipelines/merge_request_pipelines.html) by viewing the `pipelines` tab of your MR and clicking the `Run pipeline` button.\n\n## Contributing\n\nContributions are welcome, see [`CONTRIBUTING.md`](CONTRIBUTING.md) for more details.\n\n## Troubleshooting\n\n### Unable to build image\n\nIf you encounter the error message `Unknown machine architecture: aarch64` while attempting to build a `gemnasium` analyzer Docker image locally, this is due to the fact that we currently only support building on an `amd64` architecture, such as an Intel Mac. Other architectures, such as the `ARM` Apple Silicon M1 chip, are not currently supported. See [Unable to build gemnasium-maven on non-amd64 machines](https://gitlab.com/gitlab-org/gitlab/-/issues/378669) for more information.\n\n### Check image size failing\n\nGemnasium pipelines have check image size to ensure that the size of the produced image are under control. These jobs are allowed to fail. You can change the maximum allowed image size by searching for `MAX_IMAGE_SIZE_MB`.\n\n## License\n\nThis code is distributed under the The GitLab Enterprise Edition (EE) license, see the [LICENSE](LICENSE) file.\n\n[common library]: https://gitlab.com/gitlab-org/security-products/analyzers/common\n[vulnerability database]: https://gitlab.com/gitlab-org/security-products/gemnasium-db\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/gitlab.com%2Fgitlab-org%2Fsecurity-products%2Fanalyzers%2Fgemnasium","html_url":"https://awesome.ecosyste.ms/projects/gitlab.com%2Fgitlab-org%2Fsecurity-products%2Fanalyzers%2Fgemnasium","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/gitlab.com%2Fgitlab-org%2Fsecurity-products%2Fanalyzers%2Fgemnasium/lists"}