Project: FOSSA (Provisioning / Security & Compliance)
File: fossa-yml.md

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. ```yaml 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/git@github.com/fossas/fossa-cli projectRevision: "12345" projectBranch: master projectLocator: custom+123/git@github.com/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" ``` 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. 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` Sets the 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 `$FOSSAAPIKEY` environment variable and NOT in the configuration file for security purposes. Sets the telemetry configurations. 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. ```yaml version: 3 telemetry: scope: off ``` 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). 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. <img src="../../assets/project-locator-example.png"> 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"

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. <img src="../../assets/project-id-example.png"> The name field sets the projects visible name in the FOSSA dashboard. By default, this will be set to the project's ID. The name of the team in your FOSSA organization to associate this project with. The name of the teams in your FOSSA organization to associate this project with. NOTE: Currently, ONLY `fossa project edit` utilizes this field. Use to add a project to all teams in the list. 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. 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. An external link that will appear in the FOSSA UI for this specific project. The URL of your project that will appear in FOSSA. This URL is intended to be the URL to the repository of this project. The Jira Project Key to associate with your project for improved issue triage. Refer to the for more information. 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. 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. 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`. The title of the release group which can be seen in the FOSSA dashboard. <img src="../../assets/release-group-title-example.png"> The release associated with the release group. <img src="../../assets//release-example.png"> 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. 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. <img src="../../assets/project-locator-example.png"> The revision associated with a

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. <img src="../../assets//project-revision-example.png"> The branch associated with the project. The name of the license policy associated with the release group. Refer to the for addition details on license policies. The name of the security policy associated with the release group. Refer to the for addition details on security policies. The name of the quality policy associated with the release group. Refer to the for addition details on quality policies. A list of team names that are associated with the release group. 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. 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. 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. The `vendoredDependencies` section is an optional section that configures how we scan vendored dependencies. Please see the for more information on what they are and how to set up a scan for them. `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. 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 . Path filtering can be used to omit some files or directories from license scanning. For more details, see the . 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. ```yaml type: maven path: foo/bar type: pipenv (all pipenv type targets at any path) ``` The list of `only` targets that should be

When used alongside `paths.only`, the intersection of the two lists is taken to find targets for scanning 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: ```yaml targets: exclude: type: bundler path: prod/docker ``` 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. ```yaml paths: only: prod exclude: prod/vendor ``` 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 ``` 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 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: Targets that match the `targets.only` and `paths.only` sections are unioned to create a list of targets to be scanned. 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. Analysis is run on the remaining targets. For detailed walkthrough, and example please refer to 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

```yaml exclude: type: bundler path: prod/docker ``` Combining these individual filters together results in the following configuration: ```yaml 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 ``` 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. 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. 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. ```yaml version: 3 maven: scope-only: compile runtime scope-exclude: provided system test ``` 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. 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. <img src="../../assets/project-id-example.png"> 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. <img src="../../assets/project-locator-example.png"> 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.