License Finder

Build status

• Ruby 2.7.8
• Ruby 3.1.4
• Ruby 3.2.3
• Ruby 3.3.0

LicenseFinder works with your package managers to find dependencies, detect the licenses of the packages in them, compare those licenses against a user-defined list of permitted licenses, and give you an actionable exception report.

• code: https://github.com/pivotal/LicenseFinder
• ci: https://norsk.cf-app.com/teams/main/pipelines/LicenseFinder
• docker: licensefinder/license_finder
  • the docker image contains all the package managers needed to run license_finder
• support:
  • The primary form of communication for support is through github issues. The google groups are not actively monitored
  • license-finder@googlegroups.com
  • https://groups.google.com/forum/#!forum/license-finder

Supported project types

| Project Type | Package Manager | Tested on Version | | ------------ |-----------------|------------------:| | Ruby Gems | bundler | 2.3.7 | | Python 2.7 Eggs | pip2 | 19.0.2 | | Python 3.5 Eggs | pip3 | 20.0.2 | | Node.js | npm | 6.4.1 | | Bower | bower | 1.8.4 | | Nuget (without license discovery) | nuget | 4.7.1.5393 | | Godep | Godep | 80 | | Go workspace | Go lang | 1.11.5 | | Go modules | Go lang | 1.14.3 | | Java | maven | 3.6.0 | | Java | gradle | 5.6.4 |

Experimental project types

• Erlang (via rebar and Erlang.mk)
• Objective-C, Swift (via Carthage, CocoaPods [0.39 and below. See CocoaPods Specs Repo Sharding]) and Swift Package Manager(SPM)
• Elixir (via mix)
• Golang (via gvt, glide,dep, trash and govendor)
• JavaScript (via yarn)
• C++/C (via conan)
• Scala (via sbt)
• Rust (via cargo)
• PHP (via composer)
• Python (via Conda, pipenv)
• Flutter (via flutter pub)

Installation

License Finder may be run as a pre-commit hook by adding the following to your .pre-commit-config.yaml:

repos:
  - repo: https://github.com/pivotal/LicenseFinder
    rev: v7.1.0 # You probably want the latest tag.
    hooks:
      - id: license-finder

Running License Finder directly requires Ruby 2.6.0 or greater. If you have an older version of Ruby installed, you can update via Homebrew:

$ ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"

then:

$ brew install ruby

The easiest way to use license_finder directly is to install it as a command line tool, like brew, awk, gem or bundler:

$ gem install license_finder

Though it's less preferable, if you are using bundler in a Ruby project, you can add license_finder to your Gemfile:

gem 'license_finder', :group => :development

This approach helps you remember to install license_finder, but can pull in unwanted dependencies, including bundler. To mitigate this problem, see Excluding Dependencies.

Usage

Make sure your dependencies are installed (with your package manager's install command: bundle install, npm install, etc.)

The first time you run license_finder it will list all your project's packages.

$ license_finder

Or, if you installed with bundler:

$ bundle exec license_finder

The output will report that none of your packages have been approved. Over time you will tell license_finder which packages are approved, so when you run this command in the future, it will report current action items; i.e., packages that are new or have never been approved.

If you don't wish to see progressive output "dots", use the --quiet option.

If you'd like to see debugging output, use the --debug option. license_finder will then output info about packages, their dependencies, and where and how each license was discovered. This can be useful when you need to track down an unexpected package or license.

If you do not want to manually run an individual package manager's prepare command (ex: bundle install, npm install, etc) to ensure your project is fully prepared to be scanned, use the --prepare or -p option which will run each active package manager's prepare command for you. If you would like to continue running license_finder even if there is an issue with a prepare step, use the --prepare-no-fail option which prepares but carries on despite any potential failures.

Run license_finder help to see other available commands, and license_finder help [COMMAND] for detailed help on a specific command.

Docker

If you have docker installed, try using the included dlf script (potentially symlinked to be in your path via ln -s LicenseFinder/dlf /usr/local/bin or whatever method you prefer). This will run any commands passed to it inside a pre-provisioned Docker container to maintain consistent versions of all the package managers. For example,

$ dlf npm --version
5.3.0

$ dlf license_finder --help

Dependencies that need approval:
...
license_finder, 3.0.3, MIT

$ dlf "bundle install && license_finder"

You can better understand the way this script works by looking at its source, but for reference it will mount your current directory at the path /scan and run any commands passed to it from that directory. If your command has &&, ensure you quote the command. If it does not, ensure the command is not quoted.

Note that the docker image will run the gem which is installed within it. So the docker image tagged 7.0.0 will run License Finder Version 7.0.0

See the contributing guide for information on development.

Activation

license_finder will find and include packages for all supported languages, as long as that language has a package definition in the project directory:

• Gemfile (for bundler)
• requirements.txt (for pip)
• Pipfile.lock (for pipenv)
• package.json (for npm)
• pom.xml (for maven)
• build.gradle or build.gradle.kts (for gradle)
• settings.gradle that specifies rootProject.buildFileName (for gradle)
• bower.json (for bower)
• Podfile (for pod) (set ACKNOWLEDGEMENTS_PATH variable if you want to target a particular Pods-acknowledgements-<TARGET>.plist. Can be useful in multi-target pods projects.)
• Cartfile (for carthage)
• workspace-state.json under build directory (provided as enviroment variable SPM_DERIVED_DATA for Xcode, or default .build for non-Xcode projects), (for spm)
• rebar.config (for rebar)
• Erlang.mk or erlang.mk file (for Erlang.mk)
• mix.exs (for mix)
• packages/ directory (for nuget)
• *.csproj (for dotnet)
• vendor/manifest or */vendor/manifest file (for gvt)
• glide.lock file (for glide)
• vendor/vendor.json file (for govendor)
• Gopkg.lock file (for dep)
• Godeps/Godeps.json (for godep)
• *.envrc file (for go)
• go.mod file (for go mod)
• vendor.conf file (for trash)
• yarn.lock file (for yarn)
• conanfile.txt file (for conan)
• build.sbt file (for sbt)
• Cargo.lock file (for cargo)
• composer.lock file (for composer)
• environment.yml file (for conda)
• pubspec.yaml & .pub cache locaton through ENV variable (for flutter)

Continuous Integration

license_finder will return a non-zero exit status if there are unapproved dependencies. This can be useful for inclusion in a CI environment to alert you if someone adds an unapproved dependency to the project.

Approving Dependencies

license_finder will inform you whenever you have an unapproved dependency. If your business decides this is an acceptable risk, the easiest way to approve the dependency is by running license_finder approvals add.

For example, let's assume you've added the awesome_gpl_gem to your Gemfile, which license_finder reports is unapproved:

$ license_finder
Dependencies that need approval:
awesome_gpl_gem, 1.0.0, GPL

Your business tells you that in this case, it's acceptable to use this gem. You now run:

$ license_finder approvals add awesome_gpl_gem

If you rerun license_finder, you should no longer see awesome_gpl_gem in the output.

To approve specific version

$ license_finder approvals add awesome_gpl_gem --version=1.0.0

To record who approved the dependency and why:

$ license_finder approvals add awesome_gpl_gem --who CTO --why "Go ahead"

Permitting Licenses

Approving packages one-by-one can be tedious. Usually your business has blanket policies about which packages are approved. To tell license_finder that any package with the MIT license should be approved, run:

$ license_finder permitted_licenses add MIT

Any current or future packages with the MIT license will be excluded from the output of license_finder.

You can also record --who and --why when changing permitted licenses, or making any other decision about