OPEN FOSSA APP

CLI Cheat Sheet

Quick start guide to help choose the appropriate CLI command and parameters for a given use case.

Suggest Edits

👍

Recommended for Technical Users

This method requires use of a Command Line Interface and knowledge of your codebase. If you're not a developer yourself, we recommend getting a developer to help you—or you can try our Quick Import method.

Authenticate

export FOSSA_API_KEY=XXXXOR --fossa-api-key=XXX in a CLI command
OR add the apiKey to .fossa.yml. Sample below:

version: 3
server: https://app.fossa.com
apiKey:XXXX

How to generate a API key :

See here

A guide for choosing your options based on use cases

  • Understand what options are available : fossa analyze --help
  • Scanning 3rd party open source dependencies : fossa analyze
  • Scanning your own proprietary code : fossa analyze --experimental-force-first-party-scans .
  • Scanning Vendored code : fossa analyze --detect-vendored . This uses VSI. See docs here.
  • Scanning binaries: fossa analyze ~/projects/my-project --detect-dynamic ~/projects/my-project/out/my-project-bin
    See docs here.

CLI common options

fossa analyze

Looks for projects in current directory & recursively in subdirectories. And creates a project in FOSSA UI. See docs here.

If you want to create a project in your team use:

fossa analyze -T ‘Team Name’

fossa test

Use after fossa analyze to check if the most recent scan returned license issues or vulns. Returns an exit code, so can be used in a script. Typically used in a CI/CD pipeline. See docs here.

A commons use case is in CI pipelines to know if the latest revision is bringing in any net new issues

fossa test --diff revisionToCompare

Using the --diff flag only report new issues observed with the current revision that weren't already reported on the specified revisionToCompare.

fossa report

fossa report attribution --format cyclonedx-json

See docs here. The report command downloads a report of the most-recent scan of your FOSSA project. This command is usually run immediately after fossa analyze or test

Specify dependencies

Referenced Dependencies

Manually specify type, name. Find both Licenses & vulnerabilities in the referenced deps. Use sample below in fossa-deps.yml. Version is optional.

referenced-dependencies:
- type: gem
  name: iron
- type: pypi
  name: Django
  version: "2.1.7"

Vendored Dependencies

It runs FOSSA's license scanner on the directories specified and reports licenses found but not vulnerabilities. See docs here. Used to scan for licenses in your vendored dependencies, which may have been missed by normal analysis that relies on package manager info.

Use sample below in fossa-deps.yml. Path can be either a file or a folder. 

vendored-dependencies:
- name: Django
  path: vendor/Django-3.4.16.zip 
  url: https://www.fooarchive.tar.gz
  version: "3.4.16" # revision will be set to the MD5 hash of the

Remote Dependencies

Runs scan on remote bundle of code specified rather than on a local directory.Used when you can point to a URL of source code. Use sample below in fossa-deps.yml. Require name, version, and URL fields. Does not find vulnerabilities.

remote-dependencies:
- name: foo
  version: 1.2.3
  url: https://www.fooarch.tar.gz

Custom Dependencies

Used to manually specify a license. Does not find vulns. Use sample below in fossa-deps.yml.

Custom dependencies need name, version, and license

custom-dependencies:
- name: foo
  version: "1.2.3"
  license: "MIT or Apache-2.0"

Snippet scanning

fossa snippets analyze -o snippets
This subcommand extracts snippets from a user project and compares them to the FOSSA database of snippets. Any matches are then written to the directory provided.

See docs here.

fossa snippets commit --analyze-output

The result of this subcommand is a fossa-deps file written to the root of the project directory.

See docs here.

Other cases

First party scans

Allows you to scan for licenses in your own code.

fossa analyze --experimental-force-first-party-scans

fossa list-targets

The list targets command lists all valid analysis targets in a directory. This output can be useful to understand what is going to be analyzed when fossa analyze is run. See docs here.

Container scan

fossa container analyze centos:7

Scanning Archives

Sample command: fossa analyze --unpack-archives

This option will unpack archives including rpm, tar, zip. See docs here.

Vendored Source Code

Sample command:
fossa analyze --detect-vendored

See docs here.

Policies

Add/Exclude policy

  --policy ARG     #The name of the policy to assign to this project in FOSSA. Mutually excludes --policy-id.
  --policy-id ARG  #The id of the policy to assign to this project in FOSSA. Mutually excludes --policy.

Reports

Generate attribution report

The report command downloads a report of the most-recent scan of your FOSSA project. This command is usually run immediately after fossa analyze or fossa test. See docs here.

fossa report attribution --endpoint <Your FOSSA endpoint> --project-url <project_name> --branch <branch> --revision <revision> --format json > fossa-<project_name>-report.json

Troubleshooting

Debug

Creates a debug bundle to be analyzed by a FOSSA team member.

fossa analyze –-debug

See docs here.

Help

Using --help will print available options.

fossa analyze --help

Updated 6 months ago