1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
# If not set, defaults to the directory name of `source_path`
name: 'Hello Rails 8'

# Path is relative to the location of the configuration file and specifies
# the root to expand all paths from
# If not set, defaults to a git repository root
root: '.'

# Path is relative to configuration root and specifies where cached metadata will be stored.
# If not set, defaults to '.licenses'
#cache_path: 'relative/path/to/cache'

# Path is relative to configuration root and specifies the working directory when enumerating dependencies
# Optional for single app configuration, required when specifying multiple apps
# Defaults to current directory when running `licensed`
#source_path: 'relative/path/to/source'

# Whether to take any action when records are detected in the cache paths that don't map to evaluated
# dependencies.
# Available values are:
# - 'error': treat stale cached records as errors.  Notify the user and fail status checks
# - 'warn', '', unset: treat stale cached records as warnings.  Notify the user but do not fail status checks
# - 'ignore': Ignore stale cached records.  Do not notify the user and do not fail status checks
# Optional, when not set this defaults to 'warn' behavior
stale_records_action: 'warn'

# Sources of metadata
sources:
  bower: true
  bundler: true

# Dependencies with these licenses are allowed and will not raise errors or warnings.
# This list does not have a default value and is required for `licensed status`
# to succeed.
allowed:
  - mit
  - apache-2.0
  - bsd-2-clause
  - bsd-3-clause
  - cc0-1.0
  - isc
  - MIT-LICENSE

# These dependencies are ignored during enumeration.
# They will not be cached, and will not raise errors or warnings.
# This configuration is intended to be used for dependencies that don't need to
# be included for compliance purposes, such as other projects owned by the current
# project's owner, internal dependencies, and dependencies that aren't shipped with
# the project like test frameworks.
ignored:
  bundler:
    #- some-internal-gem

  bower:
    #- some-internal-package

# These dependencies have licenses not on the `allowed` list and have been reviewed.
# They will be cached and checked, but will not raise errors or warnings for a
# non-allowed license.  Dependencies on this list will still raise errors if
# license text cannot be found for the dependency.
reviewed:
  bundler:
    - bcrypt-ruby

  bower:
  - classlist # public domain
  - octicons

# Specify additional license terms that have been obtained from a dependency's owner
# which apply to the dependency's license 
additional_terms:
  bundler:
    bcrypt-ruby:
      - .licenses/amendments/bundler/bcrypt-ruby/amendment.txt

# A single configuration file can be used to enumerate dependencies for multiple
# projects.  Each configuration is referred to as an "application" and must include
# a source path, at a minimum
#apps:
#  - source_path: path/to/application1
#  - source_path: path/to/application2

Finally, running Licensed

Since we followed the default name, we can now do licensed list again, or we can pass the name of the config file by doing licensed list -c .licensed.yml instead. Wow, we have 87 dependencies in a clean Rails app from bundler.

