diff options
Diffstat (limited to 'doc/user/compliance/license_compliance/index.md')
| -rw-r--r-- | doc/user/compliance/license_compliance/index.md | 245 |
1 files changed, 234 insertions, 11 deletions
diff --git a/doc/user/compliance/license_compliance/index.md b/doc/user/compliance/license_compliance/index.md index cbabed00283..4ceb393af8c 100644 --- a/doc/user/compliance/license_compliance/index.md +++ b/doc/user/compliance/license_compliance/index.md @@ -1,10 +1,13 @@ --- type: reference, howto +stage: Secure +group: Composition Analysis +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers --- # License Compliance **(ULTIMATE)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/5483) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 11.0. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/5483) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 11.0. ## Overview @@ -61,10 +64,14 @@ The following languages and package managers are supported. | 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)| -| 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)| +| Python | [pip](https://pip.pypa.io/en/stable/) (Python is supported through [requirements.txt](https://pip.pypa.io/en/1.1/requirements/) 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)| | Objective-C, Swift | [Carthage](https://github.com/Carthage/Carthage) |[License Finder](https://github.com/pivotal/LicenseFinder)| +NOTE: **Note:** + +Java 8 and Gradle 1.x projects are not supported. + ### Experimental support The following languages and package managers are [supported experimentally](https://github.com/pivotal/LicenseFinder#experimental-project-types), @@ -135,14 +142,18 @@ License Compliance can be configured using environment variables. | 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). | +| `ASDF_JAVA_VERSION` | no | Version of Java to use for the scan. | +| `ASDF_NODEJS_VERSION` | no | Version of Node.js to use for the scan. | +| `ASDF_PYTHON_VERSION` | no | Version of Python to use for the scan. | +| `ASDF_RUBY_VERSION` | no | Version of Ruby to use for the scan. | | `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/`). | +| `SECURE_ANALYZERS_PREFIX` | no | Set the Docker registry base address to download the analyzer from. | | `SETUP_CMD` | no | Custom setup for the dependency installation (experimental). | ### Installing custom dependencies @@ -242,7 +253,7 @@ generate a key store file, see the ### Selecting the version of Python > - [Introduced](https://gitlab.com/gitlab-org/security-products/license-management/-/merge_requests/36) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 12.0. -> - In [GitLab 12.2](https://gitlab.com/gitlab-org/gitlab/issues/12032), Python 3.5 became the default. +> - In [GitLab 12.2](https://gitlab.com/gitlab-org/gitlab/-/issues/12032), Python 3.5 became the default. > - In [GitLab 12.7](https://gitlab.com/gitlab-org/security-products/license-management/-/merge_requests/101), Python 3.8 became the default. License Compliance uses Python 3.8 and pip 19.1 by default. @@ -328,7 +339,7 @@ strict-ssl = false ### Configuring Yarn projects -You can configure Yarn projects by using a [`.yarnrc.yml`](https://yarnpkg.com/configuration/yarnrc) +You can configure Yarn projects by using a [`.yarnrc.yml`](https://yarnpkg.com/configuration/yarnrc/) file. #### Using private Yarn registries @@ -339,7 +350,7 @@ setting to specify its location. For example: -```text +```plaintext npmRegistryServer: "https://npm.example.com" ``` @@ -348,6 +359,137 @@ npmRegistryServer: "https://npm.example.com" You can supply a custom root certificate to complete TLS verification by using the `ADDITIONAL_CA_CERT_BUNDLE` [environment variable](#available-variables). +### Configuring Bower projects + +You can configure Bower projects by using a [`.bowerrc`](https://bower.io/docs/config/#bowerrc-specification) +file. + +#### Using private Bower registries + +If you have a private Bower registry you can use the +[`registry`](https://bower.io/docs/config/#bowerrc-specification) +setting to specify its location. + +For example: + +```plaintext +{ + "registry": "https://registry.bower.io" +} +``` + +#### Custom root certificates for Bower + +You can supply a custom root certificate to complete TLS verification by using the +`ADDITIONAL_CA_CERT_BUNDLE` [environment variable](#available-variables), or by +specifying a `ca` setting in a [`.bowerrc`](https://bower.io/docs/config/#bowerrc-specification) +file. + +### Configuring Conan projects + +You can configure [Conan](https://conan.io/) projects by adding a `.conan` directory to your +project root. The project root serves as the [`CONAN_USER_HOME`](https://docs.conan.io/en/latest/reference/env_vars.html#conan-user-home). + +Consult the [Conan](https://docs.conan.io/en/latest/reference/config_files/conan.conf.html#conan-conf) +documentation for a list of settings that you can apply. + +The `license_scanning` job runs in a [Debian 10](https://www.debian.org/releases/buster/) Docker +image. The supplied image ships with some build tools such as [CMake](https://cmake.org/) and [GCC](https://gcc.gnu.org/). +However, not all project types are supported by default. To install additional tools needed to +compile dependencies, use a [`before_script`](../../../ci/yaml/README.md#before_script-and-after_script) +to install the necessary build tools using the [`apt`](https://wiki.debian.org/PackageManagementTools) +package manager. For a comprehensive list, consult [the Conan documentation](https://docs.conan.io/en/latest/introduction.html#all-platforms-all-build-systems-and-compilers). + +The default [Conan](https://conan.io/) configuration sets [`CONAN_LOGIN_USERNAME`](https://docs.conan.io/en/latest/reference/env_vars.html#conan-login-username-conan-login-username-remote-name) +to `ci_user`, and binds [`CONAN_PASSWORD`](https://docs.conan.io/en/latest/reference/env_vars.html#conan-password-conan-password-remote-name) +to the [`CI_JOB_TOKEN`](../../../ci/variables/predefined_variables.md) +for the running job. This allows Conan projects to fetch packages from a [GitLab Conan Repository](../../packages/conan_repository/#fetching-conan-package-information-from-the-gitlab-package-registry) +if a GitLab remote is specified in the `.conan/remotes.json` file. + +To override the default credentials specify a [`CONAN_LOGIN_USERNAME_{REMOTE_NAME}`](https://docs.conan.io/en/latest/reference/env_vars.html#conan-login-username-conan-login-username-remote-name) +matching the name of the remote specified in the `.conan/remotes.json` file. + +NOTE: **Note:** +[MSBuild](https://github.com/mono/msbuild#microsoftbuild-msbuild) projects aren't supported. The +`license_scanning` image ships with [Mono](https://www.mono-project.com/) and [MSBuild](https://github.com/mono/msbuild#microsoftbuild-msbuild). +Additional setup may be required to build packages for this project configuration. + +#### Using private Conan registries + +By default, [Conan](https://conan.io/) uses the `conan-center` remote. For example: + +```json +{ + "remotes": [ + { + "name": "conan-center", + "url": "https://conan.bintray.com", + "verify_ssl": true + } + ] +} +``` + +To fetch dependencies from an alternate remote, specify that remote in a `.conan/remotes.json`. For +example: + +```json +{ + "remotes": [ + { + "name": "gitlab", + "url": "https://gitlab.com/api/v4/packages/conan", + "verify_ssl": true + } + ] +} +``` + +If credentials are required to authenticate then you can configure a [protected variable](../../../ci/variables/README.md#protect-a-custom-variable) +following the naming convention described in the [`CONAN_LOGIN_USERNAME` documentation](https://docs.conan.io/en/latest/reference/env_vars.html#conan-login-username-conan-login-username-remote-name). + +#### Custom root certificates for Conan + +You can provide custom certificates by adding a `.conan/cacert.pem` file to the project root and +setting [`CA_CERT_PATH`](https://docs.conan.io/en/latest/reference/env_vars.html#conan-cacert-path) +to `.conan/cacert.pem`. + +If you specify the `ADDITIONAL_CA_CERT_BUNDLE` [environment variable](#available-variables), this +variable's X.509 certificates are installed in the Docker image's default trust store and Conan is +configured to use this as the default `CA_CERT_PATH`. + +### Configuring Go projects + +To configure [Go modules](https://github.com/golang/go/wiki/Modules) +based projects, specify [environment variables](https://golang.org/pkg/cmd/go/#hdr-Environment_variables) +in the `license_scanning` job's [variables](#available-variables) section in `.gitlab-ci.yml`. + +If a project has [vendored](https://golang.org/pkg/cmd/go/#hdr-Vendor_Directories) its modules, +then the combination of the `vendor` directory and `mod.sum` file are used to detect the software +licenses associated with the Go module dependencies. + +#### Using private Go registries + +You can use the [`GOPRIVATE`](https://golang.org/pkg/cmd/go/#hdr-Environment_variables) +and [`GOPROXY`](https://golang.org/pkg/cmd/go/#hdr-Environment_variables) +environment variables to control where modules are sourced from. Alternatively, you can use +[`go mod vendor`](https://golang.org/ref/mod#tmp_28) to vendor a project's modules. + +#### Custom root certificates for Go + +You can specify the [`-insecure`](https://golang.org/pkg/cmd/go/internal/get/) flag by exporting the +[`GOFLAGS`](https://golang.org/cmd/go/#hdr-Environment_variables) +environment variable. For example: + +```yaml +include: + - template: License-Scanning.gitlab-ci.yml + +license_scanning: + variables: + GOFLAGS: '-insecure' +``` + ### 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. @@ -450,15 +592,21 @@ 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 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). +Additional configuration may be needed for connecting to +[private Bower registries](#using-private-bower-registries), +[private Conan registries](#using-private-bower-registries), +[private Go registries](#using-private-go-registries), +[private Maven repositories](#using-private-maven-repos), +[private NPM registries](#using-private-npm-registries), +[private Python repositories](#using-private-python-repos), +and [private Yarn registries](#using-private-yarn-registries). 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)). ## Project policies for License Compliance -> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/5940) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 11.4. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/5940) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 11.4. From the project's settings: @@ -496,7 +644,7 @@ Searching for Licenses: ## License Compliance report under pipelines -> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/5491) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 11.2. +> [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_scanning` job to see the Licenses tab with the listed @@ -518,7 +666,7 @@ but commented out to help encourage others to add to it in the future. --> ## License list -> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/13582) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 12.7. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/13582) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 12.7. The License list allows you to see your project's licenses and key details about them. @@ -554,3 +702,78 @@ Policies can be configured by maintainers of the project. Developers of the project can view the policies configured in a project.  + +## Troubleshooting + +### `ERROR -- : asdf: No preset version installed for command` + +This error occurs when the version of the tools used by your project +do not match the version of the pre-installed tools available in the +`license_scanning` Docker image. The `license_scanning` job uses +[asdf-vm](https://asdf-vm.com/) to activate the appropriate version of +a tool that your project relies on. For example, if your project relies on a specific +version of [Node.js](https://nodejs.org/) or any other supported tool you can +specify the desired version by adding a +[`.tool-versions`](https://asdf-vm.com/#/core-configuration?id=tool-versions) file to the project +or using the appropriate [`ASDF_<tool>_VERSION`](https://asdf-vm.com/#/core-configuration?id=environment-variables) environment variable to +activate the appropriate version. + +For example, the following `.tool-versions` file will activate version `12.16.3` of [Node.js](https://nodejs.org/) +and version `2.6.6` of [Ruby](https://www.ruby-lang.org/). + +```plaintext +nodejs 12.16.3 +ruby 2.6.6 +``` + +The next example shows how to activate the same versions of the tools mentioned above by using environment variables defined in your +project's `.gitlab-ci.yml` file. + +```yaml +include: + - template: License-Scanning.gitlab-ci.yml + +license_scanning: + variables: + ASDF_NODEJS_VERSION: '12.16.3' + ASDF_RUBY_VERSION: '2.6.6' +``` + +A full list of variables can be found in [environment variables](#available-variables). + +To find out what tools are pre-installed in the `license_scanning` Docker image use the following command: + +```shell +$ docker run --entrypoint='' registry.gitlab.com/gitlab-org/security-products/analyzers/license-finder:3 /bin/bash -lc 'asdf list' +golang + 1.14 +gradle + 6.3 +java + adopt-openjdk-11.0.7+10 + adopt-openjdk-8u242-b08 +maven + 3.6.3 +nodejs + 10.20.1 + 12.16.3 +php + 7.4.5 +python + 2.7.18 + 3.8.2 +ruby + 2.6.6 +sbt + 1.3.8 +``` + +To interact with the `license_scanning` runtime environment use the following command: + +```shell +$ docker run -it --entrypoint='' registry.gitlab.com/gitlab-org/security-products/analyzers/license-finder:3 /bin/bash -l +root@6abb70e9f193:~# +``` + +NOTE: **Note:** +Selecting a custom version of [Mono](https://www.mono-project.com/) or [.NET Core](https://dotnet.microsoft.com/download/dotnet-core) is currently not supported. |