README.md 7.06 KB
Newer Older
Gilbert Roulot's avatar
Gilbert Roulot committed
1 2
# GitLab License Management

Gilbert Roulot's avatar
Gilbert Roulot committed
3 4
[![pipeline status](https://gitlab.com/gitlab-org/security-products/license-management/badges/master/pipeline.svg)](https://gitlab.com/gitlab-org/security-products/license-management/commits/master)
[![coverage report](https://gitlab.com/gitlab-org/security-products/license-management/badges/master/coverage.svg)](https://gitlab.com/gitlab-org/security-products/license-management/commits/master)
Gilbert Roulot's avatar
Gilbert Roulot committed
5 6

GitLab tool for detecting licenses of the dependencies used by the provided source.
7
It is currently based on [License Finder][license_finder]
8
only, but this may change in the future.
Gilbert Roulot's avatar
Gilbert Roulot committed
9 10 11 12 13 14 15 16 17

## How to use

1. `cd` into the directory of the source code you want to scan
1. Run the Docker image:

    ```sh
    docker run \
      --volume "$PWD":/code \
Gilbert Roulot's avatar
Gilbert Roulot committed
18 19
      --rm \
      registry.gitlab.com/gitlab-org/security-products/license-management:latest analyze /code
Gilbert Roulot's avatar
Gilbert Roulot committed
20 21
    ```

22
1. The results will be stored in the `gl-license-management-report.json` file in the application directory.
Gilbert Roulot's avatar
Gilbert Roulot committed
23

Gilbert Roulot's avatar
Gilbert Roulot committed
24 25 26 27
## Development

### Running the application

28
License Management is a Docker image. You can build it like this from the project root:
Gilbert Roulot's avatar
Gilbert Roulot committed
29 30

```sh
31
$ ./bin/docker-build
Gilbert Roulot's avatar
Gilbert Roulot committed
32 33 34 35 36
```

You can then run License Management on some target directory:

```sh
37
$ docker run --rm --volume "/path/to/my/project":/code license-management analyze /code
Gilbert Roulot's avatar
Gilbert Roulot committed
38 39
```

mo's avatar
mo committed
40 41
### Running the tests

42
You can run the tests from inside a docker container:
Gilbert Roulot's avatar
Gilbert Roulot committed
43 44

```sh
45 46
$ ./bin/docker-build
$ ./bin/docker-shell
47
$ ./bin/setup
48
$ ./bin/test
49 50 51 52 53 54
```

If you need to debug any specific issues you can do this from within the docker container by
following these steps:

```sh
55 56 57 58
$ ./bin/docker-build
$ ./bin/docker-shell
$ enable_dev_mode
$ bundle open license_finder
59 60
```

61
The `docker-shell` script will mount the current project as a volume into `/builds/gitlab-org/security-products/license-management`.
62 63
This allows you to edit code from your host machine using your preferred editor and
see the affect of those changes from within the running docker container.
mo's avatar
mo committed
64

mo's avatar
mo committed
65 66 67 68 69 70
### Updating the SPDX index

We will need to periodically update the SPDX index. This can be achieved with
the following command.

```bash
71
$ ./bin/update-spdx
mo's avatar
mo committed
72 73
```

Gilbert Roulot's avatar
Gilbert Roulot committed
74 75 76 77 78 79
## Supported languages and package managers

The following table shows which languages and package managers are supported.

| Language   | Package managers                                                  |
|------------|-------------------------------------------------------------------|
mo's avatar
mo committed
80
| .NET       | [.NET Core CLI][dotnet_core], [Nuget][nuget]                      |
mo's avatar
mo committed
81
| C/C++      | [Conan][conan]                                                    |
mo's avatar
mo committed
82 83 84 85 86 87
| Go         | [Go modules][gomod], [Godep][godep], go get                       |
| Java       | [Gradle][gradle], [Maven][maven]                                  |
| JavaScript | [npm][npm], [yarn][yarn], [Bower][bower]                          |
| PHP        | [composer][composer]                                              |
| Python     | [pip][pip], [pipenv][pipenv]                                      |
| Ruby       | [Bundler][bundler]                                                |
Gilbert Roulot's avatar
Gilbert Roulot committed
88

89 90 91
Inject `SETUP_CMD` to the docker command to override the given package managers
and run your custom command to setup your environment with a custom package manager.

92 93 94 95 96 97 98
```sh
docker run \
  --volume "$PWD":/code \
  --env "SETUP_CMD=./my-custom-install-script.sh" \
  --rm \
  registry.gitlab.com/gitlab-org/security-products/license-management:latest analyze /code
```
99

100 101
## Settings

Can Eldem's avatar
Can Eldem committed
102
The License Management tool can be customized with environments variables for some project types.
103 104 105

| Environment variable | Project type | Function |
|----------------------|--------------|----------|
mo's avatar
mo committed
106
| ADDITIONAL_CA_CERT_BUNDLE | * | Additional certificate chain to install in the trusted store. |
107
| MAVEN_CLI_OPTS       | Java (Maven) | Additional arguments for the mvn executable. If not supplied, defaults to `-DskipTests`. |
108
| LICENSE_FINDER_CLI_OPTS | * | Additional arguments for the `license_finder` executable. |
109 110
| LM_JAVA_VERSION      | Java (Maven) | Version of Java. If set to `11`, Maven and Gradle use Java 11 instead of Java 8. |
| LM_PYTHON_VERSION    | Python       | Version of Python. If set to `3`, dependencies are installed using Python 3 instead of Python 2.7. |
mo's avatar
mo committed
111
| LOG_LEVEL    | * | Control the verbosity of the logs. (`debug`, `info`, `warn` (default), `error`, `fatal`)  |
112
| LM_REPORT_FILE    | * | Name of the generated report. If not supplied, defaults to `gl-license-scanning-report.json`  |
113 114 115 116 117


Inject the required environment variables to the docker command using the [`--env` option flag](https://docs.docker.com/engine/reference/commandline/run/#set-environment-variables--e---env---env-file)
or its shorthand form (`--env MY_SETTING_VAR`) if the configuration comes from an external environment.

Gilbert Roulot's avatar
Gilbert Roulot committed
118 119 120 121
## Versioning and release process

Please check the [Release Process documentation](https://gitlab.com/gitlab-org/security-products/release/blob/master/docs/release_process.md).

mo's avatar
mo committed
122 123
## Upgrading to the latest version of LicenseFinder

124 125
1. Check for the latest version of `LicenseFinder` at [https://rubygems.org/gems/license_finder][license_finder]
1. Check the version of the `license_finder` gem that is currently being used in the [`Gemfile.lock`][gemfile_lock]
mo's avatar
mo committed
126
1. If an update is available, create a new branch
127 128
1. Bump the license management version in [CHANGELOG.md][changelog] and in [version.rb][version_rb]
1. Update the `license_finder` version constraint in the [gemspec][gemspec]
mo's avatar
mo committed
129
1. Run `bundle update license_finder`
mo's avatar
mo committed
130
1. Test the changes by following the instructions for [running the tests](#running-the-tests)
mo's avatar
mo committed
131 132
1. Submit a merge request.

Gilbert Roulot's avatar
Gilbert Roulot committed
133 134 135
# Contributing

If you want to help, read the [contribution guidelines](CONTRIBUTING.md).
136 137

If an unknown license is detected, please consider updating the mapping defined
Matt Selsky's avatar
Matt Selsky committed
138
in [normalized-licenses.yml](https://gitlab.com/gitlab-org/security-products/license-management/blob/master/normalized-licenses.yml). A mapping can be for a detected name or url and must correspond to an SPDX identifier found in [spdx-licenses.json](https://gitlab.com/gitlab-org/security-products/license-management/blob/master/spdx-licenses.json).
139

mo's avatar
mo committed
140
[bower]: https://bower.io/
mo's avatar
mo committed
141
[bundler]: https://bundler.io/
142
[changelog]: https://gitlab.com/gitlab-org/security-products/license-management/-/blob/master/CHANGELOG.md
mo's avatar
mo committed
143 144 145
[composer]: https://getcomposer.org
[conan]: https://conan.io/
[dotnet_core]: https://docs.microsoft.com/en-us/dotnet/core/tools/
146
[gemfile_lock]: https://gitlab.com/gitlab-org/security-products/license-management/-/blob/master/Gemfile.lock
mo's avatar
mo committed
147 148
[gemspec]: https://gitlab.com/gitlab-org/security-products/license-management/-/blob/master/license-management.gemspec
[godep]: https://github.com/tools/godep
mo's avatar
mo committed
149
[gomod]: https://github.com/golang/go/wiki/Modules
mo's avatar
mo committed
150
[gradle]: https://gradle.org/
mo's avatar
mo committed
151
[license_finder]: https://rubygems.org/gems/license_finder
mo's avatar
mo committed
152
[maven]: https://maven.apache.org/
mo's avatar
mo committed
153
[npm]: https://www.npmjs.com/
mo's avatar
mo committed
154 155 156
[nuget]: https://www.nuget.org/
[pip]: https://pip.pypa.io/en/stable/
[pipenv]: https://github.com/pypa/pipenv
mo's avatar
mo committed
157 158
[version_rb]: https://gitlab.com/gitlab-org/security-products/license-management/-/blob/master/lib/license/management/version.rb
[yarn]: https://yarnpkg.com/