$ licensed list
Listing dependencies for Hello Rails 8
  bundler
    actioncable (8.0.0)
    actionmailbox (8.0.0)
    actionmailer (8.0.0)
    actionpack (8.0.0)
    actiontext (8.0.0)
    actionview (8.0.0)
    activejob (8.0.0)
    activemodel (8.0.0)
    activerecord (8.0.0)
    activestorage (8.0.0)
    activesupport (8.0.0)
    base64 (0.2.0)
    bcrypt_pbkdf (1.1.1)
    benchmark (0.4.0)
    bigdecimal (3.1.8)
    bootsnap (1.18.4)
    builder (3.3.0)
    bundler (2.5.23)
    concurrent-ruby (1.3.4)
    connection_pool (2.4.1)
    crass (1.0.6)
    date (3.4.0)
    dotenv (3.1.4)
    drb (2.2.1)
    ed25519 (1.3.0)
    erubi (1.13.0)
    et-orbi (1.2.11)
    fugit (1.11.1)
    globalid (1.2.1)
    i18n (1.14.6)
    importmap-rails (2.0.3)
    io-console (0.7.2)
    irb (1.14.1)
    jbuilder (2.13.0)
    kamal (2.3.0)
    logger (1.6.1)
    loofah (2.23.1)
    mail (2.8.1)
    marcel (1.0.4)
    mini_mime (1.1.5)
    minitest (5.25.1)
    msgpack (1.7.5)
    net-imap (0.5.1)
    net-pop (0.1.2)
    net-protocol (0.2.2)
    net-scp (4.0.0)
    net-sftp (4.0.0)
    net-smtp (0.5.0)
    net-ssh (7.3.0)
    nio4r (2.7.4)
    nokogiri (1.16.7)
    ostruct (0.6.1)
    propshaft (1.1.0)
    psych (5.2.0)
    puma (6.4.3)
    raabro (1.4.0)
    racc (1.8.1)
    rack (3.1.8)
    rack-session (2.0.0)
    rack-test (2.1.0)
    rackup (2.2.1)
    rails (8.0.0)
    rails-dom-testing (2.2.0)
    rails-html-sanitizer (1.6.0)
    railties (8.0.0)
    rake (13.2.1)
    rdoc (6.7.0)
    reline (0.5.11)
    securerandom (0.3.2)
    solid_cable (3.0.2)
    solid_cache (1.0.6)
    solid_queue (1.0.1)
    sqlite3 (2.2.0)
    sshkit (1.23.2)
    stimulus-rails (1.3.4)
    stringio (3.1.2)
    thor (1.3.2)
    thruster (0.1.9)
    timeout (0.4.2)
    turbo-rails (2.0.11)
    tzinfo (2.0.6)
    tzinfo-data (1.2024.2)
    uri (1.0.2)
    useragent (0.16.10)
    websocket-driver (0.7.6)
    websocket-extensions (0.1.5)
    zeitwerk (2.7.1)
  * 87 bundler dependencies

We can now cache these by doing licensed cache which will add a .licensed folder. The output will be the same list of 87 dependencies.

Now, you can run licensed status to see what it detects about the dependencies. You will be surprised that it does not show a completely clean result!

$ licensed status
Checking cached dependency records for Hello Rails 8
........F..FFFF...F..F.F...........F......FFF..F.F.F....F.........FFF......F..F...F.FF.
Errors:
* Hello Rails 8.bundler.activerecord
  version: 8.0.0, filename: ./rails/hello8/.licenses/bundler/activerecord.dep.yml, license: other, allowed: false
    - license needs review: other

* Hello Rails 8.bundler.base64
  version: 0.2.0, filename: ./rails/hello8/.licenses/bundler/base64.dep.yml, license: other, allowed: false
    - license needs review: other

* Hello Rails 8.bundler.bcrypt_pbkdf
  version: 1.1.1, filename: ./rails/hello8/.licenses/bundler/bcrypt_pbkdf.dep.yml, license: other, allowed: false
    - license needs review: other

* Hello Rails 8.bundler.benchmark
  version: 0.4.0, filename: ./rails/hello8/.licenses/bundler/benchmark.dep.yml, license: other, allowed: false
    - license needs review: other

* Hello Rails 8.bundler.bigdecimal
  version: 3.1.8, filename: ./rails/hello8/.licenses/bundler/bigdecimal.dep.yml, license: other, allowed: false
    - license needs review: other

* Hello Rails 8.bundler.concurrent-ruby
  version: 1.3.4, filename: ./rails/hello8/.licenses/bundler/concurrent-ruby.dep.yml, license: other, allowed: false
    - license needs review: other

* Hello Rails 8.bundler.date
  version: 3.4.0, filename: ./rails/hello8/.licenses/bundler/date.dep.yml, license: other, allowed: false
    - license needs review: other

* Hello Rails 8.bundler.drb
  version: 2.2.1, filename: ./rails/hello8/.licenses/bundler/drb.dep.yml, license: other, allowed: false
    - license needs review: other

* Hello Rails 8.bundler.logger
  version: 1.6.1, filename: ./rails/hello8/.licenses/bundler/logger.dep.yml, license: other, allowed: false
    - missing license text
    - license needs review: other

* Hello Rails 8.bundler.net-imap
  version: 0.5.1, filename: ./rails/hello8/.licenses/bundler/net-imap.dep.yml, license: other, allowed: false
    - license needs review: other

* Hello Rails 8.bundler.net-pop
  version: 0.1.2, filename: ./rails/hello8/.licenses/bundler/net-pop.dep.yml, license: other, allowed: false
    - license needs review: other

