fossa-cli

README

fossa-cli - Fast, portable, and reliable dependency analysis for any codebase.

Background

fossa analyzes complex codebases to generate dependency reports and license notices. It can generate fast and highly-accurate results, by leveraging existing build environments. Refer to the FOSSA CLI User Manual for in depth information about using this tool.

Features:

• Supports over 20+ languages & environments (JavaScript, Java, Ruby, Python, Golang, PHP, .NET, etc...)
• Auto-configures for monoliths; instantly handles multiple builds in large codebases.
• Fast & portable; a cross-platform binary you can drop into CI or dev machines.
• Generates offline documentation for license notices & third-party attributions.
• Tests dependencies against license violations, audits and vulnerabilities (coming soon!) by integrating with https://fossa.com.

Installation

The following commands will execute scripts to fetch and install the latest GitHub Releases on the corresponding operating system.

Install with Homebrew (MacOS or Linux):

brew install fossas/tap/fossa

MacOS (Darwin) or Linux amd64:

curl -H 'Cache-Control: no-cache' https://raw.githubusercontent.com/fossas/fossa-cli/master/install.sh | bash

This command will install the FOSSA CLI into usr/local/bin. If you do not have permissions to access this folder you may specify the directory you would like by modifying to command to:

curl -H 'Cache-Control: no-cache' https://raw.githubusercontent.com/fossas/fossa-cli/master/install.sh | bash -s -- -b <custom directory>

Windows with Powershell:

Set-ExecutionPolicy Bypass -Scope Process -Force; iex  ((New-Object System.Net.WebClient).DownloadString('https://raw.githubusercontent.com/fossas/fossa-cli/master/install.ps1'))

Add C:\ProgramData\fossa-cli to your path by modifying your profile.ps1 file or temporarily with the following command:

$env:Path += ";C:\ProgramData\fossa-cli"

Quick Start

Run fossa and provide a FOSSA API Key to create a local configuration file and analyze the project. The project information will be uploaded and a link to a rich, hosted report on fossa.com will be output:

FOSSA_API_KEY="YOUR_API_KEY_HERE" fossa

# Output:
# ==========================================================
#
#    View FOSSA Report: https://app.fossa.com/{YOUR_LINK}
#
# ==========================================================

Note: Running fossa is equivalent to running fossa init followed by fossa analyze.

Documentation

If you run into a problem using the FOSSA CLI, most issues can be resolved by looking at our documentation in the FOSSA CLI User Manual. This will shed light to how we analyze specific ecosystems and how to accurately configure your project.

If you have questions please refer to the FAQ. If your question is related to a bug or feature please open an issue on GitHub. You can also reach out to fossa directly at support@fossa.com.

If you are interested in learning more about FOSSA you can visit our homepage at fossa.com and look at our online documentation.

Supported Environments

Environment	Package Managers
Android	Gradle
Clojure	Leiningen
Debian	Dpkg
Golang	Dep, Gomodules, Vndr, GDM, Glide, Godep, Govendor
Groovy	Gradle
Haskell	Cabal and Stack
Java	Gradle, Maven, Ant
Javascript	nodejs & npm
Kotlin	Gradle
Monorepo tooling	okbuck, Buck
.NET	NuGet, Paket
Objective-C	Cocoapods, Carthage
PHP	Composer
Python	Pip, Pipenv, requirements.txt
Ruby	Bundler
Rust	Cargo
Scala	SBT
Swift	Cocoapods, Carthage
C, C++	Archive Uploader

If your development environment is not supported, check out the archive uploader which allows direct license scanning of source code files.

Click here to learn more about the technical details behind this project.

Configuration

fossa init # writes to `.fossa.yml`

Running fossa init will create a hidden configuration file called .fossa.yml which looks like this:

version: 1
cli:
  server: https://app.fossa.com
  fetcher: custom
  project: github.com/fossas/fossa-cli
analyze:
  modules:
    - name: fossa-cli
      type: go
      target: github.com/fossas/fossa-cli/cmd/fossa
      path: ./cmd/fossa

Check out the User Guide to learn about editing this file.

After configuration, you can now analyze the project and upload new results:

# Run FOSSA analysis and preview the results to be uploaded.
fossa analyze -o

# Run FOSSA and upload results
# Going forward, you only need to run this one-liner
FOSSA_API_KEY=YOUR_API_KEY_HERE fossa analyze

Integrating with CI

Testing for License Violations

If you've integrated with https://fossa.com, you can use fossa test to fail builds against your FOSSA scan status.

# Exit with a failing status and dump an issue report to stderr
# if your project fails its license scan
FOSSA_API_KEY=YOUR_API_KEY_HERE fossa test

# Output:
# --------------------------
# - exit status (1)
#
# * FOSSA discovered 7 license issue(s) in your dependencies:
#
# UNLICENSED_DEPENDENCY (3)
# * pod+FBSnapshotTestCase$1.8.1
# * pod+FBSnapshotTestCase$2.1.4
# * pod+Then$2.1.0
#
# POLICY_FLAG (4)
# * mvn+com.fasterxml.jackson.core:jackson-core$2.2.3
# * npm+xmldom$0.1.27
# * pod+UICKeyChainStore$1.0.5
# * gem+json$1.7.7
#
# ✖ FOSSA license scan failed: 7 issue(s) found.

Generating License Notices

You are able to generate a license notice with each CI build using the fossa report command:

# write a license notice to NOTICE.txt
fossa report licenses > NOTICE.txt

See this repo's NOTICE file for an example.

License data is provided by https://fossa.com's 500GB open source registry.

Development

View our Contribution Guidelines to get started.

License

fossa is Open Source and licensed under the MPL-2.0.

You are free to use fossa for commercial or personal purposes. Enjoy!