README.md 7.64 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 8
It is currently based on [License Finder](https://gitlab.com/gitlab-org/security-products/license-management)
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 28 29 30 31 32 33 34 35 36 37 38 39 40
## 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
```

41
You can run the tests using the following command:
Gilbert Roulot's avatar
Gilbert Roulot committed
42 43

```sh
44
./bin/test
Gilbert Roulot's avatar
Gilbert Roulot committed
45 46
```

mo's avatar
mo committed
47 48 49 50 51 52
### Updating the SPDX index

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

```bash
53
$ ./bin/update-spdx
mo's avatar
mo committed
54 55
```

Gilbert Roulot's avatar
Gilbert Roulot committed
56 57 58 59 60 61 62 63 64 65 66 67
## 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/)                                      |
Can Eldem's avatar
Can Eldem committed
68
| PHP        | [composer](https://getcomposer.org)                               |
Gilbert Roulot's avatar
Gilbert Roulot committed
69

70 71 72
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.

73 74 75 76 77 78 79
```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
```
80

81 82
## Settings

Can Eldem's avatar
Can Eldem committed
83
The License Management tool can be customized with environments variables for some project types.
84 85 86 87

| Environment variable | Project type | Function |
|----------------------|--------------|----------|
| MAVEN_CLI_OPTS       | Java (Maven) | Additional arguments for the mvn executable. If not supplied, defaults to `-DskipTests`. |
88
| LICENSE_FINDER_CLI_OPTS | * | Additional arguments for the `license_finder` executable. |
89 90
| 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. |
91 92 93 94 95 96 97 98 99 100 101


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.

Gilbert Roulot's avatar
Gilbert Roulot committed
102 103
## Versioning and release process

104
1. Create a new entry in the `.gitlab/release.yml` file for the new version to release.
105 106 107 108 109 110 111 112 113 114 115

    ```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
116
    LM_PYTHON_VERSION '3'
117 118 119
    LM_REPORT_VERSION '2.0'
    ```

Gilbert Roulot's avatar
Gilbert Roulot committed
120 121
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 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139
## 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`
140
1. Test the changes locally using the `bin/test` script.
mo's avatar
mo committed
141 142 143 144 145 146 147 148 149
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.
150
1. Test the changes locally using the `bin/test` script.
mo's avatar
mo committed
151 152
1. Submit a merge request.

Gilbert Roulot's avatar
Gilbert Roulot committed
153 154 155
# Contributing

If you want to help, read the [contribution guidelines](CONTRIBUTING.md).
156 157 158

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