* Hello Rails 8.bundler.net-protocol
  version: 0.2.2, filename: ./rails/hello8/.licenses/bundler/net-protocol.dep.yml, license: other, allowed: false
    - license needs review: other

* Hello Rails 8.bundler.net-smtp
  version: 0.5.0, filename: ./rails/hello8/.licenses/bundler/net-smtp.dep.yml, license: other, allowed: false
    - license needs review: other

* Hello Rails 8.bundler.nio4r
  version: 2.7.4, filename: ./rails/hello8/.licenses/bundler/nio4r.dep.yml, license: other, allowed: false
    - license needs review: other

* Hello Rails 8.bundler.ostruct
  version: 0.6.1, filename: ./rails/hello8/.licenses/bundler/ostruct.dep.yml, license: other, allowed: false
    - license needs review: other

* Hello Rails 8.bundler.racc
  version: 1.8.1, filename: ./rails/hello8/.licenses/bundler/racc.dep.yml, license: other, allowed: false
    - license needs review: other

* Hello Rails 8.bundler.rdoc
  version: 6.7.0, filename: ./rails/hello8/.licenses/bundler/rdoc.dep.yml, license: other, allowed: false
    - license needs review: other

* Hello Rails 8.bundler.reline
  version: 0.5.11, filename: ./rails/hello8/.licenses/bundler/reline.dep.yml, license: other, allowed: false
    - license needs review: other

* Hello Rails 8.bundler.securerandom
  version: 0.3.2, filename: ./rails/hello8/.licenses/bundler/securerandom.dep.yml, license: other, allowed: false
    - license needs review: other

* Hello Rails 8.bundler.stringio
  version: 3.1.2, filename: ./rails/hello8/.licenses/bundler/stringio.dep.yml, license: other, allowed: false
    - license needs review: other

* Hello Rails 8.bundler.timeout
  version: 0.4.2, filename: ./rails/hello8/.licenses/bundler/timeout.dep.yml, license: other, allowed: false
    - license needs review: other

* Hello Rails 8.bundler.uri
  version: 1.0.2, filename: ./rails/hello8/.licenses/bundler/uri.dep.yml, license: other, allowed: false
    - license needs review: other

* Hello Rails 8.bundler.websocket-driver
  version: 0.7.6, filename: ./rails/hello8/.licenses/bundler/websocket-driver.dep.yml, license: other, allowed: false
    - license needs review: other

* Hello Rails 8.bundler.websocket-extensions
  version: 0.1.5, filename: ./rails/hello8/.licenses/bundler/websocket-extensions.dep.yml, license: other, allowed: false
    - license needs review: other


87 dependencies checked, 25 errors found.

Licensed found errors during source enumeration.  Please see https://github.com/github/licensed/tree/master/docs/commands/status.md#status-errors-and-resolutions for possible resolutions.

Ok, we found 25 errors – many in Rails and Ruby dependencies! Is that correct? The answer is Yes and No, and we’ll get into that soon.

Generating a Third Party Notices file

Once we have the dependencies identified and cached, we can use Licensed to also generate a third-pary notices file.

$ licensed notices
Writing notices for Hello Rails 8 to ./rails/hello8/.licenses/NOTICE

You can open up the file and take a look. The picture below shows a snippet of it.

Note that the dependencies identified as errors will also have their licenses included.

Dealing with Errors

There are a few ways to handle errors, depnding on the root cause. At a high level, the general strategy is as in the table below.

In all cases, once you edit and save the configuration file, you can run licensed cache and licensed status again to see the number of errors drop.

Let’s look at a few samples and how to decide what to do.

Case 1: Internal Package

We do not have such a case in our basic Rails app.

Case 2: Compatible License but with a different name

We do not have such a case in our basic Rails app, but this may be when something is called a different license (e.g., “The Software Package License” which is compatible with, as an example, “MIT License”).

Case 3: Compatible License but does not have a clear name

A lot of Ruby’s libraries fall under this group. In our case, examples are uri, timeout, ostruct etc. all of which have a COPYING file that look like this:

Ruby is copyrighted free software by Yukihiro Matsumoto <matz@netlab.jp>.
You can redistribute it and/or modify it under either the terms of the
2-clause BSDL (see the file BSDL), or the conditions below:

