README.md 4.33 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 7 8 9 10 11 12 13 14 15 16

GitLab tool for detecting licenses of the dependencies used by the provided source.
It is currently based on License Finder 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 \
Gilbert Roulot's avatar
Gilbert Roulot committed
17 18
      --rm \
      registry.gitlab.com/gitlab-org/security-products/license-management:latest analyze /code
Gilbert Roulot's avatar
Gilbert Roulot committed
19 20 21 22
    ```

1. The results will be stored in the `gl-license-management-report.json` file in the application directory. `gl-license-management-report.html` is also available with a human readable report.

Gilbert Roulot's avatar
Gilbert Roulot committed
23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42
## 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 integration tests on the image like this:

```sh
43
docker run --rm license-management /test/test.sh project_name git_ref
Gilbert Roulot's avatar
Gilbert Roulot committed
44 45
```

46 47 48 49 50 51
where:

- `project_name` is the project slug among the
[test projects for security products](https://gitlab.com/gitlab-org/security-products/tests/) (e.g. `java-maven`)
- `git_ref` is the Git ref to checkout and scan against (e.g. `master`)

Gilbert Roulot's avatar
Gilbert Roulot committed
52 53 54 55 56 57 58 59 60 61 62 63 64
## 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/)                                      |

65 66 67
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.

68 69 70 71 72 73 74
```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
```
75

76 77 78 79 80 81 82
## 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`. |
83 84
| 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. |
85 86 87 88 89 90 91 92 93 94 95


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
96 97 98 99 100

## Versioning and release process

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

Gilbert Roulot's avatar
Gilbert Roulot committed
101 102 103
# Contributing

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