Skip to content

Latest commit

 

History

History
451 lines (319 loc) · 20.2 KB

fossa-yml.md

File metadata and controls

451 lines (319 loc) · 20.2 KB

.fossa.yml

The fossa configuration file, .fossa.yml, is an optional file located at the root of a project that can be used to configure project settings.

The following example is a configuration file with all available fields filled displayed. All fields except for version are optional, configuration file versions 1 and 2 were used for CLI versions prior to 2.0.0.

version: 3

server: https://app.fossa.com
apiKey: a1b2c3

project:
  locator: custom+1/github.com/fossas/fossa-cli
  id: github.com/fossas/fossa-cli
  name: fossa-cli
  team: cli-team
  teams: 
    - cli-team-1
    - cli-team-2
  policy: custom-cli-policy
  link: fossa.com
  url: github.com/fossas/fossa-cli
  jiraProjectKey: jira-key
  releaseGroup:
    name: release-group-name
    release: 123-release-candidate
  labels:
    - project-label-1
    - test-project

releaseGroup:
  title: release-group-title
  release: release-group-release
  releaseGroupProjects:
    - projectLocator: custom+123/[email protected]/fossas/fossa-cli
      projectRevision: "12345"
      projectBranch: master 
    - projectLocator: custom+123/[email protected]/example
      projectRevision: "67890"
      projectBranch: master
  licensePolicy: license-policy-name
  securityPolicy: security-policy-name
  qualityPolicy: quality-policy-name
  teams:
    - team1
    - team2


revision:
  commit: "12345"
  branch: master

vendoredDependencies:
  forceRescans: false
  scanMethod: CLILicenseScan
  licenseScanPathFilters:
    only:
      - "**/*.rb"
    exclude:
      - ".git/**"
      - "test/**/*.rb"

targets:
  only:
    - type: maven
      path: foo/bar
  exclude:
    - type: bundler

paths:
  only:
    - ./vendor/django
    - ./test
  exclude:
    - ./vendor/django/test

telemetry:
  scope: full

customLicenseSearch:
  - matchCriteria: "[Pp]roprietary [Ll]icense"
    name: "Proprietary License"

experimentalKeywordSearch:
  - matchCriteria: "[Pp]roprietary and [Cc]onfidential"
    name: "Proprietary and Confidential match"

Fields

version:

Specifies the version of configuration file. Versions 1 and 2 were used by CLI versions up until CLI 2.0.0 and are no longer supported. Version 3 is the current supported version for FOSSA CLI v2.

server:

Sets the endpoint that the CLI will send requests to. This field should only be modified if your FOSSA account lives on a different server than app.fossa.com. This is most commonly needed with on-premise instances of FOSSA.

Default: https://app.fossa.com

apiKey:

Sets the FOSSA API key that is required for accessing the FOSSA API and uploading data (e.g. fossa analyze) or retrieving information (e.g. fossa test) about a project.

Note: FOSSA strongly recommends setting the API key with the $FOSSA_API_KEY environment variable and NOT in the configuration file for security purposes.

telemetry:

Sets the telemetry configurations.

telemetry.scope:

Sets the telemetry scope to value. Accepted values are 'full' or 'off'.

  • When 'full' is provided - CLI will emit telemetry data to server.
  • When 'off' is provided - CLI will not emit telemetry data to server.
# Example .fossa.yml
# Does not emit telemetry to server.

version: 3
telemetry:
  scope: off

project:

The project fields allow you to configure settings for the project you are interacting with through the FOSSA API.

Note: name, team, policy, link, and jiraProjectKey can only be set when creating a project (running fossa analyze for the first time). Otherwise, they will be silently ignored (we would like to make this a visible warning in the future).

project.locator:

The project Locator defines a unique ID that the FOSSA API will use to reference this project within FOSSA. The project locator can be found in the UI on the project Settings page listed as the Project Locator underneath the Project Title setting.

project.id:

The project ID defines an ID that is used to reference a project within your FOSSA organization. The project ID is a specific portion of the project locator and can be found in the UI on the project Settings page listed as the "Project Locator" underneath the "Project Title" setting. For example, if the "Project Locator" value of custom+1/foo is provided in the FOSSA UI, use foo for the project.id.

Default:

  • Git: The CLI will look for a .git/config file and set the ID to the project's remote "origin" url.
  • SVN: The CLI will run svn info and use the "Repository Root".
  • No VCS (Version control system): The ID will be set to the name of the project's directory.

NOTE: A project's ID cannot be modified after a project is created. If you change the ID, you will be interacting with a different project. If the new ID does not exist, a new project will be created for it.

project.name:

The name field sets the projects visible name in the FOSSA dashboard. By default, this will be set to the project's ID.

project.team:

The name of the team in your FOSSA organization to associate this project with.

project.teams:

The name of the teams in your FOSSA organization to associate this project with.

NOTE: Currently, ONLY fossa project edit utilizes this field. Use fossa project edit to add a project to all teams in the list.

project.policy:

The name of the policy in your FOSSA organization to associate this project with. Mutually excludes project.policyId. If a policy is provided on the command line using --policy then that value will override this one.

project.policyId:

The id of the policy in your FOSSA organization to associate this project with. Mutually excludes project.policy. If a policy is provided on the command line using --policy-id then that value will override this one.

project.link:

An external link that will appear in the FOSSA UI for this specific project.

project.url:

The URL of your project that will appear in FOSSA. This URL is intended to be the URL to the repository of this project.

project.jiraProjectKey:

The Jira Project Key to associate with your project for improved issue triage. Refer to the FOSSA docs for more information.

project.releaseGroup:

The name: and release: of the release group's release to add your project to in the FOSSA dashboard.

If you choose to associate a project with a release group, you must supply both name and release.

project.labels:

The labels field allows you to add labels to projects so that you can classify certain projects how you would like. This adds a more flexible way to query for projects in the FOSSA UI as opposed to assigning a project to a team.

Up to 5 labels are allowed to be associated with a project at a time. Labels will be applied in order up to the limit of 5 labels and then ignored.

releaseGroup:

The releaseGroup field allows you to configure settings for the release group you are interacting with through the FOSSA API.

NOTE: releaseGroup configurations are only allowed for fossa release-group create and fossa release-group add-project. This is done so that release groups are not mistakenly deleted.

NOTE: release-group command line options will always take precedence over configurations set in fossa.yml.

releaseGroup.title:

The title of the release group which can be seen in the FOSSA dashboard.

releaseGroup.release:

The release associated with the release group.

releaseGroup.releaseGroupProjects:

The projects associated with the release group's release.

NOTE: At least one project must be specified upon creating a release group.

NOTE: projectLocator , projectRevision, and projectBranch must all be specified when providing a releaseGroupProject.

releaseGroup.releaseGroupProjects.projectLocator:

The project locator defines a unique ID that the FOSSA API will use to reference this project within FOSSA. The project locator can be found in the UI on the project Settings page listed as the Project Locator underneath the Project Title setting.

releaseGroup.releaseGroupProjects.projectRevision:

The revision associated with a project. Project revisions can be found in the UI on the project Activity page. Refer to Revision ID to retrieve the specific revision you want to use for the project.

releaseGroup.releaseGroupProjects.projectBranch:

The branch associated with the project.

releaseGroup.licensePolicy:

The name of the license policy associated with the release group. Refer to the documentation for addition details on license policies.

releaseGroup.securityPolicy:

The name of the security policy associated with the release group. Refer to the documentation for addition details on security policies.

releaseGroup.qualityPolicy:

The name of the quality policy associated with the release group. Refer to the documentation for addition details on quality policies.

releaseGroup.teams:

A list of team names that are associated with the release group.

revision:

The revision fields are used to help FOSSA differentiate between one upload for a project and another, just as GitHub uses commit hashes and branch names.