1. You may make and give away verbatim copies of the source form of the
    software without restriction, provided that you duplicate all of the
    original copyright notices and associated disclaimers.

2. You may modify your copy of the software in any way, provided that
    you do at least ONE of the following:
...

Case 4: License file was not found

* Hello Rails 8.bundler.logger
  version: 1.6.1, filename: ./rails/hello8/.licenses/bundler/logger.dep.yml, license: other, allowed: false
    - missing license text
    - license needs review: other

We expect that the logger has a friendly license but you can see it is identified as other – we need to review and look into it. A good place to start is the YAML file that is shown in the output: .licenses/bundler/logger.dep.yml – let’s open it and take a look at the contents that licensed cached.

1
2
3
4
5
6
7
8
9
---
name: logger
version: 1.6.1
type: bundler
summary: Provides a simple logging utility for outputting messages.
homepage: https://github.com/ruby/logger
license: other
licenses: []
notices: []

1
2
3
4
5
6
7
8
# These dependencies have licenses not on the `allowed` list and have been reviewed.
# They will be cached and checked, but will not raise errors or warnings for a
# non-allowed license.  Dependencies on this list will still raise errors if
# license text cannot be found for the dependency.
reviewed:
  bundler:
    - bcrypt-ruby
    - logger

* Hello Rails 8.bundler.logger
  version: 1.6.1, filename: D:/projects/blog/_posts-trials/rails/hello8/.licenses/bundler/logger.dep.yml, license: other, allowed: false
    - missing license text

* Hello Rails 8.bundler.activerecord
  version: 8.0.0, filename: D:/projects/blog/_posts-trials/rails/hello8/.licenses/bundler/activerecord.dep.yml, license: other, allowed: false
    - license needs review: other

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
---
name: activerecord
version: 8.0.0
type: bundler
summary: Object-relational mapper framework (part of Rails).
homepage: https://rubyonrails.org
license: other
licenses:
- sources: MIT-LICENSE
  text: |
    Copyright (c) David Heinemeier Hansson

    Arel originally copyright (c) 2007-2016 Nick Kallen, Bryan Helmkamp, Emilio Tagua, Aaron Patterson

    Permission is hereby granted, free of charge, to any person obtaining
    a copy of this software and associated documentation files (the
    "Software"), to deal in the Software without restriction, including
    < -- snip 14 lines -->
- sources: README.rdoc
  text: |-
    Active Record is released under the MIT license:

    * https://opensource.org/licenses/MIT
notices: []

$ licensee detect d:\Ruby33-x64\lib\ruby\gems\3.3.0\gems\activerecord-8.0.0
License:        NOASSERTION
Matched files:  MIT-LICENSE, README.rdoc
MIT-LICENSE:
  Content hash:  b8776133984f1a45b28e48f68c21647676d802ed
  License:       NOASSERTION
  Closest non-matching licenses:
    MIT similarity:    84.55%
    MIT-0 similarity:  66.14%
    NCSA similarity:   60.27%
README.rdoc:
  Content hash:  5bc0714f35dc5896f8f22a338fe45ec7aaab364d
  Confidence:    90.00%
  Matcher:       Licensee::Matchers::Reference
  License:       MIT
  Closest non-matching licenses:
    WTFPL similarity:          7.69%
    Zlib similarity:           2.27%
    BlueOak-1.0.0 similarity:  2.12%

Arel originally copyright (c) 2007-2016 Nick Kallen, Bryan Helmkamp, Emilio Tagua, Aaron Patterson

1
2
3
4
5
6
7
8
# These dependencies have licenses not on the `allowed` list and have been reviewed.
# They will be cached and checked, but will not raise errors or warnings for a
# non-allowed license.  Dependencies on this list will still raise errors if
# license text cannot be found for the dependency.
reviewed:
  bundler:
    - bcrypt-ruby
    - activerecord

Copyright 2014-2020 James Coglan

Licensed under the Apache License, Version 2.0 (the "License"); you may not use
this file except in compliance with the License. You may obtain a copy of the
License at

    http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed
under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR
CONDITIONS OF ANY KIND, either express or implied. See the License for the
specific language governing permissions and limitations under the License.