diff options
Diffstat (limited to 'doc/user/compliance/license_compliance/index.md')
| -rw-r--r-- | doc/user/compliance/license_compliance/index.md | 183 |
1 files changed, 136 insertions, 47 deletions
diff --git a/doc/user/compliance/license_compliance/index.md b/doc/user/compliance/license_compliance/index.md index 2e771a17163..cbabed00283 100644 --- a/doc/user/compliance/license_compliance/index.md +++ b/doc/user/compliance/license_compliance/index.md @@ -30,12 +30,20 @@ will be displayed in the merge request area. That is the case when you add the Consecutive merge requests will have something to compare to and the license compliance report will be shown properly. - + If you are a project or group Maintainer, you can click on a license to be given the choice to allow it or deny it. - + + +When GitLab detects a **Denied** license, you can view it in the [license list](#license-list). + + + +You can view and modify existing policies from the [policies](#policies) tab. + + ## Use cases @@ -49,19 +57,30 @@ The following languages and package managers are supported. | Language | Package managers | Scan Tool | |------------|-------------------------------------------------------------------|----------------------------------------------------------| -| JavaScript | [Bower](https://bower.io/), [npm](https://www.npmjs.com/), [yarn](https://yarnpkg.com/) ([experimental support](https://github.com/pivotal/LicenseFinder#experimental-project-types)) |[License Finder](https://github.com/pivotal/LicenseFinder)| -| Go | [Godep](https://github.com/tools/godep), go get ([experimental support](https://github.com/pivotal/LicenseFinder#experimental-project-types)), gvt ([experimental support](https://github.com/pivotal/LicenseFinder#experimental-project-types)), glide ([experimental support](https://github.com/pivotal/LicenseFinder#experimental-project-types)), dep ([experimental support](https://github.com/pivotal/LicenseFinder#experimental-project-types)), trash ([experimental support](https://github.com/pivotal/LicenseFinder#experimental-project-types)) and govendor ([experimental support](https://github.com/pivotal/LicenseFinder#experimental-project-types)), [go mod](https://github.com/golang/go/wiki/Modules) ([experimental support](https://github.com/pivotal/LicenseFinder#experimental-project-types)) |[License Finder](https://github.com/pivotal/LicenseFinder)| +| JavaScript | [Bower](https://bower.io/), [npm](https://www.npmjs.com/) |[License Finder](https://github.com/pivotal/LicenseFinder)| +| Go | [Godep](https://github.com/tools/godep), [go mod](https://github.com/golang/go/wiki/Modules) |[License Finder](https://github.com/pivotal/LicenseFinder)| | Java | [Gradle](https://gradle.org/), [Maven](https://maven.apache.org/) |[License Finder](https://github.com/pivotal/LicenseFinder)| -| .NET | [Nuget](https://www.nuget.org/) (.NET Framework is supported via the [mono project](https://www.mono-project.com/). Windows specific dependencies are not supported at this time.) |[License Finder](https://github.com/pivotal/LicenseFinder)| +| .NET | [Nuget](https://www.nuget.org/) (.NET Framework is supported via the [mono project](https://www.mono-project.com/). Windows specific dependencies are not supported at this time.) |[License Finder](https://github.com/pivotal/LicenseFinder)| | Python | [pip](https://pip.pypa.io/en/stable/) (Python is supported through [requirements.txt](https://pip.readthedocs.io/en/1.1/requirements.html) and [Pipfile.lock](https://github.com/pypa/pipfile#pipfilelock).) |[License Finder](https://github.com/pivotal/LicenseFinder)| -| Ruby | [gem](https://rubygems.org/) |[License Finder](https://github.com/pivotal/LicenseFinder)| -| Erlang | [rebar](https://www.rebar3.org/) ([experimental support](https://github.com/pivotal/LicenseFinder#experimental-project-types))|[License Finder](https://github.com/pivotal/LicenseFinder)| -| Objective-C, Swift | [Carthage](https://github.com/Carthage/Carthage) , [CocoaPods v0.39 and below](https://cocoapods.org/) ([experimental support](https://github.com/pivotal/LicenseFinder#experimental-project-types)) |[License Finder](https://github.com/pivotal/LicenseFinder)| -| Elixir | [mix](https://elixir-lang.org/getting-started/mix-otp/introduction-to-mix.html) ([experimental support](https://github.com/pivotal/LicenseFinder#experimental-project-types)) |[License Finder](https://github.com/pivotal/LicenseFinder)| -| C++/C | [conan](https://conan.io/) ([experimental support](https://github.com/pivotal/LicenseFinder#experimental-project-types))|[License Finder](https://github.com/pivotal/LicenseFinder)| -| Scala | [sbt](https://www.scala-sbt.org/) ([experimental support](https://github.com/pivotal/LicenseFinder#experimental-project-types))|[License Finder](https://github.com/pivotal/LicenseFinder)| -| Rust | [cargo](https://crates.io/) ([experimental support](https://github.com/pivotal/LicenseFinder#experimental-project-types))|[License Finder](https://github.com/pivotal/LicenseFinder)| -| PHP | [composer](https://getcomposer.org/) ([experimental support](https://github.com/pivotal/LicenseFinder#experimental-project-types))|[License Finder](https://github.com/pivotal/LicenseFinder)| +| Ruby | [gem](https://rubygems.org/) |[License Finder](https://github.com/pivotal/LicenseFinder)| +| Objective-C, Swift | [Carthage](https://github.com/Carthage/Carthage) |[License Finder](https://github.com/pivotal/LicenseFinder)| + +### Experimental support + +The following languages and package managers are [supported experimentally](https://github.com/pivotal/LicenseFinder#experimental-project-types), +which means that the reported licenses might be incomplete or inaccurate. + +| Language | Package managers | Scan Tool | +|------------|-------------------------------------------------------------------|----------------------------------------------------------| +| JavaScript | [yarn](https://yarnpkg.com/)|[License Finder](https://github.com/pivotal/LicenseFinder)| +| Go | go get, gvt, glide, dep, trash, govendor |[License Finder](https://github.com/pivotal/LicenseFinder)| +| Erlang | [rebar](https://www.rebar3.org/) |[License Finder](https://github.com/pivotal/LicenseFinder)| +| Objective-C, Swift | [CocoaPods](https://cocoapods.org/) v0.39 and below |[License Finder](https://github.com/pivotal/LicenseFinder)| +| Elixir | [mix](https://elixir-lang.org/getting-started/mix-otp/introduction-to-mix.html) |[License Finder](https://github.com/pivotal/LicenseFinder)| +| C++/C | [conan](https://conan.io/) |[License Finder](https://github.com/pivotal/LicenseFinder)| +| Scala | [sbt](https://www.scala-sbt.org/) |[License Finder](https://github.com/pivotal/LicenseFinder)| +| Rust | [cargo](https://crates.io/) |[License Finder](https://github.com/pivotal/LicenseFinder)| +| PHP | [composer](https://getcomposer.org/) |[License Finder](https://github.com/pivotal/LicenseFinder)| ## Requirements @@ -81,7 +100,7 @@ For GitLab versions earlier than 11.9, you can copy and use the job as defined that template. NOTE: **Note:** -In GitLab 13.0, the `License-Management.gitlab-ci.yml` template is scheduled to be removed. +GitLab 13.0 removes the `License-Management.gitlab-ci.yml` template. Use `License-Scanning.gitlab-ci.yml` instead. Add the following to your `.gitlab-ci.yml` file: @@ -96,12 +115,12 @@ and scan your dependencies to find their licenses. NOTE: **Note:** Before GitLab 12.8, the `license_scanning` job was named `license_management`. -In GitLab 13.0, the `license_management` job is scheduled to be removed completely, +GitLab 13.0 removes the `license_management` job, so you're advised to migrate to the `license_scanning` job and used the new `License-Scanning.gitlab-ci.yml` template. The results will be saved as a -[License Compliance report artifact](../../../ci/yaml/README.md#artifactsreportslicense_scanning-ultimate) +[License Compliance report artifact](../../../ci/pipelines/job_artifacts.md#artifactsreportslicense_scanning-ultimate) that you can later download and analyze. Due to implementation limitations, we always take the latest License Compliance artifact available. Behind the scenes, the [GitLab License Compliance Docker image](https://gitlab.com/gitlab-org/security-products/license-management) @@ -114,15 +133,17 @@ The License Compliance settings can be changed through [environment variables](# License Compliance can be configured using environment variables. -| Environment variable | Required | Description | -|-----------------------|----------|-------------| -| `MAVEN_CLI_OPTS` | no | Additional arguments for the mvn executable. If not supplied, defaults to `-DskipTests`. | -| `LICENSE_FINDER_CLI_OPTS` | no | Additional arguments for the `license_finder` executable. For example, if your project has both Golang and Ruby code stored in different directories and you want to only scan the Ruby code, you can update your `.gitlab-ci-yml` template to specify which project directories to scan, like `LICENSE_FINDER_CLI_OPTS: '--debug --aggregate-paths=. ruby'`. | -| `LM_JAVA_VERSION` | no | Version of Java. If set to `11`, Maven and Gradle use Java 11 instead of Java 8. | -| `LM_PYTHON_VERSION` | no | Version of Python. If set to `3`, dependencies are installed using Python 3 instead of Python 2.7. | -| `SETUP_CMD` | no | Custom setup for the dependency installation. (experimental) | -| `PIP_INDEX_URL` | no | Base URL of Python Package Index (default: `https://pypi.org/simple/`). | -| `ADDITIONAL_CA_CERT_BUNDLE` | no | Bundle of trusted CA certificates (currently supported in Python projects). | +| Environment variable | Required | Description | +|-----------------------------|----------|-------------| +| `SECURE_ANALYZERS_PREFIX` | no | Set the Docker registry base address to download the analyzer from. | +| `ADDITIONAL_CA_CERT_BUNDLE` | no | Bundle of trusted CA certificates (currently supported in Pip, Pipenv, Maven, Gradle, Yarn, and NPM projects). | +| `GRADLE_CLI_OPTS` | no | Additional arguments for the gradle executable. If not supplied, defaults to `--exclude-task=test`. | +| `LICENSE_FINDER_CLI_OPTS` | no | Additional arguments for the `license_finder` executable. For example, if your project has both Golang and Ruby code stored in different directories and you want to only scan the Ruby code, you can update your `.gitlab-ci-yml` template to specify which project directories to scan, like `LICENSE_FINDER_CLI_OPTS: '--debug --aggregate-paths=. ruby'`. | +| `LM_JAVA_VERSION` | no | Version of Java. If set to `11`, Maven and Gradle use Java 11 instead of Java 8. | +| `LM_PYTHON_VERSION` | no | Version of Python. If set to `3`, dependencies are installed using Python 3 instead of Python 2.7. | +| `MAVEN_CLI_OPTS` | no | Additional arguments for the mvn executable. If not supplied, defaults to `-DskipTests`. | +| `PIP_INDEX_URL` | no | Base URL of Python Package Index (default: `https://pypi.org/simple/`). | +| `SETUP_CMD` | no | Custom setup for the dependency installation (experimental). | ### Installing custom dependencies @@ -263,21 +284,80 @@ license_scanning: The [`pip.conf`](https://pip.pypa.io/en/stable/reference/pip/) allows you to specify a list of [trusted hosts](https://pip.pypa.io/en/stable/reference/pip/#cmdoption-trusted-host): -```text +```plaintext [global] trusted-host = pypi.example.com ``` +#### Using private Python repos + +If you have a private Python repository you can use the `PIP_INDEX_URL` [environment variable](#available-variables) +to specify its location. It's also possible to provide a custom `pip.conf` for +[additional configuration](#custom-root-certificates-for-python). + +### Configuring NPM projects + +You can configure NPM projects by using an [`.npmrc`](https://docs.npmjs.com/configuring-npm/npmrc.html) +file. + +#### Using private NPM registries + +If you have a private NPM registry you can use the +[`registry`](https://docs.npmjs.com/using-npm/config#registry) +setting to specify its location. + +For example: + +```plaintext +registry = https://npm.example.com +``` + +#### Custom root certificates for NPM + +You can supply a custom root certificate to complete TLS verification by using the +`ADDITIONAL_CA_CERT_BUNDLE` [environment variable](#available-variables). + +To disable TLS verification you can provide the [`strict-ssl`](https://docs.npmjs.com/using-npm/config#strict-ssl) +setting. + +For example: + +```plaintext +strict-ssl = false +``` + +### Configuring Yarn projects + +You can configure Yarn projects by using a [`.yarnrc.yml`](https://yarnpkg.com/configuration/yarnrc) +file. + +#### Using private Yarn registries + +If you have a private Yarn registry you can use the +[`npmRegistryServer`](https://yarnpkg.com/configuration/yarnrc#npmRegistryServer) +setting to specify its location. + +For example: + +```text +npmRegistryServer: "https://npm.example.com" +``` + +#### Custom root certificates for Yarn + +You can supply a custom root certificate to complete TLS verification by using the +`ADDITIONAL_CA_CERT_BUNDLE` [environment variable](#available-variables). + ### Migration from `license_management` to `license_scanning` In GitLab 12.8 a new name for `license_management` job was introduced. This change was made to improve clarity around the purpose of the scan, which is to scan and collect the types of licenses present in a projects dependencies. -The support of `license_management` is scheduled to be dropped in GitLab 13.0. +GitLab 13.0 drops support for `license_management`. If you're using a custom setup for License Compliance, you're required to update your CI config accordingly: 1. Change the CI template to `License-Scanning.gitlab-ci.yml`. 1. Change the job name to `license_scanning` (if you mention it in `.gitlab-ci.yml`). -1. Change the artifact name to `gl-license-scanning-report.json` (if you mention it in `.gitlab-ci.yml`). +1. Change the artifact name to `license_scanning`, and the file name to `gl-license-scanning-report.json` (if you mention it in `.gitlab-ci.yml`). For example, the following `.gitlab-ci.yml`: @@ -303,11 +383,21 @@ license_scanning: license_scanning: gl-license-scanning-report.json ``` +If you use the `license_management` artifact in GitLab 13.0 or later, the License Compliance job generates this error: + +```plaintext +WARNING: Uploading artifacts to coordinator... failed id=:id responseStatus=400 Bad Request status=400 Bad Request token=:sha + +FATAL: invalid_argument +``` + +If you encounter this error, follow the instructions described in this section. + ## Running License Compliance in an offline environment For self-managed GitLab instances in an environment with limited, restricted, or intermittent access to external resources through the internet, some adjustments are required for the License Compliance job to -successfully run. +successfully run. For more information, see [Offline environments](../../application_security/offline_deployments/index.md). ### Requirements for offline License Compliance @@ -318,11 +408,11 @@ To use License Compliance in an offline environment, you need: NOTE: **Note:** GitLab Runner has a [default `pull policy` of `always`](https://docs.gitlab.com/runner/executors/docker.html#using-the-always-pull-policy), -meaning the runner will try to pull Docker images from the GitLab container registry even if a local +meaning the Runner tries to pull Docker images from the GitLab container registry even if a local copy is available. GitLab Runner's [`pull_policy` can be set to `if-not-present`](https://docs.gitlab.com/runner/executors/docker.html#using-the-if-not-present-pull-policy) in an offline environment if you prefer using only locally available Docker images. However, we -recommend leaving the pull policy set to `always`, as it better enables updated scanners to be used -within your CI/CD pipelines. +recommend keeping the pull policy setting to `always` if not in an offline environment, as this +enables the use of updated scanners in your CI/CD pipelines. ### Make GitLab License Compliance analyzer images available inside your Docker registry @@ -345,10 +435,8 @@ For details on saving and transporting Docker images as a file, see Docker's doc ### Set License Compliance CI job variables to use local License Compliance analyzers -Override License Compliance environment variables to use to your local container registry -as the source for License Compliance analyzer images. - -For example, this assumes a local Docker registry repository of `localhost:5000/analyzers`: +Add the following configuration to your `.gitlab-ci.yml` file. You must replace `image` to refer to +the License Compliance Docker image hosted on your local Docker container registry: ```yaml include: @@ -362,8 +450,8 @@ license_scanning: The License Compliance job should now use local copies of the License Compliance analyzers to scan your code and generate security reports, without requiring internet access. -Additional [configuration](#using-private-maven-repos) may be needed for connecting to private Maven -repositories. +Additional configuration may be needed for connecting to [private Maven repositories](#using-private-maven-repos), +[private NPM registries](#using-private-npm-registries), [private Yarn registries](#using-private-yarn-registries), and [private Python repositories](#using-private-python-repos). Exact name matches are required for [project policies](#project-policies-for-license-compliance) when running in an offline environment ([see related issue](https://gitlab.com/gitlab-org/gitlab/-/issues/212388)). @@ -384,7 +472,7 @@ To allow or deny a license: **License Compliance** section. 1. Click the **Add a license** button. -  +  1. In the **License name** dropdown, either: - Select one of the available licenses. You can search for licenses in the field @@ -398,23 +486,23 @@ To modify an existing license: 1. In the **License Compliance** list, click the **Allow/Deny** dropdown to change it to the desired status. -  +  Searching for Licenses: 1. Use the **Search** box to search for a specific license. -  +  ## License Compliance report under pipelines > [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/5491) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 11.2. From your project's left sidebar, navigate to **CI/CD > Pipelines** and click on the -pipeline ID that has a `license_management` job to see the Licenses tab with the listed +pipeline ID that has a `license_scanning` job to see the Licenses tab with the listed licenses (if any). - + <!-- ## Troubleshooting @@ -447,8 +535,9 @@ in your project's sidebar, and you'll see the licenses displayed, where: - **Name:** The name of the license. - **Component:** The components which have this license. +- **Policy Violation:** The license has a [license policy](#policies) marked as **Deny**. - + ## Policies @@ -459,9 +548,9 @@ and the associated classifications for each. Policies can be configured by maintainers of the project. - - + + Developers of the project can view the policies configured in a project. - + |