revision.commit:

The commit is used to identify a specific scan for a project (determined by project.id). This is intended to be used identically to how Git treats commit hashes.

Default:

  • Git: the CLI will parse the current HEAD state in the .git directory and use the commit hash of the HEAD branch
  • SVN: The CLI will run svn info and use the "Revision".
  • No VCS: The commit will be set to the unix timestamp.

revision.branch:

project branch is an optional setting used for organizing project revisions in the FOSSA UI. The branch field is intended to function similar to how Git defines a branch.

Default:

  • Git: the CLI will attempt to find the project's current branch from the .git/config file.
  • SVN: The CLI will run svn info and compare the "URL" and "Repository Root" fields in an attempt to determine a branch.
  • No VCS: The CLI will leave the branch field empty.

vendoredDependencies:

The vendoredDependencies section is an optional section that configures how we scan vendored dependencies. Please see the documentation for vendored dependencies for more information on what they are and how to set up a scan for them.

vendoredDependencies.forceRescans

forceRescans is an optional setting that, if true, forces a re-scan of all vendored dependencies on every run. If false or not present, then we do not re-scan vendored dependencies that have been previously scanned. A vendored dependency has been previously scanned if a dependency with the same name and version has already been scanned by your organization. If no version is provided, then any change in the files being scanned will result in a rescan.

vendoredDependencies.scanMethod

The scanMethod setting determines whether your vendored dependencies are scanned using the "Archive Upload" or the "CLI License Scan" method.

The possible values are ArchiveUpload or CLILicenseScan.

If this setting is not present, then we will use the default for your organization. This is most likely "CLI License Scan", but it is possible that your organization has changed the default to "Archive Upload".

For a description of what these methods are and the difference between them, see the documentation for vendored dependencies.

vendoredDependencies.licenseScanPathFilters

Path filtering can be used to omit some files or directories from license scanning.

For more details, see the vendored-dependencies feature reference.

targets:

The targets filtering section allows you to specify the exact targets which be should be scanned.

Targets are listed in the following formats for both only and exclude lists.

    - type: maven
      path: foo/bar
    - type: pipenv (all pipenv type targets at any path)

targets.only:

The list of only targets that should be scanned. When used alongside paths.only, the intersection of the two lists is taken to find targets for scanning

targets.exclude:

The list of exclude targets which should be excluded from scanning. The targets listed in the exclude section will override the targets listed in the only sections. This feature is used most effectively to remove specific targets from a directory.

Example: You have a directory called docker which contains 3 different targets but you would like to omit the one with type bundler. You can do this with the following configuration:

targets:
  exclude:
    - type: bundler
      path: prod/docker

paths:

The paths filtering section allows you to specify which paths should be scanned and which should not. The paths should be listed as their location from the root of your project.

paths:
  only:
    - prod
  exclude:
    - prod/vendor

paths.only:

The list of paths to only allow scanning within.

This section is most commonly used when you would like to restrict scanning to a certain list of directories from the root of your project. If you have a directory structure such as the following and would only like to scan targets located in the production directory, paths.only enables this:

/production
/development
/test

paths.exclude:

The list of paths to exclude from scanning in your directory.

This section is intended to be used as the inverse to paths.only. If you have a certain directory such as development you wish to exclude, paths.exclude enables you to do this.

Analysis target configuration

Analysis target configuration allows you to select a very specific subset of your directory for scanning. The targets and paths sections allow users to configure which targets and directories should be scanned. This is useful if you have a custom test directory or development projects within the root project.

Analysis target configuration determines which targets should be scanned with the following logic:

  1. Targets that match the targets.only and paths.only sections are unioned to create a list of targets to be scanned.
  2. Targets remaining after the only step that match the targets.exclude and paths.exclude sections are removed from the list of targets to be scanned.
    • If no targets were listed in the only sections, exclude will remove targets from the list of all available targets.
  3. Analysis is run on the remaining targets.

For detailed walkthrough, and example please refer to analysis target configuration walkthrough

