fossa/fossa-cli repository overview

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.

⁠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"

Make to sure to have your FOSSA API Key⁠ set as an environment variable

$env:FOSSA_API_KEY = "YOUR_API_KEY_HERE"

⁠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}
#
# ==========================================================

⁠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 [email protected]⁠.

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

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!