Skip to content

Latest commit

 

History

History
112 lines (82 loc) · 4.27 KB

fossa-deps.md

File metadata and controls

112 lines (82 loc) · 4.27 KB
Raw

fossa-deps

fossa-deps file is a file named fossa-deps.{yaml, yml, json} at the root of the project. It can be used to provide manual and vendor dependencies.

Fields

referenced-dependencies:

Denotes listing of dependencies, which are to be analyzed in conjunction with the analysis.

  • type: Type of dependency. (Required)
  • name: Name of the dependency. It should be the same name as listed in dependencies registry. (Required)
  • version: Revision of the dependency. If left unspecified, the latest version discovered from the registry will be used.
referenced-dependencies:
- type: gem
  name: iron
- type: pypi
  name: Django
  version: 2.1.7

For more details, please refer to the feature walk through.

custom-dependencies:

Denotes listing of dependencies, which can't be automatically discovered or identified but are to be stubbed and included in the analysis.

  • name: Name of the dependency. (Required)
  • version: Revision of the dependency. (Required)
  • license: License of the dependency. (Required)
  • metadata.homepage: Homepage of the dependency. This metadata is used to enrich reporting provided in FOSSA's web interface.
  • metadata.description: Description of the dependency. This metadata is used to enrich reporting provided in FOSSA's web interface.

Example:

- name: foo-wrapper
  version: 1.2.3
  license: MIT
  metadata:
    homepage: https://www.foowrapper.com/about
    description: Provides foo and a helpful interface around foo-like tasks.

For more details, please refer to the feature walk through.

remote-dependencies:

Denotes listing of dependencies, whose source code is to be downloaded from provided URL, and analyzed for license scanning in FOSSA backend.

  • name: Name of the dependency. (Required)
  • version: Revision of the dependency. (Required)
  • url: URL of archived source code. (Required)
  • metadata.homepage: Homepage of the dependency. This metadata is used to enrich reporting provided in FOSSA's web interface.
  • metadata.description: Description of the dependency. This metadata is used to enrich reporting provided in FOSSA's web interface.

For more details, please refer to the feature walk through.

vendored-dependencies:

Denotes listing of files or directories, which are to be archived and uploaded to FOSSA backend for license scanning.

  • name: Name of the dependency (Required)
  • path: Local path to a file, or a directory (Required)
  • version: Revision of the dependency. If not specified, the md5 hash of the file path will be used.
vendored-dependencies:
- name: Django
  path: vendor/Django-3.4.16.zip
  version: 3.4.16

Note: License scanning currently operates by uploading the files at the specified path to a secure S3 bucket. All files that do not contain licenses are then removed after 2 weeks.

For more details, please refer to the feature walk through.

Errors in the fossa-deps file

The fossa-deps scanner tries to report clear error messages when fields are missing, incorrect, or invalid. For example:

referenced-dependencies:
- type: pypi
  name: flask
  version: "2.0.1"
  license: MIT  # Error!  "license" is only allowed for custom-dependencies

custom-dependencies:
- type: custom  # Error!  "type" is only allowed for referenced-dependencies
  name: mydep
  version: "3.14.15"
  license: GPL-3.0

remote-dependencies:
- name: mydep
  version: "3.14.15"
  license: GPL-3.0 # Error! "license" is only allowed for custom-dependencies

This would return an error with a message explaining what went wrong, and where. However, we don't check for everything (yet!):

referenced-dependencies:
- type: cargo
  name: bitflags
  some-unexpected-field: hello  # Has no effect, will be considered an error in future versions.

The fossa-deps scanner also requires at least one valid dependency if the file exists. This prevents the file from being created with the wrong array names and us silently ignoring them.

If you see an error message that isn't clear, file an issue in this repository! Clear error messages are a priority for us, and we want to know where we're lacking.