1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
|
# GitLab License Management
[](https://gitlab.com/gitlab-org/security-products/license-management/commits/master)
[](https://gitlab.com/gitlab-org/security-products/license-management/commits/master)
GitLab tool for detecting licenses of the dependencies used by the provided source.
It is currently based on [License Finder](https://gitlab.com/gitlab-org/security-products/license-management)
only, but this may change in the future.
## 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 \
--rm \
registry.gitlab.com/gitlab-org/security-products/license-management:latest analyze /code
```
1. The results will be stored in the `gl-license-management-report.json` file in the application directory.
## Development
### Running the application
License Management is a Docker image, you can build it like any Docker image like so in the
project root:
```sh
docker build -t license-management .
```
You can then run License Management on some target directory:
```sh
docker run --rm --volume "/path/to/my/project":/code license-management analyze /code
```
You can run the tests from your host machine using the following command:
```sh
./bin/test
```
It is much more efficient to run the tests from inside the docker container:
```sh
./bin/docker-build
./bin/docker-shell
cd /opt/license-management/
./bin/test
```
If you need to debug any specific issues you can do this from within the docker container by
following these steps:
```sh
./bin/docker-build
./bin/docker-shell
cd /opt/license-management/
enable_dev_mode
bundle open license_finder
```
The `docker-shell` script will mount the current project as a volume into `/opt/license-management`.
This allows you edit code from your host machine using your preferred editor and
see the affects of those changes from within the running docker container.
### Updating the SPDX index
We will need to periodically update the SPDX index. This can be achieved with
the following command.
```bash
$ ./bin/update-spdx
```
## Supported languages and package managers
The following table shows which languages and package managers are supported.
| Language | Package managers |
|------------|-------------------------------------------------------------------|
| JavaScript | [Bower](https://bower.io/), [npm](https://www.npmjs.com/) |
| Go | [Godep](https://github.com/tools/godep), go get |
| Java | [Gradle](https://gradle.org/), [Maven](https://maven.apache.org/) |
| .NET | [Nuget](https://www.nuget.org/) |
| Python | [pip](https://pip.pypa.io/en/stable/) |
| Ruby | [gem](https://rubygems.org/) |
| PHP | [composer](https://getcomposer.org) |
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.
```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
```
## Settings
The License Management tool can be customized with environments variables for some project types.
| Environment variable | Project type | Function |
|----------------------|--------------|----------|
| MAVEN_CLI_OPTS | Java (Maven) | Additional arguments for the mvn executable. If not supplied, defaults to `-DskipTests`. |
| LICENSE_FINDER_CLI_OPTS | * | Additional arguments for the `license_finder` executable. |
| 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. |
| LOG_LEVEL | * | Control the verbosity of the logs. (`debug`, `info`, `warn` (default), `error`, `fatal`) |
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.
*Caution:* if you supply the `MAVEN_CLI_OPTS` for a Maven project, don't forget to append `-DskipTests` to save time by skipping the test suite.
*Tip:* in case you still need to run tests during license management check, supply `MAVEN_CLI_OPTS=-DskipTests=false`
to the docker command.
## Versioning and release process
1. Create a new entry in the `.gitlab/release.yml` file for the new version to release.
```yaml
12-x-stable:
extends: .release
variables:
DOTENV: ".env.12-x-stable"
```
2. Create a new `.env.*` that corresponds to the version to release and specify the default configuration.
```text
LM_PYTHON_VERSION '3'
LM_REPORT_VERSION '2.0'
```
Please check the [Release Process documentation](https://gitlab.com/gitlab-org/security-products/release/blob/master/docs/release_process.md).
## Upgrading to the latest version of LicenseFinder
The License Management projects depends on two different upstream components.
1. The [LicenseFinder](https://rubygems.org/gems/license_finder) Ruby gem.
2. The [LicenseFinder](https://hub.docker.com/r/licensefinder/license_finder) Docker image.
Upgrading each can be performed as two separate changes and do not need to occur simultaneously,
unless a new package manager has been added and additional tooling needs to be installed.
### Upgrading the Ruby gem
1. Check for the latest version of `LicenseFinder` at [https://rubygems.org/gems/license_finder](https://rubygems.org/gems/license_finder)
1. Check the version of the `license_finder` gem that is currently being used in the `Gemfile.lock`. E.g. [here](https://gitlab.com/gitlab-org/security-products/license-management/-/blob/39afdc40296871d9f7c1732ff3f7e1e3b7b28bbe/Gemfile.lock#L15)
1. If an update is available, create a new branch
1. Bump the license management version in [CHANGELOG.md](https://gitlab.com/gitlab-org/security-products/license-management/-/blob/master/CHANGELOG.md) and in [version.rb](https://gitlab.com/gitlab-org/security-products/license-management/-/blob/master/lib/license/management/version.rb)
1. Update the `license_finder` version constraint in the [gemspec](https://gitlab.com/gitlab-org/security-products/license-management/-/blob/39afdc40296871d9f7c1732ff3f7e1e3b7b28bbe/license-management.gemspec#L30).
1. Run `bundle update license_finder`
1. Test the changes locally using the `bin/test` script.
1. Submit a merge request.
### Upgrading the Docker image
1. Check for the latest version of `LicenseFinder` at [https://hub.docker.com/r/licensefinder/license_finder/tags](https://hub.docker.com/r/licensefinder/license_finder/tags)
1. Check the version of `license_finder` docker image that is currently being used in the `Dockerfile`. E.g. [here](https://gitlab.com/gitlab-org/security-products/license-management/-/blob/39afdc40296871d9f7c1732ff3f7e1e3b7b28bbe/Dockerfile#L1)
1. If an update is available, create a branch
1. Bump the license management version in [CHANGELOG.md](https://gitlab.com/gitlab-org/security-products/license-management/-/blob/master/CHANGELOG.md) and in [version.rb](https://gitlab.com/gitlab-org/security-products/license-management/-/blob/master/lib/license/management/version.rb)
1. Edit the version specified in the `DockerFile` to match the desired `license_finder` Docker image tag.
1. Test the changes locally using the `bin/test` script.
1. Submit a merge request.
# Contributing
If you want to help, read the [contribution guidelines](CONTRIBUTING.md).
If an unknown license is detected, please consider updating the mapping defined
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 SDPX identifier found in [spdx-licenses.json](https://gitlab.com/gitlab-org/security-products/license-management/blob/master/spdx-licenses.json).
|
