@rio-cloud/rio-license-checker

Helps checking third-party libraries' licenses according to RIO guidelines.

Installation

It is recommended to install this utility as "devDependency" with a fixed version in your package.json. This way, npx won't just download the latest version during the pipeline run, but use the version fixed in your project, instead.

⚠️ Note: If you do this, you must ensure you're updating the dependency properly, as future versions might potentially behave differently (very, very unlikely, though).

Usage

# general usage information
npx @rio-cloud/rio-license-checker help

# information on the default "run-check" command
npx @rio-cloud/rio-license-checker help run-check

# information on the "download-whitelist" command
npx @rio-cloud/rio-license-checker help download-whitelist

# information on the "upload-report" command
npx @rio-cloud/rio-license-checker help upload-report

The run-check command is the default command. The command name is optional:

npx @rio-cloud/rio-license-checker run-check -a rio-example -s example-service -t npm-frontend
# is the same as
npx @rio-cloud/rio-license-checker -a rio-example -s example-service -t npm-frontend

Automatic mode (a.k.a. run-check)

1. Downloads the appropriate license whitelist that's curated by the RIO Security Guild from a central location.
2. Orchestrates a 3rd-party license checking tool to inspect your project's dependencies.
   • If any dependency is found with non-compliant license information, this tool will exit with a non-zero code.
   • If all dependencies are okay: generate a report file containing the list of dependencies, their versions, and their respective license information.
3. Uploads the report to a central location (optional; this is only done when the --upload flag is set).

gradle

• The underlying license report tool is hierynomus/license-gradle-plugin.
• You need to include & configure the plugin in your build.gradle.kts.
• The output of the plugin is compared with the whitelist programmatically (as we used to do in the build.gradle.kts).
• For subprojects, you need a separate invocation of the license checker, where the directory points to the subproject.
  • Currently, only subprojects directly below the root project are supported (limited by where the checker looks for the gradle wrapper).
  • When doing so, take care to specify a different service name to prevent overwriting the license report of the root project.
  • Please see below for examples.

npx @rio-cloud/rio-license-checker -a rio-example -s example-service -t gradle
npx @rio-cloud/rio-license-checker -a rio-example -s example-service_sub-project -t gradle -d ./sub-project

npm-frontend and npm-backend

• The underlying license checker tool is license-checker-rseidelsohn.
• The license checker generates a report and compares the licenses to the passed whitelist.
• The application's own package is automatically excluded from the report, as it (usually) does not have a license.
• For testability reasons, we cannot use the programmatic interface of the tool. Instead, we call it as a subprocess via zx.
• You can exclude dependencies by creating a oss-licenses-ignore-packages.txt file in the project directory.
• Note that this will statically inspect the dependencies as defined in your package.json. Especially for frontends, this might not be accurate enough. Check out the "manual" type for npm-frontend-bundled below.

download-whitelist

To just download the appropriate whitelist file as-is without any processing or running the check, you can use the download-whitelist command:

npx @rio-cloud/rio-license-checker download-whitelist -t npm-frontend-bundled

Note that this will only work when the current session has access to AWS.

Also note that this only supports the "npm-frontend-bundled" type at the moment, which will save the whitelist as frontend-license-whitelist.json in the project directory.

This command supports a directory and verbose option, as well. Check out the usage docs for more info.

upload-report

If your license check is handled by another tool during the build, you can use the upload-report command to upload the report output from a given file.

npx @rio-cloud/rio-license-checker upload-report -a rio-example -s example-service -t npm-frontend-bundled -r ./build/libraries.json

Note that this only supports the "npm-frontend-bundled" type at the moment.

This command supports a verbose option, as well. Check out the usage docs for more info.

Release

Tagged releases are packed with npm pack, uploaded to S3, and published to npmjs by the GitHub Actions workflow in the rio-license-checker-npm-publish repository.