README.md 6.9 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
```

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

```sh
43 44 45 46
$ ./bin/docker-build
$ ./bin/docker-shell
$ cd /opt/license-management/
$ ./bin/test
47 48 49 50 51 52
```

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

```sh
53 54 55 56 57
$ ./bin/docker-build
$ ./bin/docker-shell
$ cd /opt/license-management/
$ enable_dev_mode
$ bundle open license_finder
58 59
```

mo's avatar
mo committed
60
The `docker-shell` script will mount the current project as a volume into `/opt/license-management`.
61 62
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
63

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

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

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

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

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

| Language   | Package managers                                                  |
|------------|-------------------------------------------------------------------|
mo's avatar
mo committed
79
| .NET       | [.NET Core CLI][dotnet_core], [Nuget][nuget]                      |
mo's avatar
mo committed
80
| C/C++      | [Conan][conan]                                                    |
mo's avatar
mo committed
81 82 83 84 85 86
| 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
87

88 89 90
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.

91 92 93 94 95 96 97
```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
```
98

99 100
## Settings

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

| Environment variable | Project type | Function |
|----------------------|--------------|----------|
mo's avatar
mo committed
105
| ADDITIONAL_CA_CERT_BUNDLE | * | Additional certificate chain to install in the trusted store. |
106
| MAVEN_CLI_OPTS       | Java (Maven) | Additional arguments for the mvn executable. If not supplied, defaults to `-DskipTests`. |
107
| LICENSE_FINDER_CLI_OPTS | * | Additional arguments for the `license_finder` executable. |
108 109
| 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
110
| LOG_LEVEL    | * | Control the verbosity of the logs. (`debug`, `info`, `warn` (default), `error`, `fatal`)  |
111 112 113 114 115


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
116 117 118 119
## 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
120 121
## Upgrading to the latest version of LicenseFinder

122 123
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
124
1. If an update is available, create a new branch
125 126
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
127
1. Run `bundle update license_finder`
128
1. Test the changes locally using the `bin/test` script.
mo's avatar
mo committed
129 130
1. Submit a merge request.

Gilbert Roulot's avatar
Gilbert Roulot committed
131 132 133
# Contributing

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

If an unknown license is detected, please consider updating the mapping defined
Matt Selsky's avatar
Matt Selsky committed
136
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).
137

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