CLI Cheat Sheet
Quick start guide to help choose the appropriate CLI command and parameters for a given use case.
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=XXXX
OR --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 12 months ago