License Compliance Tool

When you are using open-source third-party software components, you have to conform to their license. For most licenses, this means three things:

1. Attribute that you are using the component and mention its license

2. Make the source code of the component available

3. Include the license terms

While it is not particular difficult to fulfill any of these obligations, doing it manually can become quite tedious if you are using a lot of them. An in our times, we are using a lot of them - especially if you have a dependency management system like Maven or NPM at hand.

License Compliance Tool helps you to be compliant to license terms by creating a manifest of all used components including their license source code.

• Overview
• Software Bill of Materials
• Jenkins Plugin
  • Global configuration
  • Create manifest
  • Download licenses
• CLI tool

Overview

1. Create a Software Bill of Materials (SBOM) for your source code.

2. Call the Jenkins Plugin in your build job to create a component manifest and download the license files. You can configure several JSON data sources to improve data quality.

3. Add the component manifest and the license files to your delivery package (e.g. ZIP, WAR, MSI).

Software Bill of Materials

The main input is a Software Bill of Materials (SBOM) of the software project. It must be in the CycloneDX format.

It can be created manually, but if you are using a dependency management system, it is more convenient to let it be created for you.

The CycloneDX toolchain supports several dependency management systems, e.g. Apache Maven or NPM. Take a look at their GitHub page for a complete list.

Jenkins Plugin

Global configuration

You can create multiple configuration profiles. One profile can be configured as the default profile, otherwise the first profile in the list considered the default.

Each build step of this plugin provides a parameter configurationProfile to specify the desired profile. If that value is empty, the default profile is used.

Component meta data

Use this setting to override existing or add missing attributes to the components of the SBOM. This is especially useful when you use a SBOM generated from your dependency management system since the resulting data is often incomplete and incorrect.

Enter an URL point to a JSON file containing an array of metadata entries. Each entry contains regular expressions that are matched against the group and name attributes of components. At least one of these attributes need to be set. Regular expressions follow the Java style. If both are set, both have to match. The first matching entry wins, so order is important.

Entries have the following attributes:

Name	Type	Required?	Meaning
groupMatch	String	If nameMatch is not set	Regular expression for the component’s group
nameMatch	String	If groupMatch is not set	Regular expression for the component’s name
mappedName	String	Optional	"Use this name in the component manifest. Otherwise group.name will be used."
ignore	Boolean	Optional	If set to true, the component will not be included in the manifest
url	String	Optional	Overwrite the URL in the manifest which points to a website where the component’s source code can be retrieved.
licenses	Array of String	Optional	Replace the licenses defined in the SBOM
attributionNotices	Array of String	Optional	Add attribution notices, e.g. copyright statements. These are often defined in files called NOTICE or NOTICE.txt.
comment	String	Optional	Explanatory comment. Not used during processing. If you maintain these files manually you can use this field to document the purpose of the entry

Here are some examples to illustrate what you can do with it:

• Combine all components from group my.component into a component named MyComponent and add a custom URL

{
  "groupMatch": "my\\.component\\.*",
  "mappedName": "MyComponent",
  "url": "https://github.com/my/MyComponent"
}

• Ignore component, e.g. because it is not a third-party component and need not be included in the manifest

{
  "groupMatch": "my\\.component\\.*",
  "ignore": true
}

• Override licenses

{
  "groupMatch": "my\\.component\\.*",
  "licenses": [
    "Apache-2.0",
    "LGPL-2.1"
  ]
}

License information

Use this setting to define licenses and URLs with the license texts. The URL needs to point to a JSON file containing an array of entries with the following attributes:

Name	Type	Required?	Meaning
name	String	yes	Will be used for the component manifest as well as for the filename of the license file.
url	String	no	URL to which the license name will be linked in the component manifest. If empty, no link will be created.
downloadUrl	String	no	URL from which the license file will be downloaded. If not set, the file will be downloaded from url.

License mapping

Different components often use different names for the same license. You can use this setting to define aliases for licenses. The URL needs to point to a JSON file containing an array of entries with the following attributes:

Name	Type	Required?	Meaning
alias	String	yes	The name of the license in the SBOM
canonicalName	String	no	The name of the license in the license information

Create manifest

This build step creates a component manifest file based on an input SBOM and the global configuration.

Declarative pipeline example

pipeline {
    agent any

    stages {
        stage('Create manifest') {
            steps {
                componentManifest inputPath: 'input.json', outputPath: 'output.pdf', templateUrl: 'file://template.ftl', ignoreUnavailableUrl: true, configurationProfile: 'MyProfile'
            }
        }
    }
}

With the parameter templateUrl, you can specify a URL pointing to a custom FreeMarker template which is used to create the output. The parameter is optional. If it is not set, the template from de.medavis.lct.core.outputter.DefaultComponentManifest.ftlh is used.

If the parameter ignoreUnavailableUrl is set (default value: false), URLs from the SBOM are ignored when they are not available, i.e. no connection can be established or they return a different status code than 200. This is useful to prevent the generated component manifest from containing invalid links.

The desired profile from the global configuration can be chosen with configurationProfile. If that parameter is empty, the default profile is used.

Download licenses

This build step tries to download all licenses referenced in the input SBOM and the global configuration into the specified directory. Download URLs are preferred over view URLs. If neither URL has been specified for the license, then nothing will be downloaded.

The downloaded files will have an extension depending on the content type of the URL’s content:

Content type	Extension
text/plain	.txt
text/html	.html
other	none

Be aware that this task might download harmful content. Bundling the downloaded files into your redistribution package could allow an attacker to plant malware. To safeguard against that risk, add license URLs after a manual review to your license configuration and run the task with failOnDynamicLicense option. It will then fail if it encounters a license that is not part of your license configuration .

The desired profile from the global configuration can be chosen with configurationProfile. If that parameter is empty, the default profile is used.

Declarative pipeline example

pipeline {
    agent any

    stages {
        stage('Create manifest') {
            steps {
                downloadLicenses inputPath: 'bom.json', outputPath: 'target/THIRDPARTY', failOnDynamicLicense: true, configurationProfile: 'MyProfile'
            }
        }
    }
}

CLI tool

You can also run the tool as a standalone CLI tool. This is especially useful when you want to test out changes to component or license metadata since you do not have to switch back and forth between Jenkins and your development environment. You can run the CLI tool using

java -jar license-compliance-tool-cli.jar

Examples:

• Create a component manifest from a BOM on a server with a template:

  java -jar license-compliance-tool-cli.jar create-manifest --in=https://your.server.url/path/to/bom --out=manifest.html --template=htps://your.server.url/path/to/template

• Create a component manifest from a local BOM with metadata from a server:

  java -jar license-compliance-tool-cli.jar
    create-manifest
    --in=path/to/bom
    --out=manifest.html
    --componentMetadata=https://your.server.url/componentMetadata.json
    --licenses=https://your.server.url/licenses.json
    --licenseMapping=https://your.server.url/licenseMapping.json
    --template=https://your.server.url/path/to/template

• Download licenses

  java -jar license-compliance-tool-cli.jar download-licenses --in=path/to/bom --out=manifest.html

• Get usage help

  java -jar license-compliance-tool-cli.jar

Consult the help to learn about more options.

Note that it requires Java 11 or later.