README.md 7.17 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 80 81 82 83 84 85
| .NET       | [.NET Core CLI][dotnet_core], [Nuget][nuget]                      |
| 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
86

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

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

98 99
## Settings

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

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


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
115 116
## Versioning and release process

117
1. Create a new entry in the `.gitlab/release.yml` file for the new version to release.
118 119 120 121 122 123 124 125 126 127 128

    ```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
mo's avatar
mo committed
129
    LM_PYTHON_VERSION '3'
130 131 132
    LM_REPORT_VERSION '2.0'
    ```

Gilbert Roulot's avatar
Gilbert Roulot committed
133 134
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
135 136
## Upgrading to the latest version of LicenseFinder

137 138
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
139
1. If an update is available, create a new branch
140 141
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
142
1. Run `bundle update license_finder`
143
1. Test the changes locally using the `bin/test` script.
mo's avatar
mo committed
144 145
1. Submit a merge request.

Gilbert Roulot's avatar
Gilbert Roulot committed
146 147 148
# Contributing

If you want to help, read the [contribution guidelines](CONTRIBUTING.md).
149 150 151

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).
152

mo's avatar
mo committed
153
[bower]: https://bower.io/
154 155
[changelog]: https://gitlab.com/gitlab-org/security-products/license-management/-/blob/master/CHANGELOG.md
[gemfile_lock]: https://gitlab.com/gitlab-org/security-products/license-management/-/blob/master/Gemfile.lock
mo's avatar
mo committed
156 157 158 159 160 161 162 163 164 165 166 167 168 169 170
[gemspec]: https://gitlab.com/gitlab-org/security-products/license-management/-/blob/master/license-management.gemspec
[license_finder]: https://rubygems.org/gems/license_finder
[npm]: https://www.npmjs.com/
[version_rb]: https://gitlab.com/gitlab-org/security-products/license-management/-/blob/master/lib/license/management/version.rb
[yarn]: https://yarnpkg.com/
[gomod]: https://github.com/golang/go/wiki/Modules
[godep]: https://github.com/tools/godep
[gradle]: https://gradle.org/
[maven]: https://maven.apache.org/
[nuget]: https://www.nuget.org/
[dotnet_core]: https://docs.microsoft.com/en-us/dotnet/core/tools/
[pip]: https://pip.pypa.io/en/stable/
[pipenv]: https://github.com/pypa/pipenv
[bundler]: https://bundler.io/
[composer]: https://getcomposer.org