Skip to content

Latest commit

 

History

History
181 lines (132 loc) · 10.2 KB

analyze.md

File metadata and controls

181 lines (132 loc) · 10.2 KB
Raw

fossa analyze

By default, the analyze command:

  • looks for projects in the current directory (and recursively in subdirectories)
  • extracts dependency graphs from those projects
  • infers a project name, branch, and revision for the project (from git or svn)
  • uploads the dependency graphs to FOSSA

For supported command-line flags, use fossa analyze --help

Specifying FOSSA project details

In addition to the usual FOSSA project flags supported by all commands, the analyze command supports the following FOSSA-project-related flags:

Name Short Description
--title 'some title' -t Set the title of the FOSSA project
--branch 'some branch' -b Override the detected FOSSA project branch
--project-url 'https://example.com' -P Add a URL to the FOSSA project
--jira-project-key 'some-key' -j Add a Jira project key to the FOSSA project
--link 'https://example.com' -L Attach a link to the current FOSSA build
--team 'some team' -T Specify a team within your FOSSA organization
--policy 'some policy' Assign a specific FOSSA policy to this project
--config /path/to/file -c Path to a configuration file including filename. By default we look for .fossa.yml in target directory of analyze command.

Printing results without uploading to FOSSA

The --output flag can be used to print projects and dependency graph information to stdout, rather than uploading to FOSSA

fossa analyze --output

Printing project metadata

The --json flag can be used to print project metadata after running fossa analyze successfully. This metadata can be used to reference your project when integrating with the FOSSA API.

fossa analyze --json
{"project":{"name":"custom@new-project","branch":"master","revision":"123","url":"https://app.fossa.com/projects/custom+<org-id>/new-project/refs/branch/master/123","id":"custom+<org-id>/new-project$123"}}

Running in a specific directory

fossa analyze path/to/directory

Scanning archive contents

With the --unpack-archives flag present, we unpack discovered archives to a temporary directory for dependency analysis. We recursively unpack archives-in-archives.

fossa analyze --unpack-archives

We support the following archive formats:

  • .zip
  • .tar
  • .tar.gz
  • .tar.xz
  • .tar.bz2
  • .jar
  • .rpm, with...
    • gzip compression
    • lzma compression
    • xz compression
    • zstd compression

Enabling additional strategies

In addition to the standard flags, the analyze command supports the following additional strategy flags:

Name Description
--detect-vendored Enable the vendored source indentification engine. For more information, see the C and C++ overview.
--detect-dynamic './some-binary Analyze the binary at the provided path for dynamically linked dependencies. For more information, see the C and C++ overview.

Experimental Options

Important: For support and other general information, refer to the experimental options overview before using experimental options.

In addition to the standard flags, the analyze command supports the following experimental flags:

Name Description
--experimental-enable-binary-discovery Enable reporting binary files as unlicensed dependencies. For more information, see the binary discovery overview.
--experimental-link-project-binary './some-dir' Link the provided binary files to the project being analyzed. For more information, see the multi stage builds overview.
--experimental-skip-vsi-graph 'custom+1/some$locator' Skip resolving the dependencies of the given project that was previously linked via --experimental-link-project-binary.
--experimental-enable-monorepo 'monorepo-type' Scan the project in monorepo mode. For more information, see the monorepo overview.

F.A.Q.

  1. Why is the fossa-cli skipping my project?

fossa-cli may sometimes report a project of interest was skipped from the analysis. For example,

[ INFO] Scan Summary
[ INFO] ------------
[ INFO] 3 projects scanned;  2 skipped,  1 succeeded,  0 failed,  1 analysis warning
[ INFO] 
[ INFO] * setuptools project in "sandbox/": succeeded with 1 warning
[ INFO] * setuptools project in "sandbox/example/": skipped (production path filtering)
[ INFO] * setuptools project in "sandbox/external/": skipped (exclusion filters)

fossa-cli skips analysis, if and only if

  • (a) Target is excluded via fossa configuration file (this filtering is referred to as "exclusion filters").
  • (b) Target is skipped because the fossa-cli does not consider the target to be a production target (this filtering is referred to as "production path filtering").

fossa-cli skips any target per (b), if the target is found within the following directories:

  • dist-newstyle
  • doc/
  • docs/
  • test/
  • example/
  • examples/
  • vendor/
  • node_modules/
  • .srclib-cache/
  • spec/
  • Godeps/
  • .git/
  • bower_components/
  • third_party/
  • third-party/
  • Carthage/
  • Checkouts/

As fossa-cli relies on manifest and lock files provided in the project's directory, we intentionally skip node_modules/ and such directories. If fossa-cli discovers and analyzes project found in node_modules/: fossa-cli will not be able to infer the dependency's scope (development or production) and may double count dependencies.

  1. Can fossa-cli detect licensed/copyright content downloaded at runtime by dependencies?

Unfortunately, as of yet, fossa-cli cannot discover or analyze any licensed or copyrighted content retrieved at runtime by dependencies when it is not referenced in manifest or lock files.

For example, in python with datasets package,

from datasets import load_dataset
dataset = load_dataset("bigscience/P3", revision="f2cade2") # retrieved at runtime

In this case, fossa-cli would not be able to identify bigscience/P3 and its associated compliance obligation since they were not part of the manifest or lockfile - e.g. requirements.txt, setup.py, poetry.lock.

In this scenario, if the inclusion of bigscience/P3 is desired in FOSSA's reporting, we recommend fossa-deps.yml file to explicitly include bigscience/P3 in FOSSA's reporting. Likewise, you can also download huggingface.co/datasets/bigscience/P3 to disk and use vendor dependency scanning.

# Example fossa-deps.yml

custom-dependencies:
- name: huggingface.co/datasets/bigscience/P3
  version: "f2cade2"
  license: "Apache-2.0"

If you need more assistance, please contact FOSSA support.

  1. How do I ensure fossa analyze does not exit fatally when no targets are discovered?

In some scenarios, you may want to configure the fossa analyze and fossa test CI workflow on an empty repository or directory with 0 targets. Unfortunately, fossa-cli does not have a configuration yet, which will allow for successful analysis (exit code of 0) when 0 targets are discovered.

For a workaround, create an empty reqs.txt file before running fossa analyze, which will force fossa-cli to presume an empty pip project (with 0 dependencies).

touch reqs.txt && fossa analyze && rm reqs.txt && fossa test