ideaplexus/license-audit repository overview

⁠licaudit

Audit the licenses of your dependencies: detect the dependencies of a project, determine their licenses as SPDX expressions and check them against a policy. Written in Go as a maintained replacement for LicenseFinder⁠.

⁠Ecosystems

Where a build tool resolves better than its files do (go, mvn, gradle, sbt, conan, cargo), licaudit runs it if it is installed (--resolver auto) and otherwise reads the files with a warning; --resolver static never runs tools.

⁠Installation

⁠Install script

The script installs the latest release for Linux or macOS on amd64 or arm64 to /usr/local/bin, using sudo if needed, and verifies its checksum:

curl -sSfL https://ideaplexus.gitlab.io/license-audit/install.sh | sh

It needs curl or wget and is configured with environment variables:

# Install a specific version
curl -sSfL https://ideaplexus.gitlab.io/license-audit/install.sh | LICAUDIT_VERSION=0.1.0 sh

# Install into another directory, e.g. without sudo
curl -sSfL https://ideaplexus.gitlab.io/license-audit/install.sh | BINDIR="$HOME/.local/bin" sh

Without sudo and write access to BINDIR, it installs to ~/.local/bin. LICAUDIT_BASE_URL points it to a mirror of the project.

⁠Binaries

Download the archive for your platform from the releases⁠. There are binaries for Linux, macOS and Windows on amd64 and arm64, named licaudit_<version>_<os>_<arch>.tar.gz, and a file with their checksums.

⁠Go

go install gitlab.com/ideaplexus/license-audit/cmd/licaudit@latest

⁠Docker

A multi-arch image for amd64 and arm64 is available on Harbor, Docker Hub (docker.io/ideaplexus/license-audit) and Quay (quay.io/ideaplexus/license-audit):

docker run --rm -v "$PWD:/src" harbor.ideaplexus.com/ideaplexus/license-audit:latest licenses MIT

The image is based on scratch and only contains the binary, CA certificates and the license notices. It has no package managers, so licaudit resolves dependencies statically there and warns where Gradle, Maven or sbt would give a more complete result.

⁠Usage

licaudit scan                                    # table of the packages that are not allowed
licaudit scan -o json=licaudit.json -o markdown=$GITHUB_STEP_SUMMARY -o junit=licaudit.xml
licaudit scan -o notice=THIRD_PARTY_NOTICES.md   # attribution file for distribution
licaudit scan -o sarif=licaudit.sarif -o html=licaudit.html -o csv-excel=licenses.csv
licaudit scan -o cyclonedx=sbom.cdx.json -o spdx=sbom.spdx.json   # SBOMs with licenses
licaudit scan --diff main.json -o markdown       # only new or changed packages
licaudit scan --platform linux/amd64,darwin/arm64,windows/amd64   # dependencies of the target platforms
licaudit explain lodash                          # evidence and decision of a package
licaudit approve npm:caniuse-lite --license CC-BY-4.0 --reason "data only"
licaudit import licensefinder doc/dependency_decisions.yml > .licaudit.yaml
licaudit licenses --category network-copyleft
licaudit normalize "Apache License, Version 2.0" GPLv2+ UNLICENSED

licaudit reads installed dependencies (vendor/, node_modules, the Go module cache, virtual environments, vendor/bundle, the NuGet packages folder) directly; in CI run it after the install step and it needs no network. Packages that are not installed can be looked up online with --sources local,registry,depsdev,clearlydefined (opt-in, because package names and versions are sent to these services; answers are cached).

⁠Configuration

Without a configuration the preset oss applies: open source licenses only, network copyleft (AGPL) denied, strong copyleft (GPL) a warning. A .licaudit.yaml in the scanned directory adjusts it:

version: 1
extends: [preset:oss-distributed]   # GPL denied as well, for distributed software
scan:
  scopes: {include: [runtime]}
policy:
  licenses: {warn: [LGPL-*]}
decisions:
  ignore:
    - package: "go:gitlab.com/acme/**"
      reason: own code
  approve:
    - package: "npm:caniuse-lite"
      licenses: [CC-BY-4.0]
      reason: data only, attribution in the NOTICE file
      approved_by: jane.doe
      expires: 2027-11-03

licaudit config validate checks it, licaudit config show prints the merged result. See docs/config-design.md⁠ for all options. licaudit scan exits with 1 if the policy is violated (--strict: also on warnings).

⁠License categories

public-domain, permissive, weak-copyleft, strong-copyleft, network-copyleft, patent-license, free-restricted, proprietary-free, source-available, non-commercial, commercial, unstated, unknown.

They are derived from the ScanCode LicenseDB⁠ plus manual corrections in data/overrides.yaml⁠ (e.g. AGPL, EUPL, OSL-3.0 as network-copyleft). Categories are technical classifications, not legal advice.

⁠Development

The targets run the playbooks of ideaplexus/ansible-dev-tools⁠, as in CI (make init once):

make check       # lint and test
make build
make data        # re-download SPDX / ScanCode / ORT data into data/
make snapshot    # goreleaser: binaries and images, without publishing
make hooks       # once: pre-commit hook against caches, executables and large files
make check-repo  # the same check on all tracked files, as in CI

Fuzzing of the manifest and lockfile parsers and the benchmark of a monorepo with 6000 npm packages run on demand:

go test ./internal/ecosystem -run '^$' -fuzz FuzzAnalyzers -fuzztime 5m
go test ./internal/cli -run '^$' -bench ScanLargeMonorepo -benchtime 3x

Tests that run tools with HOME in test data must not leave caches behind; tools/repocheck rejects them, along with executables and files larger than 1 MiB.

CI and releases run on Forgejo Actions (.forgejo/workflows/build.yml); gitlab.com mirrors the repository, hosts the releases and serves the install script via GitLab Pages. Changes are recorded in CHANGELOG.md⁠.

Documentation: Configuration design⁠ · Report formats⁠

⁠License

MIT⁠. Third-party software and data: THIRD_PARTY_NOTICES.md⁠.