License Finder

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

code: https://github.com/pivotal/LicenseFinder
support:
- license-finder@googlegroups.com
- https://groups.google.com/forum/#!forum/license-finder
backlog: https://www.pivotaltracker.com/s/projects/234851

Supported project types

Ruby Gems (via bundler)
Python Eggs (via pip)
Node.js (via npm)
Bower

Experimental project types

Java (via maven)
Java (via gradle)
Objective-C (+ CocoaPods)

Installation

The easiest way to use license_finder 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 ignored_groups in Configuration.

Usage

license_finder will generate reports of action items; i.e., dependencies that do not fall within your license "whitelist".

$ license_finder

Or, if you installed with bundler:

$ bundle exec license_finder

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.

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

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)
package.json (for npm)
pom.xml (for maven)
build.gradle (for gradle)
bower.json (for bower)
Podfile (for CocoaPods)

Continuous Integration

license_finder will also 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.

Output and Artifacts

STDOUT

On a Rails project, you could expect license_finder to output something like the following (assuming you whitelisted the MIT license -- see Configuration):

Dependencies that need approval:

highline, 1.6.14, ruby
json, 1.7.5, ruby
mime-types, 1.19, ruby
rails, 3.2.8, other
rdoc, 3.12, other
rubyzip, 0.9.9, ruby
xml-simple, 1.1.1, other

Files and Reports

The executable task will also write out a dependencies.db, dependencies.csv, and dependencies.html file (in the doc/ directory by default -- see Configuration).

The latter two files are human-readable reports that you could send to your non-technical business partners, lawyers, etc.

The HTML report generated by license_finder shows a summary of the project's dependencies and dependencies which need to be approved. The project name at the top of the report can be set in config/license_finder.yml.

Manual Intervention

Setting Licenses

When license_finder reports that a dependency's license is 'other', you should manually research what the actual license is. When you have established the real license, you can record it with:

$ license_finder license MIT my_unknown_dependency

This command would assign the MIT license to the dependency my_unknown_dependency.

Approving Dependencies

Whenever you have a dependency that falls outside of your whitelist, license_finder will tell you. If your business decides that this is an acceptable risk, you can manually approve the dependency by using the license_finder approve command.

For example, let's assume you've only whitelisted the "MIT" license in your config/license_finder.yml. You then add the awesome_gpl_gem to your Gemfile, which we'll assume is licensed with the GPL license. You then run license_finder and see the gem listed in the output:

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 approve awesome_gpl_gem

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

To record who approved the dependency and why:

$ license_finder approve awesome_gpl_gem --approver CTO --message "Go ahead"

Adding Hidden Dependencies

license_finder can track dependencies that your package managers don't know about (JS libraries that don't appear in your Gemfile/requirements.txt/package.json, etc.)

$ license_finder dependencies add MIT my_js_dep 0.1.2

To automatically approve an unmanaged dependency when you add it, use:

$ license_finder dependencies add MIT my_js_dep 0.1.2 --approve

To record who approved the dependency when you add it, use:

$ license_finder dependencies add MIT my_js_dep 0.1.2 --approve --approver CTO --message "Go ahead"

The version is optional. Run license_finder dependencies help for additional documentation about managing these dependencies.

license_finder cannot automatically detect when one of these dependencies has been removed from your project, so you can use:

$ license_finder dependencies remove my_js_dep

Configuration

The first time you run license_finder it will create a default configuration file ./config/license_finder.yml, which will look something like this:

---
whitelist:
#- MIT
#- Apache 2.0
ignore_groups:
#- test
#- development
ignore_dependencies:
#- bundler
dependencies_file_dir: './doc/'
project_name: My Project Name
gradle_command: # only meaningful if used with a Java/gradle project. Defaults to "gradle".

By modifying this file, you can configure license_finder's behavior:

Automatically approve licenses in the whitelist
Exclude test or development dependencies by setting ignore_groups. (Currently this only works for Bundler.)
Exclude specific dependencies by setting ignore_dependencies. (Think carefully before adding dependencies to this list. A likely item to exclude is bundler itself, to avoid noisy changes to the doc files when different people run license_finder with different versions of bundler.)
Store the license database and text files in another directory by changing dependencies_file_dir.
Set the HTML report title wih project_name, which defaults to the name of the working directory.
See below for explanation of "gradle_command".

You can also configure license_finder through the command line. See license_finder whitelist help, license_finder ignored_bundler_groups help and license_finder project_name help for more details.

Gradle Projects

You need to install the license gradle plugin: https://github.com/hierynomus/license-gradle-plugin

LicenseFinder assumes that gradle is in your shell's command path and can be invoked by just calling gradle.

If you must invoke gradle some other way (e.g., with a custom gradlew script), set the gradle_command option in your project's license_finder.yml:

# ... other configuration ...
gradle_command: ./gradlew

By default, license_finder will report on gradle's "runtime" dependencies. If you want to generate a report for some other dependency configuration (e.g. Android projects will sometimes specify their meaningful dependencies in the "compile" group), you can specify it in your project's build.gradle:

// Must come *after* the 'apply plugin: license' line

downloadLicenses {
  dependencyConfiguration "compile"
}

Upgrade for pre-0.8.0 users

If you wish to cleanup your root directory you can run:

$ license_finder move

This will move your dependencies.* files to the doc/ directory and update the config.

Requirements

license_finder requires ruby >= 1.9, or jruby.

A Plea to Package Authors and Maintainers

Please add a license to your package specs! Most packaging systems allow for the specification of one or more licenses.

For example, Ruby Gems may have a license specified by name:

Gem::Specification.new do |s|
  s.name = "my_great_gem"
  s.license = "MIT"
end

And add a LICENSE file to your package that contains your license text.

Support

Send an email to the list: license-finder@googlegroups.com
View the project backlog at Pivotal Tracker: https://www.pivotaltracker.com/s/projects/234851

Contributing

Fork the project from https://github.com/pivotal/LicenseFinder
Create a feature branch.
Make your feature addition or bug fix. Please make sure there is appropriate test coverage.
Rebase on top of master.
Send a pull request.

To successfully run the test suite, you will need node.js, python, pip and gradle installed. If you run rake check_dependencies, you'll see exactly what you're missing.

You'll need a gradle version >= 1.8.

For the python dependency tests you will want to have virtualenv installed, to allow pip to work without sudo. For more details, see this post on virtualenv.

If you're running the test suite with jruby, you're probably going to want to set up some environment variables:

JAVA_OPTS='-client -XX:+TieredCompilation -XX:TieredStopAtLevel=1' JRUBY_OPTS='-J-Djruby.launch.inproc=true'

License

LicenseFinder is released under the MIT License. http://www.opensource.org/licenses/mit-license

mainej/LicenseFinder