Project target configuration example

Run the command fossa list-targets to determine the analysis targets present in your project. The output will look similar to the following with the targets in format type@path (You may see that duplicated lines for "Found target" and "Found project"):

Found target: bundler@prod/docker
Found target: bundler@prod
Found target: yarn@prod
Found target: yarn@prod/docker
Found target: yarn@prod/vendor
Found target: pipenv@prod
Found target: pipenv@prod/vendor
Found target: pipenv@dev

From here, we identify the parts of this example project that we want to scan:

  • We ONLY want targets located in the prod directory. This would also ensure that the the dev directory is never scanned. (paths.only: prod)
    • Except for the vendored dependencies. (paths.exclude: prod/vendor)
  • We want the targets inside prod/docker, except for bundler@prod/docker which is used to build the image. 
    exclude:
  - type: bundler
    path: prod/docker

Combining these individual filters together results in the following configuration:

targets:
  exclude:
    - type: bundler
      path: prod/docker

paths:
  only:
    - prod
  exclude:
    - prod/vendor

The above configuration and list of targets will result in the following targets being scanned:

Found target: bundler@prod
Found target: yarn@prod
Found target: yarn@prod/docker
Found target: pipenv@prod

Filtering by Maven Dependency Scope

You can provide maven dependency scopes that you would like to filter. You can filter by either inclusion or exclusion. When both scope-only and scope-exclude are provided, scope-only will take precedence and be used for filtering.

scope-only:

The list of only scopes that should by scanned.

When a dependency is multi-scope (i.e. [compile, runtime]) ALL of the scopes must be conatined in scope-only for the dependency to be included in the scan results.

scope-exclude:

The list of exclude scopes that you would like to exclude from scanning.

When a dependency is multi-scope (i.e. [compile, runtime]), if ANY of the scopes are contained in scope-exclude it will be excluded from the scan results.

version: 3

maven:
  scope-only:
    - compile
    - runtime
## OR
  scope-exclude:
    - provided
    - system
    - test

FAQ

Why are some configuration settings (name, team, policy, etc.) ignored by the FOSSA API after a project has already been created?

The purpose of allowing a user to set policy, team, and other settings in the configuration file is to make it easy for users to share configuration files within their teams when creating many different projects. If these configuration settings were allowed to modify a project every time they were set on the CLI they could disrupt anyone managing the project in the FOSSA UI. Example: I change a project from Team A to Team B in the FOSSA UI. The project is then scanned nightly in a CI environment and my UI team change is reverted. This behavior would be very difficult for someone managing the project only in the FOSSA UI to diagnose and fix.

What is the difference between project ID and project locator?

In the CLI, project ID refers to a specific portion of a project locator. When running fossa analyze on a project for the first time, if project ID is not directly configured, it will default to:

  • Git: The CLI will look for a .git/config file and set the ID to the project's remote "origin" url.
  • SVN: The CLI will run svn info and use the "Repository Root".
  • No VCS (Version control system): The ID will be set to the name of the project's directory.

After project ID is set, the CLI will use that value to construct a project locator on first time analysis. A project locator is a unique ID that the FOSSA API will use to reference a project across FOSSA.

NOTE: Projects uploaded through the CLI will have custom embedded into the project locator.

When do I use project ID vs project locator?

Project ID should be used when referencing projects uploaded via the CLI. In most cases, providing just a project ID is sufficient. However, when referencing projects uploaded through avenues outside the CLI (Quick Import, Archive Upload, etc), providing just a project ID fails. This is due to the nature of FOSSA's project naming conventions as project locators are constructed differently depending on how a project was uploaded. There is no way to tell at runtime which project a user is referencing when only given a project ID (i.e. Is this a project uploaded via the CLI or Archive Upload?).

In fossa release-group project locator is used to reference projects that will be added to your release group's release. By using project locator, all FOSSA project upload flows are covered and the CLI is able to determine the specific project a user is trying to add to a release.