# FOSSA Documentation

> Documentation for FOSSA, the platform for open source license compliance, vulnerability management, SBOMs, and dependency health.

Source: https://docs.fossa.com/docs/get-started

# Get Started

**Over 80% of the code in a modern application comes from open source.** Every one of those components carries license, security, and quality implications you're responsible for. FOSSA plugs into your existing workflow to automatically track, manage, and remediate them, so your team ships faster with less risk.

{% callout type="info" %}
Create an account [on our website](https://app.fossa.com/auth/login), or [request a demo](https://fossa.com/demo/). This guide takes you from zero to your first results.
{% /callout %}

## What you can do with FOSSA

- **[Stay license-compliant](/docs/licenses):** detect every license obligation and generate the attribution documents you're required to ship.
- **[Monitor security](/docs/vulnerabilities):** surface and prioritize vulnerabilities in your dependencies, with real-world exploit signals.
- **[Catch quality issues](/docs/quality):** flag outdated, abandoned, or risky components before they bite.
- **[Enforce policy](/docs/policies):** codify what's allowed and fail CI/CD automatically when something isn't.

## The fastest path to results

You're four steps from a fully monitored project:

{% steps %}
{% step title="Import your project" %}
Get your code into FOSSA. **[Quick Import](/docs/project-setup/quick-import)** connects your source host and scans hundreds of repos in a click; **[CLI](/docs/project-setup/cli)** runs in your build for the most accurate results. See all [import methods](/docs/project-setup).
{% /step %}
{% step title="Run a scan" %}
FOSSA analyzes your dependencies, automatically on import or each time you run `fossa analyze`. No extra setup required.
{% /step %}
{% step title="Review your results" %}
Explore what FOSSA found: [Licenses](/docs/licenses), [Vulnerabilities](/docs/vulnerabilities), and [Quality](/docs/quality) signals across your project.
{% /step %}
{% step title="Automate it" %}
Set [Policies](/docs/policies) and add a check to your [CI/CD pipeline](/docs/integrations) so new risk is caught on every build, not after release.
{% /step %}
{% /steps %}

## Start here

- **[Your First Scan](/docs/get-started/your-first-scan):** the hands-on five-minute walkthrough, from account to first results.
- **[CLI vs Quick Import](/docs/get-started/cli-vs-quick-import):** not sure which import method to use? Start here.
- **[Project Setup](/docs/project-setup):** every way to get code and artifacts into FOSSA.

## Need a hand?

Reach the team at [support@fossa.com](mailto:support@fossa.com) or through [our support site](https://support.fossa.com). Building on top of FOSSA? See the [API Reference](/docs/api) and [Integrations](/docs/integrations).

---

Source: https://docs.fossa.com/docs/get-started/your-first-scan

# Your First Scan

By the end of this guide you'll have a FOSSA account, your first project imported and scanned, and a clear view of its licenses and vulnerabilities, in about five minutes.

## 1. Create your account

Sign up at the [FOSSA signup page](https://app.fossa.com/auth/login). You can register with email or through GitHub, Bitbucket, or GitLab.

{% callout type="tip" %}
If you'll import via a source host, sign up with that provider (e.g. GitHub). It connects automatically, saving a step later. You can connect or disconnect providers anytime.
{% /callout %}

## 2. Import your first project

In FOSSA, go to **Projects → Add Project** and choose an import method:

- **[Quick Import](/docs/project-setup/quick-import)**: connect a source host and import repositories in a click. The fastest way to get broad coverage.
- **[CLI](/docs/project-setup/cli)**: run `fossa analyze` in your build for the most accurate results and no code access for FOSSA.

Not sure which? See **[CLI vs Quick Import](/docs/get-started/cli-vs-quick-import)**. You can also import [containers](/docs/project-setup/containers), [binaries](/docs/project-setup/binaries), or an [SBOM](/docs/project-setup/sbom-import).

{% callout type="info" %}
Once import finishes, your project appears in the **Projects** list with a scan in progress.
{% /callout %}

## 3. Read your first scan

When the scan completes, open the project. Each FOSSA project is organized into tabs; which tabs you see depends on your plan and whether you're logged into your organization.

| Tab | What it shows |
|---|---|
| **Summary** | High-level counts and status: total dependencies, license count, and issue summary. The starting point for any project. |
| **Issues** | License violations, compliance alerts, and security vulnerabilities flagged against your policy. |
| **Inventory** | All components FOSSA discovered. Has three sub-tabs: **Dependencies** (direct and transitive packages with licenses), **Snippets** ([Snippet Scanning](/docs/cli/features/snippet-scanning) results), and **Vendored** ([Vendored Dependencies](/docs/cli/features/vendored-dependencies) results). |
| **Licenses** | Every license detected across your dependency tree, deduplicated and searchable. |
| **Reports** | Tools to generate attribution notices, SBOMs, and compliance documentation for distribution. |

{% img src="/images/reading-scan-results-project-summary.png" alt="FOSSA project Summary tab showing 64 issues broken down by vulnerabilities and license issues, with dependency and license counts in the sidebar" /%}

{% callout type="enterprise" %}
The **Snippets** and **Vendored** sub-tabs are gated behind a feature flag and may not be enabled for your organization by default. Reach out to your account team to request access.
{% /callout %}

### Sanity-check your dependency list

Before digging into issues, open the **Inventory → Dependencies** tab and review what FOSSA found. On a first scan, the total number of dependencies, including transitive ones, is often larger than expected.

{% callout type="info" %}
If you see many test or documentation packages, FOSSA may be running against a non-production build. Verify that you're analyzing a production artifact, or configure [`.fossa.yml`](https://github.com/fossas/fossa-cli/blob/master/docs/references/files/fossa-yml.md) to exclude the paths you don't want scanned.
{% /callout %}

Dig into the findings by category: [Licenses](/docs/licenses), [Vulnerabilities](/docs/vulnerabilities), and [Quality](/docs/quality).

## 4. Automate it

Make FOSSA catch new risk on every build instead of after release:

- Define a **[Policy](/docs/policies)** for the licenses and vulnerabilities your organization allows.
- Add a check to your **[CI/CD pipeline](/docs/integrations)** so builds fail when a policy is violated.

## What's next

- Tune how each project is scanned in [Project Setup](/docs/project-setup).
- Bundle related projects with [Release Groups](/docs/release-groups).
- Generate attribution and compliance documents in [Reports](/docs/reports).

---

Source: https://docs.fossa.com/docs/get-started/cli-vs-quick-import

# CLI vs Quick Import

When you first integrate with FOSSA, start with **[Quick Import](/docs/project-setup/quick-import)**, the fastest way to import projects and get a feel for the dependencies and licenses in your code. Depending on your build, you may then want the **[CLI](/docs/project-setup/cli)** for deeper accuracy. Two differences drive that choice.

## Static vs dynamic analysis

- **Static analysis** parses the files in your project to infer dependencies and their relationships. Quick Import (and the Broker) use static analysis only.
- **Dynamic analysis** uses your actual build tools (e.g. the Maven or Gradle CLIs) to learn exactly what's included. The CLI supports **both** static and dynamic analysis, which makes it more accurate for complex builds. (See the CLI's [analysis strategies](/docs/cli/references/strategies).)

## Custom license scans and keyword matches

Custom License Scans and keyword matches let you define strings that FOSSA treats as a license. These are supported only with provided builds: that is, the **CLI**.

## At a glance

| | Quick Import | FOSSA CLI |
| :--- | :--- | :--- |
| Setup speed | Fastest: connect and go | Requires a working build |
| Analysis | Static only | Static **and** dynamic |
| Accuracy on complex builds | Good | Best |
| Code access for FOSSA | FOSSA pulls your code | None; uploads signatures only |
| Custom license / keyword scans | No | ✅ |
| Ignore paths / dependency types | Limited | Fine-grained control |
| Best for | Broad coverage across many repos | Accuracy on specific projects, CI |

## Recommendation

Use **Quick Import** for speed and breadth, especially when onboarding many repositories at once. Switch to the **CLI** for any project where you need the full range of analysis strategies, custom features, or want to avoid granting code access. Many teams use both: Quick Import for coverage, the CLI where accuracy matters most.

## What's next

- **[Quick Import](/docs/project-setup/quick-import)**: Get started with the fastest setup method to import and analyze your repositories.
- **[CI/CD Scanning](/docs/project-setup/cicd-scanning)**: Set up the FOSSA CLI in your pipeline for deeper dependency analysis.
- **[Supported Languages](/docs/project-setup/supported-languages)**: Check which languages and package managers are supported before choosing a scanning method.

---

Source: https://docs.fossa.com/docs/project-setup

# Project Setup

Before FOSSA can flag a license obligation or a vulnerability, it needs to know what's actually in your software. **Project setup is how you get that dependency data in.**

FOSSA meets your code where it lives, but the methods aren't equal. Running the **[CLI](/docs/project-setup/cli)** in your build sees the same dependency graph your package manager resolves (including transitive and build-time dependencies) so it's the most accurate and complete picture FOSSA can get. Wiring that into **[CI/CD](/docs/project-setup/cicd-scanning)** keeps every project current automatically and gates risky changes before they merge. That's the path we recommend for any project you care about.

{% callout type="tip" %}
Run **[`fossa analyze`](/docs/project-setup/cli)** as a step in your **[CI/CD pipeline](/docs/project-setup/cicd-scanning)**. You get the most accurate results, automatic re-scans on every build, and [PR checks](/docs/project-setup/pr-checks) that catch new risk before it merges, without granting FOSSA access to your source.
{% /callout %}

## Choose your import method

| If you want to… | Use | How it works |
| :--- | :--- | :--- |
| Get the most accurate results, or avoid giving FOSSA code access | **[CLI](/docs/project-setup/cli)** | Analyze locally or in CI; upload only dependency signatures |
| Keep every project current and gate risky changes | **[CI/CD scanning](/docs/project-setup/cicd-scanning)** | Run the CLI in your pipeline with PR checks |
| Analyze container images | **[Containers](/docs/project-setup/containers)** | `fossa container analyze` on Docker or OCI images |
| Find open source copied into your own code | **[Snippets](/docs/project-setup/snippets)** | CLI fingerprinting that surfaces undeclared open source |
| Analyze a binary without its source | **[Binaries](/docs/project-setup/binaries)** | Upload a compiled artifact for decomposition · Enterprise |
| Analyze components from an existing SBOM | **[SBOMs](/docs/project-setup/sbom-import)** | Upload a CycloneDX or SPDX document · Enterprise |
| Get broad, low-effort coverage to start | **[Quick Import](/docs/project-setup/quick-import)** | Connect your VCS; FOSSA pulls and analyzes the code |

## Scan with the FOSSA CLI

The [FOSSA CLI](/docs/cli) analyzes your build and uploads only dependency signatures, the most accurate and secure path, and the right choice whenever you can grant FOSSA a place in your build.

- **[CLI](/docs/project-setup/cli)**: run `fossa analyze` against your build for full dependency analysis.
- **[CI/CD scanning](/docs/project-setup/cicd-scanning)**: run that analysis automatically on every build, with [PR checks](/docs/project-setup/pr-checks) that gate merges.
- **[Containers](/docs/project-setup/containers)**: scan Docker and OCI container images for license and vulnerability issues.
- **[Snippets](/docs/project-setup/snippets)**: detect open source code copied into your first-party source, and the obligations it carries.

## Quick Import, broad coverage, fast

When you need coverage across many repositories with minimal setup, **[Quick Import](/docs/project-setup/quick-import)** connects GitHub, GitLab, Bitbucket, or Azure Repos and analyzes your repositories directly, wiring up webhooks and scheduled re-scans. It's the fastest way to get started and FOSSA never writes to your code, but because it analyzes source without running your build, its results are less complete than a CLI scan. Treat it as a quick start or a fallback for projects you can't put in CI, and move your important projects to the CLI when you can.

Behind a firewall? **[Broker](/docs/project-setup/broker)** imports repositories from Bitbucket Server, on-prem GitLab, or GitHub Enterprise without sharing source-code access.

## Upload an artifact

When you have a built artifact but not its source, hand it to FOSSA directly:

- **[Binaries](/docs/project-setup/binaries)**: decompose pre-compiled binaries and archives to identify the open source inside. *(Enterprise)*
- **[SBOMs](/docs/project-setup/sbom-import)**: bring in an existing CycloneDX or SPDX SBOM and run compliance checks against its components. *(Enterprise)*

## Configure and organize

Once a project is imported, you control how it's scanned: the build and analysis method, which targets are included, scan scheduling, and project-level settings. Use **[Release Groups](/docs/release-groups)** to bundle related projects and revisions for shared reporting and policy enforcement.

From here, your data flows into [Licenses](/docs/licenses), [Vulnerabilities](/docs/vulnerabilities), [Quality](/docs/quality), and [SBOM](/docs/sbom).

---

Source: https://docs.fossa.com/docs/project-setup/cli

# CLI

The most accurate way to integrate FOSSA is to analyze your code locally with the [FOSSA CLI](/docs/cli), our open source build client. It requires a working build, but it's the most performant, accurate, and secure integration method.

Pick this method if:

- You don't want to give FOSSA servers access to your code (for IT, policy, or logistical reasons).
- You need accurate, performant build results.
- You already have a configured build environment in CI or on a local dev machine.
- You tried [Quick Import](/docs/project-setup/quick-import) for a project but need more advanced configuration or build analysis for the accuracy you want.

{% callout type="info" %}
This method uses a command-line interface and knowledge of your codebase. If you're not a developer, ask one to help, or try [Quick Import](/docs/project-setup/quick-import) instead.
{% /callout %}

## Getting started

{% steps %}
{% step title="Start a local integration" %}
In FOSSA, click **Integrate Locally (CLI)** to begin importing your project.

{% img src="/images/project-setup/cli-integrate-locally.png" alt="FOSSA Add Projects page showing the Integrate Locally (CLI) option marked as Recommended" /%}
{% /step %}

{% step title="Install the CLI" %}
Click **View Guide** for the in-product instructions, then install the client with the one-line command for your platform. See [Installing FOSSA CLI](/docs/cli/walkthroughs/installing-fossa-cli) for the full guide (including Windows).

{% tabs %}
{% tab name="macOS / Linux" %}
```bash
curl -H 'Cache-Control: no-cache' https://raw.githubusercontent.com/fossas/fossa-cli/master/install-latest.sh | bash
```
{% /tab %}
{% tab name="Windows" %}
```powershell
@"%SystemRoot%\System32\WindowsPowerShell\v1.0\powershell.exe" -NoProfile -InputFormat None -ExecutionPolicy Bypass -Command "iex ((New-Object System.Net.WebClient).DownloadString('https://raw.githubusercontent.com/fossas/fossa-cli/master/install-latest.ps1'))"
```
{% /tab %}
{% /tabs %}

{% img src="/images/project-setup/cli-install-guide.png" alt="FOSSA in-product CLI guide showing steps to install fossa-cli, set an API key, and run an analysis" /%}
{% /step %}

{% step title="Analyze your project" %}
From your project root, run `fossa analyze`. The CLI uses your existing build environment to perform build and dynamic analysis, giving better accuracy than static analysis on complex codebases. See [Supported Languages](/docs/cli/references/strategies) for configuration details.
{% /step %}
{% /steps %}

## What gets uploaded

Using the CLI is **secure**: it grants FOSSA no code access and sends only public dependency signatures to `app.fossa.com`. Output exactly what would be uploaded with:

```bash
fossa analyze -o
```

For the full breakdown, see [What data gets uploaded](/docs/cli/walkthroughs/what-data-gets-uploaded).

---

Source: https://docs.fossa.com/docs/project-setup/cicd-scanning

# CI/CD Scanning

CI/CD scanning is the preferred integration model when you already have a working build environment. Instead of FOSSA running its own build of your code, you install the FOSSA CLI into your existing CI pipeline and upload dependency data directly. FOSSA receives a perfect replica of your build's actual dependency graph, no guessing, no false positives.

Once a project has been uploaded via `fossa analyze`, it becomes a provided build project. FOSSA no longer runs automated builds on it; updates are driven entirely by how often your CI runs and uploads new results.

## Why use CI/CD scanning

**Advantages:**

- Matches your exact build behavior, no unused test or dev dependencies in results
- Works with large, complex builds that are hard to replicate in FOSSA's environment
- No code access required; FOSSA never clones or scans your source
- Higher priority processing, so results arrive faster

**Trade-offs:**

- FOSSA cannot trigger a new dependency analysis from the UI; a new CI run is required. You can still run a **policy scan** from the UI to re-evaluate existing dependency data against updated policies
- Requires the FOSSA CLI to be added to your build pipeline

## Quickstart

{% steps %}
{% step title="Install the FOSSA CLI" %}
Follow the [CLI installation guide](/docs/cli/walkthroughs/installing-fossa-cli) to install `fossa` on your CI machine or developer workstation.
{% /step %}
{% step title="Analyze your project" %}
Run the following after a successful build:

```bash
FOSSA_API_KEY=<your_api_key> fossa analyze
```

This uploads your project's dependency graph to FOSSA. Run it after the build completes so that the full dependency tree is captured. Analysis runs asynchronously. You can continue with tests while it processes.
{% /step %}
{% step title="Check for issues" %}
```bash
fossa test
```

Blocks until analysis is complete, then fails the build if any license or security issues are found. Run this after your tests.
{% /step %}
{% /steps %}

## Integrating into CI

The typical fully-integrated CI workflow:

1. Revision is pushed to your Git host
2. CI clones the repository and runs the build
3. Build succeeds and produces a production artifact
4. `fossa analyze` runs and uploads the dependency graph
5. CI runs tests; `fossa test` checks for FOSSA issues and fails the build if any are found
6. If all checks pass, the revision is deployed or merged

For platform-specific setup, see the [integrations](/docs/integrations) guides (including [GitHub Actions](/docs/integrations/github-actions), [Jenkins](/docs/integrations/jenkins), [GitLab](/docs/integrations/gitlab), and [CircleCI](/docs/integrations/circleci)) or [Generic CI](/docs/integrations/generic-ci) for any other system.

{% callout type="info" %}
For security, pass `FOSSA_API_KEY` as an environment variable rather than storing it in `.fossa.yml`.
{% /callout %}

## Configuration

For projects with complex builds, custom module definitions, or monorepos, configure FOSSA's analysis using a `.fossa.yml` file in your project root. See the [configuration reference](/docs/cli/references/files/fossa-yml) for details.

## Performance and accuracy

CI/CD scanning consistently outperforms automated builds for large or complex projects:

- FOSSA processes provided builds at higher priority and skips resource-intensive build steps
- Analysis operates inside your existing environment, eliminating false positives from test dependencies, build configuration differences, and non-deterministic build behavior
- Explicit module definitions let you exclude irrelevant targets (docs, test modules) from the report

## Limitations

- **Private dependencies**: dependencies behind a firewall or requiring authentication still need to be accessible from your FOSSA instance for license and vulnerability analysis

## Troubleshooting

#### Upload fails on an unpublished branch

FOSSA uses VCS revision detection to associate the upload with a branch. If the revision hasn't been pushed to your Git host yet, FOSSA can't find it.

Run `fossa analyze` on a published branch, or pass the revision explicitly:

```bash
fossa analyze --revision <commit-hash>
```

#### `git` not available in the CI environment

Without `git`, the CLI can't infer the project name or revision.

Pass them explicitly:

```bash
fossa analyze --project my-project --revision 1.0.0
```

#### Analysis succeeds but results look wrong

The CI environment may include test or dev dependencies that aren't in your production build.

Ensure the environment is clean and mirrors your production build configuration before running `fossa analyze`. Ideally, run it immediately after your production build step.

#### On-premises: analysis fails to connect

The CLI may be pointing at the wrong server or using the wrong API key.

Check that `server` and `apiKey` in your `.fossa.yml` point at your local FOSSA instance. Verify the configuration works locally before debugging CI.

## What's next

- **[Issue Scanners](/docs/project-setup/issue-scanners)**: Configure which categories of issues (licensing, security, quality) are detected and how they gate your builds.
- **[Pull Request Checks](/docs/project-setup/pr-checks)**: Set up status checks to block merges when `fossa test` detects unresolved issues.
- **[Automatic Updates](/docs/project-setup/automatic-updates)**: Configure how FOSSA re-analyzes your project when new code is pushed or on a schedule.

---

Source: https://docs.fossa.com/docs/project-setup/pr-checks

# Pull Request Checks

FOSSA can report a GitHub status check on every pull request, blocking merges when new license compliance or security issues are detected. Setup depends on how the project was imported.

{% img src="/images/project-setup/pr-checks-settings-general.png" alt="FOSSA Settings > Projects > General page showing GitHub Status Check timeout and failure mode configuration" /%}

## Enabling PR checks via Quick Import

When you import a repository using Quick Import, FOSSA automatically creates the required webhooks. No additional setup is needed, every PR you open against that repository will trigger two checks:

- **License Compliance**: fails if the PR introduces unresolved license policy violations
- **Security**: fails if the PR introduces new unresolved vulnerabilities

A **Details** link on the GitHub status check navigates directly to the FOSSA UI for the affected revision so you can review and resolve the issues.

## Enabling PR checks via CLI upload

{% steps %}
{% step title="Import the project via the CLI" %}
Run `fossa analyze` from your project root. After a successful upload, FOSSA detects the GitHub repository and displays a banner on the project summary page prompting you to set up GitHub status checks.
{% /step %}
{% step title="Configure GitHub status checks" %}
Click the banner to open the setup flow. Follow the prompts to connect the project to GitHub. Once connected, every PR will trigger the same License Compliance and Security checks as Quick Import projects.
{% /step %}
{% /steps %}

## GitHub Status Check configuration

Timeout and failure mode settings for GitHub status checks are configured at the organization level under **Settings > Projects > General**.

| Setting | Description |
|---|---|
| **Timeout for automated builds** | How long FOSSA waits for an automated scan to complete before applying the failure mode |
| **Timeout for provided builds** | How long FOSSA waits for a CLI-uploaded build to complete before applying the failure mode |
| **Failure mode** | What FOSSA reports if analysis does not complete within the timeout: **Show a failure status** (fail closed (blocks the PR) or **Show a success status** (fail open) allows the PR through) |

Changes to these settings can be propagated to all existing projects using the **Propagate** button on the same page.

## What's next

- **[Automatic Updates](/docs/project-setup/automatic-updates)**: Configure how and when FOSSA triggers the scans that feed into your PR checks.
- **[Issue Scanners](/docs/project-setup/issue-scanners)**: Control which issue types (licensing, security, quality) fail your CI/CD checks.

---

Source: https://docs.fossa.com/docs/project-setup/badge-pull-requests

# Badge Pull Requests

{% callout type="info" %}
Badge PRs are available only for public GitHub repositories imported via Quick Import.
{% /callout %}

When importing a GitHub project, enable **Submit badge PRs after import (public GitHub READMEs only)** and FOSSA opens a pull request adding a license-scan status badge to your README as soon as the project imports. See [Webpack's README](https://github.com/webpack/webpack/blob/0e404b8683d79052e3a6b42743bd3061f17a5a5d/README.md#license) for an example.

FOSSA adds a badge near the top of the README and a more detailed badge at the bottom. You never need to update it; FOSSA refreshes it automatically when the README loads, keeping it in sync with your default branch.

{% img src="/images/project-setup/badge-pull-requests-github-readme.png" alt="FOSSA CLI GitHub README showing downloads, build status, dependency scan, and security scan badges" /%}

## Adding a badge without Quick Import

For private repositories, CLI-imported projects, or any project where you want to place the badge yourself, copy the snippet from **Project Settings → General → Embed Status Badge** and paste it into your README manually. See [Automatic Updates](/docs/project-setup/automatic-updates#embedding-a-status-badge) for details.

{% img src="/images/project-setup/badge-pull-requests-embed-badge.png" alt="Project Settings General page showing the Embed Status Badge panel with badge type tabs and a copyable Markdown snippet" /%}

---

Source: https://docs.fossa.com/docs/project-setup/containers

# Containers

Container scanning identifies open source **license and vulnerability issues** inside your container images. It follows the same FOSSA CLI conventions as a normal analysis, so it's familiar if you already run `fossa analyze`.

## Running a scan

Set your API key and point the CLI at a local Docker image, an OCI image archive, or a remote image reference:

```bash
FOSSA_API_KEY=<your_api_key> \
fossa container analyze <your image: docker | image.tar>
```

Large images may take a minute to analyze. Container scanning accepts the same arguments as `fossa analyze`, for example `--title`, `--team`, and `--policy`. Run `fossa container analyze --help`, or see the [container subcommand reference](/docs/cli/references/subcommands/container) for the full list of flags.

## Supported base images

FOSSA supports most popular base images and any container built on them:

| Package manager | Distributions |
| :-------------- | :------------ |
| Apt / Apt-Get   | Debian, Ubuntu |
| RPM / Yum       | CentOS, Oracle Linux, Fedora, SLES (beta) |
| Apk             | Alpine, Wolfi |

Because Wolfi is supported, `fossa container analyze` also scans **Chainguard** images.

{% callout type="info" %}
FOSSA does not raise a *"Container OS is not supported"* error. Distributions not listed above can still analyze successfully; it just isn't guaranteed.
{% /callout %}

## How FOSSA finds your image

You don't need to specify the image type: FOSSA accepts either a Docker image straight from your local Docker application or a Docker-format image archive on disk, and detects which it's working with.

### Docker images and registries

When given a Docker image name, FOSSA requests the image from Docker and parses it, accepting images in exactly the same form as `docker pull`: first your local Docker repository, then Docker Hub, then any registries you've authenticated to with `docker login`. You can also pull directly from a repository, for example, `fossa container analyze quay.io/coreos/dnsmasq`.

### Exported image archives

FOSSA reads exported image archives from your filesystem. The archive must be in Docker format (containing a top-level `manifest.json`), as produced by `docker save` or `docker image save`. Scan it exactly as you would a Docker image.

FOSSA does not read OCI-layout archives directly from disk. An OCI-layout archive has an `oci-layout` marker plus `index.json` and `blobs/`, with no top-level `manifest.json`, so scanning it fails with `TarballFileNotFound: "manifest.json"`. Tooling such as Buildah or Packer can emit this layout, so either convert to Docker format first (for example, `buildah push <image> docker-archive:image.tar`, or build with `--format=docker`) or pull the image from a registry instead.

---

Source: https://docs.fossa.com/docs/project-setup/snippets

# Snippets

Snippet Scanning identifies where sections of your first-party source code may have originated from open source projects, and what license obligations that may create. Rather than only analyzing declared package dependencies, it examines the actual contents of your code files to find matches against a database of open source code.

This is useful when:

- Your codebase includes code copied or adapted from open source libraries without being declared as a dependency.
- You want license compliance to cover code that was inlined, vendored, or manually incorporated.
- You need a more complete picture of the open source components present in your software.

## How it works

When you run a snippet scan, FOSSA:

1. **Fingerprints your source files**: the FOSSA CLI generates a fingerprint for each file in your project.
2. **Matches against an open source code index**: fingerprints are compared against a database of known open source code.
3. **Resolves matched packages**: FOSSA identifies and builds the open source packages behind the matches, so license and issue data is available for them.
4. **Surfaces results in the UI**: matches appear in the **Snippets** tab of your project inventory, with their license and issue information.

## Running a snippet scan

Snippet scanning runs through the FOSSA CLI with the `--snippet-scan` flag:

```bash
fossa analyze --snippet-scan
```

This fingerprints your project's files and submits snippet results alongside the standard dependency analysis. For the CLI mechanics, see the [CLI snippet scanning reference](/docs/cli/features/snippet-scanning).

## Viewing snippets

Open your project and select **Inventory → Snippets**. The page uses a two-panel layout:

- **Left, file tree:** browse your project's directory structure; click a folder to filter the list to that path.
- **Right, snippet table:** each detected snippet with its matched package, version, match count, and any associated license or security issue counts.

{% img src="/images/project-setup/view-snippets.png" alt="The Snippets tab with the project file tree on the left and the snippet table on the right" /%}

### Snippet table columns

| Column | Description |
| --- | --- |
| **Package** | The name and version of the open source package the snippet matched. |
| **Matches** | The number of files in your project where the snippet was detected. |
| **Licenses** | Licenses associated with the matched package. |
| **Issues** | License or security issues for the matched package (when issue scanning is enabled). |

Use the **Group by** dropdown to switch between **Ungrouped** (each match listed individually) and **By Package** (matches grouped by the package they matched).

{% callout type="info" %}
If no snippet scan has run, the Snippets tab shows *"Snippet analysis has not been run on this revision."*
{% /callout %}

## Snippet details

Click any row to open the **Snippet Details** drawer, which has three tabs:

- **Details**: package name, version, ecosystem, match count, license info, and any associated issues.
- **Compare Code**: a side-by-side view of your source and the matched open source code for each file; navigate matches from the list on the left, and reject or un-reject individual file matches here.
- **Labels**: package labels applied to the matched package (available once the snippet resolves to a known FOSSA package).

{% img src="/images/project-setup/view-snippets-details.png" alt="The Snippet Details drawer open on the Details tab, showing package summary, match confidence, and licenses" /%}

## Filtering and searching

- **Search**: filter snippets by package name.
- **Rejection status**: **Active** (not rejected) or **Rejected**.
- **Package labels**: filter by labels on matched packages (e.g. "Testing only", "Internal use only").

## Managing rejections

Rejecting a snippet excludes it from issue scanning and compliance reporting, appropriate for a false positive, or a match that doesn't carry license obligations for your use case.

{% img src="/images/project-setup/snippets-reject.png" alt="The Actions menu open in the snippet table, showing the Reject matches and Stop rejecting options" /%}

{% steps %}
{% step title="Reject matches" %}
Select one or more snippets with the checkboxes, then choose **Actions → Reject matches**. To reject a single file-level match, open the snippet's **Compare Code** tab, select the file match, and click **Reject**.
{% /step %}
{% step title="Stop rejecting" %}
Filter by **Rejected**, select the snippets, and choose **Actions → Stop rejecting**. To un-reject a single file match, open **Compare Code**, select the rejected match, and click **Stop Rejecting**.
{% /step %}
{% /steps %}

{% callout type="warning" %}
Rejections apply across all revisions of a project. They are not scoped to a single revision.
{% /callout %}

## Snippet settings

### Auto-reject threshold

FOSSA can automatically reject low-confidence matches when a scan completes. Configure this per project under **Settings → General → Snippet Auto-Reject Threshold**.

Enable the threshold and set a percentage (default: **10%**). Any snippet file match with a match percentage at or below that value is automatically rejected when the revision's analysis reaches steady state. Auto-rejected snippets still appear in the **Snippets** tab with a rejected status. You can review and un-reject them individually if needed.

{% img src="/images/project-setup/snippets-auto-reject-threshold.png" alt="Project Settings General page showing the Snippet Auto-Reject Threshold toggle and enabled checkbox" /%}

{% callout type="info" title="Organization default" %}
Your FOSSA account team can set an organization-wide default threshold that all new projects inherit. Individual projects can override it in their own settings.
{% /callout %}

### Source code retention

To perform snippet matching, FOSSA temporarily stores source code from your repositories. **Source Code Retention** controls how long that source code is kept before it is deleted from FOSSA's systems.

Configure it at **Organization Settings → General → Snippets → Source Code Retention**. The value must be between **1 and 30 days** (default: **30 days**).

{% img src="/images/project-setup/snippets-source-code-retention.png" alt="Organization Settings General page showing the Snippets section with the Source Code Retention field set to 30 days" /%}

## Comparing snippets between revisions

FOSSA can compare snippet results between two revisions of the same project. From **Inventory → Snippets**, click **Compare** and select the older revision. The comparison view groups snippets as:

| Category | Description |
| --- | --- |
| **New** | Present in the current revision but not the older one. |
| **Removed** | Present in the older revision but not the current one. |
| **Unchanged** | Present in both. |

All filtering, searching, and rejection functionality is available in the comparison view.

{% img src="/images/project-setup/compare-snippets.png" alt="The Comparing Snippets across revisions view, with New, Removed, and Unchanged status categories on the left" /%}

{% callout type="info" %}
Rejecting or un-rejecting snippets in the **Removed** category operates on the older revision, since those snippets don't exist in the current one.
{% /callout %}

## Issue scanning for snippets

FOSSA can scan snippet matches for licensing and security issues, just like declared dependencies. Enable it per issue type under your project's **Settings → Issues**, in the **Licensing** or **Security** section, with the **Scan for Snippets** toggle. Non-rejected matches are then included in issue scans, and their issues appear in the project's **Issues** tab.

{% callout type="info" %}
Issue scanning for snippets requires the Snippet Detection feature to be enabled for your organization.
{% /callout %}

### How snippet issues appear

Issues derived from snippet matches appear in the standard **Issues** tab alongside issues from declared dependencies, but carry a **Snippet** badge identifying their source. This badge helps distinguish them during triage, the underlying issue data (CVE, severity, license type) is the same, but the confidence of the relationship to your code differs.

### Match confidence and noise

Unlike declared dependencies where the package relationship is certain, snippet matches are probabilistic. A match means FOSSA found portions of your code that resemble code from the matched open source package; it does not mean the package is definitely included in your build. A low-confidence match (a small percentage of files overlapping) flagging a critical vulnerability may not reflect real exposure.

This is the primary source of noise when snippet issue scanning is enabled. Two tools help manage it:

- **Rejection**: rejecting a snippet removes its issues entirely. Rejected snippets show no issue counts and are excluded from issue scans. This is the most direct way to remove a false positive from your issue list.
- **Auto-reject threshold**: automatically rejects snippets below a match percentage you set, before they ever generate issues. Set this under **Project Settings → General → Snippet Auto-Reject Threshold**. See [Snippet settings](/docs/project-setup/snippets#snippet-settings) for details.

The practical workflow is: review match confidence in the **Snippets** tab before acting on issues. Use the **Compare Code** view to see exactly which files matched and how much overlap exists, a high-confidence match with substantial file overlap is worth investigating; a handful of matching lines in a test file usually isn't.

## Snippets in reports

Snippet matches can be included in reports as **Snippet Dependencies**.

### Licensing reports

| Format | Snippet behavior |
| --- | --- |
| HTML, PDF, Markdown | Snippet dependency revisions are included in the full dependency list. |
| CSV | An optional **Snippet Dependencies** section is included. |
| Plaintext | Snippet dependency revisions appear with a `Package Depth` of `Snippet`. |

### SBOM reports

All four SBOM report formats support optional inclusion of snippet dependencies; the package behind a snippet is treated as a direct dependency in the relationship graph.

{% callout type="info" %}
Issue information for snippets is included in reports only when the matching issue-scanning setting (Licensing or Security) is enabled for snippets on the project.
{% /callout %}

## FAQ

**What types of projects support snippet scanning?**
Source-based project types. On an unsupported project type, the Snippets tab indicates that snippet analysis isn't available.

**Are rejections revision-specific?**
No, rejections apply at the project level, so a rejection for a given snippet and file path carries across all revisions of the project.

**Do snippet issues appear alongside dependency issues?**
Yes. When issue scanning is enabled for snippets, snippet-match issues appear in the same **Issues** view, marked with metadata indicating they came from a snippet match.

**Do rejected snippets affect reports?**
Yes; rejected snippets are excluded from issue scanning and from report output.

---

Source: https://docs.fossa.com/docs/project-setup/quick-import

# Quick Import

Quick Import connects FOSSA to a cloud Version Control System (VCS) (such as GitHub) and analyzes the dependencies in your repositories. It gets immediate results with minimal configuration and automatically sets up webhooks, scheduled updates, and pull-request status checks.

Pick this method if:

- You want a quick setup to test integrations.
- You want to bulk-audit hundreds of repositories.
- You have many codebases that are small and relatively simple.

For the most accurate results on complex builds, use [CLI](/docs/project-setup/cli) instead.

## Connection methods

When you click **Quick Import**, FOSSA shows eight options for getting your projects in. Most are a one-click OAuth flow, authorize your VCS account and start selecting repositories. Two providers require an admin to complete a one-time setup before the connection is available to your team.

| Method | Use when… | Notes |
|---|---|---|
| **GitHub App** | Importing repos owned by a GitHub organization | Installs at the org level and isn't tied to any individual's account. Recommended for team and org-wide imports. See [GitHub App](/docs/integrations/github-app). |
| **GitHub OAuth** | Importing your own personal GitHub repos | Connects through your personal GitHub account. Already linked if you signed in to FOSSA with GitHub. |
| **GitLab** | Your projects live on GitLab.com | Standard OAuth, no prerequisites. |
| **Bitbucket.org** | Your projects live on Bitbucket Cloud | Standard OAuth, no prerequisites. |
| **Azure Repos** | Your projects live in Azure DevOps | Requires a Project Collection Administrator to enable third-party OAuth in your Azure DevOps org before connecting. See [Azure Repos](/docs/integrations/azure-repos). |
| **Bitbucket Server** | Your projects live on a self-hosted Bitbucket instance | On-Prem FOSSA only. Requires an Application Link and a `fossabot` service account. See [Bitbucket Server](/docs/integrations/bitbucket-server). |
| **Upload Archive** | Your code isn't on a VCS at all | Upload a `.zip`, `.tar.gz`, `.jar`, or similar archive directly and FOSSA analyzes it as a project. See [Archive Upload](/docs/project-setup/archive-upload). |
| **Other / Public** | Importing from any publicly accessible repository | Paste a public repository URL, no authentication required. |

## Connect your VCS

Click **Quick Import** to start importing from your VCS of choice, then connect your service account from the [Project Imports page](https://app.fossa.com/projects/import). If you signed in to FOSSA with a cloud VCS account, it's already connected.

{% img src="/images/quick-import.png" alt="The Quick Import screen showing GitHub, Bitbucket, GitLab, Azure Repos, and other VCS options" /%}

{% callout type="info" %}
The rest of this page uses GitHub as the example VCS.
{% /callout %}

{% callout type="danger" %}
The GitHub integration requests write permissions on private repositories. This is a GitHub limitation. It provides no read-only scope for private repos (see [dear-github#113](https://github.com/dear-github/dear-github/issues/113)). **FOSSA never writes to your repositories.** If you can't grant code access, [CLI](/docs/project-setup/cli) is a better fit. It requires no code access.
{% /callout %}

## Import repositories

After connecting, you'll see your repositories. Select **Import All**, or pick specific repos and click **Import**.

{% img src="/images/select-repositories.png" alt="The repository list with branch, status, and Import actions per repo" /%}

{% callout type="info" %}
Import the branch deployed in your production environment. If a repo is missing, you may not have granted FOSSA access to that team or sub-group in your VCS; check your provider's settings.
{% /callout %}

Before importing, you can filter repositories by visibility (Public / Private / All), last-updated date, and whether to include forks.


Click **Next Step** to configure the import:

- **Notifications**: issue-based email alerts.
  - Enable notifications (recommended for &lt;20 repos)
  - Configure notifications later
- **Updates**
  - Per-commit
  - Use organization defaults
  - Scheduled update (recommended for &gt;20 repos)
- **Access**
  - Default (as-is, based off repo permissions)
  - Set all public
  - Set all private
- **Misc**
  - Submit badge PRs after import (public GitHub READMEs only)

Click **Confirm Import** to start. Large or numerous repositories may take a while; click **Back to projects** to watch progress.

## Find a repository

If a repository isn't listed, switch teams with the team selector, or use the search bar to filter projects.




## What's next

- **[CI/CD Scanning](/docs/project-setup/cicd-scanning)**: For greater accuracy on complex builds, integrate FOSSA into your CI pipeline to upload dependency data directly.
- **[Pull Request Checks](/docs/project-setup/pr-checks)**: Block merges when new issues are detected by enabling automatic status checks on your repositories.
- **[Automatic Updates](/docs/project-setup/automatic-updates)**: Configure how and when FOSSA re-scans your projects to catch newly disclosed vulnerabilities and license changes.

---

Source: https://docs.fossa.com/docs/project-setup/broker

# Broker

[Broker](https://github.com/fossas/broker) is the bridge between FOSSA and your internal projects. Use it to scan local or firewalled repositories and import them into FOSSA (including FOSSA in the cloud) **without giving FOSSA access to your source code**.

That makes it the right way to import from on-premise VCS hosts (Bitbucket Server, on-prem GitLab, GitHub Enterprise, or any `git`-reachable host) behind a firewall, with the same deep integrations as [Quick Import](/docs/project-setup/quick-import): webhooks, scheduled re-scans, and pull-request status checks.

{% callout type="info" %}
Broker is maintained on GitHub and has full installation, configuration, and command documentation. This page is an overview, for everything else, see the **[Broker User Manual](https://github.com/fossas/broker/blob/main/docs/README.md)**.
{% /callout %}

## How it works

Broker runs as a proxy agent inside your network. You point it at your repositories with a config file; it clones them locally and sends only the metadata FOSSA needs (never your source code) to the FOSSA service.

| Kind | Supported | Details |
| :--- | :--- | :--- |
| `git` | ✅ | Any project reachable via `git clone` |

## Quickstart

{% steps %}
{% step title="Install Broker" %}
Install Broker on a machine inside your network, [locally or in Kubernetes](https://github.com/fossas/broker/blob/main/docs/README.md).
{% /step %}
{% step title="Initialize the config" %}
Run `broker init` to create an empty `config.yml` and database. The command prints the config file's location.
{% /step %}
{% step title="Configure your projects" %}
Edit `config.yml` to tell Broker which repositories to scan, how to access them, and at what cadence. See the [config reference](https://github.com/fossas/broker/blob/main/docs/README.md).
{% /step %}
{% step title="Run Broker" %}
Run `broker run` to scan the configured projects and import their metadata into FOSSA. Give it a moment, then view your projects in FOSSA.
{% /step %}
{% /steps %}

## Subcommands

| Command | What it does |
| :--- | :--- |
| `broker init` | Initialize an empty configuration file and database. |
| `broker fix` | Diagnose issues in the local environment that may be preventing Broker from scanning or uploading. |
| `broker run` | Boot Broker from the local config, scan the configured DevOps hosts, and import their metadata into FOSSA. |

## System requirements

Most modern systems run Broker without issues. For details, see the [system requirements reference](https://github.com/fossas/broker/blob/main/docs/README.md).

## Learn more

Full documentation lives in the **[Broker User Manual](https://github.com/fossas/broker/blob/main/docs/README.md)**. Have a question the docs don't answer? Send a support request via [support.fossa.com](https://support.fossa.com).

---

Source: https://docs.fossa.com/docs/project-setup/binaries

# Binaries

Binary Decomposition analyzes pre-compiled binaries and archives (without access to source code) to identify the open source components inside them. Reach for it when you have a shipped artifact (a `.exe`, `.jar`, firmware image, or container archive) but not the source that produced it.

## Importing a binary

{% steps %}
{% step title="Open the Decompose Binary importer" %}
From the **Add Projects** page, choose **Decompose Binary**.

{% img src="/images/project-setup/binaries-add-projects.png" alt="The Decompose Binary option on the Add Projects page" /%}
{% /step %}

{% step title="Add your files" %}
Select **Add Files** and choose the binary or archive to import. Bulk import is supported. Select as many files as you need.

{% img src="/images/project-setup/binaries-upload-wizard.png" alt="Binary Upload wizard showing the drop zone and supported file formats" /%}
{% /step %}

{% step title="Name the project and set a version" %}
Add a unique name and a semantic version number.

{% img src="/images/project-setup/binaries-name-version.png" alt="Binary Upload wizard with a file loaded, showing the Project Name and Revision fields" /%}
{% /step %}

{% step title="Review in your project list" %}
When upload and analysis finish, the binary appears in **Projects**. Use the **Binary Decomposition** project filter to find binary projects quickly; each is marked with the Binary Decomposition icon.

{% img src="/images/project-setup/binaries-projects-list.png" alt="Binary projects shown in the Projects list with the Binary Decomposition filter applied" /%}
{% /step %}
{% /steps %}

{% callout type="warning" %}
Importing under an **existing** binary project name adds the upload as the latest **revision** of that project rather than creating a new one.
{% /callout %}

You can upload a new binary as a new revision of any existing binary project at any time.

{% img src="/images/project-setup/binaries-new-revision.png" alt="Upload New Binary modal for adding a new revision to an existing binary project" /%}

## Supported formats

Each revision is a single uploaded file, either an **analyzable** binary or an **archive** that FOSSA expands and analyzes. Archives may contain any combination of archive types and analyzable binaries.

| Kind | Format | Extensions |
| :--- | :--- | :--- |
| Analyzable | Android Dex | `.dex` |
| Analyzable | Android ODEx | `.odex` |
| Analyzable | Windows dynamic linked library | `.dll` |
| Analyzable | Windows executable | `.exe` |
| Analyzable | Windows object file | `.obj` |
| Analyzable | Windows registry hive |  |
| Analyzable | Windows UWP/AppX package manifest | `AppxManifest.xml` |
| Analyzable | Firmware (SREC, bFLT, base64, Intel HEX, uBoot, wim; file systems JFFS2 `.img`/`.jffs2`, romfs, yaffs2, ubifs) | varies |
| Archive | Apple Disk Image | `.dmg` |
| Archive | AR | `.a`, `.ar`, `.deb`, `.lib` |
| Archive | arj | `.arj` |
| Archive | bzip2 | `.bz2`, `.tbz`, `.tbz2` |
| Archive | Cab | `.cab`, `.msu` |
| Archive | Compound types | `.msi`, `.msp` |
| Archive | Cpio | `.cpio` |
| Archive | cramfs | `.cramfs` |
| Archive | Docker container | `.tar.gz` |
| Archive | Ext2 / Ext3 / Ext4 | `.ext2`, `.ext3`, `.ext4` |
| Archive | FAT | `.fat` |
| Archive | GZIP | `.gz` |
| Archive | HFS | `.hfs`, `.hfsx` |
| Archive | Jar | `.jar`, `.war`, `.ear` |
| Archive | LZ4 | `.lz4` |
| Archive | Lzip | `.lz` |
| Archive | LZMA | `.lzma` |
| Archive | LZOP | `.lzo` |
| Archive | Mach | `.mach` |
| Archive | NTFS | `.ntfs` |
| Archive | RPM | `.rpm` |
| Archive | RAR | `.rar` |
| Archive | Roff | `.man`, `.roff` |
| Archive | RPM DB | `.rpmdb` |
| Archive | RPM sign | `.sig` |
| Archive | SFS | `.sfs` |
| Archive | SquashFS | `.sqsh`, `.squashfs`, `.sfs`, `.sqf`, `.sqfs`, `.sqs`, `.squ` |
| Archive | Tar | `.tar`, `.ova` |
| Archive | upx | `.upx` |
| Archive | VMDK | `.vmdk` |
| Archive | Windows Image Format | `.wim`, `.swm` |
| Archive | Xar | `.xar`, `.pkg` |
| Archive | Xz | `.xz`, `.txz` |
| Archive | ZIP | `.zip`, `.ipa`, `.xpi`, `.vsix`, `.whl`, `.apk` |
| Archive | 7z | `.7z` |

## File size limits

| Item | Limit |
| :--- | :--- |
| ISO (uncompressed data) | 40 GB |
| Archive (compressed data, direct or extracted) | 7 GB |
| Analysis target (direct or extracted) | 200 MB |
| Archive file + expanded contents (combined) | 17.5 GB |
| Maximum directory depth | 400 |

A few rules to avoid failed imports:

- Uploads through the UI must complete within **2 hours**, or the upload fails.
- ZIP files must use standard **deflate** or **store** compression, prefer standard system zip utilities over WinZip and similar tools. **Do not use encrypted ZIP files.**
- FOSSA respects object permissions inside an archive, so make sure all files and directories are readable by all users.
- Archive file extensions must match the table above; rename the archive first if needed. Analyzable binaries don't need a specific extension, but must not use one normally associated with a non-executable file.
- Files and directories beyond depth 400 are omitted.

---

Source: https://docs.fossa.com/docs/project-setup/sbom-import

# SBOM Import

Import an existing SBOM (CycloneDX or SPDX) so FOSSA can run license and security compliance checks against the components it lists, useful for analyzing software you don't build yourself.

## Import from the UI

{% steps %}
{% step title="Choose Import SBOM" %}
From the **Add Projects** page, select **Import SBOM (CycloneDX, SPDX)**.

{% img src="/images/project-setup/sbom-import-add-projects.png" alt="The Import SBOM option on the Add Projects page" /%}

{% callout type="info" %}
Imports must comply with:
- **CycloneDX** [1.2](https://cyclonedx.org/docs/1.2/json/), [1.3](https://cyclonedx.org/docs/1.3/json/), [1.4](https://cyclonedx.org/docs/1.4/json/), [1.5](https://cyclonedx.org/docs/1.5/json/), [1.6](https://cyclonedx.org/docs/1.6/json/), in JSON or XML.
- **SPDX** [2.2+](https://spdx.github.io/spdx-spec/v2.2.2/), [2.3](https://spdx.github.io/spdx-spec/v2.3/); requires a `DESCRIBES` relationship for the top-level project and `DEPENDS_ON` / `DEPENDENCY_OF` relationships, in JSON only. SPDX XML is not supported.
{% /callout %}
{% /step %}

{% step title="Add your files" %}
Select **Add Files** and choose the SBOM file (`.json` or `.xml`). Bulk import is supported. Select as many files as you need.

{% img src="/images/project-setup/sbom-import-upload-wizard.png" alt="SBOM Upload wizard showing the file drop zone" /%}
{% /step %}

{% step title="Name the project and set a version" %}
Add a unique name and a semantic version number.

{% img src="/images/project-setup/sbom-import-name-version.png" alt="SBOM Upload wizard with a file loaded, showing the Project Name and Revision fields" /%}
{% /step %}

{% step title="Review in your project list" %}
When upload and analysis finish, the SBOM appears in **Projects**, marked with the SBOM icon.

{% img src="/images/project-setup/sbom-import-projects-list.png" alt="SBOM projects in the Projects list with the SBOM import filter applied" /%}
{% /step %}
{% /steps %}

{% callout type="warning" %}
Importing under an **existing** SBOM project name adds the upload as the latest **revision** of that project rather than creating a new one.
{% /callout %}

## Import via the API

To automate imports, use the API instead of the UI. There are two steps: get a signed upload URL, then trigger a build.

{% steps %}
{% step title="Get a signed URL" %}
`GET /api/components/signed_url` returns a pre-signed cloud-storage URL. It is valid for **5 minutes**.

{% requestExamples %}
{% requestExample language="curl" %}
```bash
curl -X GET "https://app.fossa.com/api/components/signed_url" \
  --data-urlencode "packageSpec=<SBOM_package_or_file_name>" \
  --data-urlencode "revision=<SHA_hash_or_version>" \
  --data-urlencode "fileType=sbom" \
  -H "Authorization: Bearer $FOSSA_TOKEN"
```
{% /requestExample %}
{% requestExample language="python" %}
```python
import requests

resp = requests.get(
    "https://app.fossa.com/api/components/signed_url",
    params={"packageSpec": "<SBOM_package_or_file_name>", "revision": "<SHA_hash_or_version>", "fileType": "sbom"},
    headers={"Authorization": "Bearer <FOSSA_TOKEN>"},
)
signed_url = resp.json()["signedUrl"]
```
{% /requestExample %}
{% requestExample language="node" %}
```js
const params = new URLSearchParams({
  packageSpec: "<SBOM_package_or_file_name>",
  revision: "<SHA_hash_or_version>",
  fileType: "sbom",
});
const res = await fetch(`https://app.fossa.com/api/components/signed_url?${params}`, {
  headers: { Authorization: "Bearer <FOSSA_TOKEN>" },
});
const { signedUrl } = await res.json();
```
{% /requestExample %}
{% /requestExamples %}
{% /step %}

{% step title="Upload, then trigger a build" %}
`POST` your SBOM to the signed URL within 5 minutes, then call `POST /api/components/build?fileType=sbom` to start analysis. A successful build returns `201 Created`.

{% requestExamples %}
{% requestExample language="curl" %}
```bash
curl -X POST "https://app.fossa.com/api/components/build?fileType=sbom" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <token>" \
  -d '{"selectedTeams":[],"archives":[{"packageSpec":"Distro cyclonedx","revision":"123456789","fileType":"sbom"}]}'
```
{% /requestExample %}
{% requestExample language="python" %}
```python
import requests

requests.post(
    "https://app.fossa.com/api/components/build",
    params={"fileType": "sbom"},
    headers={"Authorization": "Bearer <token>"},
    json={
        "selectedTeams": [],
        "archives": [{"packageSpec": "Distro cyclonedx", "revision": "123456789", "fileType": "sbom"}],
    },
)
```
{% /requestExample %}
{% requestExample language="node" %}
```js
await fetch("https://app.fossa.com/api/components/build?fileType=sbom", {
  method: "POST",
  headers: { Authorization: "Bearer <token>", "Content-Type": "application/json" },
  body: JSON.stringify({
    selectedTeams: [],
    archives: [{ packageSpec: "Distro cyclonedx", revision: "123456789", fileType: "sbom" }],
  }),
});
```
{% /requestExample %}
{% /requestExamples %}
{% /step %}
{% /steps %}

---

Source: https://docs.fossa.com/docs/project-setup/dependencies

# Dependencies

The **Inventory** tab in a FOSSA project has three sub-tabs:

- **Dependencies**: every direct and transitive component included in the analysis (this page)
- **Snippets**: code snippets detected by [Snippet Scanning](/docs/cli/features/snippet-scanning)
- **Vendored**: vendored code detected by the [Vendored Dependencies](/docs/cli/features/vendored-dependencies) scan

(Snippets and Vendored are part of the Enterprise plan.)

This page covers the **Dependencies** sub-tab. Use it to understand how a dependency was introduced, review its license status, and correct any missing or incorrect data before generating reports.

## Dependency metadata

For each detected dependency, FOSSA captures the following:

| Field | Description |
|---|---|
| **Name** | The name or title of the dependency |
| **Version** | The resolved version. May be a commit hash for ecosystems that don't use semantic versioning. |
| **Depth** | **Direct**, explicitly included in your project; **Transitive**, pulled in by another dependency |
| **Package manager** | The ecosystem, package manager, or programming language managing the package |
| **Package Locator** | FOSSA's internal unique identifier for the component. Useful when the same package name exists across multiple ecosystems or when distinguishing public packages from private forks. |
| **Origin Path** | For direct dependencies: the file path where FOSSA found it. For transitive dependencies: the path to the root direct dependency. |
| **Dependency Path** | For transitive dependencies only, the ordered chain from the root direct dependency to the leaf. Example: `jest 18.1.0` → `jest-cli 18.1.0` → `node-notifier 4.6.1` |
| **Licenses** | Detected licenses. Licenses that conflict with the project's policy are highlighted. |
| **Issues** | Any license, security, or quality issues detected on the dependency |

{% img src="/images/project-setup/dependencies-table.png" alt="Dependencies table showing direct dependencies with columns for name, version, depth, licenses, and issues" /%}

## Unknown license dependencies

When FOSSA cannot access a dependency to scan it, the dependency appears with the message: *FOSSA was unable to perform a license scan on this dependency. If it's behind a private registry or auth, you may need to configure FOSSA's access and rebuild this project.*

The two most common causes:

**Private registry authentication**: the dependency lives in a private repository such as Artifactory or Nexus. Navigate to **Settings → Languages** and add authentication for the private registries you use.

**Incorrect discovery**: FOSSA found an incorrectly formatted entry in a manifest file, or detected an internal sub-project as a dependency (common in Gradle and Go projects).

{% callout type="warning" %}
FOSSA maintains the complete dependency graph even when individual packages cannot be accessed. Compliance and vulnerability information for accessible downstream packages is still surfaced correctly.
{% /callout %}

{% callout type="info" %}
If neither of the above explains your unknown dependency, contact [support@fossa.com](mailto:support@fossa.com) with as much detail as possible.

For help resolving missing or incomplete dependencies, see [Incomplete and Unknown Dependencies](/docs/help/incomplete-dependencies).
{% /callout %}

## Filtering

### Licenses

Filter to dependencies that contain a specific detected license.

### Package Managers

Filter to dependencies detected by a specific ecosystem, package manager, private URL, or user-defined source.

### Status

| Option | Shows |
|---|---|
| **In Progress** | Dependencies currently being analyzed |
| **Analyzed** | Dependencies that completed analysis successfully |
| **Failed** | Dependencies that encountered an analysis error |
| **Unknown** | Dependencies FOSSA could not locate |

### Flagged

Filter to dependencies that have at least one active license, security, or quality issue.

## Dependency actions

There are two ways to interact with a dependency.

### Three-dot menu

Hover over a dependency row and click the three-dot menu to access:

| Action | Description |
|---|---|
| **Overwrite package** | Opens a dialog to replace this dependency with a different one. You can search for a package in FOSSA's database, upload a package binary, or manually create an entry with your own package info. |
| **Copy locator** | Copies the dependency's internal FOSSA locator to the clipboard, useful for searching and API calls. |

### Clicking a dependency

Click anywhere on a dependency row to open the dependency drawer, which has three sections:

| Section | What you can do |
|---|---|
| **Details** | View and edit dependency metadata |
| **Licenses** | Add, change, or remove license information |
| **Ignore** | Ignore this dependency, removing it from compliance checks and suppressing its issues |

## Adding a custom license

If a dependency uses a license that isn't in FOSSA's database (such as a proprietary third-party license) you can add it as a custom license directly on the dependency.

{% steps %}
{% step title="Open the dependency" %}
Click anywhere on the dependency row to open the dependency drawer.
{% /step %}

{% step title="Add a license group" %}
Select **Add a license group**, then search for **Custom License** in the **License Name** dropdown and select it.

{% img src="/images/project-setup/dependencies-add-license.png" alt="Add License drawer showing License Name, License Text, and Copyrights fields" /%}
{% /step %}

{% step title="Enter the license details" %}
Fill in the custom license name and any additional details (license text, copyright) in the fields that appear.

{% img src="/images/project-setup/dependencies-license-details.png" alt="Add License drawer with Custom License selected and name, text, and copyright fields filled in" /%}
{% /step %}

{% step title="Save" %}
Select **Add** to add the license group, then save your changes.

{% img src="/images/project-setup/dependencies-license-saved.png" alt="Dependency Licenses tab showing the saved custom license with Approved status" /%}

When this dependency appears in future project scans, the custom license will already be applied.
{% /step %}
{% /steps %}

For broader dependency editing (changing metadata, concluding a license, updating copyright) see [License Corrections](/docs/licenses/license-corrections).

## Notice files

FOSSA detects notice files by filename, case-insensitively and regardless of where they appear in the directory tree. Files matching the following patterns are detected:

- `notice.txt`
- `third-party-notices.txt`
- `*_notice.txt`

{% callout type="info" %}
The notice file patterns listed above come from the legacy documentation and have not been verified against the current backend. If you encounter detection gaps, contact [support@fossa.com](mailto:support@fossa.com).
{% /callout %}

Detected notice files appear in the **Notice Files** section of the dependency detail view.

### Reviewing and editing notice files

Click anywhere on the dependency row to open it, then select **Edit** within the Notice Files section. From here you can review and modify the raw notice text and copyright data that will appear in attribution reports.

### Ignoring notice files

Select **Ignore** to exclude the notice file text and copyrights from attribution reports. Select **Stop Ignoring** to restore them.

{% callout type="info" %}
Notice file edits (like all dependency corrections) apply across all projects and all versions.
{% /callout %}

---

Source: https://docs.fossa.com/docs/project-setup/package-inventory

# Package Inventory

The Package Inventory is an organization-wide catalog of every package FOSSA has detected across all your projects. Instead of reviewing dependencies one project at a time, you can search and filter the full list from a single view, useful for answering questions like "which projects use this library?" or "do we have any critical vulnerabilities in this package version?" You can also block packages from entering your production environments.

## Accessing Packages

Click **Packages** in the top navigation bar. The table loads all packages detected across every project you have access to.

{% img src="/images/project-setup/package-inventory-table.png" alt="Package Inventory showing the package list, a selected package's version history with license and project counts, and the filter panel" /%}

## Browsing packages

The inventory shows one row per unique package version across your organization. Each row includes:

| Column | Description |
|---|---|
| **Package** | Package name and version |
| **Package Manager** | Package manager (npm, Maven, PyPI, etc.) |
| **License** | Detected license(s) for this package |
| **Vulnerability count** | Number of open vulnerability issues |
| **Projects** | Number of projects that include this package |

Click a package row to see its details, including the full list of projects that depend on it, its license information, and any open issues.

## Filtering and searching

Type a package name in the search field to filter the list to matching packages. While a search is active, the sort order switches to **Match**, so results closest to your search term appear first.

Filters are grouped into three sections:

### Package filters

- **Package Manager**: filter by package manager (npm, Maven, PyPI, etc.).
- **Package Labels**: filter by labels assigned to packages. See [Package Labels](/docs/organization-management/package-labels).
- **Locator**: filter by a package's unique locator identifier.

### Project filters

- **Project Name**: search for packages used by a specific project.
- **Import Method**: filter by how the project was imported: Provided via CLI, Quick Import, SBOM, Container, Archive, or Binary.
- **Visibility in FOSSA**: filter by Public or Private projects.
- **Labels**: filter by project labels. See [Organization Settings](/docs/organization-management/organization-settings#projects).
- **Teams**: filter to packages from projects belonging to a specific team.
- **Dependency Depth**: filter to Direct or Transitive dependencies only.
- **Blocked**: filter to packages that use blocked packages or have no blocked packages.

### Vulnerability filters

- **CVE**: filter by a specific CVE identifier.
- **CWE**: filter by weakness category.
- **Severity**: filter by Critical, High, Medium, Low, or Unknown severity.
- **Fix Type**: filter to packages that have a fix available or have no fix.

Severity maps to CVSS score ranges:

| Severity | CVSS range |
|---|---|
| **Critical** | 9.0–10.0 |
| **High** | 7.0–8.9 |
| **Medium** | 4.0–6.9 |
| **Low** | 0.1–3.9 |
| **Unknown** | No CVSS score available |

## Sorting

| Option | Description |
|---|---|
| **Package (A-Z)** | Alphabetical by package name (default) |
| **Match** | Closest match to your search term (active when searching) |
| **Usage** | By project count, highest first |

## Package details

Select a package and version to open the **Package Details** view, which shows:

| Field | Description |
|---|---|
| **Package name** | Name of the package |
| **Version** | Selected version |
| **Package locator** | FOSSA's unique internal identifier |
| **Package manager** | The ecosystem the package belongs to |
| **Project count** | Number of projects using this version |
| **License(s)** | Detected licenses |
| **Description** | Package description |
| **Homepage** | Link to the package's homepage or repository |

The **Projects** tab shows which of your FOSSA projects use the package. The **Vulnerabilities** tab lists detected CVEs.

{% callout type="info" %}
Vulnerabilities shown in the Package Inventory are not filtered by your security policy. A vulnerability will appear here even if it has been ignored or suppressed in a project's issue list. These vulnerabilities do not appear in FOSSA reports.
{% /callout %}

## Blocking packages

You can block a package to prevent it from being used across your organization. Blocked packages trigger issues in any project using the blocked version and fail [`fossa test`](/docs/cli/references/subcommands/test) in [CI/CD](/docs/integrations/fail-cicd-checks).

A block is attached to one or more quality policies, so only projects using those policies flag the blocked package. See [Blocking a package](/docs/policies/quality-policy#blocking-a-package) for the full workflow.

## Using Package Inventory for triage

The Package Inventory is useful for bulk triage. Common workflows:

- **Identify a vulnerable library org-wide**: search for a package name, then view all projects that include it. From each project, navigate directly to the vulnerability issues.
- **Audit a license**: filter by a license of concern to see every project that includes a dependency under that license.
- **Track adoption of an upgrade**: search for an old package version to see how many projects haven't migrated yet.

## Permissions

Package Inventory shows only packages from projects you can access based on your organization role and team memberships. If you need visibility into packages across all projects, you need an organization-level role (Admin, Editor, or Viewer). See [Role-Based Access Control](/docs/organization-management/role-based-access-control).

## FAQ

**Does Package Inventory include transitive dependencies?**
Yes. FOSSA analyzes the full dependency tree, so Package Inventory includes both direct and transitive dependencies.

**How often is the inventory updated?**
The inventory reflects the most recent completed analysis for each project. It updates each time a project is scanned.

**Can I export the Package Inventory?**
Export options depend on your plan. If export is available, use the **Export** button in the top-right of the inventory view to download a CSV.

**Why is a package missing from the inventory?**
A package only appears once FOSSA has analyzed a project that includes it. If a project has not been scanned yet, or if you don't have access to that project, its packages won't appear. Check that the relevant projects have run at least one successful scan.

## What's next

- **[Quality Scanning](/docs/quality/quality-scanning):** understand how FOSSA detects quality issues across your projects.
- **[Reviewing Quality Issues](/docs/quality/reviewing-quality-issues):** triage and act on quality issues surfaced in your projects.
- **[Quality Policy](/docs/policies/quality-policy):** define rules to automatically block packages and fail CI checks.

---

Source: https://docs.fossa.com/docs/project-setup/project-settings

# Project Settings

The Project Settings page allows you to configure details such as the project title, any [Labels](/docs/project-setup/project-labels), the policies used for your project, and much more.

{% callout type="info" %}
After making any changes, you must click the **Save** button at the top right of the screen.
{% /callout %}

## General Settings

{% img src="/images/project-setup/project-settings-general.png" alt="General project settings page showing title, locator, URL, notes, labels, and branch fields" /%}

**Project Title**: This is the title you will see the project use in the UI when viewing the [Projects table](https://app.fossa.com/projects).

**Project Locator**: This is the internal identifier used by the FOSSA API when referring to your project. It is read-only and cannot be edited.

**Project URL**: This is a URL you would like to be associated with your project. When viewing the project in the FOSSA UI, you can navigate to the Project URL by clicking the icon shaped like a house.

**Project Notes**: These are internal notes that your team can use to share details about the project you are working on.

**Labels**: Labels are used to assist with project management. You can use labels to search through your projects easily. You can read more about them [here](/docs/project-setup/project-labels).

**Default Branch**: When opening a project in the FOSSA UI, we will open to the latest revision of the default branch.

**Tracking Branches**: These branches will automatically be analyzed by FOSSA when updates are triggered.

**Ignored Dependencies**: A list of all dependencies which have been ignored. You can ignore dependencies from your project's dependencies tab. Here is an example of what it looks like when you have ignored a dependency.

{% img src="/images/project-setup/project-settings-ignored-dep.png" alt="Ignored Dependencies field showing two ignored dependency chips with remove buttons" /%}

You can remove that dependency by clicking the **X** shown in the image above. Remember to click the **Save** button at the top of the screen afterward.

**VCS Host**: The Version Control Host used for the project. When a VCS host is selected, you can configure status checks if they are supported; selecting GitHub as the host enables GitHub status checks. Here is what that dropdown looks like:

{% img src="/images/project-setup/project-settings-vcs-dropdown.png" alt="VCS Host dropdown showing GitHub, GitHub App, Bitbucket Cloud, GitLab, and Azure Repos options" /%}

### Danger Zone

In the Danger Zone at the bottom of the General Project Settings, you can change the visibility of your project or delete the project entirely.

{% img src="/images/project-setup/project-settings-danger-zone.png" alt="Danger Zone section showing Project Visibility dropdown with Public and Private options, and the Delete project button" /%}

**Change Project Visibility**: This section allows you to change your project from private, which is the default option, to public. If you change your project to public, then you can share it with users outside of your organization.

{% callout type="danger" %}
Deleting your project is a permanent change. Once you delete your project, there are aspects of the project that cannot be brought back.
{% /callout %}

---

Source: https://docs.fossa.com/docs/project-setup/ignore-a-dependency

# Ignore a Dependency

If you see a dependency in your project that you don't want to be included, you can ignore it.

{% steps %}
{% step title="Open the dependencies tab" %}
Navigate to the dependency tab, and hover over the dependency you want to ignore.

{% img src="/images/project-setup/ignore-a-dependency-nav.png" alt="Inventory dropdown open showing Dependencies, Snippets, and Vendored sub-tabs" /%}
{% /step %}
{% step title="Open the overflow menu" %}
Click the ⋯ (overflow) button on the dependency's row to open more options.

{% img src="/images/project-setup/ignore-a-dependency-overflow-btn.png" alt="Dependencies list with the overflow button visible on a dependency row" /%}
{% /step %}
{% step title="Choose Ignore package" %}
Click **Ignore package**. For dependencies that were added manually, this action instead reads **Delete Package**.

{% img src="/images/project-setup/ignore-a-dependency-menu.png" alt="Overflow menu open on a dependency row showing Copy locator and Ignore package options" /%}
{% /step %}
{% step title="Confirm" %}
A confirmation modal appears. Click **Confirm** to apply the ignore.

{% img src="/images/project-setup/ignore-a-dependency-modal.png" alt="Confirmation modal for ignoring a dependency, showing the scope warning and Cancel and Confirm buttons" /%}
{% /step %}
{% /steps %}

After a dependency has been ignored, you will see it listed on the [Project Settings page](/docs/project-setup/project-settings) under **Ignored Dependencies**.

{% callout type="info" %}
Ignoring a dependency applies to **all past, present, and future revisions** for the project. That dependency will be completely ignored until you un-ignore it.
{% /callout %}

## Un-ignore a dependency

{% steps %}
{% step title="Open Project Settings" %}
Navigate to the [Project Settings page](/docs/project-setup/project-settings).
{% /step %}
{% step title="Find Ignored Dependencies" %}
Find the section marked **Ignored Dependencies**.
{% /step %}
{% step title="Remove the chip" %}
Click the **X** on the chip for the dependency you want to restore.
{% /step %}
{% step title="Save" %}
Click the **Save** button.
{% /step %}
{% /steps %}

## Common use cases

Here are some examples of when users have ignored a dependency:

- Ignoring test dependencies that you don't want included in your reports.
- Ignoring proprietary dependencies that you would like to keep private.

---

Source: https://docs.fossa.com/docs/project-setup/project-labels

# Project Labels

Project labels let you tag projects with business context, ownership, criticality, environment, or any other classification your organization needs. Labels filter the Projects dashboard, the Issues inbox, and the Package Inventory, making it easier to focus risk evaluation on the projects that matter most.

## How labels work

Labels are defined at the organization level and applied to individual projects. FOSSA provides four default labels out of the box:

- **Critical Impact**
- **High Impact**
- **Medium Impact**
- **Low Impact**

You can create your own labels in addition to or instead of the defaults. Each label can be up to **50 characters**, must be **unique (case-insensitive)**, and an organization can have up to **500 labels** in total.

## Managing labels

### Creating labels

Labels are managed in **Settings → Organization → General**, under the Projects section. Type a label name into the input and save. Duplicate labels (including case variants of an existing label) are silently rejected.

{% img src="/images/project-setup/project-labels-org-settings.png" alt="Organization General Settings page showing the Projects section with Labels management" /%}

### Deleting labels

To delete a label, remove it from the list in org settings. Before the deletion is confirmed, FOSSA shows how many projects currently use the label, useful for understanding the blast radius before committing. Deleting a label removes it from every project using it. You must save your organization settings for the change to take effect.

### Applying labels to a project

Labels are applied per project in **Project Settings → General**. Select one or more labels from the available list and save.

#### Bulk-applying labels via API

To apply a label to many projects at once, use the API:

```bash
POST /api/v2/projects/labels?labelId=<label_id>
```

Pass an array of project locators in the request body. FOSSA applies the label to each project in the list. Any failures are returned per-locator so partial successes are visible.

## Filtering by label

Labels are available as a filter in three places across FOSSA.

### Projects dashboard

Labels appear as a filter in the **Projects** dashboard filter panel. Select one or more labels, multiple selections use OR logic (projects tagged with **Critical Impact** OR **Prod** are both shown).

Labels also appear as clickable chips on each project row. Clicking a chip instantly applies that label as a dashboard filter without opening the filter panel.

{% img src="/images/project-setup/project-labels-dashboard-filter.png" alt="Projects dashboard showing label chips on project rows and the Labels filter dropdown in the filter panel" /%}

### Issues inbox

The Issues inbox includes a **Project Labels** filter. Use it to scope the issue list to projects tagged with specific labels, for example, show only issues from projects tagged **Critical Impact** to prioritize remediation.

### Package Inventory

The Package Inventory's project filter panel includes a **Labels** filter, letting you narrow the dependency list to packages that appear in projects with specific labels.

### Release group project picker

When adding projects to a release group, the project list includes a label filter. Use it to quickly find and add all projects tagged with a given label, for example, adding every **Backend** service to a release group in one step.

---

Source: https://docs.fossa.com/docs/project-setup/automatic-updates

# Automatic Updates

FOSSA can re-build a project automatically whenever its code changes; because an issue scan runs after every build, new license and security issues surface without anyone starting a build by hand. You control how each project updates, who gets notified, whether results gate your CI builds, and how status is reported back in your repository.

## How automatic updates work

- **New commits trigger a build.** For a project connected to a repository (GitHub, GitLab, Bitbucket Cloud, Azure Repos) or a CI provider, an *update hook* tells FOSSA when a new revision lands, and FOSSA re-builds (re-analyzes) it. An issue scan runs after each build, so new license and security issues surface automatically. FOSSA configures this hook for you when you import the project through an integration (Quick Import).
- **CLI-analyzed projects update from your pipeline.** Projects you upload with the FOSSA CLI don't use update hooks; each CLI upload is itself the signal to re-analyze.
- **Issue scans also re-run on their own.** Beyond builds, FOSSA re-checks a project's existing dependencies for new issues whenever FOSSA's vulnerability data is updated or your policies change, so newly disclosed vulnerabilities surface even without a new commit.
- **A Scheduled hook re-builds the project revision on a timer.** You can optionally have a project re-build on a fixed schedule; as with any build, an issue scan runs afterward.

## Enabling automatic updates for a project

{% steps %}
{% step title="Open the project's Hooks settings" %}
From your project, go to **Settings → Hooks**.
{% /step %}
{% step title="Choose how updates are triggered" %}
Pick a hook type from the dropdown; it defaults to **No Automatic Updates**. The repository option matching the project's host (for example **GitHub**) appears alongside the host-independent options **Scheduled**, **Webhook**, **CircleCI**, and **TravisCI**. See [Update hook types](#update-hook-types) below.
{% /step %}
{% step title="Finish provider setup" %}
For a repository host (GitHub, GitLab, and so on) FOSSA configures the webhook on your repo for you. For **Scheduled**, set the interval and time. For **Webhook**, **CircleCI**, or **TravisCI**, copy the generated **Update URL** and have your pipeline ping it.
{% /step %}
{% /steps %}

Projects imported via Quick Import already have a matching hook configured. Open **Settings → Hooks** to confirm or change it. Projects uploaded with the FOSSA CLI don't use update hooks; each CLI upload is itself the signal to re-analyze.

A project uses one hook at a time. Switching a repository-connected project to a **Scheduled** hook stops commit-triggered builds. Keep the repository hook if you want a build on every push.

Admins can set an org-wide default schedule under **Account Settings → Projects → Hooks** and use **Propagate** to apply it to existing projects.

## Update hook types

The hook types offered in **Settings → Hooks** depend on the project's version control host, only the repository option matching that host appears.

| Hook type | What it does |
| :--- | :--- |
| **No Automatic Updates** | FOSSA doesn't re-build the revision on its own. A build happens only when you upload one from the CLI or trigger it manually (shown as "Manual Updates"). |
| **Scheduled** | Re-builds the project revision on a recurring schedule you set (interval and time). An issue scan runs after each build. |
| **GitHub / GitLab / Bitbucket Cloud / Azure Repos** | Triggers a build when a new revision is pushed to the connected repository. FOSSA configures the repository webhook for you. |
| **CircleCI / TravisCI** | Triggers a build when your CI pipeline pings the FOSSA update URL for that provider. |
| **Webhook** | Provides a generic update URL, pinging it triggers a build. Use this for any CI system without a dedicated option, such as Jenkins. |

## Gating CI builds on FOSSA results

You can make your build react to FOSSA's findings in two complementary ways.

### From CI with `fossa test`

If you run the FOSSA CLI in your pipeline, add [`fossa test`](/docs/cli/references/subcommands/test) after `fossa analyze`. It waits for the scan to finish and exits non-zero when the project has issues, failing the build. See the [CLI docs](/docs/cli) and the [integrations](/docs/integrations) for wiring it into specific CI systems.

### GitHub status checks

For GitHub projects, FOSSA can report a status check on every pull request and block merges when new issues are detected. See [Pull Request Checks](/docs/project-setup/pr-checks) for setup and configuration.

## Embedding a status badge

From your project, go to **Settings → General** and find the **Embed Status Badge** panel. Choose a badge type (**License Shield**, **Security Shield** (when Security is enabled), **Small**, or **Large**) then copy the **Markdown**, **HTML**, or **Link** snippet into your README or documentation.

{% callout type="info" %}
If you want FOSSA to add the badge to your README automatically at import time rather than copying it manually, see [Badge Pull Requests](/docs/project-setup/badge-pull-requests). That option is available for public GitHub repositories during Quick Import.
{% /callout %}

## Managing who gets notified

When an automatic scan finds a new issue, FOSSA emails the project's subscribed users. You can manage the recipient list in the UI or through the API.

| Scope | Where in the UI | API reference |
| :--- | :--- | :--- |
| Organization-wide default (applied to new projects) | **Account Settings → Projects → Notifications** | [`PUT /organizations/{id}/settings/projects/notifications`](/docs/api/reference/organization-settings/updateOrganizationNotificationSettings) |
| A single project | The project's **Settings → Notifications** | [`PUT /projects/{locator}`](/docs/api/reference/projects/updateProject) |
| Look up user IDs |  | [`GET /users`](/docs/api/reference/users/getAllUsers) |

**Setting the organization default.** Send the recipient list with `notificationDefaultEmailScanUserType` set to `custom` and the FOSSA user IDs in `notificationDefaultEmailScanUsers`, or use `all` or `current` to let FOSSA fill the list for you. This request **replaces the entire settings object**, so fetch the current values first (a `GET` to the same path) and send them back together with your changes.

{% callout type="warning" %}
Older integrations set default recipients by `PUT`ting `notification_default_email_scan_users` directly to `/organizations/{id}`. Use the [project notification settings endpoint](/docs/api/reference/organization-settings/updateOrganizationNotificationSettings) instead.
{% /callout %}

**Setting recipients on one project.** Update the project's `notifications` array, giving each entry a `channel` of `SCAN`, a `service` (`EMAIL`, `SLACK`, or `API_WEBHOOK`), and the `subscribed_users` IDs. Use the project locator **without** a revision.

**Finding user IDs.** Recipient lists are arrays of FOSSA user IDs. List your organization's users to map people to their IDs. Run it as an org admin to get the complete list.

## FAQ

**Can I use FOSSA with Jenkins, Azure Pipelines, or another CI system that isn't in the list?**
Yes. Either run `fossa analyze` and `fossa test` as steps in your pipeline, or choose the **Webhook** hook type and have your build ping its update URL. The dropdown only lists first-class options; anything else integrates through the CLI or a generic webhook.

**If I put a project on a schedule, will it catch new issues each time?**
Usually only when something has actually changed. A scheduled hook re-builds the project revision and runs an issue scan afterward, but FOSSA already re-checks for issues after every commit-triggered build and whenever FOSSA's vulnerability data is updated or your policies change, and it emails about an issue only the first time it's found. A fixed schedule rarely surfaces anything those automatic scans haven't already caught.

**Why isn't my project updating automatically?**
Open **Settings → Hooks** and confirm the hook type isn't **No Automatic Updates**. Projects uploaded with the FOSSA CLI don't use hooks, they update when your CI re-runs the analysis. New repository projects get a hook automatically on import.

**Which repository hosts can trigger a build on push?**
GitHub, GitLab, Bitbucket Cloud, and Azure Repos. The **Hooks** dropdown shows only the option matching your project's host.

**How do I change who gets emailed about new issues?**
Set the recipient list under **Account Settings → Projects → Notifications** (the organization-wide default) or in a project's **Settings → Notifications**, or automate it through the API. See [Managing who gets notified](#managing-who-gets-notified).

## What's next

- **[Pull Request Checks](/docs/project-setup/pr-checks)**: Block merges when automatic scans detect new issues using status checks.
- **[Scan Frequency](/docs/project-setup/scan-frequency)**: Schedule recurring scans to catch newly disclosed vulnerabilities even without code changes.
- **[Notifications](/docs/project-setup/notifications)**: Manage who gets notified when automatic scans find new issues.

---

Source: https://docs.fossa.com/docs/project-setup/archive-upload

# Archive Upload

Most dependencies reach FOSSA through a package manager, a `package.json`, `pom.xml`, or lockfile tells FOSSA exactly what was pulled and from where. Sometimes you instead have a self-contained **archive** of code, a `.tar.gz`, `.zip`, `.jar`, and so on, with no registry metadata to resolve against. This page explains how to **upload an archive directly in the FOSSA app** and how FOSSA analyzes it. If the code is vendored or lives locally in a project you already scan with the CLI, declare it through the CLI instead. See [Vendored or local code](#vendored-or-local-code) below.

{% callout type="info" %}
Archive formats are a special kind of dependency in FOSSA. They aren't introduced through a standard build tool or process, they represent instances where developers have packaged up pieces of (potentially-modified) third-party code and checked them into the source tree. When FOSSA encounters an archive, it makes a **best-effort** attempt to resolve it to known third-party code, falling back to scanning the archive's contents directly for license and copyright data.
{% /callout %}

## How FOSSA handles an archive

When FOSSA receives an uploaded archive, it recursively decompresses it (including any archives nested inside) and then runs its standard **Quick Import** analysis against the extracted source tree, exactly as it would for code pulled from a connected source host. Any package manifests inside the archive (`package.json`, `setup.py`, `pom.xml`, and so on) resolve dependencies normally, and files that don't belong to a recognized package are license-scanned directly.

Because an archive carries no registry metadata of its own, its dependency version defaults to a hash of the archive contents, so the version changes automatically whenever the code does. The result is the same analysis depth a normally-imported project gets, applied to code that was checked into the tree instead of pulled from a registry.

## Uploading an archive through the UI

You can upload an archive directly in the FOSSA app, no CLI or build required. Archive upload is one of FOSSA's **Quick Import** methods, so the result is a regular project, analyzed the same way as code imported from a source host.

{% steps %}
{% step title="Start adding a project" %}
From your project list, click **Add Projects**.
{% /step %}
{% step title="Choose Quick Import" %}
On the **Add Projects** screen, select **Quick Import** and click **Continue**.

{% img src="/images/project-setup/sbom-import-add-projects.png" alt="The Add Projects screen showing Quick Import, Import SBOM, Decompose Binary, and CLI options" /%}
{% /step %}
{% step title="Choose Upload Archive" %}
On the **Quick Import** screen, click **Upload Archive**. (You can also go straight to [app.fossa.com/projects/import/upload/archive](https://app.fossa.com/projects/import/upload/archive).)

{% img src="/images/project-setup/archive-upload-quick-import.png" alt="Quick Import screen with VCS host options and the Upload Archive tile at the bottom" /%}
{% /step %}
{% step title="Add your archive files" %}
Drag files onto the drop area, or click **Add Files** to browse for them. The uploader accepts the formats listed under **Supported formats** below.

{% img src="/images/project-setup/archive-upload-dropzone.png" alt="Archive Upload page with file drop area and accepted format list" /%}
{% /step %}
{% step title="Upload and analyze" %}
Click **Upload**. FOSSA stores each archive, then decompresses and analyzes it; the new project appears in your project list once the build completes.

{% img src="/images/project-setup/archive-upload-upload-files.png" alt="Archive Upload page with a file queued and the Upload button active" /%}
{% /step %}
{% /steps %}

{% callout type="tip" %}
Binary files are handled separately. Use **Add Projects › Decompose Binary** rather than archive upload. See [Binaries](/docs/project-setup/binaries).
{% /callout %}

## Supported formats

The archive uploader accepts the following file types. Contents are extracted recursively, so an archive containing other archives is unpacked all the way down.

| Format | Accepted extensions |
| :----- | :------------------ |
| Tar (and compressed tar) | `.tar`, `.gz`, `.bz2`/`.bzip2`, `.xz` |
| Zip | `.zip` |
| Java archive | `.jar` |
| Android / iOS packages | `.apk`, `.ipa` |
| Linux packages (RPM) | `.rpm` |
| Language packages | `.gem` (Ruby), `.whl` (Python wheel), `.conda` (Conda), `.nupkg` (NuGet) |

{% callout type="tip" %}
Wheels (`.whl`) are decompressed and scanned directly. For richer Python dependency resolution, analyze the project through FOSSA's standard [Python support](/docs/cli) so dependencies resolve from the package manager rather than from the archive alone.
{% /callout %}

## Supported languages

Because the extracted contents run through the same analysis that powers [Quick Import](/docs/project-setup/quick-import), **FOSSA supports any language that Quick Import supports**. Dependencies resolve from whatever package manifests the analysis finds inside (a `package.json`, `pom.xml`, `setup.py`, and so on), and files that don't belong to a recognized package are license-scanned directly.

For the full list of supported languages, see **[Supported Languages](/docs/project-setup/supported-languages)**. For a deeper explanation of how Quick Import's static analysis compares to CLI-based dynamic analysis, see [CLI vs Quick Import](/docs/get-started/cli-vs-quick-import).

## Vendored or local code

Archive upload is for self-contained archives. If the code is **vendored** (copied into a project) or lives **locally** in a project you already analyze with the FOSSA CLI, declare it through the CLI instead of uploading by hand, the CLI scans it as part of your normal `fossa analyze` run. The CLI docs cover each case in detail:

- **[Vendored dependencies](/docs/cli/features/vendored-dependencies)**: license-scan third-party code (an archive or a directory) checked into your tree, via the `vendored-dependencies` section of `fossa-deps.yml`.
- **[`fossa-deps.yml` reference](/docs/cli/references/files/fossa-deps)**: the full configuration file for declaring vendored, referenced, and custom dependencies.
- **[Path dependencies](/docs/cli/references/experimental/path-dependency)**: dependencies sourced from the filesystem rather than a registry.
- **[Binary discovery](/docs/cli/references/experimental/binary-discovery)**: opt-in detection that flags pre-compiled binaries found in your source tree.

---

Source: https://docs.fossa.com/docs/project-setup/supported-languages

# Supported Languages

FOSSA analyzes dependencies across dozens of language ecosystems. Each page below covers, for one language, how FOSSA imports your project through **Quick Import** (in the web app) versus the **FOSSA CLI**, how to authenticate to private registries, and what package data FOSSA collects. The CLI's per-strategy detection model (static vs. dynamic strategies and strict analysis) is covered under [Analysis strategies](#analysis-strategies) below.

## Support matrix

**Quick Import** runs server-side when you import a repository through a connected source host; the **CLI** runs in your build environment (local or CI) for the most accurate results. **Analysis type** describes how the CLI detects dependencies; see [Analysis strategies](#analysis-strategies) below for details.

| Language / platform | Quick Import | CLI | Compliance | Security | Analysis type | Vendored code |
| :-- | :-- | :-- | :-- | :-- | :-- | :-- |
| [Python (conda, pipenv, setuptools)](/docs/project-setup/supported-languages/python) | ✓ | ✓ | ✓ | ✓ | Dynamic + fallback | ❌ |
| [Python (poetry, pdm, uv)](/docs/project-setup/supported-languages/python) | ✓ | ✓ | ✓ | ✓ | Static | ❌ |
| [JavaScript / Node.js](/docs/project-setup/supported-languages/nodejs) | ✓ | **Recommended** | ✓ | ✓ | Static | ❌ |
| [Java: Maven](/docs/project-setup/supported-languages/maven) | Partial | **Recommended** | ✓ | ✓ | Dynamic + fallback | ❌ |
| [Java / Kotlin: Gradle](/docs/project-setup/supported-languages/gradle) |  | **Recommended** | ✓ | ✓ | Dynamic | ❌ |
| [Scala: sbt](/docs/project-setup/supported-languages/scala) | ✓ | ✓ | ✓ | ✓ | Dynamic | ❌ |
| [Go (dep, glide)](/docs/project-setup/supported-languages/golang) | ✓ | ✓ | ✓ | ✓ | Static | ❌ |
| [Go (gomodules)](/docs/project-setup/supported-languages/golang) | ✓ | ✓ | ✓ | ✓ | Dynamic + fallback | ❌ |
| [Ruby](/docs/project-setup/supported-languages/ruby) | ✓ | ✓ | ✓ | ✓ | Dynamic + fallback | ❌ |
| [PHP](/docs/project-setup/supported-languages/php) | ✓ | ✓ | ✓ | ✓ | Static | ❌ |
| [.NET (C#, F#, VB)](/docs/project-setup/supported-languages/dotnet) | ✓ | ✓ | ✓ | ✓ | Static | ❌ |
| [Rust](/docs/project-setup/supported-languages/rust) | ✓ | ✓ | ✓ | ✓ | Dynamic | ❌ |
| [Dart / Flutter](/docs/project-setup/supported-languages/dart) |  | ✓ | ✓ | ✓ | Dynamic + fallback | ❌ |
| [Perl](/docs/project-setup/supported-languages/perl) | ✓ | ✓ | ✓ | ✓ | Static | ❌ |
| [Haskell](/docs/project-setup/supported-languages/haskell) |  | ✓ | ✓ | ✓ | Dynamic | ❌ |
| [Elixir](/docs/project-setup/supported-languages/elixir) |  | ✓ | ✓ | ✓ | Dynamic | ❌ |
| [Erlang](/docs/project-setup/supported-languages/erlang) |  | ✓ | ✓ | ✓ | Dynamic | ❌ |
| [Clojure](/docs/project-setup/supported-languages/clojure) |  | ✓ | ✓ | ✓ | Dynamic | ❌ |
| [Fortran](/docs/project-setup/supported-languages/fortran) |  | ✓ | ✓ | ✓ | Static | ❌ |
| [Nim](/docs/project-setup/supported-languages/nim) |  | ✓ | ✓ | ✓ | Static | ❌ |
| [R](/docs/project-setup/supported-languages/r) |  | ✓ | ✓ | ✓ | Static | ❌ |
| [iOS (Objective-C, Swift)](/docs/project-setup/supported-languages/ios) | ✓ | ✓ | ✓ | ✓ | Static | ❌ |
| [C / C++](/docs/project-setup/supported-languages/c-cpp) |  | ✓ | ✓ |  | Custom | ✅ |
| [System packages](/docs/project-setup/supported-languages/system) |  | ✓ | ✓ | ✓ | -- | -- |

A blank cell means that path is not available for that ecosystem; pick the other column. Where the CLI is marked **Recommended**, the language's builds are complex enough that CI/CD scanning gives materially better results than Quick Import.

## Beyond package managers

FOSSA can also analyze code that no package manager describes:

- **[Vendored code](/docs/cli/features/vendored-dependencies)**: fingerprint copied-in open source to identify it even after minor edits.
- **[Snippet scanning](/docs/cli/features/snippet-scanning)**: detect open source copied at the snippet level, where no manifest exists.
- **[System packages](/docs/project-setup/supported-languages/system)**: OS-level packages (apk, dpkg, rpm) discovered during container scanning.
- **Git submodules**: imported as first-class dependencies when you analyze a repository that uses them.

## Analysis strategies

The FOSSA CLI detects dependencies using one or more **strategies** per ecosystem: a primary strategy that yields ideal results and zero or more fallbacks. Each language page above documents its own strategies; this section explains how those strategies are classified and selected.

### Static and dynamic strategies

Within the strategies for a language, we distinguish _static_ and _dynamic_ strategies. Static strategies parse files to find a dependency graph (example: parse a `package-lock.json` file). Dynamic strategies are required when analyzing package managers that do not offer complete lockfiles, such as Gradle or Go. Dynamic strategies require a working build environment to operate in.

Running the tool with all possible strategies enabled is recommended, but if you need to limit the CLI to only static strategies it offers the `--static-only-analysis` flag. This flag prevents the CLI from using any third-party tools, such as `npm`, `pip`, or maven plugins. With this option enabled, strategies that don't offer a way to analyze statically will fail with an error.

Neither type of strategy has an inherent benefit when detecting dependencies. If a supported language has only a static or only a dynamic strategy, that does not make it less supported than a language that has both.

The **Analysis type** column in the [support matrix](#support-matrix) above classifies each ecosystem by the strategies it offers:

- **Static**: only static strategies. Dynamic analysis is not required for ideal results, so a working build environment is not needed.
- **Dynamic**: a dynamic strategy is required for ideal results, so the CLI needs a working build environment.
- **Dynamic + fallback**: a dynamic strategy with a static fallback. The fallback provides worse results and is only used when the dynamic strategy fails.
- **Custom**: strategies (such as C/C++) that work very differently from standard package-manager analysis; read their language page for details.

When the CLI is forced to use a fallback strategy, it emits a warning in the scan summary after running `fossa analyze`.

### Strict analysis

Strict analysis enforces the use of the most accurate strategy for detecting dependencies, rejecting fallback methods that may be less reliable. For example, in Maven projects the CLI attempts analysis in this order:

1. The [mavenplugin](/docs/project-setup/supported-languages/maven/mavenplugin) strategy, which provides the most accurate dependency information.
2. If that fails, the [treecmd](/docs/project-setup/supported-languages/maven/treecmd) strategy, which parses the output of `mvn dependency:tree`.
3. Finally, the [pomxml](/docs/project-setup/supported-languages/maven/pomxml) strategy, which scans `pom.xml` files.

With the `--strict` flag, only the `mavenplugin` strategy is used; if it fails, the CLI does not fall back. Invoke strict analysis with the `--strict` flag when running `fossa analyze`.

---

Source: https://docs.fossa.com/docs/project-setup/supported-languages/python

# Python

FOSSA supports Python projects through `setuptools`, `pip`, `poetry`, `pipenv`, and `conda`. You can analyze a project two ways: **Quick Import** in the web app, or the **FOSSA CLI** for complex builds.

## Tool support

| Tool | Quick Import (app.fossa.com) | CLI (fossa-cli) |
| :-- | :-- | :-- |
| pip | `requirements.txt` and `setup.py` | `req*.txt` and `setup.py` |
| setuptools / distutils | `setup.py` | N/A |
| distribute | N/A | N/A |
| poetry | N/A | `pyproject.toml` and `poetry.lock` |
| pipenv | N/A | `Pipfile.lock` |
| conda | N/A | `environment.yml` |

## How Quick Import works

When Python code is imported through the web app, FOSSA finds and runs any `setup.py` files and recursively traverses dependencies brought in via the `install_requires` parameter. If any `requirements.txt` files are present, FOSSA resolves those entries and treats them as direct dependencies. Sub-dependencies of packages brought in from `requirements.txt` are ignored, consistent with standard build behavior.

{% callout type="info" %}
Quick Import assumes Python codebases follow standard conventions where running `setup.py` or `pip install -r <requirements.txt>` is expected. If `setup.py` files are heavily customized or require non-standard versions of Python, FOSSA may fail to run and analyze them. For these projects, use CLI analysis instead.
{% /callout %}

## Analyzing with the CLI

For complex Python builds that rely on custom tooling, scripts, or virtual environments, CI/CD scanning with the FOSSA CLI is the ideal integration path.

{% callout type="tip" %}
The CLI runs inside your build environment, so it can resolve dependencies that Quick Import cannot.
{% /callout %}

Install the latest release of `fossa-cli`:

```shell
curl -H 'Cache-Control: no-cache' https://raw.githubusercontent.com/fossas/fossa-cli/master/install-latest.sh | bash
```

Then run `fossa analyze` from your repository's root directory. The Python ecosystem spans three major toolchains (setuptools (`requirements.txt`, `setup.py`), pipenv, and conda) plus poetry, pdm, and uv. The CLI selects a strategy per project; each strategy's detection details are linked in the table below.

### Analysis strategies

| Strategy | Direct Deps | Transitive Deps | Edges | Container Scanning |
| --- | --- | --- | --- | --- |
| [pipenv](/docs/project-setup/supported-languages/python/pipenv) | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | :x: |
| [pipfile](/docs/project-setup/supported-languages/python/pipenv) | :heavy_check_mark: | :heavy_check_mark: | :x: | :x: |
| [requirements.txt & setuptools](/docs/project-setup/supported-languages/python/setuptools) | :heavy_check_mark: | :white_check_mark: | :white_check_mark: | :heavy_check_mark: |
| [setup.py & setuptools](/docs/project-setup/supported-languages/python/setuptools) | :heavy_check_mark: | :white_check_mark: | :white_check_mark: | :heavy_check_mark: |
| [conda](/docs/project-setup/supported-languages/python/conda) | :heavy_check_mark: | :white_check_mark: | :x: | :x: |
| [poetry](/docs/project-setup/supported-languages/python/poetry) | :heavy_check_mark: | :white_check_mark: | :white_check_mark: | :heavy_check_mark: |
| [pdm](/docs/project-setup/supported-languages/python/pdm) | :heavy_check_mark: | :white_check_mark: | :white_check_mark: | :heavy_check_mark: |
| [uv](/docs/project-setup/supported-languages/python/uv) | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: |

* :heavy_check_mark:, Supported in all projects
* :white_check_mark:, Supported only when relevant data is available (e.g. lockfiles are present)
* :x:, Not supported

## Authenticating to private registries

You can configure FOSSA to fetch dependencies from private PyPI registries published through tools like Artifactory or Sonatype Nexus.

{% steps %}
{% step title="Open Python language settings" %}
Go to **Account Settings → Languages → Python** (`https://app.fossa.com/account/settings/languages/python`).
{% /step %}
{% step title="Add your credentials" %}
Enter the login credentials FOSSA should use to reach your private feed, then save.
{% /step %}
{% /steps %}

FOSSA can now resolve private PyPI packages.

{% img src="/images/project-setup/05d1932-Screen_Shot_2018-03-29_at_9.17.06_PM.png" alt="Python private registry credentials in Account Settings" /%}

## Package data

FOSSA supports most standard ways Python packages can be included, ranging from packages on PyPI to packages stored in archives or VCS hosts. When possible, FOSSA prefers source-code formats over binary/archive formats like `.egg` and `.whl`; if an egg or wheel is downloaded, its contents are inspected for code auditing and dependency information.

The following are **not** supported:

- `dist-info` directories (currently skipped)
- Mercurial, Subversion, and Bazaar version control systems
- Source code distributed with XZ compression
- Custom build scripts (for example, fabric or make)
- C extensions

### Supported VCS formats

| VCS | Supported |
| :-- | :-- |
| Git | Yes |
| Mercurial (hg) | No |
| Subversion (svn) | No |
| Bazaar (bzr) | No |

---

Source: https://docs.fossa.com/docs/project-setup/supported-languages/python/setuptools

# Setuptools (requirements.txt/setup.py)

requirements.txt, alongside setup.py, is the most common -- yet imprecise --
approach to dependency management in python projects.

## Project Discovery

`requirements.txt`: Find all files matching the glob: `req*.txt`

`setup.py`: Find all files named `setup.py`

## Analysis: requirements.txt

For the CLI to identify transitive dependencies from a requirements.txt file,
certain conditions must be met. First, the specified packages must be installed
using a command like `python -m pip install -r requirements.txt`. The packages
should be installed within a virtual environment, ensuring a clean and isolated
environment. Subsequently, the CLI should be executed within the same virtual
environment the packages were installed in. Finally, the environment should
include both `python` and `pip`, as the CLI parses the output from executing
`python -m pip list` and `python -m pip show` to determine transitive
dependencies. Importantly, the CLI only reports transitive dependencies for
packages explicitly listed in the requirements.txt file and installed within the
current environment.

If neither python nor pip are installed the CLI will only to reporting only direct
dependencies.

requirements.txt contains direct dependencies, and is parsed compliant to its
[file format spec][requirements-file-format].

pip-cli options, URLs, absolute paths, and relative paths are ignored -- though
this may be revisited in the future.

Dependencies found in requirements.txt have a spec defined by
[PEP-508][pep-508]. Dependencies often have version ranges and environment
markers (e.g. python version, OS, ...). The resulting graph contains packages
tagged with environment markers.

## Analysis: setup.py

### Installed packages

For the CLI to detect transitives dependencies for packages specified in a
`setup.py` file's `install_requires` field, certain conditions must be met. The
packages must be installed with command similar to `python -m pip install .`.
The packages should be installed within a virtual environment, ensuring a clean
and isolated environment. Subsequently, the CLI should be executed with the same
environment. Finally, the environment should include both `python` and `pip`, as
the CLI will parse the output from executing `python -m pip list` and `python -m
pip show` to determine the transitive dependencies. The CLI will naively scan a
setup.py file for a `name` attribute and attempt to match the name with an
installed package. If the name matches an installed package, the CLI will
exclusively report the transitive dependencies required by the found package. If
a name is not matched then the CLI will naively scan for install_requires as
explained in the next section.

If neither python nor pip are installed the CLI will report dependencies found
by naively scanning for install_requires as explained in the next section.

### Naively scanning for install_requires

setup.py is naively scanned for its `install_requires=[...]` field, which often
fails on projects encountered in the wild. Short of implementing a robust python
parser, or running a python script in their environment (which may have
unintended consequences!), reliable output from setup.py is difficult to obtain.

Entries in the `install_requires` array are parsed compliant to the
[PEP-508][pep-508] spec, similar to requirements.txt

If `setup.cfg` exists in the same directory as `setup.py`, `fossa-cli` also naively
scans for its `install_requires=[...]` attributes, similar to `setup.py`. If both `setup.cfg` and
`setup.py` exists and both have `install_requires` attribute, `fossa-cli` concatenates requirements
from both files.

[setup.cfg docs]: https://setuptools.pypa.io/en/latest/userguide/declarative_config.html
[requirements-file-format]: https://pip.pypa.io/en/stable/reference/requirements-file-format/
[pep-508]: https://www.python.org/dev/peps/pep-0508/

## Limitations

* Python requirements files and setup.py files do not provide any data about edges between dependencies.
* Requirements files can be completely different than an existing setup.py specification, as there is no built-in
synchronization between them.
* The CLI will catch *variables* named `install_requires`, as long as they are declared earlier in the file than the `install_requires` keyword argument to `setup`.
* Because the CLI doesn't actually run `setup.py` or do its own interpretation of the Python code therein, `install_requires` not defined as a literal array of string literals done in the `setup.py` file will hide the
true `install_requires` list from the CLI's view. For example, FOSSA CLI does not have a general way to find `install_requires` set up this way:
    ```python
    a = ['package1==1.0.0']
    b = ['package2==2.0.0']
    install_requires = a + b
    ```
* Often, the `requirements.txt` file entirely overlaps the `setup.py` file.  This is almost always by design.

## Examples

Assuming no virtual environment, given the following files:

`setup.py` (manually created):

```python
setup(
    name='Foo-project',
    version='1.0',
    description='Python example project',
    author='Jeff Jefferson',
    author_email='bug-catcher@butterfly.net',
    url='https://this.url/means#nothing',
    packages=['foo'],
    # And now the important part...
    install_requires=[
        "requests",
    ],
)
```

`requirements.txt`:
*Note: your requirements file may have different versions. This file is just a reference example.*

```txt
certifi==2021.5.30
chardet==4.0.0
idna==2.10
requests==2.25.1
urllib3==1.26.6
```

We will produce a list of these direct dependencies with no edges between them (see [#limitations](#limitations)):

```txt
certifi==2021.5.30
chardet==4.0.0
idna==2.10
requests==2.25.1
urllib3==1.26.6
```

## F.A.Q

### Why is `fossa-cli` reporting incorrect transitive dependencies or edges?

`fossa-cli` uses `python -m pip list` and `python -m pip show` command to infer
transitive dependencies, and it's edges. It's paramount that you are in
project's [venv](https://docs.python.org/3/tutorial/venv.html) prior to invoking
`fossa analyze` command. If you are not in project's virtual environment,
`fossa-cli` will use global python environment to infer transitive dependencies,
edges, and dependency versions.

For example, you should always invoke `fossa-cli` in project's python's virtual environment.
```bash
python -m venv ~/envs/my-venv
source ~/envs/my-venv/bin/activate # this command may differ depending on your python version!
pip install -r requirements.txt

fossa analyze
```

If you are unable to get any transitive dependencies, ensure you can run following command in project's directory:
- `python -m pip list --format json`
- `python -m pip show`

---

Source: https://docs.fossa.com/docs/project-setup/supported-languages/python/setuptools-qr

# Quick reference: setuptools

## Requirements

**Ideal**

- `requirements.txt` files present in your project

**Minimum**

- `setup.py` files present in your project. 

Unfortunately, we fail to parse many valid `setup.py` files. In general, we recommend the use of `requirements.txt` files for better analysis.

## Project discovery

Directories containing `setup.py` files or `requirements.txt`-like files (e.g., `req-dev.txt`, `test-requires.txt` are valid -- or any filename matching the regex `.*req.*\.txt`) are treated as setuptools projects.

---

Source: https://docs.fossa.com/docs/project-setup/supported-languages/python/poetry

# Poetry

[Poetry](https://python-poetry.org/) is a tool for dependency management and packaging in Python.

## Project Discovery

Find files named `pyproject.toml` and `poetry.lock`. Pyproject must also use poetry for the [build system](https://python-poetry.org/docs/pyproject/#poetry-and-pep-517). If Pyproject does not use poetry build system - project will not be discovered.

## Analysis

We parse `pyproject.toml` to find direct dependencies and their [version constraints](https://python-poetry.org/docs/dependency-specification/):

- `[tool.poetry.dependencies]` - production dependencies
- `[tool.poetry.dev-dependencies]` - development dependencies

If `poetry.lock` file is discovered, following will be analyzed from lockfile to supplement the analyses:

- `[package.dependencies]` - package's dependencies
- `package.category` - package's environment (dev, test, etc.). If not present, defaults to `main`.
- `package.name` - name of the package
- `package.version` - resolved version of the package

If `poetry.lock` file is not discovered, we fallback to reporting only direct dependencies parsed from `pyproject.toml`.

| Strategy                                          | Direct Deps        | Transitive Deps          | Edges              |
| ------------------------------------------------- | ------------------ | ------------------ | ------------------ |
| `pyproject.toml` and `poetry.lock` are discovered | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: |
| Only `pyproject.toml` is discovered               | :heavy_check_mark: | :x:                | :x:                |
| Only `poetry.lock` is discovered                  | :x:                | :x:                | :x:                |

- :heavy_check_mark: - Supported in all projects
- :x: - Not Supported

### Limitations

- For poetry project, build system's `build-backend` must be set to `poetry.core.masonry.api` or `poetry.masonry.api` in `pyproject.toml`. If not done so, it will not discover the project. Refer to [Poetry and PEP-517](https://python-poetry.org/docs/pyproject/#poetry-and-pep-517) for more details.
- All extras specified in `[tool.poetry.extras]` are currently not reported.
- Any [path dependencies](https://python-poetry.org/docs/dependency-specification/#path-dependencies) will not be reported.
- For Poetry version greater or equal to `v1.5.0`, optional dependencies provideded in [dependencies group](https://python-poetry.org/docs/managing-dependencies/#dependency-groups) will not be included in the analysis, even with [--include-unused-deps](/docs/cli/references/subcommands/analyze), if only `pyproject.toml` is discovered.

## Example

`pyproject.toml` file (created by `poetry init` and adding relevant dependencies)

```toml
[tool.poetry]
authors = ["User <user@example.com>"]
description = "Example poetry usage"
name = "example-poetry-usage"
version = "0.1.0"

[tool.poetry.dependencies]
loguru = "^0.5"
networkx = {git = "https://github.com/networkx/networkx.git", branch = "v1.10"}
python = "^3.9"

[tool.poetry.dev-dependencies]
flake8 = "3.9.2"

[build-system]
build-backend = "poetry.core.masonry.api"
requires = ["poetry-core>=1.0.0"]
```

and accompanying poetry.lock file (created by poetry at time of dependency resolution)

```toml
[[package]]
name = "colorama"
version = "0.4.4"
description = "Cross-platform colored terminal text."
category = "main"
optional = false
python-versions = ">=2.7, !=3.0.*, !=3.1.*, !=3.2.*, !=3.3.*, !=3.4.*"

[[package]]
name = "decorator"
version = "5.0.9"
description = "Decorators for Humans"
category = "main"
optional = false
python-versions = ">=3.5"

[[package]]
name = "flake8"
version = "3.9.2"
description = "the modular source code checker: pep8 pyflakes and co"
category = "dev"
optional = false
python-versions = "!=3.0.*,!=3.1.*,!=3.2.*,!=3.3.*,!=3.4.*,>=2.7"

[package.dependencies]
mccabe = ">=0.6.0,<0.7.0"
pycodestyle = ">=2.7.0,<2.8.0"
pyflakes = ">=2.3.0,<2.4.0"

[[package]]
name = "loguru"
version = "0.5.3"
description = "Python logging made (stupidly) simple"
category = "main"
optional = false
python-versions = ">=3.5"

[package.dependencies]
colorama = {version = ">=0.3.4", markers = "sys_platform == \"win32\""}
win32-setctime = {version = ">=1.0.0", markers = "sys_platform == \"win32\""}

[package.extras]
dev = ["codecov (>=2.0.15)", "colorama (>=0.3.4)", "flake8 (>=3.7.7)", "tox (>=3.9.0)", "tox-travis (>=0.12)", "pytest (>=4.6.2)", "pytest-cov (>=2.7.1)", "Sphinx (>=2.2.1)", "sphinx-autobuild (>=0.7.1)", "sphinx-rtd-theme (>=0.4.3)", "black (>=19.10b0)", "isort (>=5.1.1)"]

[[package]]
name = "mccabe"
version = "0.6.1"
description = "McCabe checker, plugin for flake8"
category = "dev"
optional = false
python-versions = "*"

[[package]]
name = "networkx"
version = "1.10"
description = "Python package for creating and manipulating graphs and networks"
category = "main"
optional = false
python-versions = "*"
develop = false

[package.dependencies]
decorator = ">=3.4.0"

[package.source]
type = "git"
url = "https://github.com/networkx/networkx.git"
reference = "v1.10"
resolved_reference = "4d364bfcee7b24f3df137e8dcd36f7a547892e55"

[[package]]
name = "pycodestyle"
version = "2.7.0"
description = "Python style guide checker"
category = "dev"
optional = false
python-versions = ">=2.7, !=3.0.*, !=3.1.*, !=3.2.*, !=3.3.*"

[[package]]
name = "pyflakes"
version = "2.3.1"
description = "passive checker of Python programs"
category = "dev"
optional = false
python-versions = ">=2.7, !=3.0.*, !=3.1.*, !=3.2.*, !=3.3.*"

[[package]]
name = "win32-setctime"
version = "1.0.3"
description = "A small Python utility to set file creation time on Windows"
category = "main"
optional = false
python-versions = ">=3.5"

[package.extras]
dev = ["pytest (>=4.6.2)", "black (>=19.3b0)"]

[metadata]
lock-version = "1.1"
python-versions = "^3.9"
content-hash = "31cb32d5165d1cc95e45e9d3e839af556f548df74dda74e25a02b79ba5aa5948"

# [metadata.files] not shown for brevity
```

We will produce the following dependency graph from our analyses when both `poetry.lock` and `pyproject.toml` are discovered.

```mermaid
---
config:
  themeVariables:
    fontSize: 12px
  flowchart:
    nodeSpacing: 16
    rankSpacing: 24
    padding: 4
    diagramPadding: 8
---
flowchart TD
    NX["networkx@v1.10"]:::prod --> DEC["decorator@5.0.9"]:::unknown
    FL8["flake8@3.9.2"]:::prod --> MCC["mccabe@0.6.1"]:::unknown
    FL8 --> PCO["pycodestyle@2.7.0"]:::unknown
    FL8 --> PYF["pyflakes@2.3.1"]:::unknown
    LOG["loguru@0.5.3"]:::prod --> COL["colorama@0.4.4"]:::unknown
    LOG --> WIN["win32-setctime@1.0.3"]:::unknown
    classDef prod fill:#edf7f2,stroke:#1d7a54,color:#171717,stroke-width:2px
    classDef dev fill:#ffffff,stroke:#737373,color:#525252,stroke-width:2px
    classDef unknown fill:#ffffff,stroke:#a3a3a3,color:#666666,stroke-width:2px,stroke-dasharray:5 5
```

Accent green nodes are direct dependencies; dashed-border nodes are transitive dependencies.

If only `pyproject.toml` is discovered, the following dependency graph is produced.

```mermaid
---
config:
  themeVariables:
    fontSize: 12px
  flowchart:
    nodeSpacing: 16
    rankSpacing: 24
    padding: 4
    diagramPadding: 8
---
flowchart TD
    NX["networkx@v1.10"]:::prod
    FL8["flake8@3.9.2"]:::prod
    LOG["loguru~0.5"]:::prod
    classDef prod fill:#edf7f2,stroke:#1d7a54,color:#171717,stroke-width:2px
    classDef dev fill:#ffffff,stroke:#737373,color:#525252,stroke-width:2px
    classDef unknown fill:#ffffff,stroke:#a3a3a3,color:#666666,stroke-width:2px,stroke-dasharray:5 5
```

All nodes are direct dependencies. Transitive dependencies are not resolved without `poetry.lock`.

Without `poetry.lock` we are not able to identify any transitive dependencies. We are also unable to locally resolve dependency when version ranges are provided, like `loguru = "^0.5"`.

As `category` is not provided with poetry version greater or equal to [v1.5.0](https://github.com/dependabot/dependabot-core/pull/7418), FOSSA CLI will, first identify "main" dependencies by
using `tool.poetry.dependencies` from `pyproject.toml`. Afterwhich, it will [hydrate](https://github.com/fossas/fossa-cli/blob/master/docs/contributing/graph-hydration.md) dependencies. Any dependencies not hydrated, will be inferred to be a development dependency.

### References

- [Poetry Source Code](https://github.com/python-poetry/poetry)
- [Poetry Documentation](https://python-poetry.org/docs/)

---

Source: https://docs.fossa.com/docs/project-setup/supported-languages/python/pipenv

# Pipenv/Pipfile

This is a modern approach to defining python project dependencies, providing
very precise, complete dependency graphs for a python project.

## Project Discovery

Find all files named `Pipfile.lock`

## Analysis

We parse `Pipfile.lock` -- a json-structured file -- to find:

- `sources` - repositories/locations that can be referenced by packages
- `default` - production dependencies
- `develop` - development dependencies

Dependencies may contain an `index` field -- this is a reference to a repository
in the top-level `sources`.

Dependencies contain pinned `version` information.

When possible, we use `pipenv graph --json-tree` to hydrate the edges between
dependencies. This will fail unless `pipenv install` has been run in that directory.

## Limitations

- Pipfile.lock does not report edges, if `pipenv graph --json-tree` fails, we will
not be able to detect the edges between dependencies.

  - `pipenv graph --json-tree` relies on `pipenv install` being run in the directory beforehand.
  If that command was not run (such as in a freshly cloned repo), then the graph command will fail,
  which means that pipenv analysis will succeed, but with incomplete data (missing edges)
  - The graph command will also fail if `pipenv` is not installed or on the PATH.

## Examples

Pipenv does a lot of work behind the scenes, so even a trivial example is quite large.

`Pipfile` (created by running `pipenv install requests && pipenv install --dev pytest`):

```toml
[[source]]
url = "https://pypi.python.org/simple"
verify_ssl = true
name = "pypi"

[packages]
requests = "*"


[dev-packages]
pytest = "*"
```

`Pipfile.lock` (created at the same time as `Pipfile` above):
*This file is an example, and may not represent the exact versions you would find if you ran this example yourself.*

```json
{
    "_meta": {
        "hash": {
            "sha256": "03f05e808d849011739499ce042685cadfd6f14f4c6784ee3e6ad577b656437a"
        },
        "pipfile-spec": 6,
        "requires": {
            "python_version": "3.6"
        },
        "sources": [
            {
                "name": "pypi",
                "url": "https://pypi.org/simple",
                "verify_ssl": true
            }
        ]
    },
    "default": {
        "certifi": {
            "hashes": [
                "sha256:2bbf76fd432960138b3ef6dda3dde0544f27cbf8546c458e60baf371917ba9ee",
                "sha256:50b1e4f8446b06f41be7dd6338db18e0990601dce795c2b1686458aa7e8fa7d8"
            ],
            "version": "==2021.5.30"
        },
        "chardet": {
            "hashes": [
                "sha256:0d6f53a15db4120f2b08c94f11e7d93d2c911ee118b6b30a04ec3ee8310179fa",
                "sha256:f864054d66fd9118f2e67044ac8981a54775ec5b67aed0441892edb553d21da5"
            ],
            "version": "==4.0.0"
        },
        "idna": {
            "hashes": [
                "sha256:b307872f855b18632ce0c21c5e45be78c0ea7ae4c15c828c20788b26921eb3f6",
                "sha256:b97d804b1e9b523befed77c48dacec60e6dcb0b5391d57af6a65a312a90648c0"
            ],
            "version": "==2.10"
        },
        "requests": {
            "hashes": [
                "sha256:27973dd4a904a4f13b263a19c866c13b92a39ed1c964655f025f3f8d3d75b804",
                "sha256:c210084e36a42ae6b9219e00e48287def368a26d03a048ddad7bfee44f75871e"
            ],
            "index": "pypi",
            "version": "==2.25.1"
        },
        "urllib3": {
            "hashes": [
                "sha256:39fb8672126159acb139a7718dd10806104dec1e2f0f6c88aab05d17df10c8d4",
                "sha256:f57b4c16c62fa2760b7e3d97c35b255512fb6b59a259730f36ba32ce9f8e342f"
            ],
            "version": "==1.26.6"
        }
    },
    "develop": {
        "attrs": {
            "hashes": [
                "sha256:149e90d6d8ac20db7a955ad60cf0e6881a3f20d37096140088356da6c716b0b1",
                "sha256:ef6aaac3ca6cd92904cdd0d83f629a15f18053ec84e6432106f7a4d04ae4f5fb"
            ],
            "version": "==21.2.0"
        },
        "importlib-metadata": {
            "hashes": [
                "sha256:4a5611fea3768d3d967c447ab4e93f567d95db92225b43b7b238dbfb855d70bb",
                "sha256:c6513572926a96458f8c8f725bf0e00108fba0c9583ade9bd15b869c9d726e33"
            ],
            "markers": "python_version < '3.8'",
            "version": "==4.6.0"
        },
        "iniconfig": {
            "hashes": [
                "sha256:011e24c64b7f47f6ebd835bb12a743f2fbe9a26d4cecaa7f53bc4f35ee9da8b3",
                "sha256:bc3af051d7d14b2ee5ef9969666def0cd1a000e121eaea580d4a313df4b37f32"
            ],
            "version": "==1.1.1"
        },
        "packaging": {
            "hashes": [
                "sha256:5b327ac1320dc863dca72f4514ecc086f31186744b84a230374cc1fd776feae5",
                "sha256:67714da7f7bc052e064859c05c595155bd1ee9f69f76557e21f051443c20947a"
            ],
            "version": "==20.9"
        },
        "pluggy": {
            "hashes": [
                "sha256:15b2acde666561e1298d71b523007ed7364de07029219b604cf808bfa1c765b0",
                "sha256:966c145cd83c96502c3c3868f50408687b38434af77734af1e9ca461a4081d2d"
            ],
            "version": "==0.13.1"
        },
        "py": {
            "hashes": [
                "sha256:21b81bda15b66ef5e1a777a21c4dcd9c20ad3efd0b3f817e7a809035269e1bd3",
                "sha256:3b80836aa6d1feeaa108e046da6423ab8f6ceda6468545ae8d02d9d58d18818a"
            ],
            "version": "==1.10.0"
        },
        "pyparsing": {
            "hashes": [
                "sha256:c203ec8783bf771a155b207279b9bccb8dea02d8f0c9e5f8ead507bc3246ecc1",
                "sha256:ef9d7589ef3c200abe66653d3f1ab1033c3c419ae9b9bdb1240a85b024efc88b"
            ],
            "version": "==2.4.7"
        },
        "pytest": {
            "hashes": [
                "sha256:50bcad0a0b9c5a72c8e4e7c9855a3ad496ca6a881a3641b4260605450772c54b",
                "sha256:91ef2131a9bd6be8f76f1f08eac5c5317221d6ad1e143ae03894b862e8976890"
            ],
            "index": "pypi",
            "version": "==6.2.4"
        },
        "toml": {
            "hashes": [
                "sha256:806143ae5bfb6a3c6e736a764057db0e6a0e05e338b5630894a5f779cabb4f9b",
                "sha256:b3bda1d108d5dd99f4a20d24d9c348e91c4db7ab1b749200bded2f839ccbe68f"
            ],
            "version": "==0.10.2"
        },
        "typing-extensions": {
            "hashes": [
                "sha256:0ac0f89795dd19de6b97debb0c6af1c70987fd80a2d62d1958f7e56fcc31b497",
                "sha256:50b6f157849174217d0656f99dc82fe932884fb250826c18350e159ec6cdf342",
                "sha256:779383f6086d90c99ae41cf0ff39aac8a7937a9283ce0a414e5dd782f4c94a84"
            ],
            "markers": "python_version < '3.8'",
            "version": "==3.10.0.0"
        },
        "zipp": {
            "hashes": [
                "sha256:3607921face881ba3e026887d8150cca609d517579abe052ac81fc5aeffdbd76",
                "sha256:51cb66cc54621609dd593d1787f286ee42a5c0adbb4b29abea5a63edc3e03098"
            ],
            "version": "==3.4.1"
        }
    }
}
```

Output of `pipenv graph --json-tree`:

```json
[
    {
        "key": "pytest",
        "package_name": "pytest",
        "installed_version": "6.2.4",
        "required_version": "6.2.4",
        "dependencies": [
            {
                "key": "attrs",
                "package_name": "attrs",
                "installed_version": "21.2.0",
                "required_version": ">=19.2.0",
                "dependencies": []
            },
            {
                "key": "importlib-metadata",
                "package_name": "importlib-metadata",
                "installed_version": "4.6.0",
                "required_version": ">=0.12",
                "dependencies": [
                    {
                        "key": "typing-extensions",
                        "package_name": "typing-extensions",
                        "installed_version": "3.10.0.0",
                        "required_version": ">=3.6.4",
                        "dependencies": []
                    },
                    {
                        "key": "zipp",
                        "package_name": "zipp",
                        "installed_version": "3.4.1",
                        "required_version": ">=0.5",
                        "dependencies": []
                    }
                ]
            },
            {
                "key": "iniconfig",
                "package_name": "iniconfig",
                "installed_version": "1.1.1",
                "required_version": "Any",
                "dependencies": []
            },
            {
                "key": "pluggy",
                "package_name": "pluggy",
                "installed_version": "0.13.1",
                "required_version": ">=0.12,<1.0.0a1",
                "dependencies": [
                    {
                        "key": "importlib-metadata",
                        "package_name": "importlib-metadata",
                        "installed_version": "4.6.0",
                        "required_version": ">=0.12",
                        "dependencies": [
                            {
                                "key": "typing-extensions",
                                "package_name": "typing-extensions",
                                "installed_version": "3.10.0.0",
                                "required_version": ">=3.6.4",
                                "dependencies": []
                            },
                            {
                                "key": "zipp",
                                "package_name": "zipp",
                                "installed_version": "3.4.1",
                                "required_version": ">=0.5",
                                "dependencies": []
                            }
                        ]
                    }
                ]
            },
            {
                "key": "py",
                "package_name": "py",
                "installed_version": "1.10.0",
                "required_version": ">=1.8.2",
                "dependencies": []
            },
            {
                "key": "toml",
                "package_name": "toml",
                "installed_version": "0.10.2",
                "required_version": "Any",
                "dependencies": []
            }
        ]
    },
    {
        "key": "requests",
        "package_name": "requests",
        "installed_version": "2.25.1",
        "required_version": "2.25.1",
        "dependencies": [
            {
                "key": "certifi",
                "package_name": "certifi",
                "installed_version": "2021.5.30",
                "required_version": ">=2017.4.17",
                "dependencies": []
            },
            {
                "key": "chardet",
                "package_name": "chardet",
                "installed_version": "4.0.0",
                "required_version": ">=3.0.2,<5",
                "dependencies": []
            },
            {
                "key": "idna",
                "package_name": "idna",
                "installed_version": "2.10",
                "required_version": ">=2.5,<3",
                "dependencies": []
            },
            {
                "key": "urllib3",
                "package_name": "urllib3",
                "installed_version": "1.26.6",
                "required_version": ">=1.21.1,<1.27",
                "dependencies": []
            }
        ]
    }
]
```

Final graph from our analysis:

```mermaid
---
config:
  themeVariables:
    fontSize: 12px
  flowchart:
    nodeSpacing: 16
    rankSpacing: 24
    padding: 4
    diagramPadding: 8
---
flowchart TD
    REQ["requests"]:::prod --> CER["certifi"]:::prod
    REQ --> CHA["chardet"]:::prod
    REQ --> IDN["idna"]:::prod
    REQ --> URL["urllib3"]:::prod
    PYT["pytest"]:::dev --> INC["iniconfig"]:::dev
    PYT --> PLG["pluggy"]:::dev
    PYT --> PY["py"]:::dev
    PYT --> TOM["toml"]:::dev
    PYT --> ATT["attrs"]:::dev
    PLG --> IM["importlib-metadata"]:::dev
    IM --> TYP["typing-extensions"]:::dev
    IM --> ZIP["zipp"]:::dev
    classDef prod fill:#edf7f2,stroke:#1d7a54,color:#171717,stroke-width:2px
    classDef dev fill:#ffffff,stroke:#737373,color:#525252,stroke-width:2px
    classDef unknown fill:#ffffff,stroke:#a3a3a3,color:#666666,stroke-width:2px,stroke-dasharray:5 5
```

Accent green nodes are production dependencies. Gray nodes are development dependencies (`pipenv` does not distinguish dev from test).

The versions are omitted here, but are tracked as part of the graph as well.

---

Source: https://docs.fossa.com/docs/project-setup/supported-languages/python/pipenv-qr

# Quick reference: pipenv

## Requirements

**Ideal**

- `pipenv` buildtool installed
- `Pipfile.lock` file present in your project

**Minimum**

- `Pipfile.lock` file present in your project

## Project discovery

Directories containing `Pipfile.lock` files are considered pipenv projects.

---

Source: https://docs.fossa.com/docs/project-setup/supported-languages/python/conda

# Conda Analysis

While originally created for Python programs, Conda can package and distribute software for any language. It provides a full list of all dependencies installed in the environment, without providing a dependency graph.

## Project Discovery

A conda project is discovered if the project directory contains an `environment.yml` file.

## Analysis: conda env create

Run `conda env create --json --file environment.yml --dry-run --yes` to get a complete list of packages that would be installed by `conda env create -f environment.yml`.
Using the `--dry-run` option means that `fossa-cli` does not actually modify any local environments. 
This process can take some time since `conda` may need to refresh its package data in order to run the command. 
In our tests we have seen it take up to 3 minutes, for very large conda environments it could be longer.

## Analysis: environment.yml

If the `conda list --json` operation does not succeed, we fall back to parsing the `environment.yml`, and getting the list of dependencies from the `dependencies` section of this file.

---

Source: https://docs.fossa.com/docs/project-setup/supported-languages/python/pdm

# PDM

[PDM](https://pdm.fming.dev/latest/) is a tool for dependency management and packaging in Python.

## Project Discovery

Find files named `pyproject.toml` and `pdm.lock`.

## Analysis

| Strategy                                       | Direct Deps        | Transitive Deps    | Edges              |
| ---------------------------------------------- | ------------------ | ------------------ | ------------------ |
| `pyproject.toml` and `pdm.lock` are discovered | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: |
| Only `pyproject.toml` is discovered            | :heavy_check_mark: | :x:                | :x:                |
| Only `pdm.lock` is discovered                  | :x:                | :x:                | :x:                |

- :heavy_check_mark: - Supported in all projects
- :x: - Not Supported

We parse `pyproject.toml` to find, 
- direct dependencies, from `[project]'s dependencies`, 
- direct optional dependencies, from `[project.optional-dependencies]`, 
- direct development dependencies, from `[tool.pdm.dev-dependencies]`

FOSSA does not consider optional dependencies, as production
dependencies for PDM, and as such they will be discarded from final analysis findings.

If `pdm.lock` file is discovered, following will be analyzed from lockfile to supplement the analyses:

- `[[package]]` - package's dependencies
- `[[package]].name` - name of the package
- `[[package]].version` - resolved version of the package
- `[[package]].dependencies` - list of dependencies
- `[[package]].git` - git url, if the dependency's source is git vcs
- `[[package]].revision` - revision associated with the git vcs
- `[[package]].path` - local path, if the dependency's source is filesystem

To identify, if the package is `production` dependency, or `development` dependency, `fossa-cli`
hydrates the dependency graph from lockfile with `pyrpoject.toml`. 

1. `fossa-cli` marks any dependency in `pyproject.toml`'s `[]` as production dependencies, 
and rest as development dependencies. 

2. `fossa-cli` propogates this dependency environment marking to all transitive dependencies,
marking all reachable nodes.

For example,

```mermaid
---
config:
  themeVariables:
    fontSize: 12px
  flowchart:
    nodeSpacing: 16
    rankSpacing: 24
    padding: 4
    diagramPadding: 8
---
flowchart TD
    A["requests@2.25.1"] -->  B["certifi@2023.5.7"]:::unknown
    A:::prod --> C["chardet@4.0.0"]:::unknown
    A --> D["idna@2.10"]:::unknown
    A --> E["urllib3@1.26.16"]:::unknown
    J["pytest@7.3.1"]:::dev --> K["iniconfig@2.0.0"]:::unknown
    J --> L["packaging@23.1"]:::unknown
    J --> M["pluggy@1.0.0"]:::unknown
    classDef prod fill:#edf7f2,stroke:#1d7a54,color:#171717,stroke-width:2px
    classDef dev fill:#ffffff,stroke:#737373,color:#525252,stroke-width:2px
    classDef unknown fill:#ffffff,stroke:#a3a3a3,color:#666666,stroke-width:2px,stroke-dasharray:5 5
```

would be hydrated to following graph:

```mermaid
---
config:
  themeVariables:
    fontSize: 12px
  flowchart:
    nodeSpacing: 16
    rankSpacing: 24
    padding: 4
    diagramPadding: 8
---
flowchart TD
    A["requests@2.25.1"] -->  B["certifi@2023.5.7"]:::prod
    A:::prod --> C["chardet@4.0.0"]:::prod
    A --> D["idna@2.10"]:::prod
    A --> E["urllib3@1.26.16"]:::prod
    J["pytest@7.3.1"]:::dev --> K["iniconfig@2.0.0"]:::dev
    J --> L["packaging@23.1"]:::dev
    J --> M["pluggy@1.0.0"]:::dev
    classDef prod fill:#edf7f2,stroke:#1d7a54,color:#171717,stroke-width:2px
    classDef dev fill:#ffffff,stroke:#737373,color:#525252,stroke-width:2px
    classDef unknown fill:#ffffff,stroke:#a3a3a3,color:#666666,stroke-width:2px,stroke-dasharray:5 5
```

In these graphs, accent green signifies production dependency, gray signifies development dependency,
and white with a dashed border signifies unknown environment. If a dependency shared parent who had `development` marking, as well as `production` marking, `fossa-cli` marks this dependency as production dependency.

### Limitations

- Any [local dependencies](https://pdm.fming.dev/latest/usage/dependency/#local-dependencies) will not be reported, by default. To enable, local dependencies in analysis, enable experimental path dependencies. Learn more about [path dependencies and how to enable them](/docs/cli/references/experimental/path-dependency).
- Any dependency using: `hg` (mercurial), `svn` (subversion), `bzr` (bazaar) source, will not be reported.

## Example

1. Create `pyproject.toml` file

```toml
[project]
name = "myexample"
version = "1.0.0"
description = "example pyproject toml file"
authors = [
    {name = "fossa", email = "support@fossa.com"},
]
dependencies = [
    "requests==2.25.1",
]
requires-python = ">=3.11"
license = {text = "MIT"}

[project.optional-dependencies]
extra = ["black"]

[tool.pdm.dev-dependencies]
test = [
    "pytest>=7.3.1",
]
```

1. Perform `pdm lock` to create `pdm.lock` file.

```toml
# This file is @generated by PDM.
# It is not intended for manual editing.

[[package]]
name = "certifi"
version = "2023.5.7"
requires_python = ">=3.6"
summary = "Python package for providing Mozilla's CA Bundle."

[[package]]
name = "chardet"
version = "4.0.0"
requires_python = ">=2.7, !=3.0.*, !=3.1.*, !=3.2.*, !=3.3.*, !=3.4.*"
summary = "Universal encoding detector for Python 2 and 3"

[[package]]
name = "colorama"
version = "0.4.6"
requires_python = "!=3.0.*,!=3.1.*,!=3.2.*,!=3.3.*,!=3.4.*,!=3.5.*,!=3.6.*,>=2.7"
summary = "Cross-platform colored terminal text."

[[package]]
name = "idna"
version = "2.10"
requires_python = ">=2.7, !=3.0.*, !=3.1.*, !=3.2.*, !=3.3.*"
summary = "Internationalized Domain Names in Applications (IDNA)"

[[package]]
name = "iniconfig"
version = "2.0.0"
requires_python = ">=3.7"
summary = "brain-dead simple config-ini parsing"

[[package]]
name = "packaging"
version = "23.1"
requires_python = ">=3.7"
summary = "Core utilities for Python packages"

[[package]]
name = "pluggy"
version = "1.0.0"
requires_python = ">=3.6"
summary = "plugin and hook calling mechanisms for python"

[[package]]
name = "pytest"
version = "7.3.1"
requires_python = ">=3.7"
summary = "pytest: simple powerful testing with Python"
dependencies = [
    "colorama; sys_platform == \"win32\"",
    "iniconfig",
    "packaging",
    "pluggy<2.0,>=0.12",
]

[[package]]
name = "requests"
version = "2.25.1"
requires_python = ">=2.7, !=3.0.*, !=3.1.*, !=3.2.*, !=3.3.*, !=3.4.*"
summary = "Python HTTP for Humans."
dependencies = [
    "certifi>=2017.4.17",
    "chardet<5,>=3.0.2",
    "idna<3,>=2.5",
    "urllib3<1.27,>=1.21.1",
]

[[package]]
name = "urllib3"
version = "1.26.16"
requires_python = ">=2.7, !=3.0.*, !=3.1.*, !=3.2.*, !=3.3.*, !=3.4.*, !=3.5.*"
summary = "HTTP library with thread-safe connection pooling, file post, and more."

[metadata] # not shown for brevity
[metadata.files] # not shown for brevity
```

3. Perform `fossa analyze`

```bash
fossa analyze && fossa test
```

Note: Sometimes with pdm, when you perform `pdm` install, it creates `*.egg-info` directory, 
which contains `requires.txt`. This may introduce additional dependency in the analysis, as
`fossa-cli` will consider `requires.txt` to be `setuptool` manifest. 

To exclude such unwanted dependencies in your analysis, you can use [.fossa.yml](/docs/cli/references/files/fossa-yml)
file to exclude specific paths from the analysis. Here is an example:

```yml
# filename: .fossa.yml

version: 3

paths:
  exclude:
    - ./myexample.egg-info
```

### F.A.Q

1. How do I perform analysis for only `pdm`?

Explicitly specify an analysis target in `.fossa.yml` file. The example below excludes all other analysis targets:

```yaml
# .fossa.yml 

version: 3
targets:
  only:
    - type: pdm
```


2. How do I include optional and development dependencies in the analysis? 

You can include all optional and development dependencies in the analysis using: `--include-unused-deps` flag. If you want to only include optional dependencies in the analysis (without development dependencies), currently this is not possible. 

```bash
fossa analyze --include-unused-deps
```

3. I have path dependency, would FOSSA analyze it's transitive dependencies?

Fossa analysis discraded path dependencies in the analysis, but keeps it's non-path transitive dependencies, 
in the analysis.

### References

- [PDM Source Code](https://github.com/pdm-project/pdm)
- [PDM Documentation](https://pdm.fming.dev/latest/)

---

Source: https://docs.fossa.com/docs/project-setup/supported-languages/python/uv

# uv

[uv](https://docs.astral.sh/uv/) is a package and project manager for Python.

The uv strategy is a static analysis strategy and does not require the use of any external tools.

## Project Discovery

Find files named `uv.lock`. uv also uses `pyproject.toml` to define dependencies, but only the presence of a lock file is used to detect uv projects.

## Analysis

We parse the `uv.lock` file, which is in the TOML format. This file contains an array named `package` which contains all the direct and transitive dependencies in the project. Each package has a field `dependencies` which is used to build the edges in the dependency graph.

---

Source: https://docs.fossa.com/docs/project-setup/supported-languages/nodejs

# JavaScript

FOSSA supports JavaScript and Node.js codebases through npm, Yarn, and Pnpm. You can analyze a project two ways: **Quick Import** in the web app, or the **FOSSA CLI** for complex builds.

## Tool support

| Tool | Quick Import (app.fossa.com) | CLI (fossa-cli) | fossa-deps |
| :-- | :-- | :-- | :-- |
| [npm](https://npmjs.com) | `package.json`, `package-lock.json` | `package.json`, `package-lock.json` | supported |
| [Yarn](https://yarnpkg.com/en/) | `yarn.lock` | `package.json`, `yarn.lock` | supported |
| [Pnpm](https://pnpm.io/) | N/A | `pnpm-lock.yaml` | supported |
| [Bower](https://bower.io/) | N/A | N/A | partially supported |

## How Quick Import works

When JavaScript code is imported through the web app, FOSSA resolves dependencies by attempting to build your codebase via `npm install --production` or `yarn install --frozen-lockfile`. If you provide lockfiles, FOSSA prefers them.

If the build fails or is disabled by setting `prefer_mediated_dependencies` to `false`, FOSSA falls back to statically analyzing and traversing your package manifests (`package.json`, `yarn.lock`, `component.json`). By default, FOSSA filters out any `devDependencies` entries.

{% callout type="info" %}
If you have build scripts that change your build behavior, use the FOSSA CLI to scan your project instead. We call these scans Provided Builds. The CLI runs inside your build environment, so it can resolve dependencies Quick Import cannot.
{% /callout %}

## Analyzing with the CLI

For complex JavaScript builds that rely on custom tooling, scripts, or workspaces, CI/CD scanning with the FOSSA CLI is the ideal integration path.

Install the latest release of `fossa-cli`:

```shell
curl -H 'Cache-Control: no-cache' https://raw.githubusercontent.com/fossas/fossa-cli/master/install-latest.sh | bash
```

Then run `fossa analyze` from your repository's root directory. The Node.js build-tool ecosystem consists of three major toolchains, the `npm` CLI, `pnpm`, and `yarn`. The CLI selects a strategy per project; each strategy's detection details are linked in the table below.

### Analysis strategies

| Strategy | Direct Deps | Transitive Deps | Edges | Container Scanning |
| --- | --- | --- | --- | --- |
| [yarnlock](/docs/project-setup/supported-languages/nodejs/yarn) | :white_check_mark: | :white_check_mark: | :white_check_mark: | :white_check_mark: |
| [npmlock](/docs/project-setup/supported-languages/nodejs/npm-lockfile) | :white_check_mark: | :white_check_mark: | :white_check_mark: | :white_check_mark: |
| [pnpmlock](/docs/project-setup/supported-languages/nodejs/pnpm) | :white_check_mark: | :white_check_mark: | :white_check_mark: | :white_check_mark: |
| [packagejson](/docs/project-setup/supported-languages/nodejs/packagejson) | :white_check_mark: | :x: | :x: | :white_check_mark: |

* :white_check_mark:, Supported only when relevant data is available (e.g. lockfiles are present)
* :x:, Not supported

## Authenticating to private registries

You can configure FOSSA to fetch dependencies from authenticated registries, such as privately-scoped packages on npmjs.com, private Artifactory instances, or npm Enterprise instances.

{% steps %}
{% step title="Open JavaScript language settings" %}
Go to **Account Settings → Languages → NPM** (`https://app.fossa.com/account/settings/languages/npm`).
{% /step %}
{% step title="Add your registry credentials" %}
For each registry, provide either an email/username/password or an authentication token, then save.
{% /step %}
{% step title="Retry unreachable dependencies" %}
After saving, you can **retry** any previously unreachable `npm` dependencies in FOSSA and begin to analyze them.
{% /step %}
{% /steps %}

{% callout type="info" %}
If you don't know your credentials, you can find them in `.npmrc` or `~/.npmrc` after running `npm login`. [Learn more.](https://docs.npmjs.com/files/npmrc)
{% /callout %}

{% img src="/images/project-setup/7864ad9-Screen_Shot_2018-03-25_at_12.52.34_PM.png" alt="JavaScript private registry credentials in Account Settings" /%}

The legacy doc described three private-registry scenarios:

{% tabs %}
{% tab title="Private packages on npmjs.com" %}
For privately-scoped packages on npmjs.com, add your login credentials in JavaScript language settings as described above. FOSSA uses them to reach your scoped packages.
{% /tab %}
{% tab title="Private artifact registries" %}
npm Enterprise and Artifactory-configured npm registries are supported on FOSSA on-prem deployments. A FOSSA admin configures authentication in FOSSA's `config.env` file using either an auth token (`fetchers__npm__auth_token`) or legacy email/auth/username fields, matching whichever format appears in your `.npmrc`. The admin restarts FOSSA after configuring.
{% /tab %}
{% tab title="Private registries" %}
For a private registry such as Artifactory, a FOSSA admin can specify the registry URL (`fetchers__npm__registry`) in `config.env`. Registries that require authentication are configured using the credential methods above.
{% /tab %}
{% /tabs %}

{% callout type="warning" %}
npm Enterprise and Artifactory-configured npm registries are only supported on FOSSA on-prem deployments.
{% /callout %}

The settings route and label above were verified against `app/components/settings/languages/index.tsx` and `app/routes.tsx` in FOSSA-Core, where the JavaScript settings page is registered at path `npm` with the nav label "NPM".

## Package data

FOSSA supports the standard JavaScript package formats published to npm, Yarn, and Pnpm registries. When lockfiles (`package-lock.json`, `yarn.lock`, `pnpm-lock.yaml`) are present, FOSSA resolves the full dependency graph; without them it falls back to the dependencies declared in `package.json`. By default, `devDependencies` are filtered out.

---

Source: https://docs.fossa.com/docs/project-setup/supported-languages/nodejs/npm

# Quick reference: npm

## Requirements

A `package.json` file is required to be present all types of npm analysis.

Running `npm install` and generating a `package-lock.json` file will provide significantly better results. This allows FOSSA to detect the full dependency graph.

> Note: The `package-lock.json` file is expected to be located in the same directory as the `package.json` file.

## Project discovery

Directories containing `package.json` files are considered npm projects. `node_modules` subdirectories are skipped.

---

Source: https://docs.fossa.com/docs/project-setup/supported-languages/nodejs/yarn

# Yarn

Yarn is a spiritual successor to the npm cli. Yarn automatically updates the
`yarn.lock` file when the yarn CLI is used to modify the dependencies present in
the project. The `yarn.lock` file contains information about a dependency's
transitive dependencies, its location, and its resolved version.

## Project Discovery

Find all files named `yarn.lock` which have a corresponding `package.json` file.

## Analysis

yarn.lock has its own bespoke format. Dependencies typically look something
like:

```yarn-lock
"@babel/code-frame@^7.0.0", "@babel/code-frame@^7.5.5":
  version "7.5.5"
  resolved "https://registry.yarnpkg.com/@babel/code-frame/-/code-frame-7.5.5.tgz#bc0782f6d69f7b7d49531219699b988f669a8f9d"
  integrity sha512-27d4lZoomVyo51VegxI20xZPuSHusqbQag/ztrBC7wegWoQ1nLREPVSKSW8byhTlzTKyNE4ifaTA6lCp7JjpFw==
  dependencies:
    "@babel/highlight" "^7.0.0"
```

where:

- `resolved` is the exact location of the dependency
- `version` is a pinned dependency
- the section "keys" contain constraints used by other packages to refer to this
  dependency
- `dependencies` is a list of constraints for dependencies of this package

We also support yarn V2, which uses a similar, though mechanically different
schema, but uses standard YAML rather than a bespoke format.

As of _v2.19.x_, we also support yarn workspaces.  In practice, this means that
the `package.json` files used to build the `yarn.lock` file are also checked,
and the knowledge of both is combined to form a (usually) complete picture of
the full graph of dependencies.


## FAQ

### What Yarn Protocols are supported

There are many default [Yarn protocols](https://yarnpkg.com/protocols) that Yarn allows users to fetch dependencies. The FOSSA CLI currently supports the `npm` and `git` protocols.

---

Source: https://docs.fossa.com/docs/project-setup/supported-languages/nodejs/pnpm

# Pnpm

[Pnpm](https://pnpm.io/) is a fast, disk space-efficient package manager.
Unlike npm and yarn, pnpm uses symbolic links to create a nested structure
of dependencies.

## Project Discovery

Find files named `pnpm-lock.yaml` with a corresponding `package.json` file.

## Analysis

Only `pnpm-lock.yaml` is used for analysis. CLI will parse and use the following fields.
in `pnpm-lock.yaml` to analyze the dependency graph.

- `importers`
  - `[importersKey]`
    - `dependencies`: list of direct dependencies
    - `devDependencies`: list of development dependencies

- `packages`
  - `[packagesKey]`
    - `resolution`: infer git URL, git commit, or package source URL.
    - `dependencies`: list of transitive dependencies
    - `peerDependencies`: list of peer dependencies (will be treated like any other dependency)
    - `dev`: to infer if this is used dependency or not. If the value is `true` by default CLI will not include this in the final analysis.

An example is provided below:

```yml
lockfileVersion: 5.4

importers:
  .:
    specifiers:
      some-pkg: https://some-url/pkg.tar.gz
      react: '*'
      my-local-pkg: file:../libs/my-local-pkg
    dependencies:
      some-pkg: '@some-url/pkg.tar.gz'
      my-local-pkg: file:../libs/my-local-pkg
    devDependencies:
      react: 18.1.0

  # workspace project in packages/some-ws-pkg directory from root.
  packages/some-ws-pkg:
    specifiers:
      commander: 9.2.0
    dependencies:
      commander: 9.2.0

packages:
    '@some-url/pkg.tar.gz':
        resolution: {tarball: https://some-url/pkg.tar.gz}
        name: some-pkg
        version: 1.0.0
        engines: {node: '>=4.0.0'}
        dev: false

    file:../libs/my-local-pkg:
        resolution: {directory: "../libs/my-local-pkg", type: directory}
        name: unifier
        version: 1.0.0
        dependencies:
            loose-envify: 1.4.0
        engines: {node: '>=4.0.0'}
        dev: false

    /commander/9.2.0:
        resolution: {integrity: sha512-e2i4wANQiSXgnrBlIatyHtP1odfUp0BbV5Y5nEGbxtIrStkEOAAzCUirvLBNXHLr7kwLvJl6V+4V3XV9x7Wd9w==}
        engines: {node: ^12.20.0 || >=14}
        dev: false

    /react/18.1.0:
        resolution: {integrity: sha512-4oL8ivCz5ZEPyclFQXaNksK3adutVS8l2xzZU0cqEFrE9Sb7fC0EFK5uEk74wIreL1DERyjvsU915j1pcT2uEQ==}
        engines: {node: '>=0.10.0'}
        dependencies:
            loose-envify: 1.4.0
        dev: true

    /loose-envify/1.4.0:
        resolution: {integrity: sha512-lyuxPGr/Wfhrlem2CL/UcnUc1zcqKAImBDzukY7Y5F/yQiNdko6+fRLevlw1HgMySw7f611UIY408EtxRSoK3Q==}
        hasBin: true
        dependencies:
            js-tokens: 4.0.0
        dev: false

    /js-tokens/4.0.0:
        resolution: {integrity: sha512-RdJUflcE3cUzKiMqQgsCu06FPu9UdIJO0beYbPhHN4k6apgJtifcoCtT9bcxOpYBtpD2kCM6Sbzg4CausW/PKQ==}
        dev: true

```

* If the dependency was resolved using git (`resolution` will have `type: git` attribute),
FOSSA will use provided `repo` and `commit` attribute to analyze this dependency.

```yaml
    # FOSSA will use `commit` and `repo` to analyze the this dependency.
    github.com/Marak/colors.js/6bc50e79eeaa1d87369bb3e7e608ebed18c5cf26:
      resolution: {commit: 6bc50e79eeaa1d87369bb3e7e608ebed18c5cf26, repo: git+ssh://git@github.com/Marak/colors.js, type: git}
      name: colors
      version: 1.4.44-liberty-2
      engines: {node: '>=0.1.90'}
      dev: false
```

* If the dependency was resolved using tarball (`resolution` will have `tarball` attribute)
FOSSA will use provided URL address to download and analyze this dependency.

```yaml
    # FOSSA will analyze lodash from the tarball URL.
    '@some-url/pkg.tar.gz':
        resolution: {tarball: https://some-url/pkg.tar.gz}
        name: some-pkg
        version: 1.0.0
        engines: {node: '>=4.0.0'}
        dev: false
```

* If the dependency was resolved using the local directory (`resolution` will have the `type: directory` attribute),
FOSSA will not analyze this dependency. Local dependency's transitive dependencies will be analyzed,
and they will be promoted in place of local dependency.

```yaml
    # FOSSA will not analyze this dependency,
    # But FOSSA will analyze its transitive dependency (if they are not sourced from the local directory)
    #
    # FOSSA will promote loose-envify of 1.4.0 in place of unifier.
    file:../libs/my-local-pkg:
        resolution: {directory: "../libs/my-local-pkg", type: directory}
        name: unifier
        version: 1.0.0
        dependencies:
            loose-envify: 1.4.0
        engines: {node: '>=4.0.0'}
        dev: false
```

* If the dependency was resolved using registry resolver, FOSSA will use the registry to analyze the dependency.
CLI will infer the package name and version using `/${dependencyName}/${dependencyVersion}` scheme from the package's key.

```yaml
    # Resolves to npm dependency: commander with 9.2.0 version
    /commander/9.2.0:
        resolution: {integrity: sha512-e2i4wANQiSXgnrBlIatyHtP1odfUp0BbV5Y5nEGbxtIrStkEOAAzCUirvLBNXHLr7kwLvJl6V+4V3XV9x7Wd9w==}
        engines: {node: ^12.20.0 || >=14}
        dev: false
```

* Peer dependencies will be included in the analysis (they are treated like any other dependency).
* Pnpm workspaces are supported.
* Development dependencies (`dev: true`) are ignored by default from analysis. To include them in the analysis, execute CLI with `--include-unused-deps` flag e.g. `fossa analyze --include-unused-deps`.
* Optional dependencies are included in the analysis by default. They can be ignored in FOSSA UI.
* `fossa-cli` supports lockFileVersion: 4.x, 5.x, 6.x, 7.x, 8.x, and 9.x.


# F.A.Q

### How do I perform analysis only for pnpm projects?

You can explicitly specify an analysis target in `.fossa.yml` file. The example below will exclude all analysis targets except for pnpm.

```yaml
# .fossa.yml

version: 3
targets:
  only:
    - type: pnpm
```

---

Source: https://docs.fossa.com/docs/project-setup/supported-languages/nodejs/packagejson

# package.json

package.json is a common build manifest used by both yarn and npmcli.

## Project Discovery

`npm`: Find all files named `package.json`, not descending into directories
named `node_modules`

## Analysis

`package.json` is a user modified file that specifies which dependencies are
mandatory in order to run your project. This file lists dependencies with their
version specifier. These dependencies are user specified and map nearly 1:1 with
direct dependencies, however users may also specify their desired version for
transitive dependencies which would invalidate the assumption that all
dependencies specified here are direct.

There is also a different block for development dependencies which allows us to
accurately determine part of the tags available for node.

As of _v2.19.x_, we also combine `package.json` files that are members of the
same workspace.  The files are treated as though all dependencies were found
from the same file, though we report the origins of the deps as a set of all
files.

---

Source: https://docs.fossa.com/docs/project-setup/supported-languages/nodejs/npm-lockfile

# Npm Lockfile

The `package-lock.json` file is generated when npm modifies `node_modules` or
`package.json` and describes the exact dependency tree generated. One example of
this is when `npm install` is run.

> Note: In old versions of npm, `package-lock.json` was only modified when
> dependencies were installed.

## Project Discovery

Search for files named `package.json` and check for a corresponding
`package-lock.json` in the same directory, ignoring directories named
`node_modules`.

> Note: When using NPM workspaces, only the root of the project will have a
> `package-lock.json`. The other `package.json` files in the project directory
> will be combined to determine which dependencies are direct and which ones are
> development.

## Analysis (for lockFile version 3)

We consider `package-lock.json` to be version 3 compatible, if and only if, 

- `lockFileVersion` field exists, and is of value 3
- `packages` field exists in the `package-lock.json`.

In `package-lock.json`, `packages` object's key refer to filepath for associated `package.json`.

Generally, we have three types of data shape within `packages` map.

1) Root module (denoted by having `""` key)

```json
  "": {
      "name": "packageLockV3",
      "version": "1.0.0",
      "license": "ISC",
      "dependencies": {
          "foo": "^1.0.0",
          "boo": "^1.0.0"
      }
  }
```

2) Workspace module

```json
  "packages/a": {
      "name": "packageLockV3PkgA",
      "version": "2.0.0",
      "license": "ISC",
      "dependencies": {
          "foo": "^2.0.0"
      }
  }
```

Workspace module, in essence is type of root module whose parent is top level root module (as shown in (1)).

3) Package Module (these are the dependencies which fossa will report)

```json
  "node_modules/foo": {
      "version": "1.2.0",
      "resolved": "https://registry.npmjs.org/foo/-/foo-1.2.0.tgz"
  },
  "node_modules/bar": {
      "version": "1.3.0",
      "resolved": "https://registry.npmjs.org/bar/-/bar-1.3.0.tgz",
      "dependencies": {
          "baz": "^1.0.0"
      }
  },
  "node_modules/baz": {
      "version": "1.9.0",
      "resolved": "https://registry.npmjs.org/baz/-/baz-1.9.0.tgz"
  },
  "packages/a/node_modules/foo": {
      "version": "2.0.0",
      "resolved": "https://registry.npmjs.org/foo/-/foo-2.0.0.tgz"
  }
```

We will attempt infer the resolved version by looking at package's key. 

For instance, to infer resolved version of `foo@^2.0.0` for `packages/a`,
we will attempt to see if the dependency was resolved at vendored path, 
or at top level path. 

If we find, `packages/a/node_modules/foo` key in our packages object, we use it's
resolved version. If this key does not exist we fallback to `node_modules/foo`.

With this approach, for aforementioned example, we will generate following dependency tree:

```text
-- foo@2.0.0      (via workspace package a)
-- foo@1.2.0      (via root package.json)
-- bar@1.3.0      (via root package.json)
    \- baz@1.9.0  (transitive dep via bar@1.3.0)
```

We use `dev` field to infer if the dependency is development dependency or not.

We analyze `optional` dependencies. If you would like to ignore them, you can do
so from [FOSSA UI](https://docs.fossa.com/docs/generating-reports#modifying-report-information).

## Analysis (for lockFile version 1)

Opening a `package-lock.json` file reveals the project's dependency tree. This
dependency tree contains information about a dependency's version, its
transitive dependencies, the URL where the dependency is located at, and whether
or not the dependency is used as a development dependency or not. The transitive
dependency information is listed in an unintuitive way. Under each dependency
there may be two fields, `requires` and `dependencies` as in the following
example:

```json
    "babel-code-frame": {
      "version": "6.26.0",
      "resolved": "https://registry.npmjs.org/babel-code-frame/-/babel-code-frame-6.26.0.tgz",
      "integrity": "sha1-Y/1D99weO7fONZR9uP42mj9Yx0s=",
      "requires": {
        "chalk": "1.1.3",
        "esutils": "2.0.3",
        "js-tokens": "3.0.2"
      },
      "dependencies": {
        "ansi-styles": {
          "version": "2.2.1",
          "resolved": "https://registry.npmjs.org/ansi-styles/-/ansi-styles-2.2.1.tgz",
          "integrity": "sha1-tDLdM1i2NM914eRmQ2gkBTPB3b4="
        },
        "js-tokens": {
          "version": "3.0.2",
          "resolved": "https://registry.npmjs.org/js-tokens/-/js-tokens-3.0.2.tgz",
          "integrity": "sha1-mGbfOVECEw449/mWvOtlRDIJwls="
        }
      }
    }
```

The `requires` field signifies all of the dependencies that are needed by the
dependency in order to properly function.

The `dependencies` field signifies all of the dependencies included in
`babel-code-frame`'s `node_modules` folder within the top level `node_modules`
folder. Notice that these dependencies are not always included in the `requires`
section.

> Note: `npm-shrinkwrap.json` is an identically formatted file that can be used
> for [publishing packages](https://docs.npmjs.com/cli/shrinkwrap).

### Peer Dependencies

Top-level peer dependencies from `package.json` are treated as if they were
direct dependencies of the project. Peer dependencies of transitive deps are
also treated as transitive dependencies. If a transitive peer dependency also
happens to be a direct dependency then it is reported as direct rather than
transitive, however. The reason FOSSA does this is because as of `npm` 7+ peer
dependencies and transitive peer dependencies are installed by default.

`fossa-cli` doesn't report peer dependencies in a special way because FOSSA does
not model peer dependencies natively. Because direct peer dependencies are
defined in the same place as regular direct dependencies (`package.json`) and
because NPM installs them by default for FOSSA's purposes they are considered
direct. If FOSSA didn't report these dependencies users may potentially miss
license information about dependencies that would have implications for the
distribution of their projects.

Transitive peer dependencies are found in the `packages` key of
`package-lock.json` files produced by recent versions of `npm`.  The `packages`
key holds similar information to the those under the `dependencies` key, but
`packages` includes information about peer dependencies for each dependency or
transitive dependency the project uses. For example, an entry might look like
this:

```json
    "node_modules/chai-dom": {
        "version": "1.11.0",
        "resolved": "https://registry.npmjs.org/chai-dom/-/chai-dom-1.11.0.tgz",
        "integrity": "sha512-ZzGlEfk1UhHH5+N0t9bDqstOxPEXmn3EyXvtsok5rfXVDOFDJbHVy12rED6ZwkJAUDs2w7/Da4Hlq2LB63kltg==",
        "peer": true,
        "engines": {
            "node": ">= 0.12.0"
        },
        "peerDependencies": {
            "chai": ">= 3",
            "mocha": ">= 2"
        }
    }
```

In this example, when `fossa-cli` does analysis of `chai-dom`, it will include
`chai` and `mocha` as dependencies`chai-dom`. The transitive deps for `chai` and
`mocha` will also be captured.

---

Source: https://docs.fossa.com/docs/project-setup/supported-languages/nodejs/yarn-qr

# Quick reference: yarn

## Requirements

**Ideal/Minimum**

- `yarn.lock` file present in your project
- `package.json` file present in your project

## Project discovery

Directories containing `yarn.lock`/`package.json` files are considered yarn projects. `node_modules` subdirectories are skipped.

---

Source: https://docs.fossa.com/docs/project-setup/supported-languages/golang

# Go

FOSSA supports Go codebases through Go Modules, Dep, Govendor, Gopkg, and Glide. You can analyze a project two ways: **Quick Import** in the web app, or the **FOSSA CLI**.

Historically, the Go build-tool ecosystem has been very fragmented: tools like Dep, Glide, and Govendor each tried to address build reproducibility, versioning, and vendoring of dependencies. As of Go 1.11, Go has first-class support for **modules**, which solves the versioning and build-reproducibility problems so well that the other tooling has largely gone into maintenance mode, with the notable exception of Dep. As such, Go analysis primarily targets Go 1.11+ modules and Dep, with Glide support included because it is still commonly used.

## Tool support

| Tool |
| :-- |
| Go modules |
| Dep |
| Govendor |
| Gopkg |
| Glide |

## How Quick Import works

When Go code is imported through the web app, FOSSA inspects the supported manifest and lockfiles in your repository and resolves their dependencies for analysis.

{% callout type="info" %}
If a Go dependency refers to a Git repository, it may be displayed as a Git project in FOSSA. When that happens, FOSSA may show the commit hash as the version and the Git repository URL as the package name.
{% /callout %}

## Analyzing with the CLI

Install the latest release of `fossa-cli`:

```shell
curl -H 'Cache-Control: no-cache' https://raw.githubusercontent.com/fossas/fossa-cli/master/install-latest.sh | bash
```

Then run `fossa analyze` from your repository's root directory to analyze your Go project.

The CLI selects a strategy per project. Most strategies (except `gomod`, where it would be redundant since `golist` supersedes it) use `go list -json all` to hydrate edges and transitive dependencies: package imports are recursively traversed, ignoring `Standard` (system) packages. `go list` behaves slightly differently depending on context, in a Go modules project, packages can carry a `Module` field with a pinned `Version` (otherwise the version is unspecified), and `go list` includes vendored packages in both modules and non-modules projects.

### Analysis strategies

| Strategy | Direct Deps | Transitive Deps | Edges | Container Scanning |
| --- | --- | --- | --- | --- |
| [golist](/docs/project-setup/supported-languages/golang/gomodules) | :white_check_mark: | :white_check_mark: | :warning: | :x: |
| [gomod](/docs/project-setup/supported-languages/golang/gomodules) | :white_check_mark: | :x: | :warning: | :x: |
| [gopkglock](/docs/project-setup/supported-languages/golang/godep) | :white_check_mark: | :white_check_mark: | :warning: | :x: |
| [gopkgtoml](/docs/project-setup/supported-languages/golang/godep) | :white_check_mark: | :warning: | :warning: | :x: |
| [glide](/docs/project-setup/supported-languages/golang/glide) | :white_check_mark: | :white_check_mark: | :x: | :white_check_mark: |

* :white_check_mark:, Supported
* :warning:, Partially supported (see the linked strategy reference for details)
* :x:, Not supported

## Authenticating to private registries

If you use a private Go module proxy, configure FOSSA so it can access your modules during analysis.

{% steps %}
{% step title="Open Go language settings" %}
Go to **Account Settings → Languages → Go** (`https://app.fossa.com/account/settings/languages/go`).
{% /step %}
{% step title="Add your proxy" %}
Under **Private Proxies**, add the proxy URL and, if required, the username and password FOSSA should use to reach it, then save.
{% /step %}
{% /steps %}

## Package data

FOSSA resolves Go dependencies from the supported manifest and lockfiles. If a Go dependency refers to a Git repository, it may be reported as a Git project, showing the commit hash as the version and the Git repository URL as the package name.

---

Source: https://docs.fossa.com/docs/project-setup/supported-languages/golang/gomodules

# Go Modules

Go 1.11 has first-class support for "modules", which is now the preferred
way to do dependency management.

## Project Discovery

Find all files named `go.mod`

## Analysis

FOSSA CLI attempts to perform the following strategies in order (the results of the first succeeding strategy are selected):

1. go list
2. gomod

## Strategy: golist

Discovery: find go.mod files

FOSSA CLI runs `go list -json -e -deps all` which produces something like:

```json
{
        "Dir": "go/pkg/mod/github.com/cespare/xxhash/v2@v2.1.2",
        "ImportPath": "github.com/cespare/xxhash/v2",
        "Name": "xxhash",
        "Doc": "Package xxhash implements the 64-bit variant of xxHash (XXH64) as described at http://cyan4973.github.io/xxHash/.",
        "Root": "go/pkg/mod/github.com/cespare/xxhash/v2@v2.1.2",
        "Module": {
                "Path": "github.com/cespare/xxhash/v2",
                "Version": "v2.1.2",
                "Time": "2021-08-24T09:58:46Z",
                "Indirect": true,
                "Dir": "go/pkg/mod/github.com/cespare/xxhash/v2@v2.1.2",
                "GoMod": "go/pkg/mod/cache/download/github.com/cespare/xxhash/v2/@v/v2.1.2.mod",
                "GoVersion": "1.11"
        },
...
}
```

FOSSA CLI generates a graph of *packages* and then resolves these back to their parent modules.
Every `Main` module it finds in this graph will have its dependencies promoted to be a direct dependency of the project.

The reason that FOSSA CLI starts with a graph of packages is because Go modules distribute source code for one or more packages.
However, only _packages_, not _modules_, are `import`ed in Go source code.
An implication of this is that the graph of _module_ dependencies does not necessarily correspond to the graph of _package_ dependencies,
which are the real deciding factor in whether a given module is actually used in the end program.
By looking at how packages import one another, FOSSA CLI can get more information about what packages
(and therefore modules) are actually used in a final build product than by looking at modules alone.
This should eliminate some false positives found by tactics in older versions of FOSSA CLI that use `go list -m`.

Currently, this strategy does not yet include path dependencies or their transitive deps from Go `replace` directives.

This strategy was previously available only under the `--experimental-use-v3-go-resolver` flag but is now the default.
For more information about this transition please see this [document](/docs/project-setup/supported-languages/golang/v3-go-resolver-transition-qa).

### Experimental: Path dependencies

`golist` strategy, supports experimental [path dependencies](/docs/cli/references/experimental/path-dependency). It is not, 
enabled by default, and has to be explicitly enabled by using `--experimental-analyze-path-dependencies` flag with `fossa analyze` command.

In your project, you may have path dependencies, which are sourced from file system. For example, 
consider `go.mod` file, which looks something like:

```go
module tester

go 1.14

require github.com/Masterminds/squirrel v1.4.0
replace github.com/Masterminds/squirrel => ../vendor/squirrel
```

With this `go.mod` file and with [experimental path dependencies functionality](/docs/cli/references/experimental/path-dependency) enabled, `fossa-cli` will
correctly, include `../vendor/squirrel` in the dependency findings. It will identify transitive dependencies
originating from package at `../vendor/squirrel`. It will also perform license scan in the directory to identify
any license and copyright obligations. 

Without [experimental path dependencies functionality](/docs/cli/references/experimental/path-dependency) enabled, `fossa-cli` will not include `../vendor/squirrel` 
in the dependency graph. Further, it will not show [path](https://docs.fossa.com/docs/dependencies-browser#transitive-dependencies) in FOSSA UI 
for any of it's transitive dependencies.

To learn more, refer to [path dependency documentation](/docs/cli/references/experimental/path-dependency)

## Strategy: gomod

FOSSA CLI parses the go.mod file, which looks something like:

```
module our/package/path

require (
    github.com/example/one v1.2.3
    github.com/example/two v2.3.4
)

replace github.com/example/two => github.com/example/other v2.0.0
```

where:

- `replace` rewrites `require`s. In this example, our requires resolve to
  `[github.com/example/one v1.2.3, github.com/example/other v2.0.0]`


This strategy will attempt to fill in transitive dependencies by calling out to Go tools.
If it fails or `fossa analyze` is invoked with `--static-analysis-only`, the strategy will report what it found in `go.mod` without any transitive dependencies.

## FAQ

### What happens to the other directives in the `go.mod` file?

The `go.mod` [file has a number of directives](https://go.dev/doc/modules/gomod-ref) other than require and replace which we parse but discard:

- go - The version of GO that the project is built upon. The CLI does not support scanning build tools.
- toolchain - Specifies the toolchain to use during compilation. 
- tool - Developer tools that should be imported with the project. Developer tools are excluded by default.
- godebug - Specifies default GODEBUG settings.

### Why do I see a dependency in `go.mod`, but it is not reflected in FOSSA?

To explain how this can be the case, it's important to note that just because a package is in `go.mod` doesn't mean that it's actually used in the project;
and just because it's in `go.mod` without an `// indirect` comment doesn't mean it's actually direct.
Instead, [the Go language defines direct dependencies as](https://go.dev/ref/mod#glos-direct-dependency):

> A package whose path appears in an `import` declaration in a `.go` source file for a package or test in the main module, 
> or the module containing such a package.

This disconnect, where the `go.mod` file is not representative of the actual project,
occurs because Go considers packages in the `go.mod` advisory
(as in, it is not a build error to build a project that does not use a referenced package).
It also considers the `// indirect` comment to be "cosmetic", which means that the only way
this comment gets added or removed is via `go mod tidy` (or manually, by editing the `go.mod` directly).

To illustrate this, we have created a very simple reproduction case and copied the results below.
Note that at the end, despite the `go.mod` file being outdated (the dependency is neither used, nor marked `// indirect`),
Go did not complain at all when the project was built. 

Shell commands are prefixed by `;`, and comments about those commands are prefixed by `#`:
```
; fossa -V
fossa-cli version 3.8.6 (revision b2657cb78351 compiled with ghc-9.0)

# Created the initial repro case project.
; cat go.mod
module github.com/jssblck/gomodtest

go 1.20

require github.com/cenkalti/backoff/v4 v4.2.1

# Used the `backoff` package in the actual code.
; cat main.go
package main

import (
	"fmt"

	"github.com/cenkalti/backoff/v4"
)

func main() {
	fmt.Printf("default initial backoff interval: %v\n", backoff.DefaultInitialInterval)
}

# FOSSA reports `backoff` as a dependency.
; fossa analyze -o 2> /dev/null | jq '.sourceUnits'
[
  {
    "AdditionalDependencyData": null,
    "Build": {
      "Artifact": "default",
      "Dependencies": [
        {
          "imports": [],
          "locator": "go+github.com/cenkalti/backoff/v4$v4.2.1"
        }
      ],
      "Imports": [
        "go+github.com/cenkalti/backoff/v4$v4.2.1"
      ],
      "Succeeded": true
    },
    "Data": null,
    "Files": null,
    "GraphBreadth": "complete",
    "Info": null,
    "Manifest": "/Users/jessica/projects/scratch/gomodtest/",
    "Name": "/Users/jessica/projects/scratch/gomodtest/",
    "OriginPaths": [
      "go.mod"
    ],
    "Type": "gomod"
  }
]

# Edited to remove references to the `backoff` package.
; cat main.go
package main

import (
	"fmt"
)

func main() {
	fmt.Println("not using backoff!")
}

# Left `go.mod` unchanged.
; cat go.mod
module github.com/jssblck/gomodtest

go 1.20

require github.com/cenkalti/backoff/v4 v4.2.1

# FOSSA no longer reports `backoff` as a dependency.
; fossa analyze -o 2> /dev/null | jq '.sourceUnits'
[
  {
    "AdditionalDependencyData": null,
    "Build": {
      "Artifact": "default",
      "Dependencies": [],
      "Imports": [],
      "Succeeded": true
    },
    "Data": null,
    "Files": null,
    "GraphBreadth": "complete",
    "Info": null,
    "Manifest": "/Users/jessica/projects/scratch/gomodtest/",
    "Name": "/Users/jessica/projects/scratch/gomodtest/",
    "OriginPaths": [
      "go.mod"
    ],
    "Type": "gomod"
  }
]

# Even though `go.mod` is outdated, it can still build with no warnings or errors.
; go build
; ./gomodtest
not using backoff!
```

As a concrete step towards resolving this sort of discrepancy, we recommend running `go mod tidy` on projects regularly;
this command should synchronize the `go.mod` file with the actual state of the project.

#### Test Dependencies

Sometimes the above procedure may uncover a dependency that is not reported by FOSSA but that is also not removed by `go mod tidy`.
The other reason that a dependency may appear in `go.mod` but not in FOSSA is that it is a test dependency.
`go.mod` itself does not label dependencies as being used only in tests, but FOSSA's Go module strategy identifies and excludes test-only dependencies.
To verify that a direct dependency is not a test-only dependency, we recommend searching the project source code for where a package from the module is imported.
Generally, for a declaration in `go.mod` like:

```
	github.com/prometheus/client_golang v1.12.2
```

You can search for its imports using a command like:

```sh
$ find <project_directory> -name \*.go -not -path '*vendor*' -exec grep -Hn "github.com/prometheus/client_golang" {} \;
```
If `find`/`grep` are not available on your system, you can install a tool like [ripgrep](https://github.com/BurntSushi/ripgrep?tab=readme-ov-file#ripgrep-rg) to perform the same operation:
```sh
rg 'github.com/prometheus/client_golang' --glob=\!\*vendor\* -F -l
```

If the import only appears in source files that end in `_test.go`, it is a test-only dependency.
You can read more about how tests are defined in Go [here](https://go.dev/doc/tutorial/add-a-test).

The above process will make vendored test-only dependencies seem like regular dependencies.
Doing the above search should be considered a heuristic, not definitive proof that a package is test-only or not.

---

Source: https://docs.fossa.com/docs/project-setup/supported-languages/golang/godep

# Dep

Dep is an alternative toolchain for golang dependency management. Though go
modules are the blessed form of dependency management, dep is exploring
alternatives in the dependency management space, and hasn't been deprecated.

## Project Discovery

`gopkglock`: Find all files named `Gopkg.lock`

`gopkgtoml`: Find all files named `Gopkg.toml`

## Analysis: gopkglock

We parse [projects][depprojects] from Gopkg.lock. This is more comprehensive
than GopkgToml, as it contains pinned versions of all of our direct _and_
transitive dependencies. We also pick up on `source` locations from GopkgLock

[depprojects]: https://golang.github.io/dep/docs/Gopkg.toml.html#dependency-rules-constraint-and-override

## Analysis: gopkgtoml

We parse [dependency rules][deprules] from Gopkg.toml. `override`s are similar
to [gomod replaces](/docs/project-setup/supported-languages/golang/gomodules).

[deprules]: https://golang.github.io/dep/docs/Gopkg.toml.html#dependency-rules-constraint-and-override

---

Source: https://docs.fossa.com/docs/project-setup/supported-languages/golang/glide

# Glide

Glide is very commonly encountered as a buildtool for older Go projects.
Though deprecated, it's prevalent enough among existing projects that it
warrants support in fossa-cli.

## Project Discovery

Find all files named `glide.lock`

## Analysis

`glide.lock` is a yaml-formatted file containing pinned package versions:

```yaml
hash: 12345
updated: 2018-10-12T14:37:49.968644-07:00
imports:
- name: github.com/pkg/one
  version: 100
  subpackages:
  - compute
- name: github.com/pkg/three/v3
  version: 300
  repo: fossas/privatefork
```

---

Source: https://docs.fossa.com/docs/project-setup/supported-languages/golang/gomodules-qr

# Quick reference: gomodules

## Requirements

**Ideal**

- `go` buildtool installed
- `go.mod` file present in your project

**Minimum**

- `go.mod` file present in your project

## Project discovery

Directories containing `go.mod` files are considered gomodules projects.

---

Source: https://docs.fossa.com/docs/project-setup/supported-languages/golang/godep-qr

# Quick reference: godep

## Requirements

**Ideal**

- `Gopkg.lock` file present in your project

**Minimum**

- `Gopkg.toml` file present in your project

## Project discovery

Directories containing one (or both) of `Gopkg.toml` and `Gopkg.lock` are considered godep projects.

---

Source: https://docs.fossa.com/docs/project-setup/supported-languages/golang/glide-qr

# Quick reference: glide

## Requirements

**Ideal/Minimum**

- `glide.lock` file present in your project

## Project discovery

Directories containing `glide.lock` files are considered glide projects.

---

Source: https://docs.fossa.com/docs/project-setup/supported-languages/golang/v3-go-resolver-transition-qa

# What is the new package-based Go modules analysis strategy?

The V3 Go resolver is a new dynamic strategy to find dependences in go modules projects.
It was first released in v3.8.5 on 2023-06-10.

# What is the new package-based Go modules analysis strategy?

In the past, we asked the Go tools for a list of the modules used in an analyzed dependency. 
In Go though, having a module as a dependency doesn’t actually mean that any of its code will be included in the final build product. 
Instead modules are composed of packages which are imported, packages determine what code is actually included in a final build product, and modules are the downloaded unit which provide groups of packages. 
The new strategy first constructs a list of packages used by the final build product and then resolves those packages to their parent module.

For more information on how modules and packages work in Go, please see "How could a module be referenced by a Go project and not be a dependency?" below.

# Why is this change necessary?
Several of our users noticed with the old strategy that they were getting dependencies, sometimes many dependencies, that weren’t actually being used in their projects. 
This was increasing the burden on their compliance and engineering teams by requiring them to fix policy or vulnerability issues reported by FOSSA for packages that weren’t actually being used by the built software. 

# What differences can I expect to see in my results from the new package-based Go module analysis?
The main difference you can expect to see is a reduced number of dependencies and their associated issues.
However the strategy is overall more accurate so it is possible, just less common, to see an increased number of dependencies as well.

Results may also be different if scans of a project were previously falling back to a less preferred analysis strategy;
the new strategy is more resilient to errors in the project so should be forced to fall back less often.
In such cases, it's common to see an increased number of dependencies due to more accurate analysis, but they could be reduced as well.

For more information about different strategies used to analyze Go modules projects,
see the [Go modules strategy documentation](/docs/project-setup/supported-languages/golang/gomodules).

## Direct dependencies
It is possible to see a different (usually reduced) set of direct dependencies.

We expect a reduced set of dependencies to occur especially in situations where
a dependency is implied by `go.mod` to be a direct dependency, but is not actually used.

For more information see the [Go strategy FAQ](/docs/project-setup/supported-languages/golang/gomodules#why-do-i-see-a-dependency-in-gomod-but-it-is-not-reflected-in-fossa).

## Transitive dependencies
It is possible to see a different (usually reduced) set of transitive dependencies.

We expect a reduced set of dependencies to occur especially in situations where
a transitive dependency is implied by the module imports, but the package(s) the transitive dependency provides
are not actually used in the final build product of the project.

For more information see ["how could a module be referenced by a Go project and not be a dependency?"](#how-could-a-module-be-referenced-by-a-go-project-and-not-be-a-dependency).

## Test dependencies
Test dependencies should not be reported with this strategy at all.

We expect a reduced set of dependencies to occur in some cases where the previous analyzer had issues
determining whether a given module was only used for tests.

If test dependencies are reported, it is likely a bug. Please file a report at https://support.fossa.com.

# How do I use the new package-based Go modules analysis?
This new form of dynamic analysis should be available if you use a version of fossa-cli >= v3.8.5.
Additionally, the system which performs the analysis using fossa-cli should have a Go tool-chain installed. 
Basically, analyzing a project on a system which can successfully build the project should make use of the new strategy. 

# How can I verify that the new package-based Go modules analysis ran for my project?
You can verify that the strategy is running by using the `--debug` flag and looking for a message in the output that says “analysis using go list (V3 Resolver)”.

# What is the relationship between the package-based Go modules analysis and the experimental v3 flag?
They are the same.
In order to get some initial feedback from users on how this new strategy works we initially released it under the --experimental-use-v3-go-resolver flag.
The package-based Go module analysis is the same as the functionality under this flag except it is now the default. 
When using a version of the CLI >= v3.8.5 where it is now the default you can expect to see a warning if you use this flag. 
Eventually, this flag will be fully removed so we recommend removing it from any scripts where you currently have it active.

# Does the package-based Go modules strategy handle local path replacements?
The main limitation of the current strategy is that while we respect Go replace directives, we currently are only able to report on them and their dependencies if they reference a Go module and not a directory. For example, the following replace directive in a go.mod is OK:
```
replace (
    github.com/json-iterator/go v1.1.12 => github.com/json-iterator/go v1.1.11
)
```

While this one is not:
```
replace (
    github.com/json-iterator/go v1.1.12 => ./local_pkgs/go
)
```

The current Go modules strategy also does not handle this case, so this should not result in breakage for users of our current Go strategy. 

A way to handle this case in the meantime is to use vendored dependencies in fossa-deps.yml. 
The lack of automatic support for these dependencies is a known shortcoming of the strategy and something we plan to work on in the future. 

# How could a module be referenced by a Go project and not be a dependency?
In Go, code is distributed in modules which are referenced in go.mod. Modules in this case are containers for packages, which are imported in a Go source file. 
Packages are the main units of code that actually get compiled into the build-product. A Go module can be composed of multiple packages and each package can in turn depend on packages from other modules. 
Many other languages do not have an equivalent concept to modules as a container for code units. 
In those languages including a dependency in a package manager and importing any of its code causes the dependency to be included in the project in its entirety. 
In this case, a dependency is an artifact for both code distribution and code use. 
Because Go modules have both of those concepts separately, we can end up with a situation like the following dependency diagram:

```mermaid
---
config:
  themeVariables:
    fontSize: 14px
  flowchart:
    nodeSpacing: 20
    rankSpacing: 40
    padding: 6
    diagramPadding: 8
---
graph LR
    subgraph main["Main Module"]
        P1["Pkg 1"]
    end
    subgraph modA["Module A"]
        P2["Pkg 2"]
        P3["Pkg 3"]
    end
    subgraph modB["Module B"]
        P4["Pkg 4"]
    end
    main --> modA
    modA --> modB
    P1 --> P2
    P3 --> P4
    style main fill:#edf7f2,stroke:#289E6D,stroke-width:2px
    style modA fill:#edf7f2,stroke:#289E6D,stroke-width:2px
    style modB fill:#edf7f2,stroke:#289E6D,stroke-width:2px
    classDef service fill:#edf7f2,stroke:#1d7a54,color:#171717,stroke-width:2px
    class P1,P2,P3,P4 service
```

Rectangles are modules; rounded package nodes show import relationships inside and across modules. 
At the module level it’s pretty clear what is happening. The Main Module depends on Module A which depends on Module B. 
When looking only at the graph of module dependencies it’s clear that the project depends on both Module A and Module B. 
Considering the packages in a module yields a different set of dependencies than looking at modules alone. 
The Main Module in the diagram contains Package 1 which references Package 2 of Module A. 
Module A also contains Package 3, which references Package 4 in Module B. 
Notice that even though Packages 2 and 3 are part of Module A they don’t depend on each other. 
Further, Package 2 has no dependency on any packages in Module B at all. 
This means that the project containing the Main Module, which only references Package 2 of Module A, wouldn’t actually contain any code at all from Module B.

---

Source: https://docs.fossa.com/docs/project-setup/supported-languages/maven

# Maven

FOSSA supports Maven projects through `pom.xml`. You can analyze a project two ways: **Quick Import** in the web app, which incrementally runs your build, or the **FOSSA CLI** for complex builds in CI/CD.

## Tool support

| Tool | Quick Import (app.fossa.com) | CLI (fossa-cli) |
| :-- | :-- | :-- |
| Maven | `pom.xml` | `pom.xml` |

## How Quick Import works

After importing Maven code, FOSSA gets results out of the box by incrementally running your build and statically resolving the dependency signatures it produces. This method supports a wide variety of build states, but more complicated builds often require configuration or inlined settings.

To provide the best out-of-the-box experience, FOSSA elects sane defaults and configuration magic. These include choosing only `compile` and `runtime` scopes, setting default build profiles, intelligently handling optional dependencies, and more. You can customize this behavior under each project's settings at **Project Settings → Builds & Languages → Java**.

{% img src="/images/project-setup/c9e72ca-project-settings-language-settings-java.png" alt="Java build and language settings under Project Settings" /%}

If you'd like to provide `environment variables` during Quick Import, add them under **Project Settings → Builds & Languages → General**.

{% callout type="info" %}
Java builds are generally complicated, so it is both impossible to generically build codebases and impossible to get accurate results from pure static analysis of `pom.xml` files. For larger builds that require significant configuration, we recommend using the **FOSSA CLI** for fast and accurate results.
{% /callout %}

## Analyzing with the CLI

For complex builds, you can use the FOSSA CLI, our [open-source](https://github.com/fossas/fossa-cli) dependency analysis client, to upload results from an existing Maven build in CI or on your local development machine.

Install the latest release of `fossa-cli`:

```shell
curl -H 'Cache-Control: no-cache' https://raw.githubusercontent.com/fossas/fossa-cli/master/install-latest.sh | bash
```

Then run `fossa analyze` from your repository's root directory. For Maven, FOSSA offers a more-accurate strategy (mavenplugin) and a strategy with zero requirements (pomxml).

### Analysis strategies

Maven analysis attempts these strategies in order:

1. Run the Maven plugin command version 4.0.1.
2. Run the Maven tree command.
3. Run the Maven plugin command version 3.3.0.
4. Scan `pom.xml` files located in the file tree.

| Strategy | Direct Deps | Transitive Deps | Edges | Container Scanning |
| --- | --- | --- | --- | --- |
| [mavenplugin](/docs/project-setup/supported-languages/maven/mavenplugin) | :white_check_mark: | :white_check_mark: | :white_check_mark: | :x: |
| [treecmd](/docs/project-setup/supported-languages/maven/treecmd) | :white_check_mark: | :white_check_mark: | :white_check_mark: | :x: |
| [pomxml](/docs/project-setup/supported-languages/maven/pomxml) | :white_check_mark: | :x: | :x: | :white_check_mark: |

For a condensed requirements summary, see the [Maven quick reference](/docs/project-setup/supported-languages/maven/maven-qr).

### Strategy command selection

FOSSA CLI uses [strategy command selection](/docs/cli/features/strategy-command-selection) for Maven commands. The Maven _candidate commands_ are:

- If present, the command specified by the `FOSSA_MAVEN_CMD` environment variable.
- If present, the `mvnw` or `mvnw.bat` script in the project directory or any ancestor directory.
- Finally, the `mvn` command, which is searched for in `$PATH`.

To choose a command from the candidates, FOSSA CLI runs each candidate with `-v` and selects the first one that succeeds.

### Filtering by Maven dependency scope

You can use a [configuration file](/docs/cli/references/files/fossa-yml) to provide Maven dependency scopes you would like to filter. You can filter by either inclusion or exclusion. When both `scope-only` and `scope-exclude` are provided, `scope-only` takes precedence and is used for filtering.

```yaml
version: 3

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

### Filtering by submodules

If you have a Maven project with one or more subprojects, in some cases you may only want to analyze a specific set of subprojects. In `fossa-cli`, this is achieved with [exclusion filtering](/docs/cli/references/files/fossa-yml).

{% steps %}
{% step title="Identify your subproject targets" %}
Run `fossa list-targets` to identify the project directory and identifier of each subproject:

```bash
[ INFO] Found project: maven@./
[ INFO] Found target: maven@./:com.fossa:app
[ INFO] Found target: maven@./:com.fossa:list
[ INFO] Found target: maven@./:com.fossa:utilities
```

Targets are denoted in the format `type@path:target`. Maven submodule targets are composed of `<groupId>:<artifactId>`, so the `utilities` submodule above is referenced by `com.fossa:utilities`:

```
maven   @           ./      :      com.fossa:utilities
------ ---          ---    ---        -----------
Type   Path         Path   Target      Target
       separator           separator
```
{% /step %}
{% step title="Restrict analysis with a .fossa.yml file" %}
To analyze only `utilities`, add a `.fossa.yml` file in the project root:

```yaml
# filename: .fossa.yml
#
# analyze only maven@./:com.fossa:utilities
version: 3
targets:
  only:
    - type: maven
      path: ./
      target: 'com.fossa:utilities'
```

To instead exclude a specific set of subprojects:

```yaml
# filename: .fossa.yml
#
# do not analyze maven@./:com.fossa:app, and maven@./:com.fossa:utilities
version: 3
targets:
  only:
    - type: maven
  exclude:
    - type: maven
      path: ./
      target: 'com.fossa:app'
    - type: gradle
      path: ./
      target: 'com.fossa:utilities'
```
{% /step %}
{% /steps %}

### FAQ

**One of my transitive dependencies does not have path information.**

The mavenplugin and treecmd tactics can result in transitive dependencies that do not display paths to parents. For example:

```
+- com.amazonaws:aws-java-sdk-kms:1.11.415:compile
|  +- com.amazonaws:aws-java-sdk-core:1.11.415:compile
\- com.jayway.restassured:rest-assured:2.9.0:test
   +- org.apache.httpcomponents:httpclient:4.5.1:compile   👈
```

`httpclient` appears as a transitive dependency in the FOSSA UI but has no paths. Its only listed parent is `rest-assured`, which is a `test` dependency, yet `httpclient` is a `compile` dependency. This tells us `httpclient` has another parent in the graph, but we are unable to determine where.

**I need to set custom command-line arguments for Maven. Does FOSSA support that?**

Not directly, but `mvn` itself has an [environment variable](https://maven.apache.org/configure.html) you can use. For example, to set a custom `settings.xml` file:

```sh
MAVEN_ARGS="--settings /foo/bar/settings.xml" fossa analyze
```

## Authenticating to private registries

FOSSA can fetch and resolve dependencies from private registries like Artifactory, Nexus, or any custom public Maven registry. To customize how FOSSA handles Java dependencies, go to **Account Settings → Languages → Java** (`https://app.fossa.com/account/settings/languages/java`).

By default, when FOSSA encounters a package in the Java ecosystem, it tries to resolve it from the following public registries, in order:

| id | url |
| :-- | :-- |
| central | https://repo1.maven.org/maven2 |
| cloudera | https://repository.cloudera.com/artifactory/cloudera-repos |
| conjars | http://conjars.org/repo |
| cloudera-old | https://repository.cloudera.com/artifactory/repos |
| hortonworks-releases | http://repo.hortonworks.com/content/repositories/releases/ |
| mapr-releases | http://repository.mapr.com/maven/ |
| jahia | http://maven.jahia.org/maven2/ |
| atlassian-3rdparty | https://maven.atlassian.com/3rdparty/ |
| pentaho | http://repository.pentaho.org/artifactory/repo/ |
| twitter | http://maven.twttr.com/ |
| redhat-ga | https://maven.repository.redhat.com/ga/ |
| datanucleus | http://www.datanucleus.org/downloads/maven2/ |
| confluent | http://packages.confluent.io/maven/ |
| sonatype-releases | https://oss.sonatype.org/content/repositories/releases/ |

### Adding a public registry

To add a new public registry, add a new entry under **Repositories**. FOSSA begins checking that registry (in order) for packages your projects bring in.

### Adding a private registry

To add an authenticated registry, add two entries (one under **Repositories** and one under **Servers**) with a corresponding `Id`, and include your credentials under the **Servers** entry.

{% img src="/images/project-setup/2bfa12f-Screen_Shot_2018-03-25_at_2.16.25_PM.png" alt="Adding a private Maven registry under Java Language Settings" /%}

### Improving resolution performance

If you know which registries you'd like FOSSA to prefer, you can re-order them in the Java Language Settings. If you have a set of registries that you know will succeed, FOSSA checks those first and resolves dependencies without cycling through subsequent registries.

## Package data

FOSSA parses data from all package metadata and scans all code provided in an artifact or associated code archives. If references to license webpages are found, FOSSA crawls the web to seek licensing information. Where no source code is included in an artifact, FOSSA attempts to resolve it to a known codebase that the artifact was built from and performs a full code audit.

In the Java ecosystem, it is common for license data to be stripped when artifacts are published. In these cases, license data can be regenerated from the FOSSA registry by enriching build artifacts with data from associated VCSs, parent artifacts, and more. If FOSSA encounters a `META-INF` folder in a Maven archive, it treats it as data from deeper dependencies.

### Maven dependencies

The [Maven build system](http://maven.apache.org/) pulls in dependencies based on Group ID, Artifact ID, and Version. FOSSA derives dependencies by building your project and seeing which dependencies are brought in; other metadata is fetched directly from repositories. The metadata pulled in includes the home page URL and, per dependency, the Group ID, Artifact ID, resolved version, transitive excludes, optional flag, and scopes.

- **Optional**: Optional dependencies are included in analysis and tagged as `Optional` by FOSSA. They are not included beyond depth 1.
- **Scope**: Dependency scope is included in analysis and is selectable in FOSSA. Choosing different project scopes lets you control which dependencies are included in issue scans and in the UI.
- **Transitive excludes**: Dependencies excluded transitively are also handled by FOSSA. If a transitive dependency is explicitly excluded, FOSSA excludes it from issue scans and the UI. If another dependency brings in the excluded transitive dependency, it will be included. These excludes are scoped to dependencies, not projects.

---

Source: https://docs.fossa.com/docs/project-setup/supported-languages/maven/mavenplugin

# Maven plugin

| Strategy           | Direct Deps | Transitive Deps | Edges | Tags       |
| ---                | ---         | ---       | ---   | ---        |
| depgraph plugin    | ✅          | ✅        | ✅   | Optional   |

Maven projects are notoriously difficult to resolve into final dependency
graphs. While many dependencies are declared as XML, these dependency
declarations can span many buildscripts and user settings files. What's worse:
maven plugins are often used to apply dependencies to the project, and some
maven plugins allow arbitrary executable code -- similar to gradle.

To work around this, we're using the maven cli in conjunction with the [depgraph
maven plugin](https://github.com/ferstl/depgraph-maven-plugin), version 4.0.1.
This plugin is used by some Jenkins and Apache open source projects. We also maintain support for version 3.3.0 which support JDK 7.

## Project Discovery

Find `pom.xml` files, and treat those as maven projects. Skip all subdirectories.

## Analysis

1. unpack the embedded plugin to a temporary directory
2. install it to the local maven repository `mvn org.apache.maven.plugins:maven-install-plugin:3.0.0-M1:install-file -DgroupId=com.github.ferstl -DartifactId=depgraph-maven-plugin -Dversion=4.0.1 -Dpackaging=jar -Dfile=<location>/depgraph-maven-plugin-4.0.1.jar` (uses a specific version of [Maven Install Plugin](https://maven.apache.org/plugins/maven-install-plugin/) to avoid a [bug in earlier versions](https://issues.apache.org/jira/browse/MINSTALL-110))
3. invoke the plugin in the top-level project with the command `mvn com.github.ferstl:depgraph-maven-plugin:4.0.1:aggregate -DgraphFormat=text -DmergeScopes -DreduceEdges=false -DshowVersions=true -DshowGroupIds=true -DshowOptional=true -DrepeatTransitiveDependenciesInTextGraph=true`

For `graphFormat`s other than `text` the data will be output to
`target/dependency-graph.<format>`. For `text`, it will additionally be output
to stdout.

During this analysis we will attempt to determine what submodules are part of the
this project using the command `mvn com.github.ferstl:depgraph-maven-plugin:4.0.1:reactor -Dgraphformat=json -DoutputFilename=fossa-reactor-graph.json`. We then generate a graph that excludes all of those submodules, but with
their imediate deps marked as direct. This is because we don't want to include the users' projects in graphs, but
do want to be able to analyze the things that they depend on.

For example:

```
org:submodule1:1.0.0:compile
\- org2:pkg1:1.0.0:compile
   +- org2:pkg2:1.0.0:compile
   \- org:submodule2:1.0.0:compile
      \- org3:pkg3:1.0.0:compile
```

If `submodule1` and `submodule2` are both submodules of the project we would
report `pkg3` and `pkg1` as direct dependencies. `pkg2` is reported as a transitive
dependency. `submodule1` and `submodule2` won't be included at all. `fossa-cli`'s
graph would look like this:

```
org2:pkg1:1.0.0:compile
\- org2:pkg2:1.0.0:compile

org3:pkg3:1.0.0:compile
```

---

Source: https://docs.fossa.com/docs/project-setup/supported-languages/maven/treecmd

# Maven - Tree Command

This maven tactic uses native, `mvn dependency:tree` command to retrieve
dependency information. 

## Project Discovery

Find `pom.xml` files, and treat those as maven projects. Skip all subdirectories.

## Analysis

1. Executes `mvn dependency:tree -DoutputType=dot -DoutputFile=... --fail-at-end`
2. Parse and analyze generated dot file for dependency analysis

## References

- [Maven dependency:tree](https://maven.apache.org/plugins/maven-dependency-plugin/usage.html#dependency:tree)

---

Source: https://docs.fossa.com/docs/project-setup/supported-languages/maven/pomxml

# Maven pom.xml

Maven projects use `pom.xml` files to declare dependencies and multi-project relationships.

In a multi-project maven structure, sub-projects usually inherit dependencies, or can reference other sub-projects as dependencies.

## Project discovery

Do a complete directory traversal looking for files named `pom.xml`.

There's no guarantee that a maven pom will be called `pom.xml`. To accomodate for this, we use `<relativePath>` directives in `<parent>` declarations to include additional poms.

poms are linked together by their `<parent>` references into multi-project projects.

## Analysis

Each project in the single- or multi-project structure has its pom information overlayed on top of parent poms, and a dependency graph is gathered from each project.

We have limited support for naive `${property}` interpolation.

---

Source: https://docs.fossa.com/docs/project-setup/supported-languages/maven/maven-qr

# Quick reference: maven

## Requirements

**Ideal**

- `maven` buildtool installed
- `pom.xml` files present in your project

**Minimum**

- `pom.xml` files present in your project

## Project discovery

We do a complete directory traversal looking for files named `pom.xml`, and link related poms together into projects.

---

Source: https://docs.fossa.com/docs/project-setup/supported-languages/gradle

# Gradle

FOSSA supports Gradle projects, which are most often JVM-based (Java, Kotlin, Android, Scala). You can analyze a project two ways: **Quick Import** in the web app, or the **FOSSA CLI** for complex builds. Because Gradle resolves dependencies from Maven repositories, FOSSA treats Gradle as part of the Java ecosystem.

## Tool support

| Tool | Quick Import (app.fossa.com) | CLI (fossa-cli) |
| :-- | :-- | :-- |
| Gradle | `build.gradle` or custom `*.gradle` | `build.gradle`, `build.gradle.kts`, `settings.gradle`, `settings.gradle.kts` |

## How Quick Import works

When Gradle code is imported through the web app, FOSSA attempts to get results out of the box by incrementally running your build and statically resolving the dependency signatures it produces. This supports a wide variety of build states, but more complicated builds often require configuration or inlined settings.

You can configure how FOSSA scans Gradle (and the rest of the Java ecosystem) under each project's settings, in **Project Settings → Builds & Languages → Java**. FOSSA elects sane defaults, choosing only `compile` and `runtime` scopes, setting default build profiles, intelligently handling optional dependencies, and more. To pass environment variables (such as `GRADLE_OPTS`) during repository scanning, add them under **Project Settings → Builds & Languages → General**.

{% img src="/images/project-setup/c9e72ca-project-settings-language-settings-java.png" alt="Java ecosystem settings under Project Settings, Builds & Languages, Java" /%}

{% callout type="info" %}
Java builds are generally complicated, so it is both impossible to generically build every codebase and impossible to get accurate results from pure static analysis of `build.gradle` files. For larger builds that require significant configuration, use **CLI analysis** below for fast and accurate results.
{% /callout %}

## Analyzing with the CLI

For complex Gradle builds, run the FOSSA CLI in CI or on your local machine to upload results from an existing build. The CLI runs inside your build environment, so it can resolve dependencies that Quick Import cannot.

{% callout type="warning" %}
Gradle analysis requires dynamic analysis. FOSSA must execute Gradle to enumerate subprojects and evaluate build scripts. This means the CLI must run in an environment where your Gradle build succeeds.
{% /callout %}

Install the latest release of `fossa-cli`:

```shell
curl -H 'Cache-Control: no-cache' https://raw.githubusercontent.com/fossas/fossa-cli/master/install-latest.sh | bash
```

Then run `fossa analyze` from your repository's root directory.

[Gradle](https://gradle.org/) is a polyglot build tool, popular with Java and Android projects. Builds are specified in a `build.gradle`/`settings.gradle` file (Groovy) or a `build.gradle.kts`/`settings.gradle.kts` file (Kotlin), and are evaluated as programs that must be dynamically executed.

### Analysis strategies

The CLI selects tactics by trying them in preference order and uses the results of the first tactic to succeed.

| Tactic | Direct Deps | Transitive Deps | Edges | Container Scanning |
| --- | --- | --- | --- | --- |
| [Plugin](/docs/project-setup/supported-languages/gradle/plugin) | :white_check_mark: | :white_check_mark: | :white_check_mark: | :x: |

### Concepts

#### Subprojects and configurations

Most sizable Gradle builds organize their dependencies with two concepts: subprojects and configurations.

_Subprojects_ are used when you have multiple "projects" in a single Gradle build (managed with a single `settings.gradle` and zero or more `build.gradle` files). Gradle calls these "multi-projects": one root project, and one or more subprojects. A single subproject roughly corresponds to a single set of outputs, so FOSSA treats subprojects as separate analysis targets. For details, see [Creating a multi-project build](https://docs.gradle.org/current/userguide/multi_project_builds.html#authoring-multi-project-builds).

Within a single subproject, Gradle declares dependencies for different "scopes" (contexts such as compilation, test execution, or runtime execution). Gradle calls these scopes _configurations_, for example `implementation`, `testRuntime`, or `compileClasspath`. Different subprojects can have different configurations, although many common configurations (such as `compileClasspath`) appear in most subprojects. For more details, see [What are dependency configurations](https://docs.gradle.org/current/userguide/declaring_dependencies.html#sec:what-are-dependency-configurations).

Each pair of `(subproject, configuration)` corresponds to one dependency graph. Ideally each pair would be a separate analysis target; for technical reasons the current implementation treats separate subprojects as analysis targets, and treats each subproject as the union of all of its configurations. In practice this should not affect returned dependency results.

#### Gradle wrappers

Instead of invoking `gradle` directly, most Gradle projects use a "Gradle wrapper", a shell script vendored in the project that selects and downloads the correct version of Gradle. See [The Gradle Wrapper](https://docs.gradle.org/current/userguide/gradle_wrapper.html) for details. Because of this, the analyzer has logic for selecting which `gradle` executable to use.

When executing Gradle for an analysis target at `ANALYSIS_TARGET_DIR`, the CLI prefers (in order):

1. `gradlew`: first in `ANALYSIS_TARGET_DIR`, then recursively searching parent directories.
2. `gradlew.bat`: first in `ANALYSIS_TARGET_DIR`, then recursively searching parent directories.
3. `gradle` (from `$PATH`).

In the documentation below, for brevity, the selected tool is always referred to as `gradle`.

### Discovery

This strategy discovers analysis targets by looking for files whose names start with `build.gradle` or `settings.gradle`. This matches `build.gradle` and `settings.gradle` as well as Gradle build scripts in other supported languages (`build.gradle.*`, `settings.gradle.*`).

It then executes `gradle projects` in the directory where the build file is found to get the list of subprojects, which are used to create the analysis targets. If there are no subprojects, an analysis target is created for the root project. Otherwise, one analysis target is created per subproject.

### Debugging

{% callout type="tip" %}
These steps apply to Gradle generally, independent of tactic. Also check the [Plugin tactic documentation](/docs/project-setup/supported-languages/gradle/plugin) for the specific tactic your project uses.
{% /callout %}

#### Determine whether Gradle targets are detected

To confirm the CLI is detecting your Gradle project, run `fossa list-targets`. The output lists analysis targets in the format `type@path`.

{% callout type="info" %}
For more information on `fossa list-targets`, see [the reference guide](/docs/cli/references/subcommands/list-targets).
{% /callout %}

For each Gradle subproject, you should see a `gradle@PATH_TO_ROOT_PROJECT:SUBPROJECT` target. If you don't, one of two things is likely happening:

1. Your Gradle project does not have a `build.gradle` file. This is an unsupported configuration.
2. `gradle projects` is failing to execute. Make sure a Gradle wrapper is accessible and that `gradle projects` runs successfully.

#### Manually checking Gradle dependency results

To verify the CLI's results, run `gradle :dependencies` in your root project and `gradle $SUBPROJECT:dependencies` for each subproject. The CLI should produce a graph that is the union of each subproject's dependencies.

If the CLI uploads versions that differ from `gradle $SUBPROJECT:dependencies`, check whether the subproject dependency's version is the actual version resolved across the entire Gradle build. Different subprojects may select different versions when resolved independently, but a single resolved version is selected when the build is resolved as a whole.

If you'd like to file a bug report about incorrect dependencies, include the list of incorrect dependencies and the commands you ran to obtain that list.

### Walkthroughs

#### Analyzing only specific subprojects

If your Gradle project has multiple subprojects, you may want to analyze only a specific set. In `fossa-cli`, this is achieved with [exclusion filtering](/docs/cli/references/files/fossa-yml).

First, run `fossa list-targets` to identify the project directory and subproject identifiers:

```bash
[ INFO] Found project: gradle@./             # <- The root project. './' means "the project is at the root of the analysis directory".
[ INFO] Found target: gradle@./::app         # <- Submodule of the root project.
[ INFO] Found target: gradle@./::list
[ INFO] Found target: gradle@./::utilities
```

{% callout type="info" %}
Targets are denoted as `type@path:target`. For example, `gradle@./::utilities` means "a Gradle project at the scan root, with the target `:utilities`", while `gradle@./subdir/` means "a Gradle project inside `subdir`, without a target (a root project)". For more information, see [the `list-targets` reference](/docs/cli/references/subcommands/list-targets).
{% /callout %}

{% callout type="warning" %}
Gradle attaches a leading colon to submodules, and FOSSA also uses a colon to separate "path" and "target". So `gradle@./::utilities` breaks down as:

```
gradle  @           ./      :         :utilities
------ ---          ---    ---        -----------
Type   Path         Path   Target      Target
       separator           separator
```

Because Gradle prepends a colon, the `:utilities` target corresponds to the "utilities" submodule of the main project.
{% /callout %}

To analyze only `utilities`, add a `.fossa.yml` file in the project root:

```yaml
# filename: .fossa.yml
#
# analyze only gradle@./::utilities
version: 3
targets:
  only:
    - type: gradle
      path: ./
      target: ':utilities'
```

Likewise, to exclude a specific set of subprojects:

```yaml
# filename: .fossa.yml
#
# do not analyze gradle@./::app, and gradle@./::utilities
version: 3
targets:
  only:
    - type: gradle
  exclude:
    - type: gradle
      path: ./
      target: ':app'
    - type: gradle
      path: ./
      target: ':utilities'
```

#### Manually specifying Gradle dependencies

{% callout type="info" %}
The FOSSA Gradle integration internally refers to Gradle dependencies as _Maven_ dependencies, because Gradle is used to integrate dependencies from Maven code hosts (such as Maven Central). This usually isn't relevant to end users, but it is relevant when manually specifying dependencies.
{% /callout %}

If the CLI doesn't natively integrate with your build tool but your build tool uses Gradle dependencies, you can still add them to an uploaded build via [manual dependencies](/docs/cli/features/manual-dependencies):

```yaml
# fossa-deps.yml
referenced-dependencies:
- type: maven                    # <- Note that this is not "gradle", as referenced in the note above.
  name: javax.xml.bind:jaxb-api  # <- Note that this uses the Maven convention of 'groupId:artifactId'.
  version: 1.0.0
```

For more details, see the [manual dependencies](/docs/cli/features/manual-dependencies) documentation.

#### Selecting a set of configurations for analysis

You can use a [configuration file](/docs/cli/references/files/fossa-yml) to provide the set of configurations to filter analysis to. Any configurations not listed are excluded.

{% callout type="warning" %}
This feature is experimental and may be changed or removed at any time, without warning. For more information, see the [experimental features reference](/docs/cli/references/experimental).
{% /callout %}

```yaml
version: 3

experimental:
  gradle:
    configurations-only:
      - example-1-config-to-include
      - example-2-config-to-include
```

### Configuration reference

{% callout type="info" %}
The CLI excludes deprecated configurations from analysis. With newer Gradle versions, some configurations (such as `compile`) are no longer supported. Before removal, Gradle deprecates them with a warning; these configurations should not declare dependencies, and their resolution would be incorrect ([see this Gradle issue](https://github.com/gradle/gradle/issues/8585)).
{% /callout %}

By default, the CLI excludes test and development dependencies from analysis. Configurations are classified as follows:

- **Development:** `compileOnly`.
- **Test:** `testImplementation`, `testCompileOnly`, `testRuntimeOnly`, `testCompileClasspath`, `testRuntimeClasspath`.

For **Android** projects, FOSSA classifies a larger set of configurations as development or test dependencies. This includes the per-variant compile/runtime classpath and metadata configurations (`debugCompileClasspath`, `releaseCompileOnly`, the `*DependenciesMetadata` configurations, lint configurations, the Kotlin compiler classpath configurations, and so on), and the test-metadata configurations (`test*DependenciesMetadata`, `androidJacocoAnt`, etc.). FOSSA also classifies any dependency whose configuration name is prefixed with `androidTest`, `debugAndroidTest`, `releaseUnitTest`, or `debugUnitTest` as a test dependency.

## Authenticating to private registries

FOSSA can fetch and resolve Gradle dependencies from private registries like Artifactory, Nexus, or any custom Maven registry. Because Gradle resolves from Maven repositories, these settings live under the **Java** language settings, which govern the entire Java ecosystem.

{% steps %}
{% step title="Open Java language settings" %}
Go to **Account Settings → Languages → Java** (`https://app.fossa.com/account/settings/languages/java`).
{% /step %}
{% step title="Add a public registry" %}
To add a public registry, add a new entry under **Repositories**. FOSSA will begin checking that registry (in order) for the packages your projects bring in.
{% /step %}
{% step title="Add a private registry" %}
To add an authenticated registry, add two entries (one under **Repositories** and one under **Servers**) with a matching `Id`, and include your credentials in the **Servers** entry.
{% /step %}
{% /steps %}

{% img src="/images/project-setup/2bfa12f-Screen_Shot_2018-03-25_at_2.16.25_PM.png" alt="Adding a private Maven registry under Java Language Settings" /%}

By default, FOSSA resolves Java-ecosystem packages from a set of public registries (Maven Central first, then Cloudera, Sonatype, and others) in order. If you know which registries you'd like FOSSA to prefer, re-order them in the Java Language Settings so the registries most likely to succeed are checked first. This resolves dependencies without cycling through subsequent registries.

## Package data

The Gradle build system pulls in dependencies from the repository it resolves against:

| Repository type | Supported |
| :-- | :-- |
| Maven | Yes |
| Ivy | No |
| Local | No |

The metadata FOSSA pulls in is similar to Maven: available versions, home page URL, and per-dependency Group ID, Artifact ID, resolved version, transitive excludes, and scopes.

FOSSA parses data from all package metadata and scans all code provided in an artifact or associated code archives. If references to license webpages are found, FOSSA crawls the web for licensing information. Where no source code is included in an artifact, FOSSA attempts to resolve it to a known codebase and perform a full code audit. In the Java ecosystem it is common for license data to be stripped when artifacts are published; in these cases license data can be regenerated from the FOSSA registry by enriching build artifacts with data from associated VCSs, parent artifacts, and more.

### Gradle properties

Gradle properties can be set via environment variables. Property names should be prefixed with `ORG_GRADLE_PROJECT_`, as described in the [Gradle documentation](https://docs.gradle.org/current/userguide/build_environment.html).

---

Source: https://docs.fossa.com/docs/project-setup/supported-languages/gradle/plugin

# Gradle build plugin

{% callout type="warning" %}
This tactic does not support static analysis, which means it requires a CI integration executing FOSSA CLI.
{% /callout %}

{% callout type="info" %}
Gradle analysis is not supported in Container Scanning.
{% /callout %}

This tactic runs a [Gradle init script](https://docs.gradle.org/current/userguide/init_scripts.html) to output the dependencies in each Gradle subproject. Mechanically, this tactic:

1. Unpacks an [init script](https://github.com/fossas/fossa-cli/blob/master/scripts/jsondeps.gradle) to a temporary directory. Elsewhere in this document, we refer to this as "the plugin".
2. Invokes the plugin with `gradle jsonDeps -Ipath/to/init.gradle`.
3. Parses the JSON output of the plugin.

The plugin works by iterating through configurations, getting the resolution result for each configuration, and then serializing those dependencies into JSON.

{% callout type="warning" %}
The plugin requires Gradle v3.3 or greater.
{% /callout %}

## Debugging

### Manually view plugin output

If the plugin doesn't appear to be working correctly, you can run it directly:

1. [Download it from this repository](https://github.com/fossas/fossa-cli/blob/master/scripts/jsondeps.gradle).
2. Run the command `gradle -I$PATH_TO_SCRIPT jsonDeps`, where `$PATH_TO_SCRIPT` is the location to which the plugin was downloaded.

For example, with the plugin downloaded to `/tmp/jsondeps.gradle`, run (from within your project's working directory):

```
gradle -I/tmp/jsondeps.gradle jsonDeps
```

Usually, this output provides additional information on what is causing the build to fail. This information is provided by Gradle and is not related to FOSSA.

### Debugging the plugin

If the plugin itself appears to not be working based on its output, please send in a support request with the following information:

1. If available, the "complete report" written by Gradle when you ran the script directly. This is usually linked in the Gradle output with the message "See the complete report at {file path}".
2. The commands you executed to run the plugin directly, and the verbatim output of those commands.
3. A minimal reproduction case for us to run locally so we can debug the script on our systems.

{% callout type="tip" %}
Support requests can be initiated at [https://support.fossa.com](https://support.fossa.com).
{% /callout %}

### "Configuration cache problems found in this build"

The plugin output may contain text like the below:

```
FAILURE: Build failed with an exception.

* Where:
Initialization script 'jsondeps.gradle' line: 190

* What went wrong:
Configuration cache problems found in this build.
```

This is a Gradle-specific issue with the "configuration cache" feature in relation to the plugin FOSSA uses. The Gradle configuration cache is enabled by setting `org.gradle.unsafe.configuration-cache=true` in your `gradle.properties`.

According to the Gradle documentation, the configuration cache is not compatible with all "Gradle plugins and features"; the plugin used by FOSSA CLI appears to be one of them.

{% callout type="tip" %}
You can read more about the [Gradle configuration cache here](https://docs.gradle.org/current/userguide/configuration_cache.html).
{% /callout %}

Specific resolution steps depend on your project and Gradle version, but one possible resolution is to set `org.gradle.unsafe.configuration-cache-problems=warn` in your `gradle.properties`. This turns configuration cache problems into warnings instead of errors, so they stop preventing the project from building when FOSSA CLI attempts to analyze it.

---

Source: https://docs.fossa.com/docs/project-setup/supported-languages/scala

# Scala

FOSSA supports Scala projects built with **sbt** (the Scala Build Tool). You can analyze a project two ways: **Quick Import** in the web app, or the **FOSSA CLI** for complex builds.

## Tool support

| Tool | Quick Import (app.fossa.com) | CLI (fossa-cli) |
| :-- | :-- | :-- |
| sbt (Scala Build Tool) | `build.sbt` | `build.sbt` |

## How Quick Import works

After importing Scala code, FOSSA attempts to get results out of the box by incrementally running your build and statically resolving the dependency signatures it produces. This method supports a wide variety of build states, but more complicated builds often require configuration or inlined settings.

{% callout type="info" %}
Because sbt builds are generally complicated, it is both impossible to generically build codebases and to get accurate results from pure static analysis of `build.sbt` files. For larger builds that require significant configuration, we recommend **CI/CD Scanning** with the FOSSA CLI for fast and accurate results.
{% /callout %}

## Analyzing with the CLI

For complex Scala builds, use the FOSSA CLI to upload results from an existing sbt build in CI or on your local development machine.

Install the latest release of `fossa-cli`:

```shell
curl -H 'Cache-Control: no-cache' https://raw.githubusercontent.com/fossas/fossa-cli/master/install-latest.sh | bash
```

Then run `fossa analyze` from your repository's root directory. While the `gradle` and `maven` strategies offer some Scala coverage, Scala projects overwhelmingly use sbt. See the [sbt strategy reference](/docs/project-setup/supported-languages/scala/sbt) for project discovery, the supported tactics, and configuration details.

### Analysis strategies

| Strategy | Direct Deps | Transitive Deps | Edges | Container Scanning |
| --- | --- | --- | --- | --- |
| [sbt](/docs/project-setup/supported-languages/scala/sbt) | :white_check_mark: | :white_check_mark: | :white_check_mark: | :x: |

## Authenticating to private registries

Scala packages are resolved from the same Maven repositories as the rest of the Java ecosystem, so FOSSA can fetch and resolve sbt dependencies from private registries like Artifactory, Nexus, or any custom public Maven registry.

{% steps %}
{% step title="Open Java language settings" %}
Go to **Account Settings → Languages → Java** (`https://app.fossa.com/account/settings/languages/java`).
{% /step %}
{% step title="Add your registry" %}
To add a new public registry, add an entry under **Repositories**, and FOSSA will begin checking it (in order) for packages your projects bring in. To add an authenticated registry, add matching entries to **Repositories** and **Servers** with a corresponding **Id**, and include your credentials under the **Servers** entry.
{% /step %}
{% /steps %}

{% callout type="tip" %}
If you know which registries you want FOSSA to prefer, re-order them in your Java Language Settings. FOSSA checks registries in order, so placing the ones you know will succeed first lets it resolve dependencies without cycling through the rest.
{% /callout %}

## Package data

FOSSA parses data from all package metadata and scans all code provided in an artifact or its associated code archives. If references to license webpages are found, FOSSA crawls the web to find licensing information. When no source code is included in an artifact, FOSSA attempts to resolve it to a known codebase the artifact was built from and performs a full code audit.

In the Java ecosystem it is common for license data to be stripped when artifacts are published. In these cases, license data can be regenerated from the FOSSA registry by enriching build artifacts with data from associated VCSs, parent artifacts, and more.

{% callout type="warning" %}
FOSSA scans sbt dependencies that are published in the Maven-compatible file layout (the default). Artifacts published in the Ivy file layout are not yet supported.
{% /callout %}

---

Source: https://docs.fossa.com/docs/project-setup/supported-languages/scala/sbt

# sbt Analysis

While the other analysis strategies for `gradle` and `maven` offer some scala project coverage, scala projects overwhelmingly use the build tool `sbt`.

| Tactics                        | Direct Deps        | Transitive Deps    | Edges              | Container Scanning |
| ------------------------------ | ------------------ | ------------------ | ------------------ | ------------------ |
| `sbt dependencyBrowseTreeHTML` | :white_check_mark: | :white_check_mark: | :white_check_mark: | :x:                |
| `sbt dependencyTree`           | :white_check_mark: | :white_check_mark: | :white_check_mark: | :x:                |
| `sbt makePom`                  | :white_check_mark: | :x:                | :x:                | :x:                |
 
# Requirements

- `sbt` executable in PATH
- Project can be compiled with `sbt compile` or equivalent
- [sbt-dependency-graph](#how-do-i-use-sbt-dependency-graph-plugin) plugin is accessible

## Project Discovery

Directories that contain build.sbt files are treated as sbt project entry points.

After finding an sbt entry point, FOSSA CLI then runs
`sbt --no-colors --batch makePom` to infer the target to scan.

Each target listed by the entrypoint is a different target scanned by FOSSA.

## Analysis

1. Run `sbt makePom` to generate pom files

## `sbt dependencyTree`

1. From the generated pom file, identify the project name via the `<name>` attribute.
2. Perform `sbt $project/dependencyTree` and parse its output to create a dependency graph

For this approach, you will need to ensure `dependencyTree` task is accessible. To do so, 
please use [sbt-dependency-graph](#how-do-i-use-sbt-dependency-graph-plugin) plugin.

### Limitations

- This tactic does not support multi-project builds due an [inconsistent reporting defect in sbt](https://github.com/sbt/sbt/issues/6905)
- This tactic requires that project is using [sbt-dependency-graph](#how-do-i-use-sbt-dependency-graph-plugin) plugin.
- Since `sbt dependencyTree` command's output does not include a version classifier, consequently, version classifiers are ignored.

## `sbt dependencyBrowseTreeHTML`

1. Run `sbt dependencyBrowseTreeHTML`
2. From the generated `tree.html` file, find the corresponding `tree.json` file
3. Find the corresponding pom file generated via (step 1 of the analysis)
4. Parse `tree.json` to create a dependency graph

For this approach, you will need to ensure the `dependencyBrowseTreeHTML` task is accessible. To do so, 
please use [sbt-dependency-graph](#how-do-i-use-sbt-dependency-graph-plugin) plugin.

### Limitations

- This tactic requires that project is using [sbt-dependency-graph](#how-do-i-use-sbt-dependency-graph-plugin) plugin.
- Since the `sbt dependencyBrowseTreeHTML` command's output does not include a version classifier, consequently, version classifiers are ignored.

## `sbt makePom`

1. From generated pom.xml, use the maven strategy to "link together" related poms into projects and extract a dependency graph

## FAQ

### How do I only analyze scala projects?

You can explicitly specify analyses target in `.fossa.yml` file. 
The example below will exclude all analysis targets except scala. 

```yaml
# .fossa.yml 

version: 3
targets:
  only:
    - type: scala
```

### How do I use [sbt-dependency-graph](https://github.com/sbt/sbt-dependency-graph) plugin?

To identify deep dependencies and edges among them, FOSSA CLI requires use of the following tasks:

- `dependencyBrowseTreeHTML` (for multi-project builds)
- `dependencyTree`

To add the [sbt-dependency-graph](https://github.com/sbt/sbt-dependency-graph) plugin only to a single project, 
put this line into `project/plugins.sbt` of your project:

With `sbt 1.4.0+`:

```
addDependencyTreePlugin
```
Refer to sbt: https://www.scala-sbt.org/1.x/docs/sbt-1.4-Release-Notes.html#sbt-dependency-graph+is+in-sourced


With `sbt < 1.4`:

```
addSbtPlugin("net.virtual-void" % "sbt-dependency-graph" % "0.10.0-RC1")
```

Plugins can be installed for all your projects at once by declaring them in `$HOME/.sbt/$VERSION/plugins/`.
`$HOME/.sbt/$VERSION/plugins/` is an sbt project whose classpath is exported to all sbt build definition projects.

### Why does `fossa-cli` use `sbt dependencyBrowseTreeHTML` command?

`dependencyBrowseTreeHTML` command generates a dependency graph in JSON
format per each project in sbt build. Unlike `dependencyBrowseTree` command, 
it does not open a browser once command is successfully ran. It produces a graph
in a format that is easy to parse and diagnose.

## Does FOSSA CLI include standard library as a dependency?

Yes

---

Source: https://docs.fossa.com/docs/project-setup/supported-languages/scala/sbt-qr

# Quick reference: sbt

## Requirements

**Ideal/Minimum**

- `sbt` buildtool installed
- `build.sbt` file present in your project

## Project discovery

Directories containing `build.sbt` files are treated as sbt projects

---

Source: https://docs.fossa.com/docs/project-setup/supported-languages/ruby

# Ruby

FOSSA supports Ruby codebases through `RubyGems` and Bundler. You can analyze a project two ways: **Quick Import** in the web app, or the **FOSSA CLI**.

## Tool support

| Tool | Quick Import (app.fossa.com) | CLI (fossa-cli) |
| :-- | :-- | :-- |
| bundler | `Gemfile`, `Gemfile.lock` or `*.gemspec` | `Gemfile`, `Gemfile.lock` |
| gem | `Gemfile` | `Gemfile.lock` |

## How Quick Import works

When Ruby code is imported through the web app, FOSSA finds and runs any `Gemfile` or `*.gemspec` files and monitors dependency activity.

{% callout type="info" %}
If a `Gemfile.lock` is present, FOSSA prefers it for dependency information.
{% /callout %}

## Analyzing with the CLI

For complex Ruby builds, CI/CD scanning with the FOSSA CLI is the ideal integration path.

Install the latest release of `fossa-cli`:

```shell
curl -H 'Cache-Control: no-cache' https://raw.githubusercontent.com/fossas/fossa-cli/master/install-latest.sh | bash
```

Then run `fossa analyze` from your repository's root directory. In CI/CD scanning for Ruby, `fossa analyze` relies on the output of `bundle list` to determine what was installed in your build environment. If the `bundle list` command cannot be executed successfully, it falls back to parsing `Gemfile.lock`. See the [Bundler strategy reference](/docs/project-setup/supported-languages/ruby/bundler) for the full page.

### Analysis strategies

| Strategy | Direct Deps | Transitive Deps | Edges | Tags | Container Scanning |
| --- | --- | --- | --- | --- | --- |
| gemfilelock | :white_check_mark: | :white_check_mark: | :white_check_mark: | | :white_check_mark: |
| bundleshow | :white_check_mark: (unlabeled) | :white_check_mark: (unlabeled) | :x: | | :x: |

* :white_check_mark:, Supported when relevant data is available

## Authenticating to private registries

FOSSA supports fetching private Gems from custom or authenticated sources.

{% steps %}
{% step title="Open Ruby language settings" %}
Go to **Account Settings → Languages → Ruby** (`https://app.fossa.com/account/settings/languages/ruby`).
{% /step %}
{% step title="Add your credentials" %}
Enter the login credentials FOSSA should use to reach your private Gem source, then save.
{% /step %}
{% /steps %}

Once configured, FOSSA can resolve any previously unreachable Gems.

{% img src="/images/project-setup/2107111-Screen_Shot_2018-03-30_at_2.49.39_PM.png" alt="Ruby private Gem source credentials in Account Settings" /%}

## Package data

For basic metadata, FOSSA parses or evaluates all available metadata files for license and authorship information. This includes `Gemfile`, `Gemfile.lock`, and `*.gemspec` formats.

Since source is generally accessible, FOSSA supports full code auditing on RubyGems and runs license scans and code analysis across all files in a given Gem.

---

Source: https://docs.fossa.com/docs/project-setup/supported-languages/ruby/bundler

# Quick reference: bundler

## Requirements

**Ideal**

- `bundler` installed locally
- `Gemfile` or `Gemfile.lock` file present in your project

**Minimum**

- `Gemfile.lock` file present in your project

## Project discovery

Directories containing `Gemfile` or `Gemfile.lock` files are considered
Ruby projects.

Subdirectory scans are not affected by the discovery of a Ruby project.

---

Source: https://docs.fossa.com/docs/project-setup/supported-languages/php

# PHP

FOSSA supports PHP projects through [Composer](https://getcomposer.org/). You can analyze a project two ways: **Quick Import** in the web app, or the **FOSSA CLI** (recommended).

## Tool support

| Tool | Quick Import (app.fossa.com) | CLI (fossa-cli) |
| :-- | :-- | :-- |
| Composer | `composer.json` | `composer.lock` |

## How Quick Import works

When a Composer project is imported through the web app, FOSSA reads `composer.json` to resolve dependencies. If an exact version is not given (i.e. a version range), FOSSA resolves a dependency to the highest version satisfying the constraint, compliant with the [Composer versioning spec](https://getcomposer.org/doc/articles/versions.md).

{% callout type="warning" %}
Repository Scanning of Composer projects currently has the following limitations:

- We do not elect versions based on the `composer.lock` file.
- We currently ignore stability tags (`@dev`, `@stable`, etc.).
- We ignore php and php extensions when inside the `require` key of `composer.json`.
- We only look at `require` for dependencies. Dev dependencies are ignored (`require-dev`, `repositories`, and `replace` are ignored).
- Non-standard version constraints (i.e. `dev-`, or `.x-dev`) currently have stability issues.
{% /callout %}

## Analyzing with the CLI

The FOSSA CLI is the recommended way to analyze PHP projects. It reads the `composer.lock` file, so it resolves direct and transitive dependencies and classifies dev dependencies; capabilities that Quick Import does not provide.

Install the latest release of `fossa-cli`:

```shell
curl -H 'Cache-Control: no-cache' https://raw.githubusercontent.com/fossas/fossa-cli/master/install-latest.sh | bash
```

Then run `fossa analyze` from your repository's root directory to analyze your Composer project. See the [Composer strategy reference](/docs/project-setup/supported-languages/php/composer) for detection and analysis details.

### Analysis strategies

| Strategy | Direct Deps | Transitive Deps | Edges | Classifies Dev Dependencies | Container Scanning |
| --- | --- | --- | --- | --- | --- |
| [composer.lock](/docs/project-setup/supported-languages/php/composer) | :white_check_mark: | :white_check_mark: | :white_check_mark: | :white_check_mark: | :white_check_mark: |

## Package data

FOSSA supports any package available on [packagist.org](https://packagist.org/).

All code within a package is audited for license information. If a license file is declared by the `license` field in `composer.json`, it is elected as a "Declared License" or "Primary License" in the FOSSA UI.

---

Source: https://docs.fossa.com/docs/project-setup/supported-languages/php/composer

# Composer Analysis

When developing in PHP, [composer](https://getcomposer.org/) is commonly used to manage dependencies.

| Strategy      | Direct Deps        | Transitive Deps          | Edges              | Classifies Dev Dependencies | Container Scanning |
| ------------- | ------------------ | ------------------ | ------------------ | --------------------------- | --------------------------------- |
| composer.lock | :white_check_mark: | :white_check_mark: | :white_check_mark: | :white_check_mark:          | :white_check_mark:                |

## Project Discovery

Find a file named `composer.lock`.

## Analysis

1. Parse `composer.lock` to identify direct and transitive dependencies.

## Example 

1. Execute `composer init` to create a new project or create `composer.json` manually:

Example composer.json:
```json
{
    "name": "fossa/php-project",
    "description": "example php project",
    "require": {
        "michelf/php-markdown": "^1.9"
    },
    "require-dev": {
        "webmozart/assert": "^1.10"
    },
    "authors": [
        {
            "name": "Megh",
            "email": "megh@fossa.com"
        }
    ]
}
```

3. Execute `composer update` to install and pin dependencies - this will create (or modify) the `composer.lock` file.
4. Execute `fossa analyze -o` on the project to print analyzed dependency graphing (this will not upload any analysis to any endpoint)

## FAQ

### How do I only perform analysis for the composer?

You can explicitly specify an analysis target in `.fossa.yml` file. The example below will exclude all analysis targets except for the composer. 

```yaml
# .fossa.yml 

version: 3
targets:
  only:
    - type: composer
```

---

Source: https://docs.fossa.com/docs/project-setup/supported-languages/dotnet

# .NET (C#, F#, VB)

FOSSA supports .NET (C#, F#, Visual Basic, etc.) projects through the **NuGet** and **Paket** package managers. You can analyze a project two ways: **Quick Import** in the web app, or the **FOSSA CLI** for complex builds.

## Tool support

| Tool | Quick Import (app.fossa.com) | CLI (fossa-cli) |
| :-- | :-- | :-- |
| NuGet | `.csproj/.xproj`, `packages.config`, `project.json` or `.nuspec` | `.csproj/.xproj`, `packages.config`, `project.lock.json`, `obj/project.assets.json`, `project.json` or `.nuspec` |
| Paket | N/A | `paket.lock` |

## How Quick Import works

When .NET code is imported through the web app, FOSSA attempts to resolve any dependencies listed under the following files:

* `.csproj/.xproj`
* `packages.config`
* `project.json`
* `.nuspec`

{% callout type="warning" %}
- FOSSA does not currently inspect `project.lock.json` files, nor does it support `files`, `references`, or `frameworkAssemblies` specified in the `.nuspec` file.
- `.nuspec` files must be in `utf8` encoding.
- FOSSA currently ignores `Frameworks` specified in the `project.json`/`packages.config` file.
- FOSSA currently ignores the `NuGet.config` file.
{% /callout %}

For complex builds, use CLI analysis instead.

## Analyzing with the CLI

For complex .NET builds that rely on custom tooling or restore steps, CI/CD scanning with the FOSSA CLI is the ideal integration path. The CLI builds your project with `dotnet` or `nuget`, then parses the lockfiles left from your build and analyzes what you have installed in your `packages` directory, producing dependency data to upload to FOSSA.

Install the latest release of `fossa-cli`:

```shell
curl -H 'Cache-Control: no-cache' https://raw.githubusercontent.com/fossas/fossa-cli/master/install-latest.sh | bash
```

Then run `fossa analyze` from your repository's root directory. The .NET ecosystem spans two package managers, [NuGet](/docs/project-setup/supported-languages/dotnet/nuget) (`nuspec`, `PackageReference`, `packages.config`, `project.json`, `project.assets.json`) and [Paket](/docs/project-setup/supported-languages/dotnet/paket). The CLI selects a strategy per project; each strategy's detection details are linked in the table below.

### Analysis strategies

| Strategy | Direct Deps | Transitive Deps | Edges |
| --- | --- | --- | --- |
| [paket](/docs/project-setup/supported-languages/dotnet/paket) | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: |
| [project.assets.json](/docs/project-setup/supported-languages/dotnet/projectassetsjson) | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: |
| [PackageReference](/docs/project-setup/supported-languages/dotnet/packagereference) | :heavy_check_mark: | :x: | :x: |
| [project.json](/docs/project-setup/supported-languages/dotnet/projectjson) | :heavy_check_mark: | :x: | :x: |
| [packages.config](/docs/project-setup/supported-languages/dotnet/packagesconfig) | :heavy_check_mark: | :x: | :x: |
| [nuspec](/docs/project-setup/supported-languages/dotnet/nuspec) | :heavy_check_mark: | :x: | :x: |

## Authenticating to private registries

You can configure FOSSA to fetch dependencies from private NuGet feeds published through tools like Artifactory or Sonatype Nexus.

{% steps %}
{% step title="Open .NET language settings" %}
Go to **Account Settings → Languages → .NET** (`https://app.fossa.com/account/settings/languages/dotnet`).
{% /step %}
{% step title="Add your credentials" %}
Enter the login credentials FOSSA should use to reach your private feed, then save.
{% /step %}
{% /steps %}

FOSSA can now resolve private NuGet dependencies.

{% img src="/images/project-setup/ca72a8d-Screen_Shot_2018-03-28_at_11.01.56_PM.png" alt=".NET private feed credentials in Account Settings" /%}

## Package data

When FOSSA discovers a NuGet artifact, it scans all data provided in the package metadata and performs a full code scan of any files associated with or provided in a NuGet archive.

In addition, if a license file is provided as a URL (in a `.nuspec` file via the `licenseUrl` property), FOSSA attempts to crawl the URL and scan the endpoint for license data. In the FOSSA UI, matches against licenses retrieved via web crawling are labeled as `LICENSE_<license-name>.txt`.

Any missing data is enriched by associated codebases that can be resolved to known artifacts.

---

Source: https://docs.fossa.com/docs/project-setup/supported-languages/dotnet/nuget

# NuGet Analysis

| Strategy                                    | Direct Deps | Transitive Deps | Edges |
|---------------------------------------------|-------------|-----------------|-------|
| [project.assets.json](/docs/project-setup/supported-languages/dotnet/projectassetsjson) | ✅           | ✅               | ✅     |
| [PackageReference](/docs/project-setup/supported-languages/dotnet/packagereference)     | ✅           | ❌               | ❌     |
| [project.json](/docs/project-setup/supported-languages/dotnet/projectjson)              | ✅           | ❌               | ❌     |
| [packages.config](/docs/project-setup/supported-languages/dotnet/packagesconfig)        | ✅           | ❌               | ❌     |
| [nuspec](/docs/project-setup/supported-languages/dotnet/nuspec)                         | ✅           | ❌               | ❌     |

NuGet analysis follows these strategies in sequence:
1. `project.assets.json`
2. `PackageReference`

`project.assets.json` files and their dependencies are generated from  `.csproj` files. `PackageReference` dependencies can be found in `.csproj`, `.xproj`, `.vbproj`, `.dbproj`, or `.fsproj` files. To consolidate findings from these two strategies, `project.assets.json` analysis is attempted first and falls back to `PackageReference` analysis. 

The following strategies are executed independently::
1. `project.json`
2. `packages.config`
3. `nuspec`

`project.json` and `packages.config` files are deprecated in favor of `.csproj` and their usage of `PackageReference` format. `nuspec` serves as a manifest containing package metadata, used both for building the package and providing information to consumers. These strategies are isolated from the `project.assets.json` and `PackageReference` approaches and therefore run independently.

---

Source: https://docs.fossa.com/docs/project-setup/supported-languages/dotnet/nuspec

# nuspec

A `.nuspec` file is an XML manifest that contains package metadata for Nuget packages. This manifest is used both to build the package and to provide information to consumers.

## Project Discovery

Walk the directory and find all files with a  `.nuspec` suffix

## Analysis

Depending on the version of Nuget in use, dependencies can be specified in two ways.

### Dependencies element

The <dependencies> element within <metadata> contains any number of <dependency> elements that identify other packages upon which the top-level package depends. Example:

```
<?xml version="1.0"?>
<package >
  <metadata>
    <id>GenericServices</id>
    <version>1.0.10</version>
    <title>GenericServices</title>
    <authors>Jon Smith</authors>
    <owners>Jon Smith</owners>
    <dependencies>
      <dependency id="GenericLibsBase" version="1.0.1" />
      <dependency id="EntityFramework" version="6.1.3" />
      <dependency id="AutoMapper" version="4.2.1" />
      <dependency id="DelegateDecompiler.EntityFramework" version="0.18" />
    </dependencies>
  </metadata>
</package>
```

### Dependency groups

As an alternative to a single flat list, dependencies can be specified according to the framework profile of the target project using <group> elements within <dependencies>.

```
<?xml version="1.0"?>
<package >
  <metadata>
    <id>GenericServices</id>
    <version>1.0.10</version>
    <title>GenericServices</title>
    <authors>Jon Smith</authors>
    <owners>Jon Smith</owners>
    <dependencies>
      <group>
        <dependency id="RouteMagic" version="1.1.0" />
      </group>
      <group targetFramework=".NETFramework4.7.2">
        <dependency id="jQuery" version="1.6.2" />
        <dependency id="WebActivator" version="1.4.4" />
      </group>
    </dependencies>
  </metadata>
</package>
```

---

Source: https://docs.fossa.com/docs/project-setup/supported-languages/dotnet/packagereference

# PackageReference

Package references, using the `PackageReference` node, manage NuGet dependencies directly within project files (as opposed to a separate `packages.config` file)

## Project Discovery

Walk the directory and find all NuGet project files, i.e. files with the suffix of `.csproj`, `.xproj`, `.vbproj`, `.dbproj`, or `.fsproj`.

## Analysis

Parse the XML project files, and collect dependency data from all `PackageReference` tags:

```
<ItemGroup>
    
    <PackageReference Include="Sitecore.Kernel" Version="12.0.0" />
    
</ItemGroup>
```

---

Source: https://docs.fossa.com/docs/project-setup/supported-languages/dotnet/packagesconfig

# packages.config

The `packages.config` XML file is used in some project types to maintain the list of packages referenced by the project.

Note: projects that use `PackageReference` do not use `packages.config`.

## Project Discovery

Walk the directory and find all files names `packages.config`

## Analysis

Parse the XML file, and collect dependency data from all `package` tags within the `packages` section:

```
<?xml version="1.0" encoding="utf-8"?>
<packages>
  <package id="jQuery" version="3.1.1" targetFramework="net46" />
  <package id="NLog" version="4.3.10" targetFramework="net46" />
</packages>
```

---

Source: https://docs.fossa.com/docs/project-setup/supported-languages/dotnet/projectjson

# project.json

The `project.json` file maintains a list of packages used in a project, known as a package management format. It supersedes `packages.config` but is in turn superseded by `PackageReference` with NuGet 4.0+.

## Project Discovery

Walk the directory and find all files names `project.json`

## Analysis

Parse the JSON file and search for the `dependencies` section:

```
"dependencies": {
    "Microsoft.NETCore": "5.0.0",
    "System.Runtime.Serialization.Primitives": "4.0.10"
}
```

---

Source: https://docs.fossa.com/docs/project-setup/supported-languages/dotnet/projectassetsjson

# project.assets.json

The `project.assets.json` file is used in `.NET Core` projects to manage dependencies and other resources

## Project Discovery

Walk the directory and find all files names `project.assets.json`

## Analysis

> Note, `fossa-cli` expects that the project is compiled, and built prior to using `fossa analyze` command.
 
Parse the JSON file, and construct a full dependency graph (direct and transitive dependencies).
 
From the `project.assets.json`, `fossa-cli` uses:
 
- `targets`: To infer edges between dependencies of a framework.
- `project`: To infer which dependencies are direct dependencies for the target framework.
 
For example,
 
```json
{
     "version": 1,
     "targets": {
           ".NETFramework,Version=v4.0": {
                 "one/1.0.0": { // Dependency Name and Version
                       "type": "package",
                       "dependencies": {
                             "three": "3.0.0"
                       }
                 },
                 "three/3.0.0": {
                       "type": "package"
                 },
           }
     },
     "project": {
           "frameworks": {
                 "net4.0": {
                       "targetAlias": "net4.0",
                       "dependencies": {
                             "one": {}, // Direct Dependency
                       }
                 }
           }
     }
}
```
 
* Key heading under `targets.$frameworkName` are used to infer resolved dependency. For instance `one/1.0.0` will be inferred as a dependency with name of `one` and version of `1.0.0`.
 
* For each dependency, all entries under `dependencies` will form edges. From the previous example, `fossa-cli` will infer edge from dependency `one` to dependency `three`.
 
* Dependencies listed under `project.$frameworkName` are used to infer if the dependency is direct or not. From aforementioned example, `one` will be considered a direct dependency.
 
* Any dependency of type `"project"` will be ignored from the analysis.

---

Source: https://docs.fossa.com/docs/project-setup/supported-languages/dotnet/paket

# Paket

| Strategy          | Direct Deps | Transitive Deps | Edges |
|-------------------|-------------|-----------------|-------|
| [paket](/docs/project-setup/supported-languages/dotnet/paket) | ✅           | ✅               | ✅     |

Paket is a dependency manager for .NET projects. Paket enables precise and predictable control over your dependencies

Paket manages your dependencies with three core file types:

`paket.dependencies`, where you specify your dependencies and their versions for your entire codebase.
`paket.references`, a file that specifies a subset of your dependencies for every project in a solution.
`paket.lock`, a lock file that Paket generates when it runs. When you check it into source control, you get reproducible builds.

## Project Discovery

Walk the directory and find all lock files (`paket.lock`)

## Analysis
Parse the lock file, and construct a dependency graph:

```
NUGET
  remote: nuget.com
    one (1.0.0)
      two (>1.0.0)
    two (2.0.0)

HTTP
  remote: custom-site.com
    three (3.0.0)
```

dependencies can come from either NuGet, Github, or a specified remote URL.

---

Source: https://docs.fossa.com/docs/project-setup/supported-languages/dotnet/paket-qr

# Quick reference: Paket

## Requirements

**Ideal/Minimum**

- `paket.lock` file

## Project discovery

Directories containing any of the files listed above are considered Paket projects

---

Source: https://docs.fossa.com/docs/project-setup/supported-languages/rust

# Rust

FOSSA supports Rust codebases through Cargo. You can analyze a project two ways: **Quick Import** in the web app, or the **FOSSA CLI**.

## Tool support

| Tool | Quick Import (app.fossa.com) | CLI (fossa-cli) |
| :-- | :-- | :-- |
| Cargo | `Cargo.toml` or `Cargo.lock` | `Cargo.toml` |

## How Quick Import works

When Rust code is imported through the web app, FOSSA inspects any `Cargo.toml` or `Cargo.lock` files and downloads their dependencies for analysis.

{% callout type="warning" %}
- Optional dependencies are currently handled like Java optional dependencies, rather than being enabled or disabled based on features.
- FOSSA does not currently understand default or missing features.
- FOSSA does not handle path dependencies that point above your repository root.
{% /callout %}

## Analyzing with the CLI

The Rust build-tool ecosystem is nearly exclusive to `cargo`, the package manager that ships with Rust distributions. (Generic build tools like `make`, `cmake`, and `ninja` are occasionally used but are not handled here.)

Install the latest release of `fossa-cli`:

```shell
curl -H 'Cache-Control: no-cache' https://raw.githubusercontent.com/fossas/fossa-cli/master/install-latest.sh | bash
```

Then run `fossa analyze` from your repository's root directory. See the [Cargo strategy reference](/docs/project-setup/supported-languages/rust/cargo) for the full page.

### Analysis strategies

| Strategy | Direct Deps | Transitive Deps | Edges | Tags | Container Scanning |
| --- | --- | --- | --- | --- | --- |
| cargo | :white_check_mark: | :white_check_mark: | :white_check_mark: | Environment | :x: |

### Project discovery

FOSSA finds every `Cargo.toml` whose parent directories do not also contain a `Cargo.toml`. For example, given the tree below, only `root/Cargo.toml` is examined:

```
root
├── src1
│   ├── subpackage
│   │   ├── Cargo.toml
│   │   └── ...
│   └── main.rs
└── Cargo.toml
```

In the next tree, both `root/pkg1/Cargo.toml` and `root/pkg2/Cargo.toml` are examined, since neither has a parent directory with a `Cargo.toml`:

```
root
├── pkg1
│   ├── Cargo.toml
│   └── main.rs
└── pkg2
    ├── Cargo.toml
    └── main.rs
```

### Analysis

FOSSA first invokes `cargo generate-lockfile` to trigger the lockfile build; this downloads the dependency graph info and almost nothing else. It then reads the output of `cargo metadata --format-version 1` (JSON) and interrogates it for direct and transitive dependency information: `.workspace_members` lists the local crates, `.resolve` gives each crate's direct dependencies, and `.packages` carries per-package version, platform, build category, and feature data.

{% callout type="warning" %}
If FOSSA does not regenerate the lockfile, it may try to download every dependency in the tree, which can take upwards of 10 minutes even for small projects. Regenerating first updates only the package index, which usually takes 2–10 seconds.
{% /callout %}

## Authenticating to private registries

You can configure FOSSA to resolve dependencies from private Cargo registries, such as those hosted on Artifactory.

{% steps %}
{% step title="Open Rust language settings" %}
Go to **Account Settings → Languages → Rust** (`https://app.fossa.com/account/settings/languages/rust`).
{% /step %}
{% step title="Add your registry" %}
Enter the registry index URL and an authentication token. Cargo registries are reached with a bearer token sent as `Authorization: Bearer <token>`, which is the most common mechanism for Cargo registries.
{% /step %}
{% /steps %}

## Package data

Cargo packages are downloaded and extracted for full code auditing; metadata from the registry and the `Cargo.toml` manifest are parsed and extracted.

---

Source: https://docs.fossa.com/docs/project-setup/supported-languages/rust/cargo

# Quick reference: cargo

## Requirements

**Ideal/Minimum**

- `cargo` buildtool installed on your machine
- `Cargo.toml` file present in your project

## Project discovery

Directories containing `Cargo.toml` files are considered cargo projects.

Subdirectories of cargo projects are not re-scanned for nested cargo projects, because the dependency tree of the parent project already includes the dependency tree of those subprojects.  To scan only the subprojects, run the `fossa` tool against the subproject directories

---

Source: https://docs.fossa.com/docs/project-setup/supported-languages/dart

# Dart

FOSSA supports Dart and Flutter projects through [pub](https://pub.dev/), the package manager for the Dart ecosystem. Pub manages shared [packages and libraries](https://dart.dev/guides/packages), which can be sourced from the [pub registry](https://pub.dev/), a [git repository](https://dart.dev/tools/pub/dependencies#git-packages), or the [local file system](https://dart.dev/tools/pub/dependencies#path-packages).

## Tool support

| Tool | Quick Import (app.fossa.com) | CLI (fossa-cli) |
| :-- | :-- | :-- |
| Dart (pub) | N/A | `pubspec.yaml` |

## How Quick Import works

Dart projects are not supported through Quick Import in the web app. To analyze a Dart or Flutter project, use the FOSSA CLI.

{% callout type="info" %}
There is no Quick Import path for pub. Run the FOSSA CLI inside your build environment to analyze Dart and Flutter projects.
{% /callout %}

## Analyzing with the CLI

Install the latest release of `fossa-cli`:

```shell
curl -H 'Cache-Control: no-cache' https://raw.githubusercontent.com/fossas/fossa-cli/master/install-latest.sh | bash
```

Then run `fossa analyze` from your repository's root directory to analyze your Dart or Flutter project using pub. FOSSA discovers Dart projects by finding `pubspec.yaml` files. See the [pub strategy reference](/docs/project-setup/supported-languages/dart/pub) for the full page.

{% callout type="warning" %}
Run `flutter pub get` (or `dart pub get`) before `fossa analyze` to ensure all dependencies are resolved. This creates the `pubspec.lock` file and lets the `pub deps -s compact` command produce edges between direct and transitive dependencies.
{% /callout %}

### Analysis strategies

FOSSA attempts all of the strategies below and selects the result of the succeeded strategy with the highest preference.

| Preference | Strategy | Direct Deps | Transitive Deps | Edges | Container Scanning |
| --- | --- | --- | --- | --- | --- |
| Highest | `pubspec.yaml` and `pubspec.lock` discovered, and `flutter pub deps -s compact` can be executed | :white_check_mark: | :white_check_mark: | :white_check_mark: | :x: |
|  | `pubspec.yaml` and `pubspec.lock` discovered, and `dart pub deps -s compact` can be executed | :white_check_mark: | :white_check_mark: | :white_check_mark: | :x: |
|  | `pubspec.yaml` and `pubspec.lock` discovered, and `pub deps -s compact` can be executed | :white_check_mark: | :white_check_mark: | :white_check_mark: | :x: |
|  | `pubspec.yaml` and `pubspec.lock` discovered | :white_check_mark: | :white_check_mark: | :x: | :white_check_mark: |
| Lowest | Only `pubspec.yaml` discovered | :white_check_mark: | :x: | :x: | :white_check_mark: |

* :heavy_check_mark:, Supported in all projects
* :white_check_mark:, Supported only when relevant data is available
* :x:, Not supported

### Limitations

- [Path dependencies](https://dart.dev/tools/pub/dependencies#path-packages) are not reported, and are ignored in analyses. All descendant dependencies of the path dependency are promoted to the ancestor of the path dependency.
- [SDK dependencies](https://dart.dev/tools/pub/dependencies#sdk) are not reported, and are ignored in analyses. All descendant dependencies of the SDK dependency are promoted to the ancestor of the SDK dependency.

## Authenticating to private registries

You can configure FOSSA to resolve dependencies from private pub servers.

{% steps %}
{% step title="Open Pub language settings" %}
Go to **Account Settings → Languages → Pub** (`https://app.fossa.com/account/settings/languages/pub`).
{% /step %}
{% step title="Add your server" %}
Enter the server ID, URL, and an authentication token for each private pub server FOSSA should use, then save.
{% /step %}
{% /steps %}

FOSSA can now resolve packages from your private pub servers.

## Package data

When the `pub deps` command runs successfully and a lockfile is discovered, FOSSA produces a dependency graph with both direct and transitive dependencies, including the edges between them.

```mermaid
---
config:
  themeVariables:
    fontSize: 12px
  flowchart:
    nodeSpacing: 16
    rankSpacing: 24
    padding: 4
    diagramPadding: 8
---
flowchart TD
    ENC["encrypt.git"]:::prod --> ARGS["args"]:::unknown
    ENC --> ASN["asn1lib"]:::unknown
    ENC --> CLK["clock"]:::unknown
    COL["collection"]:::prod --> CRY["crypto"]:::unknown
    CRY --> PC["pointycastle"]:::unknown
    PRV["provider"]:::prod --> NST["nested"]:::unknown
    QVR["quiver"]:::prod --> MAT["matcher"]:::unknown
    MAT --> STK["stack_trace"]:::unknown
    classDef prod fill:#edf7f2,stroke:#1d7a54,color:#171717,stroke-width:2px
    classDef dev fill:#ffffff,stroke:#737373,color:#525252,stroke-width:2px
    classDef unknown fill:#ffffff,stroke:#a3a3a3,color:#666666,stroke-width:2px,stroke-dasharray:5 5
```

Accent green nodes are direct dependencies; dashed-border nodes are transitive. Descendant dependencies of SDK dependencies are promoted to their ancestor.

If the `pub deps` command does not run successfully, FOSSA falls back to a graph derived from the lockfile or manifest alone.

```mermaid
---
config:
  themeVariables:
    fontSize: 12px
  flowchart:
    nodeSpacing: 16
    rankSpacing: 24
    padding: 4
    diagramPadding: 8
---
flowchart TD
    ENC["encrypt.git"]:::prod
    PATH["path"]:::prod
    PRV["provider"]:::prod
    QVR["quiver"]:::prod
    classDef prod fill:#edf7f2,stroke:#1d7a54,color:#171717,stroke-width:2px
    classDef dev fill:#ffffff,stroke:#737373,color:#525252,stroke-width:2px
    classDef unknown fill:#ffffff,stroke:#a3a3a3,color:#666666,stroke-width:2px,stroke-dasharray:5 5
```

Only direct dependencies are listed; edges between packages are not resolved without a successful `pub deps` run.

---

Source: https://docs.fossa.com/docs/project-setup/supported-languages/dart/pub

# Quick reference: pub

## Requirements

**Ideal/Minimum**
- `dart` installed locally
- `pubspec.yaml` file present in your project
- `pubspec.lock` file present in your project, with dependencies already retrieved and resolved 

## Project discovery

Directories containing `pubspec.yaml` files are considered dart projects.

---

Source: https://docs.fossa.com/docs/project-setup/supported-languages/ios

# iOS (Objective-C, Swift)

FOSSA supports Swift, Objective-C, and Cocoa projects through CocoaPods, Carthage, and Swift Package Manager. You can analyze a project two ways: **Quick Import** in the web app, or the **FOSSA CLI** for complex builds.

## Tool support

| Tool | Quick Import (app.fossa.com) | CLI (fossa-cli) |
| :-- | :-- | :-- |
| CocoaPods | `Podfile`, `Podfile.lock`, `*.podspec` | `Podfile.lock` |
| Carthage | `Cartfile`, `Cartfile.private`, `Cartfile.resolved` | `Cartfile.resolved` |
| Swift Package Manager | N/A | `Package.resolved`, `Package.swift`, `project.pbxproj` |

## How Quick Import works

When iOS code is imported through the web app, FOSSA inspects the codebase for dependencies resolvable by CocoaPods or Carthage.

For **CocoaPods**, FOSSA derives dependencies by analyzing your `Podfile`/`Podfile.lock` files and seeing which dependencies are brought in. Other metadata is fetched directly from repository `*.podspec` files. The [CocoaPods build system](https://cocoapods.org/) pulls in dependencies based on name, [SemVer version](http://semver.org/), and external repository (Git, Subversion, Mercurial, HTTP). To add your own podspec repos, see [Authenticating to private registries](#authenticating-to-private-registries) below.

{% callout type="info" %}
FOSSA's Repository Scanning uses CocoaPods version ~1.0. If your `Podfile` is built using an earlier version, there is a chance that it may not build correctly. See [Migrating to 1.0](http://blog.cocoapods.org/CocoaPods-1.0/).
{% /callout %}

{% callout type="warning" %}
- We don't factor in the platform specified in the `Podfile`. For each dependency, we fetch the code for all valid platforms.
- Build configurations are not taken into account at the moment.
- If a subspec (or subspecs) of a pod is given, FOSSA analyzes the entire pod.
- Only Git external sources are supported. Subversion, Mercurial, and HTTP sources are currently not supported.
- Plugins in `Podfile`s are currently ignored.
- Pre- and post-install hooks sometimes do not work properly.
- Pre-release version ranges currently resolve to the version given (for example, `>=10.1.1.beta` resolves to `10.1.1.beta`, as does `~>10.1.1.beta`).
- Multi-range versions with pre-releases may not work properly (for example, `>10.1.1.beta1 <10.1.1.beta4`).
{% /callout %}

For **Carthage**, FOSSA scans through your project and analyzes any `Cartfile` that is found. It grabs dependencies based on name, [SemVer version](http://semver.org/), and external repository (Git, GitHub).

{% callout type="warning" %}
- Nested dependencies aren't properly handled.
- `Cartfile.resolved` files aren't analyzed during Quick Import, so versioning may be inconsistent.
- Local file repositories (for example, `File:///`) in `Cartfile`s aren't analyzed.
{% /callout %}

## Analyzing with the CLI

For complex iOS builds, CI/CD scanning with the FOSSA CLI is the ideal integration path. The iOS build-tool ecosystem consists of three major toolchains: CocoaPods, Carthage, and Swift Package Manager.

Install the latest release of `fossa-cli`:

```shell
curl -H 'Cache-Control: no-cache' https://raw.githubusercontent.com/fossas/fossa-cli/master/install-latest.sh | bash
```

Then run `fossa analyze` from your repository's root directory. To produce the best results, make sure the appropriate lockfile is present:

- CocoaPods projects: a `Podfile.lock` file in your repository. See the [CocoaPods strategy reference](/docs/project-setup/supported-languages/ios/cocoapods).
- Carthage projects: a `Cartfile.resolved` file in your repository. See the [Carthage strategy reference](/docs/project-setup/supported-languages/ios/carthage).
- Swift Package Manager projects: a `Package.resolved` file in your repository. See the [Swift Package Manager strategy reference](/docs/project-setup/supported-languages/ios/swift).

### Analysis strategies

| Strategy | Direct Deps | Transitive Deps | Edges | Container Scanning |
| --- | --- | --- | --- | --- |
| [Carthage](/docs/project-setup/supported-languages/ios/carthage) | :white_check_mark: | :white_check_mark: | :white_check_mark: | :white_check_mark: |
| [Podfile.lock](/docs/project-setup/supported-languages/ios/cocoapods) | :white_check_mark: | :white_check_mark: | :white_check_mark: | :x: |
| [Podfile](/docs/project-setup/supported-languages/ios/cocoapods) | :white_check_mark: | :x: | :x: | :white_check_mark: |
| [Swift Package Manager](/docs/project-setup/supported-languages/ios/swift) | :white_check_mark: | :white_check_mark: | :x: | :white_check_mark: |

* :white_check_mark:, Supported (transitive deps for Swift require `Package.resolved`; for CocoaPods require `Podfile.lock`)
* :x:, Not supported

## Authenticating to private registries

You can add your own private podspec repos so FOSSA can resolve dependencies hosted in them.

{% steps %}
{% step title="Open CocoaPods language settings" %}
Go to **Account Settings → Languages → Cocoapods** (`https://app.fossa.com/account/settings/languages/cocoa`).
{% /step %}
{% step title="Add a source repository" %}
Under **Source Repositories**, add the URL for your podspec repo. Use the form `https://github.com/artsy/Specs` for public repos and `git@github.com:artsy/Specs.git` for private repos.
{% /step %}
{% step title="Authorize FOSSA's key" %}
When you add a new spec repo, FOSSA attempts to automatically add its public key to the GitHub repo. If your private spec repos are not working, make sure FOSSA's public key is added to your GitHub settings under the project's deploy key section. On-prem users get their public key from the host server; if one doesn't exist, the CocoaPods migration creates a key pair.
{% /step %}
{% /steps %}

The route and **Cocoapods** label are confirmed against `app/components/settings/languages/index.tsx` (`/account/settings/languages/cocoa`) and `CocoaSettings/index.tsx` ("Cocoapods Settings", "Source Repositories") in FOSSA-Core.

{% img src="/images/project-setup/3db97d5-cocoapods-add.png" alt="Adding a CocoaPods podspec repo in Account Settings" /%}

{% img src="/images/project-setup/7042ab6-github-publickey.png" alt="Adding the FOSSA public key to a GitHub project's deploy keys" /%}

## Package data

FOSSA derives CocoaPods dependencies from your `Podfile`/`Podfile.lock` and fetches additional metadata from repository `*.podspec` files. Carthage dependencies are taken from the `Cartfile`. Swift Package Manager dependencies are read from `Package.swift`, `Package.resolved`, or Xcode's `project.pbxproj`.

The following are **not** supported across the iOS strategies:

- CocoaPods sources other than Git, Subversion, Mercurial, Bazaar, and HTTP-path sources are not supported (for example, `pod 'JSONKit', :podspec => 'https://example.com/JSONKit.podspec'`).
- Plugins in `Podfile`s (ignored).
- Path dependencies in Swift Package Manager (for example, `package(path: "./../local-pkg")`) and Xcode dependencies sourced via a local path are ignored.
- Swift Xcode project files that are not in ASCII plist format with UTF-8 encoding.

---

Source: https://docs.fossa.com/docs/project-setup/supported-languages/ios/cocoapods

# Cocoapods Analysis

## Project Discovery

`podfile`: Find all directories containing a `Podfile` file.

`podfilelock`: Find all directories containing a `Podfile.lock` file.

## Analysis: podfile

We scan the `Podfile` text for `pod` declarations, which indicate a direct
dependency of the current project.  We also scan for a `source` declaration,
which gives us a default source to assign to all `pod` declarations without an
explicit source.

## Analysis: podfilelock

We scan the `Podfile.lock` for two particular sections: `PODS` and
`DEPENDENCIES`.  The `PODS` section describes the relationships between the
dependencies, and `DEPENDENCIES` tells us which of the dependencies the project
depends on directly.

In the following example, we have five dependencies, `one`, `two`, `three`,
`four` and `five/+zlib`. `one`, `three` and `five/+zlib` are direct dependencies, `one` depends on both
`two` and `three`, and `three` depends on `four`.

```
PODS:
  - one (1.0.0):
    - two (= 3.2.1)
    - three (= 3.2.1)
  - two (2.0.0)
  - three (3.0.0)
    - four (= 2.3.3)
  - four (4.0.0):
  - "five/+zlib (7.0.0)"

DEPENDENCIES:
  - one (> 4.4)
  - three (from `Submodules/subproject/.podspec`)
  - "five/+zlib (7.0.0)"
```

We also look at the `EXTERNAL SOURCES` section to try and resolve locally vendored Cocoapods. If we see a locally vendored Cocoapod using either `:podspec` or `:path` to a local directory, we'll read the Podspec at that directory and also upload that dependency if it has a supported `source`. We will also replace any dependencies originating via subspec of locally vendored dependency, with it's vendored dependency's `source`. We currently only support the `git` source. 

## Limitations

- Pods sourced from http path are not supported (e.g `pod 'JSONKit', :podspec => 'https://example.com/JSONKit.podspec'`).
- Pods sourced from subversion, mercurial, and bazaar are not supported.
- Plugins in Podfiles are ignored.

---

Source: https://docs.fossa.com/docs/project-setup/supported-languages/ios/cocoapods-qr

# Quick reference: cocoapods

## Requirements

**Ideal**

- `Podfile.lock` file present in your project

**Minimum**

- `Podfile` file present in your project

## Project discovery

Directories containing `Podfile` or `Podfile.lock` files are considered
cocoapods projects.

---

Source: https://docs.fossa.com/docs/project-setup/supported-languages/ios/carthage

# Carthage Analysis

## Project Discovery

Find any folder which contains a file named `Cartfile.resolved`.  Skip all
subdirectories if one is found.

## Analysis

The `Cartfile.resolved` file contains a list of direct dependencies, which
should each represent subfolders in the `Carthage/Checkouts` directory.  This
structure is recursively scanned and combined into a single analysis.  See
below for an example:

```
myproject
├─ Cartfile.resolved     # ref to "Quick/Nimble"
└─ Carthage/
   └─ Checkouts/
      └─ Nimble/
         ├─ Cartfile.resolved     # ref to "mattgallagher/CwlPreconditionTesting"
         └─ Carthage/
            └─ Checkouts/
               └─ CwlPreconditionTesting/   # and so on...
```

---

Source: https://docs.fossa.com/docs/project-setup/supported-languages/ios/carthage-qr

# Quick reference: carthage

## Requirements

**Ideal/Minimum**
- `Cartfile.resolved` file present in your project

## Project discovery
Directories containing `Cartfile.resolved` files are considered carthage projects. Subdirectories of carthage project root directories are not scanned for nested carthage projects.

---

Source: https://docs.fossa.com/docs/project-setup/supported-languages/ios/swift

# Swift Package Manager

## Project Discovery

Find all files named: `Package.swift` or find Xcode's project file named: `project.pbxproj`. 
We will not scan `.build` directory if the `Package.swift` or Xcode project file is discovered. 

# Swift Analysis

| Strategy                                                                 | Direct Deps        | Transitive Deps    | Edges | Classifies Test Dependencies | Container Scanning |
| ------------------------------------------------------------------------ | ------------------ | ------------------ | ----- | ---------------------------- | ------------------ |
| Parse dependencies from `Package.swift`                                  | :white_check_mark: | :x:                | :x:   | :x:                          | :white_check_mark: |
| Parse dependencies from `Package.swift` and `Package.resolved`           | :white_check_mark: | :white_check_mark: | :x:   | :x:                          | :white_check_mark: |
| Parse dependencies from Xcode's `project.pbxproj`                        | :white_check_mark: | :x:                | :x:   | :x:                          | :white_check_mark: |
| Parse dependencies from Xcode's `project.pbxproj` and `Package.resolved` | :white_check_mark: | :white_check_mark: | :x:   | :x:                          | :white_check_mark: |

- Manifest file: `Package.swift`, must begin with `// swift-tools-version:` string, followed by version number specifier. 
- We follow swift package manager's convention and presume properties of the package are defined in a single nested initializer statement and are not modified after initialization.
- Valid Xcode project for swift, is defined by the discovery of `project.pbxproj` file in ASCII plist format with at least one `XCRemoteSwiftPackageReference` object in its content.

## Limitations

- Path dependencies are ignored in the analysis (e.g. `package(path: "./../local-pkg")`)
- If the Xcode project dependencies are sourced via a local path, they will be ignored in the analysis.
- Only Xcode project files in ASCII plist format with UTF-8 encoding are supported.

## Example

Create Package.swift file in the directory. Add dependencies, targets, products, and source code. Example Package.swift file is shown below. By convention, the properties of a Package are defined in a single nested initializer statement, and not modified after initialization.

```swift
// swift-tools-version:5.4.0
import PackageDescription

let package = Package(
    name: "Example",
    defaultLocalization: "en",
    products: [],
    dependencies: [
        .package(name: "grpc-swift", url: "https://github.com/grpc/grpc-swift.git", from: "1.0.0"),
    ]
)
```

We can update and resolve dependencies by performing `swift package update`. Executing this will create Package.resolved in the directory. An example file is shown below:

```json
{
  "object": {
    "pins": [
      {
        "package": "grpc-swift",
        "repositoryURL": "https://github.com/grpc/grpc-swift.git",
        "state": {
          "branch": null,
          "revision": "14e1ea3350892a864386517c037e11fb68baf818",
          "version": "1.3.0"
        }
      },
      {
        "package": "swift-log",
        "repositoryURL": "https://github.com/apple/swift-log.git",
        "state": {
          "branch": null,
          "revision": "5d66f7ba25daf4f94100e7022febf3c75e37a6c7",
          "version": "1.4.2"
        }
      }
    ]
  },
  "version": 1
}

```
Note: Only a few pins are shown above for brevity.

### `Package.swift` and `Package.resolved`

When the analysis is performed (e.g. `fossa analyze -o`), we will identify the following as direct dependencies:

- https://github.com/grpc/grpc-swift.git with version 1.3.0

If `Package.resolved` is discovered, the following transitive dependencies will be identified, however, we will not identify the edges in the dependency graph:

- https://github.com/apple/swift-log.git with version 1.4.2

If `Package.resolved` is not discovered, only direct dependencies will be reported. 

### Xcode Project and `Package.resolved`

For Xcode project using swift package manager to manage swift package dependencies, Xcode project file named `project.pbxproj` will be analyzed. In the Xcode project file, `XCRemoteSwiftPackageReference` objects will be used to identify swift packages that are direct dependencies. For the analysis, at least one such reference must exist in the file. If no such references are found, we will not consider the Xcode project in the swift analysis.

Excerpt from example `project.pbxproj`:

```
// !$*UTF8*$!
{
  archiveVersion = 1;
  classes = {
  };
  objectVersion = 52;
  objects = {
    
    ...

    170A463726ECEDEF002DDFB8 /* XCRemoteSwiftPackageReference "example-package-deckofplayingcards" */ = {
      isa = XCRemoteSwiftPackageReference;
      repositoryURL = "https://github.com/apple/example-package-deckofplayingcards";
      requirement = {
        branch = main;
        kind = branch;
      };
    };

    ...
  };
  rootObject = 17874CD926C46B8500D16CA8 /* Project object */;
} 
```

If the `Package.resolved` is discovered, transitive dependencies will be identified. If not, only direct dependencies listed in xcode project file will be identified. In either case, no edges among dependencies will be reported.

## F.A.Q

### How do I only perform analysis for swift package dependencies?

You can explicitly specify the analysis target in `.fossa.yml` file.

The example below will exclude all analysis targets except swift. 

```yaml
# .fossa.yml 

version: 3
targets:
  only:
    - type: swift
```

### Swift packages sourced from local directories are not discovered in the analysis. Is there a workaround?

This is a current limitation. For swift package manager analysis, we only support non-path dependencies at the moment. 
To include local dependencies, you can use `fossa-deps.yml` file to upload the local package for license scanning and analysis.

```yaml
# in fossa-deps.yml

vendored-dependencies:
- name: MyLocalPackage
  path: /Jenkins/App/Resources/MyLocalPackage # path can be either a file or a folder.
  version: 3.4.16 # revision will be set to the MD5 hash of the file path if left unspecified.
```

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.
Refer to [vendored dependencies](/docs/cli/features/vendored-dependencies) for more details. 

### When performing `fossa list-targets`, Xcode project using swift packages are not getting discovered.

For swift, we consider the Xcode project to be a valid Xcode project, if and only if it meets the following requirements:
- Xcode project file named: `project.pbxproj` exists in the directory.
- Xcode project file must be in ASCII plist format with UTF-8 encoding.
- Xcode project file has at least one object, with isa of `XCRemoteSwiftPackageReference`. 

## References

- [Swift Package Manager](https://docs.swift.org/swiftpm/documentation/packagemanagerdocs)
- [Package.swift documentation](https://docs.swift.org/swiftpm/documentation/packagedescription/package/)

---

Source: https://docs.fossa.com/docs/project-setup/supported-languages/c-cpp

# C/C++

C and C++ have no universal package manager, so there is no single manifest or lockfile for FOSSA to read. Instead, FOSSA detects dependencies through a combination of **vendored-code fingerprinting**, **snippet scanning**, and **build-system integrations** (Conan, Yocto, and Buildroot). These approaches are additive. You can combine whichever ones fit how your project is built.

All strategies require `fossa-cli` version 3.1.3 or greater. Install the latest release:

```shell
curl -H 'Cache-Control: no-cache' https://raw.githubusercontent.com/fossas/fossa-cli/master/install-latest.sh | bash
```

## Detection strategies

| Strategy | What it detects | Reference |
| :--- | :--- | :--- |
| Vendored code | Open-source libraries vendored directly into your project tree, even with comment or whitespace changes | [Vendored dependencies](/docs/cli/features/vendored-dependencies) |
| Snippet scanning | Open-source code snippets copied into your first-party files | [Snippet scanning](/docs/cli/features/snippet-scanning) |
| Conan | Dependencies managed by the Conan package manager | [Scanning Conan projects](/docs/cli/walkthroughs/conan) |
| Yocto | Runtime packages in a Yocto image build | [Scanning Yocto projects](/docs/cli/walkthroughs/yocto) |
| Buildroot | Dependencies in a Buildroot environment | [Scanning Buildroot projects](/docs/cli/walkthroughs/buildroot) |

## Analyzing with the CLI

Because no standard package manager is used, the CLI relies on statistical analysis of the project to determine likely vendored dependencies, and can inspect output binaries for dynamically linked dependencies on some platforms.

| Strategy | Direct Deps | Transitive Deps | Edges | Container Scanning |
| :--- | :--- | :--- | :--- | :--- |
| `detect-vendored` | :white_check_mark: | :x: | :x: | :x: |
| `detect-dynamic` | :white_check_mark: | :white_check_mark: | :x: | :x: |

### Project discovery

- `detect-vendored`: The root of the scan directory is assumed to be the only "project".
- `detect-dynamic`: The binary indicated by the argument is assumed to be the only "project".

### Analysis

- `detect-vendored`: Run `fossa analyze --detect-vendored`.
  - To _only_ detect vendored dependencies, run `fossa analyze --detect-vendored --only-target vsi`.
- `detect-dynamic`: Run `fossa analyze --detect-dynamic <BINARY_PATH>`.
  - This inspects the binary at `BINARY_PATH` for dynamically linked dependencies.
  - This requires specific platform support. See the extended documentation below.

Further reading:

- [`detect-vendored`](/docs/cli/references/subcommands/analyze/detect-vendored) in [`subcommands/analyze`](/docs/cli/references/subcommands/analyze)
- [`detect-dynamic`](/docs/cli/references/subcommands/analyze/detect-dynamic) in [`subcommands/analyze`](/docs/cli/references/subcommands/analyze)

---

Source: https://docs.fossa.com/docs/project-setup/supported-languages/haskell

# Haskell

FOSSA supports Haskell projects through `cabal` and `stack`. Haskell projects are analyzed with the **FOSSA CLI**, which resolves dependencies from within your build environment.

## Tool support

| Tool | Quick Import (app.fossa.com) | CLI (fossa-cli) |
| :-- | :-- | :-- |
| Haskell (cabal) | N/A | `*.cabal` |
| Haskell (stack) | N/A | `stack.yaml` |

## Analyzing with the CLI

The Haskell build-tool ecosystem consists of two major toolchains: `cabal`-the-tool and `stack`.

Install the latest release of `fossa-cli`:

```shell
curl -H 'Cache-Control: no-cache' https://raw.githubusercontent.com/fossas/fossa-cli/master/install-latest.sh | bash
```

Then run `fossa analyze` from your repository's root directory to analyze your Haskell project with `cabal` or `stack`. The CLI selects a strategy per project; each strategy's detection details are linked in the table below.

### Analysis strategies

| Strategy | Direct Deps | Transitive Deps | Edges | Container Scanning |
| --- | --- | --- | --- | --- |
| [cabal](/docs/project-setup/supported-languages/haskell/cabal) | :white_check_mark: | :white_check_mark: | :white_check_mark: | :x: |
| [stack](/docs/project-setup/supported-languages/haskell/stack) | :white_check_mark: | :white_check_mark: | :white_check_mark: | :x: |

---

Source: https://docs.fossa.com/docs/project-setup/supported-languages/haskell/cabal

# Cabal

## Project Discovery

Find all directories with a `cabal.project` file or a file with a `.cabal`
extension.  When one is found, skip all subdirectories.

*NOTE: We don't actually examine the cabal files, we just use their existence*
*to determine that we are woking with a cabal project.  As a result, we can*
*handle multiple `*.cabal` files, even though `cabal` cannot.*

## Analysis

From the project root, we open the `./dist-newstyle/cache/plan.json` file,
created by `cabal`.  The relevant items in the file take the following form:

*Extra data removed for brevity*

``` json
{
    "install-plan": [
        {
            "type": "configured",
            "id": "with-components-1.0.2.3-efgh",
            "pkg-name": "with-components",
            "pkg-version": "1.0.2.3",
            "style": "global",
            "components": {
                "lib": {
                    "depends": [
                        "base-4.13.0.0"
                    ]
                },
                "setup": {
                    "depends": [
                        "rts"
                    ]
                }
            }
        },
        {
            "type": "pre-existing",
            "id": "rts",
            "pkg-name": "rts",
            "pkg-version": "1.0",
            "depends": []
        },
        {
            "type": "configured",
            "id": "spectrometer-0.1.0.0-inplace",
            "pkg-name": "spectrometer",
            "pkg-version": "0.1.0.0",
            "style": "local",
            "depends": [
                "aeson-1.5.2.0-abcd",
                "base-4.13.0.0",
                "with-components-1.0.2.3-efgh"
            ]
        }
    ]
}
```

Analysis has two notable parts: matching `id` fields from the strings in
`depends` and `components.*.depends`, and noting the package `type` and
`style`.  `pre-existing` types refer to builtin, ghc-provided packages, while
`configured` packages have two `style`s of their own: `local`, referring to the
current project, and `global`, referring to packages obtained from a remote
source like [hackage](https://hackage.haskell.org/).

---

Source: https://docs.fossa.com/docs/project-setup/supported-languages/haskell/cabal-qr

# Quick reference: cabal

## Requirements

**Ideal/Minimum**

At least one of:

- `cabal.project` file present in your project
- `*.cabal` file present in your project

## Project discovery

Directories containing one of the above files are considered cabal projects.
Subdirectories are not considered once a project is found.

---

Source: https://docs.fossa.com/docs/project-setup/supported-languages/haskell/stack

# Stack

## Project Discovery

Find all directories with a `stack.yaml` file.  When one is found, skip all
subdirectories.

## Analysis

From the project root, we run `stack ls dependencies json`, which outputs JSON
in the following format.

*Extra data removed for brevity*

``` json
[
    {
        "location": {
            "type": "hackage"
        },
        "name": "remote",
        "version": "remote-ver",
        "dependencies": [
            "deep"
        ]
    },
    {
        "location": {
            "type": "project package"
        },
        "name": "local",
        "version": "local-ver",
        "dependencies": [
            "remote",
            "builtin"
        ]
    },
    {
        "location": {
            "type": "hackage"
        },
        "name": "deep",
        "version": "deep-ver",
        "dependencies": []
    },
    {
        "name": "builtin",
        "version": "builtin-ver"
    }
]
```

Analysis has two notable parts: matching `name` fields from the strings in
`dependencies`, and noting the package's `location.type`.  A package with a 
missing `location.type` refers to a builtin, ghc-provided package, and a
present field takes one of two forms: remote and local, which have different
sets of string associated with them.  Local packages are references to the
current project, while remote references are pointers to package or source 
repositories.

---

Source: https://docs.fossa.com/docs/project-setup/supported-languages/haskell/stack-qr

# Quick reference: stack

## Requirements

**Ideal/Minimum**
- `stack` buildtool install
- `stack.yaml` file present in your project

## Project discovery

Directories containing a `stack.yaml` file are considered stack projects.
Subdirectories are not considered once a project is found.

---

Source: https://docs.fossa.com/docs/project-setup/supported-languages/elixir

# Elixir

FOSSA supports Elixir projects (including Phoenix) through [Mix](https://hexdocs.pm/mix/Mix.html), using the FOSSA CLI.

## Tool support

| Tool | Quick Import (app.fossa.com) | CLI (fossa-cli) |
| :-- | :-- | :-- |
| Elixir (mix) | N/A | `mix.exs` |

## Analyzing with the CLI

When developing in Elixir, [Mix](https://hexdocs.pm/mix/Mix.html) and [Hex](https://hex.pm/) are most commonly used to manage dependencies.

Install the latest release of `fossa-cli`:

```shell
curl -H 'Cache-Control: no-cache' https://raw.githubusercontent.com/fossas/fossa-cli/master/install-latest.sh | bash
```

Then run `fossa analyze` from your repository's root directory to analyze your Elixir project using Mix. See the [mix strategy reference](/docs/project-setup/supported-languages/elixir/mix) for detection and analysis details.

### Analysis strategies

| Strategy | Direct Deps | Transitive Deps | Edges | Container Scanning |
| --- | --- | --- | --- | --- |
| mix deps | :white_check_mark: | :white_check_mark: | :white_check_mark: | :x: |

{% callout type="info" %}
Dependencies must be resolved with `mix deps.get` and compiled with `mix compile` (or at least `mix deps.compile`) before running analysis. Dependencies must be sourced from Git or from Hex; private Hex repositories are not currently supported.
{% /callout %}

---

Source: https://docs.fossa.com/docs/project-setup/supported-languages/elixir/mix

# Quick reference: mix

## Requirements

**Ideal/Minimum**
- `mix` installed locally
- `mix.exs` and `mix.lock` file present in your project

## Project discovery

Directories containing `mix.exs` files are considered.

---

Source: https://docs.fossa.com/docs/project-setup/supported-languages/erlang

# Erlang

FOSSA supports Erlang projects through [rebar3](https://rebar3.org/docs/). Erlang is analyzed with the **FOSSA CLI**, which builds the dependency graph from your `rebar.config`.

## Tool support

| Tool | Quick Import (app.fossa.com) | CLI (fossa-cli) |
| :-- | :-- | :-- |
| Erlang (rebar3) | N/A | `rebar.config` |

## Analyzing with the CLI

When developing in Erlang, [rebar3](https://rebar3.org/docs/) is the most common package manager. Dependencies are specified in a manifest file, which `rebar3` uses to build a dependency graph and download the correct dependencies.

Install the latest release of `fossa-cli`:

```shell
curl -H 'Cache-Control: no-cache' https://raw.githubusercontent.com/fossas/fossa-cli/master/install-latest.sh | bash
```

Then run `fossa analyze` from your repository's root directory to analyze your Erlang project using rebar3. See the [rebar3 strategy reference](/docs/project-setup/supported-languages/erlang/rebar3) for detection details.

### Analysis strategies

| Strategy | Direct Deps | Transitive Deps | Edges | Container Scanning |
| --- | --- | --- | --- | --- |
| rebar3 | :white_check_mark: | :white_check_mark: | :white_check_mark: | :x: |

{% callout type="warning" %}
`rebar.config` allows users to alias dependencies in a format similar to `{deps, [{chatterbox, {pkg, ts_chatterbox}},`. This format is not currently handled in the CLI and will result in unknown dependencies being shown in the FOSSA UI. The team is aware of this limitation and a fix is planned.
{% /callout %}

---

Source: https://docs.fossa.com/docs/project-setup/supported-languages/erlang/rebar3

# Quick reference: rebar3

## Requirements

**Ideal/Minimum**
- `rebar3` installed locally
- `rebar.config` file present in your project

## Project discovery

Directories containing `rebar.config` files are considered
Erlang projects. `rebar.config` files in project subdirectories are ignored.

---

Source: https://docs.fossa.com/docs/project-setup/supported-languages/clojure

# Clojure

FOSSA supports Clojure projects built with [Leiningen](https://leiningen.org/), the most common Clojure package manager. Clojure analysis is performed with the **FOSSA CLI**.

## Tool support

| Tool | Quick Import (app.fossa.com) | CLI (fossa-cli) |
| :-- | :-- | :-- |
| Clojure (Leiningen) | N/A | `project.clj` |

## Analyzing with the CLI

Clojure dependencies are specified in a `project.clj` manifest, which the `lein` tool uses to build a dependency graph and download the correct dependencies.

Install the latest release of `fossa-cli`:

```shell
curl -H 'Cache-Control: no-cache' https://raw.githubusercontent.com/fossas/fossa-cli/master/install-latest.sh | bash
```

Then run `fossa analyze` from your repository's root directory to analyze your Clojure project using Leiningen. See the [Leiningen strategy reference](/docs/project-setup/supported-languages/clojure/leiningen) for detection and analysis details.

### Analysis strategies

| Strategy | Direct Deps | Transitive Deps | Edges | Container Scanning |
| --- | --- | --- | --- | --- |
| [lein deps](/docs/project-setup/supported-languages/clojure/leiningen) | :white_check_mark: | :white_check_mark: | :white_check_mark: | :x: |

* :white_check_mark:, Supported when relevant data is available
* :x:, Not supported

---

Source: https://docs.fossa.com/docs/project-setup/supported-languages/clojure/leiningen

# Quick reference: leiningen

## Requirements

**Ideal/Minimum**

- `lein` buildtool installed locally
- `project.clj` file present in your project and Leiningen installed.

## Project discovery

Directories containing `project.clj` are considered Clojure projects.

Subdirectory scans are not affected by the discovery of a Clojure project.

---

Source: https://docs.fossa.com/docs/project-setup/supported-languages/perl

# Perl

FOSSA supports Perl projects through CPAN. You can analyze a project two ways: **Quick Import** in the web app, or the **FOSSA CLI**.

## Tool support

| Tool | Quick Import (app.fossa.com) | CLI (fossa-cli) |
| :-- | :-- | :-- |
| perl / cpan | `cpanfile`, `Makefile.PL`, `Build.PL`, `(MY)META.(yml/json)` | `(MY)META.(yml/json)` |

## How Quick Import works

When Perl code is imported through the web app, FOSSA seeks and analyzes the following files for license and dependency information:

* `cpanfile`
* `Makefile.PL`
* `Build.PL`
* `(MY)META.(yml/json)`

Along with parsing these files, FOSSA runs the `cpanm` command line tool to discover dependencies brought in dynamically by CPAN. Once dependencies are found, they are resolved against the [CPAN ElasticSearch index](https://fastapi.metacpan.org).

{% callout type="info" %}
FOSSA's Repository Scanning infrastructure currently uses `Perl v5.18.2`.
{% /callout %}

## Analyzing with the CLI

Install the latest release of `fossa-cli`:

```shell
curl -H 'Cache-Control: no-cache' https://raw.githubusercontent.com/fossas/fossa-cli/master/install-latest.sh | bash
```

Then run `fossa analyze` from your repository's root directory to analyze your Perl project.

### Analysis strategies

| Strategy | Direct Deps | Transitive Deps | Edges | Classifies Dev Dependencies | Container Scanning |
| --- | --- | --- | --- | --- | --- |
| `*META.{yml, json}` | :white_check_mark: | :white_check_mark: | :x: | :white_check_mark: | :white_check_mark: |

**Project discovery**. FOSSA finds a file named `MYMETA.json`, `MYMETA.yml`, `META.json`, or `META.yml`.

**Analysis**: FOSSA parses the discovered `MYMETA.{yml, json}` or `META.{yml, json}` file to identify dependencies.

{% callout type="info" %}
- Only dependencies required for `runtime` are reported.
- Reported analysis does not include edges.
{% /callout %}

To restrict a scan to Perl only, specify the analysis target explicitly in a `.fossa.yml` file:

```yaml
# .fossa.yml

version: 3
targets:
  only:
    - type: perl
```

## Package data

FOSSA supports any packages available in the CPAN master registry. Declared licenses in `(MY)META.(yml/json)` files are recognized, as well as any licenses picked up in a full package-wide code audit.

---

Source: https://docs.fossa.com/docs/project-setup/supported-languages/fortran

# Fortran

FOSSA supports Fortran projects through the [Fortran Package Manager (fpm)](https://fpm.fortran-lang.org/). Fortran is analyzed with the **FOSSA CLI**.

## Tool support

| Tool | Quick Import (app.fossa.com) | CLI (fossa-cli) |
| :-- | :-- | :-- |
| Fortran (fpm) | N/A | `fpm.toml` |

## Analyzing with the CLI

Install the latest release of `fossa-cli`:

```shell
curl -H 'Cache-Control: no-cache' https://raw.githubusercontent.com/fossas/fossa-cli/master/install-latest.sh | bash
```

Then run `fossa analyze` from your repository's root directory to analyze your Fortran project with the Fortran Package Manager.

### Analysis strategies

| Strategy | Direct Deps | Transitive Deps | Edges | Classifies Dev & Test Deps | Container Scanning |
| --- | --- | --- | --- | --- | --- |
| fpm | :white_check_mark: | :x: | :x: | :white_check_mark: | :white_check_mark: |

### Project discovery

FOSSA finds files named `fpm.toml`. When an `fpm.toml` is found, FOSSA does not scan the `build` directory for additional Fortran projects.

### Analysis

FOSSA parses the `fpm.toml` file to identify direct dependencies.

{% callout type="info" %}
- FOSSA does not report [path dependencies](https://github.com/fortran-lang/fpm/blob/main/manifest-reference.md#local-dependencies).
- FOSSA does not report test or [development dependencies](https://github.com/fortran-lang/fpm/blob/main/manifest-reference.md#development-dependencies).
- Only direct dependencies are reported.
{% /callout %}

---

Source: https://docs.fossa.com/docs/project-setup/supported-languages/nim

# Nim

FOSSA supports [Nim](https://nim-lang.org/) projects that manage dependencies with Nimble, Nim's package manager. Nim analysis is performed with the **FOSSA CLI**.

## Tool support

| Tool | Quick Import (app.fossa.com) | CLI (fossa-cli) |
| :-- | :-- | :-- |
| Nim (Nimble) | N/A | `nimble.lock` |

## Analyzing with the CLI

Nimble pins dependencies in a `nimble.lock` file, which the FOSSA CLI parses to build the dependency graph. Direct dependencies are identified from the output of `nimble dump --json`.

Install the latest release of `fossa-cli`:

```shell
curl -H 'Cache-Control: no-cache' https://raw.githubusercontent.com/fossas/fossa-cli/master/install-latest.sh | bash
```

Then run `fossa analyze` from your repository's root directory. See the [Nimble strategy reference](/docs/project-setup/supported-languages/nim/nimble) for detection, analysis details, and limitations.

### Analysis strategies

| Strategy | Direct Deps | Transitive Deps | Edges | Container Scanning |
| --- | --- | --- | --- | --- |
| [nimble.lock and `nimble dump`](/docs/project-setup/supported-languages/nim/nimble) | :white_check_mark: | :white_check_mark: | :white_check_mark: | :x: |
| [nimble.lock](/docs/project-setup/supported-languages/nim/nimble) | :warning: | :white_check_mark: | :white_check_mark: | :white_check_mark: |

* :white_check_mark:, Supported when relevant data is available
* :warning:, Partially supported
* :x:, Not supported

---

Source: https://docs.fossa.com/docs/project-setup/supported-languages/nim/nimble

# Nimble Analysis

When developing in [nim](https://nim-lang.org/), nimble is used to manage dependencies.

| Strategy                      | Direct Deps        | Transitive Deps    | Edges              | Classifies Dev Dependencies | Container Scanning |
| ----------------------------- | ------------------ | ------------------ | ------------------ | --------------------------- | ------------------ |
| nimble.lock and `nimble dump` | :white_check_mark: | :white_check_mark: | :white_check_mark: | :x:                         | :x:                |
| nimble.lock                   | :warning:          | :white_check_mark: | :white_check_mark: | :x:                         | :white_check_mark: |

## Project Discovery

Find a file named `nimble.lock`.

## Analysis

1. Parse `nimble.lock` to identify dependencies and edges among them.
2. Perform `nimble dump --json` to identify direct dependencies.

Limitation:
- Dependencies downloaded from mercurial are not reported.
- When `nimble dump --json` fails, any dependencies without incoming edge is considered to be a direct dependency

## Example 

1. Execute `nimble init` to create a new project or create `nim.nimble` manually:

Example `nim.nimble`:
```nim
# Package

version       = "0.1.0"
author        = "User"
description   = "A new awesome nimble package"
license       = "MIT"
srcDir        = "src"
installExt    = @["nim"]
bin           = @["nim"]


# Dependencies

requires "nim >= 1.6.0"
requires "jester >= 0.4.1 & < 0.5.0"
```

3. Execute `nimble lock` to install and pin dependencies - this will create (or modify) the `nimble.lock` file.
4. Execute `fossa analyze -o` on the project to print analyzed dependency graphing (this will not upload any analysis to any endpoint)

{% callout type="info" %}
If you are using an older version of Nim, you may need to:

1. Run `choosenim 1.6.0`
2. Run `nimble install https://github.com/nim-lang/nimble@\#head` (install the latest nimble, or any version with lock file support)
{% /callout %}

## FAQ

### How do I only perform analysis for the nimble?

You can explicitly specify an analysis target in `.fossa.yml` file. The example below will exclude all analysis targets except for the composer. 

```yaml
# .fossa.yml 

version: 3
targets:
  only:
    - type: nimble
```

---

Source: https://docs.fossa.com/docs/project-setup/supported-languages/r

# R

FOSSA supports R projects that manage dependencies with [renv](https://rstudio.github.io/renv/index.html). R analysis is performed with the **FOSSA CLI**.

## Tool support

| Tool | Quick Import (app.fossa.com) | CLI (fossa-cli) |
| :-- | :-- | :-- |
| R (renv) | N/A | `DESCRIPTION`, `renv.lock` |

## Analyzing with the CLI

Direct dependencies are read from the project's `DESCRIPTION` file, while deep dependencies and edges come from the `renv.lock` lockfile produced by `renv::snapshot()`.

Install the latest release of `fossa-cli`:

```shell
curl -H 'Cache-Control: no-cache' https://raw.githubusercontent.com/fossas/fossa-cli/master/install-latest.sh | bash
```

Then run `fossa analyze` from your repository's root directory. See the [renv strategy reference](/docs/project-setup/supported-languages/r/renv) for detection, analysis details, and limitations.

### Analysis strategies

| Strategy | Direct Deps | Deep Deps | Edges | Container Scanning |
| --- | --- | --- | --- | --- |
| [`renv.lock`](/docs/project-setup/supported-languages/r/renv) | :warning: | :white_check_mark: | :white_check_mark: | :white_check_mark: |
| [`DESCRIPTION` & `renv.lock`](/docs/project-setup/supported-languages/r/renv) | :white_check_mark: | :white_check_mark: | :white_check_mark: | :white_check_mark: |

* :white_check_mark:, Supported when relevant data is available
* :warning:, Dependencies are included but not classified as direct
* :x:, Not supported

---

Source: https://docs.fossa.com/docs/project-setup/supported-languages/r/renv

# R Analysis (renv)

Currently, we only support analysis of r project which are using [renv package manager](https://rstudio.github.io/renv/index.html).

| Files                       | Direct Deps                             | Deep Deps          | Edges              | Classifies Dev & Test Deps | Container Scanning |
| --------------------------- | --------------------------------------- | ------------------ | ------------------ | -------------------------- | ------------------ |
| `renv.lock`                 | (included but not classified as direct) | :white_check_mark: | :white_check_mark: | :x:                        | :white_check_mark: |
| `DESCRIPTION` & `renv.lock` | :white_check_mark:                      | :white_check_mark: | :white_check_mark: | :x:                        | :white_check_mark: |


## Project Discovery

Find a file named `DESCRIPTION`, and optionally look for `renv.lock` in the same directory as `DESCRIPTION`. Discovery will not look for
projects inside `renv` directory, if `renv.lock` or `DESCRIPTION` files are discovered.

## Analysis

1. Parse `DESCRIPTION` file to identify direct dependencies - we look for packages in `Depends`, `Imports`, `Suggests`, `Enhances`, `LinkingTo`.
2. Parse `renv.lock` file to identify deep dependencies, and edges among them.

## Limitations

- If only `DESCRIPTION` file is accessible, FOSSA CLI will ignore version constraints, and will always default to latest version.

## Example

1. Create `DESCRIPTION` file:
```text
Type: project
Description: My project
Depends: tidyverse

```

2. Create `main.R` file:
```r
# you may need to execute following: 
# if you do not have renv installed
# >> install.packages("renv", repos = "http://cran.us.r-project.org")

# initiate project
# ref: https://rstudio.github.io/renv/reference/init.html
options(renv.config.install.verbose = TRUE)
options(renv.config.install.transactional = FALSE)
renv::init(bare = TRUE)
renv::install("glue@1.2.0")
renv::install()

# some example code
Square <- function(x) {
  return(x^2)
}
print(Square(4))

# create renv.lock
# ref: https://rstudio.github.io/renv/reference/snapshot.html
renv::snapshot()
```
3. execute `rscript main.R`
4. execute `fossa analyze --only-target renv --output` (run analysis only `renv`, but do not upload result to an endpoint)

## Limitations


- `fossa-cli` cannot identify test or development dependencies, and by default includes all dependencies in the analysis.
- `fossa-cli` will ignore version constraint if `renv.lock` file is not present.
- `fossa-cli` cannot analyze path dependencies.  
  - Please refer to [vendored dependencies](/docs/cli/features/vendored-dependencies) for workaround. 

## FAQ

### How do I only perform analysis for renv?

Explicitly specify an analysis target in `.fossa.yml` file. The example below excludes all other analysis targets:

```yaml
# .fossa.yml 

version: 3
targets:
  only:
    - type: renv
```

### FOSSA's analyzed dependencies are incorrect or missing a package. 

Please file a ticket at [FOSSA support portal](https://support.fossa.com).

Make sure to attach following for quick response from support or development team.

* `DESCRIPTION` file
* `renv.lock` file (if any)
* stdout of `renv::diagnostics()`

## References

- [Renv Package Manager for R](https://rstudio.github.io/renv/index.html)

---

Source: https://docs.fossa.com/docs/project-setup/supported-languages/system

# System

System packages are the operating-system-level packages installed in a container image, as opposed to application dependencies pulled in by a language ecosystem. When the FOSSA CLI scans a container image, it inspects the image's package databases to identify these OS packages and report them alongside your application's dependencies.

The package database FOSSA reads depends on the base distribution of the image:

| Package manager | Distributions | Support |
| :-- | :-- | :-- |
| [apk](/docs/project-setup/supported-languages/system/apk) | Alpine Linux | General |
| [dpkg](/docs/project-setup/supported-languages/system/dpkg) | Debian, Ubuntu | General |
| [rpm](/docs/project-setup/supported-languages/system/rpm) | RHEL, CentOS, Oracle Linux | General |
| [rpm](/docs/project-setup/supported-languages/system/rpm) | Fedora, SLES | Beta |

These strategies apply to container scanning. See each page for the specific files and databases FOSSA reads.

## How system packages are licensed

FOSSA resolves licenses for system packages from its **Knowledge service** using each package's declared-license metadata. It does not read license fields out of the image at scan time. Alpine and Debian/Ubuntu packages generally include complete license information; RHEL and Oracle Linux RPM packages may be reported as **unlicensed** where that data is incomplete (see [rpm](/docs/project-setup/supported-languages/system/rpm#license-identification-on-rhel-and-oracle-linux)).

## How versions are matched

FOSSA preserves each package's distribution, version, and **release/revision** (for example `1.2.2-r7` on Alpine or `5.1-2+deb11u1` on Debian). Distributions backport security fixes into new releases of the same upstream version, so keeping the release is what lets FOSSA match packages to the right vulnerabilities. Distribution versions are normalized for matching, Alpine to `major.minor` (e.g. `3.15`), and the RHEL family and Debian/Ubuntu to the major version (e.g. `9`).

---

Source: https://docs.fossa.com/docs/project-setup/supported-languages/system/apk

# apk

The Alpine Package Manager (**apk**) installs system packages on Alpine Linux images. FOSSA detects apk packages when it scans a container image.

{% callout type="info" %}
apk packages are detected only during **container scanning**, not during a normal `fossa analyze` of a source repository.
{% /callout %}

## How FOSSA identifies apk packages

A detected apk package is identified by its name, the Alpine distribution and version, its architecture, and its package version. Alpine versions are normalized to `major.minor` (for example, `3.15`), so packages from `3.15.2` and `3.15.4` resolve against the same Alpine release line.

Licenses for apk packages are resolved from FOSSA's Knowledge service using each package's declared-license metadata, rather than being read out of the image at scan time. Alpine packages generally include complete license information.

## Discovery

FOSSA looks for a file named `installed` under any `**/apk/**` path in the image, the apk installed-package database.

## Analysis

FOSSA parses the database and reports each package's name, version, and architecture. For example, this record:

```text
C:Q1Deb0jNytkrjPW4N/eKLZ43BwOlw=
P:musl
V:1.2.2-r7
A:x86_64
S:383152
I:622592
T:the musl c library (libc) implementation
U:https://musl.libc.org/
L:MIT
o:musl
m:Timo Teräs <timo.teras@iki.fi>
t:1632431095
```

is reported as the dependency `musl` at version `1.2.2-r7` for architecture `x86_64`. The package release suffix (`-r7`) is preserved, which matters for vulnerability matching: Alpine backports security fixes into new releases of the same version.

## FAQ

### How do I only analyze apk packages?

Specify the `apkdb` analysis target in a `.fossa.yml` file to exclude all other targets:

```yaml
# .fossa.yml
version: 3
targets:
  only:
    - type: apkdb
```

---

Source: https://docs.fossa.com/docs/project-setup/supported-languages/system/dpkg

# dpkg

The Debian Package Manager (**dpkg**) installs system packages on Debian and Ubuntu images. FOSSA detects dpkg packages when it scans a container image.

{% callout type="info" %}
dpkg packages are detected only during **container scanning**, not during a normal `fossa analyze` of a source repository.
{% /callout %}

## How FOSSA identifies dpkg packages

A detected dpkg package is identified by its name, the distribution (Debian or Ubuntu) and version, its architecture, and its package version. Debian and Ubuntu versions are normalized to the major version. Licenses are resolved from FOSSA's Knowledge service using each package's declared-license metadata; Debian and Ubuntu packages generally include complete license information.

## Discovery

FOSSA looks for a file named `status` or `status.d` under `**/var/lib/dpkg/*`, the dpkg installed-package database.

## Analysis

FOSSA parses the database and reports each package's name, version, and architecture. For example, this record:

```text
Package: bash
Status: install ok installed
Priority: required
Section: shells
Installed-Size: 6512
Maintainer: Matthias Klose <doko@debian.org>
Architecture: arm64
Multi-Arch: foreign
Version: 5.1-2+deb11u1
Depends: base-files (>= 2.1.12), debianutils (>= 2.15)
Description: GNU Bourne Again SHell
Homepage: http://tiswww.case.edu/php/chet/bash/bashtop.html
```

is reported as the dependency `bash` at version `5.1-2+deb11u1` for architecture `arm64`. The Debian revision (`-2+deb11u1`) is preserved, which matters for vulnerability matching: Debian and Ubuntu backport security fixes into new revisions of the same upstream version.

## FAQ

### How do I only analyze dpkg packages?

Specify the `dpkgdb` analysis target in a `.fossa.yml` file to exclude all other targets:

```yaml
# .fossa.yml
version: 3
targets:
  only:
    - type: dpkgdb
```

---

Source: https://docs.fossa.com/docs/project-setup/supported-languages/system/rpm

# rpm

The RPM Package Manager (**rpm**) installs system packages on RHEL, Fedora, CentOS, and Oracle Linux. FOSSA detects RPM packages when it scans a container image, and can additionally analyze RPM **SPEC files** found in a source repository.

{% callout type="info" %}
RPM database detection runs during **container scanning**. RPM SPEC file analysis runs during a normal `fossa analyze` of a source repository. See [Analyzing RPM SPEC files](#analyzing-rpm-spec-files) below.
{% /callout %}

## Container scanning

### How FOSSA identifies RPM packages

A detected RPM package is identified by its name, the distribution and version, its architecture, and its version (including the epoch and release where present). Red Hat Enterprise Linux (RHEL), CentOS, and Oracle Linux are supported; Fedora is in beta. RHEL-family versions are normalized to the major version (for example, `9`). The package release is preserved, which matters for vulnerability matching, since security fixes are backported into new releases of the same version.

### Discovery

An RPM installation may use one of several database backends. FOSSA looks for each:

- **BerkeleyDB**: a file named `Packages` under `var/lib/rpm`.
- **NDB**: a file named `Packages.db` under `**/rpm/**`.
- **SQLite**: a file named `Packages.sqlite` or `rpmdb.sqlite` under `var/lib/rpm`.

Each backend shares a common record format; only the method of listing packages differs.

### Analysis

FOSSA parses the database and reports each package's name, version, architecture, and (optionally) epoch.

### License identification on RHEL and Oracle Linux

{% callout type="warning" %}
FOSSA resolves licenses for system packages from its Knowledge service rather than reading them out of the package database at scan time. For RHEL and Oracle Linux RPM packages this license data is often incomplete, so packages such as `bash`, `perl`, or `coreutils` may be reported as **unlicensed** even though license metadata exists in the RPM database.

Alpine (apk) and Debian/Ubuntu (dpkg) packages, by contrast, include complete license information.

**Workaround:** license affected packages manually in the FOSSA web app. Broader RHEL/Oracle Linux license coverage is on the roadmap, contact [support@fossa.com](mailto:support@fossa.com) if this is important to you.
{% /callout %}

## Analyzing RPM SPEC files

Outside of container scanning, FOSSA can analyze RPM **SPEC files** in a source repository to determine runtime dependencies (the `rpm-spec` strategy). RPM packages managed by `dnf` and `yum` are built from SPEC files.

| Strategy | Direct Deps | Transitive Deps | Edges | Tags | Container Scanning |
| :-- | :-- | :-- | :-- | :-- | :-- |
| rpm-spec | ✅ | ❌ | ❌ | Environment | ✅ |

**Discovery**: FOSSA scans any file with a `.spec` extension (SPEC files follow the strict `<package-name>.spec` naming convention, e.g. `binutils.spec`).

**Analysis**: FOSSA reads lines beginning with `Requires:` followed by whitespace and extracts exactly one package per line, with an optional single version constraint. Each is treated as a direct, runtime dependency.

{% callout type="warning" %}
The `rpm-spec` strategy does not yet support:
- Combinatoric version constraints such as `(>= 1.2 and != 1.4) or = 0.9` (parentheses and `and`/`or` constructs).
- Build-time requirements (`BuildRequires:`). These are parsed but not reported, since many are toolchain dependencies like `gcc`.
- Macros such as `xxxxxx-%{?_isa}` or `xxxxx = %{version}-%{release}`.
{% /callout %}

## FAQ

### How do I only analyze RPM targets?

Specify the relevant RPM analysis targets in a `.fossa.yml` file to exclude all others:

```yaml
# .fossa.yml
version: 3
targets:
  only:
    - type: ndb
    - type: berkeleydb
    - type: sqlitedb
```

---

Source: https://docs.fossa.com/docs/project-setup/scan-frequency

# Scan Frequency

By default, FOSSA scans a project when new code is pushed. Scheduled scans run independently of commits, useful for surfacing newly disclosed CVEs, updated license data, or policy changes against your existing dependencies without waiting for the next code change.

Scan frequency is configured via **update hooks**. Settings live at **Organization Settings > Projects > Update Hooks** for org-wide defaults, and can be overridden per-project in **Project Settings > Update Hooks**.

{% steps %}
{% step title="Enable update hooks" %}
Toggle **Enable update hooks** on. Scheduled scanning is off by default.
{% /step %}
{% step title="Set the frequency" %}
Configure how often scans run:

| Setting | Options |
|---|---|
| **Update every** | Any positive integer combined with **Hour(s)**, **Day(s)**, or **Week(s)** |
| **Update time** | Time of day in 30-minute increments, only available when the interval unit is **Day(s)** |

The default is every **2 Days** at **12:00 AM**.
{% /step %}
{% step title="Save and propagate" %}
Click **Save**. To apply the new defaults to existing projects, click **Propagate**.
{% /step %}
{% /steps %}

## What's next

- **[Automatic Updates](/docs/project-setup/automatic-updates)**: Learn how FOSSA re-builds and re-scans projects on commit, schedule, or CI pipeline triggers.
- **[Issue Scanners](/docs/project-setup/issue-scanners)**: Configure which types of issues trigger notifications and gate your CI/CD builds.

---

Source: https://docs.fossa.com/docs/project-setup/notifications

# Notifications

FOSSA can notify your team when a scan completes and new issues are found, via email or Slack. Notifications are triggered by new issue detection, whether from a code push, a scheduled scan, or a manual rescan.

The same notification settings are available at two scopes:

- **Organization defaults**: **Organization Settings > Projects > Notifications**, applied automatically to all new projects

  {% img src="/images/project-setup/notifications-org-settings.png" alt="Organization Settings Default Notification Settings panel with Propagate settings button" /%}

- **Per-project overrides**: **Project Settings > Notifications**, overrides the org default for a specific project

  {% img src="/images/project-setup/notifications-project-settings.png" alt="Project Settings Notifications panel showing email and Slack notification toggles" /%}

Changes to org defaults can be propagated to existing projects using the **Propagate** button.

## Email notifications

Email notifications send a summary when new issues are detected in a project scan.

Toggle **Enable email notifications** on, then choose who receives the emails:

| Recipient option | Description |
|---|---|
| **Only me** | Sends to the currently logged-in user only |
| **Organization** | Sends to all members of the organization |
| **Custom** | Sends to a specific list of users you select |

## Slack notifications

Slack notifications post a message to a configured Slack channel when new issues are detected.

Toggle **Enable Slack notifications** on. Slack must be connected before this option takes effect. Set it up at **Settings > Integrations > Slack**.

---

Source: https://docs.fossa.com/docs/project-setup/issue-scanners

# Issue Scanners

Issue scanners control which categories of issues FOSSA detects and reports for your projects. Each scanner (Licensing, Security, and Quality) is configured independently with its own policy, CI/CD gating, and sub-scanning options.

Organization-level defaults live at **Organization Settings > Projects > Issues** and apply to all new projects. Settings can be overridden per-project at **Project Settings > Issue Policies**.

## Per-scanner settings

Each scanner has the same set of controls:

| Setting | Description |
|---|---|
| **Scan for Issues** | Enables or disables issue detection for this category on new projects |
| **Default policy** | The policy applied to new projects for this scanner. Determines which issues are flagged based on the rules you've configured. |
| **Fail CI/CD checks** | When enabled, fails the CI/CD status check if issues matching the filter are found |
| **CI/CD filter** | Scopes which issues trigger the CI/CD failure. Only active when Fail CI/CD checks is on. |

## Licensing

The licensing scanner identifies open source license compliance issues across your project's dependencies. For each dependency, FOSSA detects declared and discovered licenses, compares them against your licensing policy, and raises an issue when a dependency is denied, flagged, or missing required attribution.

Common reasons for a licensing issue:
- A dependency uses a license explicitly denied by your policy (e.g. GPL in a proprietary product)
- A dependency's license is flagged for review or is unresolved
- Required attribution or copyright notices are missing

Licensing issues appear regardless of whether the vulnerability or quality scanners are enabled, and can independently gate CI/CD builds.

{% img src="/images/project-setup/issue-scanners-policies.png" alt="Project Settings Issue Policies panel showing Licensing scanner controls including Scan for Issues toggle, Default policy dropdown, Fail CI/CD checks, and CI/CD filter" /%}

## Security

The security scanner detects known vulnerabilities (CVEs) in your dependencies and evaluates them against your security policy. FOSSA matches each dependency against its vulnerability database (sourced from NVD, GitHub Advisories, and other feeds) and raises issues for CVEs that meet or exceed the severity threshold defined in your active security policy.

Common reasons for a security issue:
- A dependency has a CVE at or above your policy's minimum severity threshold
- A vulnerability's CWE matches a deny rule in your policy
- A CVE is present and no fix is available (flagged as a known risk)

Security issues support the full ignore and triage workflow (including VEX justifications when exporting SBOMs) and can independently gate CI/CD builds.

{% img src="/images/project-setup/issue-scanners-security.png" alt="Project Settings Issue Policies panel showing Security scanner controls including Scan for Issues toggle, Default security policy dropdown, Fail CI/CD checks, and CI/CD filter" /%}

## Quality

The quality scanner evaluates the health and maintenance status of your dependencies and raises issues when packages fall below the thresholds set in your quality policy. This includes dependencies that have been abandoned, are significantly out of date, or exhibit other signals of poor maintenance.

Common reasons for a quality issue:
- A dependency is classified as abandonware, no meaningful activity for an extended period
- A dependency is a configurable number of major, minor, or patch versions behind the latest release
- A dependency has other quality risk signals such as lack of active maintainers

Quality issues help teams stay ahead of future security and compatibility risk before a CVE appears in an old, unmaintained package.

{% img src="/images/project-setup/issue-scanners-quality.png" alt="Project Settings Issue Policies panel showing Quality scanner controls with Scan for Issues toggle off and grayed-out controls" /%}

See [Understanding Quality Issues](/docs/quality/understanding-quality-issues) for a breakdown of each quality issue type, and [Quality Policies](/docs/policies/quality-policy) to configure detection thresholds.

## Snippet scanning

Snippet scanning extends all three scanners to detect license and vulnerability matches in vendored or copy-pasted code fragments; source code that has been directly embedded in your repository rather than declared as a dependency.

See [Snippet Scanning](/docs/cli/features/snippet-scanning) for configuration details.

## Vendored dependency scanning

Vendored dependency scanning extends all three scanners to analyze dependencies that have been checked directly into your repository (e.g. a `vendor/` directory) rather than managed through a package manager.

See [Vendored Dependencies](/docs/cli/features/vendored-dependencies) for configuration details.

## What's next

- **[Licensing Policies](/docs/policies/licensing-policies)**: Define which licenses are approved, flagged, or denied for your organization.
- **[Security Policy](/docs/policies/security-policy)**: Set severity thresholds and rules that determine which vulnerabilities trigger issues.
- **[Quality Policy](/docs/policies/quality-policy)**: Configure thresholds for package health and maintenance status issues.

---

Source: https://docs.fossa.com/docs/project-setup/privacy-settings

# Privacy Settings

A FOSSA project can be **Public** or **Private**. Public projects and their compliance reports are accessible without authentication; anyone with the link can view them. Private projects are only accessible to authenticated members of your organization.

## Setting the organization default

The default visibility for new projects is configured at **Organization Settings > Projects > General** under the **Privacy** section.

| Option | Behaviour |
|---|---|
| **None** | No default is enforced, each project retains whatever visibility it was created with |
| **Public** | New projects default to public |
| **Private** | New projects default to private |

{% img src="/images/project-setup/privacy-settings-org-default.png" alt="Organization Settings Default General Settings page showing the Privacy section with Default Project Privacy dropdown set to None and a Propagate settings button" /%}

Click **Save** to apply. Use **Propagate** to push the new default to existing projects.

## Changing visibility per project

Project visibility is changed at **Project Settings > General**, in the **Danger Zone** section, using the **Project Visibility** dropdown.

{% callout type="warning" %}
Changing project visibility requires project maintainer permissions. FOSSA will prompt for confirmation before applying the change. You must still save after confirming.
{% /callout %}

{% img src="/images/project-setup/project-settings-danger-zone.png" alt="Danger Zone section showing Project Visibility dropdown with Public and Private options, and the Delete project button" /%}

---

Source: https://docs.fossa.com/docs/project-setup/build-history

# Build History and Rebuilding

Every time FOSSA analyzes a project it creates a revision, a point-in-time snapshot of the dependency graph. The build history lets you navigate between revisions and see what changed over time.

## Viewing build history

Open the revision selector dropdown in the project navigation bar. It lists all past revisions for the project, each showing:

- The revision identifier (commit hash for Git-backed projects, or timestamp for CLI uploads)
- Branch or tag reference
- Source, automated (FOSSA-triggered) or CLI (uploaded via `fossa analyze`)
- CI/CD check status, if GitHub status checks are configured

You can search and filter revisions by branch, tag, or source.

{% img src="/images/project-setup/build-history-project-summary.png" alt="Project summary page with the revision selector dropdown open, showing a searchable list of past revisions" /%}

## Triggering a rebuild

**From the Actions menu**. Open **Actions > Rebuild & Mediate Deps** from the project summary page. This re-runs the full dependency analysis for the current revision using fresh data from FOSSA's knowledge API. This option is only available for Quick Import projects and requires Edit permission.

**From an unanalyzed revision**; if a revision shows as unanalyzed, an **Analyze this version** button appears on its card. Click it to trigger analysis for that specific revision. Requires Edit permission.

## Running a policy scan

A policy scan re-evaluates the current revision's existing dependency data against your active policies, without re-analyzing dependencies. This is useful after changing a policy and wanting to see updated issue results immediately.

Click **Run policy scan** on the project summary page. This is available for all project types, including CI/CD scanning projects.

{% img src="/images/project-setup/build-history-policy-scan.png" alt="Project summary page showing the Last policy scan timestamp and the Run policy scan link next to the issue count" /%}

---

Source: https://docs.fossa.com/docs/project-setup/mediated-dependencies

# Mediated Dependencies

Most build graphs contain transitive dependencies that appear more than once at different required versions. When this happens, the build tool applies a resolution algorithm to select a single version, a process known as **dependency mediation**.

## How package managers mediate versions

The version selected for a shared transitive dependency varies by ecosystem:

| Ecosystem | Resolution strategy |
|---|---|
| Maven | Nearest-wins, the version declared closest to the root of the dependency tree is selected |
| Gradle | Highest-wins by default, the highest requested version across all constraints is selected |
| npm / yarn | Historically nested (each package gets its own copy); modern lockfiles consolidate to a single version where possible |
| Go modules | Minimum version selection, the lowest version that satisfies all constraints |

For example, if your project depends on library A and library B, and both require different versions of library C, the package manager picks one version of C based on its algorithm. That selected version is the mediated dependency, the one actually present in your build.

## How FOSSA captures mediated dependencies

The accuracy of FOSSA's dependency graph depends on how the project is analyzed:

**CI/CD scanning** (`fossa analyze`); the FOSSA CLI runs inside your existing build environment and captures the dependency graph after the build tool has already resolved all version conflicts. FOSSA receives the exact set of mediated versions that your build tool selected. This is the most accurate method.

**Quick Import** (FOSSA reconstructs the dependency graph by reading package manifest files (e.g. `pom.xml`, `package.json`, `go.mod`). Because FOSSA applies its own resolution logic rather than running your build tool directly, the mediated versions it selects may differ from what your actual build produces) particularly for complex graphs with many conflicting constraints.

## Why it matters

The version of a dependency that ends up in your build determines which licenses apply and which CVEs are relevant. If FOSSA's resolved graph differs from your actual build graph, you may see issues for versions you don't actually use, or miss issues for versions you do.

Using CI/CD scanning eliminates this class of false positives by ensuring FOSSA analyzes the same dependency graph that your build tool produced.

---

Source: https://docs.fossa.com/docs/release-groups

# Release Groups

A **release group** collects multiple projects into a single logical unit, for example, all the services that ship together as one product release. Within a release group, each named **release** pins the exact revision of every project that was included at that point in time.

## Key concepts

**Release group**, the named collection of projects. Think of it as the product or product line. A release group persists across time and accumulates releases as you ship.

**Release**, a named snapshot within a group. Each release locks specific revisions (branches or commits) of each member project, so the compliance picture is reproducible. Every release group has at least one release.

## Why use release groups

- **Unified reporting**: see licenses, vulnerabilities, and quality issues across every project in a release at once, and generate combined reports covering the whole product.
- **Shared policy**: apply the same licensing, security, and quality policies consistently to every project in the release.
- **Reproducible results**: pinning exact revisions means the same release always returns the same compliance result, regardless of what's been pushed since.

## When to use them

Release groups work well when you ship multiple projects together as a coherent product, want to apply a single compliance policy to an entire service or application layer, or need to demonstrate that a specific release met your compliance requirements at a point in time.

If you have one project or are doing exploratory scanning, a release group adds overhead without benefit. Use projects directly.

## Navigating a release group

Once inside a release group, a tab bar gives access to everything for the selected release. Switch releases at any time using the release selector in the header, all tabs except **Releases** and **Settings** reflect the currently selected release.

| Tab | What it shows |
|---|---|
| **Summary** | Project, dependency, and license counts for the selected release, plus quick links to generate reports |
| **Projects** | The list of projects pinned in the selected release |
| **Issues** | Licensing, security, and quality issues aggregated across all projects in the release |
| **Inventory** | The full list of dependencies across all projects in the release |
| **Licenses** | License breakdown across the release, with an obligations panel |
| **Reports** | Generate licensing, vulnerability, SBOM, and remediation guidance reports |
| **Releases** | Create, edit, clone, and delete releases (group-level, not release-specific) |
| **Settings** | Configure the group title, policies, report defaults, and portal visibility |

---

Source: https://docs.fossa.com/docs/release-groups/creating

# Creating a Release Group

## Creating a release group

{% steps %}
{% step title="Open the Release Groups page" %}
From the **Projects** dashboard, select the **Release Groups** tab, then click **New Release Group**.

{% img src="/images/release-groups-creating-dashboard.png" alt="Release Groups tab on the Projects dashboard with the New Release Group button" /%}
{% /step %}
{% step title="Name your first release" %}
Enter a title for the first release, for example, `v1.4.0` or `2024-Q3`. This names the initial release snapshot, not the group itself. You'll name the group in settings after creation.

{% img src="/images/release-groups-creating-name-release.png" alt="Name and Version fields for the first release" /%}
{% /step %}
{% step title="Add projects" %}
Browse or search your projects and click **Add** on each one you want to include. Use **Add All** to bulk-add everything matching the current filters.

For each project you add, select the **branch** and **revision** to pin. The revision is what will be evaluated for compliance. Choose the commit or tag that corresponds to this release.

{% img src="/images/release-groups-creating-add-projects.png" alt="Projects list with Add buttons for adding projects to the release group" /%}
{% /step %}
{% step title="Assign teams (optional)" %}
Select one or more teams to assign to the release group. FOSSA applies the selected teams to every project you add, bulk-assigning team ownership across the entire release in one step. You can skip this and manage team access later.

{% img src="/images/release-groups-creating-assign-teams.png" alt="Teams selector for assigning teams to the release group" /%}
{% /step %}
{% step title="Assign policies (optional)" %}
Choose a licensing, security, or quality policy to apply across the group. You can also do this later from the group's settings. See [Settings](/docs/release-groups/settings) for details.

{% img src="/images/release-groups-creating-assign-policies.png" alt="Licensing, Security, and Quality policy selectors" /%}
{% /step %}
{% step title="Save the group" %}
Click **Create**. FOSSA creates the group with your first release and redirects you to the group overview.

{% img src="/images/release-groups-creating-save.png" alt="Create release group header with the Create button" /%}
{% /step %}
{% /steps %}

{% callout type="info" %}
The group title is set in **Settings → General** after creation, the creation flow names the first release, not the group itself.
{% /callout %}

## Editing a release group

To change which projects belong to a release or update their pinned revisions, go to the **Releases** tab, find the release, and click **Edit**. You can add and remove projects, and change the branch or revision pinned for each one.

To rename the group or change its policies, go to **Settings → General**.

## Deleting a release group

Deleting a release group removes it and all its releases. Projects within the group are unaffected; they remain in FOSSA as standalone projects.

---

Source: https://docs.fossa.com/docs/release-groups/releases

# Managing Releases

A **release** is a named, pinned snapshot of the projects in a release group. Each release locks a specific revision of every member project, making the compliance result reproducible; the same release always reflects the same code.

## The Releases tab

Open a release group and click **Releases** to see all releases for that group. Each row shows the release title and when it was created. From here you can clone a release into a new one, edit an existing release, or delete one.

{% img src="/images/release-groups-releases-tab.png" alt="Releases tab of a release group showing each release's title and creation date with edit, clone, and delete actions" /%}

{% callout type="info" %}
Every release group must have at least one release. The delete button is disabled on the last remaining release.
{% /callout %}

## Cloning a release

Cloning is how you add a new release to a group. It copies an existing release's project list and pinned revisions as a starting point, so you adjust only what changed rather than rebuilding the project list from scratch. (The group's very first release is created with the group itself. See [Creating a Release Group](/docs/release-groups/creating).)

From the **Releases** tab, click **Clone** on the release you want to copy. Name the new release (e.g. `v2.0.0`), select the projects and revisions to include, then save. Projects are drawn from the same pool as the rest of the group.

{% img src="/images/release-groups-clone-release.png" alt="Clone release form with the version field and per-project branch and revision selectors" /%}

## Editing a release

Click **Edit** on any release to change its name, add or remove projects, or update the pinned branch and revision for any member project.

{% img src="/images/release-groups-edit-release.png" alt="Edit release form showing the version field and a project's branch and revision pinned for the release" /%}

{% callout type="warning" %}
Editing a release's pinned revisions changes what FOSSA evaluates. If you need a permanent record of a release's compliance state, generate a report before editing. See [Settings](/docs/release-groups/settings).
{% /callout %}

## Switching between releases

From any release group view (summary, issues, inventory), a release selector in the header lets you switch which release's data you're viewing. **Settings** and the **Releases** tab are group-level. They are not scoped to the selected release.

{% img src="/images/release-groups-releases-summary.png" alt="Release group Summary tab showing the release selector in the header, issue count with Run policy scan link, and the Actions panel" /%}

## Scanning a release

FOSSA scans a release when it is first created. To trigger a fresh analysis (for example after a policy change or to pick up updated vulnerability data) click **Scan Release** from the **Summary** tab.

Scans run against the exact revisions pinned in the release. Because revisions are fixed, a rescan reflects changes in FOSSA's data (updated vulnerability feeds, new license detections) rather than changes to your code.

## Scan history

Every scan of a release is recorded. From the **Summary** tab, a scan history selector lets you switch between past scans and view the compliance state at each point in time. This is useful for auditing: you can show what the release looked like at a specific date without modifying the current state.

{% callout type="info" %}
When generating a report, FOSSA uses the most recent scan by default. To generate a report against a specific historical scan, select that scan from the history selector before generating.
{% /callout %}

---

Source: https://docs.fossa.com/docs/release-groups/issues

# Issues

The **Issues** tab works the same as on an individual project (same issue types, same policy-driven rules) but aggregates results from every project pinned in the selected release. See [Licenses](/docs/licenses) and [Vulnerabilities](/docs/vulnerabilities) for how FOSSA detects and evaluates issues.

What's different at the release group level:

- **Cross-project aggregation**: a single view of all outstanding issues across the entire product, not per-project.
- **Each issue links back to its source**: click any issue to see which project and dependency it came from.
- **Release-scoped**: the issue list reflects the pinned revisions in the selected release. Switch releases in the header to compare compliance posture across versions.

{% img src="/images/release-groups-issues-tab.png" alt="Release group Issues tab showing 49 aggregated licensing issues across all pinned projects, with Active and Ignored tabs, filter panel, and the FOSSA Docs Release Group v2.0.0 header" /%}

## Sub-tabs

Issues are split by policy type. Which sub-tabs appear depends on which policies are assigned to the group in [Settings → General](/docs/release-groups/settings):

| Sub-tab | Shown when |
|---|---|
| **Licensing** | Always |
| **Security** | A security policy is assigned |
| **Quality** | A quality policy is assigned |

If only a licensing policy is assigned, the tab shows a flat list rather than a dropdown.

## Issue counts

Issue counts appear on the **Issues** tab badge and the **Summary** tab. They update when you switch releases or scan history. Use those selectors to compare issue counts across releases or points in time.

---

Source: https://docs.fossa.com/docs/release-groups/inventory

# Inventory & Licenses

The **Inventory** and **Licenses** tabs work the same as on an individual project but aggregate across every project pinned in the selected release. See [Licenses](/docs/licenses) for how FOSSA detects licenses and evaluates obligations.

What's different at the release group level:

- **Unified bill of materials**: all dependencies from all member projects in one view, not separated by project.
- **Cross-project filtering**: filter by project to isolate one member's dependencies, or leave unfiltered to see the full release inventory.
- **Shared dependencies are deduplicated**: a dependency that appears in multiple projects is listed once, with a count of how many projects include it.

## Inventory tab

Shows every third-party dependency across all pinned projects. Use it to browse the full component list for the release, filter by license or package type, or identify which dependencies span multiple projects.

{% img src="/images/release-groups-inventory-tab.png" alt="Release group Inventory tab showing 17 dependencies with package locators, license detections, and project links, alongside a filter panel for depth, status, and package manager" /%}

## Licenses tab

Shows a breakdown of every license present across the release. Clicking a license shows the dependencies that carry it.

### Obligations panel

An **Obligations** panel alongside the license list surfaces the aggregated legal obligations for the release (attribution requirements, source disclosure, copyleft terms, and so on) derived from every license detected across all pinned revisions.

{% callout type="info" %}
The obligations panel summarizes what the detected licenses require. For authoritative compliance decisions, consult your legal team alongside FOSSA's issue and policy results.
{% /callout %}

{% img src="/images/release-groups-licenses-tab.png" alt="Release group Licenses tab showing 11 licenses found starting with direct dependencies, alongside an Obligations panel listing 6 obligations including Disclose Source, Include Copyright, and Include License" /%}

Both tabs reflect the currently selected release. Use the release selector in the header to compare inventory or license composition across versions of the product.

---

Source: https://docs.fossa.com/docs/release-groups/reports

# Reports

Release group reports produce the same output as project-level reports (same formats, same content structure) but aggregate data from every project pinned in the selected release into a single document. See [Reports](/docs/reports) for format details and what each report type contains.

Open **Reports** in the release group navigation, or use the **Summary** tab quick-action links, then choose a report type from the sidebar. The available types are **Licensing**, **SBOM**, **Vulnerabilities**, and **Remediation Guidance**.

{% img src="/images/release-groups-reports-page.png" alt="Release group Reports page showing the Licensing report selected, with a sidebar listing Licensing, SBOM, and Remediation Guidance report types, and a two-step generation workflow with Standard and Custom options" /%}

{% callout type="info" %}
Vulnerability reports require a security policy to be assigned to the group. Remediation Guidance reports additionally require that not all projects in the release are binary projects.
{% /callout %}

## What's different at the release group level

- **Combined output**: one report covering all member projects, not one per project.
- **Generate against a historical scan**: to report on the release's state at a specific point in time, select that scan from the scan history selector on the **Summary** tab before generating.
- **Default saved options**: configure default filter presets for Licensing and SBOM reports so users see pre-filtered results when they open the report. Set these in [Settings → Reports](/docs/release-groups/settings).
- **SBOM author defaults**: set default author name, email, and supplier metadata for SBOM reports generated from this group, also in [Settings → Reports](/docs/release-groups/settings).

---

Source: https://docs.fossa.com/docs/release-groups/settings

# Release Group Settings

Release group settings are group-level; they apply to all releases within the group. Access them from the **Settings** tab inside a release group.

## General

### Title

Set or rename the release group title. This name appears across the FOSSA UI, in reports, and in any shared portal links.

### Policies

Assign a policy for each issue type. Policies determine which license, security, and quality issues are flagged across all projects in the group.

| Policy type | What it controls |
|---|---|
| **Licensing** | License obligations and restriction rules |
| **Security** | Vulnerability severity thresholds |
| **Quality** | Code quality issue rules |

Policies set on the release group take precedence over any individual project policies for issues evaluated in the group context. For more on how policies work, see [Policies](/docs/policies).

{% img src="/images/release-groups-settings-general.png" alt="Release group General Settings page showing the Release Group Title field and Licensing, Security, and Quality policy dropdowns" /%}

## Reports

Configure defaults that apply when generating reports from this release group.

### Logo and description

Upload a logo and write a description to include in generated reports. The description supports plain text and appears on the report cover.

### Default saved options

Set a default saved filter option for **Licensing** and **SBOM** reports. When a user opens the report, the selected filter is pre-applied. Leave blank to show all results by default.

### SBOM author defaults

Set default author and supplier metadata for SBOM reports generated from this group. Individual users can override these at report generation time.

| Field | Description |
|---|---|
| **Author Name** | Name of the person or team authoring the SBOM |
| **Author Email** | Contact email for the SBOM author |
| **Supplier** | Organization supplying the software described in the SBOM |

{% img src="/images/release-groups-settings-reports.png" alt="Release group Settings Reports page showing Logo upload, Description editor with Markdown support, and Saved Options for default Licensing report filters" /%}

## Portal

The **Portal** setting controls whether this release group's results are accessible via a shareable public link, useful for sharing compliance status with customers or external stakeholders without granting FOSSA account access.

Toggle **Public on Portal** to enable. When public, anyone with the portal link can view the release group's compliance summary. When private, the link requires authentication.

{% callout type="info" %}
Use portal tokens to grant scoped, authenticated access to the portal without full FOSSA accounts. Manage tokens from the Portal settings tab.
{% /callout %}

---

Source: https://docs.fossa.com/docs/release-groups/permissions

# Permissions

Release groups have their own permission model, separate from project-level permissions. Permissions can be scoped to a specific release group or granted across all release groups in the organization.

## Permission types

| Permission | What it controls |
|---|---|
| **Edit group** | Rename the group, manage its releases, delete the group |
| **Create/edit releases** | Create, edit, clone, and delete releases within the group |
| **Set licensing policy** | Assign or change the licensing policy for the group |
| **Set security policy** | Assign or change the security policy for the group |
| **Set quality policy** | Assign or change the quality policy for the group |
| **Generate reports** | Generate licensing, vulnerability, SBOM, and remediation guidance reports |

## Settings tab visibility

The **Settings** tab is shown to any user who has at least one of the following permissions for the group: edit group, set licensing policy, set security policy, or set quality policy. Users who can only generate reports do not see the Settings tab.

## Org-wide vs group-specific

Each permission type comes in two scopes:

- **Group-specific**: applies to one named release group only.
- **Org-wide**: applies to all release groups in the organization (e.g. a compliance team that manages policy across every product).

## Team-based access

Release groups can be assigned to teams during creation or from **Settings → General**. Team members inherit access to the release group based on their role within the team.

For a full overview of how FOSSA's permission model works, see [Organization Management](/docs/organization-management).

---

Source: https://docs.fossa.com/docs/issues

# Issues

Issues are the findings FOSSA surfaces when a project's dependencies conflict with your policies or contain known vulnerabilities. Every issue has a type, a source (the dependency that caused it), and a state, active, ignored, or remediated.

## Issue types

| Type | What it flags | Requires |
|---|---|---|
| **Licensing** | Dependencies that violate or are flagged by your license policies | Always available |
| **Security** | Dependencies with known vulnerabilities | Security feature enabled |
| **Quality** | Outdated, blocked, or risky dependencies | Quality feature enabled |

## What this section covers

- **[Global Issue Summary](/docs/issues/global-summary)**: org-wide dashboard tracking issue trends, KPI cards, history graph, and breakdowns across all projects
- **[Ignoring Issues](/docs/issues/ignoring-issues)**: when and how to suppress issues, choosing the right scope and version coverage
- **[Comparing Issues](/docs/issues/comparing-issues)**: diff two revisions to see what's new, remediated, or unchanged

For reviewing and resolving issues within a specific type, see [Licenses](/docs/licenses), [Vulnerabilities](/docs/vulnerabilities), or [Quality](/docs/quality).

---

Source: https://docs.fossa.com/docs/issues/global-summary

# Global Issue Summary

The **Global Issue Summary** (also called the Issue Overview) is an org-wide dashboard that aggregates licensing, security, and quality issues from every project in your organization. Use it to understand your overall compliance posture, track whether your issue count is trending up or down, and identify which issue types are driving risk.

It can also be scoped to a single project: the same view appears within a project's **Issue Overview** tab, showing only that project's data.

{% img src="/images/issues-global-summary-overview.png" alt="Global Issue Summary dashboard showing four KPI cards for Total Issues, Total Active Issues, Total Ignored Issues, and Total Remediated Issues, with a stacked history graph below spanning May to June 2026" /%}

{% callout type="info" %}
The Issue Summary is built from daily snapshots. Data reflects the previous night's scan results and updates once every 24 hours.
{% /callout %}

## Scope

The dashboard operates in two modes:

| Mode | Where to find it | What it shows |
|---|---|---|
| **Global** | Main navigation → **Issues** | All projects across your organization |
| **Project** | Inside a project → **Issue Overview** tab | That project only, on its latest revision of the default branch |

{% callout type="info" %}
When viewed from a project, the Issue Summary is only available for the **latest revision of the default branch**. Older revisions and non-default branches show a prompt to switch.
{% /callout %}

## Filters

The filter bar at the top of the dashboard controls what data is shown throughout, KPI cards, history graph, and breakdowns all respond to the active filters.

| Filter | Description |
|---|---|
| **Issue type** | Narrow to Licensing, Security, or Quality issues only |
| **Project labels** | Filter to projects tagged with specific labels (global view only) |
| **Teams** | Filter to projects belonging to specific teams (global view only) |
| **Date range** | Set a historical window to analyze, defaults to the last **30 days** |

## KPI cards

Four cards summarize your current issue state at the end of the selected date range, each showing the count and the change (delta) from the start of the period:

| Card | What it counts |
|---|---|
| **Total Issues** | All issues in all states, active, ignored, and remediated combined |
| **Total Active** | Issues currently open and requiring attention |
| **Total Ignored** | Issues you've accepted or marked as not applicable |
| **Total Remediated** | Issues no longer present in the latest revision, resolved through a dependency update, removal, or an update to FOSSA's vulnerability database |

{% callout type="info" %}
KPI card totals count an issue once per project. If the same CVE affects five projects, it counts as five. The **Licensing**, **Security**, and **Quality** tabs deduplicate; each distinct issue is counted once regardless of how many projects it affects.
{% /callout %}

## Issue history graph

The history graph shows how your issue counts changed across the selected date range. Three stacked data series show the breakdown at each point in time:

- **Active**: issues requiring attention
- **Ignored**: issues marked as accepted or suppressed
- **Remediated**: issues automatically resolved

Read the graph to see whether active issues are growing, shrinking, or stable, and whether remediations are keeping pace with new issues coming in.

## Issue breakdown

Below the graph, the dashboard breaks down **new** issues by category. Only the categories enabled for your organization appear:

{% img src="/images/issues-global-summary-breakdown.png" alt="Issue breakdown showing three panels: 1067 new licensing issues broken down by Denied and Flagged, 2240 new security issues broken down by Critical through Unknown severity, and 0 new quality issues" /%}

### Licensing
Always shown. Breaks down new licensing issues by type:
- **Policy Conflict**: dependencies that violate your policy rules
- **Policy Flag**: dependencies flagged for review
- **Unlicensed Dependency**: dependencies with no detected license

### Security
Shown when the Security feature is enabled. Breaks down new vulnerability issues by severity:
- Critical, High, Medium, Low, Unknown

### Quality
Shown when the Quality feature is enabled. Breaks down new quality issues by type:
- **Blocked Dependencies**: dependencies prohibited by your quality policy
- **Outdated Dependencies**: dependencies behind the version threshold
- **Risk indicators**: abandonware, native code, empty packages

## Exporting

Click **Export** to generate a report of the current view. The export is processed as a background job and **emailed to you** when ready; you don't need to stay on the page.

The export reflects the active filters at the time you click Export, so filter to the scope you need before exporting.

## Access

The Global Issue Summary requires view permission for at least one issue type. Security and Quality sections are hidden unless those features are enabled for your organization. The dashboard is not available on the free tier.

---

Source: https://docs.fossa.com/docs/issues/issue-details

# Issue Details

Clicking any issue opens a detail view with everything FOSSA knows about that issue, what triggered it, where it appears, and what you can do about it. The structure is consistent across all three issue types, with type-specific content in the **Issue** tab.

The header identifies the issue and the dependency it came from.

**Vulnerability issues** show:
- The vulnerability title
- The affected package and version
- Badges for CVSS score (or custom risk score if set), EPSS score, fix availability, CVE identifier, and known exploit status

{% img src="/images/issues-issue-details-security.png" alt="Security issue detail showing HIGH 7.5 CVSS badge, EPSS score, Has Fix badge, CVE identifier, Active status, and Ignore, Create Ticket, View Path, and Assign Custom Risk Score action buttons" /%}

**Licensing issues** show:
- A badge for the issue type (Denied, Flagged, Unlicensed, Unconcluded, or Concluded (Multi))
- The license name, or "No license found" for unlicensed dependencies
- The affected package and version

{% img src="/images/issues-issue-details-licensing.png" alt="Licensing issue detail showing a Flagged badge, GPL-3.0-only license name, affected package and version, Active status, and Ignore, Create Ticket, View Path, and Edit Package action buttons" /%}

**Quality issues** show:
- A badge for the issue type (Blocked Dependency, Outdated Dependency, or risk type)
- The issue title
- The affected package and version

{% img src="/images/issues-issue-details-quality.png" alt="Quality issue detail showing an Outdated badge, Outdated version title for react-markdown, Active status, Ignore, Create Ticket, and View Path action buttons, and Issue details showing the package is 2 major versions behind" /%}

## Status

Below the header, the status bar shows the current state of the issue (**Active**, **Ignored**, or **Remediated**) and whether it's been ticketed. When viewing an issue from the global or release group scope, the status reflects the issue's state across all affected projects (it may be active in some and ignored in others simultaneously).

## Actions

The available actions depend on the issue's current state, your scope, and the issue type:

| Action | When it appears |
|---|---|
| **Ignore** | Issue has active occurrences |
| **Unignore** | Issue has ignored occurrences |
| **Create Ticket** | Issue has not yet been ticketed (opens Jira or manual ticket flow) |
| **Unlink Ticket** | Issue has a linked Jira ticket |
| **View Path** | Project scope only: shows the dependency path from your project to this package |
| **Edit Package** | Licensing issues only, if you have edit access to the source project |
| **Custom Risk Score** | Vulnerability issues only, override the CVSS-based severity |

**Vulnerability** shows the full vulnerability record:
- Description and background
- CVE identifier and links to external references
- NVD base metrics (CVSS attack vector, complexity, privileges required, etc.)
- Remediation; the version that fully resolves the vulnerability and, where available, the closest partial fix and how many versions away it is

{% img src="/images/issues-issue-details-tabs.png" alt="Issue tab showing Vulnerability details with CVSS score, CVE and CWE links, EPSS score, affected and patched versions, NVD base metrics table, references, and dependency details" /%}

**Licensing** shows:
- The dependency where the license was detected
- File matches, the specific files FOSSA found the license in
- All licenses detected on the package

**Quality** shows:
- The dependency that triggered the issue
- A description specific to the quality issue type, for example, last publish date and maintainer activity for abandonware issues, or version details for outdated dependencies

### Projects

Lists every project affected by this issue, with a count badge on the tab. From the global or release group scope this shows all projects across your organization that have this issue. From a project scope it shows only the current project.

For licensing issues, each project row expands to show the license detail specific to that project's dependency.

If the issue has been ticketed, each affected project row shows a link to its Jira ticket.

### Licenses

Shown for licensing issues when License Concluded is enabled. Displays the full license breakdown for the affected package, including any license conclusions that have been applied.

### Comments

A threaded comment panel for leaving notes on the issue, visible to anyone in your organization who has access to it. The tab badge shows the current comment count.

{% callout type="info" %}
Comments are attached to the issue, not to a specific project or revision. They're visible whenever the issue is viewed, regardless of scope.
{% /callout %}

---

Source: https://docs.fossa.com/docs/issues/ignoring-issues

# Ignoring Issues

When you ignore an open source issue in FOSSA, you choose both *where* the ignore applies and *which versions* of the package it covers. Selecting the right scope keeps your issue list focused without hiding problems you still need to act on.

## Choosing an ignore scope

The best practice is to **start narrow and broaden only as needed**. Begin by ignoring an issue in the smallest scope that resolves it, then widen the scope as you gain confidence in how the package is used across your organization. Starting conservatively ensures that no critical issues are accidentally hidden across projects where they may still matter.

### Where the ignore applies

You can apply an ignore at any of the following scopes, from narrowest to broadest:

| Scope | The ignore applies to... |
|---|---|
| This project | Only the current project |
| This project + release groups | The current project and any release groups that contain it (including future release groups) |
| A release group | All projects within the selected release group |
| A policy | All projects governed by the selected policy |
| The whole organization (global) | Every project and release group in the organization |

### Which versions the ignore covers

Independently of where the rule applies, you choose which versions of the affected package it covers:

| Package scope | Description |
|---|---|
| Selected version | Ignores the issue only for the specific version of the package currently in use. A different version of the package will generate a new active issue. |
| All versions | Ignores the issue across all versions of the package, current and future. |

{% img src="/images/issues-ignoring-issues-dialog.png" alt="Ignore issue dialog showing the Where should it be ignored scope selector with In this project, Include release groups, and Globally options, the Which versions selector with Selected version and All versions, a Reason for ignoring dropdown, and an expiry setting" /%}

{% callout type="info" %}
When in doubt, ignore at the project level for the selected version first. Broaden to a release group, policy, or global scope (or to all versions) only once you understand how the package is used and are confident the issue can be safely ignored more widely.
{% /callout %}

To suppress an issue only temporarily (so it reappears automatically after a set time window) use a [time-based ignore rule](/docs/issues/time-based-ignore-rules) instead of a permanent ignore.

## Types of issues to ignore

The following are common situations where ignoring an issue is appropriate. In general, focus your attention on the code and dependencies that are directly included in your distributed product, and consider ignoring issues that only affect development, testing, documentation, or example material.

### Licenses in example, test, and documentation directories

Common directories to consider:

- `examples/`
- `tests/`
- `docs/`
- `sample/`
- `demo/`

Licenses to watch for:

- **Copyleft licenses**: GPL, LGPL, AGPL, and the like
- **Creative Commons licenses**

Consider ignoring these licenses if:

- **Non-distributed code**: The files are not included in your distributed product or application.
- **Test dependencies**: The files are only used during testing and not in production.
- **Documentation and samples**: The files are solely for reference or educational purposes and are not part of the final product.

### Test dependencies

Common issues with test dependencies:

- **License mismatches**: Test dependencies may have licenses that are incompatible with your main project.
- **Security vulnerabilities**: Issues found in test dependencies that do not affect the production code.

Consider ignoring these issues if:

- **Not in production**: The test dependencies are not included in the production environment.
- **Temporary use**: The dependencies are only used during the development phase and not shipped with the final product.

### Documentation licenses

Common directories to consider:

- `docs/`
- `manual/`
- `guide/`

Licenses to watch for:

- **Creative Commons**: Often used for documentation and/or pertaining to a package's logo.

Consider ignoring these licenses if:

- **Not part of codebase**: The documentation is not bundled with the software product.
- **Reference only**: The documentation serves as a reference for developers and is not redistributed.

### Build scripts and configuration files

Common files to consider:

- `Makefile`
- `Dockerfile`
- `.travis.yml`
- `Jenkinsfile`

Licenses to watch for:

- **Varied**: Build scripts may come with different licenses, but they generally do not affect the distribution of the software.

Consider ignoring these licenses if:

- **Build only**: The files are used exclusively for building the software and are not included in the distributed product.
- **Internal use**: The scripts are for internal development processes.

### License headers in code snippets and templates

Common issues:

- **License headers**: Code snippets or templates may contain license headers from different open source projects.

Consider ignoring these issues if:

- **Non-executable code**: The snippets or templates are not part of the executable code in the final product.
- **Reference material**: The snippets are used for educational or reference purposes only.

## Summary

When managing open source projects, focus on the code and dependencies that are directly included in the distributed product. You can typically ignore licenses and issues in directories and files meant for development, testing, documentation, and examples, as long as they do not affect the production environment or are not redistributed with the final product. Whatever you ignore, choose the narrowest scope and version coverage that resolves the issue, and broaden only as needed.

## What's next

- **[Time-based Ignore Rules](/docs/issues/time-based-ignore-rules)**: Snooze an issue temporarily so it reappears automatically after a set period.
- **[Reviewing Security Issues](/docs/vulnerabilities/reviewing-security-issues)**: Apply the same ignore scoping principles to security vulnerabilities.
- **[Reviewing Licensing Issues](/docs/licenses/reviewing-licensing-issues)**: Manage ignored licensing issues and auto-ignore rules in the issues inbox.

---

Source: https://docs.fossa.com/docs/issues/time-based-ignore-rules

# Time-based Ignore Rules

Time-based ignore rules let you ignore an issue for a set period of time. When the rule expires, the issue becomes visible again in the product. This is useful when you want to temporarily set an issue aside and review it at a later date rather than ignoring it indefinitely.

## Creating a time-based ignore rule

When you create or edit an ignore rule (for a single issue or in bulk) the "Ignore issues" modal includes a **"When does it expire?"** field. This field renders unconditionally for every ignore rule, regardless of the scope you choose.

{% img src="/images/issues-time-based-ignore-expiry.png" alt="Ignore issue dialog showing the When does it expire field with the Never option selected, alongside the scope, version, reason, and note fields" /%}

{% steps %}
{% step title="Choose an expiration duration" %}
Open the **"When does it expire?"** dropdown and select a duration:

- **Never** (default)
- 1 day
- 1 week
- 1 month
- 1 quarter (90 days)
- 1 year

Select **Never** if you want the rule to last indefinitely.
{% /step %}
{% step title="Set the reason and scope" %}
Configure the rest of the ignore rule as usual, the reason, the project/organization scope, and the versions it applies to.
{% /step %}
{% step title="Apply the rule" %}
Click **Ignore**.
{% /step %}
{% /steps %}

You can apply time-based rules to multiple issues at once using bulk actions.

## What happens when a rule expires

- The ignore rule is automatically removed the day after its expiration date.
- Any issues that were ignored *only* by that rule become visible again in your scans and reports.

## Supported issue types

This feature is supported for **all issue types** in FOSSA.

## Viewing expiration dates

Ignore rules with an expiration show an alarm icon with a tooltip displaying the expiration date. Click the icon to extend the expiration. Ignore rules that never expire do not show this icon.

{% img src="/images/issues-time-based-ignore-expiration.png" alt="Ignore Rules page showing an Apache-2.0 ignore rule with an Expires in a day badge and a detail panel with Extend Rule and Remove Rule buttons" /%}

## What's next

- **[Ignoring Issues](/docs/issues/ignoring-issues)**: Learn how to choose the right scope when permanently ignoring issues.
- **[Reviewing Security Issues](/docs/vulnerabilities/reviewing-security-issues)**: Apply time-based rules to security vulnerabilities across your projects.

---

Source: https://docs.fossa.com/docs/issues/comparing-issues

# Comparing Issues Between Revisions

Issue comparison lets you compare the issues in your current revision against an older revision, so you can see at a glance which issues are new, which have been remediated, and which are unchanged. It provides a snapshot of issue scan results across licensing, quality, and security scans within FOSSA.

## Getting started

Issue comparison is available for both **project** and **release-group** scopes, including existing projects and release groups. It uses the same issues table as the standard issues view, so you can filter, sort, and action on issues directly from the comparison view.

## Comparing two revisions

{% steps %}
{% step title="Open an issue category" %}
Navigate to a project or release group within FOSSA, then click a sub-category of **Licensing**, **Security**, or **Quality**.

{% img src="/images/release-groups-issues-tab.png" alt="Release group Issues tab showing the Licensing sub-category active with a list of issues and the Compare button in the top right" /%}
{% /step %}
{% step title="Start a comparison" %}
On the right-hand side of the page, above the filter, click the **Compare** button.

{% img src="/images/release-groups-issues-tab.png" alt="Issues tab with the Compare button highlighted in the top right corner above the issue filter panel" /%}
{% /step %}
{% step title="Pick a revision to compare against" %}
Select an older revision to compare the current revision against.

{% img src="/images/issues-comparing-issues-compare-btn.png" alt="Comparing Changes page showing the current revision 3.1.0 and the Select a revision to compare dropdown, with an empty state prompt to select a revision" /%}
{% /step %}
{% step title="View the comparison" %}
The issue comparison for the two revisions is now displayed below.

{% img src="/images/issues-comparing-issues.png" alt="Comparing Changes view showing revision 3.1.0 compared against 1.0.7, with New, Remediated, and Unchanged toggles on the left and 11 new active issues listed" /%}
{% /step %}
{% /steps %}

## Toggling between New, Remediated, and Unchanged issues

When comparing two revisions, the menu on the left-hand side lets you toggle between three categories:

| Category | Shows |
|---|---|
| New | Issues present in the current revision but not in the compared revision |
| Remediated | Issues present in the compared revision but no longer in the current revision |
| Unchanged | Issues present in both revisions |

Select an option on the left-hand side and the page displays the issues in that category.

## Supported project types

Issue comparison supports the following project types:

- Repo
- SBOM
- Binary
- Container

---

Source: https://docs.fossa.com/docs/licenses

# Licenses

Every open source dependency you ship carries license obligations: attribution, source disclosure, copyleft, and more. FOSSA identifies the licenses across your dependency tree and source, surfaces what each one requires, and helps you stay compliant.

## What this covers

- **[Understanding licensing issues](/docs/licenses/understanding-licensing-issues):** how FOSSA detects declared and discovered licenses and why an issue is raised.
- **[Reviewing licensing issues](/docs/licenses/reviewing-licensing-issues):** work through your licensing backlog with bulk actions and triage.
- **[License corrections](/docs/licenses/license-corrections)** and **[conclusions](/docs/licenses/license-conclusions)**: override or finalize the license FOSSA records for a package.
- **[License disputes](/docs/licenses/license-disputes):** resolve disagreements about what a dependency is actually licensed under.
- **[Custom license scans](/docs/licenses/custom-license-scans):** detect your own proprietary or third-party license text.

## Start here

- **[Understanding licensing issues](/docs/licenses/understanding-licensing-issues):** the concepts behind everything else in this section.
- **[Reviewing licensing issues](/docs/licenses/reviewing-licensing-issues):** the day-to-day workflow for clearing your backlog.

To automate enforcement of license rules, see [Policies](/docs/policies). To produce shareable attribution and compliance documents, see [Reports](/docs/reports).

---

Source: https://docs.fossa.com/docs/licenses/understanding-licensing-issues

# Understanding Licensing Issues

When FOSSA scans a project, it compares every detected license and dependency against your licensing policy and checks for missing license data. Anything that requires attention surfaces as a licensing issue in the **Issues** tab.

## Issue types

There are five licensing issue types. The first two are policy-driven: they fire based on rules you configure. The last three are data-quality issues: they fire when FOSSA can't determine a clean license picture.

| Issue type | What triggers it |
|---|---|
| **Denied** | A **Deny** rule in your policy matched a license or dependency in this project. |
| **Flagged** | A **Flag for Review** rule matched; the license needs manual evaluation before it can be approved or denied. |
| **Unlicensed** | FOSSA found no license information for the dependency. It can't determine whether the license is acceptable. |
| **Unconcluded** | FOSSA detected multiple licenses on a dependency and none has been concluded. The effective license is ambiguous. |
| **Concluded (Multi)** | A dependency had multiple detected licenses and a user manually concluded which one applies. This is informational. The conclusion is recorded and the ambiguity is resolved. |

{% img src="/images/licenses-understanding-issue-types.png" alt="Global Licensing issues tab showing 163 active issues grouped by package, with issue counts per row and filter panel for package manager, project labels, depth, and issue status" /%}

## What each type requires

**Denied** issues block compliance. The dependency must be removed, replaced, or have its rule updated in the policy before the project can pass.

**Flagged** issues require a human decision. A reviewer must approve or deny the flagged license before the issue is resolved.

**Unlicensed** and **Unconcluded** issues require license data to be provided. Options include editing the dependency to add a concluded license, or updating the dependency to a version that declares one. See [License Corrections](/docs/licenses/license-corrections).

**Concluded (Multi)** issues are resolved, no action required. They appear in the issue list as a record of the conclusion.

## Where issues come from

Beyond its type, two properties describe where a licensing issue originates:

- **Issue source**: most issues come from a **dependency** (a component resolved from a package manager). They can also come from a **snippet**, a license match FOSSA found directly in your first-party source code via [Snippet Scanning](/docs/project-setup/snippets). With Vendored Dependency Detection enabled, dependency-sourced issues are split further into **Managed** (package-manager) and **Vendored** (copied into your source tree).
- **License identification**: a **Declared** license is one the package author stated in the manifest; a **Discovered** license is one FOSSA found by scanning the source. A dependency can have both, and the issue records which signal it came from.

## Issue status

An issue is **Active** (needs attention) or **Ignored** (suppressed so it doesn't block CI checks). A third lifecycle state, **Remediated**, applies once an issue that was present in a previous revision is gone in the current one.

An issue can be ignored in three ways:

- **Manually**: a reviewer dismisses it, ideally with a documented reason.
- **By an ignore rule**: an auto-ignore rule suppresses it across versions or projects (see [Reviewing Licensing Issues](/docs/licenses/reviewing-licensing-issues#auto-ignore-rules)).
- **By policy**: the **Intelligent Auto-Ignore** setting auto-ignores non-concluded issues.

Ignoring suppresses an issue; it doesn't fix the underlying problem. Use it sparingly.

## What's next

- **[Reviewing Licensing Issues](/docs/licenses/reviewing-licensing-issues)**: how to triage and resolve active issues.
- **[Licensing Policies](/docs/policies/licensing-policies#configuring-policy-rules)**: how Deny and Flag rules are defined.
- **[License Corrections](/docs/licenses/license-corrections)**: add, change, or remove a dependency's detected licenses to correct FOSSA's data across your organization.

---

Source: https://docs.fossa.com/docs/licenses/reviewing-licensing-issues

# Reviewing Licensing Issues

The issues inbox is where you triage, resolve, and track licensing issues across your projects. Issues are split into two tabs:

- **Active:** issues that require attention
- **Ignored:** issues that have been reviewed and suppressed

For a breakdown of what each issue type means, see [Understanding Licensing Issues](/docs/licenses/understanding-licensing-issues).

## Filtering

{% img src="/images/licenses-reviewing-filter-panel.png" alt="Global Licensing issues page showing 163 active issues with the filter panel on the right including Depth, Ticket, Issue Type, Licenses, First Found, and Package Manager filter groups" /%}

### Depth

| Option | Shows |
|---|---|
| **Direct** | Issues on direct dependencies only |
| **Transitive** | Issues on transitive (indirect) dependencies only |

### Ticket

**Ticketed** is a parent option with two children; selecting it includes both:

| Option | Shows |
|---|---|
| **Ticketed → Jira Integration** | Issues linked via the native Jira integration |
| **Ticketed → URL linked** | Issues with a manually added URL link |
| **Not ticketed** | Issues with no ticket association |

### Issue Type

| Option | Shows |
|---|---|
| **Denied** | `policy_conflict`: license matched a Deny rule |
| **Flagged** | `policy_flag`: license matched a Flag for Review rule |
| **Unlicensed** | `unlicensed_dependency`: no license detected |
| **Unconcluded** | `unconcluded_dependency`: multiple licenses detected, none concluded |
| **Concluded (Multi)** | `multi_license_concluded`: multiple licenses detected, one manually concluded |

{% callout type="info" %}
**Unconcluded** and **Concluded (Multi)** filter options only appear when the License Concluded feature is enabled for your organization.
{% /callout %}

### License Identification

| Option | Shows |
|---|---|
| **Declared** | Issues from licenses declared by the package author in the package metadata |
| **Discovered** | Issues from licenses FOSSA detected through scanning that the author may not have declared |

### Issue Source

Where the issue originates. Which options appear depends on the detection features enabled for your org.

| Option | Shows |
|---|---|
| **Dependency** | Issues on dependencies resolved from a package manager |
| **Snippet** | Issues on license matches found in your first-party source via [Snippet Scanning](/docs/project-setup/snippets) |
| **Managed Dependency** | Package-manager dependencies *(shown when Vendored Dependency Detection is enabled and you're outside global scope)* |
| **Vendored Dependency** | Dependencies copied into your source tree *(same condition)* |

### Licenses

A multi-select of every license currently present in the scope; filters issues down to the licenses you choose.

### First Found

| Option | Shows |
|---|---|
| **Anytime** | All issues regardless of when they were found |
| **Last 7 days** | Issues first detected in the last 7 days |
| **Last 14 days** | Issues first detected in the last 14 days |
| **Last 30 days** | Issues first detected in the last 30 days |

### Package Manager

Filters issues to those from a specific ecosystem or package manager. Only ecosystems present in the current scope (global, project, or release group) are shown.

### Dependency Confidence

Shown for binary projects (Binary Decomposition). Filters by FOSSA's confidence in the detected dependency: **High**, **Medium**, **Low**, or **Unknown**.

### Layer

Shown for container projects. Filters by image layer:

| Option | Shows |
|---|---|
| **Base Layer** | Issues from the image's base layer |
| **Other Layers** | Issues from layers built on top of the base |

### Project Labels

*Global scope only.* Filters to issues in projects tagged with specific FOSSA project labels. Select multiple labels (OR logic); disabled if your org has no labels.

{% callout type="info" %}
To narrow issues to a team, use the **team selector** in the inbox header; it's a scope control, not part of the filter panel.
{% /callout %}

{% callout type="info" %}
Select **Reset all filters** at any time to clear all active filters and show every issue.
{% /callout %}

## Sorting

Use the sort dropdown to order issues by:

| Sort option | Description |
|---|---|
| **Newest** | Issues found most recently first |
| **Oldest** | Issues found longest ago first |
| **Package (A-Z)** | Alphabetical by package name |
| **Package (Z-A)** | Reverse alphabetical by package name |
| **Most issues** | Packages with the highest issue count first |
| **Least issues** | Packages with the lowest issue count first |

{% callout type="info" %}
Default sort is **Most issues** when grouped by version, and **Package (A-Z)** when ungrouped.
{% /callout %}

## Issue grouping

Issues are grouped by semantic version by default. To switch to an ungrouped view, select **Version** in the inbox header and change it to **Ungrouped**.

## Issue actions

Select one or more issues with their checkboxes, then open the **Actions** menu at the top of the inbox; it stays disabled until at least one issue is selected. Available actions depend on product type, issue status, scope, and whether you're acting on one or many issues.

{% callout type="warning" %}
Not all actions are available in every context. Check the table below for the full breakdown.
{% /callout %}

{% callout type="info" %}
Under an organization setting, the **Ignore** / **Unignore** actions can instead display as **Resolve** / **Unresolve**: same behavior, different wording. The "current version only" vs "all versions" choice below is made in the ignore modal, not as two separate menu items.
{% /callout %}

| Action | Description | Type | Products | Status | Scope |
|---|---|---|---|---|---|
| **Ignore (current version only)** | Ignores the issue for the current semantic version of the affected package, in the selected project(s) only. A new revision with any other version will generate a new active issue. | Individual, Bulk | Licensing, Security, Quality | Active | Global, Release group, Project |
| **Ignore (all versions)** | Ignores the issue across all semantic versions of the affected package. Only available for individual project issues. Scoped to the selected issue type only. | Individual | Licensing, Security | Active | Project |
| **Create ticket** | Creates a Jira ticket containing the selected issues. If a previously ticketed issue is selected, it links to the new ticket only. | Individual, Bulk | Licensing, Security, Quality | Active, Ignored | Global, Release group, Project |
| **Unlink ticket** | Removes the association between the selected issues and any linked tickets. | Individual, Bulk | Licensing, Security, Quality | Active, Ignored | Global, Release group, Project |
| **Generate CSV** | Downloads a CSV of the selected issues, scoped to the current issue status tab. | Individual, Bulk | Licensing, Security, Quality | Active, Ignored | Global, Release group, Project |
| **Unignore** | Changes selected issues from Ignored back to Active. Does not stop any existing auto-ignore rules. | Individual, Bulk | Licensing, Security, Quality | Ignored | Global, Release group, Project |

## Auto-ignore rules

Auto-ignore rules persist an ignore decision beyond a single revision or project. When you ignore an issue, you can configure the scope of that decision so it applies automatically to future versions or projects.

{% callout type="warning" %}
Auto-ignore rules apply to current and future projects within the selected scope. Use with care; see [Managing auto-ignore rules](#managing-auto-ignore-rules) for how to stop them.
{% /callout %}

**Auto-ignore applies to the combination of:**
- Package(s)
- Project(s)
- Issue type (Denied license, Flagged license, or a CVE)

### Where should it be ignored

When ignoring an issue with the necessary permissions, you'll see a **Where should it be ignored?** prompt:

| Scope | Effect |
|---|---|
| **In this project** | Auto-ignore rule scoped to the selected project only |
| **Include release groups** | Scoped to the selected project and any release group containing it, including future ones |
| **In this release group** | Scoped to the selected release group only *(release group inbox only)* |
| **In the licensing policy** | Scoped to the policy used by the selected project; applies to any other project or release group using that policy |
| **Globally** | Scoped to all projects and release groups regardless of policy |

### Which versions

| Scope | Effect |
|---|---|
| **Selected version** | Auto-ignore rule scoped to the current package version only |
| **All versions** | Scoped to all versions of the package, current and future |

{% callout type="info" %}
Selecting **In this project** and **Selected version** together does not create an auto-ignore rule. The issue is suppressed in all revisions of this project that include that exact package version, but will become active again for any new package version or new project.
{% /callout %}

### Managing auto-ignore rules

From any issue inbox (Global, Project, or Release Group), click **Ignore Rules** to see all applicable rules for that scope.

- The **Global** inbox shows all auto-ignore rules across every scope
- **Project** and **Release Group** inboxes show only applicable scoped rules plus all global rules

Each ignore rule shows:

| Column | Description |
|---|---|
| **Issue Ignored** | The issue type (Denied, Flagged, Unlicensed) and the specific license |
| **Package** | Package name |
| **Version** | Specific package version, or *All* |
| **Scope** | Global, Policy, Project, or Project + Release Group |
| **By** | User who created the rule |
| **Note** | Reason provided when the rule was created; also shown in issue details |

Use the action icon on the far right of any row to remove a rule.

{% img src="/images/licenses-reviewing-ignore-rules.png" alt="Ignore Rules page showing a table of auto-ignore rules with columns for Issue Ignored, Package, Version, Scope, By, and Note, with an action icon to remove each rule" /%}

### Auto-ignore permissions

| Scope | Required permissions |
|---|---|
| **Project** | `Resolve Licensing issues of projects` for the selected project or all projects |
| **Release group** | `Resolve Licensing issues of release group` and access to the selected release group or all release groups |
| **Project + release group** | `Resolve Licensing issues of project` and `Resolve Licensing issues of release group`, plus access to the selected project and all release groups |
| **Policy** | `Create Licensing policy` |
| **Global** | `Resolve Licensing issues of project` and `Resolve Licensing issues of release group`, plus access to all projects and release groups |

{% callout type="info" %}
Permission names in this table are taken from the legacy docs and have not been verified against current permission settings. Confirm exact names in **Settings → Organization → Roles**.
{% /callout %}

## Issue drawer

Click anywhere on an issue row to open the issue drawer for a detailed view without leaving the inbox.

{% img src="/images/issues-issue-details-licensing.png" alt="Licensing issue drawer showing the GPL-3.0-only Flagged issue with Expand, Share, and Close controls in the top-right corner, Issue and Projects tabs, and license details below" /%}

Controls in the top-right corner:

| Control | Action |
|---|---|
| **Expand** | Opens the issue in a full-screen view in a new tab |
| **Share** | Copies a link to the expanded issue view |
| **Close** | Closes the drawer |

### Drawer tabs

The drawer has top-level tabs:

| Tab | Shows |
|---|---|
| **Issue** | The issue itself, in the stacked sections below. |
| **Licenses** | Every license detected on the package, each marked Declared or Discovered. *(Appears for a licensing issue when License Conclusions is enabled.)* |
| **Projects** | The affected projects (with a count badge). See the table below. |
| **Comments** | A time- and user-stamped comment thread for triage discussions (with a count badge). |

Within the **Issue** tab, content is stacked in these sections:

| Section | Shows |
|---|---|
| **Issue Details** | Issue type (Flagged, Denied, Unlicensed…), package depth per project, and any policy notes for the detected license |
| **File Matches** | Where the license was found (Declared or Discovered), with file path and line numbers; use the dropdown to explore additional paths |
| **Dependency** | Package name, version, depth, and package manager/ecosystem |

The **Projects** tab lists every affected project:

| Column | Description |
|---|---|
| **Project Name** | Title of the project in FOSSA |
| **Issue Status** | Whether the issue is Active or Ignored in that project |
| **View Path** | The dependency path showing where the package was detected |

## What's next

- **[License Corrections](/docs/licenses/license-corrections)**: Fix incorrect or missing license data when FOSSA's detection doesn't match reality.
- **[License Conclusions](/docs/licenses/license-conclusions)**: Determine a single dominant license per dependency when multiple licenses are detected.
- **[Licensing Policies](/docs/policies/licensing-policies)**: Set up policy rules to automatically flag, deny, or permit licenses across your organization.

---

Source: https://docs.fossa.com/docs/licenses/license-corrections

# License Corrections

When FOSSA detects incorrect, missing, or unwanted license data on a dependency, you can correct it directly in the UI. Corrections apply **across all projects and all versions** in your organization: fix it once and it takes effect everywhere.

{% callout type="warning" %}
Editing a dependency applies to every project and every revision in your organization. You need an appropriate organization-level role to make these changes.
{% /callout %}

## Adding a license to an unlicensed dependency

Use this when FOSSA resolved a dependency but couldn't find a license for it. You can look up the correct license and add it manually.

{% steps %}
{% step title="Find the dependency" %}
Go to **Inventory → Dependencies** and locate the dependency with no license. If you're unsure of the correct license, open the package's repository or registry page to check.

{% img src="/images/license-corrections-dependencies-list.png" alt="Inventory Dependencies page listing packages with their detected licenses" /%}
{% /step %}

{% step title="Open the dependency and select the Licenses tab" %}
Click anywhere on the dependency row to open it. The dependency drawer opens showing the **Details** tab. Click the **Licenses** tab to see the license data.

{% img src="/images/license-corrections-drawer-details.png" alt="Dependency drawer open showing the Details tab" /%}

{% img src="/images/license-corrections-licenses-tab.png" alt="Dependency drawer with Licenses tab selected showing declared and discovered licenses" /%}
{% /step %}

{% step title="Add a license" %}
Click **+ Add a license**, then search for the correct license in the **License Name** field and select it.

{% img src="/images/license-corrections-add-form-empty.png" alt="Add License form with License Name, License Text, and Copyrights fields" /%}
{% /step %}

{% step title="Add license details and save" %}
Optionally add **License Text** and **Copyrights**, then click **Apply**.

{% img src="/images/license-corrections-add-form-filled.png" alt="Add License form with MIT License selected and copyright details filled in" /%}
{% /step %}

{% step title="Verify" %}
The **Licenses** tab now shows the corrected license. If that license is permitted by your policy, it will no longer be flagged as an issue.

{% img src="/images/license-corrections-licenses-added.png" alt="Licenses tab showing the manually added MIT license alongside the originally detected license" /%}
{% /step %}
{% /steps %}

## Removing an unwanted license

Use this when FOSSA detected a license on a dependency that shouldn't be there, for example, a false positive from a comment in the source code.

{% steps %}
{% step title="Open the dependency and select the Licenses tab" %}
Click anywhere on the dependency row in **Inventory → Dependencies** to open it, then click the **Licenses** tab.

{% img src="/images/license-corrections-licenses-tab.png" alt="Dependency drawer with Licenses tab selected showing the detected licenses" /%}
{% /step %}

{% step title="Delete the license" %}
Click **Delete** next to the license you want to remove.

{% img src="/images/license-corrections-licenses-added.png" alt="Licenses tab showing Delete buttons next to each declared license" /%}
{% /step %}

{% step title="Run policy scan" %}
Navigate to the project **Summary** tab and click **Run policy scan** to update the issue count.

{% img src="/images/license-corrections-project-summary.png" alt="Project Summary tab showing the Run policy scan link and current issue counts" /%}
{% /step %}
{% /steps %}

## Notice files

Dependency edits also cover notice files. You can review, edit, or suppress the notice text that appears in attribution reports. See [Notice files](/docs/project-setup/dependencies#notice-files) on the Dependencies page.

## What's next

- **[Reviewing Licensing Issues](/docs/licenses/reviewing-licensing-issues)**: See how your corrections affect the active issues in the inbox.
- **[Licensing Policies](/docs/policies/licensing-policies)**: Ensure your corrected licenses are evaluated against your organization's policy rules.

---

Source: https://docs.fossa.com/docs/licenses/license-disputes

# License Disputes

Occasionally FOSSA may identify a license incorrectly. You can report it **directly from the issue**, FOSSA's license data dispute routes the report to our team for review, so there's no need to email support separately.

## Report a license data dispute

{% steps %}
{% step title="Open the license issue" %}
Go to the project's **Licensing** issues and open the issue for the dependency with the incorrect license to view its details.
{% img src="/images/license-disputes-licensing-issues.png" alt="Project Licensing issues list showing active issues grouped by dependency" /%}
{% /step %}
{% step title="Click \"Report a data issue with this license\"" %}
In the issue detail footer, next to **Found a mistake?**, click **Report a data issue with this license** (for a license-conclusion issue, the link reads **Report an issue with this License Conclusion**).
{% img src="/images/license-disputes-issue-drawer.png" alt="Issue detail panel showing the 'Found a mistake? Report a data issue with this license.' link in the footer" /%}
{% /step %}
{% step title="Choose what's wrong and add detail" %}
Under **What is the problem with this license?**, pick the reason that fits, add any helpful context in the **Dispute comment** box, and click **Submit Feedback**.
{% img src="/images/license-disputes-feedback-form.png" alt="Licensing Feedback dialog showing the dispute reason options and comment field" /%}
{% /step %}
{% /steps %}

## Dispute reasons

| Reason | Use when |
| :--- | :--- |
| **License detection false positive** | FOSSA reported a license that isn't actually present. |
| **Incorrect dependency version reported** | The dependency's version is wrong, leading to the wrong license. |
| **Multi or dual licensed** | The dependency offers a choice of licenses that FOSSA didn't reflect. |
| **Incorrect license conclusion** | The concluded license is wrong *(shown only for license-conclusion issues)*. |

{% callout type="tip" %}
In the comment, include a link to a public source (the package's `LICENSE` file, repository, or registry page) showing the correct license. The more specific the evidence, the faster we can confirm and correct it.
{% /callout %}

## What happens next

FOSSA reviews the dispute, confirms the correct data, and applies a correction. It also feeds the root cause back into the scanner so the detection improves going forward. For anything the dispute flow doesn't cover, reach out at [support@fossa.com](mailto:support@fossa.com).

---

Source: https://docs.fossa.com/docs/licenses/license-conclusions

# License Conclusions

**License Conclusion** determines a single, dominant license for each dependency by combining FOSSA's **Declared License** data (from package manifests) with **Discovered License** data (from source code scans). The result is a single authoritative license that drives policy evaluation and attribution.

This mirrors the `PackageLicenseConcluded` field in the SPDX specification.

{% img src="/images/license-conclusions-dependency-drawer.png" alt="Dependency drawer Licenses tab showing a concluded Apache-2.0 license alongside declared and discovered license data" /%}

## Enabling License Conclusion

License Conclusion is disabled by default. Enable it at the organization level before it appears in projects.

{% steps %}
{% step title="Open org settings" %}
Navigate to **Settings → Organization → General**.
{% /step %}

{% step title="Enable the feature" %}
Scroll to the **Features** section and toggle **License Conclusion** to on.

The description reads: *"Enables the ability to conclude licenses and adds related license policy settings. This global setting will only take effect on individual projects upon their next analysis."*
{% img src="/images/license-conclusions-org-settings-feature-toggle.png" alt="Organization general settings showing the License Conclusion toggle in the Features section" /%}
{% /step %}
{% /steps %}

{% callout type="info" %}
Concluded License data is generated during dependency analysis. After enabling, run a new CLI scan or trigger a Quick Import refresh for data to populate.
{% /callout %}

## How FOSSA concludes multiple licenses

In some cases FOSSA will automatically conclude multiple licenses for one dependency:

**Explicit AND:** when FOSSA's internal data and external verification confirm a package is governed by multiple licenses simultaneously, they are joined with AND (e.g., `MIT AND Apache-2.0`).

**Permissive AND:** if a package normally concludes to a permissive license (e.g., MIT) but a non-permissive license (e.g., GPL-3.0) is also detected, FOSSA ANDs them together to ensure the stricter obligations aren't overlooked.

To see the data sources behind a conclusion, open the dependency drawer, select the **Licenses** tab, and review the Concluded License section.

## Policy settings

Each licensing policy has a **Settings** tab where you can configure how the policy interacts with concluded licenses. All settings are disabled by default.

| Setting | What it does |
|---|---|
| **Only create issues for Concluded Licenses** | Reduces noise by only generating issues based on the concluded license. Issues from Declared or Discovered licenses are suppressed. |
| **Intelligent Auto-Ignore** | Issues are generated for all license types, but issues from non-concluded licenses are automatically marked Ignored. Keeps the data record while removing noise from the active issue list. |
| **Create issues when a license can't be concluded** | Creates a unique **Unconcluded** issue when FOSSA cannot automatically determine a dominant license, prompting manual review. Takes effect on individual projects upon their next analysis only. |
| **Create issues when a dependency auto-concludes to multiple licenses** | Creates a unique **Multi-License Concluded** issue when FOSSA's base conclusion results in multiple licenses (e.g., `MIT AND GPL-3.0`). |

{% callout type="info" %}
**Only create issues for Concluded Licenses** and **Intelligent Auto-Ignore** are mutually exclusive. Enabling the first automatically disables the second.
{% /callout %}

## Including concluded licenses in reports

### Attribution reports

{% steps %}
{% step title="Open Reports" %}
Navigate to **Reports** for the project.
{% /step %}

{% step title="Check Concluded License(s)" %}
Under **Dependency Metadata** in the right sidebar, check **Concluded License(s)**.
{% /step %}
{% /steps %}

### SBOM exports

FOSSA maps the Concluded License to the following SBOM standard fields:

| Standard | Field |
|---|---|
| **SPDX** | `PackageLicenseConcluded` |
| **CycloneDX** | `acknowledgement` |

{% callout type="info" %}
The CycloneDX `acknowledgement` field mapping has not been verified from source code; confirm against your export if this field is critical.
{% /callout %}

## Manually overriding a concluded license

FOSSA's automated conclusion can be overridden per dependency from the dependency drawer.

| Action | What it does |
|---|---|
| **Conclude** | Manually conclude a specific license for this dependency, overriding the automated result |
| **Unconclude** | Remove the current conclusion and return to the automated result |
| **Add a License** | Add a new license to the dependency, which can then be concluded |
| **Add a license group** | Add a new group of licenses to the dependency |

Manual edits take precedence over FOSSA's automated logic for the specific dependency.

## What's next

- **[License Corrections](/docs/licenses/license-corrections)**: Manually add or remove licenses when automatic detection doesn't capture the right data.
- **[Licensing Policies](/docs/policies/licensing-policies)**: Configure how concluded licenses are evaluated against your policy rules.
- **[Licensing Reports](/docs/reports/licensing-report)**: Generate reports that include concluded license data in your attribution output.

---

Source: https://docs.fossa.com/docs/licenses/custom-license-scans

# Custom License Scans

FOSSA ships a large license database, but it can't cover everything: an internal or proprietary license, company-specific terms, or any text you want surfaced. **Custom License Scans** let you define that text yourself so FOSSA detects it in your scanned code and reports it as a license.

## What a custom license is

A custom license is a license **you define**, with two parts:

| Part | What it is |
| :--- | :--- |
| **Name** | The title shown in the UI and in reports (e.g. *Company Proprietary License*). Make it descriptive, since this is what report readers see. |
| **Match criteria** | A regular expression FOSSA matches against the text it scans. When it matches, FOSSA records the custom license on that file/dependency. |

Once detected, a custom license behaves **like any other license in FOSSA**: it shows up in the dependency's **Licenses** grouping (alongside detected and declared licenses) and in your inventory next to FOSSA's known licenses, not as a separate, special-cased thing.

## How custom licenses are governed by policy

Because a custom license is a real license, your **[licensing policy](/docs/policies/licensing-policies#configuring-policy-rules)** treats it exactly like a supported one. In a policy rule you can mark a custom license as:

| Rule | Effect |
| :--- | :--- |
| **Approved** | Allowed; no issue is raised. |
| **Flagged** | Surfaced for review (a flagged issue). |
| **Denied** | Treated as a violation (a denied issue that can fail CI/CD). |

So you might **flag** your *Company Proprietary License* for review wherever it appears, or **deny** a license phrase you never want shipped, using the same Approve / Flag / Deny model you use for known licenses.

## Configure org-wide (UI)

In the UI, custom license scans apply **across your whole organization**. Configure them at **Organization Settings → Integrations → Custom License Scans** (`/account/settings/integrations/custom_license_scans`), adding a **name** and **match criteria** for each.

{% img src="/images/custom-license-scans-settings.png" alt="Custom License Scan Settings page under Organization Settings, Integrations, with the Add button to create a license entry" /%}

Once a scan runs, a detected custom license appears on the project like any other license, labeled in the dependency's **Licenses** column:

{% img src="/images/custom-license-scans-detected-inventory.png" alt="Project Dependencies inventory showing a dependency tagged with a custom-license label" /%}

Click into the license to see the files that matched, and into a file to see the matches themselves:

{% img src="/images/custom-license-scans-file-matches.png" alt="License detail File Matches tab showing the matched files list and the highlighted license text within a file" /%}

## What appears in reports

By default, only the custom license's **name** appears in reports, **not** the matched text. (This is why a clear, descriptive name matters: it's all a report reader sees.)

To include the full license text in reports, open the dependency's **Licenses** tab and edit its licenses. For each license you can fill in **Raw License Text** (or add a license group, then add and conclude the custom license). That text then appears alongside the license in the report.

{% img src="/images/custom-license-scans-edit-raw-text.png" alt="Add License panel in the dependency Licenses tab with License Text and Copyrights fields filled in" /%}

{% img src="/images/custom-license-scans-report-raw-text.png" alt="Licensing report preview showing the full raw license text expanded under each declared license" /%}

## Configure per project (FOSSA CLI)

To scope a custom license to a single project instead of the whole org, add a `customLicenseSearch` entry to that project's `.fossa.yml`, read by the FOSSA CLI. This is useful for team-specific rules that shouldn't apply org-wide.

```yaml
# .fossa.yml
customLicenseSearch:
  - matchCriteria: (?i)this is a proprietary company license
    name: Company License
```

The CLI then flags and reports **Company License** wherever it matches in that project.

## Keyword search

Keyword search is also configured via the FOSSA CLI and warns you of matches **at scan time**, which is handy for catching sensitive data (e.g. an API key) before it's pushed.

```yaml
# .fossa.yml
experimentalKeywordSearch:
  - matchCriteria: api_key
    name: API Key Found
```

This surfaces a warning in CLI/CI runs:

```
Scan Summary
------------

1 projects scanned;  0 skipped,  1 succeeded,  0 failed,  1 analysis warnings

* Keyword Search: succeeded with 2 warnings
  ** API Key Found - path/to/sensitive-file.yml (lines 1-1)
```

Pair it with the FOSSA CLI `--output` flag to keep findings local/offline.

## Full reference

The `.fossa.yml` keys and CLI flags above are documented in full in the FOSSA CLI reference:

- [Custom License and Keyword Searches](https://github.com/fossas/fossa-cli/blob/master/docs/features/custom-license-and-keyword-searches.md)
- [Regular expression syntax for custom license and keyword searches](https://github.com/fossas/fossa-cli/blob/master/docs/features/custom-license-and-keyword-search-regular-expression-syntax.md)

---

Source: https://docs.fossa.com/docs/vulnerabilities

# Vulnerabilities

FOSSA continuously checks your dependencies against known vulnerability data so you can find and fix security issues before they ship, and focus on the ones that actually matter.

## What this covers

- **[Reviewing security issues](/docs/vulnerabilities/reviewing-security-issues)**: triage vulnerabilities across all your projects from a single inbox.
- **[Issue overview](/docs/vulnerabilities/reviewing-security-issues)** and **[comparing issues](/docs/vulnerabilities/reviewing-security-issues)**: understand the detail behind a finding and how versions differ.
- **[Custom risk scores](/docs/vulnerabilities/custom-risk-scores)** and **[upgrade distance](/docs/vulnerabilities/custom-risk-scores)**: tune prioritization to your risk model and find the cheapest path to a fix.
- **[Container scanning](/docs/vulnerabilities/container-scanning)** and **[SBOM vulnerability detection](/docs/vulnerabilities/sbom-vulnerability-detection)**: extend scanning to images and imported bills of materials.
- **[Automated malware detection](/docs/vulnerabilities/automated-malware-detection)**: catch dependencies published with malicious intent and gate them out of your builds.
- **[Ignoring issues](/docs/issues/ignoring-issues)**: suppress findings that don't apply, with an audit trail.
- **[Vulnerability data sources](/docs/vulnerabilities/vulnerability-data-sources)**: where FOSSA's vulnerability intelligence comes from.

## Start here

- **[Reviewing security issues](/docs/vulnerabilities/reviewing-security-issues)**: the core triage workflow.
- **[Issue overview](/docs/vulnerabilities/reviewing-security-issues#issue-drawer)**: how to read a single vulnerability and decide what to do.

To automate how vulnerabilities are flagged and blocked, see [Policies](/docs/policies). To surface findings in your tools, see [Integrations](/docs/integrations).

---

Source: https://docs.fossa.com/docs/vulnerabilities/reviewing-security-issues

# Reviewing Security Issues

The Security Issues page is the central place to review and act on all security issues, across all projects globally, within a specific project, or within a release group. From here you can filter and sort issues, take bulk actions, inspect individual vulnerability details in the issue drawer, and configure auto-ignore rules to persist triage decisions.

{% img src="/images/vulnerabilities/reviewing-security-issues-overview.png" alt="Security Issues page showing the Active tab, filter sidebar, and issues list" /%}

## Issue types

All issues are organized into two tabs:

| Tab | Contents |
|---|---|
| **Active** | Issues that require attention |
| **Ignored** | Issues that have been reviewed and ignored |

{% callout type="info" %}
Issues no longer present in the latest project revision are considered **remediated** and do not appear in either tab. Remediation occurs automatically when a dependency is updated to a safe version, removed from the project, or when upstream vulnerability data (e.g. NVD) marks the issue as resolved. Remediated issues can be viewed in the Issue Overview or via the revision comparison feature.
{% /callout %}

## Filters

Use filters to narrow the issue list to the subset you want to address. Select any filter group to expand it.

### Depth

| Option | Description |
|---|---|
| Direct | Issues from direct dependencies |
| Transitive | Issues from transitive (indirect) dependencies |

### CWE

Filter issues by one or more Common Weakness Enumeration (CWE) identifiers associated with the vulnerability.

### Severity

Filter by severity level and severity source. The **Severity Source** sub-filter is available in project and release group scope (not global).

**Severity levels**

| Option | CVSS score range | Custom Risk Score range |
|---|---|---|
| Critical | 9.0–10.0 | 90–100 |
| High | 7.0–8.9 | 70–89 |
| Medium | 4.0–6.9 | 40–69 |
| Low | 0.1–3.9 | 1–39 |
| Unknown | No score available |  |

**Severity source**

| Option | Description |
|---|---|
| Standard (CVSS) | Filter by FOSSA-computed CVSS severity |
| Custom Risk Score | Filter by a manually assigned custom risk score. When set on an issue, the custom risk score becomes the primary severity displayed in the issues table; the original CVSS score remains visible in the issue details. |

See [Custom Risk Scores](/docs/vulnerabilities/custom-risk-scores) for how to assign and manage custom scores.

**CVSS version**

FOSSA computes the displayed CVSS score using the highest-fidelity vector available for each vulnerability: CVSS v4 is preferred when present, falling back to CVSS v3, then CVSS v2. The version used determines what appears in the **NVD Base Metrics** section of the issue drawer.

### Fix Available

**Upgrade distance** is the gap between a dependency's current version and the nearest version that resolves the vulnerability, measured in [semantic versioning](https://semver.org/) increments. A patch-distance fix is a low-risk update; a major-distance fix may involve breaking changes and more testing effort.

Filter by upgrade distance to separate quick wins from upgrades that need planning:

| Option | Description |
|---|---|
| None | No known safe version exists |
| Patch | A patch-increment upgrade fixes the issue |
| Minor | A minor-increment upgrade fixes the issue |
| Major | A major-increment upgrade fixes the issue |
| Unknown | A fix exists but the package does not follow semantic versioning |

{% callout type="warning" %}
Some values may be unexpected. For example, an upgrade from a prerelease to a release version is classified as a **Major** increment under semantic versioning rules.
{% /callout %}

{% callout type="info" %}
**Partial fix**; the nearest update that resolves the selected CVE; may not resolve all vulnerabilities on the dependency. **Complete fix**; the nearest update that resolves all known vulnerabilities on the dependency.
{% /callout %}

The Security Issues page also shows an upgrade distance indicator on each issue row at a glance, without opening the filter. Opening an issue surfaces the full remediation guidance, including the current version, the nearest safe version, and whether the upgrade is a complete or partial fix.

{% img src="/images/vulnerabilities/reviewing-security-issues-remediation.png" alt="Issue drawer showing remediation guidance with a complete fix upgrade and Has fix indicators on the issue rows" /%}

### Exploit Maturity

| Option | Description |
|---|---|
| Known exploit | Vulnerability has a known exploit listed in the [CISA Known Exploited Vulnerabilities catalog](https://www.cisa.gov/known-exploited-vulnerabilities-catalog) |
| No known exploit | Vulnerability has no known exploit in the CISA catalog |

### EPSS

Filter by EPSS score or percentile range. EPSS (Exploit Prediction Scoring System) quantifies the probability that a given CVE will be exploited, using inputs such as code execution patterns, CVE age, and known exploits. Learn more at [first.org/epss/model](https://www.first.org/epss/model).

### CVSS Metric

Filter by individual CVSS vector components. Available metrics:

| Metric | Description |
|---|---|
| Attack Vector | How the vulnerability is exploited (Network, Adjacent, Local, Physical) |
| Attack Complexity | Complexity of the attack required to exploit the vulnerability |
| Privileges Required | Level of privileges an attacker must have before exploiting |

### Ticket

Filter by whether issues have an associated ticket. Requires a paid plan.

| Option | Description |
|---|---|
| Ticketed, Jira Integration | Issues linked via the native Jira integration |
| Ticketed, URL linked | Issues with a manually associated URL |
| Not ticketed | Issues with no ticket of any kind |

### First Found

Filter by when FOSSA first detected the issue. Requires a paid plan.

| Option | Description |
|---|---|
| Anytime | All detected issues regardless of detection date |
| Last 7 days | Issues first detected within the past 7 days |
| Last 14 days | Issues first detected within the past 14 days |
| Last 30 days | Issues first detected within the past 30 days |

### Package Manager

Filter issues to a specific ecosystem or package manager. Only ecosystems present in the current scope (global, project, or release group) appear as options.

### Project Label

Available in the **global security issues page only**. Filter to issues detected in projects that use a specific FOSSA or user-defined project label. Multiple labels are combined with OR logic.

### Ignore Reason

Available on the **Ignored** tab only. Filter ignored issues by the reason provided when they were ignored.

## Sorting

Sort the issue list by any of the following criteria:

| Sort option | Available orders |
|---|---|
| When found by FOSSA | Newest first / Oldest first |
| Package name | A→Z / Z→A |
| Severity | Highest first / Lowest first |
| Issue count per semantic version | Most issues / Fewest issues |
| EPSS score | Highest first / Lowest first |

{% callout type="info" %}
The default sort is **Issue count** when grouped by version, and **Severity (highest first)** when ungrouped. EPSS sort is only available in the ungrouped view.
{% /callout %}

## Issue grouping

By default, issues are grouped by semantic version. To switch to the ungrouped view, select **Version** in the page header and choose **Ungrouped**.

## Issue actions

Select the checkbox next to any issue to access the action menu. Available actions depend on product type, issue status, issue scope, and whether you are acting on one issue or many.

| Action | Description | Action type | Product type(s) | Status | Scope |
|---|---|---|---|---|---|
| Ignore (current version only) | Ignores the issue for the current semantic version of the affected package in the selected project(s). A new revision with any other version of the package will generate a new active issue. | Individual, bulk | Licensing, security, quality | Active | Global, release group, project |
| Ignore (auto-ignore all versions) | Ignores the issue for all semantic versions of the affected package in the selected project. Applies only to the selected issue type (denied/flagged license or CVE). Future revisions with any version of the package are auto-ignored. | Individual only | Licensing, security | Active | Project only |
| Create ticket | Creates a JIRA ticket containing the selected issues. Selecting a previously ticketed issue links it to the new ticket only. | Individual, bulk | Licensing, security, quality | Active, ignored | Global, release group, project |
| Unlink ticket | Removes the association between the selected issue(s) and any linked tickets. | Individual, bulk | Licensing, security, quality | Active, ignored | Global, release group, project |
| Download CSV | Downloads a CSV of the selected issues scoped by their current status (active or ignored). | Individual, bulk | Licensing, security, quality | Active, ignored | Global, release group, project |
| Unignore | Returns selected issue(s) from ignored to active. Does not end any existing auto-ignore rules. | Individual, bulk | Licensing, security, quality | Ignored | Global, release group, project |

### Bulk actions

To act on multiple issues at once, use the select-all checkbox or check individual issues in the global issues view.

{% img src="/images/vulnerabilities/reviewing-security-issues-bulk-actions.png" alt="Multiple issues selected with the Actions menu open, showing Ignore, Create ticket, and Generate CSV" /%}

{% callout type="warning" %}
The bulk-select checkbox selects only the issues visible on the current page. To select all matching issues across all pages, click the **Select all** link that appears after checking the checkbox.
{% /callout %}

## Issue drawer

Click anywhere on an issue row to open the issue drawer. See [Issue Details](/docs/issues/issue-details) for a full breakdown of what's shown, status, actions, vulnerability details, affected projects, and comments.

## Auto-ignore rules

Auto-ignore rules persist an ignore decision across package versions, future revisions, or other projects. Select **View Ignore Rules** from the security issues page to create and manage them. See [Auto-Ignore Rules](/docs/vulnerabilities/auto-ignore-rules) for scope options, version coverage, package label rules, and permissions.

## What's next

- **[Custom Risk Scores](/docs/vulnerabilities/custom-risk-scores)**: Override CVSS severity with context-aware scores that reflect your organization's actual exposure.
- **[Issue Exceptions (VEX)](/docs/vulnerabilities/issue-exceptions)**: Formally document why a vulnerability doesn't apply using VEX justifications.
- **[Auto-Ignore Rules](/docs/vulnerabilities/auto-ignore-rules)**: Persist ignore decisions across versions and projects to keep your issue list focused.

---

Source: https://docs.fossa.com/docs/vulnerabilities/auto-ignore-rules

# Auto-Ignore Rules

Auto-ignore rules persist an ignore decision beyond a single manual action, carrying it forward across package versions, future revisions, or other projects. Use them when you've confirmed a vulnerability or license issue isn't relevant to your use case and don't want it resurfacing on every new scan.

{% callout type="warning" %}
Auto-ignore rules apply to their selected scope for current and future projects. Use the narrowest scope that meets your needs.
{% /callout %}

Standard auto-ignore rules are scoped to the combination of **package**, **project**, and **CVE**. A separate mechanism ([package label ignore rules](#package-label-ignore-rules)) ignores issues more broadly by dependency label rather than by specific CVE.

## Where the rule applies

The ignore dialog presents both the scope and version choices when you ignore an issue.

{% img src="/images/issues-time-based-ignore-expiry.png" alt="Ignore issue dialog showing where the issue should be ignored and which versions are covered" /%}

When ignoring an issue, choose the scope:

| Scope | Description |
|---|---|
| **In this project** | Auto-ignore rule scoped to the selected project only |
| **Include release groups** | Auto-ignore rule scoped to the selected project and any release group containing it, including future release groups |
| **In this release group** | Auto-ignore rule scoped to the selected release group only *(release group security issues page only)* |
| **Globally** | Auto-ignore rule scoped to all projects and release groups |

## Which versions are ignored

Independently of scope, choose which package versions the rule covers:

| Version scope | Description |
|---|---|
| **Selected version** | Ignores the current package version only |
| **All versions** | Ignores all versions of the package, current and future |

{% callout type="info" %}
Selecting **In this project** + **Selected version** does not create an auto-ignore rule. Instead, the issue is ignored in all revisions of that project where the selected package version appears. The issue returns as active when a different package version is submitted or the package appears in a new project.
{% /callout %}

## Managing auto-ignore rules

From the security issues page (global, project, or release group), select **View Ignore Rules** to see all applicable rules.

{% callout type="info" %}
The global security issues page lists auto-ignore rules across every scope. Project and release group security issues pages list only the rules applicable to that project or release group, plus all global rules.
{% /callout %}

Each rule shows the following metadata:

| Field | Description |
|---|---|
| **Issue Ignored** | CVE being ignored (blank for package label rules) |
| **Package** | Package name (blank for package label rules) |
| **Version** | Specific package version, or **All** (blank for package label rules) |
| **Package Label** | Package label(s) the rule applies to, if this is a package label ignore rule |
| **Scope** | Global, Policy, Project, or Project + Release Group |
| **By** | User who created the rule |
| **Note** | Ignore reason provided at creation time; also shown on the issue detail |

Use the action icon on the far right of any rule row to remove it.

{% img src="/images/vulnerabilities/auto-ignore-rules-table.png" alt="View Ignore Rules page listing an auto-ignore rule with its package, version, scope, package label, creator, and note" /%}

## Package label ignore rules

Package label ignore rules are a broader alternative to per-CVE auto-ignore rules. Instead of targeting a specific vulnerability on a specific package, they ignore **all issues of a given type** (vulnerability, licensing, or quality) on any dependency that carries one or more specified [package labels](/docs/organization-management/package-labels).

Create them from the **View Ignore Rules** page rather than from an individual issue. You must select at least one package label. The rule applies whenever a dependency carries that label, regardless of the specific CVE or version.

The scope options (project, release group, globally) apply to package label rules in the same way as standard auto-ignore rules.

## Permissions

| Scope | Required permissions |
|---|---|
| Project | `Resolve Security issues of projects` for the selected project or for all projects |
| Release group | `Resolve Security issues of release group` and access to the selected release group or all projects/release groups |
| Project + release group | `Resolve Security issues of project` and `Resolve Security issues of release group`; access to the selected project and access to *all release groups* |
| Global | `Resolve Security issues of project` and `Resolve Security issues of release group`; access to *all projects and release groups* |

## What's next

- **[Reviewing Security Issues](/docs/vulnerabilities/reviewing-security-issues)**: Manage active issues and see the impact of your ignore rules in the inbox.
- **[Custom Risk Scores](/docs/vulnerabilities/custom-risk-scores)**: Pair ignore rules with custom risk scores to further refine how vulnerabilities are prioritized.

---

Source: https://docs.fossa.com/docs/vulnerabilities/custom-risk-scores

# Custom Risk Scores

Custom Risk Scores let you override the standard CVSS severity of a vulnerability issue with a score that reflects your organization's internal risk exposure. With Custom Risk Scores, your security team can assign a context-aware severity score to any vulnerability issue, make it the primary severity displayed across FOSSA, and filter and triage issues based on your own assessments rather than third-party scores alone.

## How it works

When you assign a custom risk score to a vulnerability issue:

- The custom score **replaces the CVSS badge** as the primary severity displayed in the issues list and issue details.
- The original CVSS score remains visible in the **Vulnerability Details** section for reference.
- The custom score, the reason you provided, and who assigned it are all displayed in the issue details drawer.
- The score can be **edited or removed** at any time, reverting the issue back to its standard CVSS severity.

All actions (create, update, delete) are recorded in FOSSA's **Audit Log**.

## Severity thresholds

Custom Risk Scores use a 0–100 scale. The score maps to severity levels as follows:

| Score Range | Severity Level |
|---|---|
| 90 – 100 | Critical |
| 70 – 89 | High |
| 40 – 69 | Medium |
| 0 – 39 | Low |

Unlike CVSS (where a null score means the severity is unknown), a custom risk score of `0` is an intentional **Low** rating, not an absence of data.

## Assigning a custom risk score

### From the UI

{% steps %}
{% step title="Open the Security tab" %}
Navigate to a **Project** or **Release Group** and open the **Issues → Security** tab.
{% /step %}
{% step title="Open the issue drawer" %}
Click on a vulnerability issue to open the issue details drawer.
{% /step %}
{% step title="Start assigning a score" %}
In the action buttons area, click **Assign custom risk score** (or **Edit custom risk score** if one already exists).
{% /step %}
{% step title="Enter the score and reason" %}
In the drawer that opens:

- Enter a **score** between 0 and 100 (whole numbers only).
- Optionally provide a **reason** (up to 500 characters) explaining why you chose this score. For example: *"Not exploitable in our environment, internal service only."*
{% /step %}
{% step title="Save" %}
Click **Save**. The issues list refreshes automatically to reflect the new custom risk score.
{% /step %}
{% /steps %}

### From the API

You can also manage custom risk scores programmatically using the FOSSA API.

```
POST /api/custom-risk-scores/:issueId?scope[type]={scope}&scope[id]={scopeId}
```

**Path parameter:**

- `issueId`: The numeric ID of the vulnerability issue.

**Query parameters:**

- `scope[type]`: Either `project` or `release_group`.
- `scope[id]`: The project locator (e.g. `npm+my-package`) or release group ID.

{% requestExamples %}
{% requestExample language="curl" %}
```bash
curl -X POST "https://app.fossa.com/api/custom-risk-scores/12345?scope[type]=project&scope[id]=npm+my-package" \
  -H "Authorization: Bearer $FOSSA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"score": 25, "reason": "Not exploitable in our environment — internal service only."}'
```
{% /requestExample %}
{% requestExample language="python" %}
```python
import requests

resp = requests.post(
    "https://app.fossa.com/api/custom-risk-scores/12345",
    params={"scope[type]": "project", "scope[id]": "npm+my-package"},
    headers={"Authorization": "Bearer <FOSSA_TOKEN>"},
    json={"score": 25, "reason": "Not exploitable in our environment — internal service only."},
)
```
{% /requestExample %}
{% requestExample language="node" %}
```js
const params = new URLSearchParams({
  "scope[type]": "project",
  "scope[id]": "npm+my-package",
});
const res = await fetch(`https://app.fossa.com/api/custom-risk-scores/12345?${params}`, {
  method: "POST",
  headers: {
    Authorization: "Bearer <FOSSA_TOKEN>",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    score: 25,
    reason: "Not exploitable in our environment — internal service only.",
  }),
});
```
{% /requestExample %}
{% /requestExamples %}

**Request body fields:**

| Field | Type | Required | Description |
|---|---|---|---|
| `score` | integer | Yes | Integer between 0 and 100 (inclusive). |
| `reason` | string | No | Justification for the score. Max 500 characters. |

**Response (201 Created):**

```json
{
  "issueId": 12345,
  "score": 25,
  "reason": "Not exploitable in our environment — internal service only.",
  "scope": "project",
  "scopeId": "npm+my-package"
}
```

## Editing a custom risk score

### From the UI

{% steps %}
{% step title="Open the issue drawer" %}
Open the issue details drawer for a vulnerability that already has a custom risk score.
{% /step %}
{% step title="Edit the score" %}
Click **Edit custom risk score**.
{% /step %}
{% step title="Save your changes" %}
Update the score and/or reason, then click **Save**.
{% /step %}
{% /steps %}

{% img src="/images/custom-risk-scores-edit-drawer.png" alt="Edit Custom Risk Score drawer showing the score field, severity range legend, and reason field" /%}

### From the API

```
PATCH /api/custom-risk-scores/:issueId?scope[type]={scope}&scope[id]={scopeId}
```

{% requestExamples %}
{% requestExample language="curl" %}
```bash
curl -X PATCH "https://app.fossa.com/api/custom-risk-scores/12345?scope[type]=project&scope[id]=npm+my-package" \
  -H "Authorization: Bearer $FOSSA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"score": 60, "reason": "Upgraded mitigations in place — downgraded from Critical."}'
```
{% /requestExample %}
{% requestExample language="python" %}
```python
import requests

resp = requests.patch(
    "https://app.fossa.com/api/custom-risk-scores/12345",
    params={"scope[type]": "project", "scope[id]": "npm+my-package"},
    headers={"Authorization": "Bearer <FOSSA_TOKEN>"},
    json={"score": 60, "reason": "Upgraded mitigations in place — downgraded from Critical."},
)
```
{% /requestExample %}
{% requestExample language="node" %}
```js
const params = new URLSearchParams({
  "scope[type]": "project",
  "scope[id]": "npm+my-package",
});
const res = await fetch(`https://app.fossa.com/api/custom-risk-scores/12345?${params}`, {
  method: "PATCH",
  headers: {
    Authorization: "Bearer <FOSSA_TOKEN>",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    score: 60,
    reason: "Upgraded mitigations in place — downgraded from Critical.",
  }),
});
```
{% /requestExample %}
{% /requestExamples %}

Pass `"reason": null` to clear an existing reason without providing a new one.

## Removing a custom risk score

### From the UI

{% steps %}
{% step title="Open and edit" %}
Open the issue details drawer and click **Edit custom risk score**.
{% /step %}
{% step title="Remove the score" %}
Click **Remove Custom Score** and confirm. The issue reverts to its standard CVSS severity.
{% /step %}
{% /steps %}

### From the API

```
DELETE /api/custom-risk-scores/:issueId?scope[type]={scope}&scope[id]={scopeId}
```

{% requestExamples %}
{% requestExample language="curl" %}
```bash
curl -X DELETE "https://app.fossa.com/api/custom-risk-scores/12345?scope[type]=project&scope[id]=npm+my-package" \
  -H "Authorization: Bearer $FOSSA_TOKEN"
```
{% /requestExample %}
{% requestExample language="python" %}
```python
import requests

resp = requests.delete(
    "https://app.fossa.com/api/custom-risk-scores/12345",
    params={"scope[type]": "project", "scope[id]": "npm+my-package"},
    headers={"Authorization": "Bearer <FOSSA_TOKEN>"},
)
```
{% /requestExample %}
{% requestExample language="node" %}
```js
const params = new URLSearchParams({
  "scope[type]": "project",
  "scope[id]": "npm+my-package",
});
const res = await fetch(`https://app.fossa.com/api/custom-risk-scores/12345?${params}`, {
  method: "DELETE",
  headers: { Authorization: "Bearer <FOSSA_TOKEN>" },
});
```
{% /requestExample %}
{% /requestExamples %}

Returns `204 No Content` on success.

## Filtering issues by severity source

On the **Issues → Security** filter panel (within a project or release group), a **Severity Source** filter lets you narrow results based on how the severity was determined:

- **Standard (CVSS)**: Shows issues whose displayed severity is derived from the standard CVSS score.
- **Custom Risk Score**: Shows only issues that have a custom risk score assigned.

You can select one or both options. The filter is not available in the Global issues view, where custom risk scores are not applied.

### Filtering via the API

Use the `filter[severitySource][]` and `filter[severity][]` query parameters on the issues endpoint:

```
GET /api/v2/issues?category=vulnerability
  &scope[type]=project
  &scope[id]={projectLocator}
  &filter[severitySource][0]=custom
  &filter[severity][0]=critical
```

`severitySource` accepts `standard` and/or `custom`. When omitted, the filter defaults to standard CVSS behavior.

## Viewing custom risk score details

When a vulnerability issue has a custom risk score, the issue details drawer displays a dedicated **Custom Risk Score** section showing:

- The score and its severity badge (e.g., *Low 25*).
- The reason provided, or *"No reason given"* if none was entered.
- **Assigned by**: the email address of the team member who created the score.

The original CVSS score remains visible in the **Vulnerability Details** section below.

{% img src="/images/custom-risk-scores-details.png" alt="Custom risk score section showing a Low 37 badge, the reason, and the assigning user" /%}

## Retrieving custom risk scores via the Issues API

The `GET /api/v2/issues` endpoint includes a `customRiskScore` field in each vulnerability issue response when a custom score has been assigned in the requested scope:

```json
{
  "results": [
    {
      "id": 12345,
      "title": "CVE-2024-XXXX in lodash",
      "cvssScore": 9.8,
      "customRiskScore": {
        "score": 25,
        "reason": "Not exploitable in our environment.",
        "createdBy": "alice@example.com"
      }
    }
  ]
}
```

The `customRiskScore` field is omitted when no custom score exists for that issue in the given scope, or when querying at global scope.

## Permissions

Managing custom risk scores requires **Edit** permission on the project or release group. Users with only **View** permission can see custom risk scores but cannot assign, edit, or remove them.

## Audit log

All custom risk score actions are recorded in FOSSA's Audit Log:

| Action | Logged When |
|---|---|
| Created | A custom risk score is assigned to an issue. |
| Updated | An existing score or reason is changed. |
| Deleted | A custom risk score is removed. |

Each entry includes the acting user, the issue, scope, and the old and new score values where applicable.

## Frequently asked questions

**Does a custom risk score affect policy evaluation?**
Custom risk scores affect how issues are displayed and filtered in FOSSA. Check your organization's policy configuration for whether policies evaluate standard CVSS severity or custom risk score severity.

**Can I assign a custom risk score at the global level?**
No. Custom risk scores are scoped to a specific project or release group. This ensures that a score reflects the context of how a dependency is used in a particular codebase, not universally across all projects.

**What happens if I remove a custom risk score?**
The issue reverts to displaying its standard CVSS-based severity. The custom score history is preserved in the audit log.

**Can the same vulnerability have different custom risk scores in different projects?**
Yes. Because scores are scoped to a project or release group, you can assign a different score to the same vulnerability depending on how it is used in each context.

**Is the original CVSS score still available after I assign a custom score?**
Yes. The original CVSS score remains visible in the Vulnerability Details section of the issue drawer at all times.

## What's next

- **[Reviewing Security Issues](/docs/vulnerabilities/reviewing-security-issues)**: Filter and sort issues using your custom risk scores to prioritize remediation.
- **[Auto-Ignore Rules](/docs/vulnerabilities/auto-ignore-rules)**: Suppress issues that don't apply to your environment across future scans.

---

Source: https://docs.fossa.com/docs/vulnerabilities/issue-exceptions

# Issue Exceptions (VEX)

Issue Exceptions let you formally mark a vulnerability issue as not applicable in your environment, using a structured VEX (Vulnerability Exploitability eXchange) justification. Unlike a simple ignore, an exception documents the specific reason why the vulnerability cannot be exploited in your context, producing defensible, auditable records for security reviews and compliance programs.

{% callout type="info" %}
VEX is an industry standard for communicating vulnerability exploitability status. A VEX statement says: "This CVE exists in our software, but it is not exploitable because of *X*." VEX is recognized by CISA and is compatible with CycloneDX and SPDX SBOM formats.
{% /callout %}

## How Issue Exceptions work

When you create an exception on a vulnerability issue:

- The issue's status changes to **Ignored** in the issues list.
- The exception records the VEX justification and an optional note.
- Policy checks re-evaluate the issue with its new status; an excepted issue typically no longer counts toward a policy failure.
- The exception is recorded in the [Audit Log](/docs/organization-management/audit-logs) with the user, justification, and timestamp.

## VEX justification categories

FOSSA supports the standard VEX justification categories plus additional resolution reasons:

| Justification | Meaning |
|---|---|
| **Component not present** | The vulnerable component is listed as a dependency but is not actually included in the built artifact |
| **Vulnerable code not present** | The vulnerable code path exists in the package but is not included in this project's build |
| **Vulnerable code not in execute path** | The vulnerable code is present but cannot be reached during execution in this deployment |
| **Vulnerable code cannot be controlled by adversary** | The vulnerable code can be reached but the attacker cannot control the inputs needed to exploit it |
| **Inline mitigations already exist** | A separate control (WAF, network policy, etc.) prevents exploitation |
| **Fixed** | The issue has been resolved |
| **Under investigation** | The issue is being assessed |
| **Incorrect data found** | The vulnerability data is inaccurate for this package |
| **Other** | A reason not covered by the above categories |

## Creating an exception

{% steps %}
{% step title="Open the vulnerability issue" %}
Navigate to a project or release group, open the **Issues** tab, and click the vulnerability to open its detail drawer.

{% img src="/images/issue-exceptions-issues-list.png" alt="Project vulnerability issues list with the Active tab selected" /%}
{% /step %}
{% step title="Ignore the issue" %}
Click **Ignore** in the issue action buttons. This opens the exception modal.

{% img src="/images/issue-exceptions-issue-detail.png" alt="Vulnerability issue detail with the Ignore button in the action buttons row" /%}
{% /step %}
{% step title="Choose a scope" %}
Select where this exception applies:

- **Organization**: applies across the entire organization
- **Policy**: applies to all projects using a specific policy
- **Project**: applies to this project only
- **Release Group**: applies to a specific release group
- **Project and Release Groups**: applies to the project and all release groups using it
{% /step %}
{% step title="Choose a package scope" %}
Select whether the exception applies to the **selected version only** or **all versions** of the package (including future versions).
{% /step %}
{% step title="Choose a VEX justification" %}
Select one of the justification categories from the dropdown.

{% img src="/images/issue-exceptions-justification.png" alt="Ignore issue modal with the Reason for ignoring dropdown open showing the VEX justification categories" /%}
{% /step %}
{% step title="Add a note and expiration" %}
Optionally enter a free-text explanation and set an expiration date after which the exception is no longer active.

{% img src="/images/issue-exceptions-expiration.png" alt="Ignore issue modal with the expiration dropdown open showing duration options" /%}
{% /step %}
{% step title="Save" %}
Click **Save**. The issue status updates immediately.
{% /step %}
{% /steps %}

## Viewing and managing exceptions

Excepted issues appear in the issues list with an **Ignored** status. Each excepted issue displays the VEX justification category and, if provided, the explanatory note.

To remove an exception and return an issue to its original state, open the issue details and click **Remove Exception**. The issue reverts to open and becomes subject to policy evaluation again.

## VEX annotations in SBOM exports

When you export a CycloneDX SBOM from FOSSA, excepted vulnerability issues are included as VEX annotations in the SBOM document. Each annotation includes the VEX state, the justification category, and any resolution note you provided.

See [Generating SBOMs](/docs/sbom/generating-sboms) for how to export a CycloneDX SBOM.

## Permissions

Creating and removing issue exceptions requires **Edit** permission on the project or release group. Viewers can see exceptions but cannot create or remove them.

## Audit log

All exception actions are recorded:

| Action | When logged |
|---|---|
| Exception created | An exception is applied to an issue |
| Exception updated | The justification or note is changed |
| Exception removed | An exception is deleted from an issue |

## FAQ

**How is an exception different from ignoring an issue?**
The **Ignore** action is the same flow; exceptions are how FOSSA records ignores with a formal VEX justification. Use the VEX justification options to document your exploitability assessment in an auditable way.

**Does an exception apply to all projects?**
By default, exceptions are scoped to a single project or release group. You can also scope them to a policy or the entire organization when creating the exception.

**Do exceptions affect policy checks?**
Yes. Ignored issues are excluded from policy evaluation. Review your security policy configuration to confirm how exceptions interact with your rules; see [Security Policy](/docs/policies/security-policy).

**Are exceptions preserved in future scans?**
Yes. Exceptions persist across scans until explicitly removed or until they expire (if an expiration date was set). If the vulnerable package version is removed in a future scan, the exception becomes inactive but is not deleted.

---

Source: https://docs.fossa.com/docs/vulnerabilities/container-scanning

# Container Scanning

Container scanning lets you analyze container images for vulnerability and license issues alongside your standard FOSSA projects. The scanner inspects both OS-level dependencies (APK, DPKG, RPM) and application dependencies inside the image, and reports issues through the same policies and Security Issues page you use for source code projects. For setup instructions (supported base images, image sources, and CLI usage) see [Containers](/docs/project-setup/containers).

{% callout type="info" %}
Container scanning is available on Business and Enterprise plans.
{% /callout %}

## How container scanning works

The FOSSA CLI's `container` subcommand handles scanning. It accepts images from multiple sources (a local Docker engine, an exported archive, or any OCI-compatible registry) and uploads dependency metadata to FOSSA for analysis. No source code or file contents are sent.

Scans run in two steps:

1. The **base layer** is scanned independently.
2. All remaining layers are squashed and scanned together.

Issues are surfaced through your existing security and license policies, the same as any other FOSSA project. The [Container Layer filter](/docs/vulnerabilities/reviewing-security-issues#filters) on the Security Issues page lets you scope results to specific layers.

## What gets analyzed

The scanner detects OS package managers (Alpine APK, Debian DPKG, RedHat RPM) and a wide range of application package managers. Java JAR files embedded in layers are also detected and matched against FOSSA's vulnerability database.

For the full list of supported package managers and their support level, see the [container scanner reference](/docs/cli/references/subcommands/container/scanner#supported-container-package-managers).

## Getting started

{% callout type="info" %}
Container scanning requires FOSSA CLI. See the [CLI installation guide](/docs/cli) for setup instructions.
{% /callout %}

The core workflow is two commands:

```bash
# Analyze the image and upload results to FOSSA
fossa container analyze <IMAGE>

# Check for issues against your policy (exits non-zero if issues are found)
fossa container test <IMAGE>
```

`<IMAGE>` can be a Docker image name, a registry reference, or a path to an exported `.tar` archive. For detailed usage including private registries, Podman, Buildah, and CI integration examples, see:

- [Container scanner reference](/docs/cli/references/subcommands/container/scanner): image sources, supported package managers, configuration, debugging, and FAQs
- [Walkthrough: Integrating container scanning in CI](/docs/cli/walkthroughs/container-scanning-generic-ci): end-to-end examples with Docker, Podman, and Buildah

---

Source: https://docs.fossa.com/docs/vulnerabilities/sbom-vulnerability-detection

# Vulnerability Detection in Imported SBOMs

When you import an SBOM into FOSSA, the system attempts to identify vulnerabilities for each package it contains. The matching method (and the confidence of the result) depends on what identifiers the SBOM provides.

## CPE-based matching

A CPE (Common Platform Enumeration) is a standardized identifier for software components, defined by NIST. SBOMs may include CPEs to describe packages. When FOSSA encounters a CPE during import, it attempts to match the package against its vulnerability database using that identifier.

Because CPEs allow wildcards (`*`) in fields like OS, ecosystem, and version range, they offer variable precision. A CPE with specific version information produces tighter matches than one with wildcards. FOSSA cannot independently verify the accuracy of a user-provided CPE.

Learn more about the CPE specification at [NIST's Security Content Automation Protocol](https://csrc.nist.gov/projects/security-content-automation-protocol/specifications/cpe).

## How CPE-matched vulnerabilities appear

Issues identified through CPE matching are flagged as **Unverified** throughout the Security Issues page. The tooltip on the badge reads: *"This vulnerability was identified based on a CPE with limited context in the SBOM and could not be verified by FOSSA."*

When you open the issue drawer for an Unverified issue, a banner confirms the source: *"This vulnerability was supplied by the SBOM. Accuracy cannot be verified by FOSSA's analysis."*

Unverified issues should be reviewed with this context in mind. The vulnerability may or may not apply to the specific package version in your project.

## Why CPEs resolve poorly

CPE-based matching is inherently imprecise for several reasons:

**Wildcard fields.** The CPE format allows `*` in place of specific values for fields like version, product, and vendor. A CPE of `cpe:2.3:a:vendor:product:*:...` means "any version", so FOSSA cannot determine whether the specific version in your project is actually affected and must treat all matching vulnerabilities as candidates rather than confirmed hits.

**No ecosystem context.** A CPE doesn't encode which package registry a dependency comes from. When an SBOM entry has a CPE but no locator that FOSSA can resolve to a known ecosystem, FOSSA falls back to the broadest available CVE dataset (Debian) to attempt version range comparisons. This means a Python, npm, or Go package may be compared against Linux system package vulnerability ranges, producing both false positives and false negatives.

**Vendor and product name mismatches.** CPE vendor and product fields often don't align with package registry names. For example, `cpe:2.3:a:apache:log4j:2.14.1` refers to the same library as Maven's `org.apache.logging.log4j:log4j-core`, but FOSSA has to resolve that mapping heuristically rather than by exact lookup.

**Version range epoch stripping.** Some ecosystems encode version epochs (e.g. `1:2.14.1-1`) in their CVE data. When FOSSA compares a CPE-sourced version against these ranges, it strips epoch tokens to make the comparison possible, which can cause matches to be missed or overapplied.

## Using PURLs for more accurate matching

A [PURL](https://github.com/package-url/purl-spec) (Package URL) eliminates all of these issues. PURLs encode the ecosystem, package name, and exact version in a standardised format, for example, `pkg:maven/org.apache.logging.log4j/log4j-core@2.14.1` or `pkg:npm/lodash@4.17.11`. This gives FOSSA an unambiguous identifier to match directly against its vulnerability database without fallback heuristics, wildcard handling, or ecosystem guesswork.

When your SBOM contains PURLs, FOSSA resolves each dependency to a precise locator and applies the same high-confidence vulnerability matching it uses for CLI-analyzed projects. Issues found this way are not marked Unverified.

To generate an SBOM with accurate PURLs automatically, integrate your codebase with FOSSA and use the CLI to produce the SBOM rather than importing a hand-authored one.

---

Source: https://docs.fossa.com/docs/vulnerabilities/automated-malware-detection

# Automated Malware Detection

Automated malware detection finds dependencies that have been identified as malicious, so you can catch supply-chain compromises before they reach production. Unlike a vulnerability, which is an unintentional security flaw, malware is code published with intent to harm, for example a hijacked package release or a typosquatted lookalike.

FOSSA flags malicious dependencies as a **Quality** issue and can fail your CI/CD checks when one is found, acting as a hard gate against compromised packages entering your codebase.

{% callout type="info" %}
Malware detection surfaces as a quality issue and is configured through your quality policy, even though it addresses a security concern. For known security flaws (CVEs), see [Reviewing security issues](/docs/vulnerabilities/reviewing-security-issues).
{% /callout %}

## How it works

Every time FOSSA analyzes a project, the quality scanner cross-references each direct and transitive dependency against known malware reports drawn from multiple data sources. When a package version matches a report, FOSSA raises a **Malware** quality issue for it. Because the underlying data is updated continuously, a dependency can be flagged on a later scan even if an earlier scan was clean.

A malware issue carries the report that identified it:

| Field | Description |
|---|---|
| **Name** | The malware report's title |
| **Description** | Details of why the package is considered malicious |
| **Read more** | A link to the full upstream report |

## Enabling malware detection

Malware detection is a rule on your [quality policy](/docs/policies/quality-policy) and runs as part of [quality scanning](/docs/quality/quality-scanning). For enterprise organizations with quality enabled, it is turned on automatically.

{% steps %}
{% step title="Turn on quality scanning" %}
Enable the quality scanner so FOSSA evaluates your dependencies. Organization-level defaults live at **Organization Settings > Projects > Issues**; you can override them per project at **Project Settings > Issue Policies**. See [Quality Scanning](/docs/quality/quality-scanning).
{% /step %}
{% step title="Enable the Malware Detection rule" %}
On the quality policy applied to your projects, enable **Malware Detection**. This rule "detects dependencies identified as malicious by cross-referencing packages against known malware reports."

{% img src="/images/automated-malware-detection-policy-rule.png" alt="Quality policy Risk Intelligence section with the Malware Detection rule enabled" /%}
{% /step %}
{% step title="Gate your builds (optional)" %}
Turn on **Fail CI/CD checks** for the quality scanner so a detected malicious dependency fails the project's status check and [`fossa test`](/docs/cli/references/subcommands/test), blocking the change from merging.
{% /step %}
{% /steps %}

## Reviewing malware issues

Malicious dependencies appear alongside your other findings in the **Issues** tab:

1. Open the **Issues** tab and select the **Quality** issue category.
2. In the **Issue Type** filter, select **Malware**.
3. Open an issue to see the malware report's name, description, and a link to read more.

{% img src="/images/automated-malware-detection-issues-list.png" alt="Issues tab listing a dependency flagged with a Malware badge and Malicious Dependency Identified" /%}

{% img src="/images/automated-malware-detection-issue-detail.png" alt="Malware issue details showing the report name, description, and a Read more link" /%}

A flagged dependency also shows a **Malicious Dependency** banner in its details drawer on the project's dependencies view, linking directly to the issue.

To resolve a malware issue, remove or replace the affected dependency. See [Reviewing Quality Issues](/docs/quality/reviewing-quality-issues) for triage workflows shared across quality issue types.

## How it differs from vulnerability detection

| | Automated malware detection | Vulnerability detection |
|---|---|---|
| **What it finds** | Packages published with malicious intent (supply-chain attacks) | Known security flaws (CVEs) in legitimate packages |
| **Issue category** | Quality | Security |
| **Source** | Known malware reports | [Vulnerability data sources](/docs/vulnerabilities/vulnerability-data-sources) |
| **Typical response** | Remove or replace the package immediately | Triage by severity and reachability, then remediate |

## Further reading

- [Quality Scanning](/docs/quality/quality-scanning): how the quality scanner runs and gates CI/CD.
- [Quality Policies](/docs/policies/quality-policy): configure the Malware Detection rule and other quality rules.
- [Reviewing security issues](/docs/vulnerabilities/reviewing-security-issues): triage known vulnerabilities.

---

Source: https://docs.fossa.com/docs/vulnerabilities/vulnerability-data-sources

# How FOSSA Sources Vulnerability Data

FOSSA builds its vulnerability dataset by aggregating data from a number of sources, running it through a review pipeline, and matching the reviewed results against the dependencies in your projects. This means the vulnerabilities you see in FOSSA have been collected, validated, and mapped specifically to the packages you use.

## Data collection

FOSSA collects vulnerability data from a number of sources rather than relying on any single feed. Primary examples include the [National Vulnerability Database (NVD)](https://nvd.nist.gov/) and [GitHub Security Advisories](https://github.com/advisories), and additional sources such as OSS Index and RustSec contribute coverage for specific ecosystems. Drawing from many sources (16 and counting) improves coverage and reduces the chance that a vulnerability is missed because it is absent from one particular feed.

All collected vulnerabilities are stored in FOSSA's database for processing.

## Review

Collected vulnerabilities pass through a review pipeline that combines both human and automated review. This pipeline determines whether each vulnerability is valid, should be rejected, or needs further investigation, and tracks each entry's review status (for example: completed, in review, or rejected). Combining automated processing with human judgment helps reduce false positives while keeping coverage broad.

## Vulnerability matching

After review, FOSSA produces "vulnerability calculations" that map specific package versions to CVEs along with the affected version ranges. Conceptually, the data is structured as:

```
dependency locator → CVE → affected version range
```

Your project's dependencies are then matched against these reviewed vulnerabilities.

## What you see

The vulnerabilities surfaced in your FOSSA dashboard have been:

- Collected from a number of security sources
- Reviewed through FOSSA's combined human and automated pipeline
- Mapped to your specific dependencies
- Filtered for relevance to your project

The goal of this process is to reduce false positives while ensuring you remain aware of legitimate security issues affecting your dependencies.

---

Source: https://docs.fossa.com/docs/vulnerabilities/vulnerability-service-api-token-provisioning

# Vulnerability Service API Token Provisioning

Vulnerability service endpoints (such as the [snapshot download](/docs/vulnerabilities/vulnerability-snapshot)) use a dedicated token, separate from your main FOSSA API token.

## Requesting a token

Email [support@fossa.com](mailto:support@fossa.com) with the subject line **"Vulnerability Snapshot API Keys"**. FOSSA support will provision and return a **key ID** and **key secret**.

## Using the token

Include the token in the `Authorization` header on every request to a vulnerability service endpoint:

```
Authorization: token <keyId>:<keySecret>
```

Documentation for each endpoint that requires this token will repeat the header format inline.

---

Source: https://docs.fossa.com/docs/vulnerabilities/vulnerability-snapshot

# Vulnerability Snapshot Downloads

FOSSA publishes its full vulnerability dataset as a downloadable snapshot. A single authenticated `GET` request returns a pre-signed AWS S3 URL; following that URL downloads a gzipped tarball of the complete dataset in JSON format. The snapshot is updated daily.

{% callout type="info" %}
You need a Vulnerability Service API **token ID** and **token secret** to authenticate. See [Vulnerability Service API Token Provisioning](/docs/vulnerabilities/vulnerability-service-api-token-provisioning) for how to obtain them.
{% /callout %}

## Downloading the vulnerability snapshot

{% steps %}
{% step title="Request a pre-signed download URL" %}
Make a `GET` request to the snapshot endpoint:

```
GET https://vulns.fossa.com/api/vulns/snapshot
Authorization: token <tokenId>:<tokenSecret>
```

On success, the response body is:

```json
{ "url": "string" }
```

On failure, the response includes an error description and a UUID. If you cannot resolve the issue, contact [support@fossa.com](mailto:support@fossa.com) and include the error UUID.
{% /step %}
{% step title="Download the snapshot" %}
Make a `GET` request to the `url` value returned in the previous step. The file is a gzipped tarball containing the full vulnerability dataset as an array of JSON objects.
{% /step %}
{% /steps %}

## Snapshot schema

Each object in the array conforms to this schema:

| Field | Description |
|---|---|
| `fetcher` | Package type of the affected package (e.g. `mvn`, `deb`, `npm`) |
| `package` | Name of the affected package |
| `cve` | CVE identifier, or `null` if the vulnerability has no CVE |
| `cwes` | CWEs associated with the vulnerability, or `null` if unavailable |
| `cvssV2Vector` | CVSS v2 enum vector |
| `cvssV3Vector` | CVSS v3 enum vector |
| `cvssV4Vector` | CVSS v4 enum vector |
| `cvss` | FOSSA-computed severity score, or `null` if unavailable |
| `affectedVersionRanges` | Version ranges affected by this vulnerability |
| `description` | Long-form explanation of the vulnerability, or `null` if unavailable |
| `epssSscore` | EPSS score, likelihood of exploitation in the wild (higher = more predictable, less sophisticated exploit) |
| `epssPercentile` | EPSS percentile rank relative to all other vulnerabilities in the dataset |
| `exploitability` | Exploit maturity, sourced from the CISA Known Exploits catalog |
| `published` | Date the vulnerability was published (ISO datetime string) |
| `references` | Links to external references such as disclosures, writeups, and post-mortems |
| `createdAt` | When FOSSA first created this vulnerability entry (ISO datetime string) |
| `updatedAt` | When FOSSA last updated this vulnerability entry (ISO datetime string) |

## IP allowlist for on-premises deployments

If your on-premises installation is behind a firewall, allowlist the following to reach the snapshot service and its file storage:

- `vulns.fossa.com`
- AWS S3, `us-west-2` region

---

Source: https://docs.fossa.com/docs/quality

# Quality

Beyond licenses and CVEs, the long-term risk of a dependency comes from how well it's maintained. FOSSA's quality scanner evaluates every direct and transitive dependency and raises a quality issue (in the project's **Issues** tab) when a package is outdated, blocked, or shows a supply-chain risk signal.

## What this covers

- **[Understanding Quality Issues](/docs/quality/understanding-quality-issues)**: what each issue type means: outdated versions, blocked packages, and the risk-intelligence signals (abandonware, empty packages, native code).
- **[Reviewing Quality Issues](/docs/quality/reviewing-quality-issues)**: triage and resolve quality issues across your projects.
- **[Quality Scanning](/docs/quality/quality-scanning)**: how quality issues are generated and gated in CI/CD.

## Put it to work

- Use **[Quality Policies](/docs/policies/quality-policy)** to gate on quality thresholds across your projects, so unhealthy dependencies raise issues automatically.
- Review what FOSSA finds alongside your [licensing](/docs/licenses) and [security](/docs/vulnerabilities) issues; the same triage workflow surfaces all three.

---

Source: https://docs.fossa.com/docs/quality/understanding-quality-issues

# Understanding Quality Issues

When FOSSA analyzes a project, the quality scanner evaluates each dependency's health and maintenance against your quality policy and FOSSA's risk-intelligence signals. Anything that needs attention surfaces as a quality issue in the **Issues** tab.

{% img src="/images/understanding-quality-issues-inbox.png" alt="FOSSA Issues tab listing quality issues by type" /%}

## Issue types

There are five quality issue types. The first two are **policy-driven** (they fire based on rules you configure in a [quality policy](/docs/policies/quality-policy). The last three are **risk-intelligence signals**) they fire when FOSSA detects a supply-chain risk in the published package itself.

| Issue type | API type | What triggers it |
|---|---|---|
| **Outdated version** | `outdated_dependency` | A dependency is further behind the latest release than your Stale Package Prevention rule allows. |
| **Package blocked** | `blacklisted_dependency` | A dependency matches a package your organization has blocked (deny-listed). |
| **Abandonware** | `risk_abandonware` | The package has had no maintainer activity (a new publish) for an extended period. |
| **Empty package** | `risk_empty-package` | The published package contains no runnable code. |
| **Native code** | `risk_native-code` | The package embeds compiled, executable binaries. |

## What each type means

### Outdated version

FOSSA compares each dependency's version against the latest available release. Stale Package Prevention rules flag a dependency once it is more major, minor, or patch versions behind than you allow; the exact distance is configurable per version part in your quality policy. Resolve by upgrading the dependency, or tune the threshold in the policy.

### Package blocked

A blocked package is one your organization has explicitly deny-listed from the Packages inventory. Blocked packages are reported across the organization and **fail `fossa test`** in [CI/CD](/docs/integrations/fail-cicd-checks), preventing them from reaching production. Resolve by removing or replacing the dependency, or by unblocking the package. See [Quality Policies](/docs/policies/quality-policy) for how blocking works.

### Abandonware

FOSSA flags a package as abandonware when it has had no new publish for **two years**. An abandoned package is a supply-chain risk: if a vulnerability or bug is later discovered, a fix is unlikely to ship. Available for npm, PyPI, and Maven dependencies.

### Empty package

An empty package is one that ships no runnable code, often a sign of faulty publication, name-squatting, or a package at risk of being unpublished. FOSSA considers a package empty when none of the expected code filetypes are present:

| Ecosystem | Code filetypes checked |
|---|---|
| **npm** | `.js`, `.jsx`, `.ts`, `.tsx`, `.ejs`, `.mjs`, `.cjs` |
| **PyPI** | `.py`, `.pyc`, `.pyd`, `.dll` |
| **Maven** | `.class`, `.java`, and `classes.jar` |

### Native code

FOSSA flags packages that embed compiled, executable binaries. Binaries can obfuscate intent and break across deployment environments, so FOSSA lists the offending files so you can investigate. The detected filetypes expand over time and include `.exe`, `.dmg`, `.deb`, `.rpm`, `.wasm`, `.wat`, `.swf`, `.eps`, and `.crx`. Available for npm and PyPI dependencies.

## Issue status

Every issue is either **active** (unresolved) or **ignored** (manually dismissed). Ignoring an issue does not resolve the underlying problem; it suppresses the issue from blocking CI checks. Use ignore sparingly and with a documented reason.

## What's next

- **[Reviewing Quality Issues](/docs/quality/reviewing-quality-issues)**: how to triage and resolve active issues.
- **[Quality Policies](/docs/policies/quality-policy)**: how Stale Package Prevention, blocked packages, and risk-intelligence rules are configured.
- **[Quality Scanning](/docs/quality/quality-scanning)**: how quality issues are generated and gated in CI/CD.

---

Source: https://docs.fossa.com/docs/quality/reviewing-quality-issues

# Reviewing Quality Issues

The issues inbox is where you triage, resolve, and track quality issues. You can review quality issues globally (across all projects), within a single project, or within a release group. From the main **Issues** tab, select **Quality**.

Issues are split into two tabs:

- **Active**: issues that require attention
- **Ignored**: issues that have been reviewed and suppressed

For a breakdown of what each issue type means, see [Understanding Quality Issues](/docs/quality/understanding-quality-issues).

{% img src="/images/reviewing-quality-issues-inbox.png" alt="Quality issues inbox showing the filter panel, sort, and grouping controls" /%}

## Filtering

### Depth

| Option | Shows |
|---|---|
| **Direct** | Issues on direct dependencies only |
| **Transitive** | Issues on transitive (indirect) dependencies only |

### Issue Type

| Option | Shows |
|---|---|
| **Outdated Version** | Issues generated by Stale Package Prevention rules |
| **Blocked package** | Issues generated by blocked-package rules |
| **Abandonware** | Issues generated by the Abandonware risk-intelligence signal |
| **Empty Package** | Issues generated by the Empty Package risk-intelligence signal |
| **Native Code** | Issues generated by the Native Code risk-intelligence signal |

### Ticket

| Option | Shows |
|---|---|
| **Ticketed** | Issues that have a ticket associated (Jira integration or a manually added URL) |
| **Not ticketed** | Issues with no ticket association |

### First Found

| Option | Shows |
|---|---|
| **Anytime** | All issues regardless of when they were found |
| **Last 7 / 14 / 30 days** | Issues first detected within the selected window |

### Package Manager

Filters issues to a specific ecosystem or package manager. Only ecosystems present in the current scope (global, project, or release group) appear as options.

### Project Label

Filters to issues in projects tagged with a specific FOSSA or user-defined project label. Multiple labels can be selected using OR logic.

### Team

Filters to issues in projects belonging to a specific team. Multiple teams can be selected using OR logic.

{% callout type="info" %}
Select **Reset all filters** at any time to clear all active filters and show every issue.
{% /callout %}

## Sorting

Use the sort dropdown to order issues by:

| Sort option | Description |
|---|---|
| **Newest / Oldest** | By the date FOSSA first found the issue |
| **Package (A–Z) / (Z–A)** | Alphabetical by package name |
| **Most / Least issues** | By issue count per semantic version |

{% callout type="info" %}
The default sort is **Most issues** when grouped by version, and **Newest** when ungrouped.
{% /callout %}

## Issue grouping

Issues are grouped by **Version** by default. To switch to an ungrouped view, select **Version** in the inbox header and change it to **Ungrouped**.

## Issue actions

Select the checkbox next to any issue to open the action menu. Available actions depend on issue status, scope, and whether you're acting on one issue or many.

| Action | Description | Type | Status | Scope |
|---|---|---|---|---|
| **Ignore (current version only)** | Ignores the issue for the current semantic version of the affected package, in the selected project(s) only. A new revision with any other version generates a new active issue. | Individual, bulk | Active | Global, release group, project |
| **Create ticket** | Creates a Jira ticket containing the selected issues. Selecting a previously ticketed issue links it to the new ticket only. | Individual, bulk | Active, ignored | Global, release group, project |
| **Unlink ticket** | Removes the association between the selected issues and any linked tickets. | Individual, bulk | Active, ignored | Global, release group, project |
| **Download CSV** | Downloads a CSV of the selected issues, scoped to the current status tab. | Individual, bulk | Active, ignored | Global, release group, project |
| **Unignore** | Returns selected issues from Ignored back to Active. | Individual, bulk | Ignored | Global, release group, project |

{% callout type="info" %}
Unlike licensing and security issues, quality issues are ignored for the **current version only**; there is no all-versions auto-ignore rule for quality. To suppress quality issues more broadly, use [package label ignore rules](/docs/vulnerabilities/auto-ignore-rules#package-label-ignore-rules), which ignore all quality issues on dependencies carrying a given label.
{% /callout %}

### Bulk actions

To act on multiple issues at once, use the select-all checkbox or check individual issues in the global view.

{% callout type="warning" %}
The bulk-select checkbox selects only the issues visible on the current page. To select all matching issues across every page, click the **Select all** link that appears after checking the checkbox.
{% /callout %}

## Issue drawer

Click anywhere on an issue row to open the issue drawer for a detailed view without leaving the inbox. Use the controls in the top-right corner:

| Control | Action |
|---|---|
| **Expand** | Opens the issue in a full-screen view in a new tab |
| **Share** | Copies a link to the expanded issue view |
| **Close** | Closes the drawer |

### Issue sub-navigation

| Section | Shows |
|---|---|
| **Issue Details** | Why the issue was flagged and how many packages or projects are impacted |
| **Dependency** | Package name, version, depth, and package manager/ecosystem |

### Projects sub-navigation

| Column | Description |
|---|---|
| **Project Name** | Title of the project in FOSSA |
| **Issue Status** | Whether the issue is Active or Ignored in that project |
| **View Path** | The dependency path showing where the package was detected |

### Comments

The drawer includes a time- and user-stamped comment thread for tracking triage discussions.

## What's next

- **[Understanding Quality Issues](/docs/quality/understanding-quality-issues)**: what each issue type means.
- **[Quality Policies](/docs/policies/quality-policy)**: configure which quality problems are flagged.
- **[Issue Scanners](/docs/project-setup/issue-scanners)**: enable the quality scanner and gate CI/CD.

---

Source: https://docs.fossa.com/docs/quality/quality-scanning

# Quality Scanning

Every time FOSSA analyzes a project, the quality scanner evaluates each direct and transitive dependency against your quality policy and FOSSA's risk-intelligence signals, then raises a quality issue for anything that fails.

## What the quality scanner checks

| Check | Source |
|---|---|
| **Outdated versions** | Stale Package Prevention rules in your quality policy (semantic-version distance) |
| **Blocked packages** | Packages your organization has deny-listed |
| **Risk-intelligence signals** | Abandonware, empty packages, and native code detected in the package itself |

See [Understanding Quality Issues](/docs/quality/understanding-quality-issues) for a breakdown of each.

## Enabling the quality scanner

The quality scanner is configured like the licensing and security scanners. Organization-level defaults live at **Organization Settings > Projects > Issues** and apply to all new projects; settings can be overridden per project at **Project Settings > Issue Policies**.

For each scanner you control whether issue detection is on, which policy applies, and whether issues fail CI/CD checks. See [Issue Scanners](/docs/project-setup/issue-scanners) for the full set of controls.

## Gating CI/CD

When **Fail CI/CD checks** is enabled for the quality scanner, FOSSA fails the project's status check if quality issues matching the CI/CD filter are found. Blocked packages additionally fail [`fossa test`](/docs/cli/references/subcommands/test), keeping deny-listed dependencies out of production builds.

## What's next

- **[Understanding Quality Issues](/docs/quality/understanding-quality-issues)**: what each issue type means.
- **[Reviewing Quality Issues](/docs/quality/reviewing-quality-issues)**: triage and resolve issues.
- **[Quality Policies](/docs/policies/quality-policy)**: configure detection thresholds.

---

Source: https://docs.fossa.com/docs/sbom

# SBOM

A software bill of materials (SBOM) is the inventory of components in your software. FOSSA produces and consumes SBOMs so you can share what's inside your software and analyze what's inside others'.

## What this covers

- **[Generate](/docs/sbom/generating-sboms)**: produce SBOMs (SPDX, CycloneDX) from your scans, with optional VDR/VEX vulnerability statements.
- **[Import](/docs/project-setup/sbom-import)**: bring in existing SBOMs to analyze dependencies you don't build yourself.
- **[PURL Support](/docs/sbom/purl-support)**: how FOSSA resolves package identifiers for high-confidence license and vulnerability matching.
- **[SBOM Policies](/docs/policies/sbom-policy)**: define required fields and formats for imported SBOMs, including NTIA/FDA minimum elements.
- **[Vulnerability Detection](/docs/vulnerabilities/sbom-vulnerability-detection)**: how FOSSA matches vulnerabilities in imported SBOMs, and when results are marked Unverified.
- **[Sharing SBOMs](/docs/sbom/sharing)**: share SBOM data publicly via the SBOM Portal or directly with partner organizations (Enterprise, requires enablement).

## Start here

- **[Generate an SBOM](/docs/sbom/generating-sboms)**: the fastest way to get a standards-compliant SBOM out of FOSSA.

SBOMs draw on data from [Licenses](/docs/licenses) and [Vulnerabilities](/docs/vulnerabilities). For attribution and compliance documents, see [Reports](/docs/reports).

---

Source: https://docs.fossa.com/docs/sbom/importing-sboms

# Importing SBOMs

SBOM import lets you bring an existing bill of materials into FOSSA without running the FOSSA CLI on the source project. Once imported, FOSSA analyzes the declared components against its license and vulnerability databases and surfaces issues through your existing policies.

## Supported formats

| Format | Versions supported |
|---|---|
| CycloneDX (JSON) | 1.2, 1.3, 1.4, 1.5, 1.6 |
| CycloneDX (XML) | 1.2, 1.3, 1.4, 1.5, 1.6 |
| SPDX (JSON) | 2.2, 2.3 |

### CycloneDX requirements

FOSSA processes all components listed under the `components` array. Each component should include a `purl` for highest-confidence license and vulnerability matching. See [PURL Support](/docs/sbom/purl-support) for the full list of supported PURL types and how FOSSA resolves them.

### SPDX requirements

FOSSA uses relationship types to determine which packages are dependencies of your project. The following relationship types are recognized:

**Package is a dependency of the project:** `DEPENDS_ON`, `CONTAINS`, `ANCESTOR_OF`

**Project is a dependency of a package:** `DEPENDENCY_OF`, `CONTAINED_BY`, `BUILD_DEPENDENCY_OF`, `DEV_DEPENDENCY_OF`, `OPTIONAL_DEPENDENCY_OF`, `PROVIDED_DEPENDENCY_OF`, `TEST_DEPENDENCY_OF`, `RUNTIME_DEPENDENCY_OF`, `DESCENDANT_OF`

FOSSA infers the top-level project from a `DESCRIBES` relationship originating from `SPDXRef-DOCUMENT`. If no `DESCRIBES` relationship is present, FOSSA attempts to infer the root document automatically.

## Importing via the UI

{% steps %}
{% step title="Open the Add Projects page" %}
Navigate to **Add Projects** and select **Import SBOM (CycloneDX, SPDX)**.

{% img src="/images/quick-import.png" alt="Add Projects page with the Import SBOM option" /%}
{% /step %}
{% step title="Add your files" %}
Click **Add Files** and select one or more `.json` or `.xml` SBOM files. Bulk import is supported. Select as many files as needed in one operation.

{% img src="/images/importing-sboms-add-files.png" alt="SBOM Upload page with the Add Files button and file dropzone" /%}
{% /step %}
{% step title="Name the project" %}
Enter a unique project name and an applicable semantic version number.

{% img src="/images/importing-sboms-name-project.png" alt="SBOM Upload page with a file selected, showing the Project Name and Revision fields" /%}

{% callout type="info" %}
If you use a project name that already exists, FOSSA adds the SBOM as a new revision to that project rather than creating a new one.
{% /callout %}
{% /step %}
{% step title="Upload and analyze" %}
Submit the form. Once processing completes, the project appears in your Projects list marked with the SBOM icon.

{% img src="/images/importing-sboms-projects-list.png" alt="Projects list filtered to SBOM imports, each row marked with the SBOM source icon" /%}
{% /step %}
{% /steps %}

## Importing via the API

The API import is a two-step process: first obtain a pre-signed upload URL, then trigger a build against the uploaded file.

### Step 1, Get a signed URL

Call `GET /api/components/signed_url` to receive a pre-signed S3 URL. The URL is valid for **5 minutes**.

{% tabs %}
{% tab name="curl" %}
```bash
curl -X GET "https://app.fossa.com/api/components/signed_url" \
  --data-urlencode "packageSpec=<SBOM_package_or_file_name>" \
  --data-urlencode "revision=<SHA_hash_or_version>" \
  --data-urlencode "fileType=sbom" \
  -H "Authorization: Bearer $FOSSA_TOKEN"
```
{% /tab %}
{% tab name="Python" %}
```python
import requests

resp = requests.get(
    "https://app.fossa.com/api/components/signed_url",
    params={"packageSpec": "<SBOM_package_or_file_name>", "revision": "<SHA_hash_or_version>", "fileType": "sbom"},
    headers={"Authorization": "Bearer <FOSSA_TOKEN>"},
)
signed_url = resp.json()["signedUrl"]
```
{% /tab %}
{% tab name="Node" %}
```js
const params = new URLSearchParams({
  packageSpec: "<SBOM_package_or_file_name>",
  revision: "<SHA_hash_or_version>",
  fileType: "sbom",
});
const res = await fetch(`https://app.fossa.com/api/components/signed_url?${params}`, {
  headers: { Authorization: "Bearer <FOSSA_TOKEN>" },
});
const { signedUrl } = await res.json();
```
{% /tab %}
{% tab name="Go" %}
```go
req, _ := http.NewRequest("GET", "https://app.fossa.com/api/components/signed_url", nil)
q := req.URL.Query()
q.Set("packageSpec", "<SBOM_package_or_file_name>")
q.Set("revision", "<SHA_hash_or_version>")
q.Set("fileType", "sbom")
req.URL.RawQuery = q.Encode()
req.Header.Set("Authorization", "Bearer <FOSSA_TOKEN>")
resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()
```
{% /tab %}
{% /tabs %}

Upload your SBOM file to the returned `signedUrl` using a `PUT` request within 5 minutes.

### Step 2, Trigger a build

Call `POST /api/components/build` to start analysis on the uploaded file.

{% tabs %}
{% tab name="curl" %}
```bash
curl -X POST "https://app.fossa.com/api/components/build?fileType=sbom" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $FOSSA_TOKEN" \
  -d '{"selectedTeams":[],"archives":[{"packageSpec":"<SBOM_package_or_file_name>","revision":"<SHA_hash_or_version>","fileType":"sbom"}]}'
```
{% /tab %}
{% tab name="Python" %}
```python
import requests

requests.post(
    "https://app.fossa.com/api/components/build",
    params={"fileType": "sbom"},
    headers={"Authorization": "Bearer <FOSSA_TOKEN>"},
    json={
        "selectedTeams": [],
        "archives": [{"packageSpec": "<SBOM_package_or_file_name>", "revision": "<SHA_hash_or_version>", "fileType": "sbom"}],
    },
)
```
{% /tab %}
{% tab name="Node" %}
```js
await fetch("https://app.fossa.com/api/components/build?fileType=sbom", {
  method: "POST",
  headers: { Authorization: "Bearer <FOSSA_TOKEN>", "Content-Type": "application/json" },
  body: JSON.stringify({
    selectedTeams: [],
    archives: [{ packageSpec: "<SBOM_package_or_file_name>", revision: "<SHA_hash_or_version>", fileType: "sbom" }],
  }),
});
```
{% /tab %}
{% tab name="Go" %}
```go
body := `{"selectedTeams":[],"archives":[{"packageSpec":"<SBOM_package_or_file_name>","revision":"<SHA_hash_or_version>","fileType":"sbom"}]}`
req, _ := http.NewRequest("POST", "https://app.fossa.com/api/components/build?fileType=sbom", strings.NewReader(body))
req.Header.Set("Content-Type", "application/json")
req.Header.Set("Authorization", "Bearer <FOSSA_TOKEN>")
http.DefaultClient.Do(req)
```
{% /tab %}
{% /tabs %}

A `201 Created` response confirms the build was queued successfully.

## Importing via the CLI

The FOSSA CLI can upload an SBOM file directly using `fossa sbom analyze`:

```bash
fossa sbom analyze /path/to/your-sbom.json
```

The project name defaults to the filename (minus the extension) and the revision to a timestamp. Override both with `--project` and `--revision`:

```bash
fossa sbom analyze /path/to/your-sbom.json --project "my-project" --revision "1.0.0"
```

After uploading, run `fossa sbom test` to check whether the analysis raised any policy issues:

```bash
fossa sbom test /path/to/your-sbom.json
```

`fossa sbom test` exits with a non-zero code if issues are found. See the [CLI reference](/docs/cli/references/subcommands/sbom) for the full list of flags.

## Package resolution

FOSSA resolves each component in the imported SBOM against its knowledge base using the component's PURL. For details on which PURL types are supported, how FOSSA converts PURLs to its internal format, and best practices for SBOM authoring, see [PURL Support](/docs/sbom/purl-support).

## What's next

- **[Reviewing Licensing Issues](/docs/licenses/reviewing-licensing-issues)**: Evaluate and resolve license compliance issues detected from your imported SBOM.
- **[Reviewing Security Issues](/docs/vulnerabilities/reviewing-security-issues)**: Address vulnerabilities identified in imported SBOM components.
- **[Licensing Reports](/docs/reports/licensing-report)**: Generate compliance documentation based on imported SBOM components.

---

Source: https://docs.fossa.com/docs/sbom/purl-support

# PURL Support

A Package URL (PURL) is a standardized string used to identify software packages across different registries and ecosystems. Including PURLs in your SBOMs gives FOSSA a precise, unambiguous identifier for each component, enabling high-confidence license and vulnerability matching. Without PURLs, FOSSA falls back to CPE-based matching, which is less reliable. See [Vulnerability Detection in Imported SBOMs](/docs/vulnerabilities/sbom-vulnerability-detection) for details.

The PURL format follows this pattern:

```
pkg:<type>/<namespace>/<name>@<version>?<qualifiers>#<subpath>
```

For the full specification, see the [official PURL spec](https://github.com/package-url/purl-spec).

## Supported PURL types

### Package managers

FOSSA supports PURLs for the following package ecosystems. Types marked as FOSSA custom are not in the official PURL specification but are fully supported for SBOM import and generation.

| PURL type | Ecosystem | Example |
|---|---|---|
| `apk` | Alpine Linux | `pkg:apk/alpine/curl@7.83.1-r2` |
| `cargo` | Rust | `pkg:cargo/tokio@1.21.0` |
| `cocoapods` | CocoaPods (iOS/macOS) | `pkg:cocoapods/AFNetworking@4.0.1` |
| `composer` | PHP | `pkg:composer/symfony/console@6.1.7` |
| `cran` | R | `pkg:cran/ggplot2@3.4.0` |
| `deb` | Debian / Ubuntu | `pkg:deb/debian/curl@7.74.0-1.3` |
| `gem` | RubyGems | `pkg:gem/rails@7.0.4` |
| `golang` | Go modules | `pkg:golang/github.com/gin-gonic/gin@1.8.1` |
| `hackage` | Haskell | `pkg:hackage/aeson@2.1.0.0` |
| `hex` | Hex (Elixir / Erlang) | `pkg:hex/phoenix@1.6.15` |
| `maven` | Maven (Java) | `pkg:maven/org.springframework/spring-core@5.3.23` |
| `npm` | npm (JavaScript) | `pkg:npm/express@4.18.2` |
| `nuget` | NuGet (.NET) | `pkg:nuget/Newtonsoft.Json@13.0.1` |
| `pub` | Pub (Dart / Flutter) | `pkg:pub/flutter@3.3.0` |
| `pypi` | Python | `pkg:pypi/django@4.1.3` |
| `rpm` | RPM (Red Hat / CentOS) | `pkg:rpm/redhat/curl@7.76.1-14.el9` |
| `swift` | Swift Package Manager | `pkg:swift/github.com/Alamofire/Alamofire@5.6.2` |
| `bower` | Bower *(FOSSA custom)* | `pkg:bower/jquery@3.6.0` |
| `cart` | Carthage (iOS/macOS) *(FOSSA custom)* | `pkg:cart/Alamofire@5.6.2` |
| `cpan` | Perl *(FOSSA custom, based on draft spec)* | `pkg:cpan/MIYAGAWA/Plack@1.0050` |

### Git repositories

The following git hosting platforms are supported as PURL types:

| PURL type | Platform | Spec | Example |
|---|---|---|---|
| `github` | GitHub | Official | `pkg:github/facebook/react@18.2.0` |
| `bitbucket` | Bitbucket | Official | `pkg:bitbucket/atlassian/python-bitbucket@0.1` |
| `gitlab` | GitLab | FOSSA custom | `pkg:gitlab/gitlab-org/gitlab@15.0.0` |
| `gitee` | Gitee | FOSSA custom | `pkg:gitee/openeuler/kernel@5.10` |
| `googlesource` | Google Source | FOSSA custom | `pkg:googlesource/chromium/tools/depot_tools@main` |
| `sourceforge` | SourceForge | FOSSA custom | `pkg:sourceforge/dex-os@1.0` |

{% callout type="info" %}
GitLab is not part of the official PURL specification, but FOSSA fully supports `pkg:gitlab` PURLs for both SBOM import and generation.
{% /callout %}

### Generic PURLs for other git repositories

For git repositories hosted on platforms not listed above (self-hosted GitLab instances, Gitea, Gogs, or custom git servers) use `pkg:generic` with URL qualifiers:

```
# Using download_url
pkg:generic/package-name@version?download_url=https://git.example.com/repo.git

# Using vcs_url
pkg:generic/my-library@1.2.3?vcs_url=https://git.internal.company.com/team/my-library.git
```

{% callout type="tip" %}
If the repository is on GitHub, GitLab, or Bitbucket, use the specific PURL type rather than `pkg:generic`; you'll get better resolution and more reliable enrichment. Save `pkg:generic` for platforms that don't have their own type.
{% /callout %}

## How FOSSA resolves PURLs

To enrich components with license and vulnerability data, FOSSA converts each PURL into its internal locator format. FOSSA's knowledge base, fetchers, and scanners operate on locators (not raw PURLs) so this conversion is required before any enrichment can occur.

### FOSSA Locator Format

```
<fetcher>+<package>$<revision>
```

**Git repository examples**

| PURL | FOSSA locator |
|---|---|
| `pkg:github/owner/repo@abc123` | `git+github.com/owner/repo$abc123` |
| `pkg:gitlab/owner/repo@def456` | `git+gitlab.com/owner/repo$def456` |
| `pkg:bitbucket/owner/repo@789xyz` | `git+bitbucket.org/owner/repo$789xyz` |
| `pkg:generic/lib@1.0?download_url=https://git.example.com/lib.git` | `url-private+{orgId}/https://git.example.com/lib.git$1.0` |

**Package manager examples**

| PURL | FOSSA locator |
|---|---|
| `pkg:npm/express@4.18.2` | `npm+express$4.18.2` |
| `pkg:maven/org.springframework/spring-core@5.3.23` | `mvn+org.springframework:spring-core$5.3.23` |
| `pkg:pypi/django@4.1.3` | `pip+django$4.1.3` |

## Best practices

**For package managers:**
- Follow the naming conventions for the ecosystem; PyPI uses lowercase with hyphens, Maven requires the full `namespace/name` group-artifact format
- Always include a specific version, avoid version ranges or wildcards
- For ecosystems with namespaces (Maven, Go, Swift), include the full namespace

**For git repositories:**
- Always specify the version as a full commit SHA or tag
- Use the most specific PURL type available; fall back to `pkg:generic` only when no matching type exists
- For `pkg:generic`, always include `download_url` or `vcs_url` so FOSSA can resolve the repository

**Good examples:**

- `pkg:github/facebook/react@18.2.0`
- `pkg:gitlab/gitlab-org/gitlab-foss@15.0.0-ee`
- `pkg:generic/internal-lib@v1.2.3?vcs_url=https://git.company.com/internal-lib.git`

**Avoid:**

- `pkg:github/facebook/react`: missing version
- `pkg:generic/internal-lib@1.2.3`: missing URL qualifier

## Troubleshooting

**`Found unsupported Purl type: <type>`**; the PURL type is not recognised by FOSSA. Use `pkg:generic` with URL qualifiers as a fallback.

**PURL not converting correctly**. Verify the PURL follows the correct format for its type, that required fields (namespace, version) are present, and for `pkg:generic` that a `download_url` or `vcs_url` qualifier is included.

---

Source: https://docs.fossa.com/docs/sbom/generating-sboms

# Generating SBOMs

FOSSA can generate a Software Bill of Materials (SBOM) for any analyzed project or release group. Generated SBOMs serve several purposes:

- Security vulnerability reviews with embedded VDR (Vulnerability Disclosure Report) and VEX (Vulnerability Exploitability eXchange) statements
- Customer-facing bills of materials for sales enablement, partnerships, and OEM agreements
- Fully-compliant attribution and copyright notices
- End-of-life and end-of-support communication
- Regulatory compliance for software supply chain mandates, including US EO 14028, the EU Cyber Resilience Act (CRA), FDA premarket cybersecurity requirements for medical devices, the EU Digital Operational Resilience Act (DORA), India's SEBI CSCRF, and PCI DSS

## Supported formats

| Format | Description |
|---|---|
| **SPDX** (tag-value) | ISO/IEC 5962:2021 standard. Widely used for compliance and legal workflows. |
| **SPDX (JSON)** | JSON-serialized SPDX. Machine-readable; suitable for toolchain integration. |
| **CycloneDX (JSON)** | OWASP CycloneDX standard in JSON. Supports VDR/VEX vulnerability embedding. |
| **CycloneDX (XML)** | OWASP CycloneDX standard in XML. Supports VDR/VEX vulnerability embedding. |

## Generating via the CLI

The FOSSA CLI generates SPDX attribution reports directly from your terminal, which is useful for automating report generation in CI pipelines.

{% steps %}
{% step title="Analyze your project" %}
Run `fossa analyze` from your project root:

```bash
export FOSSA_API_KEY=<your_api_key>
fossa analyze
```
{% /step %}
{% step title="Generate the SBOM" %}
Run the report command with your desired format:

```bash
fossa report attribution --format spdx
```

Supported `--format` values: `spdx`, `json`, `markdown`, `text`.
{% /step %}
{% /steps %}

{% callout type="info" %}
CycloneDX format is available via the UI only. Use the UI workflow below to generate CycloneDX JSON or XML.
{% /callout %}

## Generating via the UI

Navigate to your project or release group page and go to **Reports > SBOM**. Choose a **Standard** flow for FOSSA's recommended settings, or a **Custom** flow to control the content options below.

{% img src="/images/generating-sboms-report.png" alt="Project Reports > SBOM page showing the customization type, report preview, and format selector" /%}

### Selecting a format

Choose one of the four supported formats. Your selection determines which content options are available.

{% img src="/images/generating-sboms-format.png" alt="SBOM report Format dropdown showing SPDX, SPDX JSON, CycloneDX JSON, and CycloneDX XML options" /%}

### Content options

Configure which information to include in the SBOM. Options are split into two groups.

**Per-package metadata**

These control what data is included for each dependency in the SBOM:

| Option | Description | SPDX | SPDX JSON | CycloneDX JSON | CycloneDX XML |
|---|---|:---:|:---:|:---:|:---:|
| Authors | Individuals or organizations credited with creating the package | ✓ | ✓ | ✓ | ✓ |
| Description | Short summary of the package's purpose | ✓ | ✓ | ✓ | ✓ |
| Declared License | License stated in the package's metadata | ✓ | ✓ | ✓ | ✓ |
| Discovered Licenses | Licenses FOSSA identified by scanning package files | ✓ | ✓ | ✓ | ✓ |
| Concluded License | Final license FOSSA determines after analyzing all available data | ✓ | ✓ | ✓ | ✓ |
| Copyrights | Ownership statements found in source files or license documents | ✓ | ✓ | ✓ | ✓ |
| Notice Files | Files that summarize license and copyright notices for a package | ✓ | ✓ | ✓ | ✓ |
| Package Homepage | URL pointing to the package's main project page | ✓ | ✓ | | |
| Package Download URL | Direct link to where the package can be downloaded | ✓ | ✓ | | |
| Full License Text | Complete legal text of the license associated with the dependency | ✓ | ✓ | | |
| Copyrights from non-license text | Copyright statements found outside of license files | ✓ | ✓ | | |
| Issue Resolution Notes | Comments or clarifications made during license identification | | | ✓ | ✓ |

**Report sections**

These control which dependency groups and additional sections appear in the SBOM:

| Option | Description | SPDX | SPDX JSON | CycloneDX JSON | CycloneDX XML |
|---|---|:---:|:---:|:---:|:---:|
| Transitive Dependencies | Packages indirectly included through other dependencies | ✓ | ✓ | ✓ | ✓ |
| Direct Dependencies | Packages your project explicitly declares | | | ✓ | ✓ |
| License File Matches | File paths where license matches were detected within each dependency | ✓ | ✓ | | |
| Open Vulnerabilities | Active security issues with CVE metadata and VEX `affected` state | | | ✓ | ✓ |
| Closed Vulnerabilities | Resolved or ignored issues with VEX state and justification | | | ✓ | ✓ |
| Support Status | Whether each dependency is actively maintained or abandoned | | | ✓ | ✓ |
| FOSSA Projects | Nested FOSSA projects in the release group *(release groups only)* | | | ✓ | ✓ |

{% callout type="info" %}
All direct and transitive dependencies are included by default. The Direct Dependencies and Transitive Dependencies options let you control whether each group appears separately.
{% /callout %}

### Embedding VDR and VEX statements

Selecting **Open Vulnerabilities** or **Closed Vulnerabilities** on a CycloneDX format adds a `vulnerabilities` array to the output containing VDR and VEX statements for each security issue.

**Open Vulnerabilities**; active issues are embedded with their CVE metadata (VDR) and a VEX `analysis` with `state: affected`.

**Closed Vulnerabilities**; ignored issues are embedded with their CVE metadata (VDR) and a VEX `analysis` reflecting the resolution. The `state` and optional `justification` are derived from the FOSSA ignore reason at the time of export:

| FOSSA ignore reason | VEX state | VEX justification |
|---|---|---|
| Component not present | `not_affected` | `component_not_present` |
| Inline mitigations already exist | `not_affected` | `inline_mitigations_already_exist` |
| Vulnerable code cannot be controlled | `not_affected` | `vulnerable_code_cannot_be_controlled_by_adversary` |
| Vulnerable code not in execute path | `not_affected` | `vulnerable_code_not_in_execute_path` |
| Vulnerable code not present | `not_affected` | `vulnerable_code_not_present` |
| Fixed | `fixed` |  |
| Under investigation | `under_investigation` |  |
| Incorrect data found | `not_affected` |  |
| Other | `not_affected` |  |

VEX justifications align with [CISA VEX status justifications](https://www.cisa.gov/sites/default/files/publications/VEX_Status_Justification_Jun22.pdf). Reasons without a justification value (`Fixed`, `Under investigation`, `Incorrect data found`, `Other`) produce the appropriate VEX state but no `justification` field.

**Example VEX output**

An active vulnerability:

```json
{
  "bom-ref": "CVE-2023-39956",
  "id": "CVE-2023-39956",
  "source": { "url": "https://nvd.nist.gov/vuln/detail/CVE-2023-39956", "name": "NVD" },
  "ratings": [
    {
      "score": 6.6,
      "severity": "medium",
      "vector": "CVSS:3.1/AV:L/AC:L/PR:L/UI:N/S:U/C:L/I:H/A:L",
      "method": "CVSSv31"
    }
  ],
  "affects": [
    { "ref": "pkg:npm/electron@11.1.1" }
  ],
  "analysis": {
    "state": "affected"
  }
}
```

An ignored vulnerability with a VEX justification:

```json
{
  "bom-ref": "CVE-2023-39956",
  "id": "CVE-2023-39956",
  "analysis": {
    "state": "not_affected",
    "justification": "inline_mitigations_already_exist",
    "detail": "CVE not exploitable due to inline mitigation in the form of external input validation preventing injection"
  }
}
```

### Downloading or emailing your SBOM

Click **Download** to generate and download the SBOM immediately. For large projects, click **Email** to trigger an asynchronous generation job; the completed SBOM will be delivered to your email address.

## What's next

- **[Importing SBOMs](/docs/sbom/importing-sboms)**: Bring existing bills of materials into FOSSA to run compliance checks against their components.
- **[Sharing SBOMs](/docs/sbom/sharing)**: Publish and distribute your generated SBOMs to customers or partners.
- **[Licensing Reports](/docs/reports/licensing-report)**: Generate attribution notices and compliance documentation alongside your SBOMs.

---

Source: https://docs.fossa.com/docs/sbom/sharing

# Sharing SBOMs

FOSSA provides two ways to share SBOM data outside your organization: the public **SBOM Portal** and direct **cross-organization sharing**. Both require an Enterprise plan and must be enabled by the FOSSA team. Contact your account team or [support@fossa.com](mailto:support@fossa.com) to request access.

## SBOM Portal

The SBOM Portal gives you a public-facing URL where external stakeholders (customers, auditors, partners) can view your SBOM data without a FOSSA account. Once enabled, **SBOM Portal** appears in the main navigation.

{% img src="/images/sharing-sbom-portal.png" alt="Public SBOM Portal page with Public and Private tabs, branded for the publishing organization" /%}

From the Portal Settings page you control which projects and release groups are visible on the portal and configure the portal's appearance. The portal URL can be shared freely; no FOSSA login is required to view it.

You enable and configure the portal from the **Portal** tab in [Organization Settings](/docs/organization-management/organization-settings).

## Cross-organization sharing

Cross-organization sharing lets you push a specific project revision's SBOM data directly to another FOSSA organization. The receiving organization gets the shared project imported into their own FOSSA account, where they can view its dependency data, licenses, and vulnerabilities.

This is useful when:

- A vendor needs to provide a software component manifest to a customer who also uses FOSSA.
- A parent organization wants visibility into the dependency health of a subsidiary's projects.
- Partners exchanging SBOMs for due diligence or compliance purposes both use FOSSA.

Unlike the SBOM Portal, which publishes data for anyone to view, cross-organization sharing grants one specific FOSSA organization access to a project's dependency data.

### Prerequisites

Before sharing, your FOSSA account team must establish a link between your organization and the receiving organization. Once linked, the receiving organization appears as an option when you share a project.

### Sharing a project

{% steps %}
{% step title="Open the project's share action" %}
Navigate to the project revision in FOSSA and open the **Share** action from the project summary page (in the **Actions** menu).
{% /step %}
{% step title="Choose an organization" %}
Select the linked organization you want to share with from the list of organizations your account is connected to.
{% /step %}
{% step title="Confirm" %}
Click **Share**. FOSSA sends the revision's SBOM data to that organization as a background job and imports the shared revision into their account as a project.
{% /step %}
{% /steps %}

If the project is updated, return to the Share modal and click **Send Update** to push the new revision. FOSSA prevents sending the same revision twice; the button is disabled if the current revision has already been shared with that organization.

### What the receiving organization sees

The shared revision appears as a regular project in the receiving organization's FOSSA account. They can view its dependencies, licenses, and vulnerabilities.

Sharing is per revision. If you scan and share again, a new revision is created in the receiving organization.

### Managing shares

You can view all revisions you have shared from the **Share** modal on the project. Contact your FOSSA account team to remove a share or modify the organization link.

### Permissions

Sharing a project requires **Edit** permission on that project in your organization.

### FAQ

**Does cross-organization sharing expose my source code?**
No. Only the dependency graph, license data, and vulnerability information are shared, never source code.

**Can the receiving organization re-share the project with others?**
No. A received shared project cannot be shared onward. Only the original project owner can control sharing.

**Is shared data kept in sync?**
Sharing is per revision. To give the receiving organization access to updated data, share the project again after a new scan completes.

---

Source: https://docs.fossa.com/docs/policies

# Policies

The policy engine is how FOSSA turns your organization's standards into automatic, repeatable enforcement. Define a rule once and it applies across every project and scan.

## What this covers

- **[Licensing policies](/docs/policies/create-licensing-policy)**: approve, flag, or deny licenses and license families, with full control over the **[rules](/docs/policies/licensing-policy-rules)** that decide an outcome.
- **[Security policies](/docs/policies/security-policy)**: set thresholds for vulnerability severity and require remediation.
- **[SBOM policies](/docs/policies/sbom-policy)**: require specific fields and formats in the SBOMs you import.
- **[Time-based ignore rules](/docs/policies/time-based-ignore-rules)**: grant temporary exceptions that expire on their own.

## Start here

- **[Create a licensing policy](/docs/policies/create-licensing-policy)**: the most common first policy, end to end.
- **[How licensing policy rules work](/docs/policies/licensing-policy-rules)**: the model behind every policy decision.

Policies act on the data described in [Licenses](/docs/licenses), [Vulnerabilities](/docs/vulnerabilities), and [Quality](/docs/quality). To enforce them in your pipeline, see [Integrations](/docs/integrations).

---

Source: https://docs.fossa.com/docs/policies/licensing-policies

# Licensing Policies

A licensing policy controls which licenses and dependencies FOSSA approves, flags for review, or denies across every project you scan. FOSSA ships three builtin templates tuned to different distribution models. Use one as-is or customize its rules. Once configured, a policy can be set as your organization default or applied to individual projects.

{% callout type="info" %}
The **Standard Bundle Distribution** template is applied by default to all newly imported projects unless you set a different policy.
{% /callout %}

## How licensing policies work

A licensing policy is a collection of rules. Each rule assigns an action (**Deny**, **Flag for Review**, or **Approve**) to a specific license or dependency. On every analysis run, FOSSA evaluates each detected license and dependency against the active policy and raises issues accordingly.

| Action | What it does |
|---|---|
| **Deny** | Generates a *Policy Conflict* issue. The license or dependency must be removed or resolved before the project can pass. |
| **Flag for Review** | Generates a *Policy Flag* issue requiring manual approval. Use when the license needs case-by-case evaluation. |
| **Approve** | Suppresses issues for the license or dependency. FOSSA will never flag it, regardless of what other rules exist. |

## The three builtin templates

Each template is tuned to a different distribution model. They differ mainly in how they treat copyleft licenses, which scales with how much the distribution model exposes you to copyleft obligations.

{% callout type="warning" %}
This guidance reflects common patterns observed across FOSSA's customer base and incorporates insights gathered through our work with open-source compliance teams. It is intended to provide general best-practice guidance for configuring license compliance policies. It is not a substitute for legal advice, nor does it represent a legal opinion. Organizations should apply these recommendations in alignment with their own internal policies, governance standards, and risk tolerance.
{% /callout %}

| License family | Website/Hosted Service | Standard Bundle Distribution | Single-Binary Distribution |
| --- | --- | --- | --- |
| MIT, Apache-2.0, BSD | Approved | Approved | Approved |
| LGPL | Flagged | Flagged | Flagged |
| GPL (v2 / v3) | Mostly flagged | Flagged | Denied |
| AGPL | Mostly denied | Flagged | Denied |

{% callout type="info" %}
The exact action is configured for each individual license and version (for example, `GPL-3.0-only` and `GPL-3.0-or-later` can differ) so treatment varies within a family. Open a policy in FOSSA to see the precise rule for any license. Some rules also carry a **DIRECT** depth condition, meaning they only apply when the license appears in a direct dependency; see [Rule conditions](#rule-conditions) below.
{% /callout %}

### Standard Bundle Distribution

The general-purpose default, and the template FOSSA applies to new projects unless you choose another. Best for traditional software distributed to end users:

- Desktop applications, CLI tools, and installers
- Software libraries, SDKs, and plugins built for redistribution
- Commercial products with a standard "users install and run it locally" model

It balances compliance with development flexibility: most GPL licenses are flagged for review rather than denied, giving teams room to evaluate copyleft dependencies case by case.

### Website/Hosted Service

Best for code that runs server-side and is never delivered to end users:

- SaaS applications, web services, and APIs
- Backend microservices and cloud-native components
- Internal tools and services used only within your organization

This is the most permissive template toward copyleft. Because server-side execution generally does not trigger distribution obligations, it denies AGPL but only flags most GPL and LGPL licenses, maximizing flexibility for backend development.

### Single-Binary Distribution

Best for software shipped as a single self-contained artifact, where all dependencies are bundled together:

- Mobile applications (iOS, Android)
- Embedded systems, IoT devices, and firmware
- Statically-linked executable binaries

This is the strictest template. It denies the full GPL and AGPL families to minimize copyleft obligations in scenarios where source-code disclosure would be problematic.

## Creating a policy

Navigate to **Policies** in the top navigation, then open the **Licensing** tab. You'll see any existing policies alongside the option to create a new one.

{% steps %}
{% step title="Open the Create New Policy dialog" %}
Click **Create New Policy**.

{% img src="/images/policies/licensing-create-new-policy.png" alt="Create New Policy dialog" /%}
{% /step %}

{% step title="Set the policy type" %}
From the **Type** dropdown, select **Licensing**.
{% /step %}

{% step title="Name and describe the policy" %}
Give the policy a **Title** and a **Description** that provides context for your team, for example, the distribution scenario it covers.

{% img src="/images/policies/licensing-create-policy-filled.png" alt="Create New Policy dialog with the type set to Licensing and a title and description filled in" /%}
{% /step %}

{% step title="Choose a starting point (optional)" %}
Select a FOSSA template or an existing policy from your organization to use as a skeleton.

{% img src="/images/policies/licensing-template-selection.png" alt="Template selection showing Standard Bundle Distribution, Single-Binary Distribution, and Website/Hosted Service options" /%}

The three available templates are described in [The three builtin templates](#the-three-builtin-templates) above.
{% /step %}

{% step title="Submit" %}
Click **Submit** to create the policy. It now appears in your Policies list and can be assigned to projects.
{% /step %}
{% /steps %}

{% callout type="tip" %}
You can edit the title and description of any policy by clicking the pencil icon that appears when you hover over it.
{% /callout %}

## Configuring policy rules

A new policy inherits its template's rules. Add, remove, or adjust rules to match your organization's standards.

{% img src="/images/policies/licensing-policy-editor.png" alt="Licensing policy editor showing the Uncategorized, Deny, Flag for Review, and Approve rule panels" /%}

### Adding a rule

Open the policy you want to edit from the **Policies** page, then add rules to the Deny, Flag for Review, or Approve panel.

{% steps %}
{% step title="Click Add Rule" %}
In the policy editor, click **Add Rule** above the panel you want to add the rule to, **Deny**, **Flag for Review**, or **Approve**.
{% /step %}

{% step title="Choose the rule target" %}
Select whether the rule applies to a **license** or a **dependency** (project), then search for and select the specific license or dependency.

{% img src="/images/policies/licensing-add-rule-dialog.png" alt="New Rule dialog with a license selector" /%}
{% /step %}

{% step title="Add conditions (optional)" %}
Narrow when the rule fires by enabling one or more conditions. See [Rule conditions](#rule-conditions) below.
{% /step %}

{% step title="Save" %}
Click **Submit** to add the rule to the policy. Changes take effect on the next scan.
{% /step %}
{% /steps %}

### Rule conditions

Conditions let you restrict a rule to specific circumstances so it only fires when relevant. Each rule supports up to three independent conditions.

| Condition | UI label | What it filters |
|---|---|---|
| **License location** | *License is found:* | Whether the license appears **In your code** (direct) or **In a dependency** (transitive). Useful for licenses like MPL that only impose obligations when you modify the licensed code. |
| **Dependency name** | *Dependency name contains:* | Whether the dependency name contains a specific substring, e.g. `acme-` or `@acme/` to distinguish internal packages from external ones. |
| **Linking type** | *Dependency is linked:* | Whether the dependency is linked **Statically** or **Dynamically**. Relevant for licenses like LGPL where linking method affects obligations. FOSSA infers this from the language and build system. |

### Setting a default for uncategorized licenses

When FOSSA encounters a license that has no explicit rule in the policy, it falls back to the policy's **default action**. By default this is Uncategorized, which takes no action.

{% callout type="warning" %}
Setting a default of Deny or Flag for Review on a large project can generate a high volume of issues on the first scan, one for every uncategorized license found.
{% /callout %}

{% steps %}
{% step title="Open the rule action menu" %}
In the policy editor, find the panel (Deny, Flag for Review, or Approve) you want to make the default. Open the action menu for that panel.

{% img src="/images/policies/licensing-panel-action-menu.png" alt="Rule panel action menu open showing Make this the default category and Create new rule" /%}
{% /step %}

{% step title="Set as default" %}
Select **Make this the default category**. The panel is now marked as the default, any license with no explicit rule will be treated as if it matched this action.
{% /step %}
{% /steps %}

The four possible defaults and their behavior:

| Default | Behavior |
|---|---|
| **Uncategorized** (default) | No action taken. License is noted but no issue is created. |
| **Deny** | Generates a *Policy Conflict* issue for every uncategorized license. |
| **Flag for Review** | Generates a *Policy Flag* issue for every uncategorized license. |
| **Approve** | Silently approves all uncategorized licenses. |

## Choosing defaults across your organization

Set one builtin template as your organization-wide default, then override at the project level wherever a project's distribution model differs.

For organizations with mixed project types, a common approach is:

1. Set **Standard Bundle Distribution** as the org-wide default for maximum flexibility.
2. Override at the project level for specific distribution scenarios, for example, mobile and embedded projects → **Single-Binary Distribution**; backend services and internal tools → **Website/Hosted Service**.

For more specialized organizations, match the default to your dominant distribution model and override the exceptions:

| Organization type | Recommended default | Override with |
| --- | --- | --- |
| SaaS / web companies | Website/Hosted Service | Single-Binary or Standard Bundle for any distributed mobile or desktop tools |
| Enterprise software vendors | Standard Bundle Distribution | Single-Binary for mobile/embedded components; Website/Hosted Service for internal tools and services |
| Hardware / embedded companies | Single-Binary Distribution | Website/Hosted Service for any cloud services or management portals |

## Setting the organization default

Once you've created a policy, assign it as the organization default so it applies automatically to every new project imported going forward.

{% callout type="tip" %}
If you are setting up policies for the first time, set the default at the organization level before importing additional projects.
{% /callout %}

{% steps %}
{% step title="Open organization project settings" %}
Click your username in the top-right corner and select **Settings**, then navigate to **Projects → Issue Policies → Licensing**.

{% img src="/images/policies/licensing-org-issue-policies.png" alt="Organization Default Issue Policies Settings page showing the Licensing section" /%}
{% /step %}

{% step title="Select the policy" %}
Under the **Licensing** section, use the policy dropdown to select your newly created policy.

{% img src="/images/policies/licensing-org-select.png" alt="Default licensing policy dropdown open on the organization Issue Policies settings page" /%}
{% /step %}

{% step title="Save" %}
Click **Save** to apply the policy to all future projects.
{% /step %}

{% step title="Propagate to existing projects (optional)" %}
To apply the change to projects already in FOSSA, click **Propagate** and select which settings you want to push to existing projects.
{% /step %}
{% /steps %}

## Applying a policy to a project

Override the organization default on any individual project whose distribution model differs.

{% callout type="warning" %}
Changing the `policy:` field in a [`.fossa.yml`](https://github.com/fossas/fossa-cli/blob/master/docs/references/files/fossa-yml.md) file for an existing project will **not** update the policy applied in FOSSA. Update the policy through project settings instead.
{% /callout %}

{% steps %}
{% step title="Open project settings" %}
Navigate to the project in FOSSA and open its **Settings**.
{% /step %}

{% step title="Go to Issue Policies" %}
Select **Issue Policies** from the settings sidebar.

{% img src="/images/policies/licensing-project-issue-policies.png" alt="Project Issue Policies settings page with the Licensing default policy selected" /%}
{% /step %}

{% step title="Select the policy" %}
Choose the appropriate policy for each issue type (Licensing, Security, Quality).
{% /step %}

{% step title="Save" %}
Save your changes. The new policy applies on the next scan.
{% /step %}
{% /steps %}

## Rolling out a policy

When introducing policy enforcement for the first time:

1. **Start with the most restrictive policy** that fits your distribution model, so you surface compliance risk early.
2. **Run an initial scan** across your projects to understand your current license landscape before enforcing.
3. **Resolve denied licenses** before turning enforcement on, then relax restrictions only once you understand the implications.
4. **Begin from a builtin template** rather than building a policy from scratch, and document any customizations along with the business reasons behind them.
5. **Align your team** on the difference between Approve, Flag for Review, and Deny, and establish a clear escalation path for flagged-license decisions.

## Migrating between policies

**From no policy to a builtin template:** start with **Standard Bundle Distribution**, run comprehensive scans across all projects, address any denied licenses, then gradually apply project-specific policies based on each project's distribution model.

**Between builtin templates:** understand the license differences first (see the comparison table above), test the change on a few representative projects, communicate the change to development teams in advance, and provide a timeline for addressing any newly-denied licenses.

The key is matching your policy choice to your actual distribution model and risk tolerance. Start conservatively, then adjust as you learn your organization's specific needs.

## What's next

- **[Reviewing Licensing Issues](/docs/licenses/reviewing-licensing-issues)**: Resolve dependencies flagged or denied by your licensing policy.
- **[Security Policy](/docs/policies/security-policy)**: Define vulnerability handling policies to complement your licensing rules.
- **[Fail CI/CD Checks](/docs/integrations/fail-cicd-checks)**: Enforce your policies in CI/CD to block non-compliant builds.

---

Source: https://docs.fossa.com/docs/policies/security-policy

# Security Policies

A security policy defines which vulnerabilities FOSSA raises as issues. You set a severity threshold, suppress false positives with allow rules, and force-flag specific weaknesses with deny rules. Once configured, a policy can be set as the organization default or applied to individual projects.

## How security policies work

When FOSSA scans a project, the issue scanner evaluates each detected vulnerability against the active security policy. The policy holds five independent rule types:

| Rule type | What it does |
|---|---|
| **Severity Filter** | Sets a minimum CVSS severity level (Low / Medium / High / Critical) or a minimum CVSS score (0–10). Vulnerabilities below the threshold are not flagged. Vulnerabilities with unknown severity are always included regardless of this setting. |
| **CWE Allow Rules** | Suppresses vulnerabilities that are associated with any listed CWE. If a vulnerability matches any one of the listed CWEs, it is never flagged. |
| **CWE Deny Rules** | Force-flags vulnerabilities that are associated with any listed CWE, even if they fall below the severity threshold. |
| **CVE Allow Rules** | Suppresses specific CVEs by identifier. Listed CVEs are never flagged. |
| **CVE Filter Rules** | Controls whether vulnerabilities with a Disputed CVE status appear in issues and reports. Disputed CVEs are hidden by default; enabling **Show Disputed CVEs** makes them visible. |

{% callout type="info" %}
For CWE Allow and Deny Rules, each entry is evaluated independently. A vulnerability is affected by the rule if it matches **any one** of the listed CWEs, not all of them.
{% /callout %}

{% callout type="info" %}
Avoid suppressing vulnerability categories at the policy level unless you have a specific reason to. FOSSA recommends using the Issue Inbox and its filters to triage unwanted issues so that all vulnerabilities remain captured in your data.
{% /callout %}

## Creating a security policy

{% steps %}
{% step title="Open the Policies page" %}
Navigate to **Policies** in the top navigation, then select the **Security** tab.

{% img src="/images/policies/security-policies-tab.png" alt="Security tab of the Policies page" /%}
{% /step %}
{% step title="Create the policy" %}
Click **Create Policy**. In the dialog that appears, confirm **Type** is set to **Security**, enter a **Title** and optional **Description**, then click **Submit**.

{% img src="/images/policies/security-create-new-policy.png" alt="Create New Policy dialog" /%}
{% /step %}
{% /steps %}

The policy is created with no rules configured. Proceed to [Configuring policy rules](#configuring-policy-rules) to define thresholds.

## Configuring policy rules

{% steps %}
{% step title="Open the policy" %}
Navigate to **Policies > Security** and click the policy you want to edit.

{% img src="/images/policies/security-policy-configuration.png" alt="Security Policy configuration screen" /%}
{% /step %}
{% step title="Configure each rule section" %}
Update the **Severity Filter**, **CWE Allow Rules**, **CWE Deny Rules**, **CVE Allow Rules**, and **CVE Filter Rules** sections to match your requirements. See the [rule type reference](#how-security-policies-work) above for details on each.
{% /step %}
{% step title="Save" %}
Click **Save** at the top of the page to apply all changes.
{% /step %}
{% /steps %}

## Setting the organization default

The organization default policy applies to all projects that have not been assigned a specific policy.

{% steps %}
{% step title="Open Settings" %}
Click your username in the top-right corner and select **Settings**.

{% img src="/images/policies/user-settings-dropdown.png" alt="User settings dropdown" /%}
{% /step %}
{% step title="Navigate to Issue Policies" %}
Go to **Organization > Projects > Issue Policies**.

{% img src="/images/policies/security-org-issue-policies.png" alt="Organization Issue Policies settings page" /%}
{% /step %}
{% step title="Assign the default policy" %}
Under **Security**, click the **Default security policy** dropdown, select your policy, then click **Save**.

{% img src="/images/policies/security-default-policy-dropdown.png" alt="Default security policy dropdown" /%}
{% /step %}
{% step title="Propagate to existing projects (optional)" %}
To push the new default to projects already in use, click **Propagate settings…**, select which settings to propagate, then click **Propagate settings**.
{% /step %}
{% /steps %}

## Applying a policy to a project

{% steps %}
{% step title="Open project settings" %}
Go to your project list, select the project, then navigate to **Settings > Issue Policies**.

{% img src="/images/policies/security-project-issue-policies.png" alt="Project Issue Policies settings" /%}
{% /step %}
{% step title="Assign the policy" %}
Under **Security**, click the **Default security policy** dropdown, select a policy, then click **Save**.
{% /step %}
{% step title="Run a new scan" %}
Trigger a new scan on the project. The updated policy applies to issues generated by the next completed scan.
{% /step %}
{% /steps %}

## Editing a policy title

{% steps %}
{% step title="Find the policy" %}
Navigate to **Policies > Security** and hover over the policy you want to rename. Click the pencil icon that appears.

{% img src="/images/policies/security-edit-pencil-icon.png" alt="Pencil icon on hover" /%}
{% /step %}
{% step title="Save" %}
Update the **Title** and **Description** in the dialog, then click **Submit**.

{% img src="/images/policies/security-edit-policy-dialog.png" alt="Edit Security Policy dialog" /%}
{% /step %}
{% /steps %}

## Deleting a policy

{% steps %}
{% step title="Find the policy" %}
Navigate to **Policies > Security** and hover over the policy you want to delete. Click the red **X** icon that appears.

{% img src="/images/policies/security-delete-icon.png" alt="Delete icon on hover" /%}
{% /step %}
{% step title="Confirm" %}
In the confirmation dialog, click **Confirm**.

{% img src="/images/policies/security-confirm-deletion.png" alt="Confirm Policy Deletion dialog" /%}
{% /step %}
{% /steps %}

{% callout type="warning" %}
Deleting a policy cannot be undone. Projects assigned to the deleted policy fall back to the organization default.
{% /callout %}

## What's next

- **[Reviewing Security Issues](/docs/vulnerabilities/reviewing-security-issues)**: Triage vulnerabilities flagged by your security policy.
- **[Licensing Policies](/docs/policies/licensing-policies)**: Add licensing rules alongside security policies for comprehensive compliance.
- **[Fail CI/CD Checks](/docs/integrations/fail-cicd-checks)**: Enforce your policy in CI/CD to block builds with unresolved vulnerabilities.

---

Source: https://docs.fossa.com/docs/policies/quality-policy

# Quality Policies

A quality policy defines which dependency-health and supply-chain-risk problems FOSSA raises as issues. Use one to keep dependencies up to date, block specific packages, and turn on FOSSA's risk-intelligence signals. Once configured, a policy can be set as the organization default or applied to individual projects.

## How quality policies work

When FOSSA scans a project, the quality scanner evaluates each dependency against the active quality policy. A policy holds these rule types:

| Rule type | What it does |
|---|---|
| **Stale Package Prevention** | Flags dependencies that are further behind the latest release than you allow, by semantic-version distance (configurable per major, minor, and patch), by ordered versions, or both. |
| **Blocked Packages** | Flags dependencies your organization has deny-listed. Blocked packages also fail `fossa test` in CI/CD. |
| **Abandonware** | A risk-intelligence signal that flags packages with no new publish for two years. Available for npm, PyPI, and Maven. |
| **Empty Package** | A risk-intelligence signal that flags packages shipping no runnable code. Available for npm, PyPI, and Maven. |
| **Native Code** | A risk-intelligence signal that flags packages embedding compiled binaries. Available for npm and PyPI. |

See [Understanding Quality Issues](/docs/quality/understanding-quality-issues) for a detailed breakdown of each signal.

## Creating a quality policy

{% steps %}
{% step title="Open the Policies page" %}
Navigate to **Policies** in the top navigation, then select the **Quality** tab.

{% img src="/images/policies/quality-policies-tab.png" alt="Quality tab of the Policies page" /%}
{% /step %}
{% step title="Create the policy" %}
Click **Create Policy**, confirm **Type** is set to **Quality**, enter a **Title** and optional **Description**, then submit.

{% img src="/images/policies/quality-create-policy-dialog.png" alt="Create Quality Policy dialog" /%}
{% /step %}
{% /steps %}

The policy is created with no rules configured. Proceed to [Configuring policy rules](#configuring-policy-rules) to define thresholds.

## Configuring policy rules

{% steps %}
{% step title="Enable Stale Package Prevention" %}
Open the policy and enable rules to flag packages by semantic version, ordered versions, or both. A package matching either rule is flagged as an issue.

{% img src="/images/policies/quality-stale-package-prevention.png" alt="Stale Package Prevention configuration" /%}
{% /step %}
{% step title="Enable risk-intelligence rules" %}
Turn on the **Abandonware**, **Empty Package**, and **Native Code** signals you want FOSSA to flag for projects using this policy.

{% img src="/images/policies/quality-risk-intelligence.png" alt="Risk Intelligence rules with Abandonware, Empty Package, and Native Code toggles" /%}
{% /step %}
{% step title="Save" %}
Save the policy to apply your changes. The rules take effect on the next completed scan.
{% /step %}
{% /steps %}

## Blocking a package

Blocked packages are managed from the **Packages** inventory rather than the policy editor, and are attached to a quality policy.

{% steps %}
{% step title="Find the package" %}
Go to the **Packages** inventory and search or filter to the package you want to block.
{% /step %}
{% step title="Block it" %}
Use **Block package** to block all versions, or select specific versions to block.

{% img src="/images/policies/quality-block-package-dialog.png" alt="Block package dialog" /%}
{% /step %}
{% step title="Attach to a quality policy" %}
Select the quality policy the blocked-package rule should apply to, then confirm. Projects using that policy will flag the blocked package, and fail [`fossa test`](/docs/cli/references/subcommands/test) if it is present.
{% /step %}
{% /steps %}

## Setting the organization default

The organization default policy applies to all projects that have not been assigned a specific quality policy.

{% steps %}
{% step title="Open Settings" %}
Click your username in the top-right corner and select **Settings**.

{% img src="/images/policies/user-settings-dropdown.png" alt="User settings dropdown" /%}
{% /step %}
{% step title="Navigate to Issue Policies" %}
Go to **Organization > Projects > Issue Policies**.
{% /step %}
{% step title="Assign the default policy" %}
Under **Quality**, select your policy from the **Default quality policy** dropdown, then click **Save**. To push the new default to existing projects, use **Propagate settings…**.

{% img src="/images/policies/quality-default-policy-dropdown.png" alt="Quality section of Default Issue Policies Settings with the Default quality policy dropdown" /%}
{% /step %}
{% /steps %}

## Applying a policy to a project

{% steps %}
{% step title="Open project settings" %}
Go to your project list, select the project, then navigate to **Settings > Issue Policies**.
{% /step %}
{% step title="Assign the policy" %}
Under **Quality**, select a policy from the **Default quality policy** dropdown, then click **Save**.
{% /step %}
{% step title="Run a new scan" %}
Trigger a new scan. The updated policy applies to issues generated by the next completed scan.
{% /step %}
{% /steps %}

## Related

- **[Understanding Quality Issues](/docs/quality/understanding-quality-issues)**: what each quality issue type means.
- **[Reviewing Quality Issues](/docs/quality/reviewing-quality-issues)**: triage and resolve issues.
- **[Issue Scanners](/docs/project-setup/issue-scanners)**: enable the quality scanner and gate CI/CD.

---

Source: https://docs.fossa.com/docs/policies/sbom-policy

# SBOM Policies

An SBOM policy defines the **required fields** and **file formats** that imported SBOMs must satisfy. When a policy is active on a project, FOSSA evaluates each imported SBOM against these rules and surfaces results in the **SBOM Analysis** section of the project summary, without running a full issue scan.

{% callout type="info" %}
SBOM policy configuration requires a paid plan.
{% /callout %}

## How SBOM policies work

Unlike license, security, and quality policies, an SBOM policy does not create issues in FOSSA. It only informs the SBOM Analysis. This means policy changes take effect immediately on the next import, no new scan needed.

A policy contains two categories of rules:

- **Required fields**: component and metadata attributes that must be present in the SBOM
- **File format**: which specifications (CycloneDX, SPDX) are accepted, the minimum version required, and whether dependency relationships or vulnerability data must be present
## Required fields

Required fields are attributes that must exist on each component or the SBOM itself to pass the policy check.

{% img src="/images/policies/sbom-policy-required-fields.png" alt="Required Fields section of an SBOM policy with the NTIA/FDA toggle and component checkboxes" /%}

| Field | Description | Scope | NTIA minimum | Configurable |
|---|---|---|---|---|
| Name | Name of the SBOM component | Component | Yes | No, always required by FOSSA |
| Version | Version of the SBOM component | Component | Yes | No, always required by FOSSA |
| SBOM Author | Individual, organization, or tool that created the SBOM | SBOM metadata | Yes | Yes |
| Creation Timestamp | Date and time the SBOM was created | SBOM metadata | Yes | Yes |
| Supplier | Supplier of the component, individual, organization, or package registry | Component | Yes | Yes |
| PURL (Package URL) | Unique identifier for the component including type, namespace, name, and version. Without a valid PURL, license and vulnerability data quality will be lower. See [PURL Support](/docs/sbom/purl-support). | Component | No | Yes |
| Generic PURL | Flags SBOMs with more than 5 `pkg:generic` PURLs as a potential data quality issue. Generic PURLs indicate components that could not be resolved to a specific ecosystem. | Component | No | Yes |
| CPE (Common Platform Enumeration) | Structured naming scheme for software and packages, used to associate vulnerabilities. See [NIST](https://nvd.nist.gov/products/cpe). | Component | No | Yes |

### NTIA/FDA compliance toggle

For organizations subject to US federal software supply chain requirements, FOSSA provides an **NTIA/FDA** toggle that instantly configures all fields required by the [NTIA minimum elements for an SBOM](https://www.ntia.gov/sites/default/files/publications/sbom_minimum_elements_report_0.pdf). The FDA currently follows NTIA requirements, so a single toggle covers both.

Enabling the toggle sets **SBOM Author**, **Creation Timestamp**, **Supplier**, **PURL**, **CycloneDX Dependencies**, **SPDX Relationships**, and the minimum version thresholds for both formats, everything marked "Yes" in the NTIA minimum column above. You can still adjust individual fields after using the toggle.

This is most useful for software vendors supplying US federal agencies, medical device manufacturers under FDA guidance, or any organization that wants a quick baseline before refining further.

## File format

At least one format must be enabled. Both CycloneDX and SPDX can be enabled at the same time; when they are, the policy accepts either format. An SBOM only needs to match one.

{% img src="/images/policies/sbom-policy-file-format.png" alt="File format section of an SBOM policy with CycloneDX and SPDX settings" /%}

### CycloneDX

| Setting | Description | NTIA minimum |
|---|---|---|
| CycloneDX allowed | Permit import of CycloneDX SBOMs | Yes |
| Minimum CycloneDX version | Reject CycloneDX SBOMs below this version (1.2–1.6) | Yes |
| Dependencies | Require a `dependencies` array where each component has at least one dependency relationship. Essential for FOSSA to determine direct vs. transitive dependencies. | Yes |
| Vulnerabilities | Require a `vulnerabilities` array with a unique identifier (CVE) per entry (VDR) and an `analysis` object with a VEX state. See [Generating SBOMs](/docs/sbom/generating-sboms#embedding-vdr-and-vex-statements) for how FOSSA generates these fields. | No |

### SPDX

| Setting | Description | NTIA minimum |
|---|---|---|
| SPDX allowed | Permit import of SPDX SBOMs | Yes |
| Minimum SPDX version | Reject SPDX SBOMs below this version (2.2–2.3) | Yes |
| Relationships | Require a `relationships` array where each package has at least one dependency relationship. Essential for FOSSA to determine direct vs. transitive dependencies. | Yes |

## Applying a policy

### Setting the organization default

Navigate to **Settings > Organization > Projects > Issue Policies**. Under the **SBOM** section, select the policy from the **Default SBOM policy** dropdown and click **Save**. To apply to existing projects, click **Propagate settings**.

{% img src="/images/policies/sbom-policy-org-default.png" alt="SBOM section of Default Issue Policies Settings with the Default SBOM policy dropdown" /%}

### Applying to a specific project

Navigate to the project, go to **Settings > Issue Policies**, select the policy from the **SBOM policy** dropdown, and click **Save**.

{% img src="/images/policies/sbom-policy-project.png" alt="SBOM section of a project's Issue Policies settings with the SBOM policy dropdown" /%}

## SBOM Analysis

The **Analysis** section appears on the project summary page of any imported SBOM project. Navigate to your SBOM project and the Analysis section loads automatically below the project overview.

{% img src="/images/policies/sbom-policy-analysis.png" alt="SBOM Analysis section showing the SBOM File, Required Fields, and Dependency Scan checks" /%}

Each attribute shows one of three indicators:

| Indicator | Meaning |
|---|---|
| ✓ Green checkmark | Attribute is present and meets the policy criteria |
| ✗ Red X | Attribute is missing or violates the policy |
| – Grey hyphen | Attribute is not required by the active policy |

The Analysis is divided into three categories.

### SBOM File

Checks whether the file itself is valid and parseable by FOSSA, regardless of policy settings.

| Attribute | What is checked |
|---|---|
| File is recognized as an SBOM | FOSSA can parse the file as a valid CycloneDX or SPDX document |
| Components can be identified | The file contains at least one component |
| Relationship between components can be mapped | The file contains valid dependency relationship data (shown when a relationships rule is enabled in the policy) |

A banner at the top of this section summarises the overall result: *"This SBOM meets all of FOSSA's requirements for analysis"* on pass, or *"FOSSA encountered problems reading the source SBOM file"* on fail.

### Required fields check

Evaluates the SBOM against the active policy's required fields and file format rules. This section only appears when a policy is assigned to the project. If no policy is set, FOSSA prompts you to assign one.

| Attribute | What is checked |
|---|---|
| Uses required format | Whether the file's format (CycloneDX or SPDX) matches the formats enabled in the policy |
| Uses minimum version of X or greater | Whether the file's spec version meets the minimum version set in the policy (shown separately for CycloneDX and SPDX when each is enabled) |
| Includes SBOM author | Whether an author is present in the SBOM metadata |
| Includes creation timestamp | Whether a creation timestamp is present in the SBOM metadata |
| Includes component name | Whether every component has a name, shown as a count (e.g. `42/42 components`) |
| Includes component version | Whether every component has a version, shown as a count |
| Includes supplier | Whether every component has a supplier, shown as a count |
| Includes PURL (Package URL) | Whether every component has a PURL, shown as a count |
| Uses generic PURLs | Whether the SBOM contains `pkg:generic` PURLs: pass if 0, neutral if 1–5, fail if more than 5 |
| Includes CPE (Common Platform Enumeration) | Whether every component has a CPE, shown as a count |
| Includes relationship data | Whether every component has at least one dependency relationship, shown as a count |
| Includes vulnerability | Whether the SBOM contains a `vulnerabilities` array with at least one entry *(CycloneDX only)* |
| Includes unique vulnerability ID | Whether every vulnerability has a unique identifier (e.g. a CVE), shown as a count *(CycloneDX only)* |
| Vulnerability analysis state (VEX) | Whether every vulnerability has an `analysis` object with a VEX state, shown as a count *(CycloneDX only)* |

A banner summarises the category result: *"All required fields are included"* on pass, or *"Required fields missing or encountered problems"* on fail.

{% callout type="warning" %}
A single policy rule can inform multiple analysis attributes. Enabling the **Vulnerabilities** file format rule produces three separate analysis rows: **Includes vulnerability**, **Includes unique vulnerability ID**, and **Vulnerability analysis state (VEX)**.
{% /callout %}

### Dependency Scan

Reports the outcome of FOSSA's attempt to resolve and analyse the SBOM's components against its knowledge base.

| Attribute | What is checked |
|---|---|
| All dependencies are identified and analyzed | Whether all components were successfully resolved; shows counts of unknown and failed dependencies |

---

Source: https://docs.fossa.com/docs/reports

# Reports

Turn FOSSA's analysis into the documents your auditors, customers, and legal teams expect. FOSSA generates reports at three scopes: a single project, a release group, or your entire organization.

## Report types

| Report | Scope | Where to find it |
|---|---|---|
| **[Licensing](/docs/reports/licensing-report)** | Project or release group | Project or release group **Reports** tab |
| **[SBOM](/docs/sbom/generating-sboms)** | Project or release group | Project or release group **Reports** tab |
| **[Remediation Guidance](/docs/reports/remediation-guidance)** | Project or release group | Project or release group **Reports** tab |
| **[Global Package Report Bundle](/docs/reports/global-reports)** | Entire organization | **Reports** dashboard |
| **[Audit / Due Diligence Report](/docs/reports/global-reports)** | Entire organization | **Reports** dashboard |
| **[Global Issue CSV Export](/docs/reports/global-reports)** | Entire organization | **Reports** dashboard |

## Project and release group reports

From a project's or release group's **Reports** tab, pick a report type, apply any filters, and choose an export format. The same report types are available at both scopes; a release group report aggregates the projects in the group.

{% img src="/images/reports/project-reports-tab.png" alt="Project Reports tab showing the report type sidebar (Licensing, SBOM, Remediation Guidance) and the report preview" /%}

### Licensing

The licensing report (also called the attribution report) documents the open source in your project: a dependency summary, direct and transitive dependencies, detected and concluded licenses, copyright notices, and full license texts. It is the document you ship to satisfy attribution obligations. Export as HTML, PDF, CSV, Markdown, or plain text. See [Licensing Reports](/docs/reports/licensing-report).

### SBOM

A Software Bill of Materials lists every component in your project in a standard, machine-readable format. FOSSA exports SPDX (tag-value or JSON) and CycloneDX (JSON or XML), and CycloneDX exports can embed vulnerability and support-status data. See [Generating SBOMs](/docs/sbom/generating-sboms).

### Remediation Guidance

A prioritized fix plan: quick wins, high and low priority fixes, outdated dependencies, and malicious dependencies, so you can clear the most risk with the fewest changes. Export as PDF, HTML, or JSON. Requires security scanning and is not available for binary projects. See [Remediation Guidance](/docs/reports/remediation-guidance).

{% callout type="info" %}
The report builder offers a **Standard** flow with recommended defaults and a **Custom** flow for fine-grained control over what each report includes. The Custom flow is a paid feature.
{% /callout %}

## Organization-wide reports

From the **Reports** dashboard you can generate reports that span every project in your organization. These require a premium subscription and report permissions. See [Global Reports](/docs/reports/global-reports).

{% img src="/images/reports/global-reports-dashboard.png" alt="Organization Reports dashboard with cards for the Global Package Report Bundle, Audit / Due Diligence Report, and Global Issue CSV Export" /%}

### Global Package Report Bundle

An organization-wide report on licenses and packages across the projects you select, delivered by email.

### Audit / Due Diligence Report

An organization-wide report on issues and project changes, delivered by email. Useful for M&A due diligence and audit trails.

### Global Issue CSV Export

Organization-wide issue data in CSV format, with separate reports for license, security, and quality issues. Download it directly or have it emailed.

## Configuration

- **[Report Settings](/docs/reports/report-settings)**: customize the logo and description on generated reports, manage saved filter presets, and set SBOM author defaults per project or release group.

Reports draw on data from [Licenses](/docs/licenses) and [Vulnerabilities](/docs/vulnerabilities). For the machine-readable component inventory, see [SBOM](/docs/sbom).

---

Source: https://docs.fossa.com/docs/reports/licensing-report

# Licensing Reports

Open source licenses require you to give attribution to their authors in specific ways. FOSSA generates the compliance documentation automatically (licensing reports, copyright disclosures, and bills of materials) based on the dependencies it has analyzed.

Licensing reports are useful for:

- Distributing attribution notices with your product
- Customer-facing bills of materials for sales, partnerships, or OEMs
- Audit reports for due diligence events
- [Security vulnerability reviews](/docs/vulnerabilities/reviewing-security-issues)

## Generating a report from the UI

Navigate to a project or release group, open **Reports**, and select **Licensing** from the sidebar. Generating a report takes two steps: choose a flow, then select an output format and adjust the content options. A live preview updates as you change options.

{% img src="/images/reports/licensing-report-builder.png" alt="Licensing report builder showing the flow selector, output format, content options, and live preview" /%}

{% callout type="info" %}
All FOSSA plans can generate **Standard** reports using pre-set filters. The **Custom** report flow (which lets you control every filter, view, and data point) requires a paid plan.
{% /callout %}

### Choosing a flow

| Flow | Description |
|---|---|
| **Standard** (Recommended) | Pre-set options, consistent, quick, available to all plans |
| **Custom** | Full control over included content and data points, paid plans only |

The Standard flow includes a fixed set chosen by FOSSA: Dependencies Summary, Direct Dependencies, Notice File(s), Package Metadata, and Concluded License(s) when license conclusions are enabled for your organization.

### Selecting a format

FOSSA supports five output formats for licensing reports:

| Format | Best for |
|---|---|
| **HTML** | Hosting on your website or a public page |
| **PDF** | Distributing as a document to customers or auditors |
| **CSV** | Spreadsheet-based review or processing |
| **Markdown** | Embedding in source code or documentation |
| **Plain Text** | Simple distribution or embedding in built artifacts |

{% img src="/images/reports/reports-format-dropdown.png" alt="Output format dropdown open, showing HTML, PDF, CSV, Markdown, and Plain Text options" /%}

### Selecting report content

The following options control what appears in the generated report:

| Option | Description |
|---|---|
| **Dependencies Summary** | An overview of all dependencies and licenses found. |
| **Direct Dependencies** | First-level dependencies explicitly included in your project. |
| **Transitive Dependencies** | Indirect dependencies pulled in by your direct dependencies. |
| **Snippet Dependencies** | Dependencies detected via [code snippets](/docs/project-setup/snippets). Available when snippet detection is enabled for your organization. |
| **Hash and Version Data** | Includes package hashes and version identifiers for each dependency. |
| **Package Labels** | Includes any [package labels](/docs/organization-management/package-labels) assigned to packages in your organization. |
| **List of Licenses** | Includes license information for each dependency. Choose which license data to include: Declared Licenses, First Party Licenses, Copyrights from non-license text. |
| **Exclude Package Labels** | Excludes packages that have certain labels, such as Dynamically Linked, Modified, Statically Linked, or Unmodified. |
| **Concluded License(s)** | Any licenses that have been manually concluded on a dependency. Only available when the License Conclusion feature is enabled for your organization. |
| **Notice File(s)** | Verbatim text from `NOTICE.TXT`, `THIRD-PARTY-NOTICES.TXT`, and similar files. |
| **Dependency Metadata** | Per-dependency details. Choose which fields to include: Project, Authors, Description, Concluded License, Declared License, License Header, Full License Text, Discovered License(s), File Path, Package Manager, Package Homepage, Package Download URL, Dependency Paths, Issue Resolution Notes, Copyrights, License URL. |

### Excluding by package label

In Custom mode, the **Exclude Package Labels** filter lets you omit dependencies that carry specific [package labels](/docs/organization-management/package-labels) from the report output, useful for excluding test-only or internal dependencies that shouldn't appear in customer-facing attribution.

### Saving custom options

In the Custom flow, save a configuration you use often as a named preset from the **Saved Options** control, then apply it to future reports in one click. See [Report Settings](/docs/reports/report-settings) for managing presets and choosing a default. Saved options require a paid plan.

### Downloading, emailing, or hosting

Once generated, you can:

- **Download** the report to your computer immediately
- **Email** the report, for large projects, click **Email** to queue generation as a background job; the completed report is delivered to your email address
- **Host** the report via FOSSA, FOSSA generates a persistent public URL that always serves the latest version, updating automatically with each new scan

## Generating a report from the CLI

The FOSSA CLI can generate licensing reports directly, which is useful for automating report generation in CI.

```shell
export FOSSA_API_KEY=XXXXXXXX
fossa analyze && fossa report attribution --format spdx
```

{% callout type="info" %}
The CLI supports additional formats beyond the web UI: `csv`, `cyclonedx-json`, `cyclonedx-xml`, `html`, `json`, `markdown`, `spdx`, `spdx-json`, and `text`. See [fossa report](/docs/cli/references/subcommands/report) for the full reference.
{% /callout %}

## Keeping reports up to date

Attribution notices become stale as dependencies change. To keep them current:

- Integrate FOSSA into your CI pipeline so a fresh report is available at every commit
- Use the FOSSA API to fetch the latest file as part of your release process
- If using hosted reports, FOSSA updates them automatically

## Modifying dependency data for reports

If a dependency appears in your report with incorrect or missing information (wrong license, missing author, no copyright text) you can correct it directly in FOSSA before regenerating.

See [License Corrections](/docs/licenses/license-corrections) for the full workflow, including how to:

- Conclude or change a detected license
- Update author and description metadata
- Add or edit copyright text
- Remove a dependency from the report entirely

## What's next

- **[Generating SBOMs](/docs/sbom/generating-sboms)**: Export your project's full bill of materials in SPDX or CycloneDX format.
- **[Licensing Policies](/docs/policies/licensing-policies)**: Configure which licenses are approved, flagged, or denied to improve future report outcomes.
- **[Reviewing Licensing Issues](/docs/licenses/reviewing-licensing-issues)**: Resolve open licensing issues before regenerating your report.

---

Source: https://docs.fossa.com/docs/reports/remediation-guidance

# Remediation Guidance

The Remediation Guidance report gives developers a prioritized vulnerability remediation plan for a project or release group. It focuses on resolving the most impactful security issues with the least refactor effort.

The report organizes recommendations into five categories, each with a distinct priority and strategy:

- **Quick Wins**
- **High Priority Fixes**
- **Low Priority Fixes**
- **Outdated Dependencies**
- **Malicious Dependencies**

{% callout type="info" %}
The primary difference between this report and the remediation guidance shown on individual security issues is scope. This report calculates remediations in the context of all active vulnerabilities and upgrade recommendations across the entire project, including any vulnerabilities a given upgrade might introduce. Individual issue guidance covers only the best remediation path for a specific CVE or vulnerability.
{% /callout %}

## Generating the report

Open **Reports** on a project or release group and select **Remediation Guidance** from the sidebar, then choose a format and generate. Remediation Guidance requires security to be enabled for your organization and is not available for binary-only projects. For release groups, it is available when at least one project in the release group is not a binary project.

## How recommended upgrades work

FOSSA's remediation algorithm accounts for vulnerability ignore rules, vulnerabilities that a potential upgrade might introduce, and remediation metadata aggregated across its knowledge base. The algorithm avoids recommending upgrades that would worsen your overall security posture. If the nearest patch version introduces vulnerabilities of similar or greater severity, FOSSA suggests a safer upgrade path, even if it requires a larger version jump.

## Report categories

### Quick Wins

Remediation recommendations limited to patch-distance upgrades as defined by [semantic versioning](https://semver.org/). Patch upgrades should not introduce breaking changes, making these the lowest-effort fixes available.

{% img src="/images/reports/remediation-guidance-quick-wins.png" alt="Quick Wins category in the Remediation Guidance report" /%}

### High Priority Fixes

Upgrades prioritized using FOSSA's exploitability prediction algorithm, which flags true-positive security issues most likely to be exploited. The calculation draws on CVSS vectors, exploitability data sources, EPSS probability, and FOSSA's knowledge base.

After flagging high-exploitability issues, FOSSA groups remaining vulnerabilities remediable by the same upgrade, guided by the principle of maximum impact with minimum effort.

Enable the **Transitive Vulnerabilities** toggle to include indirect (transitive) dependencies that may also be remediated by a given upgrade.

{% callout type="info" %}
Transitive vulnerability guidance asserts issues that *may* (but are not confirmed to) be remediated by a direct dependency upgrade. Direct dependency guidance will be remediated with certainty.
{% /callout %}

{% img src="/images/reports/remediation-guidance-high-priority.png" alt="High Priority Fixes category in the Remediation Guidance report" /%}

### Low Priority Fixes

Remaining vulnerabilities that did not meet the High Priority threshold but still satisfy FOSSA's recommendation criteria. These are real vulnerabilities that require remediation, grouped only where the upgrade improves overall security posture.

{% img src="/images/reports/remediation-guidance-low-priority.png" alt="Low Priority Fixes category in the Remediation Guidance report" /%}

### Outdated Dependencies

Dependencies that are significantly behind the latest release; flagged proactively so teams can address them before a high-priority vulnerability appears in a future version. Which dependencies qualify is determined by your project's outdated dependencies policy. See [Quality Policies](/docs/policies/quality-policy) for configuration details.

Enable the **Exclude Vulnerable** toggle to limit this category to dependencies that do not currently contain known vulnerabilities.

{% img src="/images/reports/remediation-guidance-outdated-dependencies.png" alt="Outdated Dependencies category in the Remediation Guidance report" /%}

### Malicious Dependencies

Dependencies identified as malicious and recommended for immediate removal.

{% img src="/images/reports/remediation-guidance-malicious-dependencies.png" alt="Malicious Dependencies category in the Remediation Guidance report" /%}

## Report formats

The Remediation Guidance report is available in three formats:

| Format | Contents |
|---|---|
| **PDF** | Top 5 upgrade recommendations per category |
| **HTML** | Top 5 upgrade recommendations per category |
| **JSON** | Full report including all vulnerability details not included in PDF and HTML outputs |

---

Source: https://docs.fossa.com/docs/reports/global-reports

# Global Reports

Global reports aggregate data across every project in your organization rather than a single project or release group. They live on the **Reports** dashboard, accessible from the main navigation.

{% img src="/images/reports/global-reports-dashboard.png" alt="Reports dashboard with the team selector and the Global Package Report Bundle, Audit/Due Diligence, and Global Issue CSV Export report cards" /%}

{% callout type="info" %}
Generating global reports requires **Organization Report** or **Team Report** create permission. Users without either permission see a notice on the Reports page rather than the report cards.
{% /callout %}

## Team filtering

The **Reports** page includes a team selector in the header. When a team is selected, the Audit/Due Diligence report and Global Issue CSV Export are scoped to projects belonging to that team. The Global Package Report Bundle is not affected by the team selector.

## Global Package Report Bundle

An org-wide report on licenses and packages across all your projects, delivered by **email**.

Click **Generate report** to open the configuration modal. Choose which content to include in the bundle:

| Option | What it includes |
|---|---|
| **Package** | Package name and version for each dependency |
| **Authors** | Individuals or organizations credited with creating each package |
| **Description** | Short summary of each package's purpose |
| **Teams** | Teams associated with each project |
| **Package Homepage** | URL pointing to each package's main project page |
| **Package Manager** | The ecosystem each dependency comes from |
| **Dependency Paths** | The path from your project root to each dependency |
| **Projects** | Which projects each dependency appears in |
| **Issue Resolution Notes** | Comments or clarifications made during license identification |
| **License Template** | The standard license text for each detected license |
| **Discovered License(s)** | Licenses FOSSA identified by scanning package files |
| **Concluded License** | Final license determined after FOSSA's full analysis |
| **Packages from Binary Decomposition** | Dependencies identified from binary decomposition scans (shown only when Binary Decomposition is enabled for your organization) |

Enter your email address and click **Generate**. The bundle is sent when processing completes.

## Audit / Due Diligence Report

An org-wide report on issues and project changes, delivered by **email**.

The Audit/Due Diligence report summarizes licensing and security issue status across your organization, along with a history of project changes. It is designed for due diligence events, audits, and legal review.

Click **Generate report** and select **Email**. The report is processed as a background job and emailed when ready.

## Global Issue CSV Export

An org-wide export of all issues in CSV format, available for **immediate download** or **email delivery**.

The export produces separate CSV files for each issue type:

- **Licensing issues**
- **Security issues**
- **Quality issues**

Click **Generate report** and choose **Download** to receive the file immediately, or **Email** to have it sent when the export completes. When a team is selected in the header, the export is scoped to that team's projects.

---

Source: https://docs.fossa.com/docs/reports/report-settings

# Report Settings

Report settings control the branding and default filter presets that apply when generating reports for a project or release group. Access them at **Project Settings → Reports** or **Release Group Settings → Reports**.

## Logo

Upload a logo to appear in the header of generated reports. By default, reports use your organization's logo (configured in **Organization Settings → General**). Upload a custom logo to override the default for a specific project or release group.

Click **Remove** to revert to the organization logo.

{% img src="/images/reports/reports-settings-logo.png" alt="Logo upload section in project report settings" /%}

## Description

Add a custom description that appears in the report header. The description field supports **Markdown**. Use the **Preview** tab to see how it will render before saving.

{% img src="/images/reports/reports-settings-description.png" alt="Description field in project report settings with a Markdown editor and Preview tab" /%}


## Saved options

Saved options are named presets of report filter selections. Instead of reconfiguring filters each time you generate a report, save a configuration once in the report builder's [Custom flow](/docs/reports/licensing-report) and apply it with one click.

### Creating a saved option

{% steps %}
{% step title="Configure your filters" %}
Configure your report filters as desired in the report builder's [Custom flow](/docs/reports/licensing-report).
{% /step %}

{% step title="Open Saved Options and select Save as" %}
Open the **Saved Options** dropdown and select **Save as**.

{% img src="/images/reports/reports-saved-options-creating-01.png" alt="Saved Options dropdown open in the report builder with Save As highlighted" /%}
{% /step %}

{% step title="Name the preset" %}
Give the preset a name. It will be available for any future report generation on this project or release group.

{% img src="/images/reports/reports-saved-options-creating-02.png" alt="Save option dialog with a Name field for the new preset" /%}
{% /step %}
{% /steps %}

### Applying a saved option

Open the **Saved Options** dropdown when generating a report and select the preset to apply. The filters update to match the saved configuration. Any subsequent changes mark the option as modified, save again to update it or save as a new option to keep both.

{% img src="/images/reports/reports-saved-report-options-apply.png" alt="Saved Options dropdown open with a list of presets to select" /%}

### Managing saved options

From the **Saved Options** dropdown you can:

- **Rename**: update the preset name

    {% img src="/images/reports/reports-saved-options-rename.png" alt="Rename option dialog with the preset name in an editable Name field" /%}

- **Delete**: remove the preset permanently

    {% img src="/images/reports/reports-saved-options-delete.png" alt="Delete confirmation dialog for removing a saved options preset" /%}

{% callout type="info" %}
Creating, renaming, and deleting saved options requires a paid plan and permission to manage report options. Users without that permission can apply existing saved options but cannot create, rename, or delete them.
{% /callout %}

### Setting a default saved option

Saved options can be set as the default for a project's licensing or SBOM reports so that users land on pre-filtered results when they open the report. Set defaults in **Project Settings → Reports** or **Release Group Settings → Reports** under the **Saved Options** section.

{% img src="/images/reports/reports-saved-options-defaults.png" alt="Saved Options section in project settings showing a dropdown to select the default saved option" /%}

## SBOM author defaults

Set default author and supplier metadata for SBOM reports generated from this project or release group. These values pre-fill the SBOM author fields at report generation time; users can override them before generating.

| Field | Description |
|---|---|
| **Author Name** | Name of the person or team authoring the SBOM |
| **Author Email** | Contact email for the SBOM author |
| **Supplier** | Organization supplying the software described in the SBOM |

{% img src="/images/reports/reports-saved-options-sbom-author-defaults.png" alt="SBOM author defaults section in project settings showing Author Name, Author Email, and Supplier fields" /%}

---

Source: https://docs.fossa.com/docs/cli

# FOSSA CLI

The **FOSSA CLI** analyzes your project's dependencies from the command line, on your machine or in CI, and uploads the results to FOSSA for license, security, and quality analysis. For most projects it works with zero configuration: [install the CLI](/docs/cli/walkthroughs/installing-fossa-cli), set your [API key](/docs/api), and run `fossa analyze`.

Because it reads dependencies straight from your build, the CLI is the most accurate way to get a project into FOSSA. See [Project Setup](/docs/project-setup) for how it compares to Quick Import and the other import methods, and [CI/CD scanning](/docs/project-setup/cicd-scanning) to run it automatically on every build.

These docs are organized into **Concepts** (how analysis works), **Walkthroughs** (step-by-step integration guides), **Features** (specific capabilities like container and vendored-dependency scanning), and **References** (every command, configuration file, and troubleshooting guide). Browse them below or from the sidebar. Not sure what the CLI sends to FOSSA? See [what data gets uploaded](/docs/cli/walkthroughs/what-data-gets-uploaded).

---

Source: https://docs.fossa.com/docs/cli/concepts

# Concepts

---

Source: https://docs.fossa.com/docs/cli/concepts/analysis-and-analyzers

# Analysis Strategies

The CLI performs dependency analysis using a set of "strategies".

Strategies define how to identify user projects and how to determine the dependencies of each project. Each strategy corresponds to roughly one tool, language, or ecosystem.


## Table of contents

- [Anatomy of a strategy](#anatomy-of-a-strategy)
  - [Analysis targets](#analysis-targets)
  - [Discovery and analysis](#discovery-and-analysis)
  - [Tactics](#tactics)
- [Supported strategies](#supported-strategies)

## Anatomy of a strategy

### Analysis targets

When the CLI identifies user projects to analyze, it groups these projects into "analysis targets". The exact semantics of an analysis target depends on the language, but usually a target is a single module, package, library, or program. Usually, an analysis target is equivalent to whatever you would create a dependency manifest file for.

Analysis targets have exactly one type (which identifies which strategy is used to analyze the target) and produce exactly one dependency graph.

A single Analysis (i.e. a single run of the CLI) includes every analysis target discovered in the folder being analyzed.

You can view a list of filterable targets for analysis using [`fossa list-targets`](/docs/cli/references/subcommands/list-targets).

### Discovery and analysis

Strategies usually have two phases:

1. A _discovery_ phase, to determine which user projects are in the folder being analyzed.
2. An _analysis_ phase, where dependencies of discovered user projects are analyzed.

_Discovery_ usually works by examining the file system for special files that indicate the presence of a project. For example, a `package.json` usually indicates the presence of an NPM project, or a `pom.xml` usually indicates the presence of a Maven project.

_Analysis_ usually works by running through a series of _tactics_ for each strategy. For example, to analyze the dependencies of an NPM project, we might try to parse `package-lock.json` or execute `npm ls`.

Each strategy defines its own logic for how it does discovery, and its own logic for which tactics it uses to analyze dependencies.

### Tactics

Strategies use one or more _tactics_ to analyze the dependencies or discovered projects.

Each strategy defines its own tactics. Strategies generally have multiple tactics, and will automatically select between tactics depending on what information is available.

Tactics tend to vary across two axes:

1. What _requirements_ must be fulfilled for the tactic to succeed?
2. What _structure_ does the tactic provide in its output?

The relevant questions for _requirements_ are usually:

1. Does this tactic perform dynamic or static analysis? Tactics that do dynamic analysis usually require a functioning build environment and a CI integration, while tactics that only do static analysis only require a copy of the source code.
2. What files are necessary? Some tactics require files such as lockfiles that are not always present by default.
3. What build environment is necessary? Some tactics require running after successful builds, or being able to install build plugins.

The relevant questions for _structure_ are usually:

1. Does this tactic provide all dependencies? Some tactics are only able to provide direct dependencies, installed dependencies, or some other subset of dependencies.
2. Does this tactic provide a graph or a list? Some tactics don't provide edge information between dependencies.
3. Does this tactic provide additional dependency metadata? Some tactics are able to tag dependencies with metadata, such as whether they're test dependencies.

Each strategy's documentation contains information about its tactics and how it chooses between them.

## Supported strategies



For more information on supported strategies, see the [strategies documentation](/docs/project-setup/supported-languages#support-matrix).

---

Source: https://docs.fossa.com/docs/cli/features

# Features

---

Source: https://docs.fossa.com/docs/cli/features/custom-license-and-keyword-search-regular-expression-syntax

# Regular Expression Syntax for Custom License and Keyword Searches

Custom License and Keyword Searches use version 1.9.5 of the Rust regular expression library, [regex](https://docs.rs/regex/latest/regex).

This document describes the syntax supported by this library.

In this document, the following terms are used:

Haystack
: The text being searched

Pattern
: The string used to create a regular expression. An uncompiled regular expression

Regex or Regular Expression
: A regular expression compiled from a pattern.

## Matching one character

<pre class="rust">
.             any character except new line (includes new line with s flag)
[0-9]         any ASCII digit
\d            digit (\p{Nd})
\D            not digit
\pX           Unicode character class identified by a one-letter name
\p{Greek}     Unicode character class (general category or script)
\PX           Negated Unicode character class identified by a one-letter name
\P{Greek}     negated Unicode character class (general category or script)
</pre>

## Character classes

<pre class="rust">
[xyz]         A character class matching either x, y or z (union).
[^xyz]        A character class matching any character except x, y and z.
[a-z]         A character class matching any character in range a-z.
[[:alpha:]]   ASCII character class ([A-Za-z])
[[:^alpha:]]  Negated ASCII character class ([^A-Za-z])
[x[^xyz]]     Nested/grouping character class (matching any character except y and z)
[a-y&&xyz]    Intersection (matching x or y)
[0-9&&[^4]]   Subtraction using intersection and negation (matching 0-9 except 4)
[0-9--4]      Direct subtraction (matching 0-9 except 4)
[a-g~~b-h]    Symmetric difference (matching `a` and `h` only)
[\[\]]        Escaping in character classes (matching [ or ])
[a&&b]        An empty character class matching nothing
</pre>

Any named character class may appear inside a bracketed `[...]` character
class. For example, `[\p{Greek}[:digit:]]` matches any ASCII digit or any
codepoint in the `Greek` script. `[\p{Greek}&&\pL]` matches Greek letters.

Precedence in character classes, from most binding to least:

1. Ranges: `[a-cd]` == `[[a-c]d]`
2. Union: `[ab&&bc]` == `[[ab]&&[bc]]`
3. Intersection, difference, symmetric difference. All three have equivalent
precedence, and are evaluated in left-to-right order. For example,
`[\pL--\p{Greek}&&\p{Uppercase}]` == `[[\pL--\p{Greek}]&&\p{Uppercase}]`.
4. Negation: `[^a-z&&b]` == `[^[a-z&&b]]`.

## Composites

<pre class="rust">
xy    concatenation (x followed by y)
x|y   alternation (x or y, prefer x)
</pre>

This example shows how an alternation works, and what it means to prefer a
branch in the alternation over subsequent branches.

## Repetitions

<pre class="rust">
x*        zero or more of x (greedy)
x+        one or more of x (greedy)
x?        zero or one of x (greedy)
x*?       zero or more of x (ungreedy/lazy)
x+?       one or more of x (ungreedy/lazy)
x??       zero or one of x (ungreedy/lazy)
x{n,m}    at least n x and at most m x (greedy)
x{n,}     at least n x (greedy)
x{n}      exactly n x
x{n,m}?   at least n x and at most m x (ungreedy/lazy)
x{n,}?    at least n x (ungreedy/lazy)
x{n}?     exactly n x
</pre>

## Empty matches

<pre class="rust">
^     the beginning of a haystack (or start-of-line with multi-line mode)
$     the end of a haystack (or end-of-line with multi-line mode)
\A    only the beginning of a haystack (even with multi-line mode enabled)
\z    only the end of a haystack (even with multi-line mode enabled)
\b    a Unicode word boundary (\w on one side and \W, \A, or \z on other)
\B    not a Unicode word boundary
</pre>

The empty regex is valid and matches the empty string. For example, the
empty regex matches `abc` at positions `0`, `1`, `2` and `3`. When using the
top-level [`Regex`] on `&str` haystacks, an empty match that splits a codepoint
is guaranteed to never be returned. However, such matches are permitted when
using a [`bytes::Regex`].

Note that an empty regex is distinct from a regex that can never match.
For example, the regex `[a&&b]` is a character class that represents the
intersection of `a` and `b`. That intersection is empty, which means the
character class is empty. Since nothing is in the empty set, `[a&&b]` matches
nothing, not even the empty string.

## Grouping and flags

<pre class="rust">
(exp)          numbered capture group (indexed by opening parenthesis)
(?P&lt;name&gt;exp)  named (also numbered) capture group (names must be alpha-numeric)
(?&lt;name&gt;exp)   named (also numbered) capture group (names must be alpha-numeric)
(?:exp)        non-capturing group
(?flags)       set flags within current group
(?flags:exp)   set flags for exp (non-capturing)
</pre>

Capture group names must be any sequence of alpha-numeric Unicode codepoints,
in addition to `.`, `_`, `[` and `]`. Names must start with either an `_` or
an alphabetic codepoint. Alphabetic codepoints correspond to the `Alphabetic`
Unicode property, while numeric codepoints correspond to the union of the
`Decimal_Number`, `Letter_Number` and `Other_Number` general categories.

Flags are each a single character. For example, `(?x)` sets the flag `x`
and `(?-x)` clears the flag `x`. Multiple flags can be set or cleared at
the same time: `(?xy)` sets both the `x` and `y` flags and `(?x-y)` sets
the `x` flag and clears the `y` flag.

All flags are by default disabled unless stated otherwise. They are:

<pre class="rust">
i     case-insensitive: letters match both upper and lower case
m     multi-line mode: ^ and $ match begin/end of line
s     allow . to match \n
R     enables CRLF mode: when multi-line mode is enabled, \r\n is used
U     swap the meaning of x* and x*?
u     Unicode support (enabled by default)
x     verbose mode, ignores whitespace and allow line comments (starting with `#`)
</pre>

Note that in verbose mode, whitespace is ignored everywhere, including within
character classes. To insert whitespace, use its escaped form or a hex literal.
For example, `\ ` or `\x20` for an ASCII space.

Flags can be toggled within a pattern. Here's an example that matches
case-insensitively for the first part but case-sensitively for the second part:

```regex
(?i)a+(?-i)b+
```

Notice that the `a+` matches either `a` or `A`, but the `b+` only matches
`b`.

Multi-line mode means `^` and `$` no longer match just at the beginning/end of
the input, but also at the beginning/end of lines. This regular expression:

```regex
(?m)^line \d+
```

Will match "line " at the beginning of a line followed by some numbers. If the `(?m)` switch was not there, it would match "line " followed by some numbers only if it was at the beginning of the file being matched.

> line one
>
> line 2
>


When both CRLF mode and multi-line mode are enabled, then `^` and `$` will
match either `\r` and `\n`, but never in the middle of a `\r\n`:

```regex
(?mR)^foo$
```

Unicode mode can also be selectively disabled, although only when the result
*would not* match invalid UTF-8. One good example of this is using an ASCII
word boundary instead of a Unicode word boundary, which might make some regex
searches run faster:

```regex
(?-u:\b).+(?-u:\b)
```

## Escape sequences

Note that this includes all possible escape sequences, even ones that are
documented elsewhere.

<pre class="rust">
\*          literal *, applies to all ASCII except [0-9A-Za-z<>]
\a          bell (\x07)
\f          form feed (\x0C)
\t          horizontal tab
\n          new line
\r          carriage return
\v          vertical tab (\x0B)
\A          matches at the beginning of a haystack
\z          matches at the end of a haystack
\b          word boundary assertion
\B          negated word boundary assertion
\123        octal character code, up to three digits (when enabled)
\x7F        hex character code (exactly two digits)
\x{10FFFF}  any hex character code corresponding to a Unicode code point
\u007F      hex character code (exactly four digits)
\u{7F}      any hex character code corresponding to a Unicode code point
\U0000007F  hex character code (exactly eight digits)
\U{7F}      any hex character code corresponding to a Unicode code point
\p{Letter}  Unicode character class
\P{Letter}  negated Unicode character class
\d, \s, \w  Perl character class
\D, \S, \W  negated Perl character class
</pre>

## Perl character classes (Unicode friendly)

These classes are based on the definitions provided in
[UTS#18](https://www.unicode.org/reports/tr18/#Compatibility_Properties):

<pre class="rust">
\d     digit (\p{Nd})
\D     not digit
\s     whitespace (\p{White_Space})
\S     not whitespace
\w     word character (\p{Alphabetic} + \p{M} + \d + \p{Pc} + \p{Join_Control})
\W     not word character
</pre>

## ASCII character classes

These classes are based on the definitions provided in
[UTS#18](https://www.unicode.org/reports/tr18/#Compatibility_Properties):

<pre class="rust">
[[:alnum:]]    alphanumeric ([0-9A-Za-z])
[[:alpha:]]    alphabetic ([A-Za-z])
[[:ascii:]]    ASCII ([\x00-\x7F])
[[:blank:]]    blank ([\t ])
[[:cntrl:]]    control ([\x00-\x1F\x7F])
[[:digit:]]    digits ([0-9])
[[:graph:]]    graphical ([!-~])
[[:lower:]]    lower case ([a-z])
[[:print:]]    printable ([ -~])
[[:punct:]]    punctuation ([!-/:-@\[-`{-~])
[[:space:]]    whitespace ([\t\n\v\f\r ])
[[:upper:]]    upper case ([A-Z])
[[:word:]]     word characters ([0-9A-Za-z_])
[[:xdigit:]]   hex digit ([0-9A-Fa-f])
</pre>

---

Source: https://docs.fossa.com/docs/cli/features/custom-license-and-keyword-searches

# Custom-License and Keyword Searches

FOSSA offers the ability to search your codebase using regular expressions and to report matches. These matches can be reported in two different ways: Keyword Searches or Custom-License Searches.

For both of these searches, you provide a `name` and a `matchCriteria`. The `name` is a description of what you are searching for. The `matchCriteria` is a regular expression used to find the thing you are searching for.

The simplest way to provide these values is in your `.fossa.yml` config file. Here is an example config file that does both a Keyword Search and a Custom-License Search. It is searching case-insensitively for the phrase "this project is provided under a proprietary license" as a custom license with a name of "Proprietary License". It is also searching for the string "abc123" as a keyword search with a name of "Password".

```yaml
version: 3

customLicenseSearch:
  - matchCriteria: (?i)this project is provided under a proprietary license
    name: Proprietary License

experimentalKeywordSearch:
  - matchCriteria: abc123
    name: Password
```

Both of these searches will run the regular expression provided in the `matchCriteria` field on every non-binary file in the directory that you are searching. The difference is in how the results are used.

## Keyword Searches

If a match to a keyword search is found, then the results of that search are output in the scan summary that `fossa analyze` outputs. For example, if you have just the `experimentalKeywordSearch` entry in the above `.fossa.yml` file and search a project that contains the string "abc123" in two files, then you will see something like this in the scan summary:

```
* Keyword Search: succeeded
  ** Password - /Users/me/myproject/something.txt (lines 3-3)
  ** Password - /Users/me/myproject/some/subdirectory/anotherfile.txt (lines 31-31)
```

## Custom License Searches

If a match to a custom-license search is found, then the CLI will add the match to the licenses reported for the project being searched. The license will be identified as a "Custom License", and the name that you provided will be used in the FOSSA UI and in reports when displaying that license.

The result will also be output in the scan summary, just as it is for [Keyword Searches](#keyword-searches).

For example, if you have just the `customLicenseSearch` entry in the example `.fossa.yml` above and you find a match to the regular expression in two files, then the scan summary will look something like this:

```
* Custom-License Search: succeeded
  ** Proprietary License - /Users/me/myproject/LICENSE (lines 4-4)
  ** Proprietary License - /Users/me/myproject/src/main.rs (lines 2-3)
```

This will create a custom license match in your project in FOSSA. The results of that in the UI will look something like this:

![A Custom License in the FOSSA UI](/cli/assets/custom-license-scan-licenses-in-ui.png)

The custom license will also be included in reports, and will look something like this:

![A Custom License in a FOSSA Licensing report](/cli/assets/custom-license-scan-report.png)

Note that the name will be used as the license's name in the UI, so it is important to use names that are understandable to someone looking at license issues and viewing a report.

If your project is set to raise issues for a license of type "Custom License", then an issue will be raised for any custom licenses found.

## Regular expression format

The regular expressions in Custom License and Keyword searches use Rust's regular expression syntax. Here are a few examples. You can also view the [full regular expression syntax documentation](/docs/cli/features/custom-license-and-keyword-search-regular-expression-syntax).

### Searching for an exact match to some text

Most of the time, if you are searching for an exact match to some text you can just use the text. For example, if you wanted to find the phrase "This code has been released into the public domain", you could just use that as your match criteria:

```yaml
customLicenseSearch:
  - matchCriteria: This code has been released into the public domain
    name: public domain
```

If the text you are searching for contains any special characters that need to be escaped, then you will need to escape those characters by prepending a `\` to them. Please see the next section for a list of these special characters and some examples.

### Escapes in your regular expressions

If the text you are searching for has one of the following special characters in it, then you will need to "escape" that character by prepending a `\` to it.

Special Characters:

| `.` |
| `^` |
| `$` |
| `*` |
| `+` |
| `?` |
| `(` |
| `)` |
| `[` |
| `{` |
| `\` |
| `|` |

For example, if you were searching for the text 'associated documentation files (the "Software").', then you would have to escape the opening and closing parentheses and the final period in the sentence, like this:

```yaml
customLicenseSearch:
  - matchCriteria: associated documentation files \(the "Software"\)\.
    name: associated documentation
```

If you wrap your `matchCriteria` in single quotes or no quotes in `.fossa.yml`, then you should use a single backslash (`\`) to escape characters.

If you use double quotes, then you will need to use two backslashes (`\\`) to escape characters.

So in the example below, we are using the same regular expression three times. Once with double quotes, once with no quotes and the final time with single quotes.

Note that we have to escape the double-quotes in the regular expression when we wrap it in double-quotes.

```yaml
version: 3

customLicenseSearch:
  - matchCriteria: "to any person obtaining a copy of this software and associated documentation files \\(the \"Software\"\\)"
    name: Obtaining Clause, double quotes
  - matchCriteria: to any person obtaining a copy of this software and associated documentation files \(the "Software"\)
    name: Obtaining Clause, no quotes
  - matchCriteria: 'to any person obtaining a copy of this software and associated documentation files \(the "Software"\)'
    name: Obtaining Clause, single quotes
```

We recommend using single quotes or no quotes.

### Searching for a phrase with some characters capitalized

If you want to search for the phrase "proprietary license", but you know that the "P" and the "L" are sometimes capitalized, you can use a [character class](/docs/cli/features/custom-license-and-keyword-search-regular-expression-syntax#character-classes) to match the capitalized and uncapitalized versions.

```
[Pp]roprietary [Ll]icense
```

This will match "Proprietary License", "proprietary license", "proprietary License" and "Proprietary License". It will not match if any of the other characters are capitalized. For example, "PROPRIETARY LICENSE" will not match.

### Ignoring case

You can ignore case by using the case-insensitive [flag](/docs/cli/features/custom-license-and-keyword-search-regular-expression-syntax#character-classes), `i`. This is done by prepending `(?i)` to your regular expression. Everything after `(?i)` will be matched case-insenitively.

```
(?i)custom license
```

This will match "Custom License", "CUSTOM LICENSE", "custom license" or "CusTOm LiCenSe".

### Matching newlines

If you have some text that has newlines in it, you can match it by using `\s+` wherever there is a newline.

For example, if you had this text in a file:

> This is one of of my license
>
> and this is the second line

Then you could match this with this regular expression:

```
This is line one of my license\s+and this is the second line
```

We use `\s+` instead of just `\s` so that this will match both Unix-style newlines (which are a single character) and Windows style newlines (which consist of two characters).

The `\s+` character class will match to spaces as well as newlines. So the following text will also match:

> This is one of of my license and this is the second line

### Matching at the beginning or end of a line

In a regular expression, `^` matches to the beginning of the string we are searching in (the haystack) and `$` to the end of the haystack. If you turn on multi-line mode using [`(?m)`](/docs/cli/features/custom-license-and-keyword-search-regular-expression-syntax#character-classes), then `^` matches to the beginning of a line in the haystack and `$` matches to the end of a line.

So if you want to find the string "Permission is hereby granted, free of charge", but only if it happens at the beginning of a line, then you would use this regular expression:

```
(?m)^Permission is hereby granted, free of charge
```

Without the `(?m)`, it would only match at the beginning of a file.

If you wanted to allow some optional whitespace before "Permission", you could add a `\s*` after the  `(?m)` flag, as `\s*` matches zero or more space characters:

```
(?m)^\s*Permission is hereby granted, free of charge
```

Finally, if you also wanted to allow an optional comment delimiter before the license, you could do this:

```
# is for Bash, Perl, Ruby, etc
/*, // and * are for c-like comments
-- is for Haskell
(?m)\s*(#|/\*|\*|//|--)?\s*Permission is hereby granted, free of charge
```

### Matching to a year

To match to a year, you can use the number [character class](/docs/cli/features/custom-license-and-keyword-search-regular-expression-syntax#perl-character-classes-unicode-friendly)) four times. This will match a four digit year:

```
(?i)this document was last updated in \d\d\d\d
```

You could also specify the number of [repetitions](/docs/cli/features/custom-license-and-keyword-search-regular-expression-syntax#repetitions), by putting the number of repetitions in curly quotes (`{4}`), like this:

```
(?i)this document was last updated in \d{4}
```

These regular expressions will both match, for example, "This document was last updated in 2023".

## Troubleshooting Regular Expressions

It can be extremely useful to use a tool that allows you to debug your regular expressions. We recommend using [Regex 101](https://regex101.com/), as it has support for Rust regular expressions.

To use this tool, go to [Regex 101](https://regex101.com/) and select "Rust" for your regular expression flavor. Then, after removing any sensitive data, enter the text you would like to search for in the "Test String" box and the regular expression in the "Regular Expression" box.

## Configuring custom-license searches for your whole organization

If you want to search for the same custom licenses for every project you analyze with `fossa analyze`, you can set up custom license searches in FOSSA's admin UI.

In order to do this you must have permission to edit your admin's Integration Settings. If you have this permission, you can go to the "account settings" page, click on the "Integrations" tab and then the "Custom License Scans" sub-navigation.

![The settings dropdown](/cli/assets/settings-dropdown.png)

![The Custom License Scans settings page](/cli/assets/custom-license-scans-settings-page.png)

You can then add custom license searches. Once you do this, anyone in your organization who runs `fossa analyze` will run the configured custom-license searches.

Any custom-license searches configured in the repositories `.fossa.yml` file will also be run.

### Escape characters in custom-license searches for your whole organization

The match criteria in the admin interface should be escaped with single backslashes (`\`). For example, if you wanted to match a phrase containing a four-digit year, you would use

```
(?i)this document was last updated in \d\d\d\d
```

### Turning off organization-wide custom-license searches

You can ignore the organization wide custom-license searches by providing the `--ignore-org-wide-custom-license-scan-configs` flag when you run `fossa analyze`:

```
fossa analyze --ignore-org-wide-custom-license-scan-configs
```

You can also set the `orgWideCustomLicenseScanConfigPolicy` flag to `true` in your `.fossa.yml` file. For example:

```yaml
version: 3
orgWideCustomLicenseScanConfigPolicy: true
```

---

Source: https://docs.fossa.com/docs/cli/features/first-party-license-scans

# First-Party License Scans

First-party license scans allow you to find licenses in your project's code.

Normally, FOSSA will find licenses in your dependencies but not scan for licenses found in your code. This is because for most cases the code you are scanning does not contain licenses that you need to comply with.

However, if you do need to find licenses in your code you can do this by running a first-party license scans. The licenses found in your code will show up as "Directly In Code" in the FOSSA UI. For example, here are the results from scanning [broker](https://github.com/fossas/broker), which has an Apache-2.0 license.

![](/cli/assets/first-party-scan.png)

By default the FOSSA CLI will not run first-party license scans on your code. You can turn on first-party scans by using the `--experimental-force-first-party-scans` flag. FOSSA can make first-party scans the default for your organization by turning on a feature flag. If you are interested in turning this feature on for your organization, please [contact us](https://support.fossa.com).

We recommend running some analyses with first-party license scans turned on for a few of your projects before turning it on for your whole organization.

You can turn on first-party license scans for an individual scan by using the `--experimental-force-first-party-scans` flag when you run `fossa analyze`. E.g.

```bash
fossa analyze --experimental-force-first-party-scans .
```

If your organization has first-party scans on by default, you can turn off first-party license scans off for an individual scan by using the `--experimental-block-first-party-scans` flag. E.g.

```bash
fossa analyze --experimental-block-first-party-scans .
```

## Path filtering First-Party License Scans

You can use path filters to exclude and include paths that are license scanned.

This is done in exactly the same way that you do path filtering for [Vendored Dependencies](/docs/cli/features/vendored-dependencies#path-filtering). You add a section to `.fossa.yml`that will look something like this. This `vendoredDependencies.licenseScanPathFilters` section will affect the paths scanned for both vendored dependency and first-party license scans.

```yaml
version: 3
vendoredDependencies:
  licenseScanPathFilters:
    only:
      - "**/*.rb"
      - "**/LICENSE"
    exclude:
      - "**/test/**"
      - "**/test/*"
      - "**/spec/**"
      - "**/spec/*"
```

For a full explanation of how this works, see the documentation for [Vendored Dependencies](/docs/cli/features/vendored-dependencies#path-filtering).

## First-Party License Scans and Vendored Dependencies

The FOSSA CLI's [Vendored Dependency](/docs/cli/features/vendored-dependencies) feature allows you to run a license scan on vendored dependencies.

This is closely related to the first-party license scan feature. Vendored dependency scans are intended to be used when you are scanning third-party code that has been vendored into a directory in your project. Only the directories specified for each vendored dependency will be scanned for licenses, and the vendored dependencies will show up as dependencies in the FOSSA UI.

First-party license scans scan the whole project for licenses, and licenses found are marked as directly found in your code.

You can also combine first-party license scans and vendored dependencies. If you run a first-party license scan and there are vendored dependencies, the FOSSA CLI will skip the vendored dependencies when scanning for licenses in the first-party scan. E.g. if you have a directory structure like this:

```
.
├── FIRST_LICENSE
├── another-dependency.zip
├── fossa-deps.yml
├── src
│   ├── foo.rb
│   ├── src
│       ├── my_project.rb
│       └── subdir
│           └── my_project_again.rb
├── runit
    ├── VENDORED_LICENSE
    ├── foo.rb
    ├── src
        ├── runit.rb
        ├── runit_external.rb
        └── subdir
            └── again.rb
```

And fossa-deps.yml looks like this:

```yaml
vendored-dependencies:
  - name: runit
    path: runit
    version: 2.0.19
```

Then any licenses found in the `runit` directory will be part of the `runit` vendored dependency, and any licenses found in the root or the `src` directory will be found by the first-party license scan and will be reported as licenses found directly in code in the FOSSA UI.

---

Source: https://docs.fossa.com/docs/cli/features/manual-dependencies

# Manually specifying dependencies

## Manually specifying dependencies

FOSSA offers a way to manually upload dependencies provided we support the dependency type. Manually specifying dependencies is very helpful in the event your package manager is unsupported or you are using a custom and nonstandard dependency management solution.

The FOSSA CLI will automatically read a `fossa-deps.yml` or a `fossa-deps.json` file in the root directory (usually the current working directory) when `fossa analyze` is run and parse dependencies from it. These dependencies will be added to the dependencies that are normally found when `fossa analyze` is run in the directory.

FOSSA CLI supports 4 types of manual dependencies:
1. Referenced dependencies: Used for packages that originate from a known package manager.
2. Custom dependencies: Used to add a unique dependency to your dependency graph and the metadata you wish to associate with it.
3. Remote dependencies: Used when all you have is the URL to an archive.
4. Vendored dependencies: Used when open-source source code is copied directly into your project and you want FOSSA to license-scan it in place. See [Vendored dependencies](/docs/cli/features/vendored-dependencies) for the full guide.

| Manual Dependency Type | Supports Licenses | Supports Vulnerabilities | Performance |
|----------------------|----------------|----------------------|-------------|
| [Referenced](#referenced-dependencies) | Yes | Yes* | Caches by (type, name, version) |
| [Remote](#remote-dependencies) | Yes | No | Caches by (name, url, version) |
| [Custom](#custom-dependencies) | Yes | No | No caching |
| [Vendored](/docs/cli/features/vendored-dependencies) | Yes | No | License-scanned in place; cached by revision |

*Referenced dependencies are the only type that supports vulnerabilities; custom, remote, and vendored dependencies do not. Reference dependencies of type `url` also do not support vulnerabilities.

> Tip: Use a script to generate this file before running `fossa analyze` to keep your results updated.

### Referenced Dependencies

To manually specify a dependency, you must provide the package type, package name, and optionally a package version, under the `referenced-dependencies` array, as shown here:

```yaml
referenced-dependencies:
- type: gem
  name: iron
- type: pypi
  name: Django
  version: "2.1.7"
```

The `name` and `type` fields are required and specify the name of the dependency and where to find it. The `version` field is optional and specifies the preferred version of the dependency.

Note: When parsed, YAML considers text that could be a decimal number (such as 1.0 or 2.0) to be a number, not a string. This means that 1.0 would be parsed as 1. This probably isn't what you want. To avoid this, surround your version with quotes, as in "1.0".

Supported dependency types:

- `bower` - Bower dependencies that are typically found at [bower.io](https://registry.bower.io).

- `cargo` - Rust dependencies that are typically found at [crates.io](https://crates.io/).
- `carthage` - Dependencies as specified by the [Carthage](https://github.com/Carthage/Carthage) package manager.
- `composer` - Dependencies specified by the PHP package manager [Composer](https://getcomposer.org/), which are located on [Packagist](https://packagist.org/).
- `cpan` - Dependencies located on the [CPAN package manager](https://www.cpan.org/).

- `cran` - Dependencies located on the [CRAN](https://cran.r-project.org/) like repository.
- `gem` - Dependencies which can be found at [RubyGems.org](https://rubygems.org/).
- `git` - Git projects (which may appear as dependencies in many package managers). Specified as the full link to the Git repo. GitHub project example: `https://github.com/fossas/fossa-cli`.
- `go` - Go specific dependency. Many Go dependencies are located on Github, but there are some which look like the following `go.mongodb.org/mongo-driver` that have custom Go URLs.
- `hackage` - Haskell dependencies found at [Hackage](https://hackage.haskell.org/).
- `hex` - Erlang and Elixir dependencies that are found at [Hex.pm](https://hex.pm/).
- `maven` - Maven dependencies that can be found at many different sources. Specified as `name: javax.xml.bind:jaxb-api` where the convention is `groupId:artifactId`.

- `npm` - Javascript dependencies found at [npmjs.com](https://www.npmjs.com/).
- `nuget` - .NET dependencies found at [NuGet.org](https://www.nuget.org/).
- `pypi` - Python dependencies that are typically found at [Pypi.org](https://pypi.org/).
- `swift` - Swift dependencies using the [Swift Package Manager](https://www.swift.org/package-manager/).
- `cocoapods` - Swift and Objective-C dependencies found at [Cocoapods.org](https://cocoapods.org/).

The following dependency types are also supported but they require `arch`, `os`, and `osVersion` attributes:

- `apk` - Alpine packages.
- `deb` - Debian packages.
- `rpm-generic` - Rpm packages.

At this moment the following `os` are supported:

- `alpine`
- `centos`
- `debian`
- `redhat`
- `ubuntu`
- `oraclelinux`
- `busybox`
- `sles`
- `fedora`
- `rocky`

For example:

```yaml
referenced-dependencies:
 - name: musl
   version: 1.2.3-r0
   type: apk
   arch: x86_64
   os: alpine
   osVersion: 3.16.2

 - name: bash
   type: deb
   version: 5.1-6ubuntu1
   arch: amd64
   os: ubuntu
   osVersion: 22.04

 - name: bash
   type: rpm-generic
   version: 4.4.19-14.el8
   os: centos
   arch: x86_64
   osVersion: 8
```

You should choose `architecture`, `os`, and `osVersion` values based on the package
information. If you are unsure of how to identify these values for these packages
refer to the table below:

| type        | version                                                                                                                        | architecture                                                                                                                                                                    |
|-------------|--------------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| apk         | version value from `apk info -vv`<br>e.g. for `musl-1.2.3-r0` version is `1.2.3-r0`                                            | `A` field in alpine database, or `Architecture` field in PKGINFO.<br>You can also infer architecture from calling `arch` command on system where this <br>package is installed. |
| deb         | version value from `dpkg -p package`                                                                                           | `Architecture` field from `dpkg -p package` query                                                                                                                               |
| rpm-generic | `version-release` value from `rpm -qi package` query. <br>e.g `Version: 4.4.19 Release: 14.el-8` translates to `4.4.19-14.el8` | `Architecture` field from `rpm -qi package` query                                                                                                                               |

For `os` and `osVersion`, refer to `ID` value and `VERSION_ID` value from `/etc/os-release` of target system.


### Custom dependencies

FOSSA supports users that have dependencies that can't be automatically discovered or identified, by offering the ability to define new dependencies.

To do this, you must supply the name, version, and license of the dependency.  This creates a stub package which requires no source code or linkage to any other system, but still acts as a normal dependency in other areas of FOSSA, like reports and the dependency views.

You may also supply a description and/or url, but both are optional.  Note that these fields reference the dependency itself, and do not reference the parent project (the one at the current analysis directory), or the individual versions of the dependency.

```yaml
custom-dependencies:
# Custom dependencies need name, version, and license
- name: foo
  version: "1.2.3"
  license: "MIT or Apache-2.0"
# You can also provide a description and/or homepage. These values populate metadata fields in reports in the FOSSA web UI.
- 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.
```

Note: When parsed, YAML considers text that could be a decimal number (such as 1.0 or 2.0) to be a number, not a string. This means that we'd parse the version 1.0 as 1. This probably isn't what you want. To avoid this, surround your version with quotes, as in "1.0".

> Note: Custom dependencies **do not** support vulnerabilites.

### Remote dependencies

FOSSA also supports dependencies when the user has a URL to an archive of the source code of the dependency.

To specify a remote dependency, you must provide the name, version, and download URL of the dependency. The FOSSA backend will attempt to download and scan any source code contained in an archive hosted at this URL. The following archive types are supported: *.zip, *.tar, *.tar.gz, *.tar.bz2, *.tar.xz.

For example, for a dependency released on a GitHub release, your URL might look like: `https://github.com/fossas/fossa-cli/archive/refs/tags/v3.3.12.tar.gz`.

You can also optionally add metadata fields ("description" and "homepage") to populate these fields in the FOSSA web UI (these fields can be displayed when generating reports).

```yaml
remote-dependencies:
# Remote dependencies require name, version, and URL fields.
- name: foo
  version: 1.2.3
  url: https://www.fooarchive.tar.gz
# You can also provide a description and/or homepage. These values populate metadata fields in reports in the FOSSA web UI.
- name: foo-wrapper
  version: 1.2.3
  url: https://www.foowrapper.tar.gz
  metadata:
    description: Provides foo and a helpful interface around foo-like tasks.
    homepage: https://www.foowrapper-home.com
```

> Note: Remote dependencies **do not** support vulnerabilites.

## Performance

The FOSSA service caches the results of dependency analysis depending on the type of remote dependency specified (explained below).
Due to this caching setup, it is normal for the first analysis to take some time, especially for larger projects, but future analysis of dependencies with the same information should be fast.

### Referenced dependencies

Most `referenced-dependencies` are cached by the combination of their `(type, name, version)` fields.
If `version` is not provided, the system assumes the version is "latest", and caching is usually not applied.

For dependency types that require `arch`, `os`, and `osVersion` attributes, these fields are additionally considered for the cache.

In the event caching is causing problems, FOSSA can be made to rebuild this kind of dependency:
Click the dependency in the UI and then click "Reanalyze".
This button enqueues a background job to rebuild the dependency, which should resolve after a few minutes.

### Custom dependencies

`custom-dependencies` do not require analysis by the FOSSA backend and are therefore not cached.

### Remote dependencies

`remote-dependencies` are cached by their `(name, url, version)` fields, which are all required.

In the event caching is causing problems, FOSSA can be made to rebuild this kind of dependency:
Click the dependency in the UI and then click "Reanalyze".
This button enqueues a background job to rebuild the dependency, which should resolve after a few minutes.

---

Source: https://docs.fossa.com/docs/cli/features/snippet-scanning

# Snippet Scanning

Snippet scanning identifies potential open source code snippets within your first-party source code by comparing file fingerprints against FOSSA's knowledge base. This feature helps detect code that may have been copied from open source projects.

Snippet Scanning runs as part of `fossa analyze`. To enable it, add the `--snippet-scan` flag when you run `fossa analyze`:

```
fossa analyze --snippet-scan
```

Snippet Scanning must also be enabled for your organization, and is only available for enterprise customers. If you would like to enable it for your organization, please [contact us](https://support.fossa.com).

## How Snippet Scanning Works

When `--snippet-scan` is enabled, the CLI:

1. **Hashes Files First**: Creates CRC64 hashes of all source files to identify which files need fingerprinting
2. **Checks Necessity of Fingerprinting**: Checks with FOSSA servers to determine which file hashes are already known
3. **Fingerprints New or Changed Files**: Uses the Ficus fingerprinting engine to create cryptographic fingerprints only for files not previously seen
4. **Filters Content**: By default, skips directories like `.git/`, and hidden directories. This includes, from `.fossa.yml`, `vendoredDependencies.licenseScanPathFilters.exclude`, documented further below.
5. **Uploads Fingerprints**: Sends only the fingerprints to FOSSA's servers
6. **Receives Matches**: Gets back information about any matching open source components
7. **Uploads Match Contents**: For files that have matches, uploads source code content temporarily to FOSSA servers (see below for more details on what we send and how long it is retained for).

## Data Sent to FOSSA

**For Performance Optimization:**
- CRC64 hashes of all files, to avoid re-fingerprinting unchanged files.

**For Fingerprinting:**
- Fingerprints of source code to identify matches.

**For Matched Files Only:**
- The full content of all files that contain snippet matches.

## Data Retention

- **File Fingerprints**: Stored permanently for caching and performance optimization
- **Source Code Content**: Stored temporarily for 30 days and then automatically deleted
- **CRC64 Hashes**: The likelihood of a collision with CRC64 (2^64 possible values) is extremely low.

## Directory Filtering

By default, snippet scanning excludes common non-production directories and follows `.gitignore` patterns:

- Hidden directories.
- Globs as directed by `.gitignore` files.

#### Custom Exclude Filtering

You can customize which files and directories are excluded from snippet scanning by configuring exclude filters in your `.fossa.yml` file. Note that snippet scanning currently only supports exclude patterns, not `only` patterns.

For example:
```yaml
version: 3
vendoredDependencies:
  licenseScanPathFilters:
    exclude:
      - "**/test/**"
      - "**/tests/**"
      - "**/spec/**"
      - "**/node_modules/**"
      - "**/dist/**"
      - "**/build/**"
      - "**/*.test.js"
      - "**/*.spec.ts"
```

**Important Notes:**

- Snippet scanning only uses the `exclude` filters from `licenseScanPathFilters` - `only` filters are ignored for this use-case.
- Path filters use standard glob patterns (e.g., `**/*` for recursive matching, `*` for single-directory matching).
- The configuration goes in the `vendoredDependencies.licenseScanPathFilters.exclude` section.
- These exclude patterns are passed directly to the Ficus fingerprinting engine as `--exclude` arguments.
- Default exclusions (hidden files, `.gitignore` patterns) are applied in addition to custom excludes.

## A note on scan times

The first time you run a snippet scan on a codebase, it may take a long time to scan. For example, scanning [Linux](https://github.com/torvalds/linux) for the first time takes around 60 minutes. This is because most of the files in your codebase will not exist in FOSSA's knowledge base, and we will need to fingerprint and compare all of them to our snippet scan corpus.

However, the next time you scan that codebase we will only need to re-fingerprint and compare files that have changed since the previous scan, and the scan will be much faster. For example, if you snippet scan that same revision of Linux a second time, the scan will complete in less than a minute.

Because of this speed difference, we recommend doing a manual scan of your project before enabling Snippet Scanning in CI. This will avoid running multiple slow scans, as any scans started before the first scan completes will also be slower.

The time it takes to scan newer versions of your codebase will depend on how many files in the new version have not been previously scanned. A file has been previously scanned if the exact same file has ever been snippet scanned. FOSSA recommends snippet scanning your codebase on a regular basis to keep scan times low.

## The Snippet Scan Summary


When a Snippet Scan completes, the CLI will output a summary of the scan. It will look like this:

```
 ============================================================
  Snippet scan summary:
    Analysis ID: 110054
    Bucket ID: 110551
    Files skipped: 6
    Total Files processed: 18
    Unique Files processed: 13
    Unique Files with matches found: 4
    Unique Files with no matches found: 9
    Unique Files already in our knowledge base: 11
    Unique Files new to our knowledge base: 2
    Processing time: 0.087s
  ============================================================
```

Here is a description of what each line means:

<dl>
<dt>Analysis ID</dt>
<dd>The ID of the Snippet Scan analysis stored in FOSSA's servers. This is used by FOSSA's support team.</dd>

<dt>Bucket ID</dt>
<dd>The ID of the temporary storage bucket where we store Snippet Scan results before processing them. This is used by FOSSA's support team.</dd>

<dt>Files Skipped</dt>
<dd>The number of files skipped during the Snippet Scan.</dd>

<dt>Total Files Processed</dt>
<dd>The number of files processed during the Snippet Scan. This count includes every processed file, even if the same file contents are included multiple times.</dd>

<dt>Unique Files processed</dt>
<dd>The number of unique files processed during the Snippet Scan. If we scan multiple files with the same contents, they will only be counted once.</dd>

<dt>Unique Files with matches found</dt>
<dd>The number of unique files where we found a potential match to Open Source code</dd>

<dt>Unique files with no matches found</dt>
<dd>The number of unique files where no potential matches to Open Source code were found.</dd>

<dt>Unique Files already in our knowledge base</dt>
<dd>The number of files that already exist in FOSSA's knowledge base. These files do not need to be fingerprinted.</dd>

<dt>Unique Files new to our knowledge base</dt>
<dd>The number of files that do not exist in FOSSA's knowledge base. These files needed to be fingerprinted in this Snippet Scan.</dd>
</dl>

## Invalid certificate errors

You may encounter an error like:

```
error uploading digest batch:
   0: upload digests
   1: error sending request for url (https://app.fossa.com/api/proxy/analysis/api/x/snippets/digests)
   2: client error (Connect)
   3: invalid peer certificate: UnknownIssuer
```

This can occur in environments that use custom TLS certificates. To resolve this,
set the `ALLOW_INVALID_CERTS` environment variable:

```sh
ALLOW_INVALID_CERTS=1 fossa analyze --snippet-scan
```

This instructs the CLI to accept certificates it cannot verify.

---

Source: https://docs.fossa.com/docs/cli/features/strategy-command-selection

# Strategy command selection

In some strategies, FOSSA CLI uses actual package managers or build tools in order to analyze the dependencies of a project.
FOSSA refers to such strategies as "dynamic analysis strategies".

Some dynamic analysis strategies have multiple command options to use, preferred in a fallback manner.
FOSSA refers to these as "candidate commands".

FOSSA CLI chooses which command in a list of _candidate commands_ to use by running each command
with a set of flags suitable for determining whether the candidate will work for FOSSA CLI.
The particular flags used are up to each strategy; sometimes they simply test whether the command is able to run,
and sometimes they may test that the command is of a particular minimum version or supports some capability.
FOSSA refers to these flags as _evaluation flags_.

If the command, run with the _evaluation flags_, exits with a non-zero exit code FOSSA CLI
determines that the candidate command is unsuitable and moves on to the next candidate.
If no suitable command is found, the overall strategy fails.

If a _candidate command_ was chosen, but then later fails, FOSSA CLI treats
this as an overall strategy failure since that command was determined to be the correct
one to use for the project.

## Concrete example: Maven

For example the "Maven" strategy prefers, in order:

1. The command provided by the user via `FOSSA_MAVEN_CMD`, if present.
2. The local `mvnw` command, if one is found in the project or an ancestor directory.
3. The `mvn` command in `$PATH`.

Suppose FOSSA CLI is analyzing the following project:
```
.
├── mvnw
├── pom.xml
├── readme.md
└── src
   └── main
      └── java
         └── org
            └── apache
               └── maven
                  └── wrapper
                     └── BootstrapMainStarter.java
```

And that FOSSA CLI is being run with the following command:
```
FOSSA_MAVEN_CMD=/usr/local/bin/custom-mvn fossa analyze
```

This results in the following list of candidate commands,
where the earlier in the list the command appears, the higher priority that command has:
```
[ "/usr/local/bin/custom-mvn"
, "./mvnw"
, "mvn"
]
```

FOSSA CLI evaluates these candidates with the following commands in sequence,
stopping after the first one evaluates with exit code zero (signifying no error):
```
; /usr/local/bin/custom-mvn -v # exit code 1
; ./mvnw -v # exit code 0
```

Since `./mvnw` appears suitable, FOSSA CLI chooses that as the command to use
and performs analysis on this Maven project using the `./mvnw` command.

---

Source: https://docs.fossa.com/docs/cli/features/vendetta

# Vendetta

Vendetta is the name of FOSSA's vendored dependency identification feature.

Vendetta hashes files in your first party source code, compares them against
FOSSA's knowledge base, and matches them to common open source components before
finally feeding those matches to a special algorithm that deduces a holistic set
of vendored open source dependencies present in your project.

Vendetta can be run as part of `fossa analyze`. To enable it, add the
`--x-vendetta` flag when you run `fossa analyze`:

```sh
fossa analyze --x-vendetta
```

## How Vendetta Works

When `--x-vendetta` is enabled, the CLI:

1. **Hashes Files**: Creates MD5 hashes of the contents of all relevant files.
2. **Filters Content**: By default, skips directories like `.git/`, and hidden
    directories. This includes, from `.fossa.yml`,
    `vendoredDependencies.licenseScanPathFilters.exclude`, documented further
    below.
5. **Uploads Hashes**: Sends only the hashes to FOSSA's servers.
6. **Receives Matches**: Gets back information about any matching open source
   components.
7. **Infers Dependencies**: Feeds the matches to an algorithm that heuristically
   identifies the vendored dependencies in your project.

## Data Sent to FOSSA

Vendetta sends _only_ the MD5 hashes of your file contents to FOSSA. The raw
contents are never sent to FOSSA.

## Data Retention

The MD5 hashes are stored permanently in FOSSA.

## Directory Filtering

By default, Vendetta excludes common non-production directories and follows
`.gitignore` patterns:

- Hidden directories.
- Globs as directed by `.gitignore` files.

#### Custom Exclude Filtering

You can customize which files and directories are excluded from Vendetta by
configuring exclude filters in your `.fossa.yml` file. Note that Vendetta scans
currently only support exclude patterns, not `only` patterns.

For example:
```yaml
version: 3
vendoredDependencies:
  licenseScanPathFilters:
    exclude:
      - "**/test/**"
      - "**/tests/**"
      - "**/spec/**"
      - "**/node_modules/**"
      - "**/dist/**"
      - "**/build/**"
      - "**/*.test.js"
      - "**/*.spec.ts"
```

**Important Notes:**

- Vendetta scanning only use the `exclude` filters from `licenseScanPathFilters`.
  - `only` filters are ignored for this use-case.
- Path filters use standard glob patterns (e.g., `**/*` for recursive matching,
  `*` for single-directory matching).
- The configuration goes in the
  `vendoredDependencies.licenseScanPathFilters.exclude` section.
- These exclude patterns are passed directly to the Ficus scanning engine as
  `--exclude` arguments.
- Default exclusions (hidden files, `.gitignore` patterns) are applied in
  addition to custom excludes.

## A note on scan times

The first time you run Vendetta on a codebase, it may take a long time to scan.
For example, scanning [Linux](https://github.com/torvalds/linux) for the first
time may take upwards of 60 minutes. This is because most of the files in your
codebase will have never been checked against FOSSA's knowledge base for open
source components, which can take time.

Once you scan the first time however, FOSSA will cache the open source component
matches for each MD5 hash Vendetta provides. This means that subsequent scans of
the same project will be drastically faster. For example, scanning the same
revision of Linux twice in a row should result in the second scan taking only
1-2 minutes.

The time it takes to scan newer versions of your codebase will depend on how
many files in the new version have not been previously scanned. A file has been
previously scanned if the exact same file has ever been scanned by Vendetta.
FOSSA recommends scanning your codebase on a regular basis to keep scan times
low. Additionally, if you intend on running Vendetta as part of your CI
pipeline, it might be best to do a manual run first on a local machine. That
way, future automated scans of your project will be able to benefit from the
initial caching done in the first scan.

## Invalid certificate errors

You may encounter an error like:

```
error uploading digest batch:
   0: upload digests
   1: error sending request for url (https://app.fossa.com/api/proxy/analysis/api/x/snippets/digests)
   2: client error (Connect)
   3: invalid peer certificate: UnknownIssuer
```

This can occur in environments that use custom TLS certificates. To resolve this,
set the `ALLOW_INVALID_CERTS` environment variable:

```sh
ALLOW_INVALID_CERTS=1 fossa analyze --x-vendetta
```

This instructs the CLI to accept certificates it cannot verify.

---

Source: https://docs.fossa.com/docs/cli/features/vendored-dependencies

# License scanning local dependencies

### License scanning local dependencies

FOSSA offers the ability to license scan your code directly. This is used primarily if a package manager is not yet supported or if you are vendoring dependencies. Using the license scanning feature will allow you to capture the licenses for dependencies that may otherwise be missed from normal fossa analysis that relies on package manager information.

If you would like to license scan your whole project, you may want to use the [first-party license scan](/docs/cli/features/first-party-license-scans) feature.

In order to specify a file path, modify your `fossa-deps.yml` file and add a `vendored-dependencies` section like the following:

```yml
# Example full `fossa-deps.yaml` file.
referenced-dependencies:
- type: gem
  name: rubyXL
  version: "3.4.16"

vendored-dependencies:
- name: Django
  path: vendor/Django-3.4.16.zip # path can be either a file or a folder.
  version: "3.4.16" # revision will be set to the MD5 hash of the filepath if left unspecified.
# You can also provide a description and/or homepage. These values populate metadata fields in reports in the FOSSA web UI.
- name: Winston
  path: vendor/winston.zip
  version: "5.0.0-alpha"
  metadata:
    description: "winston archive"
    homepage: "https://winston-project.com"
```

The path to a vendored dependency can either be a path to an archive or a path to a directory.

If it is a path to an archive, then we recursively unarchive and scan the archive. If it is a directory, then we scan the directory and recursively unarchive and scan any archives contained in the directory.

If the version is not specified, FOSSA CLI calculates the version by generating a hash of the contents of the archive or directory. This is often desired, as it means that the version automatically changes when the contents of the vendored dependency change. It also avoids conflicts across an organization when two different projects contain a vendored dependency with the same name and version, as described in [Vendored Dependency Names and Scope](#vendored-dependency-names-and-scope).

Note: When parsed, YAML considers text that could be a decimal number (such as 1.0 or 2.0) to be a number, not a string. This means that we'd parse the version 1.0 as 1. This probably isn't what you want. To avoid this, surround your version with quotes, as in "1.0".

You can also optionally add metadata fields ("description" and "homepage") to populate these fields in the FOSSA web UI (these fields can be displayed when generating reports).

We also support json-formatted dependencies:

```json
{
  "referenced-dependencies": [
    {
      "type": "gem",
      "name": "iron"
    }, {
      "type": "pypi",
      "name": "Django",
      "version": "2.1.7"
    }
  ],
  "custom-dependencies": [
    {
      "name": "foo",
      "version": "1.2.3",
      "license": "MIT"
    }, {
      "name": "foo-wrapper",
      "version": "1.0.2",
      "license": "MIT or Apache-2.0",
      "metadata": {
        "description": "Provides a help wrapper for foo-related tasks",
        "homepage": "https://foo-project.org/homepage"
      }
    }
  ],
  "vendored-dependencies": [
    {
      "name": "lodash",
      "path": "lodash-4.17.21"
    }, {
      "name": "winston",
      "path": "vendor/winston.tar.gz",
      "version": "5.0.0-alpha",
      "metadata": {
        "description": "winston archive",
        "homepage": "https://winston-project.com/homepage"
      }
    }
  ],
  "remote-dependencies": [
    {
      "name": "foo-url",
      "version": "1.2.3",
      "url": "www.foo.tar.gz",
      "metadata": {
        "description": "foo archive",
        "homepage": "https://foo-url.org/homepage"
      }
    }
  ]
}
```

## Vendored Dependency Names and Scope

The name of a vendored dependency is scoped to an organization.

This means that if two different projects in an organization have the same name and version, they are treated as the same dependency by FOSSA, and the one that was scanned first is reported. As an example:

Project A defines a vendored dependency like this in its fossa-deps.yml, and the contents of that vendored dependency contain an MIT license:

```yaml
vendored-dependencies:
- name: Django
  path: vendor/Django-3.4.16.zip
  version: "3.4.16"
```

Project B has exactly the same contents in fossa-deps.yml, but the contents of Project B's vendored dependency contain an Apache 2.0 license.

If Project A is scanned first, then both Project A and Project B report that their vendored dependency has an MIT license.

If Project B is scanned first, then both Project A and Project B report that their vendored dependency has an Apache 2.0 license.

This can cause unexpected behavior. (Note: FOSSA is working on changing this so that vendored dependencies are scoped to projects rather than organizations.)

The suggested workaround is to not set a version in the vendored dependency entry. When the version is omitted, FOSSA calculates a version based on the contents of the vendored dependency, thus avoiding any conflicts. This also has the added benefit of automatically changing the version when the contents of the vendored dependency change.


## How Vendored Dependencies are scanned

There are two methods of vendored dependency scanning: "CLI license scan" and "archive upload".

The default is typically "CLI license scan", but your organization may have opted to default to "archive upload".

Both methods use the same license scanning technology and will give you the same results. The difference is where the license scan is done.

A "CLI license scan" inspects your code for licensing on the local system within the CLI, and only uploads the matched license data to FOSSA's servers.

"Archive upload" uploads the files at the specified path to a secure S3 bucket. We license scan the uploaded files on our servers. All files that do not contain licenses are then removed after 30 days.

You can change the scan method by using the `--force-vendored-dependency-scan-method` flag when invoking the CLI, or by setting the `vendoredDependencies.scanMethod` field in your `.fossa.yml` file. See the [.fossa.yml documentation](https://github.com/fossas/fossa-cli/blob/master/docs/references/files/fossa-yml.md) for details.

## Performance

The FOSSA service caches the results of a vendored dependency by the combination of its `(name, version)` fields.
Due to this caching setup, it is normal for the first analysis to take some time, especially for larger projects, but future analysis of dependencies with the same information should be fast.

If `version` is not specified, FOSSA computes a version based on the contents specified by `path`; this means that if the contents have not changed then the results are reused.

In the event caching is causing problems, FOSSA can be made to rescan this kind of dependency:
- Run `fossa analyze` with the `--force-vendored-dependency-rescans` flag, or
- Set `vendoredDependencies.forceRescans` to `true` in `.fossa.yml` at the root of the project.

## Path Filtering

> Note: This section does not apply to archive uploads. Path filtering is only available when doing a CLI License Scan. See [here](#how-vendored-dependencies-are-scanned) for more info on the difference between these two methods.

> Note: these path filters also work for and affect [first-party license scans](/docs/cli/features/first-party-license-scans).

Path filtering can be used to omit some files or directories from license scanning. Path filtering is set up in the `.fossa.yml` file. Here is an example:

```yaml
version: 3
vendoredDependencies:
  licenseScanPathFilters:
    only:
      - "**/*.rb"
      - "**/LICENSE"
    exclude:
      - "**/test/**"
      - "**/test/*"
      - "**/spec/**"
      - "**/spec/*"
```

Filters are set in the `vendoredDependencies.licenseScanPathFilters` section of the file. You can provide an `only` object and an `exclude` object. Both of these objects consist of a list of file globs. You can provide both `only` and `exclude` objects or just `only` or just `exclude`.

The `only` object will scan paths that match at least one of the entries in the `only` object. The `exclude` object will exclude paths that match any of the entries in the `exclude` object.

So in the example above, we will license scan files named "LICENSE" and files that have an extension of `.rb`. We will also filter out any files in directories named `test` or `spec`, even if they match the `only` filters.

The `**`, known as a globstar, is a non-standard extension to globs. It matches one or more directories.

> Note: Some implementations of globstar treat it as matching "zero or more directories". Since different implementations differ in their globstar functionality, we have decided to treat globstars as matching "one or more directories". We did this as it is simpler to include the additional glob for the base directory case when desired than to exclude the base directory case when it is not desired.
>
> There is one exception to this. A glob like `**/*.rb` will also include `*.rb` files in the root directory. This was done so that you would only need one line in order to exclude all files with a given extension. If you had `**/*.rb` in the `only` object but wanted to exclude `*.rb` files in the root directory, you would need to add an entry of `*.rb` to the `exclude` object.

The following table shows which files will be matched by a glob for this directory structure.

```
.
├── LICENSE
├── foo.rb
├── src
│   ├── runit.rb
│   ├── runit_external.rb
│   └── subdir
│       └── again.rb
└── test
    ├── LICENSE
    └── runit_test.rb
```

| Glob          | Meaning                                             | Files matched                                                                                   |
| ------------- | --------------------------------------------------- | ----------------------------------------------------------------------------------------------- |
| `src/*.rb`    | All .rb files directly in the root src directory    | `src/runit.rb`, `src/runit_external.rb`                                                         |
| `**/src/*.rb` | All .rb files directly in any directory named `src` | `src/runit.rb`, `src/runit_external.rb`                                                         |
| `**/*.rb`     | All .rb files                                       | `foo.rb`, `src/runit.rb`, `src/runit_external.rb`,  `src/subdir/again.rb`, `test/runit_test.rb` |
| `**/src/**`   | All files under the src directory                   | `src/subdir/again.rb`                                                                           |

- To filter out all files with a given extension, add an entry like `**/*.extension` to the `exclude` object. E.g. `**/*.ts`.

- To filter out all files with a given name, add an entry like `**/filename` to the `exclude` object. E.g `**/LICENSE` or `**/LICENSE.*`.

- To include only files with a given extension, add an entry like `**/*.extension` to the `only` object. If you want to include files with multiple extensions, you can add multiple entries to the `only` object. E.g. `**/*.ts`.

- To include all files with a given name, add an entry like `**/filename` to the `only` object. E.g `**/LICENSE` or `**/LICENSE.*`.

- To exclude all files in subdirectories of a given directory, add that directory followed by `/**` to the exclude object. E.g. `path/to/exclude/**`.

- If you also want to exclude files directly in that directory, add a second entry with the directory followed by `/*`. E.g. `path/to/exclude/*`.

- To scan only files in a subdirectory of a given directory, add that directory followed by `/**` to the exclude object.  E.g. `path/to/scan/**`.

- If you also want to scan all files directly in that directory, add a second entry with the directory followed by `/*`. E.g. `path/to/scan/*`.

### Path filtering and Windows

You must always use `/` as a path separator in your path filters. The CLI will convert these to `\` when you run in a Windows environment.

### Debugging your path filters

If you want to see what files we are scanning with your current `.fossa.yml` file, you can use the `fossa license-scan fossa-deps` command:

```
fossa license-scan fossa-deps
```

That will output the results of the license-scan. If you have `jq` installed, you can filter the output to just show the paths that were scanned:

```
fossa license-scan fossa-deps | jq '.uploadUnits[].LicenseUnits[].Files'
```

This will include all of the files scanned, even those with no licenses found in them.

---

Source: https://docs.fossa.com/docs/cli/walkthroughs

# Walkthroughs

Step-by-step guides for installing the CLI, configuring credentials, and integrating FOSSA into CI and specialized build systems.

---

Source: https://docs.fossa.com/docs/cli/walkthroughs/analysis-target-configuration

# Analyze only a set of targets

FOSSA CLI can be configured to discover and analyze, based on the target type (e.g. gradle, rebar3, etc.) and by its path. This can be useful when multiple targets exist in the directory, but we are only interested in a select few. 

To do so, we will use the following:

- [fossa list-targets](/docs/cli/references/subcommands/list-targets) command
- [.fossa.yml](/docs/cli/references/files/fossa-yml) configuration file

## Example

For an example scenario, presume our source code is structured in the following manner (simplified for brevity):

```bash
.
├── src
│   ├── back-end
│   │   └── pyproject.toml
│   └── front-end
│       ├── v1
│       │   └── package.json
│       └── v2
│           └── package.json
├── test-suite
│   ├── browser
│   │   ├── package.json
│   │   └── yarn.lock
│   └── integration
│       └── build.gradle
└── utils
    ├── helpers
    │   └── requirements.txt
    ├── migration-tests
    │   └── build.gradle
    ├── requirements.txt
    └── scripts
        └── requirements.txt
```

And we are only interested in analyzing:

- Any targets under `src/back-end/` and `src/front-end/v2/` directory
- Any targets under `utils/` directory, 
  - But excluding only setuptools targets found in `utils/scripts` directory. 
  - But excluding any targets under `utils/migration-tests` directory

To identify, target and its path discovered by fossa CLI, we can use: `fossa list-targets` command. 

When command is executed, it would produce a list of target and their path:

```bash
[ INFO] Found project: yarn@test-suite/browser/
[ INFO] Found target: yarn@test-suite/browser/
[ INFO] Found project: setuptools@utils/helpers/
[ INFO] Found target: setuptools@utils/helpers/
[ INFO] Found project: setuptools@utils/scripts/
[ INFO] Found target: setuptools@utils/scripts/
[ INFO] Found project: setuptools@utils/
[ INFO] Found target: setuptools@utils/
[ INFO] Found project: poetry@src/back-end/
[ INFO] Found target: poetry@src/back-end/
[ INFO] Found project: npm@src/front-end/v1/
[ INFO] Found target: npm@src/front-end/v1/
[ INFO] Found project: npm@src/front-end/v2/
[ INFO] Found target: npm@src/front-end/v2/
[ INFO] Found project: gradle@utils/migration-tests/
[ INFO] Found target: gradle@utils/migration-tests/:
[ INFO] Found project: gradle@test-suite/integration/
[ INFO] Found target: gradle@test-suite/integration/:
```

So,

1. Let's select any targets under `src/back-end` and `src/front-end/v2/` directory using [`paths.only`](/docs/cli/references/files/fossa-yml#pathsonly) directive:

```yaml
version: 3

paths:
    only:
        - src/back-end/
        - src/front-end/v2/
```

2. We want to scan for targets in the `utils` directory. Let's add that to the paths to scan for targets.

```yaml
version: 3

paths:
    only:
        - src/back-end/
        - src/front-end/v2/
        - utils/
```

3. We want to exclude any targets in `utils/migration-tests/` directory, to do so, use [`paths.exclude`](/docs/cli/references/files/fossa-yml#pathsexclude) directive. This will ensure cli does not scan `utils/migration-tests/` directory for analysis.

```yaml
version: 3

paths:
    exclude:
        - utils/migration-tests/
    only:
        - src/back-end/
        - src/front-end/v2/
        - utils/

targets:
  exclude:
    - type: setuptools
      path: utils/scripts/
```

4. We want to exclude only `setuptools` targets in `utils/scripts/` directory. Since there may be other type of targets in `utils/scripts/` directory, use [`targets.exclude`](/docs/cli/references/files/fossa-yml#targetsexclude) directive to explicitly ignore analysis of `setuptools` type in `utils/scripts/` directory.

```yaml
version: 3

paths:
    exclude:
        - utils/migration-tests/
    only:
        - src/back-end/
        - src/front-end/v2/
        - utils/

targets:
  exclude:
    - type: setuptools
      path: utils/scripts/
```

Likewise, we can also use [`targets.only`](/docs/cli/references/files/fossa-yml#targetsonly) directive to explicitly indicate which targets we are interested. This will achieve the same behavior.

```yaml
version: 3

targets:
  only:
    - type: npm
      path: src/front-end/v2/
    - type: poetry
      path: src/back-end/
    - type: setuptools
      path: utils/
    - type: setuptools
      path: utils/helpers/
    - type: setuptools
      path: utils/helpers/
```

## Target Filtering for Submodules

For some package managers, you may have submodules or sub-projects within a single project
that you are analyzing and you may want to analyze only specifics sub project in some cases.

Here is an example with gradle:

1) Running `fossa list-targets`
```bash
[ INFO] Found project: gradle@./
[ INFO] Found target: gradle@./::app
[ INFO] Found target: gradle@./::list
[ INFO] Found target: gradle@./::utilities
```

Note that, targets are denoted in following format `type@path:target`. For 
example `gradle@./::utilities`:

Note: gradle attaches leading colons to submodules, so the utilities submodule here is referenced by ":utilities"

```
gradle  @           ./      :         :utilities
------ ---          ---    ---        -----------
Type   Path         Path   Target      Target
       separator           separator
```

2) Now to analyze only `utilities`, use `.fossa.yml` file.

```yaml
version: 3
targets:
  only:
    - type: gradle
      path: ./
      target: ':utilities'
```

3) Running `fossa analyze --output -c .fossa.yml`, will only analyze `utilities` submodule.

---

Source: https://docs.fossa.com/docs/cli/walkthroughs/aosp

# Analyzing the Android Open Source Project

[Android Open Source Project (AOSP)](https://source.android.com/) is used to make custom Android operating system distributions.
This document describes how to analyze AOSP distributions for licenses using FOSSA.
It does not describe how to analyze AOSP distributions for dependencies and security vulnerabilities.

[This FOSSA project shows the result of analyzing unmodified and unbuilt AOSP](https://app.fossa.com/projects/custom%2B1%2Faosp-subdirs-example/refs/branch/master).

## Requirements

In our testing, we have been able to analyze unmodified AOSP sources for licenses in about 2 hours and 30 minutes with 32 CPU cores and 64 GB of memory (`m5a.8xlarge` EC2 instance), with a peak system memory usage of 54 GB.

This is in line with the [hardware requirements to build AOSP suggested by Google](https://source.android.com/docs/setup/build/requirements).

## Analyzing AOSP

Create the following `fossa-deps.yml` file in the AOSP root:

```yml
vendored-dependencies:
- name: aosp-bionic
  path: bionic
  version: master
- name: aosp-cts
  path: cts
  version: master
- name: aosp-developers
  path: developers
  version: master
- name: aosp-device
  path: device
  version: master
- name: aosp-hardware
  path: hardware
  version: master
- name: aosp-libcore
  path: libcore
  version: master
- name: aosp-packages
  path: packages
  version: master
- name: aosp-platform_testing
  path: platform_testing
  version: master
- name: aosp-sdk
  path: sdk
  version: master
- name: aosp-test
  path: test
  version: master
- name: aosp-tools
  path: tools
  version: master
- name: aosp-art
  path: art
  version: master
- name: aosp-bootable
  path: bootable
  version: master
- name: aosp-dalvik
  path: dalvik
  version: master
- name: aosp-development
  path: development
  version: master
- name: aosp-external
  path: external
  version: master
- name: aosp-frameworks
  path: frameworks
  version: master
- name: aosp-kernel
  path: kernel
  version: master
- name: aosp-libnativehelper
  path: libnativehelper
  version: master
- name: aosp-pdk
  path: pdk
  version: master
- name: aosp-prebuilts
  path: prebuilts
  version: master
- name: aosp-system
  path: system
  version: master
- name: aosp-toolchain
  path: toolchain
  version: master
```

Create this `.fossa.yml` configuration file in the same directory:

```yml
version: 3

targets:
  excludeManifestStrategies: true
```

Then, run `fossa analyze` in the same directory.


If you cannot create or modify a `.fossa.yml` configuration file, you can achieve the same result with this command:

```sh
fossa analyze --exclude-manifest-strategies
```

## Explanation

The directories listed in `fossa-deps.yml` were selected from unmodified and unbuilt AOSP.
If you need to analyze a different set of directories, you should modify this file accordingly.

`version` is actually an optional field when defining vendored dependencies in `fossa-deps.yml`.
However, omitting this field causes the FOSSA CLI to compress each vendored directory to calculate a hash to use as a placeholder version.
AOSP directory trees are too transitive for zip files, so we manually define a dummy version to avoid having to compress each subdirectory.

Running `fossa analyze` without any other flags or configuration files causes all [analysis strategies](/docs/project-setup/supported-languages) to be executed, which requires significantly more resources. This is likely to fail or take an excessive amount of time due to the size and number of subprojects discovered in the AOSP source tree. The flag `--exclude-manifest-strategies` is set to avoid the use of such strategies and to only look at the dependencies in `fossa-deps.yml`.

---

Source: https://docs.fossa.com/docs/cli/walkthroughs/buildroot

# Scanning Buildroot Projects

This guide explains how to integrate FOSSA into a Buildroot environment for license and security compliance scanning. By leveraging Buildroot's `make show-info` feature, you extract package dependency information and generate a [`fossa-deps`](/docs/cli/references/files/fossa-deps) file that FOSSA can analyze.

{% callout type="info" %}
- A working **Buildroot** environment.
- The **FOSSA CLI** installed. See [Installing the FOSSA CLI](/docs/cli/walkthroughs/installing-fossa-cli).
- **Python 3** (to run the conversion script).
- Basic familiarity with running Buildroot commands.
{% /callout %}

{% steps %}
{% step title="Generate package information from Buildroot" %}
From your Buildroot project directory, export package metadata to JSON:

```bash
cd /path/to/your/buildroot-project
make show-info > buildroot_deps.json
```

This produces `buildroot_deps.json` containing package names, versions, some licenses, and dependencies.
{% /step %}

{% step title="Convert Buildroot dependencies to FOSSA format" %}
FOSSA can enhance the information extracted from Buildroot by incorporating additional insights. Save the following script as `generate_fossa_deps.py` in your Buildroot directory. It reads the JSON and writes a `fossa-deps.yml` with [referenced and custom dependencies](/docs/cli/features/manual-dependencies):

```python
#!/usr/bin/env python3

import json
import argparse
import yaml

def parse_arguments():
    parser = argparse.ArgumentParser(description='Generate fossa-deps.yml from Buildroot package info.')
    parser.add_argument('input_file', type=str, help='Path to the JSON file containing package information.')
    return parser.parse_args()

def load_package_info(file_path):
    with open(file_path, 'r') as file:
        return json.load(file)

def map_to_fossa_type(package_name):
    # Define mapping rules from Buildroot packages to FOSSA dependency types
    if package_name.startswith('python-'):
        return 'pypi'
    elif package_name.startswith('ruby-'):
        return 'gem'
    else:
        return 'custom'

def transform_package_name(package_name):
    # Remove 'python-' if the package name starts with it
    if package_name.startswith('python-'):
        return package_name.replace('python-', '', 1)
    return package_name

def generate_fossa_deps(packages):
    referenced_deps = []
    custom_deps = []

    for pkg_name, pkg_info in packages.items():
        transformed_name = transform_package_name(pkg_name)  # Apply name transformation
        fossa_type = map_to_fossa_type(pkg_name)

        # Get version and ensure it is not empty or blank
        version = pkg_info.get('version', None)
        if not version or str(version).strip() == "":
            version = '1.0'  # Set default version if empty

        dep_entry = {
            'name': transformed_name,  # Use transformed package name
            'version': version
        }
        if fossa_type == 'custom':
            dep_entry['license'] = pkg_info.get('licenses', 'unknown')
            custom_deps.append(dep_entry)
        else:
            dep_entry['type'] = fossa_type
            referenced_deps.append(dep_entry)

    fossa_deps = {}
    if referenced_deps:
        fossa_deps['referenced-dependencies'] = referenced_deps
    if custom_deps:
        fossa_deps['custom-dependencies'] = custom_deps

    return fossa_deps

def main():
    args = parse_arguments()
    packages = load_package_info(args.input_file)
    fossa_deps = generate_fossa_deps(packages)

    with open('fossa-deps.yml', 'w') as f:
        yaml.dump(fossa_deps, f, default_flow_style=False)

    print('fossa-deps.yml has been generated.')

if __name__ == '__main__':
    main()
```
{% /step %}

{% step title="Run the script to generate fossa-deps.yml" %}
Make the script executable and run it against the generated JSON:

```bash
chmod +x generate_fossa_deps.py
./generate_fossa_deps.py buildroot_deps.json
```

This writes a `fossa-deps.yml` file in the current directory.
{% /step %}

{% step title="Run the FOSSA analysis" %}
With `fossa-deps.yml` in place, analyze your Buildroot dependencies:

```bash
fossa analyze
```

FOSSA scans the dependencies listed in `fossa-deps.yml` for license compliance and security vulnerabilities.
{% /step %}

{% step title="View the results" %}
Open the [FOSSA dashboard](https://app.fossa.com/), review license compliance and security issues, and address any flagged items.
{% /step %}
{% /steps %}

## Troubleshooting

| Issue | Solution |
| :-- | :-- |
| `make show-info` fails | Ensure Buildroot is properly set up and built before running the command. |
| `fossa analyze` does not detect dependencies | Check that `fossa-deps.yml` is correctly formatted by inspecting it manually. |
| Missing license information | Buildroot packages may not always specify a license. Add it manually if known. |

---

Source: https://docs.fossa.com/docs/cli/walkthroughs/conan

# Custom Integration with Conan Package Manager

Conan is a dependency and package manager for C and C++ languages. It is free and open-source, works on all
platforms (Windows, Linux, OSX, FreeBSD, Solaris, etc.), and can be used to develop for all targets, including
embedded, mobile (iOS, Android), and bare metal. It also integrates with all build systems like CMake,
Visual Studio (MSBuild), Makefiles, etc., including proprietary ones.

## Prerequisite

- Conan v2.0.0 or greater (you can check the version by running: `conan -v`)
- Python v3 (so you can run the script)

## Integration

This integration uses the `conan graph info` command to retrieve the dependency graph and source code for all dependencies. From this data, it generates [fossa-deps](/docs/cli/references/files/fossa-deps) file with
[vendored-dependencies](/docs/cli/features/vendored-dependencies) and [custom-dependencies](/docs/cli/features/manual-dependencies).

To use this integration,
1. Download [make_fossa_deps_conan.py](https://raw.githubusercontent.com/fossas/fossa-cli/master/docs/walkthroughs/make_fossa_deps_conan.py) python script, and place it in the same directory as `conanfile.txt` or `conanfile.py.`
2. Build your project (ensure it compiles)
3. Run `python make_fossa_deps_conan.py` (this will generate `fossa-deps.yaml` in the same directory)
4. Run `fossa analyze && fossa test`

### Analysis

In this approach, `make_fossa_deps_conan.py` does the followings:

1. Retrieve the project's dependency graph via the `conan graph info` command
2. Uses `-c tools.build:download_source=True` option to ensure Conan always [retrieves source code](https://docs.conan.io/2.0/reference/conanfile/methods/source.html#forced-retrieval-of-sources)
3. For each requirement with non `build` context and source code directory, it builds a vendor-dependency entry in the `fossa-deps.yaml` file
4. For each requirement with non `build` context and empty source code directory, it builds a custom-dependency entry in the `fossa-deps.yaml` file

### Limitations

This integration method uses [vendored-dependencies](/docs/cli/features/vendored-dependencies) and [custom-dependencies](/docs/cli/features/manual-dependencies)
functionalities, and as such, it does not provide the following,

- Security functionalities (FOSSA will not be able to identify vulnerabilities, only licensing and copyright issues)
- Author information (in dependency view)

This integration example uses the best alternative mode of analysis for each dependency. It tries to
locate the source code for each dependency, and if it fails to locate the source code, it will create this dependency
as [custom-dependency](/docs/cli/features/manual-dependencies) entry in the [fossa-deps](/docs/cli/references/files/fossa-deps) file.
In this case, it will use a declared license for this dependency.

If the script locates the source code, it will create [vendor-dependency](/docs/cli/features/vendored-dependencies) entry in
the [fossa-deps](/docs/cli/references/files/fossa-deps) file.

### Example

```bash
# install Conan and some prerequisites
apt-get -y install python3 pip git wget
pip3 install conan
wget https://raw.githubusercontent.com/fossas/fossa-cli/master/install-latest.sh
bash install-latest.sh

# check the Conan version
conan --version

# retrieve example projects
git clone https://github.com/conan-io/examples2.git
cd /examples2/tutorial/consuming_packages/simple_cmake_project

# build
conan profile detect --force
conan install . --output-folder=build --build=missing

# download make_fossa_deps_conan.py
wget https://raw.githubusercontent.com/fossas/fossa-cli/master/docs/walkthroughs/make_fossa_deps_conan.py

# Set your API key. Get this from the FOSSA web application.
export FOSSA_API_KEY=XXXX

# Perform analysis
python3 make_fossa_deps_conan.py
fossa analyze

# Perform test
fossa test
```

## F.A.Q

#### 1. Why doesn't FOSSA offer native Conan package manager analysis?

FOSSA is actively working to develop native Conan support. We want to build a functionality that provides accurate and repeatable analysis for all versions of the Conan package manager. This integration
script is supplied as a potential option if you want to start using FOSSA for Conan immediately.

#### 2. Why do I need Conan `v2` or greater?

This integration example uses the `conan graph info` command with `--format json` and
`-c tools.build:download_source=True` option, which are only available in Conan v2 (`v2.0.0+`).

#### 3. I want to use a custom profile or provide additional options.

You can provide any additional [`conan graph info`](https://docs.conan.io/2.0/reference/commands/graph/info.html) options (except `--format` or `-f`)

To do so, provide options to the Python script. For example,

```bash
>> python3 make_fossa_deps_conan.py -s compiler=gcc
```

#### 4. How can I get help with this integration?

You can file a support ticket with [FOSSA helpdesk](https://support.fossa.com).

#### 5. How do I always use a declared license?

This can be achieved by modifying [make_fossa_deps_conan.py](https://raw.githubusercontent.com/fossas/fossa-cli/master/docs/walkthroughs/make_fossa_deps_conan.py). In the script,
you can choose to always create [custom-dependency](/docs/cli/features/manual-dependencies) entry, this will ensure
that declared license is always used.

### References

- [Conan Package Manager](https://docs.conan.io)
- [Conan graph command](https://docs.conan.io/2.0/reference/commands/graph/info.html)

---

Source: https://docs.fossa.com/docs/cli/walkthroughs/container-scanning-generic-ci

# Integrating Container Scanning in CI

- [Integrating container scanning in CI](#integrating-container-scanning-in-ci)
  - [Analyze](#analyze)
  - [Test](#test)
  - [Example](#example)

**Scenario:**

As a development team we want to analyze container image for vulnerability and compliance issues as part of the CI process.

## Analyze

Use the `fossa container analyze <IMAGE>` command.

With Docker:

```bash
docker build . -t <IMAGE>
fossa container analyze <IMAGE>

# Alternately, export the image to an archive and analyze that for maximal performance. 
#
# >> docker save -o image.tar <IMAGE>
# >> fossa container analyze image.tar
```

With Podman:

```bash
podman build . -t <IMAGE>
fossa container analyze <IMAGE>

# Alternately, export the image to an archive and analyze that for maximal performance. 
#
# >> podman save <IMAGE> --format docker-archive -o image.tar 
# >> fossa container analyze image.tar
```

With Buildah:

```bash
buildah bud --format=docker -f Dockerfile -t <IMAGE> .
buildah push <IMAGE> docker-archive:image.tar

fossa container analyze image.tar
```

## Test

Use the `fossa container test <IMAGE>` command to test a previously analyzed image.
This command exits with a non-zero exit code if issues are discovered.

```bash
fossa container test <IMAGE>
```

## Example

**Prerequisite**

Dockerfile:
```Dockerfile
FROM alpine:latest

RUN apk add tree python3 py3-pip
COPY ./app ./app

RUN pip install -r ./app/reqs.txt
```

`app/reqs.txt`:
```text
# app/reqs.txt
flask
```

**With Docker**

```bash
VERSION="1.0.0" # or git commit hash: VERSION=$(git log -1 --pretty=%h)
REPO="core-app:"
TAG="$REPO$VERSION"
BUILD_TIMESTAMP=$( date '+%F_%H:%M:%S' )

# Build
docker build -t "$TAG" -build-arg VERSION="$VERSION" --build-arg BUILD_TIMESTAMP="$BUILD_TIMESTAMP" . 

# Analyze and test image for security and compliance issues
fossa container analyze "$TAG"
fossa container test "$TAG"

# Push image to registry
docker push "$TAG"
```

**With Podman**

```bash
VERSION="1.0.0" # or git commit hash: VERSION=$(git log -1 --pretty=%h)
REPO="core-app:"
TAG="$REPO$VERSION"
BUILD_TIMESTAMP=$( date '+%F_%H:%M:%S' )

# Build
podman build . -t "$TAG" --build-arg VERSION="$VERSION" --build-arg BUILD_TIMESTAMP="$BUILD_TIMESTAMP" . 

# Analyze and test image for security and compliance issues
fossa container analyze "$TAG"
fossa container test "$TAG"

# Push image to registry
podman push "$TAG"
```

**With Buildah**

```bash
VERSION="1.0.0" # or git commit hash: VERSION=$(git log -1 --pretty=%h)
REPO="core-app:"
TAG="$REPO$VERSION"
BUILD_TIMESTAMP=$( date '+%F_%H:%M:%S' )

# Build
buildah bud --format=docker -f Dockerfile --build-arg VERSION="$VERSION" --build-arg BUILD_TIMESTAMP="$BUILD_TIMESTAMP" -t "$TAG" .
buildah push "$TAG" docker-archive:image.tar

# Analyze and test image for security and compliance issues
fossa container analyze image.tar
fossa container test image.tar
rm image.tar
```

---

Source: https://docs.fossa.com/docs/cli/walkthroughs/custom-integrating-with-bower-example

# Custom Integration using fossa-deps

With `fossa-deps.{yml, json, yaml}` file, FOSSA CLI can be integrated to support any package manager or custom and non-standard management solution, that is yet to be supported natively by FOSSA CLI. With the fossa-deps file, we can:

- [Include manual dependencies](/docs/cli/features/manual-dependencies)
- [Include vendored dependencies](/docs/cli/features/vendored-dependencies)

## Example with Bower

For an example, we will look at [Bower](https://bower.io/).

We can usually identify a list of dependencies from our custom tool by looking at configuration files or executing a command. Bower provides both of these options, we can inspect (1) `bower.json` or (2) parse the output from the `bower list` command.

From an example `bower.json` file, lists direct dependencies:

```json
{
  "name": "example-project",
  "authors": [
    "user <user@example.com>"
  ],
  "description": "Example project",
  "main": "main.js",
  "license": "MIT",
  "homepage": "",
  "ignore": [
    "**/.*",
    "node_modules",
    "bower_components",
    "test",
    "tests"
  ],
  "dependencies": {
    "font-awesome": "^5.0.0",
    "jquery": "^3.6.0"
  }
}
```

We can execute `bower list` command to list all of the resolved bower dependencies:

```
example-project /Users/example-user/path
├── font-awesome#5.15.4
└── jquery#3.6.0
```

We have two dependencies (1) jquery and (2) font-awesome.

From [manual dependencies](/docs/cli/features/manual-dependencies) documentation, we know that `bower` type dependencies are supported type as reference dependency.

We can include all listed dependencies in fossa-deps.json.

```json
{
  "referenced-dependencies": [
    {
      "type": "bower",
      "name": "jquery",
      "version": "3.6.0"
    },
    {
      "type": "bower",
      "name": "font-awesome",
      "version": "5.15.4"
    }
  ]
}
```

To programmatically add these dependencies, you can write a script in your language of choice to translate the dependency graph produced by bower to a fossa-deps file. Provided below is an example python script, which parses a dependency graph and produces a fossa-deps file.

[Here](https://github.com/fossas/fossa-cli/blob/master/experimental-scripts/bower.py) is an example python script that parses bower list command, and prints fossa-deps file.

## Limitation

Please note that with the fossa-deps file, we can report dependencies, but we cannot:

- differentiate between direct and transitive dependencies
- report edge information between dependencies

---

Source: https://docs.fossa.com/docs/cli/walkthroughs/installing-fossa-cli

# Installing Fossa CLI

## Using Installation script

FOSSA CLI provides an install script that downloads the latest release from GitHub Releases for your computer's architecture. You can see the source code and flags at [`install-latest.sh`](https://github.com/fossas/fossa-cli/blob/master/install-latest.sh) for Mac and Linux or [`install-latest.ps1`](https://github.com/fossas/fossa-cli/blob/master/install-latest.ps1) for Windows.

**NOTE:** You may need to add the downloaded executable to your `$PATH`. The installer script will output the installed path of the executable. You can also use `-b` to pick the installation directory when using `install-latest.sh` (see [the `install-latest.sh` source code](https://github.com/fossas/fossa-cli/blob/master/install-latest.sh) for details).

### Linux or macOS

```bash
# Install latest version
curl -H 'Cache-Control: no-cache' https://raw.githubusercontent.com/fossas/fossa-cli/master/install-latest.sh | bash

# Installs cli version v3.1.1 instead of latest
curl -H 'Cache-Control: no-cache' https://raw.githubusercontent.com/fossas/fossa-cli/master/install-latest.sh | bash -s -- v3.1.1

# Installs cli version v3.1.1 instead of latest at current working directory
curl -H 'Cache-Control: no-cache' https://raw.githubusercontent.com/fossas/fossa-cli/master/install-latest.sh | bash -s -- -b . v3.1.1

# Installs cli version v3.1.1 instead of latest at current working directory in debug mode
curl -H 'Cache-Control: no-cache' https://raw.githubusercontent.com/fossas/fossa-cli/master/install-latest.sh | bash -s -- -b . -d v3.1.1
```

### Windows

```powershell
Set-ExecutionPolicy Bypass -Scope Process -Force; iex  ((New-Object System.Net.WebClient).DownloadString('https://raw.githubusercontent.com/fossas/fossa-cli/master/install-latest.ps1'))
```

Alternatively, install using [Scoop](https://scoop.sh/):

```
scoop install fossa
```

Likewise with `scoop` you can install a specific version of CLI:

```powershell
scoop install fossa@3.2.9
```

## Installing CLI 1.x using Installation script

You can install FOSSA CLI 1.x with installation script for macOS or 64-bit Linux using:

```bash
curl -H 'Cache-Control: no-cache' https://raw.githubusercontent.com/fossas/fossa-cli/master/install-v1.sh | bash
```

And for windows:

```powershell
Set-ExecutionPolicy Bypass -Scope Process -Force; iex  ((New-Object System.Net.WebClient).DownloadString('https://raw.githubusercontent.com/fossas/fossa-cli/master/install-v1.ps1'))
```

> As of now, there is no development work being done on CLI 1.x. Likewise, support for CLI 1.x is deprecated. If there is a defect with CLI 1.x, we will not make patches to CLI 1.x anymore but instead will ask you to migrate to 3.x, and make necessary patches to CLI 3.x. It is recommended that you migrate to CLI 3.x. Please read the [migration guide](/docs/cli/differences-from-v1) for more details.

## Installing manually with Github Releases

1) To download FOSSA CLI manually using GITHUB releases, identify release of interest by going to [releases](https://github.com/fossas/fossa-cli/releases/)

Example: https://github.com/fossas/fossa-cli/releases/tag/v3.2.17

2) Identify release artifact for your system's OS and ARCH by looking at release [assets](https://github.com/fossas/fossa-cli/releases/tag/v3.2.17)

Example: https://github.com/fossas/fossa-cli/releases/download/v3.2.17/fossa_3.2.17_darwin_amd64.zip

3) Identify release checksum to verify the release artifact

Example: https://github.com/fossas/fossa-cli/releases/download/v3.2.17/fossa_3.2.17_darwin_amd64.zip.sha256

4) Download release artifact, and release artifact checksum

Example:
```bash
wget https://github.com/fossas/fossa-cli/releases/download/v3.2.17/fossa_3.2.17_darwin_amd64.zip
wget https://github.com/fossas/fossa-cli/releases/download/v3.2.17/fossa_3.2.17_darwin_amd64.zip.sha256
```

5) Confirm sanity of the release artifact by comparing sha256 checksum

```bash
sha256sum --binary fossa_3.2.17_darwin_amd64.zip
```

```bash
cat fossa_3.2.17_darwin_amd64.zip.sha256
```

You can also compare output using diff:
```bash
diff <(sha256sum --binary fossa_3.2.17_darwin_amd64.zip) <(cat fossa_3.2.17_darwin_amd64.zip.sha256)
```

6) Extract and copy the binary to `$PATH`

```bash
unzip fossa_3.2.17_darwin_amd64.zip
mv fossa /usr/local/bin/fossa
```

7) Confirm the fossa version using `--version`

```bash
fossa --version
```

---

Source: https://docs.fossa.com/docs/cli/walkthroughs/integrating

# Quick Start

## Quick Start

FOSSA CLI (occasionally referred to as Spectrometer) is a tool that requires minimal configuration: usually, only a FOSSA API key is required.

If you do not have an API key, please check the [FOSSA documentation](https://docs.fossa.com/docs/api-reference) for instructions on generating an API key.

### Configure your API key

```sh
export FOSSA_API_KEY=abcdef123456
```

### Run Analysis

This runs dependency analysis in the current directory, uploading results to FOSSA

```sh
fossa analyze
```

### Check for FOSSA scan results

```sh
fossa test
```

This may take some time to return while FOSSA downloads and scans each dependency for display in our web UI.

For additional commands and command flags, use `--help`:

```sh
fossa --help
fossa analyze --help
# etc
```

---

Source: https://docs.fossa.com/docs/cli/walkthroughs/proxy-configuration

# Using FOSSA CLI with HTTP Proxies

FOSSA CLI supports HTTP proxies through standard environment variables.
This is useful in corporate environments where outbound connections must go through a proxy server.

## Configuring Proxy Environment Variables

FOSSA CLI uses the standard proxy environment variables recognized by most command-line tools:

```sh
# For HTTP connections
export http_proxy=http://proxy.example.com:8080

# For HTTPS connections (most common)
export https_proxy=http://proxy.example.com:8080

# Hosts to exclude from proxy (comma-separated)
export no_proxy=localhost,127.0.0.1,internal.example.com
```

For proxy servers that require authentication:

```sh
export https_proxy=http://username:password@proxy.example.com:8080
```

## Verifying Proxy Configuration Locally

Usually, you can test proxy configuration by simply configuring the proxy with the settings required by your organization;
if it works then you're done. But if you need to verify it locally you can do so with any standard proxy server.

Below is a walkthrough on how to verify using the `squid` proxy server:

1. Install Squid:
   - Ubuntu/Debian: `sudo apt-get install squid`
   - RHEL/CentOS: `sudo yum install squid`
   - macOS: `brew install squid`

2. Create a minimal configuration at `/tmp/squid.conf`:

```
http_port 3128
http_access allow all
```

3. Run Squid:

> [!NOTE]
> If you don't know where your installation of `squid` stores its access log,
> run it with `-d 3` to have `squid` log its access log location.

```sh
squid -f /tmp/squid.conf -N
```

4. Run `fossa`:

```sh
fossa analyze
```

5. Check the access log:

> [!NOTE]
> This example demonstrates the standard location for `homebrew`-installed `squid`;
> your location may be different.

```sh
; cat /opt/homebrew/var/logs/access.log
1747163889.439    486 ::1 TCP_TUNNEL/200 5934 CONNECT app.fossa.com:443 - HIER_DIRECT/35.71.190.183 -
1747163889.695    254 ::1 TCP_TUNNEL/200 5505 CONNECT app.fossa.com:443 - HIER_DIRECT/35.71.190.183 -
1747163889.887    231 ::1 TCP_TUNNEL/200 5505 CONNECT app.fossa.com:443 - HIER_DIRECT/35.71.190.183 -
1747163892.236   1232 ::1 TCP_TUNNEL/200 18550 CONNECT app.fossa.com:443 - HIER_DIRECT/35.71.190.183 -
1747163892.495   1210 ::1 TCP_TUNNEL/200 6597 CONNECT s3.us-east-1.amazonaws.com:443 - HIER_DIRECT/54.231.201.248 -
1747163892.496   1616 ::1 TCP_TUNNEL/200 5762 CONNECT app.fossa.com:443 - HIER_DIRECT/35.71.190.183 -
1747163892.591    400 ::1 TCP_TUNNEL/200 4889 CONNECT app.fossa.com:443 - HIER_DIRECT/35.71.190.183 -
1747163898.487    670 ::1 TCP_TUNNEL/200 5934 CONNECT app.fossa.com:443 - HIER_DIRECT/35.71.190.183 -
1747163898.651    301 ::1 TCP_TUNNEL/200 5505 CONNECT app.fossa.com:443 - HIER_DIRECT/35.71.190.183 -
1747163898.806    208 ::1 TCP_TUNNEL/200 5505 CONNECT app.fossa.com:443 - HIER_DIRECT/35.71.190.183 -
1747163899.158    217 ::1 TCP_TUNNEL/200 5762 CONNECT app.fossa.com:443 - HIER_DIRECT/35.71.190.183 -
1747163900.966   1770 ::1 TCP_TUNNEL/200 18386 CONNECT app.fossa.com:443 - HIER_DIRECT/35.71.190.183 -
1747163901.012   1462 ::1 TCP_TUNNEL/200 6597 CONNECT s3.us-east-1.amazonaws.com:443 - HIER_DIRECT/54.231.201.248 -
1747164273.479    214 ::1 TCP_TUNNEL/200 5934 CONNECT app.fossa.com:443 - HIER_DIRECT/52.223.16.182 -
1747164273.588    134 ::1 TCP_TUNNEL/200 5505 CONNECT app.fossa.com:443 - HIER_DIRECT/52.223.16.182 -
1747164273.812    258 ::1 TCP_TUNNEL/200 5505 CONNECT app.fossa.com:443 - HIER_DIRECT/52.223.16.182 -
1747164273.969    104 ::1 TCP_TUNNEL/200 5762 CONNECT app.fossa.com:443 - HIER_DIRECT/52.223.16.182 -
1747164276.816    419 ::1 TCP_TUNNEL/200 4889 CONNECT app.fossa.com:443 - HIER_DIRECT/52.223.16.182 -
1747164276.816   2872 ::1 TCP_TUNNEL/200 18341 CONNECT app.fossa.com:443 - HIER_DIRECT/52.223.16.182 -
1747164276.816   2652 ::1 TCP_TUNNEL/200 6597 CONNECT s3.us-east-1.amazonaws.com:443 - HIER_DIRECT/52.217.231.104 -
```

## Common Proxy Issues

### Invalid Proxy URL Format

Ensure your proxy URLs have the correct format:

- Valid: `http://proxy.example.com:8080`
- Valid: `http://username:password@proxy.example.com:8080`
- Invalid: `proxy.example.com:8080` (missing protocol)

### TLS Certificate Issues

If your proxy server performs TLS inspection, you may need to configure FOSSA CLI to trust your organization's certificate authority.
See the [SSL/TLS Configuration](/docs/cli/walkthroughs/ssl-cert) walkthrough.

### Network Connectivity

If you encounter connection timeouts, ensure that your proxy server allows connections to your instance of FOSSA
and the object store that your instance of FOSSA uses.

If you use the instance of FOSSA at `https://app.fossa.com`, those settings are:
- `app.fossa.com`
- `analysis.fossa.com`
- `s3.us-east-1.amazonaws.com`

Other instances, especially on-premise instances, may have different settings-
please work with your IT department and/or FOSSA support in these cases to determine the correct values.

### Corporate Proxy Challenges

Some corporate proxies may present additional challenges:

1. Content filtering - Some proxies inspect and filter certain types of content
2. Authentication - Proxies may require periodic re-authentication
3. Bandwidth limitations - Upload of large scan results may be throttled

If you encounter persistent issues with your proxy, contact your IT department for assistance.

---

Source: https://docs.fossa.com/docs/cli/walkthroughs/ssl-cert

# Custom SSL Certificate with fossa-cli

## Custom SSL Certificate with `fossa-cli`

`fossa-cli` uses the path provided in the following environment variable to infer root certificate store:

1) `SSL_CERT_FILE`
2) `SSL_CERT_DIR`
3) `SYSTEM_CERTIFICATE_PATH` (only for linux)

If none of these environment variables are provided, fossa-cli uses a system store to retrieve signed certificates.

#### Linux

`fossa-cli` looks for certificate store in the following paths:

- `/etc/ssl/certs/`  
- `/system/etc/security/cacerts/`
- `/usr/local/share/certs/`
- `/etc/ssl/cert.pem`

#### macOS

`fossa-cli` creates a certificate store by finding all signed certificates.  

We use following command to retrieve all signed certificates: `security find-certificate -pa /System/Library/Keychains/SystemRootCertificates.keychain /Library/Keychains/System.keychain`


#### Windows

`fossa-cli` retrieves certificates store by performing,

- [CertOpenSystemStoreW](https://docs.microsoft.com/en-us/windows/win32/api/wincrypt/nf-wincrypt-certopensystemstorew)

From which, [CertEnumCertificatesInStore](https://docs.microsoft.com/en-us/windows/win32/api/wincrypt/nf-wincrypt-certenumcertificatesinstore) perform until exhaustion to retrieve all signed certificates. 

## Recommendations

_We recommended that you leverage the operating system's certificate store instead of using environment variables._

## Examples

In Windows:
```
$Env:SSL_CERT_FILE = "\path\to\rootCa"
fossa analyze
```

In Linux:
```
SSL_CERT_FILE=path/to/rootCa fossa analyze
```

In Osx:
```
SSL_CERT_FILE=path/to/rootCa fossa analyze
```

---

Source: https://docs.fossa.com/docs/cli/walkthroughs/what-data-gets-uploaded

# What Data Gets Uploaded to FOSSA's Servers

During analysis, the FOSSA CLI will upload a few different types of data to FOSSA's servers. These types are:

* The list of dependencies obtained when running `fossa analyze`
* Vendored dependency data
* Telemetry data

The following sections describe what these different types of data look like. A final section describes and provides a link to a tool called `echotraffic` that allows you to see exactly what data the FOSSA CLI is sending to FOSSA's servers.

## Dependency list

When you run `fossa analyze`, the CLI finds the dependencies used by your project and then uploads the list of dependencies to FOSSA's servers for analysis.

You can see what the CLI will upload for your specific project by running `fossa analyze --output`.

As an example, here are the results from doing the following:

```
git clone https://github.com/bohnman/squiggly
cd squiggly
fossa analyze --output
```

The output is a bit large to include in this document. You can [view the results here](/cli/assets/fossa-analyze-output.json).

## Vendored Dependencies

If you have a `fossa-deps.yml` file that contains a `vendored-dependencies` section ([vendored dependencies documentation](/docs/cli/features/vendored-dependencies)), then the CLI will scan and upload data for the vendored dependencies listed.

There are two methods of vendored dependency scans: "CLI license scan" and "Archive upload". Archive Upload is older functionality and is only used if your organization has specifically requested it. In almost all cases you will be using CLI license scans.

A "CLI license scan" inspects vendored dependencies for licensing on the local system within the CLI, and only uploads the matched license data to FOSSA's servers.

"Archive upload" uploads vendored dependencies to a secure S3 bucket. FOSSA then license scans the uploaded files on FOSSA's servers. All files that do not contain licenses are then removed after 30 days.

You can figure out whether the scan was a CLILicenseScan or an ArchiveUpload by running `fossa analyze` with the `--debug` flag: `fossa analyze --debug`.

If it was a CLILicenseScan, then you will see this in the logs:

```
"License Scanning '<vendored dependency name>' at '<vendored dependency path>'.
```

If it was an ArchiveUpload, then you will see this in the logs:

```
"Compressing '<vendored dependency name>' at '<vendored dependency path>'.
```

You can see exactly what data the CLI is uploading for a CLI license scan for your code by running the following command:

```
fossa license-scan fossa-deps
```

Here is a sample output of the data that gets uploaded to the server for a CLI license scan. The license text has been truncated for readability, but other than that this is exactly what would be uploaded. You can also [download the full JSON](/cli/assets/license-scan-data.json).

```json
{
  "uploadUnits": [
    {
      "LicenseUnits": [
        {
          "Data": [
            {
              "Copyright": null,
              "Copyrights": null,
              "ThemisVersion": "df717b7762a7441a82713f03ad626b65734060ae",
              "match_data": [
                {
                  "end_line": 201,
                  "index": 0,
                  "length": 11322,
                  "location": 33,
                  "match_string": "Apache License\n                           Version 2.0, January 2004\n                        http://www.apache.org/licenses/\n\n   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION ...  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n   See the License for the specific language governing permissions and\n   limitations under the License.",
                  "start_line": 1
                }
              ],
              "path": "vendored/apache-2.0.LICENSE"
            }
          ],
          "Dir": "",
          "Files": [
            "vendored/apache-2.0.LICENSE"
          ],
          "Info": {
            "Description": ""
          },
          "Name": "apache-2.0",
          "Type": "LicenseUnit"
        },
        {
          "Data": [
            {
              "Copyright": null,
              "Copyrights": null,
              "ThemisVersion": "df717b7762a7441a82713f03ad626b65734060ae",
              "match_data": [
                {
                  "end_line": 18,
                  "index": 0,
                  "length": 1021,
                  "location": 0,
                  "match_string": "Permission is hereby granted, free of charge, to any person obtaining\na copy of this software ...\nSOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.",
                  "start_line": 1
                }
              ],
              "path": "vendored/mit.LICENSE"
            }
          ],
          "Dir": "",
          "Files": [
            "vendored/mit.LICENSE"
          ],
          "Info": {
            "Description": ""
          },
          "Name": "mit",
          "Type": "LicenseUnit"
        }
      ],
      "Name": "vendored",
      "Type": "cli-license-scanned"
    }
  ]
}
```

## Telemetry

The FOSSA CLI collects anonymous feature usage information, observed errors and warnings, and performance diagnostic information to help improve the experience for everyone.

You can get more information about what telemetry data gets uploaded and how to opt-out of telemetry uploads [here](/docs/cli/telemetry).

## Inspecting exactly what gets uploaded with `echotraffic`

FOSSA provides an open-source tool called [`echotraffic`](https://github.com/fossas/echotraffic) that you can use to see exactly what data FOSSA is sending to FOSSA's servers.

Follow the directions in `echotraffic`'s README to get started.

---

Source: https://docs.fossa.com/docs/cli/walkthroughs/yocto

# Scanning Yocto Projects

This guide explains how to integrate FOSSA into a [Yocto](https://www.yoctoproject.org/)-based build for license and security compliance scanning. FOSSA supports Yocto builds via [`meta-fossa`](https://github.com/fossas/meta-fossa), a Yocto layer that analyzes and reports the runtime packages of a Yocto image build to FOSSA.

{% callout type="info" %}
- A working **Yocto** build environment (or [Poky](https://git.yoctoproject.org/poky)).
- A **FOSSA API key**, generate one at [Account Settings → Integrations → API Tokens](https://app.fossa.com/account/settings/integrations/api_tokens).
- Basic familiarity with running `bitbake` and `bitbake-layers` commands.
{% /callout %}

## Supported Yocto versions

The `meta-fossa` layer is published per Yocto release as a dedicated branch. Check out the branch that matches your Yocto version:

| Yocto Version | Branch |
| :--- | :--- |
| `dunfell` | [dunfell](https://github.com/fossas/meta-fossa/tree/dunfell) |
| `honister` | [honister](https://github.com/fossas/meta-fossa/tree/honister) |
| `kirkstone` | [kirkstone](https://github.com/fossas/meta-fossa/tree/kirkstone) |
| `mickledore` | [mickledore](https://github.com/fossas/meta-fossa/tree/mickledore) |

## Quickstart

{% steps %}
{% step title="Check out the FOSSA layer" %}
Clone `meta-fossa`, replacing `dunfell` with your Yocto version:

```shell
git clone https://github.com/fossas/meta-fossa.git -b dunfell
```
{% /step %}

{% step title="Check out Yocto" %}
If you do not already have a Yocto build environment, clone Poky on the matching branch:

```shell
git clone git://git.yoctoproject.org/poky.git -b dunfell
```
{% /step %}

{% step title="Activate the Yocto build environment" %}
Source the build environment script:

```shell
cd poky && source oe-init-build-env
```
{% /step %}

{% step title="Add and inherit the meta-fossa layer" %}
Register the layer and configure your build to inherit it:

```shell
# Add the meta-fossa layer
bitbake-layers add-layer ../../meta-fossa/
echo 'BBLAYERS += "${TOPDIR}/../../meta-fossa"' >> conf/local.conf

# Inherit the FOSSA layer
echo 'INHERIT += "fossa"' >> conf/local.conf
```
{% /step %}

{% step title="Set your FOSSA API key" %}
Add your API key to the build configuration:

```shell
echo 'FOSSA_API_KEY = "<VALID-FOSSA-API-KEY>"' >> conf/local.conf
```
{% /step %}

{% step title="Build your image" %}
Run your build as usual. The FOSSA layer analyzes the runtime packages as part of the build:

```shell
bitbake core-image-minimal
```
{% /step %}

{% step title="View the results" %}
When the build completes, FOSSA logs the project URL:

```shell
[ INFO] Using project name: `core-image-minimal`
[ INFO] Using revision: `qemux86-64-20230103233003`
[ INFO] Using branch: `dunfell`
[ INFO] ============================================================
[ INFO]
[ INFO]     View FOSSA Report:
[ INFO]     https://app.fossa.com/projects/<YOUR-PROJECT-URL-HERE>
[ INFO]
[ INFO] ============================================================
```

Open the project URL to review license compliance and security issues.
{% /step %}
{% /steps %}

{% callout type="info" %}
If license or security issues are found, the build fails with an error. This behavior can be disabled. See the `GUIDE.md` on your branch of the [meta-fossa repository](https://github.com/fossas/meta-fossa) for details.
{% /callout %}

## Resources

- [meta-fossa repository](https://github.com/fossas/meta-fossa): select your Yocto version branch for branch-specific docs.
- [Installing the FOSSA CLI](/docs/cli/walkthroughs/installing-fossa-cli)

---

Source: https://docs.fossa.com/docs/cli/references

# References

Lookup tables for CLI commands, configuration files, debugging workflows, and in-development features.

---

Source: https://docs.fossa.com/docs/cli/references/debugging

# Debugging FOSSA CLI

FOSSA CLI is complicated, and debugging it is too.
This reference describes how to debug it and in what situations you may want to.

The intended audience for this reference is both FOSSA employees and any users
who want to debug FOSSA CLI themselves.

If you are a reader inside or outside the FOSSA organization and see anything
that could be improved in this document, please open a pull request or
drop us a note on [support.fossa.com](https://support.fossa.com)!

## Using this reference

Since this reference is likely to get quite long, keep in mind you can use
GitHub's automated ["Table of Contents" interface](https://github.blog/changelog/2021-04-13-table-of-contents-support-in-markdown-files/)
to jump around.

## Debugging a Missing Project

If your project wasn't found, make sure you meet the requirements in the
[relevant language/build-tool's quick reference](/docs/project-setup/supported-languages)

If your project meets the requirements, it's very likely `fossa analyze` found your project,
but dependency analysis failed.
The next step is to get more information to [debug the strategy](#debugging-strategies).

## Debugging Strategies

The most common scenario for needing to debug FOSSA CLI is when
it uses an external program as part of its analysis, and that fails
for some reason. In this case, the documentation for the strategy
generally will have more specific steps one can take for debugging.

First, see which strategies are being used in your project
with `fossa list-targets`. Here's an example:
```
; fossa list-targets
[ WARN] fossa list-targets does not apply any filtering, you may see projects which are not present in the final analysis.
[ INFO] Found project: npm@testdata/fossa-analyze/
[ INFO] Found target: npm@testdata/fossa-analyze/
[ INFO] Found project: cargo@./
[ INFO] Found target: cargo@./
```

From here you can then go to the FOSSA CLI
[strategies reference](/docs/project-setup/supported-languages)
to view more information (including additional debugging steps)
for the strategies that are actually in use in your project.

If these steps don't help, the next step is to move on to
[debugging with the debug bundle](#debugging-with-the-debug-bundle).

## Debugging FOSSA CLI operation

Sometimes the issue isn't with a specific strategy, but is related
instead to something FOSSA CLI is doing- for example walking the
file system or uploading results to FOSSA.

The first stop here is always to check the _full_ FOSSA CLI output,
not just the summary at the end: often detailed error messages are printed
at the time the error occurs, but by the time other actions run
and the scan summary is printed, the error messages are no longer
obvious. We recommend scrolling to the top of the FOSSA CLI output
and checking for error messages before moving on, these may
show exactly the cause of the error and even give steps to fix it.

For cases where that doesn't work, the next step is to move on to
[debugging with the debug bundle](#debugging-with-the-debug-bundle).

## Debugging with the debug bundle

The FOSSA CLI debug bundle contains a ton of data useful for
troubleshooting what FOSSA CLI does when analyzing your project.

**Important:** Note that FOSSA does not consider the format
of the FOSSA CLI debug bundle to be stable; this means that
any new release of FOSSA CLI could change this format in
a backwards incompatible way.

**Note:** This reference is written from the persective
of the current CLI version. If you're using an older
FOSSA CLI version, check that tag to see if an older
version of this reference exists. If not, some information
may be different than in this reference.

### Generating a debug bundle

To generate a debug bundle, run:
```
fossa analyze --debug
```

After this has run, a new file is created in the current
working directory (the directory from which you launched `fossa`).
This file is titled `fossa.debug.zip`. Its contents can vary depending on the exact command you are running.
But it will almost always contain the debug bundle in fossa.debug.json.

### Extracting a debug bundle

The FOSSA CLI debug bundle is a JSON file inside of fossa.debug.zip,

If you want to extract every file in the zip:

```
; unzip fossa.debug.zip
```


If you only want the debug bundle, you can use
```
; unzip fossa.debug.zip fossa.debug.json
```

If you also want the JSON to be formatted, you can do this in a single line
(if you have `jq` installed):
```
; unzip -p fossa.debug.zip fossa.debug.json | jq > fossa.debug.json
```

### Reading a debug bundle

The contents of the debug bundle are not stable, so rather
than explain the format in detail, we'll keep this high level.

If in doubt, always feel free to reach out to
[FOSSA Support](https://support.fossa.com)
(or, if you're a FOSSA employee, the Analysis team)
for assistance.

#### Tools

Since debug bundles are often quite large,
we recommend viewing the contents in a command-line tool
that is able to handle a large JSON document.

In practice, we've found `jless`
([website](https://jless.io/), [GitHub](https://github.com/PaulJuliusMartinez/jless))
to be a good tool for this purpose.
We recommend viewing its user guide.

Alternative tools are `jq` ([website](https://stedolan.github.io/jq/))
and `gron` ([GitHub](https://github.com/tomnomnom/gron)),
alongside of course graphical tools like
[Visual Studio Code](https://code.visualstudio.com/),
although we have found that these tools can have issues
parsing FOSSA CLI debug bundles due to their size.

The remainder of this section assumes use of `jless`.

#### Top level fields

When the debug bundle is first opened, select the
first field and press `c` to collapse the top-level fields.
You're left with the following:
```
bundleCLIVersion      # Describes the version of FOSSA CLI
bundleSystem          # Records system information
bundleOutput          # The output of your analysis
bundleArgs            # Records the arguments for FOSSA CLI
bundleConfig          # Records the effective config for FOSSA CLI
bundleEnvVariables    # Records the environment variables provided to FOSSA CLI
bundleScope           # Records FOSSA CLI internal operations
bundleJournals        # Records information about IO actions, such as reading files
```

##### `bundleCLIVersion`

`bundleCLIVersion` reports the version of FOSSA CLI.

##### `bundleSystem`

`bundleSystem` reports system information:

- The operating system name, e.g. `linux`.
- The architecture of the system, e.g. `x86_64`.
- The "capabilities" of the system,
  which is the number of parallel threads that may be run.
  Usually this corresponds to number of cores (for local systems)
  although this is different for Docker containers.
- The number of processors available to the system.
- System memory statistics.

##### `bundleOutput`

The raw output of what FOSSA CLI found when analyzing your project.
This is the same output generated when running `fossa analyze -o`.

##### `bundleArgs`

The arguments provided to FOSSA CLI at runtime.
These are a JSON array of strings; for example the command
```
fossa analyze --debug -p 'my cool project'
```

Would report the following list of arguments:
```
["fossa", "analyze", "--debug", "-p", "my cool project"]
```

##### `bundleConfig`

`bundleConfig` records the effective config for FOSSA CLI.

FOSSA CLI can be configured in a number of ways:
- A config file, e.g. `.fossa.yml`
- Arguments at run time, e.g. `--fossa-api-key`
- Environment variables, e.g. `FOSSA_MAVEN_CMD`

These configurations are then merged together internally,
with some sources overwriting other sources.

The config reported here is the final merged config
from all these sources that FOSSA CLI used.

##### `bundleEnvVariables`

`bundleEnvVariables` records the environment variables provided to FOSSA CLI.

FOSSA CLI only includes environment variables believed to be safe to share
(we don't want to accidentally include secrets)
and that we believe are useful for debugging a given strategy.

##### `bundleJournals`

`bundleJournals` records information about IO actions, such as reading files.

These entries are structured in the form:
```
[
  ["<IO Action Identifier>", "<IO Action Arguments ...>"],
  <IO Action Result>
]
```

Where `IO Action Result` is a variable type that may be a literal
(for example `false`), or an object.

When in object form, generally the object is in the shape
```
{
  "Left": "<Error message or null if no error>",
  "Right": <IO Action Data>
}
```

Using the above, here are a few examples:
```
# This indicates that the file `/home/me/test/package.json` does not exist.
[
  [ "Effect.ReadFS.DoesFileExist", "/home/me/test/package.json" ],
  false
]

# This indicates that FOSSA CLI failed to read the content of `package.json`.
[
  [ "Effect.ReadFS.ReadContentsBS", "/home/me/test/package.json" ],
  { "Left": "Failed to read content: file does not exist" }
]

# This indicates that `/home/me/test/Cargo.toml` does exist.
[
  [ "Effect.ReadFS.DoesFileExist", "/home/me/test/Cargo.toml" ],
  true
]

# This indicates that FOSSA CLI ran the command `cargo generate-lockfile`
# successfully, and that it did not provide any output.
[
  [ "Effect.Exec.Exec", "/home/me/test/", { "cmdName": "cargo", "cmdArgs": "generate-lockfile" } ],
  { "Right": "" }
]

# This indicates that FOSSA CLI ran the command `cargo metadata`
# successfully, and that it did provide the given output.
# However the actual output is extremely verbose and not included in this example.
[
  [ "Effect.Exec.Exec", "/home/me/test/", { "cmdName": "cargo", "cmdArgs": "metadata" } ],
  { "Right": "<omitted output for example>" }
]
```

##### `bundleScope`

`bundleScope` records FOSSA CLI internal operations.

This is the most complicated part of the debug bundle,
and is _generally_ something only useful for FOSSA employees,
since understanding this requires a pretty good understanding
of the internals of FOSSA CLI.

However, in general, the shape of this section is as follows:
```
{
  "duration": "2.613411",   # The number of seconds the operation took to complete
  "scope": "analyze-cargo", # (Optional) The name of the operation.
  "events": [],             # A nested set of objects.
}
```

The objects under `events` can be in many forms,
and different types of objects are interspersed in this array.

Some examples:
- Plain text lines, representing log output, may appear here.
- Objects similar to those in `bundleJournals` may appear here.
- Additional `bundleScope` objects may be arbitrarily nested here.

The most effective way for someone not familar with FOSSA CLI internals
to interpret this section is to skim the entries looking for text
(which represents log lines) and use that to zero in on what FOSSA CLI
is doing, using that to zero in on more critical parts of the
output. Given the structure of this section it is very information dense.

---

Source: https://docs.fossa.com/docs/cli/references/experimental

# Experimental Features

## Experimental Features

At FOSSA, we like to develop in the open. 
This helps us get feedback from our users early and often, and helps our users take advantage of the newest cutting-edge features we're working on.

FOSSA also has strong commitments to backwards compatibility and support.
We respect the fact that we live in the CI pipeline, and we want to avoid anything that would get in the way of our users shipping software.

These two commitments are hard to reconcile: developing in the open means some level of backwards-incompatible changes and potential user disruption.
Our way of bridging this gap is "experimental options", which offer a peek into what we're working on next while still retaining the flexibility to iterate.

### What denotes an experimental feature?

Experimental features are always prefixed by `experimental`. For example, the flag `--output` is _not_ experimental, while the hypothetical flag `--experimental-text-output` would be.
In the case where we are testing out new functionality for an existing feature, we may simply prepend `experimental`: to reuse the previous example, a new output format might be tested under simply `--experimental-output`.

### When are experimental features used?

Experimental features are _always_ opt-in. This means that we'll never turn on an experimental feature unless the user explicitly enables it!

### CLI Versioning with experimental features

Experimental features aren't considered part of our semver-style versioning scheme. This lets us focus on only stable features in the version scheme and gives us the room we need to experiment in the open.
This means that experimental features may be introduced, change in backwards incompatible ways, or even be removed in a `PATCH` release (`x.x.PATCH`).

That being said, we do try to maintain backwards compatibility, and if we can't we will try our best to issue deprecation warnings before making backwards-incompatible changes to experimental features.

### Feature promotion

When experimental features are promoted, we perform the following steps:

1. We add the feature without an `experimental` prefix.
2. We mark the `experimental`-prefixed version of the feature as deprecated, and log warnings when it's used.
3. After at least two CLI releases we remove the `experimental`-prefixed version of the feature.

Once an experimental feature is promoted it's considered part of our backwards compatibility goals and is considered part of our semver-style CLI versioned releases.

### Support level

We do our best to support our users using experimental features! If you have a question or a problem about the experimental feature, send us an email or open an issue. 
We'd appreciate if you'd include:

- In the title/subject, whether you are using experimental features.
- In the body, the features you're using (ideally along with your actual command being run).

The main difference compared to stable features is that we don't consider experimental features to be "critical", meaning that we consider them to be something that users can stop using to unblock their CI pipeline.
As such, our first recommendation if you're in a situation where an experimental feature is blocking your CI pipeline is to disable the feature (but still send us a support request, we'd like to know about it)!

### Submitting feedback

We love getting feedback from our users, and feedback on experimental options is no different!
If you send us an email or open an issue relating to an experimental feature, we'd appreciate if you'd include:

- In the title/subject, whether you are using experimental features.
- In the body, the features you're using (ideally along with your actual command being run).

This helps us route the feedback to the person who owns the feature!

---

Source: https://docs.fossa.com/docs/cli/references/experimental/path-dependency

# Path Dependency

## What is path dependency?

Path dependency is a dependency, which is sourced from filesystem, as opposed to a package manager registry or URL. A path dependency may or may not have transitive dependencies. 
Path dependency is also referred to as `local` or `vendor` dependency by some package managers.

For example, in the following `go.mod` file, with `gomod` analysis and the `--experimental-analyze-path-dependencies` flag, `fossa-cli` would consider `../vendor/squirrel`, to be a path dependency. If path dependency analysis is disabled, `fossa-cli` would ignore this dependency completely and only show transitive dependencies originating from `../vendor/squirrel`. In such a case, license and copyright obligations originating from `../vendor/squirrel` will not be captured in FOSSA's findings, and subsequent software bill of materials generated.

```go
// Example go.mod file
module tester

go 1.14

replace github.com/Masterminds/squirrel => ../vendor/squirrel
require github.com/Masterminds/squirrel v1.4.0
```

In the FOSSA UI, path dependencies are shown with the `Local` tag.

## How are path dependencies scanned?

Path dependencies are scanned using the "CLI license scan," similar to how [vendor dependencies](/docs/cli/features/vendored-dependencies) are scanned by default. A "CLI license scan" performs a license scan at the path and uploads the results of these scans to the provided FOSSA endpoint.

For performance reasons, the FOSSA service caches the results of a path dependency by the combination of its `(project id, path, hash of path's content)`. Due to this caching setup, it is normal for the first analysis to take some time, especially for larger projects, but future analyses of dependencies with the same information should be fast.

In the event that caching is causing problems, FOSSA can be made to rescan this kind of dependency by:
- Running `fossa analyze` with the `--force-vendored-dependency-rescans` flag, or
- Setting `vendoredDependencies.forceRescans` to `true` in `.fossa.yml` at the root of the project.

## Limitations

- Currently, path dependencies do not support vulnerability scanning.
- Currently, path dependencies are only supported in:
  - `golang` using the [gomod strategy](/docs/project-setup/supported-languages/golang/gomodules).
  - PDM (Python) projects via the [pdm strategy](/docs/project-setup/supported-languages/python/pdm).
  - Rust projects via the [Cargo strategy](/docs/project-setup/supported-languages/rust/cargo).

## F.A.Q

### How do I enable path dependency in FOSSA analysis?

Run `fossa analyze` with the `--experimental-analyze-path-dependencies` flag.

### How do I disable path dependency in FOSSA analysis?

By default, path dependency analysis is disabled. Note that, in the future, `fossa-cli` will enable path dependency analysis by default.

### Is `fossa-cli` uploading the content of my path dependency to the server?

`fossa-cli` only uploads the portions of the file that contain matches to licenses, not the entire file. If `cliLicenseScanRequireFullFileUpload` is enabled in FOSSA endpoint
for your organization, `fossa-cli` will upload the full contents of any file that has licensing data. By default,  `cliLicenseScanRequireFullFileUpload` is
disabled for all organizations. Please contact [FOSSA support](https://support.fossa.com) to enable, this functionality.

## How are path dependencies different from FOSSA's vendor dependencies?

Path dependencies, unlike [vendored dependencies](/docs/cli/features/vendored-dependencies), can be either direct or transitive in the dependency graph. Furthermore, path dependencies are scoped to the project in FOSSA, as opposed to the entire organization.

---

Source: https://docs.fossa.com/docs/cli/references/experimental/binary-discovery

# Binary Discovery

FOSSA supports the ability to flag all binary dependencies discovered in your project source tree as unlicensed dependencies via an opt-in flag (`--experimental-enable-binary-discovery`).

The core idea behind this feature is that some organizations wish to validate all potential sources of intellectual property rights,
and binaries are potential sources of intellectual property rights data for which we typically cannot automatically discover licensing information.

## Discovery

Find all files that contain a NUL (`0`) byte in the first 8000 bytes of the file.

## Analysis

The following strategies are implemented in a "fallback" manner, 
meaning that for any matching file extension we try strategies in the order listed here until a strategy succeeds.

| File Extension   | Analysis                       |
|------------------|--------------------------------|
| `.jar` or `.aar` | Read `pom.xml`                 |
| `.jar` or `.aar` | Read `MANIFEST.MF`             |
| `.whl`           | Read `*.dist-info/METADATA`    |
| `.nupkg`         | Read `*.nuspec`                |
| Anything else    | Create user-defined dependency |

### Analyzing jar and aar dependencies

#### Read `pom.xml`

We unpack the archive and search inside the `META-INF` directory for `pom.xml` files.
We then select the `pom.xml` with the *shortest path* and use that as the representative `pom.xml` for the JAR.

From the `pom.xml` we read:

- `project.groupId` and `project.artifactId` are combined to make the dependency description.
- `project.version` is used for the dependency version.
- Entries in `project.licenses` are extracted for their `name` field, which are concatenated and used as the dependency license.

#### Read `MANIFEST.MF`

We unpack the archive and search inside for a `META-INF/MANIFEST.MF` file.

From that file we read:

- `Bundle-SymbolicName`, if present, is used for the dependency description. If `Bundle-SymbolicName` is not present, we fallback to `Implementation-Title`.
- `Implementation-Version` is used for the dependency version.

#### Read `*.dist-info/METADATA`

We unpack the archive and search inside for a `*.dist-info/METADATA` file.

From that file we read:

- `Name` is used for the dependency name.
- `Version` is used for the dependency version.

Using those values, we create a `pip` dependency.

#### Read `*.nuspec`

We unpack the archive and search inside for a `*.nuspec` file.

From that file we read:

- `id` is used for the dependency name.
- `version` is used for the dependency version.

Using those values, we create a `nuget` dependency.

### Creating user-defined binary dependencies

Any binaries not discovered using a different feature are considered user-defined.
Binaries discovered via this feature are displayed in the FOSSA UI as `user` dependencies.

The name of the dependency is the path to the binary within the project, and the version of the dependency is the hash of the binary file that was discovered.
The description of the dependency is "Binary discovered in source tree".

---

Source: https://docs.fossa.com/docs/cli/references/experimental/msb

# Multi Stage Builds

## Multi Stage Builds

The _Multi-stage builds_ feature allows users give FOSSA metadata attached to a binary ahead of time (for example, a team working on an internal library can tell FOSSA about that library as part of that CI process).
FOSSA then can detect binaries that are registered as dependencies in downstream projects that include that binary in their source tree when [detecting vendored dependencies](/docs/cli/references/subcommands/analyze/detect-vendored).

### Use Cases

#### Vendor a known binary

The _Multi-stage builds_ feature supports the ability to link metadata to binaries (example: `name`, `version`, `license`) for which you do not have the source available.
The binary will be identified within the org by its unique fingerprint as it is shared internally between the projects it will appear as a regular direct dependency with all of the specified metadata that was previously specified.
Such binary can be a library purchased from a vendor, or a prebuilt open source project.

#### Vendor an internal binary

If the team building the internal binary links the binary to its project, multi-stage build support can identify such binaries vendored into the directory structure of another project.
Linking will preserve all of the metadata known about the artifact during the linking.

The upstream library project will be shown as a direct dependency of the project that is vendoring the binary artifact, and upstream project’s dependencies are shown as transitive dependencies of the vendoring project.

#### Build a binary used downstream

The _Multi-stage builds_ feature supports the ability to link your output binaries when analyzing your project to support the internal binary use case.
This allows you to configure the CI pipeline for your project to always keep the linked binary up to date.

### Link a binary’s fingerprint to a user project

When the source of a library is available, FOSSA can scan that library for its dependencies and associate one or more binaries with the project.
Then, when scanning a downstream project that uses one of those binaries, all the dependency information from the library will appear as transitive dependency information for the downstream project.

To link one or more binaries to a project, use `--experimental-link-project-binary`.

Example:

```bash
fossa analyze --experimental-enable-vsi \
  --experimental-link-project-binary <BIN_DIR>
```

### Link a binary’s fingerprint to a user-defined dependency

When the source of a binary library is not available, FOSSA can still surface a binary as a user-defined dependency when it is present in a downstream project, so long as the dependency information has been linked to the binary ahead of time.

To link one or more binaries to a set of user-defined dependency metadata, use the subcommand `experimental-link-user-defined-dependency-binary`.

Example:

```bash
fossa experimental-link-user-defined-dependency-binary [DIR] \
  --name <NAME> \
  --version <VERSION> \
  --license <LICENSE>
```

Optionally, a project homepage and/or a description may be provided.

Example:

```bash
fossa experimental-link-user-defined-dependency-binary [DIR] \
  --name <NAME> \
  --version <VERSION> \
  --license <LICENSE> \
  --description <DESCRIPTION> \
  --homepage <HOMEPAGE>
```

**Note**: Similar to the `analyze` subcommand, this supports the `--endpoint` and `--fossa-api-key` commands to customize how the client connects to FOSSA.

### Troubleshooting

#### Failing to resolve dependencies for FOSSA projects

> _Note: This error may present during a `--detect-vendored` strategy._
> _For more information on detecting vendored dependencies see [detecting vendored dependencies](/docs/cli/references/subcommands/analyze/detect-vendored)._

Let's say we have two C projects: `LibProject` and `CliProject`.
`LibProject` is a library that is used inside `CliProject`, and we want to report that relationship in FOSSA, such that dependencies of `LibProject` appear as transitive dependencies of `CliProject`.

Let's go further and say our CI pipeline for `LibProject` looks like this, where we compile its output binary (`libproject.o`) into the directory `out/`:

```bash
make build -o out
```

We can then integrate FOSSA here to essentially tie the fingerprint of that `libproject.o` binary to `LibProject` in FOSSA:

```bash
make build -o out
fossa analyze --experimental-link-project-binary out --detect-vendored
```

This causes FOSSA to store a record saying "whenever I see a file with the same cryptographic fingerprint as `libproject.o` in a future scan, I know that means `LibProject`".

Later, when we scan `CliProject`, so long as it contains a copy of `libproject.o` inside, we'll then perform the following steps:

1. The CLI will determine that `LibProject` is a dependency of `CliProject`, because it sees that copy of `libproject.o` inside the `CliProject` directory tree.
2. The CLI will then ask the FOSSA server for the list of `LibProject`'s dependencies.
3. The CLI will then report to the FOSSA server that `LibProject` is a dependency of `CliProject`, and include `LibProject`'s dependencies as transitive dependencies.

The trouble is, what happens if the user scanning `CliProject` doesn't have access to view the dependencies of `LibProject`?

In that case, we fail with an error like this one:

```bash
Failed to resolve dependencies for the following FOSSA projects:
  custom+1/libproject$1635972409

You may not have access to the projects, or they may not exist (see the warnings below for details).
If desired you can use --experimental-skip-vsi-graph to skip resolving the dependencies of these projects.
```

This is the CLI telling us "I know `LibProject` is a dependency of `CliProject`, but I can't view `LibProject` in the FOSSA server, so I don't know its dependencies and therefore I can't report its dependencies as transitive dependencies of `CliProject`".

The best way to handle this is to ensure that anyone using `LibProject` as a dependency has access to view it in FOSSA, so that they can get an accurate dependency graph.
However, as a workaround, the user may also use `--experimental-skip-vsi-graph custom+1/libproject$1635972409`, which tells the CLI "that's OK, I know you can't see it, and I'm OK with not getting the transitive dependencies from that project".

---

Source: https://docs.fossa.com/docs/cli/references/experimental/subcommands

# Subcommands

Unstable subcommands and flags that may change before promotion to the main reference.

---

Source: https://docs.fossa.com/docs/cli/references/experimental/subcommands/experimental-link-user-defined-dependency-binary

# fossa experimental-link-user-defined-dependency-binary

## `fossa experimental-link-user-defined-dependency-binary`

`experimental-link-user-defined-dependency-binary` is a subcommand used to link binaries produced from a project to that project as part of the "multi-stage builds" experimental feature.
For more information, see the [multi stage builds overview](/docs/cli/references/experimental/msb).

---

Source: https://docs.fossa.com/docs/cli/references/files

# Files

Schemas and examples for optional files that extend or override default CLI behavior.

---

Source: https://docs.fossa.com/docs/cli/references/files/fossa-deps

# 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.

By default, the `fossa-deps.{yaml, yml, json}` file at the root of the project is used. However, if the `--fossa-deps-file` flag is present, then the provided `<name-of-file>.{yaml, yaml, json}` file will be used instead.

For more details on specifying a fossa-deps file, please refer to the [subcommand](/docs/cli/references/subcommands/analyze) documentation.

## 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.
- `labels`: An optional list of labels to be added to the dependency.
```yaml
referenced-dependencies:
- type: gem
  name: iron
- type: pypi
  name: Django
  version: 2.1.7
```

For more details, please refer to the [feature](/docs/cli/features/manual-dependencies) 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:
```yaml
- 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](/docs/cli/features/manual-dependencies) 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.

> Combined length of url and version has upper bound. It depends on your organization identifier. You can
find your organization identifier in FOSSA Webapp, by going to any project's "settings" page, and retrieving
numeric value from project's locator. For example, project locator of `custom+123/some-project-id`, means
`123` is your organization identifier.

> Combined length of `url`, `version`, and your `organizaion id` must be less than `241`.

For more details, please refer to the [feature](/docs/cli/features/manual-dependencies) 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.
- `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.

```yaml
vendored-dependencies:
- name: Django
  path: vendor/Django-3.4.16.zip
  version: 3.4.16
  metadata:
    homepage: https://djangoproject.com
    description: Django
```
> 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](/docs/cli/features/vendored-dependencies) walk through.

### `fork-aliases:`

Denotes mapping of fork dependencies to their base dependencies. This is useful when you have forked a dependency and want it to be treated as the base dependency by FOSSA. This, for example, will allow FOSSA to find and report security issues that are associated with the root project.

As an example, if you have forked the Serde crate in a private repository and called it `my-serde`, then you could tell FOSSA to tranlate `my-serde` to `serde` like this:

```yaml
fork-aliases:
- fork:
    type: cargo
    name: my-serde
  base:
    type: cargo
    name: serde
```

- `fork`: The fork dependency entry that should be aliased to the base dependency. (Required)
  - `type`: Type of the fork dependency. (Required)
  - `name`: Name of the fork dependency. (Required)
  - `version`: Version of the fork dependency. See "version matching rules" below for more details. (Optional)
- `base`: The base dependency that your fork should be aliased to. (Required)
  - `type`: Type of the base dependency. (Required)
  - `name`: Name of the base dependency. (Required)
  - `version`: Version of the base dependency. See "version matching rules" below for more details. (Optional)
- `labels`: An optional list of labels to be added to the fork alias. The dependency in FOSSA's UI will be treated as a normal dependency, so if you use an `org` scope for the label it will be applied to all versions of the base dependency across your organization. We suggest using the `project` or `revision` scope for labels on fork aliases.

**Version Matching rules:**
- If `fork` version is specified, only that exact version will be translated
- If `fork` version is not specified, any version will be translated to the base dependency. The version of the translated dependency depends on whether the base version is specified or not.

- If `base` version is specified, the dependency will always be translated to the specified version
- If `base` version is not specified, the original version from the fork is preserved

```yaml
fork-aliases:
- fork:
    type: cargo
    name: my-serde
  base:
    type: cargo
    name: serde
  labels:
  - label: internal
    scope: project
- fork:
    type: cargo
    name: my-serde
    version: 1.0.0  # Only version 1.0.0 will be translated
  base:
    type: cargo
    name: serde
    version: 2.0.0  # Will always translate to version 2.0.0
```

## Labels

Each kind of dependency referenced above can have a `labels` field, which is a list of labels to be added to the dependency.
These labels are **user-defined**; you may choose any labels. What they mean is up to you and/or your organization.

Labels have a `scope` field, which is the scope of the label. The possible scopes are:
- `org`: The label is scoped to the organization.
- `revision`: The label is scoped to the revision.
- `project`: The label is scoped to the project.

You may attach multiple labels to a single dependency.
For example:

```yaml
referenced-dependencies:
- type: pypi
  name: numpy
  version: 2.2.0
  labels:
  - label: numbers-go-brr
    scope: org
  - label: oss-approved
    scope: revision

custom-dependencies:
- name: somecorp-api-client
  version: 1.2.3
  license: Proprietary
  metadata:
    homepage: https://www.partner.somecorp.com/interface/client/wrapper/lib
    description: Gives access to the SomeCorp API.
  labels:
  - label: proprietary
    scope: version
  - label: license-paid-2024
    scope: revision

vendored-dependencies:
- name: Django
  path: vendor/Django-3.4.16.zip
  version: 3.4.16
  metadata:
    homepage: https://djangoproject.com
    description: Django
  labels:
  - label: hr-docs
    scope: project
  - label: internal-dependency
    scope: revision

fork-aliases:
- fork:
    type: cargo
    name: my-serde
  base:
    type: cargo
    name: serde
  labels:
  - label: internal
    scope: org
  - label: fork-approved
    scope: revision
```

## 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:

```yaml
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!):

```yaml
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.

---

Source: https://docs.fossa.com/docs/cli/references/files/fossa-yml

# .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.


```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"
```


## 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](https://docs.fossa.com/docs/api-reference#api-tokens) 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.

```yaml
# 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.

<img src="../../assets/project-locator-example.png">

#### `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.

<img src="../../assets/project-id-example.png">

#### `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](/docs/cli/references/subcommands/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](https://docs.fossa.com/docs/atlassian-jira) 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. Specifying more than 5 labels (counting both `.fossa.yml` labels and any `--project-label` flags) fails the analysis with the error `Projects are only allowed to have 5 associated project labels`, rather than silently ignoring the extras. Keep the label count at or below 5.

### `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.

<img src="../../assets/release-group-title-example.png">

#### `releaseGroup.release:`
The release associated with the release group.

<img src="../../assets//release-example.png">

#### `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.

<img src="../../assets/project-locator-example.png">

#### `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.

<img src="../../assets//project-revision-example.png">

#### `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](https://docs.fossa.com/docs/configuring-a-licensing-policy) for addition details on license policies.

#### `releaseGroup.securityPolicy:`
The name of the security policy associated with the release group. Refer to the [documentation](https://docs.fossa.com/docs/configuring-a-security-policy) for addition details on security policies.

#### `releaseGroup.qualityPolicy:`
The name of the quality policy associated with the release group. Refer to the [documentation](https://docs.fossa.com/docs/configuring-quality-policies-copy) 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](https://github.com/fossas/fossa-cli/blob/master/docs/features/vendored-dependencies.md) 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](https://github.com/fossas/fossa-cli/blob/master/docs/features/vendored-dependencies.md).

#### `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](/docs/cli/features/vendored-dependencies#path-filtering).

### `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.
```yaml
    - 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:

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

#### `targets.excludeManifestStrategies:`
If set to true, all manifest-based strategies for discovering targets will be skipped. This will still allow things like finding dependencies explicitly specified in fossa-deps.yml, running first-party license scans or running custom-license scans if they are configured. This setting will override any target filters or path filters.

### `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.

```yaml
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](/docs/cli/walkthroughs/analysis-target-configuration)

#### 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.
    ```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
```

### 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.


```yaml
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.

<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">

### 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.

---

Source: https://docs.fossa.com/docs/cli/references/subcommands

# Subcommands

Entry point for stable fossa subcommands: analyze, test, report, container, project, and release group.

---

Source: https://docs.fossa.com/docs/cli/references/subcommands/analyze

# fossa analyze

## `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](#common-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. Mutually excludes `--policy-id`.    |
| `--policy-id 'some policy id'`         |       | Assign a specific FOSSA policy to this project by id. Mutually excludes `--policy`. |
| `--project-label`                      |       | assign up to 5 labels to the project                                                |
| `--release-group-name 'MY_RG'`         |       | add the project to this release group (also requires `--release-group-release`)     |
| `--release-group-release 'MY_RELEASE'` |       | add the project to this release version within the release group                    |

### Filtering Paths and Targets

The paths and targets filtering options allow you to specify the exact targets which be should be scanned.

| Name                             | Description                                                                                                              |
|----------------------------------|--------------------------------------------------------------------------------------------------------------------------|
| `--only-target`                  | Only scan these targets. See [targets.only](/docs/cli/references/files/fossa-yml#targetsonly) in the fossa.yml spec.                   |
| `--exclude-target`               | Exclude these targets from scanning. See [targets.exclude](/docs/cli/references/files/fossa-yml#targetsexclude) in the fossa.yml spec. |
| `--only-path`                    | Only scan these paths. See [paths.only](/docs/cli/references/files/fossa-yml#pathsonly) in the fossa.yml spec.                         |
| `--exclude-path`                 | Exclude these paths from scanning. See [paths.exclude](/docs/cli/references/files/fossa-yml#pathsexclude) in the fossa.yml spec.        |
| `--include-unused-deps`          | Include all deps found, instead of filtering non-production deps.  Ignored by VSI.                                       |
| `--debug-no-discovery-exclusion` | Ignore these filters during discovery phase.  This flag is for debugging only and may be removed without warning.        |
| `--without-default-filters`      | Ignore default path filters. See [default path filters](/docs/cli/references/subcommands/analyze#what-are-the-default-filters)                       |


### Printing FOSSA results

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

```sh
fossa analyze --output
```

To print projects and dependency graph information to stdout *in addition* to uploading to FOSSA as normal, use the `--tee-output` flag.

```sh
fossa analyze --tee-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.

```sh
fossa analyze --json
```

```json
{"branch":"master", "id":"custom+<org-id>/new-project$123", "project":"<org-id>/new-project", "projectId":"custom+<org-id>/new-project", "revision":"123", "url":"https://app.fossa.com/projects/custom%2b+<org-id>$2fnew-project/refs/branch/master/123"}
```

### Running a specific fossa-deps file

The `--fossa-deps-file` flag can be used to specify the `fossa-deps` file that you want to use. The name of the file is arbitrary.

See the [fossa-deps documentation](/docs/cli/references/files/fossa-deps) for configuration.

```sh
fossa analyze --fossa-deps-file /path/to/file
```

### Vendored Dependencies

The Vendored Dependencies feature allows you to scan for licenses directly in your code. For more information, please see the [Vendored Dependencies documentation](/docs/cli/features/vendored-dependencies).

| Name                                      | Description                                                                                                                                                                           |
|-------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `--force-vendored-dependency-scan-method` | Force the vendored dependency scan method. The options are 'CLILicenseScan' or 'ArchiveUpload'. 'CLILicenseScan' is usually the default unless your organization has overridden this. |
| `--force-vendored-dependency-rescans`     | Force vendored dependencies to be rescanned even if the revision has been previously analyzed by FOSSA. This currently only works for CLI-side license scans.                         |

### Custom License Searches

The "Custom License Searches" feature allows you to define text strings or regular expressions that are used to search through your codebase. If a match to the text string or regular expression is found, then a custom license is reported for that match.

An administrator of your organization can set up custom license searches that are always run when you analyze your codebase with `fossa analyze`. Using the `--ignore-org-wide-custom-license-scan-configs` flag will ignore those organization-wide custom license searches.

See the [Custom License and Keyword Searches documentation](/docs/cli/features/custom-license-and-keyword-searches) for more details.

### Running in a specific directory

```sh
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.

```sh
fossa analyze --unpack-archives
```

We support the following archive formats:

- `.zip`
- `.tar`
- `.tar.gz`
- `.taz`
- `.tgz`
- `.tar.xz`
- `.txz`
- `.tar.bz2`
- `.tbz`
- `.tbz2`
- `.tz2`
- `.jar`
- `.aar`
- `.rpm`, with...
  - `gzip` compression
  - `lzma` compression
  - `xz` compression
  - `zstd` compression

### Enabling or disabling additional strategies

In addition to the [standard flags](#specifying-fossa-project-details), the analyze command supports the following additional strategy flags:

| Name                                                                              | Description                                                                                                                                                                                      |
|-----------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| [`--detect-vendored`](/docs/cli/references/subcommands/analyze/detect-vendored)                               | Enable the vendored source identification engine. For more information, see the [C and C++ overview](/docs/project-setup/supported-languages/c-cpp).                                                    |
| [`--detect-dynamic './some-binary`](/docs/cli/references/subcommands/analyze/detect-dynamic)                  | Analyze the binary at the provided path for dynamically linked dependencies. For more information, see the [C and C++ overview](/docs/project-setup/supported-languages/c-cpp).                         |
| [`--static-only-analysis`](/docs/project-setup/supported-languages#static-and-dynamic-strategies) | Do not use third-party tools when analyzing projects.                                                                                                                                            |
| `--strict`                                                                        | Enforces strict analysis to ensure the most accurate results by rejecting fallbacks. When run with `--static-only-analysis`, the most optimal static strategy will be applied without fallbacks. |


### Snippet Scanning

Snippet scanning identifies potential open source code snippets within your first-party source code by comparing file fingerprints against FOSSA's knowledge base. This feature helps detect code that may have been copied from open source projects.

#### Enabling Snippet Scanning

| Name                | Description                                                                                                                                                                           |
|---------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `--snippet-scan`  | Enable snippet scanning during analysis. This feature fingerprints your source files and checks them against FOSSA's snippet database.        |

Snippet Scanning must also be enabled for your organization, and is only available for enterprise customers. If you would like to enable it for your organization, please [contact us](https://support.fossa.com).

#### More detail

For more detail about how Snippet Scanning works, how to use file filtering during Snippet Scanning, what information is sent to FOSSA's servers and a description of the Snippet Scan Summary, see [the Snippet Scanning feature documentation](/docs/cli/features/snippet-scanning).

### Vendored Dependency Scanning with Vendetta

Vendetta is a feature that identifies the paths of potential open source code
dependencies vendored in your project by comparing file hashes against FOSSA's
knowledge base. This feature helps find dependencies that are included in your
project directly as source.

#### Enabling Vendetta

| Name                | Description                                                                                                                                                                           |
|---------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `--x-vendetta`      | Enable vendored dependency scanning during analysis. This experimental feature hashes your source files and checks them against FOSSA's open source component database.               |

#### More detail

For more detail about how Vendetta works, how to use file filtering during
scanning, or what information is sent to FOSSA's servers, see
[the Vendetta feature documentation](/docs/cli/features/vendetta).

### Experimental Options

_Important: For support and other general information, refer to the [experimental options overview](/docs/cli/references/experimental) before using experimental options._

In addition to the [standard flags](#specifying-fossa-project-details), the analyze command supports the following experimental flags:

| Name                                                                                     | Description                                                                                                                                                                                    |
|------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| [`--experimental-enable-binary-discovery`](/docs/cli/references/experimental/binary-discovery)   | Enable reporting binary files as unlicensed dependencies. For more information, see the [binary discovery overview](/docs/cli/references/experimental/binary-discovery).                               |
| [`--experimental-link-project-binary './some-dir'`](/docs/cli/references/experimental/msb)       | Link the provided binary files to the project being analyzed. For more information, see the [multi stage builds overview](/docs/cli/references/experimental/msb).                                      |
| [`--experimental-skip-vsi-graph 'custom+1/some$locator'`](/docs/cli/references/experimental/msb) | Skip resolving the dependencies of the given project that was previously linked via `--experimental-link-project-binary`.                                                                      |
| `--experimental-force-first-party-scans`                                                 | Force [first party scans](/docs/cli/features/first-party-license-scans) to run                                                                                                                  |
| `--experimental-block-first-party-scans`                                                 | Force [first party scans](/docs/cli/features/first-party-license-scans) to not run. This can be used to forcibly turn off first-party scans if your organization defaults to first-party scans. |
| `--experimental-analyze-path-dependencies`                                               | License scan path dependencies, and include them in the final analysis. For more information, see the [path dependency overview](/docs/cli/references/experimental/path-dependency).                          |


### F.A.Q.

#### How do I add a project to a release group when it is analyzed?

To add the project you're analyzing to a [release group](https://docs.fossa.com/docs/release-groups), use
`fossa analyze --release-group-name 'MY_RG' --release-group-release 'MY_RELEASE_VERSION'`

Note that the `MY_RG` release group must already exist, as well as `MY_RELEASE_VERSION` within it. You may use the `release-group` [subcommand](https://github.com/fossas/fossa-cli/blob/master/docs/references/subcommands/release-group.md) in advance to create these or do so [within the FOSSA UI](https://docs.fossa.com/docs/release-groups).

#### Why is the `fossa-cli` skipping my project?

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

```text
[ 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 (default path filters)
[ 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](https://github.com/fossas/fossa-cli/blob/master/docs/references/files/fossa-yml.md#analysis-target-configuration) (this filtering is referred to as "exclusion filters").
- (b) Target is excluded via [default path filters](/docs/cli/references/subcommands/analyze#what-are-the-default-filters) (this filtering was previously referred to as "production path filtering").

#### What are the default filters?

Default filters are filters which `fossa-cli` applies by default. These filters,
provide sensible non-production target exclusion. As `fossa-cli` relies on manifest and lock files provided in the project's directory,
default filters, 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.

Specifically, `fossa-cli` by default skips any targets found within the following directories:

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

To disable default filters, provide `--without-default-filters` flag when performing `fossa analyze` command. Currently,
it is not possible to disable only a subset of default filters. If you would like to only apply a subset of default filters, you can
use `--without-default-filters` in conjunction with [exclusion filters](/docs/cli/references/files/fossa-yml#analysis-target-configuration). Refer to
[exclusion filters walkthough](/docs/cli/walkthroughs/analysis-target-configuration) for example on how to apply path and target exclusion filters.

#### 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](https://pypi.org/project/datasets/) package,

```python
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](/docs/cli/references/files/fossa-deps) 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](/docs/cli/features/vendored-dependencies).

```yaml
# 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](https://support.fossa.com).

#### 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).

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

## Common FOSSA Project Flags

All `fossa` commands support the following FOSSA-project-related flags:

| Name                               | Short | Description                                                                                                                              |
|------------------------------------|-------|------------------------------------------------------------------------------------------------------------------------------------------|
| `--project 'some project'`         | `-p`  | Override the detected project name                                                                                                       |
| `--revision 'some revision'`       | `-r`  | -Override the detected project revision                                                                                                  |
| `--fossa-api-key 'my-api-key'`     |       | An alternative to using the `FOSSA_API_KEY` environment variable to specify a FOSSA API key                                              |
| `--endpoint 'https://example.com'` | `-e`  | Override the FOSSA API server base URL                                                                                                   |
| `--config /path/to/file`           | `-c`  | Path to a [configuration file](/docs/cli/references/files/fossa-yml) including filename. By default we look for `.fossa.yml` in base working directory. |

---

Source: https://docs.fossa.com/docs/cli/references/subcommands/container

# fossa container

The `fossa container` subcommand supports analysis and testing of containers for vulnerabilities and compliance issues.

`fossa container` supports following subcommands:

- `analyze`: Scan a container image
- `test`: Check for issues in a previously scanned container image

## `fossa container analyze <ARG>`

`fossa container analyze` scans container images from:

1) Docker archive, e.g. `docker save redis:alpine > redis.tar`
2) Docker Engine (accessed via unix socket `/var/lib/docker.sock`)
3) OCI Registry

No arguments are required to specify the kind of image being analyzed:
`fossa-cli` automatically identifies the appropriate image source.

For example:

```bash
# Local image via Docker Engine
#
# Note: when pulling Docker Engine, the tag is required;
# otherwise the image is inferred to be `docker.io/library/<image>`.
fossa container analyze alpine:3.16.0

# Infers to `docker.io/library/debian:latest` and pulls the image from there.
fossa container analyze debian

# Tries to use the local Docker Engine, but if that fails
# infers to `docker.io/library/debian:latest`
# and pulls the image from there.
fossa container analyze debian:latest

# Explicit remote image with a host and namespace
fossa container analyze cgr.dev/chainguard/wolfi-base:latest

# Exported container image
# `docker save redis:latest > redis.tar`
fossa container analyze redis.tar
```

You can provide `--only-system-deps` to only analyze dependencies originating from following system package managers:

- dpkg
- rpm
- alpine

You can refer to [scanner](/docs/cli/references/subcommands/container/scanner) documentation, to learn
more about how FOSSA CLI performs scan on a container image.

> [!NOTE]
>
> FOSSA CLI uses [`circe`](https://github.com/fossas/circe), another binary
> maintained by FOSSA, to download and export container images.
>
> For more details on how this works refer to the Circe documentation;
> you can also always try running `circe` directly if you encounter any issues.

## `fossa container test <ARG>`

Check for issues in a previously analyzed image.
Exits non-zero if issues are found.

For example:

```bash
fossa container test redis:alpine
```

To render results in JSON format:

```bash
fossa container test redis:alpine --format json
```

## Printing results without uploading to FOSSA

The `--output` flag outputs dependency graph information to the terminal rather than uploading to FOSSA.

```sh
fossa container analyze redis:alpine --output
```

## Ignore default filters

Default filters are filters which `fossa-cli` applies by default. These filters,
provide sensible non-production target exclusion. As `fossa-cli` relies on manifest and lock files provided in the project's directory,
default filters, 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.

Specifically, `fossa-cli` by default skips any targets found within the following directories:

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

To disable default filters, provide `--without-default-filters` flag when performing `fossa container analyze`. Currently,
it is not possible to disable only a subset of default filters. If you would like to only apply a subset of default filters, you can
use `--without-default-filters` in conjunction with [exclusion filters](/docs/cli/references/files/fossa-yml#analysis-target-configuration). Refer to
[exclusion filters walkthough](/docs/cli/walkthroughs/analysis-target-configuration) for example on how to apply path and target exclusion filters.

### F.A.Q.

1. How can I only scan system dependencies?

You can provide `--only-system-deps`, like following to scan only system dependencies.

```bash
fossa container analyze <IMAGE> --only-system-deps
```

2. How can I improve performance of fossa container scanning?

You can use docker-archive source with FOSSA CLI. This will reduce
time required to retrieve container image from registry or from docker engine.

```bash
# save archive of the image
docker save redis:alpine > redis.tar

# scan and test the image
fossa container analyze redis.tar
fossa container test redis.tar
```

3. How can I exclude certain projects or targets from container image?

You can use [fossa configuration](/docs/cli/references/files/fossa-yml) file to exclude
specific directory or projects.

Refer to [target exclusion walk-through](/docs/cli/concepts/analysis-and-analyzers).

---

Source: https://docs.fossa.com/docs/cli/references/subcommands/init

# fossa init

## `fossa init`

The `fossa init` command creates _examples_ of the following files if they do not exist in the current working directory:

- [.fossa.yml](/docs/cli/references/files/fossa-yml): `fossa-cli` Configuration file
- [fossa-deps.yml](/docs/cli/references/files/fossa-deps): File for stubbing and manually providing dependencies

Note that both the `.fossa.yml` and `fossa-deps.yml` files are optional.
They allow for more specificity on how fossa-cli performs dependency analysis, but they are not required for `fossa-cli` usage.

---

Source: https://docs.fossa.com/docs/cli/references/subcommands/list-targets

# fossa list targets

## `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. `list-targets` can be also be used with [analysis target configuration](/docs/cli/references/files/fossa-yml#analysis-target-configuration) to limit what is ultimately analyzed.

### Command output

Example output
```bash
$ fossa list-targets
[ INFO] Found target: cabal@./
[ INFO] Found target: cocoapods@project/mobile/
[ INFO] Found target: setuptools@scripts/python/
[ INFO] Found target: yarn@./
```

This output tells us that when `fossa analyze` is run, we will be analyzing `cabal`, `cocoapods`, `pipenv`, and `yarn` projects. This can be useful to determine if there are targets you expect or don't expect to see.

#### Command output formats

The list-targets command supports the following formats (via `fossa list-targets --format=<OPTION>`):

- `legacy` (this is the default format, as shown above in the command output section)
- `text` (renders valid analysis targets per line, in the format of [`fossa analyze --only-target`](/docs/cli/references/subcommands/analyze#filtering-paths-and-targets) and [`fossa analyze --exclude-target`](/docs/cli/references/subcommands/analyze#filtering-paths-and-targets))
- `ndjson` (renders valid analysis targets in JSON format separated by line breaks)

### Utilizing [analysis target configuration](/docs/cli/references/files/fossa-yml#analysis-target-configuration)

Analysis target configuration through the fossa configuration file allows users to manually determine what they would like to analyze. Looking at the example above, if we know that the dependencies for the `setuptools@scripts/python/` target are not part of the production release, we can exclude it from the analysis. Example exclusion format:

```yaml
exclude:
  - type: setuptools
    path: scripts/python
```

Adding this section to your configuration file at the root of your project will ensure that when `fossa analyze` is run, the `setuptools` target is skipped.

### F.A.Q.

#### How can I ensure that my project is discoverable before running `fossa analyze` or `fossa test`?

In some scenarios, you may want to set up automation for projects that have been discovered. For example, you might want the process to fail if the project of interest isn't discovered by `fossa` before running `fossa analyze`.

First, execute `fossa list-targets --format=text` to see what `fossa` currently discovers:

```text
yarn@javascript/with-v2-yarn-workspaces/
yarn@javascript/with-v1-yarn/
npm@javascript/with-package-json/
npm@javascript/with-npm-package-lock/
npm@javascript/with-npm-lockfile-v3/
pnpm@javascript/pnpm/
```

From here, we assert that `fossa` finds the npm project at the directory `javascript/with-npm-package-lock/` before running `fossa analyze` using the following in CI:

```bash
if fossa list-targets --format=text | grep -q 'npm@javascript/with-npm-package-lock/' ; then
  fossa analyze && fossa test
else
  exit 1
fi
```

---

Source: https://docs.fossa.com/docs/cli/references/subcommands/project

# fossa project

## `fossa project`

This `fossa project` subcommand allows users to interact with FOSSA projects.

It has the following subcommand:

- [`fossa project edit`](/docs/cli/references/subcommands/project/edit)

See the pages linked above for more details.

### `fossa project edit`

Edits a FOSSA project's settings and configurations. 

Example:

```bash
fossa project edit --project-locator custom+1/example --title example-title --project-url github.com/fossas/fossa-cli --jira-project-key example-jira-key --link fossa.com --team example-team-1 --team example-team-2 --policy example-policy --project-label example-label-1 --project-label example-label-2 
```

### F.A.Q.

1. Where can I find my 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.

<img src="../../assets/project-locator-example.png">

---

Source: https://docs.fossa.com/docs/cli/references/subcommands/release-group

# fossa release-group

## `fossa release-group`

This `fossa release-group` subcommand allows users to interact with FOSSA release groups.

It has the following subcommands:

- [`fossa release-group add-projects`](/docs/cli/references/subcommands/release-group/add-projects)
- [`fossa release-group create`](/docs/cli/references/subcommands/release-group/create)
- [`fossa release-group create-release`](/docs/cli/references/subcommands/release-group/create-release)
- [`fossa release-group delete`](/docs/cli/references/subcommands/release-group/delete)
- [`fossa release-group delete-release`](/docs/cli/references/subcommands/release-group/delete-release)

See the pages linked above for more details.

>NOTE: For all subcommands that allow adding projects to releases, the combination of `--project-locator` , `--project-revision`, and `--project-branch` are required to identify the project that will be added to the release group. Multiple occurrences of these arguements are accepted and are grouped together based on their order. For example, `fossa release-group [create, create-release, add-projects] --title example-release-group --release example-release --project-locator custom+1/example --project-revision 1234 --project-branch main --project-locator custom+1/example2 --project-revision 5678 --project-branch main ` has project groupings of (project locator: custom+1/example, project revision: 1234, project branch: main) and (project locator: custom+1/example2, project revision: 5678, project branch: main).

### `fossa release-group add-projects`

Add FOSSA projects to a FOSSA release group

Example:

```bash
fossa release-group add-projects --title example-release-group --release example-release --project-locator custom+1/example --project-revision 1234 --project-branch main --project-locator custom+1/example2 --project-revision 5678 --project-branch main 
```

### `fossa release-group create`

Create a FOSSA release group

Example:

```bash
fossa release-group create --title example-release-group --release example-release --project-locator custom+1/example --project-revision 1234 --project-branch main --project-locator custom+1/example2 --project-revision 5678 --project-branch main --license-policy example-license-policy --security-policy example-security-policy --quality-policy example-quality-policy --team ExampleTeam --team ExampleTeam2
```

### `fossa release-group create-release`

Create a release within a FOSSA release group

Example:

```bash
fossa release-group create-release --title example-release-group --release example-release --project-locator custom+1/example --project-revision 1234 --project-branch main --project-locator custom+1/example2 --project-revision 5678 --project-branch main 
```

### `fossa release-group delete`

Delete a FOSSA release group

Example:

```bash
fossa release-group delete --title example-title
```

### `fossa release-group delete-release`

Delete a release within a FOSSA release group

Example:

```bash
fossa release-group delete-release --title example-title --release example-release-title 
```

### F.A.Q.

1. Why are `.fossa.yml` configurations disabled for `fossa release-group delete` and `fossa release-group delete-release`?

This is done intentionally so that lingering configurations in `.fossa.yml` are not extracted and used to mistakenly delete release groups or release group releases.

2. Where can I find my release groups? 

[Release groups](https://app.fossa.com/release-groups) can be found in the UI on the `Release Groups` page.

<img src="../../assets//release-group-title-example.png">

3. Where can I find my release group releases?

Releases can be found in the UI on the `Releases` page for your given release group.

<img src="../../assets//release-example.png">

4. Where can I find my project locator?

The project locator defines a unique ID that the FOSSA API will use to reference a project. 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">

5. Where can I find my project revision ID?

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">

---

Source: https://docs.fossa.com/docs/cli/references/subcommands/report

# fossa report

## `fossa report`

The report command downloads a report of the most-recent scan of your FOSSA project. This command is usually run immedately after `fossa analyze` or `fossa test`

The report type **must** be specified to successfully run, for example:

```sh
fossa report attribution
```

`fossa report` supports the [Common FOSSA Project Flags](#common-fossa-project-flags) supported by all commands.

### Report types

- `fossa report attribution` - A report that contains information about your dependencies and their authors. For more info about attributions, check the [FOSSA docs page illustrating the topic](https://docs.fossa.com/docs/generating-reports).

### Specifying a report timeout

By default, `fossa report` waits a maximum of 3600 seconds (1 hour) for report contents. To override the default timeout, use, e.g.:

```sh
fossa report attribution --timeout 60
```

Where `60` is the maximum number of seconds to wait for the report to be downloaded.

### Valid Report Targets

#### Project Directory

You can specify a project directly like you would with `fossa analyze` to generate a report.
For example:

```
fossa report attribution --format json ~/my-project
```

With no final path, FOSSA will try to fetch a report for the current directory's project.

#### SBOM Files

After using [`fossa sbom analyze`](/docs/cli/references/subcommands/sbom), you can specify an SBOM that you would like to generate a report for using its file:

```
fossa report attribution --format json ~/my-project-sbom.txt
```

#### Common FOSSA Project Flags

All `fossa` commands support the following FOSSA-project-related flags:

| Name                               | Short | Description                                                                                                                              |
|------------------------------------|-------|------------------------------------------------------------------------------------------------------------------------------------------|
| `--project 'some project'`         | `-p`  | Override the detected project name                                                                                                       |
| `--revision 'some revision'`       | `-r`  | -Override the detected project revision                                                                                                  |
| `--fossa-api-key 'my-api-key'`     |       | An alternative to using the `FOSSA_API_KEY` environment variable to specify a FOSSA API key                                              |
| `--endpoint 'https://example.com'` | `-e`  | Override the FOSSA API server base URL                                                                                                   |
| `--config /path/to/file`           | `-c`  | Path to a [configuration file](/docs/cli/references/files/fossa-yml) including filename. By default we look for `.fossa.yml` in base working directory. |

In this case, FOSSA will attempt to fetch any report it can find matching the `project` and `revision` criteria.

### Specifying a report format

`fossa report` supports customizing the format used to render a report via the `--format` flag.
Available options are:
- `csv`
- `cyclonedx-json`
- `cyclonedx-xml`
- `html`
- `json`
- `markdown`
- `spdx`
- `spdx-json`
- `text`

For example, to render the report in JSON format, use `fossa report attribution --format json`.

In earlier versions of the FOSSA CLI, the `--json` flag was used to denote rendering the report in JSON format.
For backwards compatibility, this flag is still supported and takes precedence over the `--format` flag if present.
However, it is deprecated, and should be replaced with `--format json` to prevent future changes from breaking this behavior.

### FOSSAv1 report compatibility

FOSSA supported a compatibility script that converts FOSSAv2 attribution report output to the same format as that in FOSSAv1.

This script was supported until the end of April 2022 and was included in the release assets, under the name `compat-attribution`.
After April 2022, it's no longer supported, but can still be found on older releases, for example https://github.com/fossas/fossa-cli/releases/tag/v3.2.12.

**We strongly recommend not trying to use this script, and instead migrating to the new report format.**

To use this compatibility script:

1. Download and extract `compat-attribution` for your platform to the same place as the `fossa` binary.
2. Run `fossa report attribution --format json`, piping its output to `compat-attribution`.
   For example, `fossa report attribution --format json | compat-attribution`
3. Parse the resulting output as you would have from FOSSAv1.

---

Source: https://docs.fossa.com/docs/cli/references/subcommands/sbom

# fossa sbom

The `fossa sbom` subcommand uploads SBOM files to FOSSA for analysis (`fossa sbom analyze`) and then tests to see if there were any issues raised from that analysis (`fossa sbom test`).

This feature is only available in a FOSSA Enterprise subscription. Contact [sales@fossa.com](mailto:sales@fossa.com) for more details.

FOSSA supports SPDX (JSON only) and CycloneDX (XML and JSON) SBOM files. For more information about the specific versions supported and required fields, see our [documentation on SBOM import via the web UI](https://docs.fossa.com/docs/sbom-import)

## `fossa sbom analyze <path to sbom file>`

`fossa sbom analyze <path to sbom file>` will upload the SBOM file to FOSSA and Analyze it. The name of the project will be the name of the SBOM file with extensions of ".xml" or ".json" removed. The revision will be derived from the current time. For example, if you run this command:

```
fossa sbom analyze /path/to/sampleCycloneDX.json
```

Then the project will be named "sampleCycloneDX" and the revision will be a timestamp based on the current time.

You can override the project name and revision using the `--project` and `--revision` flags, described below in [Common FOSSA Project Flags](#common-fossa-project-flags).

In addition to the [usual FOSSA project flags](#common-fossa-project-flags) supported by all commands, the `sbom analyze` command supports the following flags:


| Name                                  | Short | Description                                                                         |
| ------------------------------------- | ----- | ----------------------------------------------------------------------------------- |
| `--team 'team name'` | `-T` | Specify a team within your FOSSA organization. If you only have team-scoped permissions, you must specify a team of which you are a member. |
| `--force-rescan`  | | Force the SBOM file to be rescanned, even if this exact revision has been previously uploaded |

### Team Permissions

When using `fossa sbom analyze`, the command respects team-scoped permissions:
- If you have organization-wide permissions, you can upload SBOMs without specifying a team
- If you only have team-scoped permissions, you must use the `--team` flag to specify a team of which you are a member
- The behavior matches that of `fossa analyze --team`

## `fossa sbom test <path to sbom file>`

The `sbom test` command checks whether the most-recent scan of your FOSSA project raised license-policy or vulnerability issues. This command is usually run immediately after `fossa sbom analyze`.

While `fossa sbom analyze` uploads and processes an SBOM file, `fossa sbom test` verifies the analysis results against your organization's license and security policies. The key differences:

- `sbom analyze` - Uploads and scans an SBOM file, creating a build in FOSSA
- `sbom test` - Checks if that scan found any policy violations or security issues

The test command has the following behavior:
- If there are issues, it prints them to stderr and fails with an exit code of 1
- If there are no issues, it prints nothing and succeeds with an exit code of 0

These commands are typically used together in a workflow:
1. Run `fossa sbom analyze` to upload and analyze your SBOM
2. Run `fossa sbom test` to verify the analysis against your organization's policies

`fossa sbom test` supports the [Common FOSSA Project Flags](/docs/cli/references/subcommands/analyze#common-fossa-project-flags).

`fossa sbom test` also supports the [flags supported by `fossa test`](/docs/cli/references/subcommands/test).

## Common FOSSA Project Flags

`fossa sbom` commands support the following FOSSA-project-related flags:

| Name                               | Short | Description                                                                                                                                            |
| ---------------------------------- | ----- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `--project 'some project'`         | `-p`  | Override the detected project name                                                                                                                     |
| `--revision 'some revision'`       | `-r`  | -Override the detected project revision                                                                                                                |
| `--fossa-api-key 'my-api-key'`     |       | An alternative to using the `FOSSA_API_KEY` environment variable to specify a FOSSA API key                                                            |
| `--endpoint 'https://example.com'` | `-e`  | Override the FOSSA API server base URL                                                                                                                 |
| `--config /path/to/file`           | `-c`  | Path to a [configuration file](/docs/cli/references/files/fossa-yml) including filename. By default we look for `.fossa.yml` in base working directory. |

---

Source: https://docs.fossa.com/docs/cli/references/subcommands/test

# fossa test

## `fossa test`

The test command checks whether the most-recent scan of your FOSSA project raised license-policy or vulnerability issues. This command is usually run immediately after `fossa analyze`

- If there are issues, it prints them to stderr and fails with an exit code of 1
- If there are no issues, it prints nothing and succeeds with an exit code of 0

`fossa test` supports the [Common FOSSA Project Flags](/docs/cli/references/subcommands/analyze#common-fossa-project-flags) supported by all commands

### Specifying a timeout

By default, `fossa test` waits a maximum of 3600 seconds (1 hour) for issue scan results. To override the default timeout, use, e.g.:

```sh
fossa test --timeout 60
```

Where `60` is the maximum number of seconds to wait for issue scan results.

### Print issues as JSON

By default, `fossa test` displays issues in a human-readable format. To instead print issues as JSON, use:

```sh
fossa test --format json
```

### Test for new issues compared to another revision

`--diff <REVISION>` configures FOSSA to only report new issues observed with the current revision that weren't already reported on the specified `<REVISION>`.

```sh
fossa test --diff revisionToCompare
```

#### Example

```sh
fossa test --revision 34021e --diff v2.0.0
```

This only reports issues that are present in `34021e` revision,
BUT are not present in revision `v2.0.0`.

For instance, 

* If the revision `v2.0.0` has issue: `A`, and the revision `34021e` has issue `A`, 
  * `fossa-cli` reports no new issues discovered and exits with status code of 0.
  

* If the revision `v2.0.0` has issue: `A`, and the revision `34021e` has 0 issues, 
  * `fossa-cli` reports no new issues discovered and exits with status code of 0.


* If the revision `v2.0.0` has issue: `A`, and the revision `34021e` has issues `A`, `B`, 
  * `fossa-cli` reports issue `B` and exits with status code of 1.

---

Source: https://docs.fossa.com/docs/cli/references/subcommands/analyze/cli-options

# Fossa Analyze Additional Flag Options

This page is going to outline the optional flags that you can pass in when you are running `fossa analyze`:

| Flag | Description |
| :--- | :--- |
| `--debug` | Enable debug logging, and write detailed debug information to fossa.debug.json |
| `-e,--endpoint URL` | The FOSSA API server base URL (default [https://app.fossa.com](https://app.fossa.com)) |
| `-p,--project ARG` | this repository's URL or VCS endpoint (default: VCS remote 'origin') |
| `-r,--revision ARG` | this repository's current revision hash (default: VCS hash HEAD) |
| `--fossa-api-key ARG` | the FOSSA API server authentication key (default:FOSSA\_API\_KEY from env) |
| `-c,--config ARG` | Path to configuration file including filename (default: .fossa.yml) |
| `--with-telemetry-scope ARG` | Scope of telemetry to use, the options are 'full' or 'off'. (default: 'full') |
| `-o,--output` | Output results to stdout instead of uploading to fossa |
| `--unpack-archives` | Recursively unpack and analyze discovered archives |
| `--json` | Output project metadata as json to the console. Useful for communicating with the FOSSA API |
| `--include-unused-deps` | Include all deps found, instead of filtering non-production deps. Ignored by VSI. |
| `--debug-no-discovery-exclusion` | Ignore filters during discovery phase. This is for debugging only and may be removed without warning. |
| `--force-vendored-dependency-scan-method METHOD` | Force the vendored dependency scan method. The options are 'CLILicenseScan' or 'ArchiveUpload'. 'CLILicenseScan' is usually the default unless your organization has overridden this. |
| `--force-vendored-dependency-rescans` | Force vendored dependencies to be rescanned even if the revision has been previously analyzed by FOSSA. This currently only works for CLI-side license scans. |
| `-b,--branch ARG` | this repository's current branch (default: current VCS branch) |
| `-t,--title ARG` | the title of the FOSSA project. (default: the project name) |
| `-P,--project-url ARG` | this repository's home page |
| `-j,--jira-project-key ARG` | this repository's JIRA project key |
| `-L,--link ARG` | a link to attach to the current build |
| `-T,--team ARG` | this repository's team inside your organization |
| `--policy ARG` | the policy to assign to this project in FOSSA |
| `--release-group-name ARG` | the name of the release group to add this project to |
| `--release-group-release ARG` | the release of the release group to add this project to |
| `--only-target PATH` | Only scan these targets. See targets.only in the fossa.yml spec. |
| `--exclude-target PATH` | Exclude these targets from scanning. See targets.exclude in the fossa.yml spec. |
| `--only-path PATH` | Only scan these paths. See paths.only in the fossa.yml spec. |
| `--exclude-path PATH` | Exclude these paths from scanning. See paths.exclude in the fossa.yml spec. |
| `--x-vendetta` | Analyzes project files on disk to detect vendored open source libraries |
| `--experimental-enable-binary-discovery` | Reports binary files as unlicensed dependencies |
| `--experimental-link-project-binary DIR` | Links output binary files to this project in FOSSA |
| `--detect-dynamic BINARY` | Analyzes dynamically linked libraries in the target binary and reports them as dependencies |
| `--experimental-skip-vsi-graph LOCATOR` | Skip resolving the dependencies of the given project in FOSSA |
| `DIR` | Set the base directory for scanning (default: current directory) |
| `-h,--help` | Show this help text |
| `-V,--version` | show version information and exit (global option) |

---

Source: https://docs.fossa.com/docs/cli/references/subcommands/analyze/detect-dynamic

# Dynamic Linked Dependency Detection

## Dynamic Linked Dependency Detection

Some projects, especially C or C++ projects, result in binaries that dynamically link with system installed libaries.

### How does it work?

Dynamic Linked Dependency Detection works by using `ldd` to inspect target binaries for a list of linked libraries.
It then interacts with the local package manager (`rpm` for RedHat-based systems, `dpkg` for Debian-based systems) to determine the library which owns the binary.

If a library is found, it is reported to FOSSA, which uses our database of Linux packages to lookup licensing and vulnerability information for the package.
If a library is not found, the dependency is reported in FOSSA as an "unmanaged dynamically linked dependency". From there users may use the FOSSA UI to add a license or ignore the dependency.

### Prerequisites

Dynamic Linked Dependency Detection is supported on the following platforms:

* RedHat-based Linux systems (examples: RedHat, CentOS, Fedora)
* Debian-based Linux systems (examples: Debian, Ubuntu)

### Security

Dynamic Linked Dependency Detection is currently powered by `ldd`.

It is possible for a program to be built with its own loader which ignores the `LD_TRACE_LOADED_OBJECTS` variable used by `ldd`.
This could result in the binary being executed instead of being inspected.

For this reason, we strongly recommend against running Dynamic Linked Dependency Detection on an untrusted binary within a trusted environment.
If you are using Dynamic Linked Dependency Detection on your own binary, we recommend against running the feature on a binary with its own execution loader.

## How to use

`--detect-dynamic` supports scanning binaries directly, as well as scanning a directory recursively.

### Scanning a binary directly

When running `fossa analyze`, use the `--detect-dynamic <BINARY>` flag.
Point the `<BINARY>` at the binary that is built from the project.

As an example, if the project is located at `~/projects/my-project`,
and results in a binary at `~/projects/my-project/out/project`,
the scan invocation would be as follows:

```shell
fossa analyze ~/projects/my-project --detect-dynamic ~/projects/my-project/out/my-project-bin
```

This results in the FOSSA reporting both the dependencies discovered inside the project directory and the dependencies discovered by analyzing the binary.

### Scanning all binaries in a directory

When running `fossa analyze`, use the `--detect-dynamic <DIR>` flag.
Point the `<DIR>` at the directory containing binaries built from the project.

As an example, if the project is located at `~/projects/my-project`,
and results in binaries output in `~/projects/my-project/out/`,
the scan invocation would be as follows:

```shell
fossa analyze ~/projects/my-project --detect-dynamic ~/projects/my-project/out
```

This results in the FOSSA reporting both the dependencies discovered inside the project directory
and the dependencies discovered by analyzing any binaries in `~/projects/my-project/out` recursively.

#### Filters

When running against a directory, `--detect-dynamic` respects path filters provided to FOSSA CLI (via `.fossa.yml` or command line flags).

This uses the same mechanism as the CLI uses for determining projects to include in the report.

- To learn how path filters work, see [path filtering](https://github.com/fossas/fossa-cli/blob/master/docs/contributing/filtering.md#discovery-exclusion-by-path).
- To learn how to set path filters, see [configuring path filters](/docs/cli/references/files/fossa-yml#paths).

As an example, if the project is located at `~/projects/my-project`,
and results in binaries output in subdirectories of `~/projects/my-project/out/`,
but it should skip `~/projects/my-project/out/docs/`,
the scan invocation would be as follows:

```shell
fossa analyze ~/projects/my-project \
  --detect-dynamic ~/projects/my-project/out \
  --exclude-path ~/projects/my-project/out/docs/
```

This results in the FOSSA reporting both the dependencies discovered inside the project directory
and the dependencies discovered by analyzing any binaries in `~/projects/my-project/out` recursively,
skipping the `~/projects/my-project/out/docs` directory.

### Quick Example

As an example of this functionality, the analysis can run against a common system binary and an empty project directory.
For example, this invocation results in reporting only the dynamic dependencies for the `/bin/ls` system binary:

```shell
mkdir empty
fossa analyze empty --detect-dynamic /bin/ls
```

**Important:** It's possible to use this method to analyze arbitrary binaries. Keep the guidance in the [Security](#security) section in mind when using this feature.

---

Source: https://docs.fossa.com/docs/cli/references/subcommands/analyze/detect-vendored

# Vendored Source Identification

## Vendored Source Identification

Some projects, especially C or C++ projects, vendor open source libraries in directories adjacent to the first party code being developed in-house.
FOSSA's Vendored Source Identification is intended to support identifying and categorizing such vendored libraries.

### How does it work?

FOSSA fingerprints all files in your project and uploads those fingerprints to our analysis service.
The analysis service then uses a proprietary algorithm to compare those fingerprints with the fingerprints in our database of open source projects.

In the FOSSA CLI, this feature is called "VSI", for "vendored source identification".
VSI can be enabled with the `--detect-vendored` flag when running `fossa analyze`. For example:

```
fossa analyze --detect-vendored
```

### Default Filters

By default, VSI ignores the following directory:

- `{scandir}/.git`

### FAQ

#### Is there a limit to the number of scanned files?

This feature does not have a concrete limit, however at this time FOSSA considers projects that have more than 35,000 files "unsupported".
That being said, they may work.

> [!NOTE]
> Files are counted recursively, meaning that every archive contained in your project is unpacked and its contents are scanned,
> and each of those interior files count when talking about the 35,000 file supported limit.

If you find that this is a significant issue in your usage of this feature, we'd love to hear more about your use case.
Please consider dropping us a message through the [FOSSA Support page](https://support.fossa.com)!

#### Is my source code sent to FOSSA's servers?

VSI fingerprints your first party source code but does not send it to the server. Currently this is implemented with two SHA-256 hashes:
- A raw SHA-256 hash of the file content.
- For text files, a SHA-256 hash of the file content with lightweight comment and whitespace removal.

Additionally, the project file paths are uploaded to FOSSA; this is required for the statistical analysis to function properly.

The code to perform this is open source in this CLI; FOSSA can also provide a binary that displays the data FOSSA CLI uploads to the backend.

#### Why not always enable VSI?

VSI is more computationally intensive, and therefore takes longer to run.
For this reason, we recommend only enabling it when you are reasonably confident that you will obtain useful information by enabling it.

To explain, enabling VSI causes the CLI to:

1. Fingerprint all files in the project
2. Send those fingerprints to the FOSSA analysis service for vendored source identification
3. Wait for remote analysis to complete

This process has undergone a lot of optimization to improve its performance (and this is an area we’re continually investing in), but it will never be as fast as scanning local files for dependency information.

#### Manually specifying vendored source

Vendored dependencies can be manually specified in `fossa-deps.yml`.
For more information, see [`vendored-dependencies`](/docs/cli/features/vendored-dependencies) in `features`.

---

Source: https://docs.fossa.com/docs/cli/references/subcommands/container/podman

# Experimental Scanner - Podman

## Experimental Scanner - Podman

`fossa-cli` can use podman client to perform container image scanning analysis.

# Integration via Podman's Docker Compatible API

`fossa-cli` will look for environment variable `DOCKER_HOST`,
to infer docker engine api's socket location. As of now, `fossa-cli`
only works with `unix://` socket.

For podman, you can use `podman machine start` command, to retrieve
Docker client compatible `DOCKER_HOST`.

```bash
➜ podman machine start
Starting machine "podman-machine-default"
Waiting for VM ...
Mounting volume... /Users/fossa:/Users/fossa

This machine is currently configured in rootless mode. If your containers
require root permissions (e.g. ports < 1024), or if you run into compatibility
issues with non-podman clients, you can switch using the following command:

	podman machine set --rootful

API forwarding listening on: /Users/fossa/.local/share/containers/podman/machine/podman-machine-default/podman.sock

The system helper service is not installed; the default Docker API socket
address can\'t be used by podman. If you would like to install it run the
following commands:

	sudo /usr/local/Cellar/podman/4.2.0/bin/podman-mac-helper install
	podman machine stop; podman machine start

You can still connect Docker API clients by setting DOCKER_HOST using the
following command in your terminal session:

	export DOCKER_HOST='unix:///Users/fossa/.local/share/containers/podman/machine/podman-machine-default/podman.sock'

Machine "podman-machine-default" started successfully
```

Now we can specify `DOCKER_HOST` when running `fossa-cli`.

```bash
DOCKER_HOST='unix:///Users/fossa/.local/share/containers/podman/machine/podman-machine-default/podman.sock' fossa container analyze
```

Likewise, if you are using `podman-remote`, you should be able to use generate unix socket, and use it with `fossa-cli`. Refer to documentation below for more details.

Refer to documentation here:
- https://web.archive.org/web/20230405171636/https://podman.io/blogs/2020/07/01/rest-versioning.html
- https://docs.podman.io/en/latest/_static/api.html
- https://web.archive.org/web/20220926013308/https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux/8/html/building_running_and_managing_containers/assembly_using-the-container-tools-api_building-running-and-managing-containers

# Integration via Podman Executables

`fossa-cli` will perform the following command:

```bash
# check if image exists
podman image inspect <ARG>

# export said image to temporary location,
# and perform analysis on exported image.
podman save --format docker-archive -o <temp-path>
```
`fossa-cli` will look for `podman` executable in `$PATH`.

> Note this is same approach as integration via Docker Archive except that
> `fossa-cli` performs necessary invocation and does cleanup of artifacts.

# Integration via Docker Archive

We can manually export image using podman, and analyze such image
with `fossa-cli`.

```bash
podman build . -t someImg:1.0.0
podman save --format docker-archive -o image.tar

fossa container analyze image.tar

# Cleanup
rm image.tar
```

---

Source: https://docs.fossa.com/docs/cli/references/subcommands/container/scanner

# FOSSA's container scanner

- [FOSSA's container scanner](#fossas-container-scanner)
  - [What's supported in FOSSA's container scanner?](#whats-supported-in-fossas-container-scanner)
- [Documentation](#documentation)
  - [Container image source](#container-image-source)
    - [1) Exported docker archive](#1-exported-docker-archive)
    - [2) From Docker Engine](#2-from-docker-engine)
    - [3) From registries](#3-from-registries)
  - [Container image analysis](#container-image-analysis)
    - [Container JAR analysis](#container-jar-analysis)
    - [Distroless Containers](#distroless-containers)
    - [Supported Container Package Managers](#supported-container-package-managers)
    - [View detected projects](#view-detected-projects)
      - [Command output](#command-output)
    - [Utilize analysis target configuration](#utilize-analysis-target-configuration)
    - [Debugging](#debugging)
    - [Frequently Asked Questions (FAQs)](#frequently-asked-questions-faqs)
      - [How do I scan multi-platform container images with `fossa-cli`?](#how-do-i-scan-multi-platform-container-images-with-fossa-cli)
    - [How can I only scan for system dependencies (alpine, dpkg, rpm)?](#how-can-i-only-scan-for-system-dependencies-alpine-dpkg-rpm)
    - [How do I exclude specific projects from container scanning?](#how-do-i-exclude-specific-projects-from-container-scanning)
  - [Limitations \& Workarounds](#limitations-workarounds)

## What's supported in FOSSA's container scanner?

FOSSA's container scanner adds support for compliance and vulnerability checks for application dependencies inside of containers.
The performance of analysis and support for container image sources is improved, and is more robust for future enhancement.

FOSSA's container scanner brings support for standard FOSSA CLI features into containers:
- Support for configuration via `.fossa.yml`.
- Support for path filtering (exclusion and inclusion).

The container scanner fully supports the detection of OS dependencies (`apk`, `deb`, etc).

Refer to following guides for integrating container scanning in your CI,

- [Walthrough: Integrating in Generic CI](/docs/cli/walkthroughs/container-scanning-generic-ci)

# Documentation

FOSSA's container scanner scans the base layer of the image, squashes all other layers, and scans those as well.
Scans report compliance and security issues for operating system dependencies and application dependencies.

To scan a container image with `fossa-cli`, use the `container analyze` command:

```bash
# Analyze the container image `<IMAGE>` with container scanner and upload scan results to FOSSA.
# This command only reports dependency metadata, no source code or actual file is sent to FOSSA.
#
# This command uses the repository name as project name, and image digest as the revision.
# Like standard FOSSA analysis, the project name is customizable via `--project` and revision via `--revision`:
#
#   >> fossa container analyze <IMAGE> --project <PROJECT-NAME> --revision <REVISION-VALUE>
#
fossa container analyze <IMAGE>

# Similar to the above, but instead of uploading the results they are instead written to the terminal in JSON format.
#
fossa container analyze <IMAGE> -o
```

Once the container image has been scanned and the results uploaded to FOSSA,
security and compliance issues are reported via the `fossa container test` command.

```bash
# Run FOSSA security and compliance checks on the container metadata.
# Like the standard `fossa test` command, `fossa container test` exits with a non-zero exit code if issues are detected.
#
# Container issue scanning works with standard FOSSA policies just like any other project.
# Policies are also able to surface or suppress issues based on the layer in which the issue was detected.
# Refer to FOSSA's product documentation for more information: https://docs.fossa.com
fossa container test <IMAGE>
```

## Container image source

FOSSA can analyze container images from multiple sources:
- Exported archive
- Docker engine
- Podman
- OCI container registry (public and private)
- Docker Hub

By default `fossa-cli` attempts to identify `<IMAGE>` source in the following order:

### 1) Exported docker archive

```bash
docker save redis:alpine > redis_alpine.tar
fossa container analyze redis_alpine.tar
```

### 2) From Docker Engine

```bash
fossa container analyze redis:alpine
```

For this image source to work, `fossa-cli` requires docker to be running and accessible.
Specifically, `fossa-cli` uses the Unix socket at `/var/lib/docker.sock`, with `http://localhost/v1.28/` as a base API endpoint.

1) `/_ping`: check connection to docker
2)  `images/<IMAGE>/json`: retrieve image manifest
3) `images/<IMAGE>/get`: retrieve image archive

In summary, `fossa-cli` performs the equivalent of:

```bash
curl --unix-socket /var/run/docker.sock -X GET "http://localhost/v1.28/_ping"
curl --unix-socket /var/run/docker.sock -X GET "http://localhost/v1.28/images/redis:alpine/json"
curl --unix-socket /var/run/docker.sock -X GET "http://localhost/v1.28/images/redis:alpine/get" > tmp/fossa-cli-docker-engine-artifact-<random-number>/img.tar
```

`fossa-cli` stores this archive in a temporary location and analyzes that archive.

### 3) From registries

```bash
fossa container analyze ghcr.io/fossas/haskell-dev-tools:9.0.2
```

This step works even if you do not have docker installed or have docker engine accessible.

If `<IMAGE>` is not a docker image archive and is not accessible via the docker engine API,
`fossa-cli` attempts to retrieve the image via registries based on the content of `<IMAGE>`.

`<IMAGE>` is parsed in a similar fashion to `docker pull <ARG>`:

| `<IMAGE>`                                         | Registry                             | Repository                 | Manifest Reference             |
| ------------------------------------------------- | ------------------------------------ | -------------------------- | ------------------------------ |
| `redis`                                           | None (defaults to `index.docker.io`) | `library/redis`            | None (defaults to `latest`)    |
| `redis:alpine`                                    | None (defaults to `index.docker.io`) | `library/redis`            | `alpine` (as tag)              |
| `bitnami/wordpress:6.0.1-debian-11-r14`           | None (defaults to `index.docker.io`) | `bitnami/wordpress`        | `6.0.1-debian-11-r14` (as tag) |
| `ghcr.io/fossas/haskell-dev-tools:9.0.2`          | `ghcr.io`                            | `fossas/haskell-dev-tools` | `9.0.2` (as tag)               |
| `ghcr.io/fossas/haskell-dev-tools@sha256:e83e...` | `ghcr.io`                            | `fossas/haskell-dev-tools` | `sha256:e83e...` (as digest)   |
| `quay.io/org/image:tag`                           | `quay.io`                            | `org/image`                | `tag`                          |

Note:
- When the domain is not present, `fossa-cli` defaults to the registry `index.docker.io`.
- When digest or tag is not present, `fossa-cli` defaults to the tag `latest`.
- When the registry is `index.docker.io`, and repository does not contain the literal `/`, `fossa-cli` infers that this is official image stored under `library/<image>`.
- When a multi-platform image is provided (e.g. `ghcr.io/graalvm/graalvm-ce:ol7-java11-21.3.3`), `fossa-cli` defaults to selecting image artifacts for current runtime platform.

Analyzing the container image for a platform other than the one currently running is possible by specifying the digest for the image on a different platform.

For example, the following command analyzes the `arm64` platform image of `ghcr.io/graalvm/graalvm-ce@sha256` regardless of the platform running `fossa container analyze`:

```bash
fossa container analyze ghcr.io/graalvm/graalvm-ce@sha256:bdcba07acb11053fea0026b807ecf94550ace7df27b10596ca4c765165243cef
```

**Private registries**

`fossa-cli` automatically infers credentials based on the host name and Docker credential store.

This is done in following steps:

1) Identify the host of image source (e.g. `quay.io` for `quay.io/org/image:tag`)
2) Parse Docker config file: `$HOME/.docker/config.json` or `%USERPROFILE%/.docker/config.json`
3) If there is an associated credential helper specified in `credHelpers` it is used. Otherwise, the default helper `credsStore` is used.
4) `fossa-cli` executes `docker-credential-<store>`, similar to following command to retrieve credentials:

```bash
>> echo "index.docker.io" | docker-credential-desktop get
{
  "ServerURL": "https://index.docker.io",
  "Username": "username",
  "Secret": "secret"
}
```

If any of the steps above fail, `fossa-cli` defaults to connecting without user credentials.

To explicitly provide a username and password, use HTTP-style authentication in the image URL.
For this to work the host value must be present in the image URL:

```bash
fossa container analyze user:secret@quay.io/org/image:tag
```

**Retrieving image from registry**

`fossa-cli` uses `/v2/` registry api (per OCI distribution spec) for retrieving
image manifests, and image artifacts from registry. It does so in following manner:

1) `HEAD <repository>/manifests/<tag-or-digest>` (to see if the manifests exists)
   1) If 401 status code is provided, and auth challenge is presented, `fossa-cli` will make request to token provider with mentioned scope and service (if username and password were provided for registry, HTTP auth will be used) to retrieve token.
2) Use token from step (1) to make `GET /v2/<repository>/manifests/<tag-or-digest>` to retrieve manifest
   1) If multi-platform image is detected (content-type indicating manifest index, or manifest list), manifest for current runtime's digest will be identified
   2) Using (2.a)'s digest value, `GET /v2/<repository>/manifests/<digest>` will be used to infer platform specific manifest
3) Identify configuration blob and layer blobs digests from (2)
4) Download all blobs using `GET /v2/<repository>/blobs/<digest>` (if blobs are tar.gzip, they will be gzip extracted)
5) From artifacts downloaded representative image tarball will be created.

All `GET` request from step 2 to step 5, will make a `HEAD` call prior to confirm existence of resource. If
401 status is received new access token will be generated using auth flow mentioned in step (1).

## Container image analysis

The container scanner scans in two steps:
1. The base layer.
2. The rest of the layers, squashed.

### Container JAR analysis

The container analyzer will try to find Java Archive (Jar) files inside each layer.
It will then report them to FOSSA which will try to match the Jar files to the project they are a build artifact from.

The container analyzer will also expand each Jar file that it encounters and report any Jar files that it finds in the expanded Jar file. This is done recursively.

This process relies on there being a back-end that can perform that analysis.
SaaS customers should have this functionality available but on-prem customers may need to contact FOSSA support to have it enabled.

### Distroless Containers

Container images where FOSSA cannot detect an operating system are supported but in a more limited way than images where FOSSA can.
These container images will not support reporting system deps (APK, DPKG, and RPM) but can support the other forms of analyses listed in the table below.

### Supported Container Package Managers
The following package managers are supported in container scanning:

| Analysis                             | Supported?         | Docs                                                             |
| ------------------------------------ | ------------------ | ---------------------------------------------------------------- |
| Alpine (APK)                         | :white_check_mark: | [APK Docs](/docs/project-setup/supported-languages/system/apk)                 |
| Debian (DPKG)                        | :white_check_mark: | [DPKG Docs](/docs/project-setup/supported-languages/system/dpkg)              |
| RedHat (RPM)                         | :warning:          | [RPM Docs](/docs/project-setup/supported-languages/system/rpm)         |
| Python (setuptools, poetry, etc.)    | :white_check_mark: | [Python Docs](/docs/project-setup/supported-languages/python)     |
| Javascript (npm, yarn, pnpm, etc.)   | :white_check_mark: | [Javascript Docs](/docs/project-setup/supported-languages/nodejs) |
| Ruby (bundler)                       | :white_check_mark: | [Ruby](/docs/project-setup/supported-languages/ruby)                |
| .Net (paket, projectjson, etc.)     | :white_check_mark: | [.Net](/docs/project-setup/supported-languages/dotnet)            |
| Perl                                 | :white_check_mark: | [Perl](/docs/project-setup/supported-languages/perl)                |
| Swift (xcode, swift package manager) | :white_check_mark: | [Swift](/docs/project-setup/supported-languages/ios/swift)               |
| Carthage                             | :white_check_mark: | [Carthage](/docs/project-setup/supported-languages/ios/carthage)         |
| Fortran (fpm)                        | :white_check_mark: | [Fortran](/docs/project-setup/supported-languages/fortran)       |
| R (renv)                             | :white_check_mark: | [Fortran](/docs/project-setup/supported-languages/r/renv)                |
| Cocoapods                            | :warning:          | [CocoaPods](/docs/project-setup/supported-languages/ios/cocoapods)       |
| Nim (nimble)                         | :warning:          | [Nim](/docs/project-setup/supported-languages/nim/nimble)                |
| Dart (pub)                           | :warning:          | [Dart](/docs/project-setup/supported-languages/dart/pub)                 |
| Maven                                | :warning:          | [Maven](/docs/project-setup/supported-languages/maven)             |
| Java Jar Files                       | :white_check_mark: | [Container Jar Analysis](#container-jar-analysis)               |
| Golang (gomod)                       | :x:                | N/A                                                              |
| Rust (cargo)                         | :x:                | N/A                                                              |
| Haskell (cabal, stack)               | :x:                | N/A                                                              |
| Gradle                               | :x:                | N/A                                                              |
| Clojure (lein)                       | :x:                | N/A                                                              |
| Scala (sbt)                          | :x:                | N/A                                                              |
| Elixir                               | :x:                | N/A                                                              |
| Erlang                               | :x:                | N/A                                                              |

Where:
- :white_check_mark: - analysis is supported
- :warning: - partial analysis is supported. Refer to the linked strategy documentation for more details.
- :x: - analysis is not supported in container scanning.

### View detected projects

To view the list of projects detected within the container by the above strategies run `fossa container list-targets <ARG> `.
`ARG` must be the same value as provided to `fossa container analyze <ARG> ` or `fossa container test <ARG>`.

This output can be useful to understand what is going to be analyzed via `fossa container analyze <ARG> `,
and if desired can inform [analysis target configuration](/docs/cli/references/files/fossa-yml#analysis-target-configuration).

#### Command output

Example output:
```bash
; fossa container list-targets ghcr.io/tcort/markdown-link-check:stable

[ INFO] Discovered image for: ghcr.io/tcort/markdown-link-check:stable (of 137610196 bytes) via docker engine api.
[ INFO] Exporting docker image to temp file: /private/var/folders/hb/pg5d0r196kq1qdswr6_79hzh0000gn/T/fossa-docker-engine-tmp-f7af2b5d1ec5173d/image.tar! This may take a while!
[ INFO] Listing targets exported docker archive: /private/var/folders/hb/pg5d0r196kq1qdswr6_79hzh0000gn/T/fossa-docker-engine-tmp-f7af2b5d1ec5173d/image.tar
[ WARN] fossa container list-targets does not apply any filtering, you may see projects which are not present in the final analysis.
[ WARN] fossa container list-targets only lists targets for experimental-scanner (when analyzed with flag).
[ INFO] Found project: apkdb@lib/apk/db/ (Base Layer)
[ INFO] Found target: apkdb@lib/apk/db/ (Base Layer)
[ INFO] Found project: setuptools@usr/local/lib/node_modules/npm/node_modules/node-gyp/gyp/ (Other Layers)
[ INFO] Found target: setuptools@usr/local/lib/node_modules/npm/node_modules/node-gyp/gyp/ (Other Layers)
[ INFO] Found project: npm@src/ (Other Layers)
[ INFO] Found project: npm@opt/yarn-v1.22.5/ (Other Layers)
[ INFO] Found target: npm@src/ (Other Layers)
[ INFO] Found target: npm@opt/yarn-v1.22.5/ (Other Layers)
[ INFO] Found project: apkdb@lib/apk/db/ (Other Layers)
[ INFO] Found target: apkdb@lib/apk/db/ (Other Layers)
```

### Utilize analysis target configuration

The container scanner supports configuring analysis targets via `.fossa.yml`, as with a standard `fossa analyze` command.
For more information on configuring analysis targets, see [analysis target configuration](/docs/cli/references/files/fossa-yml#analysis-target-configuration).

For example, the following `fossa.yml` excludes all `setuptools` targets:
```yaml
exclude:
  - type: setuptools
```

### Debugging

`fossa-cli` supports the `--debug` flag and debug bundle generation with the container scanner.

```bash
fossa container analyze redis:alpine --debug

# Generates debug logs in the terminal.
# Writes the FOSSA debug bundle in the current working directory with the filename "fossa.container.debug.json.gz".
```

For best performance prefer analyzing exported docker archive file instead of downloading image from registry.
When building in CI, consider saving the image as an artifact and using that for analysis.
This improves performance by being able to skip downloading and extracting the image from a registry.

Images can be exported to archives using Docker:

```bash
docker pull <IMAGE>:<TAG> # or docker pull <IMAGE>@<DIGEST>
docker save <IMAGE>:<TAG> > image.tar

fossa container analyze image.tar

rm image.tar
```

### Frequently Asked Questions (FAQs)

#### How do I scan multi-platform container images with `fossa-cli`?

By default when `fossa-cli` is analyzing multi-platform image it prefers using the same runtime architecture as the host.
If a specific platform is desired, use the digest for that platform:

```bash
fossa container analyze ghcr.io/graalvm/graalvm-ce@sha256:bdcba07acb11053fea0026b807ecf94550ace7df27b10596ca4c765165243cef
```

### How can I only scan for system dependencies (alpine, dpkg, rpm)?

Use the `--only-system-deps` option:

```bash
fossa container analyze <IMAGE> --only-system-deps
```

### How do I exclude specific projects from container scanning?

Use a FOSSA configuration file to perform exclusion of projects or paths.
Refer to the [configuration file](/docs/cli/references/files/fossa-yml) documentation for more details.

As an example, the following configuration file only analyzes `setuptools`, and `alpine` packages:

```yml
# filename: .fossa.yaml
version: 3

targets:
  only:
    - type: setuptools
    - type: apkdb
```

```bash
fossa container analyze <IMAGE> -c .fossa.config.yaml --output
```

## Limitations & Workarounds

`fossa-cli` does not support [v1 docker manifest format](https://docs.docker.com/registry/spec/manifest-v2-1/).
This manifest format is officially deprecated, but is still found in some registries.

The recommended workaround is to export the image to an archive, then analyze that:

```bash
docker pull quay.io/org/image:tag
docker save quay.io/org/image:tag > img.tar

fossa container analyze img.tar
rm img.tar
```

For guidance migrating off of the deprecated format, refer to Docker's [migration guide](https://docs.docker.com/registry/spec/deprecated-schema-v1/).

---

Source: https://docs.fossa.com/docs/cli/references/subcommands/project/edit

# fossa project edit

## `fossa project edit`

`fossa project edit` allows you to edit a FOSSA project's settings and configuration.

## Options

Argument                     | Required | Description
-----------------------------|----------|--------------------------------------------------------------------------------------------------------------------------------------
`--config` / `-c`            | No       | The to your path to your `.fossa.yml`.
`--project-locator`          | Yes      | 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`               | Yes      | 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`. Project ID defaults to the .git/config file or project's remote "origin" URL (Git), "Repository Root" obtained using 'svn info' (SVN), or the name of the project's directory (No VCS), if project ID wasn't explicityly set during project creation.
`--title` / `-t`             | No       | The title of the FOSSA project.
`--project-url`              | No       | The url of the project's repository.
`--jira-project-key` / `-j`  | No       | The JIRA project key to associate to the FOSSA project.
`--link` / `-L`              | No       | A link to attach to the FOSSA project. 
`--team` / `T`               | No       | The name of the team that will be associated with the FOSSA project. Specify multiple options by providing this argument multiple times.
`--project-label`            | No       | The labels associated with the FOSSA project. Assign up to 5 labels for a project. Specify multiple options by providing this argument multiple times.

> NOTE: The arguments listed as `Required` need to be provided through CLI options OR through your `.fossa.yml` configuration.

> NOTE: Either project ID OR project locator needs to be set. Project ID takes precedence over project locator. For more details on the differences between project ID and project locator refer to [documentation](/docs/cli/references/files/fossa-yml#what-is-the-difference-between-project-id-and-project-locator).

## .fossa.yml Configuration

All of the previously mentioned CLI options can be provided through a `.fossa.yml`. Refer to [fossa configuration](/docs/cli/references/files/fossa-yml) to set up your `.fossa.yml`.

> NOTE: CLI options take precedence over the configurations in `.fossa.yml`. 

## `fossa project edit` usage and guidance

### Updating a project's labels 

When updating project labels through `fossa project edit`, the transaction is all or nothing. This means that the project labels specified through this command will overwrite the existing labels that are associated with the project. Be sure to include all the labels that you want to be associated with the project, even if some labels are already currently set. 

### Updating the teams associated with a project

Currently, `fossa project edit` only supports adding a project to the teams that are specified through the command. There will be support to remove a project from the provided teams in the future. 

Providing teams for `fossa project edit` takes the following precdence:

1. CLI options - Adds the project to teams (1 or many)
2. `project.teams` in `.fossa.yml` - Adds the project to teams (1 or many)
3. `project.team` in `.fossa.yml` - Adds the project to a team 

There is support for `project.team` due to backwards compatibility as `project.teams` is a newly added field in `.fossa.yml`. 

## Example

### Project locator example
Given a project with project locator: `custom+1/example`, the following command:

- Sets the project's title to `example-title`
- Set the the project's url to `github.com/fossas/fossa-cli`
- Sets the project's JIRA key to `example-jira-key`
- Attaches link: `fossa.com` to the project
- Adds the project to teams: `example-team-1`, `example-team-2`
- Attaches policy: `example-policy` to the project
- Attaches labels: `example-label-1` , `example-label-2` to the project

```bash
fossa project edit --project-locator custom+1/example --title example-title --project-url github.com/fossas/fossa-cli --jira-project-key example-jira-key --link fossa.com --team example-team --team example-team-2 --policy example-policy --project-label example-label-1 --project-label example-label-2 
``` 

Similarly, you can you achieve the same result by running the following command with the given `.fossa.yml` configuration: 

```bash
fossa project edit --config /path/to/config
``` 

```yaml
project:
  locator: custom+1/example
  name: example-title
  teams: 
    - example-team-1
    - example-team-2
  policy: example-policy
  link: fossa.com
  url: github.com/fossas/fossa-cli
  jiraProjectKey: example-jira-key
  labels:
    - example-label-1
    - example-label-2
```

### Project ID example
Achieve the same result as defined above (for projects created through the CLI) using project ID:

```bash
fossa project edit --project-id example --title example-title --project-url github.com/fossas/fossa-cli --jira-project-key example-jira-key --link fossa.com --team example-team --team example-team-2 --policy example-policy --project-label example-label-1 --project-label example-label-2 
``` 

Similarly, you can you achieve the same result by running the following command with the given `.fossa.yml` configuration: 

```bash
fossa project edit --config /path/to/config
``` 

```yaml
project:
  id: example
  name: example-title
  teams: 
    - example-team-1
    - example-team-2
  policy: example-policy
  link: fossa.com
  url: github.com/fossas/fossa-cli
  jiraProjectKey: example-jira-key
  labels:
    - example-label-1
    - example-label-2
```

---

Source: https://docs.fossa.com/docs/cli/references/subcommands/release-group/add-projects

# fossa release-group add-projects

## `fossa release-group add-projects`

`fossa release-group add-projects` allows you to add FOSSA projects to a FOSSA release group.

## Options

Argument              | Required | Description
----------------------|----------|--------------------------------------------------------------------------------------------------------------------------------------
`--config` / `-c`     | No       | The to your path to your `.fossa.yml`.
`--title` / `-t `     | Yes      | The name of your FOSSA release group.
`--release` / `-r `   | Yes      | The name of your release within your FOSSA release group.
`--project-locator`   | Yes      | The FOSSA project locator defines a unique ID that the FOSSA API will use to reference this project. The project locator can be found in the UI on the project `Settings` page listed as the `Project Locator` underneath the `Project Title` setting. Specify multiple options by providing this argument multiple times.
`--project-revision`  | Yes      | The revision associated with your FOSSA 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. Specify multiple options by providing this argument multiple times.
`--project-branch`    | Yes      | The name of the FOSSA project branch. Specify multiple options by providing this argument multiple times.

> NOTE: The arguments listed as `Required` need to be provided through CLI options OR through your `.fossa.yml` configuration.

## .fossa.yml Configuration

Refer to [fossa configuration](/docs/cli/references/files/fossa-yml) to set up your `.fossa.yml`.

> NOTE: CLI options take precedence over the configurations in `.fossa.yml`.

> NOTE: Project ID values will not work if provided to `releaseGroupProjects.projectLocator`. For more details on the differences between project ID and project locator refer to [documentation](/docs/cli/references/files/fossa-yml#what-is-the-difference-between-project-id-and-project-locator).

## Example

```bash
fossa release-group add-projects --title example-release-group --release example-release --project-locator custom+1/example --project-revision 1234 --project-branch main --project-locator custom+1/example2 --project-revision 5678 --project-branch main 
``` 

>NOTE: `--project-locator` , `--project-revision`, and `--project-branch` must all be specified when providing a releaseGroupProject. Multiple occurrences of these arguements are accepted and are grouped together based on their order. For example, `fossa release-group add-projects --title example-release-group --release example-release --project-locator custom+1/example --project-revision 1234 --project-branch main --project-locator custom+1/example2 --project-revision 5678 --project-branch main` has project groupings of (project locator: custom+1/example, project revision: 1234, project branch: main) and (project locator: custom+1/example2, project revision: 5678, project branch: main).

Similarly, you can you achieve the same result by running the following command with the given `.fossa.yml` configuration:

```yaml
releaseGroup:
  title: example-release-group
  release: example-release
  releaseGroupProjects:
    - projectLocator: custom+1/example
      projectRevision: 1234
      projectBranch: main 
    - projectLocator: custom+1/example2
      projectRevision: 5678
      projectBranch: main
```

```bash
fossa release-group add-projects -c path/to/config
```

---

Source: https://docs.fossa.com/docs/cli/references/subcommands/release-group/create-release

# fossa release-group create-release

## `fossa release-group create-release`

`fossa release-group create-release` allows you to create a FOSSA release group release.

## Options

Argument              | Required | Description
----------------------|----------|--------------------------------------------------------------------------------------------------------------------------------------
`--config` / `-c`     | No       | The to your path to your `.fossa.yml`.
`--title` / `-t `     | Yes      | The name of your FOSSA release group.
`--release` / `-r `   | Yes      | The name of your release within your FOSSA release group.
`--project-locator`   | Yes      | The FOSSA project locator defines a unique ID that the FOSSA API will use to reference this project. The project locator can be found in the UI on the project `Settings` page listed as the `Project Locator` underneath the `Project Title` setting. Specify multiple options by providing this argument multiple times.
`--project-revision`  | Yes      | The revision associated with your FOSSA 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. Specify multiple options by providing this argument multiple times.
`--project-branch`    | Yes      | The name of the FOSSA project branch. Specify multiple options by providing this argument multiple times.

> NOTE: The arguments listed as `Required` need to be provided through CLI options OR through your `.fossa.yml` configuration.

## .fossa.yml Configuration

Refer to [fossa configuration](/docs/cli/references/files/fossa-yml) to set up your `.fossa.yml`.

> NOTE: CLI options take precedence over the configurations in `.fossa.yml`.

> NOTE: Project ID values will not work if provided to `releaseGroupProjects.projectLocator`. For more details on the differences between project ID and project locator refer to [documentation](/docs/cli/references/files/fossa-yml#what-is-the-difference-between-project-id-and-project-locator).

## Example

```bash
fossa release-group create-release --title example-release-group --release example-release --project-locator custom+1/example --project-revision 1234 --project-branch main --project-locator custom+1/example2 --project-revision 5678 --project-branch main 
``` 
>NOTE: `--project-locator` , `--project-revision`, and `--project-branch` must all be specified when providing a releaseGroupProject. Multiple occurrences of these arguements are accepted and are grouped together based on their order. For example, `fossa release-group create-release --title example-release-group --release example-release --project-locator custom+1/example --project-revision 1234 --project-branch main --project-locator custom+1/example2 --project-revision 5678 --project-branch main` has project groupings of (project locator: custom+1/example, project revision: 1234, project branch: main) and (project locator: custom+1/example2, project revision: 5678, project branch: main).

Similarly, you can you achieve the same result by running the following command with the given `.fossa.yml` configuration:

```yaml
releaseGroup:
  title: example-release-group
  release: example-release
  releaseGroupProjects:
    - projectLocator: custom+1/example
      projectRevision: 1234
      projectBranch: main 
    - projectLocator: custom+1/example2
      projectRevision: 5678
      projectBranch: main
```

```bash
fossa release-group create-release -c path/to/config
```

---

Source: https://docs.fossa.com/docs/cli/references/subcommands/release-group/create

# fossa release-group create

## `fossa release-group create`

`fossa release-group create` allows you to create a FOSSA release group.

## Options

Argument                  | Required | Description
--------------------------|----------|--------------------------------------------------------------------------------------------------------------------------------------
`--config` / `-c`         | No       | The to your path to your `.fossa.yml`.
`--title` / `-t`          | Yes      | The name of the FOSSA release group.
`--release` / `-r`        | Yes      | The name of the release within your FOSSA release group.
`--project-locator`       | Yes      | The FOSSA project locator defines a unique ID that the FOSSA API will use to reference this project. The project locator can be found in the UI on the project `Settings` page listed as the `Project Locator` underneath the `Project Title` setting. Specify multiple options by providing this argument multiple times.
`--project-revision`      | Yes      | The revision associated with your FOSSA 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. Specify multiple options by providing this argument multiple times.
`--project-branch`        | Yes      | The name of the FOSSA project branch. Specify multiple options by providing this argument multiple times.
`--license-policy` / `l`  | No       | The name of the license policy to assign to the FOSSA release group. 
`--security-policy` / `s` | No       | The name of the security policy to assign to the FOSSA release group. 
`--quality-policy` / `q`  | No       | The name of the quality policy to assign to the FOSSA release group.
`--team` / `T`            | No       | The name of team that will be associated with the FOSSA release group. Specify multiple options by providing this argument multiple times.

> NOTE: The arguments listed as `Required` need to be provided through CLI options OR through your `.fossa.yml` configuration.

## .fossa.yml Configuration

Refer to [fossa configuration](/docs/cli/references/files/fossa-yml) to set up your `.fossa.yml`.

> NOTE: CLI options take precedence over the configurations in `.fossa.yml`.

> NOTE: Project ID values will not work if provided to `releaseGroupProjects.projectLocator`. For more details on the differences between project ID and project locator refer to [documentation](/docs/cli/references/files/fossa-yml#what-is-the-difference-between-project-id-and-project-locator).

## Example

```bash
fossa release-group create --title example-release-group --release example-release --project-locator custom+1/example --project-revision 1234 --project-branch main --project-locator custom+1/example2 --project-revision 5678 --project-branch main --license-policy example-license-policy --security-policy example-security-policy --quality-policy example-quality-policy --team ExampleTeam --team ExampleTeam2
``` 

>NOTE: `--project-locator` , `--project-revision`, and `--project-branch` must all be specified when providing a releaseGroupProject. Multiple occurrences of these arguements are accepted and are grouped together based on their order. For example, `fossa release-group create --title example-release-group --release example-release --project-locator custom+1/example --project-revision 1234 --project-branch main --project-locator custom+1/example2 --project-revision 5678  --project-branch main` has project groupings of (project locator: custom+1/example, project revision: 1234, project branch: main) and (project locator: custom+1/example2, project revision: 5678, project branch: main).

Similarly, you can you achieve the same result by running the following command with the given `.fossa.yml` configuration:

```yaml
releaseGroup:
  title: example-release-group
  release: example-release
  releaseGroupProjects:
    - projectLocator: custom+1/example
      projectRevision: 1234
      projectBranch: main 
    - projectLocator: custom+1/example2
      projectRevision: 5678
      projectBranch: main
  licensePolicy: example-license-policy
  securityPolicy: example-security-policy
  qualityPolicy: example-quality-policy
  teams:
    - ExampleTeam
    - ExampleTeam2
```

```bash
fossa release-group create -c path/to/config
```

---

Source: https://docs.fossa.com/docs/cli/references/subcommands/release-group/delete-release

# fossa release-group delete-release

## `fossa release-group delete-release`

`fossa release-group delete-release` allows you to delete a FOSSA release group release.

## Options

Argument              | Required | Description
----------------------|----------|--------------------------------------------------------------------------------------------------------------------------------------
`--title`   / `-t `   | Yes      | The name of your FOSSA release group.
`--release` / `-r`    | Yes      | The name of the release within your FOSSA release group.

> NOTE: `fossa release-group delete-release` does not use `.fossa.yml` configurations.

## Usage

```bash
fossa release-group delete-release --title example-title --release example-release 
```

---

Source: https://docs.fossa.com/docs/cli/references/subcommands/release-group/delete

# fossa release-group delete

## `fossa release-group delete`

`fossa release-group delete` allows you to delete a FOSSA release group.

## Options

Argument              | Required | Description
----------------------|----------|--------------------------------------------------------------------------------------------------------------------------------------
`--title` / `-t `     | Yes      | The name of your FOSSA release group.

> NOTE: `fossa release-group delete` does not use `.fossa.yml` configurations.

## Usage

```bash
fossa release-group delete --title example-title
```

---

Source: https://docs.fossa.com/docs/cli/telemetry

# FOSSA CLI Telemetry

### FOSSA CLI Telemetry

FOSSA CLI collects anonymous feature usage information, observed errors and warnings, 
and performance diagnostic information to help improve the experience for everyone. 
	
Getting a better understanding of usage patterns, the impact of exceptions, 
and crash reports, helps our team to better prioritize work and 
ultimately deliver a better user experience. 

### What data is collected in CLI telemetry?

CLI telemetry collects the following data: 

- Fatal and non-fatal errors and warnings
- Configurations, and command-line arguments used
- Anonymous system information (operating system, and architecture)
- Feature usage data

CLI telemetry does not collect personally identifiable information or metadata about source code.

### How is CLI telemetry data collected and processed?

CLI telemetry data is collected at the provided endpoint in configuration (with --endpoint). 
CLI telemetry data is validated and processed for our logging system.

### How can I inspect CLI telemetry data?

You can view collected CLI telemetry data by running cli with environment variable `FOSSA_TELEMETRY_DEBUG=1`, with scope of `FOSSA_TELEMETRY_SCOPE=full`. 
This will generate `fossa.telemetry.json` file in your current working directory, and will not send any telemetry data to server.

```bash
FOSSA_TELEMETRY_DEBUG=1 FOSSA_TELEMETRY_SCOPE=full fossa analyze sandbox
```

### How can I disable CLI telemetry?

You can disable telemetry with any of the following options, 

(1) Setting environment variable

```
$ FOSSA_TELEMETRY_SCOPE=off fossa analyze
```

(2) Using command line flag

```
$ fossa analyze --with-telemetry-scope=off
```

(3) Using the configuration file: 

```
# .fossa.yml
version: 3

telemetry:
    scope: off
```

Also, we do not collect telemetry when `--output` is used with analyze command.

### I’m an on-prem customer, what telemetry data is collected by FOSSA?

CLI sends telemetry data to the endpoint specified in the FOSSA CLI command. 
We never receive telemetry data collected from your endpoint. 

You can inspect collected telemetry data on your endpoint from your on-prem FOSSA database instance.

---

Source: https://docs.fossa.com/docs/cli/differences-from-v1

# Differences from FOSSA 1.x to 3.x

Upgrading from FOSSA CLI 1.x to 3.x is a major breaking change. For most users, this change should be seamless. For users who use less common flags, or who have heavily customized their CLI usage, you may need to update some scripts.

## Table of contents 

- [Differences from FOSSA 1.x to 3.x](#differences-from-fossa-1x-to-3x)
  - [What's new in FOSSA 3.x?](#whats-new-in-fossa-3x)
    - [New Build Manager Supports](#new-build-manager-supports)
    - [Automatic analysis target discovery](#automatic-analysis-target-discovery)
    - [New fossa-deps configuration support](#new-fossa-deps-configuration-support)
    - [Improved correctness](#improved-correctness)
    - [Improved debug logging](#improved-debug-logging)
    - ["Modules" are now "analysis targets"](#modules-are-now-analysis-targets)
  - [Breaking changes in FOSSA 3.x](#breaking-changes-in-fossa-3x)
    - [Build Managers](#build-managers)
    - [CLI commands](#cli-commands)
    - [Language Specific Changes](#language-specific-changes)
      - [Gradle](#gradle)
      - [Clojure](#clojure)
      - [Go](#go)
      - [Haskell](#haskell)
      - [Maven](#maven)
      - [Nodejs](#nodejs)
      - [Nuget](#nuget)
      - [Cocoapods](#cocoapods)
      - [Carthage](#carthage)
      - [Composer](#composer)
      - [Python](#python)
      - [Gem](#gem)
      - [Cargo](#cargo)
      - [Sbt](#sbt)
  - [How to upgrade to FOSSA 3.x](#how-to-upgrade-to-fossa-3x)
    - [Remove calls to `fossa init`](#remove-calls-to-fossa-init)
    - [Migrate your .fossa.yml file](#migrate-your-fossayml-file)
    - [Migrate "archive upload" targets](#migrate-archive-upload-targets)
    - [Getting help with your migration](#getting-help-with-your-migration)
    - [Migrate "fossa report" commands](#migrate-fossa-report-commands)
  - [Frequently Asked Questions](#frequently-asked-questions)
      - [Until when CLI v1 will be supported by FOSSA?](#until-when-cli-v1-will-be-supported-by-fossa)
      - [I'm getting a poor result with latest version compared 1.x.](#im-getting-a-poor-result-with-latest-version-compared-1x)
      - [How do I run only a specific analyzer for my project?](#how-do-i-run-only-a-specific-analyzer-for-my-project)
      - [How do I identify which version of CLI I have installed?](#how-do-i-identify-which-version-of-cli-i-have-installed)
      - [I'm running into an error - how do I debug?](#im-running-into-an-error-how-do-i-debug)
      - [What's the difference between FOSSA CLI 1.x, 2.x, and 3.x?](#whats-the-difference-between-fossa-cli-1x-2x-and-3x)

## What's new in FOSSA 3.x?

Our focus in CLI 3.x is making FOSSA integrations easier to deploy by reducing the amount of configuration needed by users. Our goal is to get as close to turnkey deployment on as many build systems and codebases as possible.

### New Build Manager Supports

FOSSA 3.x supports following new build managers and languages:

- [Swift Package Manager (for swift)](/docs/project-setup/supported-languages/ios/swift)
- [Pub (for flutter and dart)](/docs/project-setup/supported-languages/dart)
- [Poetry (for Python)](/docs/project-setup/supported-languages/python)
- [Mix (for Elixir)](/docs/project-setup/supported-languages/elixir)
- [Fortran Package Manager (for Fortran)](/docs/project-setup/supported-languages/fortran)
- [Nim (Nimble)](/docs/project-setup/supported-languages/nim/nimble)
- [Pnpm (for javascript)](/docs/project-setup/supported-languages/nodejs/pnpm)

### Automatic analysis target discovery

FOSSA CLI 3.x now does automatic analysis target discovery when you run `fossa analyze`. This means that `fossa init` is no longer required. `fossa init` is now a no-op that emits a warning, and will be removed in a future release.

In 1.x, modules could be manually configured with "strategies" that specified _how_ a module should be analyzed. While `fossa init` attempted to choose the best strategy, manual intervention was sometimes required depending on the project's setup.

In 3.x, the CLI now automatically selects the optimal strategy for analysis targets given the current environment (e.g. whether a build tool is available). This is possible because discovery and analysis are now one step, so we can check the suitability of analysis strategies while discovering targets.

### New fossa-deps configuration support

With [`fossa-deps.{yml,json}` file](/docs/cli/features/manual-dependencies), 3.x supports:

- License scanning vendor dependencies

- Analyzing archives that are located at a specific web address (e.g. https://my-deps-source/v1.zip)
- Manually specifying dependency by it's name and license (e.g. my-custom-dep with MIT license)
- Manually specifying dependency for analysis by its name and dependency type (e.g. pip dependency: request)

This is very useful when working with a package manager that is not supported, or when you have a custom and nonstandard dependency management solution. The FOSSA CLI will automatically read a fossa-deps.yml or a fossa-deps.json file in the root directory (usually the current working directory) when fossa analyze is run and parse dependencies from it. These dependencies will be added to the dependencies that are normally found when fossa analysis is run in the directory.

Please refer to [fossa-deps](/docs/cli/features/manual-dependencies) documentation for more details.

### Improved correctness

Analysis strategies in CLI 3.x have substantive improvements in correctness and reliability across all language integrations. 3.x has much stronger compile-time correctness guarantees in its parsers, and uses build tool plugins instead of output parsing for target types where output parsing was brittle.

### Improved debug logging

CLI 3.x has much better debug logging, including a new feature called "replay logging" which allows developers to perfectly reproduce a bug report given a replay log. This is made possible by stronger compile-time guarantees that ensure all effects that occur during analysis are logged for replay.
### "Modules" are now "analysis targets"

In 1.x, the CLI was configured by "modules", which were entrypoints to user programs that the CLI should analyze. In 3.x, we've renamed "modules" to "analysis targets", and simplified how analysis targets are defined. We renamed analysis targets to avoid confusing naming conflicts with existing language-specific "modules". Analysis targets are no longer defined by multiple, confusingly similar fields (e.g. "Dir" vs. "Path"), and are now simple `(type, target)` tuples.

## Breaking changes in FOSSA 3.x

### Build Managers

FOSSA 3.x does not support following build managers:

- Bazel
- Debian
- Ant
- Bower
- Okbuck
- Buck

For these managers, you can write a custom integration by creating `fossa-deps.{yml,json}` file which is more representative of your project's dependencies usage.

### CLI commands

Following CLI commands are not supported with 3.x:

- `fossa analyze --server-scan`
- `fossa analyze --dev`
- `fossa analyze --options`
- `fossa test --suppress-issues`
- `fossa upload` (this is supplemented by `fossa-deps.{yml,json}` file now, refer to "Migrate archive upload targets" section)
- `fossa report licences` (supplemented by `fossa report attribution --format json`)
- `fossa report dependencies`

### Language Specific Changes

#### Gradle
- 3.x uses a new plugin-based strategy to perform discovery and analysis, it analyses all resolvable Gradle configurations.
- 3.x does not accept any options: `cmd`, `task`, `timeout`, `all-configurations`, `configuration`, `retries`, `online`, `all-submodules`, and any other option supported in 1.x for Gradle analysis.
- In 3.x,
   - There is no timeout (analysis may run for a long time)
   - All resolvable configurations are analyzed
   - There are no retries (CLI will attempt to analyze the project once)
   - Specific command and Gradle tasks can not be used in the analysis
   - `$FOSSA_GRADLE_COMMAND` environment variable cannot be configured. 3.x uses Gradle executable in `$PATH`.
- Refer to [FOSSA 3.x gradle docs](/docs/project-setup/supported-languages/gradle) for more information for gradle.

#### Clojure
- 3.x performs the `lein deps :tree` strategy by default.
- 3.x does not support any options - `strategy`, and `lien` for Clojure analysis.
- Refer to [FOSSA 3.x clojure docs](/docs/project-setup/supported-languages/clojure) for more information on how 3.x performs analysis for clojure.

#### Go
- 3.x supports analysis of the Go project for projects using gomod, godeps, and glide.
- 3.x does not support following options: `tags`, `all-tags,` `strategy`, `lockfile`, `manifest`, `modules-vendor`, `allow-unresolved`, `allow-unresolved-prefix`, `allow-nested-vendor`, `allow-deep-vendor`, `allow-external-vendor`, `allow-external-vendor-prefix`.
- Refer to [FOSSA 3.x Go docs](/docs/project-setup/supported-languages/golang) for more information on how 3.x performs analysis for Go.

#### Haskell
- 3.x will apply stack strategy when a project is discovered having stack.yaml file
- 3.x will apply cabal-install strategy for projects using cabal.project or file with .cabal extension
- 3.x does not support `strategy` option for Haskell analysis
- Refer to [FOSSA 3.x haskell docs](/docs/project-setup/supported-languages/haskell) for more information on how 3.x performs analysis for haskell.

#### Maven
- 3.x uses `mvn` command for analysis. `mvn` must be accessible in $PATH
- 3.x does not support any option: `strategy`, `cmd`, or `bin` for Maven analysis
- Refer to [FOSSA 3.x maven docs](/docs/project-setup/supported-languages/maven) for more information on how 3.x performs analysis for maven.

#### Nodejs
- 3.x supports `yarn`, `npm`, and `package.json` for analysis.
- 3.x does not support the `strategy` option for Nodejs analysis. v2.x automatically selects the application strategy which yields the highest fidelity of dependency information.
- Refer to [FOSSA 3.x nodejs docs](/docs/project-setup/supported-languages/nodejs/npm) for more information on how 3.x performs analysis for nodejs.

#### Nuget
- 3.x does not support the `strategy` option for Nuget analysis. v2.x automatically selects the application strategy which yields the highest fidelity of dependency information.
- Refer to [FOSSA 3.x nuget docs](/docs/project-setup/supported-languages/dotnet) for more information on how 3.x performs analysis for nuget.

#### Cocoapods
- Refer to [FOSSA 3.x cocoapods docs](/docs/project-setup/supported-languages/ios/cocoapods) for more information on how 3.x performs analysis for cocoapods.

#### Carthage
- Refer to [FOSSA 3.x carthage docs](/docs/project-setup/supported-languages/ios/carthage) for more information on how 3.x performs analysis for carthage.

#### Composer
- Refer to [FOSSA 3.x composer docs](/docs/project-setup/supported-languages/php/composer) for more information on how 3.x performs analysis for composer.

#### Python
- 3.x automatically selects the application strategy which yields the highest fidelity of dependency information.
- 3.x uses attempts to infer requirements.txt for any file with prefix `req` in its name, and `txt` extension.
- 3.x does not support the `strategy` or `requirement` option for Python analysis.
- Refer to [FOSSA 3.x python docs](/docs/project-setup/supported-languages/python) for more information on how 3.x performs analysis for python.

#### Gem
- 3.x attempts to use the `bundle show` command (`bundle` must be accessible from `$PATH`), and if it fails, it attempts to analyze dependencies from `Gemfile.lock` file.
- 3.x does not support `strategy` or `gemfile-lock-path` option for Gem Analysis.
- Refer to [FOSSA 3.x gem docs](/docs/project-setup/supported-languages/ruby) for more information on how 3.x performs analysis for gem.

#### Cargo
- Refer to [FOSSA 3.x cargo docs](/docs/project-setup/supported-languages/rust) for more information on how 3.x performs analysis for cargo.

#### Sbt
- 3.x requires `sbt` executable to be accessible from `$PATH`
- 3.x does not require a project to have a `net.virtual-void.sbt-dependency-graph` extension installed.
- Refer to [FOSSA 3.x scala docs](/docs/project-setup/supported-languages/scala/sbt) for more information on how 3.x performs analysis for sbt.

## How to upgrade to FOSSA 3.x

### Remove calls to `fossa init`

Since analysis targets are now automatically discovered during analysis, `fossa init` is no longer a valid command. `fossa init` is currently a no-op that emits a warning. It may be removed in a future release.

### Migrate your .fossa.yml file

We've made major breaking changes in the `.fossa.yml` file format for CLI 3.x to improve clarity. You'll need to migrate your 1.x `.fossa.yml` to the new 3.x format for their configurations to apply. `.fossa.yml` for 1.x will be ignored when running cli with version greater than 1.x. We determine whether a configuration file is compatible by examining its `version` field.

- .fossa.yml with version field value of `1` and `2` are for 1.x.
- .fossa.yml with version field value of `3` are for 3.x, and 2.x.

For documentation on the new configuration file format, see [here](/docs/cli/references/files/fossa-yml)

### Migrate "archive upload" targets

In 1.x, ["archive upload" modules](https://github.com/fossas/fossa-cli/blob/v1-master/docs/integrations/archive.md#archive) were a special kind of manually specified module of type `archive` that uploaded source code to the FOSSA backend for license scanning. They were also known as "raw" modules or "license scan" modules.

In 3.x, archive uploads are no longer a special analysis target type. Instead, you can use our general support for [manually specified dependencies](/docs/cli/features/manual-dependencies) to specify local dependencies.

### Getting help with your migration

If you run into migration issues, you can get support by opening a ticket in this repository.

If you are integrating a private project and want to share more details, or if you're a FOSSA customer with priority support, you can you can file a ticket at [support.fossa.com](https://support.fossa.com) for assistance.

### Migrate "fossa report" commands

In 1.x, `fossa report` supported `fossa report dependencies`, `fossa report licenses` and `fossa report attribution`.

In 3.x, only `fossa report attribution` is supported. The information in the previously supported v1 commands is contained in the output from `attribution`.
This command also now requires a `--format` argument: see [fossa report attribution](/docs/cli/references/subcommands/report#specifying-a-report-format) for details.

The format for this report has also changed slightly. Until the end of April 2022, FOSSA supported a compatibilty script to convert the format of the report.
For more information, including usage information, see [FOSSAv1 report compatibility](/docs/cli/references/subcommands/report#fossav1-report-compatibility) in the user guide.

## Frequently Asked Questions

#### Until when CLI v1 will be supported by FOSSA?

FOSSA 1.x CLI is available and can be used indefinitely. We intend to make 3.x the default target for our installation scripts (as previously described in our documentation) in July 2022. If you wish to continue using 1.x, please migrate to using `install-v1` scripts.

FOSSA will only patch 1.x for security fixes. Any feature and patch development work will occur in 3.x moving forth.

#### I'm getting a poor result with latest version compared 1.x.

If you run into poor dependency results with 3.x, you can get support by opening a ticket in this repository.

If you are integrating a private project and want to share more details, or if you're a FOSSA customer with priority support, you can file a ticket at [support.fossa.com](https://support.fossa.com) for assistance.

#### How do I run only a specific analyzer for my project?

You can configure to run specific analyzer or only analyze specific paths in `.fossa.yml` file. Please refer to documentation [here](/docs/cli/references/files/fossa-yml)

#### How do I identify which version of CLI I have installed?

You can identify your cli version by performing `fossa --version` command.

#### I'm running into an error - how do I debug?

You can add a `--debug` argument to your fossa commands (e.g. `fossa analyze --debug`), this will emit debug logs to stdout, and create a file called `fossa.debug.zip` in the working directory that contains a debug bundle (fossa.debug.json).

#### What's the difference between FOSSA CLI 1.x, 2.x, and 3.x?

1.x version, is first major release of fossa cli sourced at [fossas/fossa-cli](https://github.com/fossas/fossa-cli/).

2.x version, is the second major release of fossa CLI sourced at [fossas/spectrometer](https://github.com/fossas/spectrometer/). This release was not a default target of the installation script, provided on fossa's website.

3.x version, is third major releases. With this release:
  - 3.x becomes default target for installation script provided at [fossas/spectrometer](https://github.com/fossas/spectrometer/)
  - 3.x becomes default target for install-latest script provided at [fossas/fossa-cli](https://github.com/fossas/spectrometer/)
  - We migrates 2.x source code from [fossas/spectrometer](https://github.com/fossas/spectrometer/) to [fossas/fossa-cli](https://github.com/fossas/fossa-cli/) and releases it as 3.x.
  - Archives [fossas/spectrometer] source code repository.

3.x will be released on November 12, 2021.

> Note: There are no breaking changes from 2.x to 3.x. The 3.x version in functional sense, continuation of 2.x version. The 3.x version was released to (1) match the `version` field of the fossa configuration file with the major release version of cli, (2) mark migration of CLI 2.x source code back into the fossa-cli repository, and (3) mark 3.x now the default target for installation for all fossa users moving forwards.


If you were previously using the installation script provided at [fossas/spectrometer](https://github.com/fossas/spectrometer/), it is now recommended to use the installation latest script provided at [fossas/fossa-cli](https://github.com/fossas/fossa-cli/).

---

Source: https://docs.fossa.com/docs/api

# API Reference

The FOSSA REST API lets you query and manage your FOSSA data programmatically (projects, revisions, issues, vulnerabilities, release groups, and reports) so you can automate workflows from CI/CD or custom tooling.

**[Browse the Endpoint Reference →](/docs/api/reference)**


## What you can do with the API

- Automate tasks in your CI/CD pipeline.
- Query and manage your dependencies, projects, and revisions.
- Generate custom documents and reports.
- Build custom features and integrations on top of FOSSA data.

## Start here

- **[Introduction](/docs/api/introduction)**: generate an API key and make your first request.
- **[Authentication](/docs/api/authentication)**: how to authenticate and the two token types.
- **[Errors](/docs/api/errors)**: how to interpret API error responses.

## Guides and reference

- **[Usage examples](/docs/api/examples)**: practical recipes: managing issues, users, teams, reports, Jira tickets, and more.
- **[Endpoint Reference](/docs/api/reference)**: the complete, interactive endpoint catalog.

---

Source: https://docs.fossa.com/docs/api/introduction

# Introduction to the FOSSA API

The FOSSA API is a RESTful API for programmatic access to your FOSSA data. This guide walks you from generating an API key to making your first authenticated request.

{% callout type="info" %}
All API requests are made over HTTPS to `https://app.fossa.com/api`.
{% /callout %}

## Making your first request

{% steps %}
{% step title="Generate an API key" %}
In the FOSSA dashboard, go to **Account Settings → Integrations → API** and create a new token. See [Authentication](/docs/api/authentication) for the difference between Push-Only and Full tokens; most API calls require a **Full** token.
{% /step %}
{% step title="Authenticate your request" %}
Pass your token in the `Authorization` header, prefixed with `Bearer`:

```
Authorization: Bearer YOUR_API_KEY
```
{% /step %}
{% step title="Call an endpoint" %}
Send a `GET` request to `/api/v2/projects` to list the projects in your organization.
{% /step %}
{% /steps %}

## Common requests

### Listing all projects

```bash
curl --request GET \
  --url 'https://app.fossa.com/api/v2/projects' \
  --header 'Authorization: Bearer YOUR_API_KEY'
```

Use `page` and `count` to paginate, and `title` to filter by name.

### Listing the revisions of a project

Once you have a project locator, retrieve its revisions:

```bash
curl --request GET \
  --url 'https://app.fossa.com/api/revisions?projectId=<project-locator>' \
  --header 'Authorization: Bearer YOUR_API_KEY'
```

{% callout type="info" %}
Project and revision locators contain characters such as `+`, `/`, and `$` that must be URL-encoded when used in a path or query string (for example, `custom+1234/example` becomes `custom%2B1234%2Fexample`).
{% /callout %}

## Next steps

- [Authentication](/docs/api/authentication): token types and security best practices.
- [Managing issues](/docs/api/examples/managing-issues): query and filter issues programmatically.
- [Usage examples](/docs/api/examples): end-to-end recipes for common tasks.
- [Endpoint Reference](/docs/api/reference): every endpoint, parameter, and response.

---

Source: https://docs.fossa.com/docs/api/authentication

# Authentication

Every FOSSA API call requires an API token (also called an API key). You can create and manage tokens in the FOSSA dashboard under **Account Settings → Integrations → API**, or see [API Tokens](/docs/organization-management/api-tokens) for details.

{% callout type="warning" %}
API tokens carry the same privileges as the account that created them. Never commit a token to source control, embed it in client-side code, or share it in a publicly accessible location.
{% /callout %}

## Authenticating a request

Provide your token in the `Authorization` header, prefixed with `Bearer`:

```
Authorization: Bearer YOUR_API_KEY
```

For example:

```bash
curl --request GET \
  --url 'https://app.fossa.com/api/organizations' \
  --header 'Authorization: Bearer YOUR_API_KEY'
```

{% callout type="info" %}
All API requests must be made over HTTPS. Requests over plain HTTP are rejected.
{% /callout %}

## Token types

| Token type | Description |
| --- | --- |
| **Push-Only** | A limited-access token used by the CLI and CI integrations to push analysis results. It cannot be used for most read APIs. |
| **Full** | A user-level token with the same access as the account it belongs to. Required for most API endpoints and management tasks. |

For guidance on creating dedicated service accounts and rotating tokens safely, see [Rotating access tokens](/docs/api/examples/rotating-access-tokens).

---

Source: https://docs.fossa.com/docs/api/errors

# Errors

The FOSSA API uses conventional HTTP response codes to indicate the success or failure of a request.

| Status range | Meaning | What to do |
| --- | --- | --- |
| `2xx` | Success | The request succeeded. |
| `4xx` | Client error | Something about the request was wrong, for example, a missing API token or an omitted required parameter. Check your request and try again. |
| `5xx` | Server error | An error occurred on FOSSA's servers. Retry later, and contact support if it persists. |

For the full list of HTTP status codes, see [List of HTTP status codes](https://en.wikipedia.org/wiki/List_of_HTTP_status_codes).

{% callout type="info" %}
If you receive an unexpected error, contact [support@fossa.com](mailto:support@fossa.com) with the endpoint, request, and response you received.
{% /callout %}

---

Source: https://docs.fossa.com/docs/api/webhook-notifications

# Webhook Notifications

FOSSA supports two ways to keep projects automatically up to date: **scheduled hooks**, which re-analyze projects on a recurring interval, and **webhook hooks**, which let an external system trigger a re-analysis on demand.

Both are configured under **Settings → Projects → Hooks** at the organization level.

## Scheduled hooks

Scheduled hooks tell FOSSA to automatically re-analyze all projects in your organization on a recurring basis.

| Field | Description |
|---|---|
| **Enabled** | Turns on scheduled re-analysis by default for all new projects |
| **Interval** | How often to re-analyze: `hour`, `day`, or `week` |
| **Interval length** | How many intervals between re-analyses (e.g. `2` days) |
| **Time** | Time of day to run the update (e.g. `3:30pm`) |

Once enabled, new projects will have scheduled re-analysis turned on by default using the configured interval and time. Existing projects are not affected retroactively; their hook settings must be updated individually.

## Webhook hooks

Webhook hooks let an external system (such as a CI pipeline or a package registry) trigger a FOSSA re-analysis for a specific project by sending a POST request to that project's webhook URL.

Each project has a unique webhook URL:

```
https://app.fossa.com/hooks/webhook/{project-locator}
```

To trigger a re-analysis:

```shell
curl -X POST "https://app.fossa.com/hooks/webhook/{project-locator}"
```

Replace `{project-locator}` with the URL-encoded locator for your project, for example, `sbom%2B58760%2Fmy-project`.

{% callout type="info" %}
Calling the webhook URL returns a `404 NoActiveUpdateHooksError` if no active webhook hook is configured for that project. Enable it per project under **Project Settings → Settings → Hooks**.
{% /callout %}

{% callout type="warning" %}
If the webhook call cannot be processed (for example, because the project is not eligible for re-analysis), FOSSA automatically disables the hook and records the error. Check the hook status in project settings if calls stop being processed.
{% /callout %}

### Supported project types

Webhook hooks are supported for VCS-managed projects. They are not supported for fully provided (non-VCS) projects.

---

Source: https://docs.fossa.com/docs/api/cpe-lookup

# CPE Lookup API

The FOSSA Analysis Service exposes a public API at `https://analysis.fossa.com` that lets you look up security metadata and vulnerabilities for any software component using its CPE (Common Platform Enumeration) identifier. No project scan or FOSSA account is required to use these endpoints.

This is useful for:

- Checking whether a specific package version has known CVEs before importing it
- Integrating FOSSA's vulnerability data into external tooling or pipelines
- Investigating vulnerabilities for components outside a FOSSA project

## What is a CPE?

A **CPE (Common Platform Enumeration)** is a standardized identifier for software products defined by the CPE v2.3 specification. It uses a structured string format with 11 fields separated by colons:

```
cpe:2.3:{part}:{vendor}:{product}:{version}:{update}:{edition}:{language}:{sw_edition}:{target_sw}:{target_hw}:{other}
```

Examples:

```
cpe:2.3:a:microsoft:internet_explorer:8.0.6001:beta:*:*:*:*:*:*
cpe:2.3:a:hp:openview_network_manager:7.51:*:*:*:*:linux:*:*
cpe:2.3:a:apache:log4j:2.14.1:*:*:*:*:*:*:*
```

Use `*` (asterisk) to match any value in a field. All 11 fields must be present.

## Exploring the API interactively

The homepage at [analysis.fossa.com](https://analysis.fossa.com) offers two built-in viewers for exploring and testing the API without writing any code:

- **RapiDoc Viewer**: a clean, dark-themed interface for browsing endpoints, filling in parameters, and executing requests directly from the browser. Recommended for most users.
- **Swagger UI**: the standard OpenAPI explorer, useful if you're already familiar with Swagger tooling.

To try the CPE lookup endpoints:

1. Go to [analysis.fossa.com](https://analysis.fossa.com) and select **RapiDoc Viewer**.
2. Find the **Security** section in the left sidebar and select **Search for security metadata by CPE**.
3. Enter a CPE string in the `search` field and optionally enable `reverse-wildcard`.
4. Click **Try** to run the request and see the live response inline.

{% img src="/images/cpe-lookup-search.png" alt="RapiDoc Viewer showing a CPE search for cpe:2.3:a:microsoft:internet_explorer:8.0.6001:beta with reverse-wildcard enabled and the JSON response below" /%}

## Endpoints

### Search for security metadata by CPE

Returns full security metadata (CVE IDs, CVSS scores, EPSS scores, CWEs, affected packages, and more) for all vulnerabilities matching the CPE.

```
GET https://analysis.fossa.com/api/v1/cpe/match/{search}
```

| Parameter | Type | Required | Description |
|---|---|---|---|
| `search` | path | Yes | A CPE v2.3 formatted string, or a JSON array of up to 20 CPE strings for batch search |
| `reverse-wildcard` | query | No | Set to `true` to enable reverse wildcard matching (see below) |

**Example:**

```shell
curl -X GET "https://analysis.fossa.com/api/v1/cpe/match/cpe%3A2.3%3Aa%3Aapache%3Alog4j%3A2.14.1%3A*%3A*%3A*%3A*%3A*%3A*%3A*?reverse-wildcard=true" \
  -H 'accept: application/json'
```

**Response fields:**

| Field | Type | Description |
|---|---|---|
| `id` | string | Unique vulnerability identifier (e.g. `CVE-2021-44228`) |
| `description` | string | Detailed description of the vulnerability |
| `cpes` | string[] | CPEs explicitly recorded in the dataset that matched your search |
| `matches` | object[] | Packages explicitly recorded as affected |
| `cvss_v2_vector` | string \| null | CVSS v2 vector string |
| `cvss_v3_vector` | string \| null | CVSS v3 vector string |
| `cvss_v4_vector` | string \| null | CVSS v4 vector string |
| `epss` | number \| null | EPSS score (0–1): probability of exploitation in the next 30 days |
| `epss_percentile` | number \| null | EPSS percentile rank (0–1) |
| `cwes` | string[] | Associated CWE identifiers |
| `references` | string[] | Reference URLs from the upstream source |
| `published` | datetime | When the entry was publicly published |
| `updated` | datetime | When the entry was last updated |
| `status` | object | Status of the entry according to the data source |
| `review` | object | FOSSA's internal review status for the entry |
| `exploitability` | string \| null | Exploitability information |
| `known_ransomware_campaign_use` | string \| null | Known ransomware campaigns using this vulnerability |

---

### Search for vulnerability IDs only by CPE

Returns only the list of vulnerability IDs (e.g. CVE identifiers) matching the CPE, lighter weight than the full metadata endpoint.

```
GET https://analysis.fossa.com/api/v1/cpe/match/{search}/id
```

| Parameter | Type | Required | Description |
|---|---|---|---|
| `search` | path | Yes | A CPE v2.3 formatted string, or a JSON array of up to 20 CPE strings |
| `reverse-wildcard` | query | No | Set to `true` to enable reverse wildcard matching |

**Example:**

```shell
curl -X GET "https://analysis.fossa.com/api/v1/cpe/match/cpe%3A2.3%3Aa%3Aapache%3Alog4j%3A2.14.1%3A*%3A*%3A*%3A*%3A*%3A*%3A*/id?reverse-wildcard=true" \
  -H 'accept: application/json'
```

**Response:** an array of vulnerability ID strings.

```json
["CVE-2021-44228", "CVE-2021-45046"]
```

To get full details for a specific vulnerability, use `/api/v1/vulns/lookup/{id}`.

---

### Search for vulnerabilities by CPE (compatibility mode)

A compatibility endpoint for clients previously using `vulns.fossa.com/api/vulns/cpes/search`. Returns a simplified response shape.

```
GET https://analysis.fossa.com/api/v1/cpe/match/{search}/compat
```

| Parameter | Type | Required | Description |
|---|---|---|---|
| `search` | path | Yes | A CPE v2.3 formatted string, or a JSON array of up to 20 CPE strings |
| `reverse-wildcard` | query | No | Set to `true` to enable reverse wildcard matching |

**Response fields:**

| Field | Type | Description |
|---|---|---|
| `nvdId` | string | The CVE ID (e.g. `CVE-2021-44228`) |
| `cpe` | string | The matched CPE string |
| `affectedVersionRanges` | string[] | Version ranges affected (e.g. `[">=2.0.0", "<2.15.0"]`) |
| `affectedPackageRanges` | object | Affected version ranges keyed by package name |
| `id` | integer | Arbitrary numeric identifier (not stable across requests) |

{% callout type="info" %}
The `id` field in the compatibility response is arbitrary and not meaningful. Use `nvdId` to identify vulnerabilities.
{% /callout %}

## Wildcard matching

All three endpoints support wildcards in the CPE search string using the standard CPE v2.3 rules:

- `*` matches any value in a field
- `?` matches any single character
- `-` represents "not applicable" (NA)

### Reverse wildcard matching

By default, matching only runs in one direction, your search wildcards match concrete database values. With `reverse-wildcard=true`, matching also runs in reverse: if the database has a wildcard in a field where your search has a concrete value, that entry will also match.

**Example:** searching for `cpe:2.3:a:vendor:product:1.0.0:*:*:*:*:*:*:*` with reverse wildcards enabled matches:
- Exact: `cpe:2.3:a:vendor:product:1.0.0:*:*:*:*:*:*:*`
- Reverse wildcard on version: `cpe:2.3:a:vendor:product:*:*:*:*:*:*:*:*`
- Reverse wildcard on part: `cpe:2.3:*:vendor:product:1.0.0:*:*:*:*:*:*:*`

{% callout type="info" %}
The `vendor` and `product` fields are exempt from reverse wildcard matching to prevent excessive results. Either your search must use a wildcard in those fields, or the database value must exactly match.
{% /callout %}

## Batch search

All endpoints accept a JSON array of up to 20 CPE strings in the path to search multiple CPEs in one request:

```shell
curl -g "https://analysis.fossa.com/api/v1/cpe/match/%5B%22cpe:2.3:a:microsoft:internet_explorer:8.0.6001:beta:*:*:*:*:*:*%22,%22cpe:2.3:a:hp:insight:7.4.0.1570:-:*:*:online:win2003:x64:*%22%5D"
```

Requests with more than 20 CPE strings are rejected with a `400` error.

## Further reading

- [CPE v2.3 specification (NIST IR 7695)](https://nvlpubs.nist.gov/nistpubs/Legacy/IR/nistir7695.pdf)
- [Interactive API explorer](https://analysis.fossa.com/docs/rapidoc)

---

Source: https://docs.fossa.com/docs/api/examples

# Usage examples

Practical, real-world recipes for accomplishing common tasks with the FOSSA API.

{% callout type="info" %}
These examples assume you have a valid FOSSA API token. See [Authentication](/docs/api/authentication) for details.
{% /callout %}

- **[Managing issues](/docs/api/examples/managing-issues)**: query, filter, bulk-ignore, and manage auto-ignore rules across licensing, security, and quality issues.
- **[Managing users and teams](/docs/api/examples/managing-users-and-teams)**: create users, manage team membership, and assign projects to teams.
- **[Initiating a binary scan](/docs/api/examples/initiating-a-binary-scan)**: upload a binary or archive and start a decomposition scan, then poll for completion.
- **[Generating reports](/docs/api/examples/generating-reports)**: trigger org-wide audit and issue CSV reports via the API.
- **[Creating Jira tickets](/docs/api/examples/creating-jira-tickets)**: export FOSSA issues to Jira without the UI.
- **[Downloading attribution reports](/docs/api/examples/downloading-attribution-reports)**: download licensing reports in several formats.
- **[Modifying release groups](/docs/api/examples/modifying-release-groups)**: add and update projects in a release group.
- **[Retrieving the latest revision](/docs/api/examples/retrieving-latest-revision)**: get the latest revision for each branch of a project.
- **[Rotating access tokens](/docs/api/examples/rotating-access-tokens)**: manage and rotate tokens securely.

---

Source: https://docs.fossa.com/docs/api/examples/managing-issues

# Managing issues

The FOSSA Issues API (v2) lets you query, filter, and act on issues across your organization or a single project. This page covers the core concepts, key endpoints, and practical recipes for common issue management tasks.

{% callout type="tip" %}
For every parameter, response field, and the complete set of issue endpoints, see the [Issues category in the Endpoint Reference](/docs/api/reference/issues).
{% /callout %}

{% callout type="info" %}
A FOSSA API token with **Full** access. See [Authentication](/docs/api/authentication).
{% /callout %}

## Core concepts

### Scope

The **scope** determines which issues are returned:

- **Global**: issues across all projects in your organization. Set `scope[type]=global`.
- **Project**: issues for a single project. Set `scope[type]=project`, `scope[id]=<project-locator>`, and `scope[revision]=<revision>`.

### Category

Issues fall into three categories, passed as the `category` query parameter:

| Value | Description |
|---|---|
| `licensing` | License policy conflicts and flags |
| `vulnerability` | Security vulnerabilities |
| `quality` | Dependency quality issues |

### Status

| Value | Description |
|---|---|
| `active` | Active issues requiring attention (default when `status` is omitted) |
| `ignored` | Issues that have been ignored |
| `all` | Both active and ignored issues |

### Ticket status

Filter by ticket status using the bracketed array parameter `filter[ticketed][]`. Pass one or more of the following values (URL-encode the brackets when your HTTP client doesn't do it automatically):

| Value | Description |
|---|---|
| `has_ticket` | Issues that have a ticket of any kind |
| `no_ticket` | Issues with no ticket association |
| `jira` | Issues with a Jira ticket |
| `custom` | Issues with a custom (manually created) ticket |

### Depth

| Value | Description |
|---|---|
| `direct` | Issues from direct dependencies only |
| `deep` | Issues from both direct and transitive dependencies |

### Severity (vulnerability only)

Filter by `severity`: `critical`, `high`, `medium`, `low`, or `unknown`.

### Issue types

Pass one or more values to `types` to narrow by issue type:

| Category | Types |
|---|---|
| Licensing | `policy_conflict`, `policy_flag`, `unlicensed_dependency` |
| Quality | `outdated_dependency`, `blacklisted_dependency`, `risk_abandonware`, `risk_empty-package`, `risk_native-code` |

### Sort

Issues are sorted by `created_at` descending by default. Control this with the `sort` parameter.

{% callout type="info" %}
Nested parameters use bracket notation: `scope[type]=global`. URL-encode the brackets when your HTTP client doesn't do it automatically.
{% /callout %}

---

## Listing issues

```bash
# All active licensing issues globally
curl -G 'https://app.fossa.com/api/v2/issues' \
  -d 'category=licensing' \
  -d 'scope[type]=global' \
  -d 'status=active' \
  -H 'Authorization: Bearer YOUR_API_KEY'

# Active security issues for a specific project
curl -G 'https://app.fossa.com/api/v2/issues' \
  -d 'category=vulnerability' \
  -d 'scope[type]=project' \
  -d 'scope[id]=git%2Bgithub.com%2Fyour-org%2Fyour-repo' \
  -d 'scope[revision]=abc123' \
  -d 'status=active' \
  -H 'Authorization: Bearer YOUR_API_KEY'
```

The response includes an `issues` array and pagination metadata. Use `page` and `count` to paginate. Each issue has an `id` used in follow-up requests.

## Getting issue counts

`GET /api/v2/issues/categories` returns counts grouped by category, useful for dashboards or alerting:

```bash
curl -G 'https://app.fossa.com/api/v2/issues/categories' \
  -d 'scope[type]=global' \
  -H 'Authorization: Bearer YOUR_API_KEY'
```

`GET /api/v2/issues/statuses` returns counts grouped by status:

```bash
curl -G 'https://app.fossa.com/api/v2/issues/statuses' \
  -d 'category=vulnerability' \
  -d 'scope[type]=global' \
  -H 'Authorization: Bearer YOUR_API_KEY'
```

## Getting a single issue

```bash
curl -G 'https://app.fossa.com/api/v2/issues/12345' \
  -d 'category=vulnerability' \
  -d 'scope[type]=global' \
  -H 'Authorization: Bearer YOUR_API_KEY'
```

## Bulk-ignoring issues

Use `PUT /api/v2/issues` to ignore multiple issues at once. Pass issue IDs as query parameters and the action in the request body.

{% steps %}
{% step title="Fetch the issue IDs you want to ignore" %}
```bash
curl -G 'https://app.fossa.com/api/v2/issues' \
  -d 'category=licensing' \
  -d 'scope[type]=global' \
  -d 'status=active' \
  -H 'Authorization: Bearer YOUR_API_KEY' | jq '[.issues[].id]'
```
{% /step %}
{% step title="Submit the ignore action" %}
```bash
curl --request PUT \
  --url 'https://app.fossa.com/api/v2/issues?category=licensing&scope[type]=global&ids[0]=12345&ids[1]=67890' \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "type": "ignore",
    "reason": "other",
    "notes": "Test-only dependency, not shipped to production"
  }'
```

Valid `reason` values: `Fixed`, `Under_investigation`, `incorrect_data_found`, `Component_not_present`, `Inline_mitigations_already_exist`, `Vulnerable_code_cannot_be_controlled_by_adversary`, `Vulnerable_code_not_in_execute_path`, `Vulnerable_code_not_present`, `other`. Use the `notes` field (not `comment`) for free-text justification.
{% /step %}
{% /steps %}

## Bulk-unignoring issues

```bash
curl --request PUT \
  --url 'https://app.fossa.com/api/v2/issues?category=licensing&scope[type]=global&ids[0]=12345' \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{ "type": "unignore" }'
```

## Working with auto-ignore rules

Auto-ignore rules persist ignore decisions across versions or projects. Manage them via the exceptions API.

### List auto-ignore rules for a project

```bash
curl -G 'https://app.fossa.com/api/v2/issues/exceptions' \
  -d 'scope[type]=project' \
  -d 'scope[id]=git%2Bgithub.com%2Fyour-org%2Fyour-repo' \
  -H 'Authorization: Bearer YOUR_API_KEY'
```

### Get a single auto-ignore rule

```bash
curl 'https://app.fossa.com/api/v2/issues/exceptions/456' \
  -H 'Authorization: Bearer YOUR_API_KEY'
```

### Delete an auto-ignore rule

```bash
curl --request DELETE \
  'https://app.fossa.com/api/v2/issues/exceptions/456' \
  -H 'Authorization: Bearer YOUR_API_KEY'
```

### Bulk-delete auto-ignore rules

```bash
curl --request DELETE \
  --url 'https://app.fossa.com/api/v2/issues/exceptions' \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{ "kind": "idList", "value": [456, 789] }'
```

The request body is a discriminated union on `kind`. Use `{ "kind": "idList", "value": [456, 789] }` to delete specific rules by ID, or `{ "kind": "all", "filters": { ... } }` to delete every rule matching a filter.

## Exporting issues as CSV

```bash
# Download immediately
curl -G 'https://app.fossa.com/api/v2/issues/csv/global' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  --output issues.zip

# Email instead
curl -G 'https://app.fossa.com/api/v2/issues/csv/global' \
  -d 'email=true' \
  -H 'Authorization: Bearer YOUR_API_KEY'
```

The download contains separate CSV files for licensing, security, and quality issues. See [Generating reports](/docs/api/examples/generating-reports) for more on org-wide report options.

---

Source: https://docs.fossa.com/docs/api/examples/managing-users-and-teams

# Managing users and teams

These recipes cover common user and team management tasks that are useful for provisioning automation and integrations with identity systems.

{% callout type="info" %}
A FOSSA API token with **Full** access and sufficient permissions (organization admin or equivalent). See [Authentication](/docs/api/authentication).
{% /callout %}

## Listing users

```bash
# Paginated user list — page 1, 25 per page
curl -G 'https://app.fossa.com/api/v2/users/' \
  -d 'page=1' \
  -d 'pageSize=25' \
  -H 'Authorization: Bearer YOUR_API_KEY'

# Search by name or email
curl -G 'https://app.fossa.com/api/v2/users/' \
  -d 'search=alice' \
  -H 'Authorization: Bearer YOUR_API_KEY'
```

## Creating a user

```bash
curl --request POST \
  --url 'https://app.fossa.com/api/users' \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "email": "alice@example.com",
    "full_name": "Alice Smith",
    "role": "member"
  }'
```

To create the user and generate an API token in one request, include `createFullApiToken` or `createPushOnlyApiToken`:

```bash
curl --request POST \
  --url 'https://app.fossa.com/api/users' \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "email": "ci-bot@example.com",
    "full_name": "CI Bot",
    "role": "member",
    "isServiceAccount": true,
    "createPushOnlyApiToken": true
  }'
```

The response includes `pushOnlyApiToken` (or `fullApiToken`) directly; this is the only time the token is returned in plain text.

## Deleting a user

```bash
curl --request DELETE \
  'https://app.fossa.com/api/users/123' \
  -H 'Authorization: Bearer YOUR_API_KEY'
```

## Listing teams

```bash
# Paginated list of all teams
curl -G 'https://app.fossa.com/api/v2/teams/' \
  -d 'page=1' \
  -d 'pageSize=25' \
  -H 'Authorization: Bearer YOUR_API_KEY'
```

## Creating a team

```bash
curl --request POST \
  --url 'https://app.fossa.com/api/teams' \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{ "name": "Platform Security" }'
```

## Getting a team

```bash
curl 'https://app.fossa.com/api/teams/42' \
  -H 'Authorization: Bearer YOUR_API_KEY'
```

The response includes the team's member user IDs and associated project locators.

## Listing team members

```bash
curl -G 'https://app.fossa.com/api/teams/42/members' \
  -d 'page=1' \
  -d 'pageSize=25' \
  -H 'Authorization: Bearer YOUR_API_KEY'
```

## Adding and removing team members

Use `PUT /api/teams/:id/users` with a top-level `action` (`add`, `replace`, or `remove`) and a `users` array. Each user specifies an `id` and an optional `roleId`.

```bash
# Add a user to the team with a specific role
curl --request PUT \
  --url 'https://app.fossa.com/api/teams/42/users' \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "action": "add",
    "users": [
      { "id": 123, "roleId": 2 }
    ]
  }'

# Remove a user from the team
curl --request PUT \
  --url 'https://app.fossa.com/api/teams/42/users' \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "action": "remove",
    "users": [
      { "id": 123 }
    ]
  }'
```

## Listing team projects

```bash
curl -G 'https://app.fossa.com/api/teams/42/projects' \
  -d 'page=1' \
  -d 'pageSize=25' \
  -H 'Authorization: Bearer YOUR_API_KEY'
```

## Assigning projects to a team

`PUT /api/teams/:id/projects` updates the team's project list. Pass a `projects` array of locators and an `action` of `add`, `remove`, or `replace`. Use `replace` to set the full list of projects the team should own.

```bash
curl --request PUT \
  --url 'https://app.fossa.com/api/teams/42/projects' \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "action": "replace",
    "projects": [
      "git+github.com/your-org/service-a",
      "git+github.com/your-org/service-b"
    ]
  }'
```

## Deleting a team

```bash
curl --request DELETE \
  'https://app.fossa.com/api/teams/42' \
  -H 'Authorization: Bearer YOUR_API_KEY'
```

---

Source: https://docs.fossa.com/docs/api/examples/initiating-a-binary-scan

# Initiating a binary scan

Binary scanning (binary decomposition) uploads a compiled binary or archive to FOSSA and breaks it down into the open source components it was built from. This recipe walks through the full API flow: request an upload URL, push the file, trigger the scan, and poll until it finishes. It is the same flow the FOSSA CLI uses under the hood, exposed here so you can drive it from CI or custom tooling without the CLI.

{% callout type="info" %}
**Prerequisites:**
- A FOSSA API token. A **Push-Only** token is sufficient to upload and trigger a scan; retrieving component results (below) needs a **Full** token. See [Authentication](/docs/api/authentication).
- **Project create** permission in your organization.
- Binary scanning enabled for your organization. It requires a Business or Enterprise plan and is metered by a binary decomposition quota. If the quota is exhausted, the upload URL request returns `403`. Contact your FOSSA account team to enable it or raise the limit.
{% /callout %}

## How the flow works

A binary scan is three API calls plus one direct upload to storage. You never send the file bytes to the FOSSA API itself.

1. Ask FOSSA for a short-lived, signed upload URL for your binary.
2. `PUT` the raw file to that URL (it points at FOSSA's object storage, not the API).
3. Tell FOSSA to build (scan) the uploaded file.
4. Poll the build status until it reports finished.

FOSSA identifies the upload by a **locator** built from the values you supply: `binary+<orgId>/<packageSpec>$<revision>`. You provide `packageSpec` and `revision` on each call; the poll step (step 4) uses the full locator.

## Running a binary scan

{% steps %}
{% step title="Request a signed upload URL" %}
Call `GET /api/components/signed_url` with `fileType=binary`. `packageSpec` is the name to give the binary project and `revision` is its version.

```bash
curl -G 'https://app.fossa.com/api/components/signed_url' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  --data-urlencode 'packageSpec=my-binary' \
  --data-urlencode 'revision=1.0.0' \
  --data-urlencode 'fileType=binary'
```

The response contains the upload URL:

```json
{ "signedUrl": "https://blob.fossa.io/binary_components/...&X-Amz-Signature=..." }
```

Copy the `signedUrl` value for the next step. The signed URL is write-only and expires one hour after it is issued.
{% /step %}
{% step title="Upload the binary" %}
`PUT` the raw file to the signed URL, pasted inside single quotes. This request goes to object storage, so it does not take a FOSSA `Authorization` header.

```bash
curl -X PUT \
  -H 'Content-Type: binary/octet-stream' \
  --upload-file ./my-binary.bin \
  'PASTE_SIGNED_URL'
```

A successful upload prints no response body. If it fails, the response shows the error (for example an `AccessDenied` block).

{% callout type="warning" %}
Paste the URL exactly as returned, with no added backslashes or line breaks. Keeping it inside single quotes stops your shell from altering the `?`, `&`, and `=` characters. An altered URL returns `AccessDenied`.
{% /callout %}

{% callout type="warning" %}
Do not trigger the scan until the upload succeeds.
{% /callout %}
{% /step %}
{% step title="Trigger the scan" %}
Call `POST /api/components/build?fileType=binary`. The JSON body must reference the same `packageSpec` and `revision` you uploaded under in step 1. The endpoint queues the scan and returns immediately.

```bash
curl -X POST 'https://app.fossa.com/api/components/build?fileType=binary' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{ "archives": [ { "packageSpec": "my-binary", "revision": "1.0.0" } ] }'
```

A `201 Created` (empty body) confirms the scan is queued.
{% /step %}
{% step title="Poll for completion" %}
Poll `GET /api/cli/<locator>/latest_build`, where `<locator>` is `binary+<orgId>/<packageSpec>$<revision>`, URL-encoded, using the same `packageSpec` and `revision` as the upload.

```bash
curl -G 'https://app.fossa.com/api/cli/binary%2B<orgId>%2Fmy-binary%241.0.0/latest_build' \
  -H 'Authorization: Bearer YOUR_API_KEY'
```

```json
{ "id": 12345, "task": { "status": "RUNNING" } }
```

Poll until `task.status` is `SUCCEEDED`. A `FAILED` status is surfaced only after retries are exhausted; on failure, check `error` in the response.
{% /step %}
{% /steps %}

{% callout type="warning" %}
Use the same `packageSpec` and `revision` across all three calls. To scan a new version of the same binary, keep `packageSpec` and change `revision`.
{% /callout %}

{% callout type="info" %}
Locators contain characters that must be URL-encoded in a path: `+` becomes `%2B`, `/` becomes `%2F`, and `$` becomes `%24`. Your `orgId` is your organization's numeric ID, which you can get from `GET /api/organizations`. For `packageSpec=my-binary` and `revision=1.0.0` in org `123`, the locator `binary+123/my-binary$1.0.0` encodes to `binary%2B123%2Fmy-binary%241.0.0`.
{% /callout %}

## Optional build parameters

Pass these as query parameters on the `POST /api/components/build` call to control how the resulting project is set up. The exception is `forceRebuild`, which is a boolean field in the JSON body.

| Parameter | Description |
| --- | --- |
| `title` | Display title for the project (defaults to `packageSpec`). |
| `branch` | Branch to record the revision under (defaults to `master`). |
| `team` | Name of a team to assign the project to. |
| `description` | Project description. |
| `projectURL` | External URL to attach to the project. |
| `policyId` | ID of a policy to apply to the project. |
| `releaseGroup` / `releaseGroupRelease` | Title of a release group and release to add the project to. |
| `forceRebuild` | Body field (boolean). Re-scan a locator that was already built. |

{% callout type="info" %}
If your organization requires a team on every upload, include `team` (or a `selectedTeams` array in the body). Without it the build call returns an error naming the missing team requirement.
{% /callout %}

## Retrieving results

When the build succeeds, the binary appears as a project in the FOSSA dashboard with its decomposed components and any license or vulnerability issues. To read the components programmatically, use the `/api/binary/...` endpoints with a **Full** token, for example:

```bash
curl -G 'https://app.fossa.com/api/binary/revision/<encoded-locator>/components/count' \
  -H 'Authorization: Bearer YOUR_API_KEY'
```

For querying the resulting issues, see [Managing issues](/docs/api/examples/managing-issues).

## Next steps

- [Authentication](/docs/api/authentication): token types and security best practices.
- [Retrieving the latest revision](/docs/api/examples/retrieving-latest-revision): find the newest revision of a project.
- [Endpoint Reference](/docs/api/reference): every endpoint, parameter, and response.

---

Source: https://docs.fossa.com/docs/api/examples/generating-reports

# Generating reports

These recipes show how to trigger the global org-wide reports available from the Reports dashboard. For project-level attribution reports, see [Downloading attribution reports](/docs/api/examples/downloading-attribution-reports).

{% callout type="info" %}
- A FOSSA API token with **Full** access. See [Authentication](/docs/api/authentication).
- **Organization Report** or **Team Report** create permission.
{% /callout %}

## Generating an audit / due diligence report

The audit report provides an org-wide summary of issues and project changes. It is generated as a background job and delivered by email.

```bash
curl 'https://app.fossa.com/api/organization/summary' \
  -H 'Authorization: Bearer YOUR_API_KEY'
```

The response includes a `jobToken` you can use to poll the job status. When the job completes, the report is emailed to the requesting user's address.

### Scope to a team

Pass `teamId` to limit the report to projects belonging to a specific team:

```bash
curl -G 'https://app.fossa.com/api/organization/summary' \
  -d 'teamId=42' \
  -H 'Authorization: Bearer YOUR_API_KEY'
```

## Generating a global issue CSV export

`GET /api/v2/issues/csv/global` exports all issues across your organization as a ZIP file containing separate CSVs for licensing, security, and quality issues.

### Download immediately

```bash
curl -G 'https://app.fossa.com/api/v2/issues/csv/global' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  --output fossa-issues.zip
```

### Email the report

For large organizations, request email delivery instead:

```bash
curl -G 'https://app.fossa.com/api/v2/issues/csv/global' \
  -d 'email=true' \
  -H 'Authorization: Bearer YOUR_API_KEY'
```

The response includes a `jobToken` that resolves when the report has been sent.

### Scope to a team

```bash
curl -G 'https://app.fossa.com/api/v2/issues/csv/global' \
  -d 'teamIds[]=42' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  --output fossa-issues-team42.zip
```

## Polling job status

Both the audit report and the emailed CSV export return a job token. Poll the token to track completion:

```bash
curl -G 'https://app.fossa.com/api/jobs/status' \
  -d 'jobs[]=YOUR_JOB_TOKEN' \
  -H 'Authorization: Bearer YOUR_API_KEY'
```

The response nests each token under `jobs`:

```json
{ "jobs": { "YOUR_JOB_TOKEN": { "status": "finished" } } }
```

A `status` of `finished` means the report has been sent. The other values are `running`, `created`, and `failed`; on `failed`, retry or contact support.

---

Source: https://docs.fossa.com/docs/api/examples/creating-jira-tickets

# Creating Jira tickets

This recipe shows how to create Jira tickets from FOSSA issues programmatically, without going through the UI.

{% callout type="info" %}
- A FOSSA API token with **Full** access. See [Authentication](/docs/api/authentication).
- A configured Jira integration in FOSSA.
- The Jira project ID and issue type you want to use.
{% /callout %}

## Exporting issues to Jira

{% steps %}
{% step title="Fetch the issue IDs you want to export" %}
Use the [Managing issues](/docs/api/examples/managing-issues) guide to list the relevant issues and extract their IDs:

```bash
curl -G 'https://app.fossa.com/api/v2/issues' \
  -d 'category=vulnerability' \
  -H 'Authorization: Bearer YOUR_API_KEY' | jq -r '.issues | .[] | .id'
```
{% /step %}
{% step title="Submit a PUT request to create the tickets" %}
Pass the issue IDs in the query string and the Jira configuration in the request body:

```bash
curl --request PUT \
  --url 'https://app.fossa.com/api/v2/issues?category=vulnerability&scope[type]=global&ids[0]=12345&ids[1]=67890' \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "type": "export",
    "ticket": {
      "type": "jira",
      "title": "Security vulnerability found",
      "description": "Please review and remediate.",
      "trackerId": "PROJ",
      "jiraId": "10001",
      "issueType": "Bug",
      "labels": ["security", "fossa"]
    }
  }'
```
{% /step %}
{% /steps %}

{% callout type="info" %}
The `description` field supports Markdown and can be up to 32,767 characters.
{% /callout %}

---

Source: https://docs.fossa.com/docs/api/examples/downloading-attribution-reports

# Downloading attribution reports

This recipe shows how to download a project's attribution report (typically a licensing report) in several formats.

{% callout type="info" %}
- A FOSSA API token, see [Authentication](/docs/api/authentication).
- The project locator or revision ID of the project you want to report on, see [Retrieving the latest revision](/docs/api/examples/retrieving-latest-revision).
{% /callout %}

## Adding a custom report header (optional)

To add custom text to the top of your report, open **Project Settings > Reports** and enter it in the **Description** field (Markdown is supported). Once configured, the custom text appears at the top of the generated attribution report.

{% img src="/images/reports/custom-report-header.png" alt="Project Settings report section with the custom report header text field" /%}

## Endpoints by format

Some formats are emailed to your account; others download directly to your machine. Replace `{revision_id}` with your URL-encoded revision locator.

| Format | Delivery | Endpoint |
| --- | --- | --- |
| Plain text | Emailed | `GET /api/revisions/{revision_id}/attribution/email?format=TXT` |
| PDF | Emailed | `GET /api/revisions/{revision_id}/attribution/email?format=PDF` |
| HTML | Download | `GET /api/revisions/{revision_id}/attribution/download?download=true&format=HTML` |
| Markdown | Download | `GET /api/revisions/{revision_id}/attribution/download?download=true&format=MD` |
| CSV | Download | `GET /api/revisions/{revision_id}/attribution/download?download=true&format=CSV` |

## Example: download an HTML report

```bash
curl --request GET \
  --url 'https://app.fossa.com/api/revisions/{revision_id}/attribution/download?download=true&format=HTML' \
  --header 'Authorization: Bearer YOUR_API_KEY'
```

## Choosing what the report includes

Pass `dependencyInfoOptions[]` one or more times to control which fields appear per dependency. Available values:

- `Library`
- `Authors`
- `Description`
- `ConcludedLicense`
- `License`
- `CustomTextLicense`
- `FullTextLicense`
- `OtherLicenses`
- `FilePath`
- `Source`
- `ProjectUrl`
- `PackageDownloadUrl`
- `DependencyPaths`
- `IssueNotes`
- `Copyrights`
- `NoticeFiles`
- `LicenseFileURL`

Some values depend on features being enabled for your organization (for example, `ConcludedLicense` requires license conclusions and `FilePath` requires file paths in reports).

## Related

- [Managing issues](/docs/api/examples/managing-issues): query issues programmatically.
- [Retrieving the latest revision](/docs/api/examples/retrieving-latest-revision): get the revision ID for a project.

---

Source: https://docs.fossa.com/docs/api/examples/modifying-release-groups

# Modifying release groups

This recipe shows how to create a release group with projects and how to update the projects in an existing release group.

{% callout type="info" %}
A FOSSA API token with **Full** access. See [Authentication](/docs/api/authentication).
{% /callout %}

## Adding projects to a new release group

Send a `POST` request to `/api/project_group` with the projects to include:

```bash
curl --request POST \
  --url 'https://app.fossa.com/api/project_group' \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "title": "My Release Group",
    "release": {
      "projects": [
        {
          "projectId": "custom+1234/example",
          "branch": "main",
          "revisionId": "custom+1234/example$2024-01-01T00:00:00Z"
        }
      ]
    }
  }'
```

## Updating an existing release group

Send a `PUT` request to `/api/project_group/<group-id>/release/<release-id>` with the updated project list.

{% callout type="info" %}
You'll need a valid `revisionId` for each project. See [Retrieving the latest revision](/docs/api/examples/retrieving-latest-revision).
{% /callout %}

Things to keep in mind:

- A project can only belong to one release group at a time.
- The `revisionId` must be a valid revision of the project.

## Troubleshooting

**Why am I getting a `400` error from the PUT endpoint?**

A `400` usually means the request body is malformed, or a project you're adding already belongs to another release group.

---

Source: https://docs.fossa.com/docs/api/examples/retrieving-latest-revision

# Retrieving the latest revision

This recipe shows how to retrieve the latest revision for each branch of a project.

## Listing a project's branches

Send a `GET` request to the project endpoint with `ref_type=branch`:

```bash
curl --request GET \
  --url 'https://app.fossa.com/api/projects/<project-locator>?ref_type=branch' \
  --header 'Authorization: Bearer YOUR_API_KEY'
```

{% callout type="info" %}
URL-encode the project locator, for example, `custom+1234/example` becomes `custom%2B1234%2Fexample`.
{% /callout %}

## Reading the response

The response includes a `references` array. Each entry describes a branch and points to its latest revision:

| Field | Description |
| --- | --- |
| `id` | The reference ID. |
| `type` | The reference type (e.g. `branch`). |
| `name` | The branch name. |
| `revision_id` | The locator of the latest revision on that branch. |
| `project_id` | The project locator. |

Use the `revision_id` value wherever a revision locator is required, for example, when [downloading attribution reports](/docs/api/examples/downloading-attribution-reports) or [modifying release groups](/docs/api/examples/modifying-release-groups).

---

Source: https://docs.fossa.com/docs/api/examples/rotating-access-tokens

# Rotating access tokens

Access tokens provide programmatic access to FOSSA. Like passwords, they should be stored securely and rotated periodically.

## Use a service account

Create a dedicated service account with minimal permissions for automation, rather than using a personal account. A typical minimal set is **Create projects**, **Edit projects**, and **View projects**. See [Roles and permissions](/docs/organization-management/role-based-access-control) for how to scope access.

## Choose the right token type

| Token type | Use it for |
| --- | --- |
| **Push-Only** | CLI and CI integrations that only push analysis results. |
| **Full** | Read APIs and management tasks that need account-level access. |

See [Authentication](/docs/api/authentication) for more on token types.

## Rotation procedure

{% steps %}
{% step title="Generate a new token" %}
Create a new token for the service account.
{% /step %}
{% step title="Update your integrations" %}
Point your integrations and stored secrets at the new token.
{% /step %}
{% step title="Verify" %}
Confirm the integrations work with the new token.
{% /step %}
{% step title="Revoke the old token" %}
Once everything is confirmed, revoke the previous token.
{% /step %}
{% /steps %}

## Security considerations

- Store tokens in a secrets manager (AWS Secrets Manager, HashiCorp Vault, Azure Key Vault).
- Rotate tokens regularly; every 80–180 days is a reasonable cadence.
- Monitor token usage and revoke unused tokens.

## Related

- [Authentication](/docs/api/authentication)
- [API Tokens](/docs/organization-management/api-tokens)
- [Endpoint Reference](/docs/api/reference)

---

Source: https://docs.fossa.com/docs/integrations

# Integrations

FOSSA fits into the tools your teams already use, so analysis and findings show up where work happens.

## What this covers

- **CI/CD:** run FOSSA in [GitHub Actions](/docs/integrations/github-actions), Jenkins, GitLab CI, CircleCI, and more.
- **Source hosts:** connect GitHub, GitLab, Bitbucket, and Azure DevOps.
- **Ticketing & chat:** sync issues to Jira and notify teams in Slack.
- **fossabot:** automated PR checks and comments powered by FOSSA.

To build a custom connection, see the [API Reference](/docs/api).

---

Source: https://docs.fossa.com/docs/integrations/jira

# Jira

FOSSA's Jira integration lets your team track open-source compliance and security issues without leaving the tools they already use. Once connected, you can export FOSSA issues as Jira tickets and have those issues automatically resolve in FOSSA when the corresponding Jira ticket is closed.

The integration provides two capabilities:

- **Export issues:** create Jira tickets from any FOSSA issue, individually or in bulk.
- **Auto-resolve via webhook:** when a Jira ticket is marked resolved, FOSSA automatically resolves the linked issue.

## How it works

FOSSA authenticates to Jira using basic credentials (email + API token for Cloud; username + password for Server). When you export an issue, FOSSA calls Jira's REST API v2 (`POST /rest/api/2/issue/bulk`) and stores the returned ticket ID to track the link.

For auto-resolution, you register a FOSSA-generated webhook URL in your Jira instance. Jira sends an event to FOSSA when a ticket is updated or deleted. FOSSA checks whether the ticket has a resolution set and, if so, marks the linked FOSSA issue as resolved.

## Required Jira permissions

| Capability | Required Jira permission |
|---|---|
| Export issues | Basic Jira product access (create and interact with issues) |
| Auto-resolve via webhook | **Jira Administrator** or **Product Admin for Jira** (to create and manage webhooks) |

In enterprise environments you may need your IT or Jira administrator to grant these permissions. You can also create a dedicated permission group that combines both levels so a single service account covers the full integration.

See Atlassian's [Default groups and permissions](https://support.atlassian.com/user-management/docs/default-groups-and-permissions/) guide for details.

## Connecting Jira to FOSSA

{% steps %}
{% step title="Open Jira integration settings" %}
Go to [**Settings → Integrations → Jira**](https://app.fossa.com/account/settings/integrations/jira). If you have not configured a site yet, click **Add Site**.

{% img src="/images/integrations/59f737557178b8b2d652535f4868ec14f6e3561459ed1d2ee11c151a7be0b14a-image.png" alt="Jira integration settings page with Add Site button" /%}
{% /step %}
{% step title="Enter a name and site URL" %}
Give the integration a unique name, which is helpful if you configure multiple Jira sites. Then enter your Jira site's **base URL only**, for example `your-org.atlassian.net` for Jira Cloud.
{% /step %}
{% step title="Add project key(s)" %}
Enter at least one Jira **project key**, the short identifier that prefixes every issue ID in that project (for example, `PROJ` in `PROJ-123`). You can find it in the project URL or in **Project Settings → Details** under **Key**.

Multiple keys are supported if you route issues to more than one project.
{% /step %}
{% step title="Set issue type and labels (optional)" %}
- **Issue type:** must exactly match a type configured in your Jira instance (e.g., `Bug`, `Task`, `Story`). FOSSA defaults to `Task` if none is specified.
- **Labels:** free-form tags that do not need to exist in Jira beforehand. A label like `FOSSA` makes exported tickets easy to filter.

{% callout type="info" %}
Using a consistent label or issue type for all FOSSA-exported tickets makes them easy to find in Jira.
{% /callout %}
{% /step %}
{% step title="Save the site" %}
Click **Save**. FOSSA will generate a webhook URL for this site; copy it now if you plan to set up auto-resolution.
{% /step %}
{% /steps %}

## Configuring credentials

FOSSA authenticates with Jira via basic auth. Use a dedicated service account rather than a personal user account.

{% tabs %}
{% tab name="Jira Cloud" %}
FOSSA authenticates using your Jira user's **email address** and an **API token**.

{% callout type="warning" %}
FOSSA does not currently support scoped (granular) API tokens. Use a classic API token.
{% /callout %}

To create a token, follow [Atlassian's guide on managing API tokens](https://support.atlassian.com/atlassian-account/docs/manage-api-tokens-for-your-atlassian-account/).

The account must have permission to **create, resolve, and modify issues** in the target projects.
{% /tab %}
{% tab name="Jira Server / On-Premises" %}
FOSSA authenticates using a Jira username and password. Create a dedicated user in your Jira instance and grant it administrator-level permissions.

{% steps %}
{% step title="Create a new Jira user" %}
In your Jira instance, navigate to user management and create a new user account.

{% img src="/images/integrations/e3a4ac9-jira-user-nav.png" alt="Jira user management navigation" /%}

{% img src="/images/integrations/811fe5b-jira-create-user-btn.png" alt="Create user button in Jira" /%}

{% img src="/images/integrations/296d5f1-jira-create-user.png" alt="Create user form in Jira" /%}
{% /step %}
{% step title="Add the user as an administrator" %}
Add the new user to the Jira Administrators group so it has permission to create issues and manage webhooks.

{% img src="/images/integrations/83f4847-jira-edit-members.png" alt="Edit group members in Jira" /%}

{% img src="/images/integrations/ea1562a-jira-add-admin.png" alt="Adding user as admin in Jira" /%}
{% /step %}
{% /steps %}
{% /tab %}
{% /tabs %}

### Adding custom fields

{% callout type="danger" %}
FOSSA supports simple text-based custom fields only. To create a custom field in Jira first, follow [Atlassian's guide](https://support.atlassian.com/jira-cloud-administration/docs/create-a-custom-field/).
{% /callout %}

{% steps %}
{% step title="Open custom fields in FOSSA" %}
On the Jira integration settings page, click **Add Field** under the custom fields section.
{% /step %}
{% step title="Find the field ID in Jira" %}
In your Jira site, go to **Project Settings → Issues → Fields**. Click the pencil (edit) icon in the top-right of the table.

{% img src="/images/integrations/0de34b8-Screen_Shot_2022-05-09_at_3.12.06_PM.png" alt="Project Settings navigation in Jira" /%}

{% img src="/images/integrations/f89d5d3-Screen_Shot_2022-05-09_at_3.12.28_PM.png" alt="Issues > Fields in Jira sidebar" /%}

{% img src="/images/integrations/0ed458f-Screen_Shot_2022-05-09_at_3.12.45_PM.png" alt="Edit button at top-right of fields table" /%}

Click **Edit** on the field you want to add. In the URL you will see `orderableFieldId=customfield_XXXXX`; copy only the numeric portion (e.g., `10031`).

{% img src="/images/integrations/3df908f-Screen_Shot_2022-05-09_at_3.13.19_PM.png" alt="URL showing customfield ID" /%}
{% /step %}
{% step title="Configure the field in FOSSA" %}
Enter the numeric Field ID, a display name (usually matching the Jira field name), and an optional default value. Check **Required** if every exported issue should include this field.
{% /step %}
{% /steps %}

### Request headers

If your Jira configuration requires additional authentication headers, add them at the bottom of the Jira settings page. This is an advanced option not needed for standard Jira Cloud integrations.

## Setting up the webhook

The webhook lets Jira notify FOSSA when a ticket is closed, which automatically resolves the linked FOSSA issue.

{% steps %}
{% step title="Copy your webhook URL from FOSSA" %}
After saving your Jira site settings, FOSSA generates a unique webhook URL for that site. Copy it from the integration settings page. Each Jira site you configure gets its own URL.
{% /step %}
{% step title="Open webhook settings in Jira" %}
In Jira, click the **Settings gear** in the top-right corner. Under Jira admin settings, click **System**.

{% img src="/images/integrations/f0d8dcd029283b1b2b5c90d5e978a93b2ef2a21aaf070aefcdc0ce113764e6cf-image.png" alt="Jira admin System settings" /%}

In the left panel under **Advanced**, click **WebHooks**.

{% img src="/images/integrations/8e36ccea10134e0dffceaaefb0a0b99a5c3bca6d1898b16fd49dc8215ba34067-image.png" alt="WebHooks option in Jira Advanced sidebar" /%}
{% /step %}
{% step title="Create a new webhook" %}
Click **Create a WebHook**. Enter the FOSSA webhook URL as the endpoint.

{% img src="/images/integrations/dbb9b02-jira-create-webhook.png" alt="Create webhook form in Jira" /%}

{% img src="/images/integrations/555c00e134503fcf03fc2420ca64e010c39b46ec4abc2903d8e3108abaee3fda-image.png" alt="Webhook URL field in Jira" /%}
{% /step %}
{% step title="Select trigger events" %}
Under **Issues**, enable the **updated** and **deleted** events.

{% img src="/images/integrations/908955e8c20e179ece278c6ebddd915c0bea20b5a9f30949c626b701144229ab-image.png" alt="Jira webhook event configuration for issue updated and deleted" /%}
{% /step %}
{% step title="Save and verify" %}
Save the webhook. It will appear in the webhook list with the URL and events you configured.

{% img src="/images/integrations/b08168fb2b9af3627e4f103509dbf189bbbd3b7670d1438f2ed78f9823b2da6d-image.png" alt="Saved webhook entry in Jira" /%}
{% /step %}
{% /steps %}

## Creating tickets from FOSSA

### Creating a ticket for a single issue

{% steps %}
{% step title="Select the issue" %}
On the FOSSA Issues page, check the box next to the issue you want to ticket.

{% img src="/images/integrations/1e42649-CreateTicket.png" alt="Issue checkbox and Create Ticket button on the FOSSA Issues page" /%}
{% /step %}
{% step title="Fill in the ticket details" %}
In the **Create Ticket** modal, select the Jira **Site** and **Project ID**. Optionally set the issue type and label, then click **Create ticket**.

{% img src="/images/integrations/8a4ef76-JIRATicketPopUpTemplate.png" alt="Create Ticket modal with Site, Project ID, Issue Type, and Label fields" /%}
{% /step %}
{% /steps %}

The new Jira ticket includes the issue details and a live link back to FOSSA. Use the **Ticketed** filter on the Issues page to find it.

### Creating tickets for multiple issues

Select multiple issue checkboxes, or use the bulk-select checkbox to select all on the page, then click **Select all** to include every matching issue. Click **Create Ticket**, choose your Site and Project ID, and confirm.

{% img src="/images/integrations/89b1e47-CreateTicketMultipleIssues.png" alt="Multiple issues selected with Create Ticket button" /%}

{% callout type="danger" %}
When creating a single ticket for multiple issues, only the first 50 issues receive full details in the ticket body. The remaining issues appear as links back to FOSSA.
{% /callout %}

### Creating unique tickets per issue

Enable **Unique Jira ticket per FOSSA issue** in the Create Ticket modal to create one individual ticket per selected issue. Use the left/right arrows to review and edit each ticket before creating.

{% img src="/images/integrations/6d03ada-Screen_Shot_2023-07-06_at_9.35.46_AM.png" alt="Unique Jira ticket per FOSSA issue toggle in the Create Ticket modal" /%}

{% callout type="warning" %}
Unique ticket creation is limited to the first 50 selected issues due to Jira API limits.
{% /callout %}

To make unique tickets the default for your entire organization, go to **Organization Settings → Integrations → Jira** and enable the setting there.

{% img src="/images/integrations/6e53755-Screen_Shot_2023-07-06_at_9.42.30_AM.png" alt="Enable unique Jira tickets by default in Organization Settings" /%}

### Creating URL-linked tickets

To link a FOSSA issue to an existing ticket in Jira (or any other ticketing system), choose **Link to an existing URL** when clicking **Create Ticket**.

{% img src="/images/integrations/2429456-Screen_Shot_2024-03-21_at_12.31.03_PM.png" alt="Create Ticket modal showing 'Create a JIRA ticket' and 'Link to an existing URL' options" /%}

Supply the ticket URL and an optional comment. The comment appears on the tracked FOSSA issue.

{% img src="/images/integrations/366a75e-Screen_Shot_2024-03-21_at_1.23.25_PM.png" alt="Manual ticketing modal with URL and comment fields" /%}

{% img src="/images/integrations/929ca79-Screen_Shot_2024-03-21_at_1.24.32_PM.png" alt="Comment visible on the tracked FOSSA issue" /%}

## Troubleshooting

### "Failed to create issue" error

```
Failed to create issue. Make sure the configured Jira account has permission to create issues in the target Jira project.
```

This message appears for several root causes, not only permissions problems. Work through the steps below before escalating.

**Check basic configuration**

| Setting | What to verify |
|---|---|
| Site URL | Formatted as `https://yourcompany.atlassian.net/` with trailing slash |
| Username | Email address format, not display name |
| API token | Valid and not expired |
| Project key | Exists in Jira and the account can access it |
| Issue type | Matches a type in the project's issue type scheme |

**Test the API manually**

Before assuming a permissions problem, replay FOSSA's exact API calls with the same credentials you configured:

{% tabs %}
{% tab name="Single issue" %}
{% request-examples %}
{% request-example language="curl" %}
```bash
curl -X POST "https://YOUR-JIRA-SITE.atlassian.net/rest/api/2/issue" \
  -H "Content-Type: application/json" \
  -u "your-email@company.com:YOUR_API_TOKEN" \
  -d '{"fields":{"project":{"key":"YOUR_PROJECT_KEY"},"summary":"Test FOSSA Integration","description":"Testing API compatibility for FOSSA integration","issuetype":{"name":"Bug"},"labels":["FOSSA"]}}'
```
{% /request-example %}
{% request-example language="python" %}
```python
import requests

requests.post(
    "https://YOUR-JIRA-SITE.atlassian.net/rest/api/2/issue",
    auth=("your-email@company.com", "YOUR_API_TOKEN"),
    json={"fields": {
        "project": {"key": "YOUR_PROJECT_KEY"},
        "summary": "Test FOSSA Integration",
        "description": "Testing API compatibility for FOSSA integration",
        "issuetype": {"name": "Bug"},
        "labels": ["FOSSA"],
    }},
)
```
{% /request-example %}
{% request-example language="node" %}
```js
const token = Buffer.from("your-email@company.com:YOUR_API_TOKEN").toString("base64");
await fetch("https://YOUR-JIRA-SITE.atlassian.net/rest/api/2/issue", {
  method: "POST",
  headers: { Authorization: `Basic ${token}`, "Content-Type": "application/json" },
  body: JSON.stringify({ fields: {
    project: { key: "YOUR_PROJECT_KEY" },
    summary: "Test FOSSA Integration",
    description: "Testing API compatibility for FOSSA integration",
    issuetype: { name: "Bug" },
    labels: ["FOSSA"],
  }}),
});
```
{% /request-example %}
{% request-example language="ruby" %}
```ruby
require "net/http"
require "json"

uri = URI("https://YOUR-JIRA-SITE.atlassian.net/rest/api/2/issue")
req = Net::HTTP::Post.new(uri, "Content-Type" => "application/json")
req.basic_auth("your-email@company.com", "YOUR_API_TOKEN")
req.body = { fields: {
  project: { key: "YOUR_PROJECT_KEY" },
  summary: "Test FOSSA Integration",
  description: "Testing API compatibility for FOSSA integration",
  issuetype: { name: "Bug" },
  labels: ["FOSSA"],
} }.to_json
Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |h| h.request(req) }
```
{% /request-example %}
{% request-example language="go" %}
```go
body := `{"fields":{"project":{"key":"YOUR_PROJECT_KEY"},"summary":"Test FOSSA Integration","description":"Testing API compatibility for FOSSA integration","issuetype":{"name":"Bug"},"labels":["FOSSA"]}}`
req, _ := http.NewRequest("POST", "https://YOUR-JIRA-SITE.atlassian.net/rest/api/2/issue", strings.NewReader(body))
req.Header.Set("Content-Type", "application/json")
req.SetBasicAuth("your-email@company.com", "YOUR_API_TOKEN")
http.DefaultClient.Do(req)
```
{% /request-example %}
{% request-example language="java" %}
```java
String creds = Base64.getEncoder().encodeToString("your-email@company.com:YOUR_API_TOKEN".getBytes());
String body = "{\"fields\":{\"project\":{\"key\":\"YOUR_PROJECT_KEY\"},\"summary\":\"Test FOSSA Integration\",\"issuetype\":{\"name\":\"Bug\"},\"labels\":[\"FOSSA\"]}}";
HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://YOUR-JIRA-SITE.atlassian.net/rest/api/2/issue"))
    .header("Content-Type", "application/json")
    .header("Authorization", "Basic " + creds)
    .POST(HttpRequest.BodyPublishers.ofString(body))
    .build();
HttpClient.newHttpClient().send(request, BodyHandlers.ofString());
```
{% /request-example %}
{% request-example language="php" %}
```php
(new GuzzleHttp\Client())->post(
    "https://YOUR-JIRA-SITE.atlassian.net/rest/api/2/issue",
    [
        "auth"    => ["your-email@company.com", "YOUR_API_TOKEN"],
        "json"    => ["fields" => [
            "project"     => ["key" => "YOUR_PROJECT_KEY"],
            "summary"     => "Test FOSSA Integration",
            "description" => "Testing API compatibility for FOSSA integration",
            "issuetype"   => ["name" => "Bug"],
            "labels"      => ["FOSSA"],
        ]],
    ]
);
```
{% /request-example %}
{% /request-examples %}
{% /tab %}
{% tab name="Bulk issues" %}
{% request-examples %}
{% request-example language="curl" %}
```bash
curl -X POST "https://YOUR-JIRA-SITE.atlassian.net/rest/api/2/issue/bulk" \
  -H "Content-Type: application/json" \
  -u "your-email@company.com:YOUR_API_TOKEN" \
  -d '{"issueUpdates":[{"fields":{"project":{"key":"YOUR_PROJECT_KEY"},"summary":"Test FOSSA Bulk Integration","description":"Testing bulk API compatibility for FOSSA integration","issuetype":{"name":"Bug"},"labels":["FOSSA"]}}]}'
```
{% /request-example %}
{% request-example language="python" %}
```python
import requests

requests.post(
    "https://YOUR-JIRA-SITE.atlassian.net/rest/api/2/issue/bulk",
    auth=("your-email@company.com", "YOUR_API_TOKEN"),
    json={"issueUpdates": [{"fields": {
        "project": {"key": "YOUR_PROJECT_KEY"},
        "summary": "Test FOSSA Bulk Integration",
        "description": "Testing bulk API compatibility for FOSSA integration",
        "issuetype": {"name": "Bug"},
        "labels": ["FOSSA"],
    }}]},
)
```
{% /request-example %}
{% request-example language="node" %}
```js
const token = Buffer.from("your-email@company.com:YOUR_API_TOKEN").toString("base64");
await fetch("https://YOUR-JIRA-SITE.atlassian.net/rest/api/2/issue/bulk", {
  method: "POST",
  headers: { Authorization: `Basic ${token}`, "Content-Type": "application/json" },
  body: JSON.stringify({ issueUpdates: [{ fields: {
    project: { key: "YOUR_PROJECT_KEY" },
    summary: "Test FOSSA Bulk Integration",
    description: "Testing bulk API compatibility for FOSSA integration",
    issuetype: { name: "Bug" },
    labels: ["FOSSA"],
  }}]}),
});
```
{% /request-example %}
{% request-example language="ruby" %}
```ruby
require "net/http"
require "json"

uri = URI("https://YOUR-JIRA-SITE.atlassian.net/rest/api/2/issue/bulk")
req = Net::HTTP::Post.new(uri, "Content-Type" => "application/json")
req.basic_auth("your-email@company.com", "YOUR_API_TOKEN")
req.body = { issueUpdates: [{ fields: {
  project: { key: "YOUR_PROJECT_KEY" },
  summary: "Test FOSSA Bulk Integration",
  description: "Testing bulk API compatibility for FOSSA integration",
  issuetype: { name: "Bug" },
  labels: ["FOSSA"],
} }] }.to_json
Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |h| h.request(req) }
```
{% /request-example %}
{% request-example language="go" %}
```go
body := `{"issueUpdates":[{"fields":{"project":{"key":"YOUR_PROJECT_KEY"},"summary":"Test FOSSA Bulk Integration","issuetype":{"name":"Bug"},"labels":["FOSSA"]}}]}`
req, _ := http.NewRequest("POST", "https://YOUR-JIRA-SITE.atlassian.net/rest/api/2/issue/bulk", strings.NewReader(body))
req.Header.Set("Content-Type", "application/json")
req.SetBasicAuth("your-email@company.com", "YOUR_API_TOKEN")
http.DefaultClient.Do(req)
```
{% /request-example %}
{% request-example language="java" %}
```java
String creds = Base64.getEncoder().encodeToString("your-email@company.com:YOUR_API_TOKEN".getBytes());
String body = "{\"issueUpdates\":[{\"fields\":{\"project\":{\"key\":\"YOUR_PROJECT_KEY\"},\"summary\":\"Test FOSSA Bulk Integration\",\"issuetype\":{\"name\":\"Bug\"},\"labels\":[\"FOSSA\"]}}]}";
HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://YOUR-JIRA-SITE.atlassian.net/rest/api/2/issue/bulk"))
    .header("Content-Type", "application/json")
    .header("Authorization", "Basic " + creds)
    .POST(HttpRequest.BodyPublishers.ofString(body))
    .build();
HttpClient.newHttpClient().send(request, BodyHandlers.ofString());
```
{% /request-example %}
{% request-example language="php" %}
```php
(new GuzzleHttp\Client())->post(
    "https://YOUR-JIRA-SITE.atlassian.net/rest/api/2/issue/bulk",
    [
        "auth" => ["your-email@company.com", "YOUR_API_TOKEN"],
        "json" => ["issueUpdates" => [["fields" => [
            "project"     => ["key" => "YOUR_PROJECT_KEY"],
            "summary"     => "Test FOSSA Bulk Integration",
            "description" => "Testing bulk API compatibility for FOSSA integration",
            "issuetype"   => ["name" => "Bug"],
            "labels"      => ["FOSSA"],
        ]]]],
    ]
);
```
{% /request-example %}
{% /request-examples %}
{% /tab %}
{% /tabs %}

**Match symptoms to root causes**

| Symptom | Root cause | Fix |
|---|---|---|
| Generic permission error + manual API call succeeds | Field configuration | Enable the description/summary fields for the issue type in project settings |
| Permission error + manual API call also fails | Actual permissions | Grant the user "Create Issues" permission in the project |
| Issue type error | Missing issue type in project scheme | Add the issue type, or configure FOSSA to use one that already exists |
| Custom field error | Required custom field missing from payload | Make the field optional in Jira, or set a default value in FOSSA |
| Connectivity / SSL error | Wrong URL or network issue | Verify the Jira base URL; confirm FOSSA can reach it |

### Webhook not resolving issues

Check that the webhook URL registered in Jira exactly matches the URL shown in FOSSA's integration settings. Each Jira site you configure gets its own unique URL; if you added a second site, register a separate webhook for it.

Confirm the webhook is set to fire on **Issue updated** and **Issue deleted** events, and that the account used to configure it has Jira Administrator permissions.

### Issue type `Task` is missing

FOSSA defaults to the `Task` issue type. If your Jira project has removed or renamed it, either add `Task` back to the project's issue type scheme or configure a different issue type in FOSSA's integration settings.

See Atlassian's [Unable to move issue due to invalid issue type](https://confluence.atlassian.com/jirakb/unable-to-move-issue-to-another-issue-type-due-to-the-issue-type-selected-is-invalid-error-227413483.html) article for further help.

### Advanced debugging

To capture detailed API logs from Jira's side:

{% steps %}
{% step title="Enable debug logging in Jira" %}
Go to **Jira Administration → System → Logging and profiling**. Add the package `com.atlassian.jira.rest` at log level **DEBUG**.
{% /step %}
{% step title="Reproduce the failure" %}
Attempt to export a FOSSA issue while the debug logging is active.
{% /step %}
{% step title="Review the logs" %}
Check the Jira logs for the specific API call details and error codes returned.
{% /step %}
{% /steps %}

To verify connectivity and credentials independently of FOSSA:

```bash
# Test that Jira is reachable
curl -I "https://yourcompany.atlassian.net/"

# Test that credentials work
curl -u "email:token" "https://yourcompany.atlassian.net/rest/api/2/myself"
```

## Support escalation

Escalate to FOSSA engineering when:

- Manual API calls succeed with the same credentials but the FOSSA integration still fails.
- Field configuration appears correct but ticket creation still returns errors.
- API responses suggest FOSSA is sending a malformed request body.
- Multiple customers report the same failure pattern.

Include in the escalation:

- API test results (both successful and failing calls with response bodies)
- Jira project configuration details (issue types, required fields, project scheme)
- FOSSA integration settings (redact the API token)
- Exact error messages from API responses, not just the message shown in the FOSSA UI

---

Source: https://docs.fossa.com/docs/integrations/creating-a-jira-ticket

# Creating Jira Tickets

Turn any issue in your inbox into a ticket so work gets tracked in the tools your team already uses. You can create a native **Jira** ticket or link an issue to an existing URL in any ticketing system. Every ticket carries the issue's details and a live link back to the FOSSA issue.

{% callout type="info" %}
Native Jira ticketing requires a connected Jira integration. See [Jira](/docs/integrations/jira) to connect your instance first. Linking to an existing URL works with any ticketing system and needs no integration.
{% /callout %}

## How ticketing works

- Start from the **Issues** inbox. Select one or more issues, then click **Create Ticket**.
- Choose **Create a Jira ticket** for native Jira, or **Link to an existing URL** for any other system.
- The ticket is populated with the issue's information and a live link back to the FOSSA issue.
- By default, a single Jira ticket holds the details of up to **50 issues**. Beyond that, the extra issues get only a live link back to FOSSA.
- Enable **Unique Jira ticket per FOSSA issue** to split a selection into one ticket each, available only when fewer than 50 issues are selected.

## Creating a ticket for a single issue

{% steps %}
{% step title="Select the issue" %}
In the **Issues** inbox, select the checkbox next to the issue, then click **Create Ticket**.
{% /step %}
{% step title="Fill in the ticket details" %}
In the **Create Ticket** window, choose the **Site** and **Project Id**, plus any optional fields such as **Issue Type** or **Label**.
{% /step %}
{% step title="Create the ticket" %}
Click **Create ticket**. The new ticket carries the issue's information and a live link back to the FOSSA issue.
{% /step %}
{% /steps %}

{% img src="/images/integrations/8a4ef76-JIRATicketPopUpTemplate.png" alt="Create ticket window with Site, Project Id, and optional fields" /%}

Filter your inbox with the **Ticketed** option to find newly created tickets.

## Creating tickets for multiple issues

{% steps %}
{% step title="Select the issues" %}
In the **Issues** inbox, select the checkbox next to each issue. To select everything, use the bulk-select checkbox, then click **Select all**.
{% /step %}
{% step title="Open the ticket window" %}
Click **Create Ticket**, then set the **Site**, **Project Id**, and any optional fields.
{% /step %}
{% step title="Create the tickets" %}
Click **Create ticket(s)**.
{% /step %}
{% /steps %}

{% callout type="danger" %}
A single Jira ticket includes full details for only the **first 50 issues**. Any remaining issues get a live link back to FOSSA instead of inline detail.
{% /callout %}

## Creating a unique ticket for each issue

Enable **Unique Jira ticket per FOSSA issue** in the **Create Ticket** window to split your selection into one ticket per issue. Use the left and right arrows to move between issues and edit each ticket's details before creating them.

{% img src="/images/integrations/6d03ada-Screen_Shot_2023-07-06_at_9.35.46_AM.png" alt="Unique Jira ticket per FOSSA issue option" /%}

{% callout type="danger" %}
Ticket splitting is turned off when **50 or more** issues are selected. Select fewer than 50 to create unique tickets.
{% /callout %}

{% callout type="warning" %}
Switching a selection to unique tickets means the selected FOSSA issues are **no longer associated with their previous Jira ticket**.
{% /callout %}

## Enabling unique tickets by default

Admins can make unique tickets the default for every user in the organization.

{% steps %}
{% step title="Open Jira integration settings" %}
Go to **Organization Settings → Integrations → Jira**.
{% /step %}
{% step title="Turn on the default" %}
Enable **Enable unique Jira tickets by default**. From then on, unique tickets are the default action whenever any user creates Jira tickets.
{% /step %}
{% /steps %}

{% img src="/images/integrations/6e53755-Screen_Shot_2023-07-06_at_9.42.30_AM.png" alt="Enable unique Jira tickets by default toggle in organization settings" /%}

## Linking an issue to an existing URL

To track an issue in a non-Jira system, link it to any URL instead of creating a native Jira ticket.

{% steps %}
{% step title="Open the ticket window" %}
Select the issue and click **Create Ticket**.
{% /step %}
{% step title="Choose Link to an existing URL" %}
Select **Link to an existing URL** to open the manual ticketing window.
{% /step %}
{% step title="Add the URL" %}
Supply the **URL** and an optional **comment**. Any comment you add appears on the tracked FOSSA issue.
{% /step %}
{% /steps %}

{% img src="/images/integrations/366a75e-Screen_Shot_2024-03-21_at_1.23.25_PM.png" alt="Manual ticketing window for linking an issue to a URL" /%}

## Ticket fields and limits

| Field | Applies to | Notes |
| --- | --- | --- |
| **Site** | Jira | The connected Jira instance. |
| **Project Id** | Jira | The Jira project that receives the ticket. |
| **Issue Type** | Jira (optional) | Jira issue type, such as Bug or Task. |
| **Label** | Jira (optional) | Label applied to the created ticket. |
| **URL** | Manual | The external ticket link. |
| **Comment** | Manual (optional) | Added as a comment on the FOSSA issue. |

| Limit | Value |
| --- | --- |
| Issues detailed in a single Jira ticket | First **50** |
| Maximum selection for unique tickets | Fewer than **50** |

## FAQ

**What happens to issues past the first 50 in one ticket?**
They are not detailed inline. Each gets a live link back to its FOSSA issue instead.

**Can I track issues in a system other than Jira?**
Yes. Choose **Link to an existing URL** to link an issue to any ticketing system without a Jira integration.

**Why is the unique-ticket option unavailable?**
You have 50 or more issues selected. Ticket splitting is only available for selections under 50.

**How do I find issues that already have tickets?**
Filter the **Issues** inbox with the **Ticketed** option.

---

Source: https://docs.fossa.com/docs/integrations/fail-cicd-checks

# Fail CI/CD Checks

FOSSA can fail CI/CD checks when issues are detected during a scan. Those issues may relate to licensing, security (vulnerabilities), or quality. You configure this behavior per category in a project's **Policies** settings.

{% img src="/images/integrations/36b7e996acbc58d460c13444165b3dccc80c865b4cd6458ec04a043ae130c481-image.png" alt="Project Policies settings" /%}

## Configuring a failure condition

{% callout type="info" %}
Before you can fail CI/CD checks for a category, you must enable the relevant scan type (Licensing, Security, or Quality) for the project.
{% /callout %}

{% steps %}
{% step title="Open the project's Policies settings" %}
In your project's settings, select the **Policies** tab, then choose the category you want to configure: Licensing, Security, or Quality.
{% /step %}
{% step title="Enable the failure condition" %}
Turn on **"Fail CI/CD checks if {category} issues matching this filter exist."** The `{category}` placeholder reflects the category you selected, for example, "Fail CI/CD checks if Licensing issues matching this filter exist."
{% /step %}
{% step title="Choose an issue filter" %}
Select an issue filter from the dropdown. The default is **"All issues (not filtered)"**, which fails the check on any issue in that category. Use a filter to target specific issues.
{% /step %}
{% /steps %}

Below are some example licensing issue filters:

{% img src="/images/integrations/663c029bef79ec2fa179300b5219c36b5ae386f3c36e2656eef1ea4b91abaca3-image.png" alt="Example licensing issue filters" /%}

## How the check fails

When a check is configured and matching issues exist, FOSSA reports a failing status to your CI/CD pipeline. If you run scans with the FOSSA CLI, `fossa test` returns a non-zero exit code when matching issues are found, which fails the build step. See the [CLI documentation](/docs/cli) for details.

## What's next

- **[Issue Scanners](/docs/project-setup/issue-scanners)**: Control which issue categories (licensing, security, quality) contribute to CI/CD failures.
- **[Licensing Policies](/docs/policies/licensing-policies)**: Define which licenses trigger check failures.
- **[Security Policy](/docs/policies/security-policy)**: Define which vulnerability severities trigger check failures.

---

Source: https://docs.fossa.com/docs/integrations/aws-codebuild

# AWS CodeBuild

Add FOSSA to your CodeBuild pipeline to scan dependencies on every build. The setup has two parts: storing your FOSSA API key securely in AWS Systems Manager, then configuring your `buildspec.yml` to install and run the FOSSA CLI.

## Storing the API key in AWS Systems Manager

FOSSA needs your API key at scan time. Store it in SSM Parameter Store as a SecureString so CodeBuild can inject it without exposing it in source control. CodeBuild automatically redacts Parameter Store values from build logs.

{% callout type="info" %}
AWS Secrets Manager is a more modern alternative for storing secrets. If you prefer it, use `env.secrets-manager` in your buildspec instead of `env.parameter-store`. The IAM setup differs. See the [AWS Secrets Manager docs](https://docs.aws.amazon.com/secretsmanager/latest/userguide/intro.html) for details.
{% /callout %}

{% steps %}
{% step title="Open Systems Manager" %}
In the AWS Console, open the **Services** menu and select **Systems Manager** under Management Tools.

{% img src="/images/integrations/bb87939-cb_00_systems_manager.png" alt="AWS Services menu with Systems Manager highlighted" /%}
{% /step %}
{% step title="Open Parameter Store" %}
Select **Parameter Store** from the left navigation.

{% img src="/images/integrations/ed65d07-cb_01_parameter_store.png" alt="Parameter Store option in Systems Manager sidebar" /%}
{% /step %}
{% step title="Create the parameter" %}
Click **Create Parameter**. Set the name to `FOSSA_API_KEY`, the type to **SecureString**, and the value to your FOSSA API key. Click **Create Parameter**.

{% img src="/images/integrations/c0074cb-cb_02_fs_create_key.png" alt="Create Parameter form with FOSSA_API_KEY name, SecureString type, and API key value" /%}
{% /step %}
{% /steps %}

### Granting CodeBuild access to the parameter

CodeBuild runs under a service role that needs explicit permission to read the parameter you just created.

{% steps %}
{% step title="Open IAM" %}
In the AWS Console, open the **Services** menu and select **IAM** under Security, Identity, & Compliance.

{% img src="/images/integrations/a516691-cb_03_iam.png" alt="AWS Services menu with IAM highlighted" /%}
{% /step %}
{% step title="Find the CodeBuild service role" %}
Select **Roles** from the sidebar. Locate the service role for your CodeBuild project, typically named `codebuild-<project-name>-service-role`. Click the role, then expand the attached policy.

{% img src="/images/integrations/dedac3b-cb_04_roles.png" alt="IAM Roles list" /%}

{% img src="/images/integrations/6386f3e-cb_05_expand_policy.png" alt="CodeBuild service role with policy expanded" /%}
{% /step %}
{% step title="Add SSM read permission" %}
Click **Edit policy**, then **Add additional permissions**. Search for and select **SSM** as the service. Under **Actions → Read**, select **GetParameters**.

{% callout type="warning" %}
Select **GetParameters** (plural), not **GetParameter** (singular). CodeBuild uses the bulk form.
{% /callout %}

{% img src="/images/integrations/fdd1481-cb_06_get_parameters.png" alt="SSM Actions with GetParameters selected under Read" /%}
{% /step %}
{% step title="Scope the permission to your parameter" %}
In the **Resources** section, click **Add ARN**. Enter your AWS region, account ID, and `FOSSA_API_KEY` as the fully qualified parameter name. Click **Add**.

{% img src="/images/integrations/6f5eeb2-cb_07_fs_edit_arn.png" alt="Add ARN dialog with region, account ID, and FOSSA_API_KEY filled in" /%}
{% /step %}
{% step title="Save the policy" %}
Click **Review policy**, then **Save changes**.
{% /step %}
{% /steps %}

## Configuring the pipeline

With the key stored and accessible, configure your repository to install and run FOSSA as part of the build.

### Updating buildspec.yml

{% steps %}
{% step title="Add the parameter-store env block" %}
Open `buildspec.yml` in the root of your repository (create it if it doesn't exist). Add an `env` section before `phases` that pulls the `FOSSA_API_KEY` from Parameter Store:

```yaml
version: 0.2

env:
  parameter-store:
    FOSSA_API_KEY: "FOSSA_API_KEY"

phases:
  install:
    commands:
      # ...
```
{% /step %}
{% step title="Call the scan script in post_build" %}
In the `post_build` commands, add `bash sca.sh` to run after your build completes:

```yaml
post_build:
  commands:
    - echo Entering post_build phase...
    - echo Build completed on `date`
    - bash sca.sh
```
{% /step %}
{% /steps %}

{% callout type="info" %}
The full `buildspec.yml` example below is from a sample Java/Maven project. Your `install`, `pre_build`, and `build` phases will differ, only the `env` block and `bash sca.sh` in `post_build` are FOSSA-specific.
{% /callout %}

```yaml
version: 0.2

env:
  parameter-store:
    FOSSA_API_KEY: "FOSSA_API_KEY"

phases:
  install:
    commands:
      - pip install --upgrade awscli
  pre_build:
    commands:
      - echo Entering pre_build phase...
      - echo Test started on `date`
      - mvn clean compile test
  build:
    commands:
      - echo Entering build phase...
      - echo Build started on `date`
      - mvn war:exploded
  post_build:
    commands:
      - echo Entering post_build phase...
      - echo Build completed on `date`
      - bash sca.sh
      - mv target/ROOT .
artifacts:
  type: zip
  files:
    - 'ROOT/WEB-INF/classes/application.properties'
    - 'ROOT/WEB-INF/classes/com/aws/codestar/projecttemplates/HelloWorldAppInitializer.class'
    - 'ROOT/WEB-INF/classes/com/aws/codestar/projecttemplates/configuration/ApplicationConfig.class'
    - 'ROOT/WEB-INF/classes/com/aws/codestar/projecttemplates/configuration/MvcConfig.class'
    - 'ROOT/WEB-INF/classes/com/aws/codestar/projecttemplates/controller/HelloWorldController.class'
    - 'ROOT/WEB-INF/lib/aopalliance-1.0.jar'
    - 'ROOT/WEB-INF/lib/commons-fileupload-1.3.3.jar'
    - 'ROOT/WEB-INF/lib/commons-io-2.5.jar'
    - 'ROOT/WEB-INF/lib/commons-logging-1.2.jar'
    - 'ROOT/WEB-INF/lib/javax.servlet-api-3.1.0.jar'
    - 'ROOT/WEB-INF/lib/spring-aop-4.3.14.RELEASE.jar'
    - 'ROOT/WEB-INF/lib/spring-beans-4.3.14.RELEASE.jar'
    - 'ROOT/WEB-INF/lib/spring-context-4.3.14.RELEASE.jar'
    - 'ROOT/WEB-INF/lib/spring-core-4.3.14.RELEASE.jar'
    - 'ROOT/WEB-INF/lib/spring-expression-4.3.14.RELEASE.jar'
    - 'ROOT/WEB-INF/lib/spring-web-4.3.14.RELEASE.jar'
    - 'ROOT/WEB-INF/lib/spring-webmvc-4.3.14.RELEASE.jar'
    - 'ROOT/WEB-INF/views/index.jsp'
    - 'ROOT/resources/gradients.css'
    - 'ROOT/resources/set-background.js'
    - 'ROOT/resources/styles.css'
    - 'ROOT/resources/tweet.svg'
```

### Creating sca.sh

The `buildspec.yml` calls `bash sca.sh`, which doesn't exist yet. Create it in the root of your repository.

{% steps %}
{% step title="Create and make the script executable" %}
```bash
touch sca.sh && chmod +x sca.sh
```
{% /step %}
{% step title="Add the FOSSA install and analyze commands" %}
```bash
#!/bin/bash

curl -H 'Cache-Control: no-cache' https://raw.githubusercontent.com/fossas/fossa-cli/master/install-latest.sh | bash
fossa analyze
```
{% /step %}
{% /steps %}

Commit both files. On the next CodeBuild run, FOSSA will install and scan your dependencies in the `post_build` phase.

---

Source: https://docs.fossa.com/docs/integrations/azure-repos

# Azure Repos

Connect FOSSA to Azure Repos to import repositories and scan them for license compliance and security issues. The connection uses Azure DevOps OAuth, so an Azure DevOps organization administrator must enable third-party OAuth access before FOSSA can connect.

## Prerequisites

You must be a **Project Collection Administrator** in your Azure DevOps organization to change the OAuth policy.

## Enabling third-party OAuth access in Azure DevOps

{% callout type="danger" %}
FOSSA cannot connect to Azure Repos until third-party application access through OAuth is enabled in your Azure DevOps organization settings.
{% /callout %}

{% steps %}
{% step title="Open Organization settings" %}
Sign in to your Azure DevOps organization at `https://dev.azure.com/{your-organization}` and click **Organization settings** in the bottom-left corner.

{% img src="/images/integrations/46dcde7-OrgSettingsPage.png" alt="Azure DevOps Organization settings page" /%}
{% /step %}
{% step title="Open Policies" %}
In the left menu under **Security**, click **Policies**.
{% /step %}
{% step title="Enable the OAuth toggle" %}
Under **Application connection policies**, toggle on **Third-party application access through OAuth**.

{% img src="/images/integrations/43606a1-OAuthTogglePoliciesPage.png" alt="Third-party application access through OAuth toggle enabled" /%}
{% /step %}
{% /steps %}

Azure Repos is now ready to connect.

## Importing repos from Azure Repos

{% steps %}
{% step title="Open the Add Projects page" %}
In FOSSA, go to **Add Projects** and select the **Quick Import** option. Choose **Azure Repos**.

{% img src="/images/integrations/deb944d-QuickImportScreen.png" alt="Quick Import screen with Azure Repos option" /%}
{% /step %}
{% step title="Connect to Azure DevOps" %}
Click **Connect with Service** to begin the OAuth authorization flow.

{% img src="/images/integrations/6b8e5d5-ConnectToServicesScreen.png" alt="Connect to Services screen" /%}
{% /step %}
{% step title="Grant FOSSA access" %}
In the Azure DevOps authorization page, click **Accept** to grant FOSSA access to your repositories.

{% img src="/images/integrations/8ac5597-Access_Approval.png" alt="Azure DevOps access approval dialog" /%}
{% /step %}
{% step title="Select an organization" %}
If you belong to more than one Azure DevOps organization, select the one you want to import from.

{% img src="/images/integrations/bfa7fd4-ADOOrgDropdown.png" alt="Azure DevOps organization dropdown" /%}

{% callout type="info" %}
If a repository doesn't appear in the list, you may not have granted FOSSA access to that organization. Return to the previous step and repeat the authorization for the correct organization.
{% /callout %}
{% /step %}
{% step title="Select repositories and import" %}
Choose individual repositories to import, or click **Import All** to import everything. When importing all, a dialog lets you review the projects before committing.

{% img src="/images/integrations/a726065-AssignToTeam.png" alt="Import All confirmation dialog" /%}

{% img src="/images/integrations/b18fe23-ImportAll.png" alt="Import All project review screen" /%}

You can filter repositories by **Public**, **Private**, or **All**, by last-updated date, and by whether to include forks.
{% /step %}
{% step title="Configure import settings" %}
Click **Next Step** to configure notifications, updates, and access permissions. The recommended settings are shown below.

{% img src="/images/integrations/2ec91f9-Notifications_only.png" alt="Notifications settings, issues only" /%}

{% img src="/images/integrations/c88213b-Updates.png" alt="Updates settings" /%}

{% img src="/images/integrations/5b1bb94-Access_AND_Badge.png" alt="Access and badge settings" /%}
{% /step %}
{% step title="Assign to teams and confirm" %}
Optionally assign the imported projects to specific teams in your organization, then click **Confirm Import Repos**.

{% callout type="info" %}
Depending on the number of repositories and their sizes, the import may take some time to complete.
{% /callout %}
{% /step %}
{% /steps %}

## Troubleshooting

### Azure Repos commits are no longer triggering new scans

When the OAuth token used for the FOSSA webhook expires or becomes invalid, new commits to Azure Repos stop appearing as project revisions in FOSSA. Regenerating the webhook issues a fresh token.

{% steps %}
{% step title="Open project settings in FOSSA" %}
Navigate to the affected project in FOSSA and go to **Settings → Update Hooks**.

{% img src="/images/integrations/12a3363-Webhook_updated.png" alt="FOSSA project Settings showing Update Hooks" /%}
{% /step %}
{% step title="Regenerate the hook" %}
Click **Auto-Regenerate Hook**. FOSSA will re-authorize with Azure Repos and create a new webhook.

{% img src="/images/integrations/c40436d-Auto-regenerate-webhooks.png" alt="Auto-Regenerate Hook button" /%}
{% /step %}
{% /steps %}

---

Source: https://docs.fossa.com/docs/integrations/bitbucket-cloud

# Bitbucket Cloud

FOSSA integrates with Bitbucket Cloud (bitbucket.org) so your team can import repositories directly and trigger rescans on every push. The integration uses OAuth 2.0, so users authorize FOSSA once and can then browse and import any repo they have access to.

{% callout type="info" %}
This guide covers **Bitbucket Cloud** (bitbucket.org). For self-hosted Bitbucket Server or Data Center, see [Bitbucket Server](/docs/integrations/bitbucket-server).
{% /callout %}

## Connecting your account

Individual users connect their Bitbucket Cloud account from the FOSSA project import flow; no admin configuration is required.

{% steps %}
{% step title="Start a new project import" %}
In FOSSA, click **Add Project** and select **Bitbucket Cloud** as the source.
{% /step %}
{% step title="Authorize FOSSA" %}
FOSSA redirects you to Bitbucket.org. Log in if prompted, then click **Grant Access** to allow FOSSA to read your repositories. You are redirected back to FOSSA.
{% /step %}
{% step title="Select a repository" %}
Browse or search your Bitbucket Cloud workspaces and repositories. Click a repository to import it as a FOSSA project.
{% /step %}
{% /steps %}

## Importing repositories from a workspace

After connecting, FOSSA shows all repositories across every Bitbucket Cloud workspace your account belongs to. Use the workspace selector to filter by workspace, and the search bar to find a specific repo.

## Setting up [automatic updates](/docs/project-setup/automatic-updates) (webhooks)

By default, FOSSA scans when you trigger it manually or on a [schedule](/docs/project-setup/scan-frequency). To have FOSSA rescan automatically on every push, configure a webhook in Bitbucket Cloud.

{% callout type="warning" %}
Automatic webhook updates require a **Premium** FOSSA subscription.
{% /callout %}

{% steps %}
{% step title="Get the webhook URL from FOSSA" %}
Open the project in FOSSA, go to **Settings → Update Hooks**, set the update method to **Webhook**, and copy the **Webhook Update URL**.
{% /step %}
{% step title="Add the webhook in Bitbucket Cloud" %}
In your Bitbucket Cloud repository, go to **Repository settings → Webhooks → Add webhook**.

Fill in:

| Field | Value |
|---|---|
| Title | `FOSSA` (or any label) |
| URL | The Webhook Update URL from FOSSA |
| Triggers | **Repository push** (at minimum) |

Click **Save**.
{% /step %}
{% /steps %}

After saving, every push to the repository triggers FOSSA to re-analyze the project.

## Revoking access

To disconnect FOSSA from your Bitbucket Cloud account, go to your [Bitbucket Cloud account's app authorizations](https://bitbucket.org/account/settings/app-authorizations) and revoke the FOSSA OAuth application. Existing FOSSA projects are not deleted, but FOSSA can no longer fetch new code from Bitbucket until you reconnect.

## FAQ

**Why don't I see a workspace's repositories after connecting?**
FOSSA only shows repos you have **read access** to in Bitbucket Cloud. If a workspace is missing, verify that your Bitbucket Cloud account is a member of that workspace.

**Can I import private repositories?**
Yes. The OAuth authorization grants FOSSA read access to your private repos. FOSSA only reads code to perform analysis and does not store source files.

**What if my organization requires OAuth app approval?**
Some Bitbucket Cloud workspaces require workspace admin approval before OAuth apps can be used. If you see an access error, ask your Bitbucket Cloud workspace admin to approve the FOSSA app under **Workspace settings → OAuth consumers**.

**Does FOSSA support Bitbucket Cloud App Passwords?**
No. FOSSA uses OAuth 2.0 for Bitbucket Cloud authentication. App Passwords are not supported for this integration.

---

Source: https://docs.fossa.com/docs/integrations/bitbucket-server

# Bitbucket Server

{% callout type="info" %}
This integration is only available on FOSSA On-Prem. This guide is written for Bitbucket Server v4.0.6 and later.
{% /callout %}

Connect Bitbucket Server to FOSSA so users can browse and import their internal repositories. The setup has three parts: creating an OAuth1 Application Link so users can authenticate, adding a `fossabot` service account so FOSSA can fetch code, and configuring webhooks so FOSSA rescans on every push.

## Setting up the Application Link

The Application Link lets users log in to Bitbucket Server and view their projects through FOSSA.

{% steps %}
{% step title="Open Application Links" %}
In Bitbucket Server, go to **Settings → Application Links**.

{% img src="/images/integrations/d7c971f-stash-dashboard-view.png" alt="Bitbucket Server settings dashboard" /%}
{% /step %}
{% step title="Create a link to FOSSA" %}
Click **Create link** and enter FOSSA's internal IP address as the application URL.

{% img src="/images/integrations/782989c-stash-add-link-view.png" alt="Add Application Link dialog" /%}

Fill in `fossa` for all options when prompted.

{% img src="/images/integrations/de35c77-stash-add-link.png" alt="Application Link configuration with fossa filled in for all fields" /%}
{% /step %}
{% step title="Generate an RSA keypair" %}
On the machine where FOSSA On-Prem is running, generate a 2048-bit RSA keypair. You will use the **public key** in Bitbucket and the **private key** in FOSSA's configuration.

```bash
openssl genrsa -out privkey.pem 2048
openssl rsa -pubout -in privkey.pem -out pubkey.pem
```

Keep both files. You will need them in the next two steps.
{% /step %}
{% step title="Configure Incoming Authentication" %}
In the Application Links list, find the link you just created and click **Edit → Incoming Authentication**.

{% img src="/images/integrations/17da4d2-stash-edit-link.png" alt="Edit Application Link with Incoming Authentication option" /%}

Fill in the following fields and click **Save** (leave all others blank):

| Field | Value |
|---|---|
| Consumer Key | `fossa` |
| Consumer Name | `fossa` |
| Public Key | *(paste the contents of `pubkey.pem` generated in the previous step)* |

{% callout type="warning" %}
The Public Key field must contain the RSA public key **you generated** in the previous step, not a copied example. Using someone else's public key will mean FOSSA cannot authenticate.
{% /callout %}

{% img src="/images/integrations/b5448be-stash-configure-auth.png" alt="Incoming Authentication form showing Consumer Key, Consumer Name, and Public Key fields" /%}
{% /step %}
{% /steps %}

Users can now connect their Bitbucket Server accounts to FOSSA.

## Adding the fossabot service account

FOSSA requires a `fossabot` account on your Bitbucket Server instance with global read access to fetch code for analysis.

{% callout type="info" %}
`fossabot` is not visible to end users of FOSSA. It acts as an internal proxy for fetching code. Users can only browse and import repositories they already have access to in Bitbucket Server.
{% /callout %}

{% steps %}
{% step title="Create the fossabot user" %}
In Bitbucket Server, go to **Settings → Accounts → Users** and click **Create User**.

{% img src="/images/integrations/214e799-stash-user-admin.png" alt="Bitbucket Server user administration page" /%}

{% img src="/images/integrations/0749aaf-stash-create-user.png" alt="Create User form in Bitbucket Server" /%}

Use the username and password from FOSSA's `config.env` (the defaults are shown below, change them if your deployment uses custom values):

```bash
bitbucket_server__credentials__basic__username=fossabot
bitbucket_server__credentials__basic__password=fossa123
```
{% /step %}
{% step title="Grant global read access" %}
`fossabot` must be able to clone any repository in your Bitbucket Server instance. The simplest way is to grant admin privileges at **Settings → Accounts → Global Permissions**.

{% img src="/images/integrations/788d865-stash-fossabot-admin.png" alt="Global Permissions settings showing fossabot with admin access" /%}

If you need a custom role instead of full admin, ensure the account still has global read access by verifying it can clone repos across different projects.
{% /step %}
{% /steps %}

Users on FOSSA can now browse and import their Bitbucket Server repositories via **Bulk Import**.

## Configuring automatic updates

After importing a project, configure webhooks in both FOSSA and Bitbucket Server so that new commits trigger a rescan automatically.

{% steps %}
{% step title="Enable webhook updates in FOSSA" %}
Open the imported project in FOSSA and go to **Settings → Update Hooks**. Select **Webhook** as the update method and click **Save Changes**. Copy the **Webhook Update URL** shown on the page.
{% /step %}
{% step title="Create a webhook in Bitbucket Server" %}
Bitbucket Server and Data Center have webhooks built in. In the project's repository settings, open **Webhooks** and click **Create webhook**. See Atlassian's [Manage webhooks](https://confluence.atlassian.com/bitbucketserver/manage-webhooks-938025878.html) guide for details. (Older instances without native webhooks can use the legacy Post-Receive Webhooks add-on instead.)
{% /step %}
{% step title="Point the webhook at FOSSA" %}
Paste the **Webhook Update URL** from step 1 as the webhook URL, enable the webhook for repository push events, and save.
{% /step %}
{% /steps %}

## On-Prem Helm configuration

If you are deploying FOSSA On-Prem via Helm, configure Bitbucket Server in your `input-values.yaml`. The `privateKey` must match the private key you generated during the Application Link setup.

{% callout type="warning" %}
The `input-values.yaml` schema is defined in the FOSSA On-Prem Helm chart, not the application code. Confirm the exact key names against your installed chart version before deploying.
{% /callout %}

```yaml
bitbucketEnterprise:
  url: http://bitbucket.your-company.com
  cloneWithSSH: false  # set to true to clone over SSH; also configure fetchers.git

  ## OAuth1 credentials (from Application Link setup)
  clientId: fossa
  privateKey: |-
    -----BEGIN RSA PRIVATE KEY-----
    # paste the contents of privkey.pem here
    -----END RSA PRIVATE KEY-----

  ## Basic auth credentials (must match fossabot account)
  username: fossabot
  password: fossa123
```

If you have any problems, contact support at [support@fossa.com](mailto:support@fossa.com).

---

Source: https://docs.fossa.com/docs/integrations/circleci

# CircleCI

Add FOSSA to your CircleCI pipeline to upload dependency data on every build and optionally gate builds on your FOSSA policy status.

## Prerequisites

- FOSSA CLI installed locally or available in your build image. Install it with:

  ```bash
  curl -H 'Cache-Control: no-cache' https://raw.githubusercontent.com/fossas/fossa-cli/master/install-latest.sh | bash
  fossa --help
  ```

- A FOSSA API key from [**Settings → Integrations → API Tokens**](https://app.fossa.com/account/settings/integrations/api_tokens).

  {% img src="/images/integrations/7851253-api-token-creation.png" alt="FOSSA API token creation screen" /%}

  {% callout type="info" %}
  If you maintain a public repository, use a **Push Only** token so the key cannot be used to read sensitive data from your FOSSA account.
  {% /callout %}

## Adding FOSSA to `.circleci/config.yml`

{% steps %}
{% step title="Add FOSSA_API_KEY to CircleCI environment variables" %}
In your CircleCI project settings, add `FOSSA_API_KEY` as an environment variable and set its value to your API key.

{% img src="/images/integrations/7b30baf-Screen_Shot_2018-03-30_at_11.50.46_AM.png" alt="CircleCI environment variables settings showing FOSSA_API_KEY" /%}
{% /step %}
{% step title="Install the CLI in your build job" %}
Add a `run` step to install `fossa-cli` before the `checkout` step of your `build` job:

```yaml
jobs:
  build:
    steps:
      - run: |
          curl -H 'Cache-Control: no-cache' https://raw.githubusercontent.com/fossas/fossa-cli/master/install-latest.sh | bash
      - checkout
```
{% /step %}
{% step title="Run fossa analyze after your build" %}
Add a `fossa analyze` step immediately after your build or install steps, before any tests run:

```yaml
      - run:
          command: fossa analyze
          working_directory: <repo_dir>
```

**Full example:**

```yaml
version: 2
jobs:
  build:
    docker:
      - image: circleci/<language>:<version tag>
    steps:
      - run: |
          curl -H 'Cache-Control: no-cache' https://raw.githubusercontent.com/fossas/fossa-cli/master/install-latest.sh | bash
      - checkout
      - run: <build command>
      - run:
          command: fossa analyze
          working_directory: <repo_dir>
workflows:
  version: 2
  build:
    jobs:
      - build
```

With this in place, every CI build uploads dependency data to FOSSA for analysis.
{% /step %}
{% /steps %}

{% callout type="info" %}
To customise which targets FOSSA analyses, add a `.fossa.yml` file to the root of your repository. See the [.fossa.yml reference](https://github.com/fossas/fossa-cli/blob/master/docs/references/files/fossa-yml.md) on GitHub.
{% /callout %}

## Blocking builds on FOSSA policy status

Add a `fossa test` step to fail the build when FOSSA detects policy violations.

{% img src="/images/integrations/07e7362-Screen_Shot_2018-03-30_at_12.02.25_PM.png" alt="CircleCI build showing a FOSSA test step with pass/fail status" /%}

`fossa test` polls FOSSA until the scan completes, then exits with a non-zero status if any issues violate your policy, blocking the build. It also renders issue details inline in the CircleCI test results.

Add it to your `test` job:

```yaml
      - run:
          command: fossa test
          working_directory: <repo_dir>
```

The default timeout is **600 seconds** (10 minutes). Override it with `--timeout`:

```bash
fossa test --timeout 300
```

See the [fossa test reference](https://github.com/fossas/fossa-cli/blob/master/docs/references/subcommands/test.md#specifying-a-timeout) for details.

**Full example with both jobs:**

```yaml
version: 2
jobs:
  build:
    docker:
      - image: circleci/<language>:<version tag>
    steps:
      - run: |
          curl -H 'Cache-Control: no-cache' https://raw.githubusercontent.com/fossas/fossa-cli/master/install-latest.sh | bash
      - checkout
      - run: <build command>
      - run:
          command: fossa analyze
          working_directory: <repo_dir>
  test:
    docker:
      - image: circleci/<language>:<version tag>
    steps:
      - checkout
      - run: <test command>
      - run:
          command: fossa test
          working_directory: <repo_dir>
workflows:
  version: 2
  build_and_test:
    jobs:
      - build
      - test
```

## Triggering updates via webhook (CircleCI 1.0 only)

{% callout type="warning" %}
The `notify.webhooks` block below is a **CircleCI 1.0** feature and does not work in CircleCI 2.0+ `config.yml` files. Most users running CircleCI 2.0+ should use `fossa analyze` in a `run` step instead (see above). Only use this section if you are on CircleCI 1.0 with **Automated Builds** and no other update strategy.
{% /callout %}

Add the following to your `circle.yml` file:

```yaml
notify:
  webhooks:
    - url: https://app.fossa.com/hooks/circleci
```

Then in FOSSA, go to **Project → Settings → Update Hooks** and select **CircleCI** in the dropdown.

---

Source: https://docs.fossa.com/docs/integrations/concourse-ci

# Concourse CI

Add FOSSA to your Concourse CI pipeline to upload dependency data and gate builds on policy status with every run.

## Prerequisites

- A FOSSA API key from [**Settings → Integrations → API Tokens**](https://app.fossa.com/account/settings/integrations/api_tokens).

  {% img src="/images/integrations/7851253-api-token-creation.png" alt="FOSSA API token creation screen" /%}

- The FOSSA CLI available in your pipeline's build environment. To test it locally before wiring it into your pipeline:

  ```bash
  curl -H 'Cache-Control: no-cache' https://raw.githubusercontent.com/fossas/fossa-cli/master/install-latest.sh | bash
  fossa --help
  ```

## Adding FOSSA to your pipeline

The FOSSA job runs after your existing build-and-test job, downloads the CLI, and runs `fossa analyze` and `fossa test` against your freshly-built code. The API key is injected via Concourse's params block so it never appears in source control.

{% steps %}
{% step title="Add the fossa_run job to your pipeline.yml" %}
Add the following job after your existing build job under `jobs:`. It chains off `build_and_test` (adjust `passed:` to match the name of your own build job):

```yaml
- name: fossa_run
  public: true
  plan:
    - get: nodejs.org-git
      passed: [build_and_test]
      trigger: true
    - task: run-fossa
      config:
        platform: linux
        image_resource:
          type: registry-image
          source: {repository: node, tag: "lts"}
        inputs:
          - name: nodejs.org-git
        run:
          path: /bin/sh
          args:
            - -c
            - |
              echo "Node Version: $(node --version)"
              echo "NPM Version: $(npm --version)"
              curl -H 'Cache-Control: no-cache' https://raw.githubusercontent.com/fossas/fossa-cli/master/install-latest.sh | bash
              cd nodejs.org-git
              fossa analyze
              fossa test
        params:
          FOSSA_API_KEY: ((fossa_api_key))
```

`fossa analyze` uploads dependency data to FOSSA. `fossa test` polls FOSSA for the scan result and exits non-zero if any issues violate your policy, failing the build.
{% /step %}
{% step title="Set the pipeline with fly" %}
Apply the updated pipeline configuration:

```bash
fly -t <target> set-pipeline -p <pipeline-name> -c pipeline.yml
```

Then pass in your FOSSA API key as a pipeline variable:

```bash
fly -t <target> set-pipeline -c pipeline.yml -p <pipeline-name> -v fossa_api_key=<your-api-key>
```

Every subsequent build will upload a dependency report to FOSSA and block on policy failures.
{% /step %}
{% /steps %}

## Full pipeline.yml example

The complete pipeline below builds and tests a Node.js project, then runs FOSSA in a chained job:

```yaml
---
resources:
  - name: nodejs.org-git
    type: git
    icon: github-circle
    source:
      uri: https://github.com/nodejs/nodejs.org.git

jobs:
  - name: build_and_test
    public: true
    plan:
      - get: nodejs.org-git
        trigger: true
      - task: run-tests
        config:
          platform: linux
          image_resource:
            type: registry-image
            source: {repository: node, tag: "lts"}
          inputs:
            - name: nodejs.org-git
          run:
            path: /bin/sh
            args:
              - -c
              - |
                echo "Node Version: $(node --version)"
                echo "NPM Version: $(npm --version)"
                cd nodejs.org-git
                npm install
                npm test

  - name: fossa_run
    public: true
    plan:
      - get: nodejs.org-git
        passed: [build_and_test]
        trigger: true
      - task: run-fossa
        config:
          platform: linux
          image_resource:
            type: registry-image
            source: {repository: node, tag: "lts"}
          inputs:
            - name: nodejs.org-git
          run:
            path: /bin/sh
            args:
              - -c
              - |
                echo "Node Version: $(node --version)"
                echo "NPM Version: $(npm --version)"
                curl -H 'Cache-Control: no-cache' https://raw.githubusercontent.com/fossas/fossa-cli/master/install-latest.sh | bash
                cd nodejs.org-git
                fossa analyze
                fossa test
          params:
            FOSSA_API_KEY: ((fossa_api_key))
```

{% callout type="info" %}
To control which targets FOSSA analyses, add a `.fossa.yml` file to the root of your repository. See the [.fossa.yml reference](https://github.com/fossas/fossa-cli/blob/master/docs/references/files/fossa-yml.md) on GitHub.
{% /callout %}

---

Source: https://docs.fossa.com/docs/integrations/generic-ci

# Generic CI

Add FOSSA to any CI pipeline to upload dependency data on every build and optionally gate builds on your FOSSA policy status. The steps below apply to any CI system; adapt the syntax to your platform's configuration format.

## Prerequisites

- A FOSSA API key from [**Settings → Integrations → API Tokens**](https://app.fossa.com/account/settings/integrations/api_tokens).

  {% img src="/images/integrations/7851253-api-token-creation.png" alt="FOSSA API token creation screen" /%}

- Store the key as a CI environment variable named `FOSSA_API_KEY`. Most CI systems have a secrets or environment variables UI in their project settings; never commit the key to source control.

## Running fossa analyze

{% steps %}
{% step title="Install the FOSSA CLI" %}
Add a step early in your build, before tests run, to download and install the CLI:

```bash
curl -H 'Cache-Control: no-cache' https://raw.githubusercontent.com/fossas/fossa-cli/master/install-latest.sh | sudo bash
```

Place this after your dependency install commands (e.g. `npm install`, `bundle install`) so the CLI has access to a fully-built environment.
{% /step %}
{% step title="Run fossa analyze" %}
Immediately after your build steps, add:

```bash
fossa analyze
```

This uploads a dependency snapshot to FOSSA. Run it before tests so FOSSA always sees a complete, freshly-built dependency graph.
{% /step %}
{% /steps %}

Every build will now upload a dependency report to your FOSSA instance.

{% callout type="info" %}
To control which targets FOSSA analyses, add a `.fossa.yml` file to the root of your repository. See the [.fossa.yml reference](https://github.com/fossas/fossa-cli/blob/master/docs/references/files/fossa-yml.md) on GitHub.
{% /callout %}

## Blocking builds on FOSSA policy status

Add a `fossa test` step after `fossa analyze` to fail the build when FOSSA detects policy violations:

```bash
fossa test
```

`fossa test` polls FOSSA until the scan result is ready, then exits non-zero if any issues violate your policy. The default timeout is **600 seconds** (10 minutes); override it with:

```bash
fossa test --timeout 300
```

See the [fossa test reference](https://github.com/fossas/fossa-cli/blob/master/docs/references/subcommands/test.md#specifying-a-timeout) for details.

---

Source: https://docs.fossa.com/docs/integrations/github-actions

# GitHub Actions

The [official FOSSA Action](https://github.com/marketplace/actions/official-fossa-action) runs the FOSSA CLI inside your GitHub Actions workflow. At minimum it needs an API key. It installs the latest CLI, runs `fossa analyze` on your checked-out code, and can optionally gate the build with `fossa test`.

## When to use this

This is the fastest way to get dynamic analysis from a GitHub project. It sits between the two other GitHub options:

- **[GitHub App](/docs/integrations/github-app)** / **[GitHub OAuth](/docs/integrations/github)**: source-host import. Minimal setup, but FOSSA runs the build itself. Best when you want managed, hands-off scanning and don't need to reproduce a real build.
- **GitHub Actions (this page):** minimal setup *and* dynamic analysis. The Action runs in your actual workflow, so FOSSA sees the real, freshly-built dependency graph (a [CI/CD scan](/docs/project-setup/cicd-scanning)) without you hand-writing CLI install scripts.
- **[Generic CI](/docs/integrations/generic-ci):** the manual equivalent if you outgrow the Action or need full control over the CLI invocation.

{% callout type="info" %}
The Action is intended as a quick, easy entry point. For more customization, or to scan on Windows runners (which the Action does not support), [integrate the FOSSA CLI directly](/docs/integrations/generic-ci) in your workflow instead.
{% /callout %}

## Prerequisites

- A FOSSA API key from [**Settings → Integrations → API Tokens**](https://app.fossa.com/account/settings/integrations/api_tokens).

  {% callout type="info" %}
  If you maintain a public repository, use a **Push Only** token so the key cannot be used to read sensitive data from your FOSSA account.
  {% /callout %}

- A Linux or macOS runner. Windows runners are not supported. Container scanning additionally requires a running Docker daemon, which GitHub's macOS runners do not provide.

## Quickstart

{% steps %}
{% step title="Store your API key as a secret" %}
In your repository, go to **Settings → Secrets and variables → Actions** and add a secret named `FOSSA_API_KEY` set to your API key. Never commit the key to source control.
{% /step %}
{% step title="Add the Action to a workflow" %}
Create or edit a workflow file (for example `.github/workflows/fossa.yml`). Check out your code, then add the FOSSA Action:

```yaml
name: FOSSA
on: [push, pull_request]

jobs:
  fossa-scan:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: fossas/fossa-action@main # pin to a specific version if locking is preferred
        with:
          api-key: ${{ secrets.FOSSA_API_KEY }}
```

This runs `fossa analyze` and uploads a dependency snapshot to FOSSA on every push and pull request.
{% /step %}
{% step title="Gate the build on policy status" %}
Add `run-tests: true` to fail the build when FOSSA finds license or security issues that violate your policy. A scan must complete first, so run analysis before tests:

```yaml
      - uses: fossas/fossa-action@main
        with:
          api-key: ${{ secrets.FOSSA_API_KEY }}
          run-tests: true
```
{% /step %}
{% /steps %}

{% callout type="info" %}
The Action's version does **not** track the FOSSA CLI version. By default it always installs the [latest CLI release](https://github.com/fossas/fossa-cli/releases). Pin the CLI with [`pinned-cli-version`](#inputs) if you need a fixed version.
{% /callout %}

## Inputs

| Input | Required | Description |
|---|---|---|
| `api-key` | Yes | Your FOSSA API key. |
| `run-tests` | No | Set to `true` to run `fossa test` after analysis. Defaults to `false`. |
| `container` | No | A container name or OCI image path. Runs `fossa container analyze` (and `fossa container test` with `run-tests`). Requires a Docker daemon. |
| `test-diff-revision` | No | Run `fossa test --diff <revision>` to check only for issues new relative to a revision. Requires `run-tests: true`. |
| `generate-report` | No | A [report format](https://github.com/fossas/fossa-cli/blob/master/docs/references/subcommands/report.md#specifying-a-report-format) (e.g. `html`). Generates an attribution report exposed as the `report` output. |
| `branch` | No | Override the detected FOSSA project branch. |
| `project` | No | Override the detected FOSSA project name. |
| `team` | No | Assign the project to a team by name. Applies only when the project is first created. |
| `policy` | No | Assign a policy to the project by name. Applies only when the project is first created. |
| `endpoint` | No | FOSSA endpoint. Defaults to `app.fossa.com`. Set this for [on-premises](/docs/on-premises) instances. |
| `working-directory` | No | The directory to analyze. Defaults to the workspace root. |
| `include-unused-deps` | No | Set to `true` to pass `--include-unused-deps` to `fossa analyze`. No effect when `container` is set. |
| `pinned-cli-version` | No | Pin the FOSSA CLI to a specific version instead of the latest release. |
| `debug` | No | Set to `true` to run all FOSSA commands in debug mode and produce a debug bundle. Defaults to `false`. |

**Output:** `report`. When `generate-report` is set, contains the report contents in the requested format.

## Common patterns

### Test only new issues on pull requests

Run `fossa test` against the PR base so the build fails only on issues the PR introduces, not pre-existing ones:

```yaml
      - uses: fossas/fossa-action@main
        with:
          api-key: ${{ secrets.FOSSA_API_KEY }}
          run-tests: ${{ github.event_name == 'pull_request' }}
          test-diff-revision: ${{ github.event.pull_request.base.sha }}
```

### Container scanning

Scan a built image with `fossa container analyze`. Replace `ubuntu:20.04` with your image:

```yaml
      - uses: fossas/fossa-action@main
        with:
          api-key: ${{ secrets.FOSSA_API_KEY }}
          container: ubuntu:20.04
          run-tests: true
```

### Generate an attribution report

Capture the report from the step output and write it to a file:

```yaml
      - id: fossa
        uses: fossas/fossa-action@main
        with:
          api-key: ${{ secrets.FOSSA_API_KEY }}
          run-tests: true
          generate-report: html
      - run: echo '${{ steps.fossa.outputs.report }}' > report.html
```

### Upload a debug bundle

Run in debug mode and upload the resulting bundle as a build artifact for troubleshooting:

```yaml
      - uses: fossas/fossa-action@main
        with:
          api-key: ${{ secrets.FOSSA_API_KEY }}
          debug: true
      - uses: actions/upload-artifact@v4
        with:
          name: fossa.debug.json.gz
          path: ./fossa.debug.json.gz
```

### Point at an on-premises instance

```yaml
      - uses: fossas/fossa-action@main
        with:
          api-key: ${{ secrets.FOSSA_API_KEY }}
          endpoint: fossa.my-company.com
```

{% callout type="info" %}
To control which targets FOSSA analyzes, add a `.fossa.yml` file to the root of your repository. See the [.fossa.yml reference](https://github.com/fossas/fossa-cli/blob/master/docs/references/files/fossa-yml.md) on GitHub.
{% /callout %}

---

Source: https://docs.fossa.com/docs/integrations/github

# GitHub

FOSSA supports two GitHub integration methods. Both let you import repositories and scan pull requests, but they differ in how permissions are scoped and how access survives personnel changes.

{% callout type="info" %}
This page covers connecting GitHub as a source host so FOSSA can import and build your repositories. To run analysis as a step in your own CI pipeline instead, see [GitHub Actions](/docs/integrations/github-actions).
{% /callout %}

## OAuth vs GitHub App

| | GitHub OAuth | GitHub App |
|---|---|---|
| **Permissions** | Read/write all public repo data; read org membership, team membership, private project boards; read/write repo webhooks | Read code and metadata; read/write commit statuses, pull requests, and webhooks |
| **Repository scope** | All repos the authenticated user can access | All current and future repos, or selected repos only |
| **GitHub editions** | Cloud, Enterprise Cloud, Enterprise Server | Cloud, Enterprise Cloud |
| **Access tied to** | An individual user account | The app installation; survives user departures |

**Recommendation:** GitHub App provides more conservative, granular permissions and is the preferred method for most organizations. OAuth is simpler to set up and scales well when the authorizing user is a long-lived service account.

For GitHub App setup instructions, see [GitHub App](/docs/integrations/github-app).

## GitHub Cloud: OAuth

If you are not seeing repos or organizations after connecting with OAuth, work through the following checks.

### Verifying org membership

The user account you authorized with must be a member of the GitHub organization you want to import from. Check at `https://github.com/orgs/{YOUR_ORG}/people`; the account should appear in the list. If not, add it as a member with global read access.

### Granting org access to FOSSA

If you authorized FOSSA before granting it access to a specific organization, FOSSA's OAuth app will not have permission to see that org's repositories.

{% steps %}
{% step title="Revoke and re-authorize" %}
Go to [**GitHub → Settings → Applications → Authorized OAuth Apps**](https://github.com/settings/applications) and revoke any existing FOSSA access.

Then reconnect at [**app.fossa.com/projects/import/github**](https://app.fossa.com/projects/import/github). When GitHub shows the authorization screen, look for your organization under **Organization access** before clicking **Authorize**. Your organization should show a green check mark. If it shows a **Request** or **Grant** button instead, click it; an organization owner must approve the request before you can continue.
{% /step %}
{% step title="Approve from the org side" %}
An organization owner can approve third-party OAuth access at:

```
https://github.com/organizations/{YOUR_ORGANIZATION}/settings/oauth_application_policy
```

If your organization has third-party access restrictions enabled, make sure FOSSA is listed as an approved application.
{% /step %}
{% /steps %}

If you already authorized FOSSA without granting org access, you can fix it without re-authorizing. Go to [**GitHub → Settings → Applications → Authorized OAuth Apps**](https://github.com/settings/applications), click the FOSSA app, and find your organization at the bottom of the page:

{% img src="/images/integrations/9abb0ee-oauth-apps-settings_annotated.png" alt="Authorized OAuth Apps page showing FOSSA with organization access section" /%}

{% img src="/images/integrations/ba21409-app-org-permissions_annotated.png" alt="FOSSA app page showing organization with Request button" /%}

Click **Request** and have an organization owner approve it.

## GitHub Enterprise: OAuth (On-Prem)

{% callout type="info" %}
This section covers integrating a self-hosted FOSSA appliance with GitHub Enterprise behind the firewall.
{% /callout %}

### Creating the OAuth App in GitHub Enterprise

{% steps %}
{% step title="Register a new OAuth App" %}
In your GitHub Enterprise instance, navigate to:

```
{GITHUB_URL}/organizations/{ORGANIZATION_NAME}/settings/applications
```

{% img src="/images/integrations/395f06f-Screen_Shot_2018-05-22_at_10.49.56_AM.png" alt="GitHub Enterprise organization applications settings page" /%}

Create a new OAuth App and set the **Authorization callback URL** to:

```
{FOSSA_HOST}/api/services/github/authorize/callback
```
{% /step %}
{% step title="Copy the Client ID and Client Secret" %}
After creating the app, note the **Client ID** and **Client Secret**; you will need them in the next step.
{% /step %}
{% /steps %}

### Configuring FOSSA

SSH into the FOSSA appliance and edit `config.env`. Add or update the following:

```bash
github__enabled=true
github__base_url={GITHUB_HOST}
github__enterprise=true

github__credentials__oauth2__client_id={GITHUB_CLIENT_ID}
github__credentials__oauth2__client_secret={GITHUB_CLIENT_SECRET}
github__credentials__oauth2__callback={FOSSA_HOST}/api/services/github/authorize/callback
```

Then restart FOSSA:

```bash
fossa restart
```

Users can now sign in with their GitHub Enterprise accounts and import repositories.

---

Source: https://docs.fossa.com/docs/integrations/github-app

# GitHub App

The FOSSA GitHub App provides more conservative and granular permissions than OAuth: access is tied to an app installation rather than an individual user account, so it survives team changes. You can scope it to all repositories or a selected subset.

## How it works

When an organization installs the FOSSA GitHub App, GitHub generates an installation access token that FOSSA uses to read code, post commit statuses, and manage pull request checks. Webhooks notify FOSSA of new pushes and PR events automatically, with no per-project webhook setup required.

## Required permissions

Configure the following when creating the GitHub App in GitHub. The **Minimum** column is what FOSSA requires for core functionality; permissions marked N/A are not used.

### Repository permissions

| Permission | FOSSA uses | Minimum required |
|---|---|---|
| Commit statuses | Post scan results to commits | Read & Write |
| Contents | Read repository code | Read |
| Issues | Link FOSSA issues to GitHub issues | Read & Write |
| Metadata | Repository metadata (always required by GitHub) | Read |
| Pull requests | Post PR check results and comments | Read & Write |
| Webhooks | Receive push and PR events | Read & Write |
| Actions, Administration, Checks, Deployments, Packages, Pages, Projects | Not used | N/A |

### Organization permissions

No organization permissions are required. All organization-level permissions should be set to N/A.

## Installing on GitHub Cloud

For FOSSA Cloud, the app is already registered; users just need to install it on their organization.

{% steps %}
{% step title="Start the installation" %}
In FOSSA, go to **Add Projects → Quick Import → GitHub App**. FOSSA will redirect you to the GitHub App installation page.

Alternatively, navigate directly to `https://github.com/apps/{FOSSA_APP_NAME}/installations/new`.
{% /step %}
{% step title="Select repositories" %}
Choose **All repositories** to give FOSSA access to all current and future repos, or **Only select repositories** to scope access to specific ones. Click **Install**.
{% /step %}
{% step title="Import projects" %}
Return to FOSSA's Add Projects page. Your repositories will now appear under the GitHub App import option.
{% /step %}
{% /steps %}

## Setting up on On-Prem

{% callout type="info" %}
Cloud customers use FOSSA's pre-registered app; the steps below are only needed for self-hosted FOSSA appliances.
{% /callout %}

### Creating the GitHub App in GitHub

{% steps %}
{% step title="Register a new GitHub App" %}
In GitHub, navigate to **Settings → Developer settings → GitHub Apps → New GitHub App** (for personal accounts), or **Organization Settings → Developer settings → GitHub Apps** (for org-owned apps).

Fill in the following:

- **GitHub App name:** choose a name (this becomes the app slug used in install URLs)
- **Homepage URL:** your FOSSA instance URL (e.g., `https://fossa.yourcompany.com`)
- **Webhook URL:** `{FOSSA_HOST}/api/services/github-app/webhook`
- **Webhook secret:** generate a strong random string and note it
{% /step %}
{% step title="Set repository permissions" %}
Under **Repository permissions**, configure exactly the values from the [required permissions](#required-permissions) table above. Leave all organization permissions as N/A.
{% /step %}
{% step title="Subscribe to events" %}
Under **Subscribe to events**, enable:
- **Push**
- **Pull request**
- **Installation** (to track installs and uninstalls)
{% /step %}
{% step title="Generate a private key" %}
After saving the app, scroll to the bottom of the app settings page and click **Generate a private key**. GitHub downloads a `.pem` file; keep this secure.

Also note the **App ID** shown at the top of the app settings page, and the **Client ID** and **Client Secret** under OAuth credentials.
{% /step %}
{% /steps %}

### Configuring FOSSA

SSH into the FOSSA appliance and edit `config.env`. Add or update the following:

```bash
github_app__enabled=true
github_app__base_url={GITHUB_HOST}
github_app__app_id={APP_ID}
github_app__app_name={APP_SLUG}

github_app__credentials__oauth2__client_id={CLIENT_ID}
github_app__credentials__oauth2__client_secret={CLIENT_SECRET}
github_app__credentials__webhook_secret={WEBHOOK_SECRET}
github_app__credentials__private_key={PEM_CONTENT}
```

For `github_app__credentials__private_key`, paste the full contents of the `.pem` file downloaded in the previous step.

Then restart FOSSA:

```bash
fossa restart
```

### Installing the app

Once FOSSA is restarted, users install the app by visiting:

```
https://{GITHUB_HOST}/apps/{APP_SLUG}/installations/new
```

Or from within FOSSA: **Add Projects → Quick Import → GitHub App**.

## Reference: config keys

| Key | Description |
|---|---|
| `github_app__enabled` | Set to `true` to enable the GitHub App integration |
| `github_app__base_url` | Root URL of your GitHub instance (default: `https://github.com/`) |
| `github_app__app_id` | Numeric App ID from the GitHub App settings page |
| `github_app__app_name` | App slug; appears in install URLs |
| `github_app__credentials__oauth2__client_id` | OAuth Client ID from the GitHub App settings page |
| `github_app__credentials__oauth2__client_secret` | OAuth Client Secret |
| `github_app__credentials__webhook_secret` | Secret used to validate incoming webhook payloads |
| `github_app__credentials__private_key` | Full PEM content of the generated private key |

---

Source: https://docs.fossa.com/docs/integrations/gitlab

# GitLab

{% callout type="info" %}
FOSSA connects to GitLab.com out of the box, so users can sign in with GitLab immediately with no configuration. This guide covers two scenarios: (1) adding a self-managed GitLab instance from the FOSSA SaaS settings UI, and (2) integrating a self-hosted FOSSA appliance with a self-hosted GitLab instance behind the firewall.
{% /callout %}

## Adding a self-managed GitLab instance (SaaS)

If you run FOSSA SaaS but your code lives on a self-managed GitLab instance (e.g., `gitlab.yourcompany.com`), you can add that instance from your organization settings; no on-prem FOSSA deployment required.

{% steps %}
{% step title="Open GitLab integrations" %}
Go to Settings → Integrations → GitLab.
{% /step %}
{% step title="Add an instance" %}
Click **Connect to GitLab** and enter the base URL of your self-managed GitLab (for example, `https://gitlab.yourcompany.com`).
{% /step %}
{% step title="Register FOSSA as an OAuth application" %}
In your self-managed GitLab instance, navigate to **Admin → Applications** and create a new application with:

| Field | Value |
|---|---|
| Name | `FOSSA` |
| Redirect URI | The callback URL shown in the FOSSA settings UI |
| Scopes | `read_user`, `read_api`, `read_repository` |

Copy the **Application ID** and **Secret** after saving.
{% /step %}
{% step title="Enter credentials in FOSSA" %}
Back in FOSSA, enter the **Application ID** and **Secret** from the previous step, then click **Save**.
{% /step %}
{% step title="Connect user accounts" %}
Users who want to import from this instance must connect their GitLab account once. They will be prompted to authorize FOSSA when they first try to import a project from the new instance.
{% /step %}
{% /steps %}

After setup, users can import repositories from your self-managed GitLab instance in the same flow as GitLab.com.

## Connecting GitLab to FOSSA on-prem

{% steps %}
{% step title="Register FOSSA as a GitLab OAuth application" %}
Sign in to your GitLab instance with an administrator account and navigate to:

```
{GITLAB_HOST}/-/profile/applications
```

(For older GitLab versions: `{GITLAB_HOST}/profile/applications`)

Or go to **User Settings → Applications → Add New Application**.

Fill in the application details and save.

{% img src="/images/integrations/4fe7d8b-gitlab-add-app.png" alt="GitLab Add New Application form for FOSSA" /%}

After saving, GitLab shows the **Application ID**, **Secret**, and **Callback URL**. Copy all three; you will need them in the next step.

{% img src="/images/integrations/e1236ec-gitlab-view-creds.png" alt="GitLab application credentials showing Application ID, Secret, and Callback URL" /%}
{% /step %}
{% step title="Add GitLab credentials to FOSSA" %}
SSH into the FOSSA appliance and edit `config.env`. Add or update the following:

```bash
# Base config
gitlab__enabled=true
gitlab__base_url={GITLAB_HOST}

# Credentials from the previous step
gitlab__credentials__oauth2__client_id={APPLICATION_ID}
gitlab__credentials__oauth2__client_secret={SECRET}
gitlab__credentials__oauth2__callback={CALLBACK_URL}
```

Replace `{GITLAB_HOST}` with your GitLab instance URL (protocol included, e.g. `https://gitlab.yourcompany.com`).
{% /step %}
{% step title="Restart FOSSA" %}
While still in your SSH session, run:

```bash
fossa restart
```

Wait for FOSSA to finish booting. Users can now sign in with their GitLab accounts and import repositories.
{% /step %}
{% /steps %}

## What's next

- **[CI/CD Scanning](/docs/project-setup/cicd-scanning):** run FOSSA analysis automatically on every push from your GitLab repositories.
- **[PR Checks](/docs/project-setup/pr-checks):** surface license and vulnerability issues directly in GitLab merge requests.
- **[Fail CI/CD Checks](/docs/integrations/fail-cicd-checks):** block merges when FOSSA detects policy violations.

---

Source: https://docs.fossa.com/docs/integrations/jenkins

# Jenkins

Add FOSSA to your Jenkins pipeline to upload dependency data on every build and optionally gate builds on your FOSSA policy status.

## Prerequisites

- A FOSSA API key from [**Settings → Integrations → API Tokens**](https://app.fossa.com/account/settings/integrations/api_tokens).

  {% callout type="info" %}
  If you maintain a public repository, use a **Push Only** token so the key cannot be used to read sensitive data from your FOSSA account.
  {% /callout %}

- Store the key as a Jenkins credential. In Jenkins, go to **Manage Jenkins → Credentials** and add a **Secret text** credential with the ID `FOSSA_API_KEY`. Then expose it to your pipeline using the `withCredentials` or `environment` block (see the examples below).

## Adding FOSSA to your Jenkinsfile

### Running fossa analyze

Add a `Fossa Analyze` stage immediately after your build stage, before tests run, so FOSSA has access to a freshly-built dependency graph:

```groovy
pipeline {
    agent any
    environment {
        FOSSA_API_KEY = credentials('FOSSA_API_KEY')
    }
    stages {
        stage('Checkout') {
            steps {
                git 'https://github.com/your-org/your-repo.git'
            }
        }
        stage('Build') {
            steps {
                sh 'npm install'
            }
        }
        stage('Fossa Analyze') {
            steps {
                sh 'curl -H \'Cache-Control: no-cache\' https://raw.githubusercontent.com/fossas/fossa-cli/master/install-latest.sh | bash'
                sh 'fossa analyze'
            }
        }
    }
}
```

The `environment` block injects the credential as `$FOSSA_API_KEY`, which the CLI picks up automatically. Every build will upload a dependency report to FOSSA.

{% callout type="info" %}
To control which targets FOSSA analyses, add a `.fossa.yml` file to the root of your repository. See the [.fossa.yml reference](https://github.com/fossas/fossa-cli/blob/master/docs/references/files/fossa-yml.md) on GitHub.
{% /callout %}

### Blocking builds on FOSSA policy status

Add a `Fossa Test` stage to fail the build when FOSSA detects policy violations:

```groovy
        stage('Fossa Test') {
            steps {
                sh 'fossa test'
            }
        }
```

`fossa test` polls FOSSA until the scan result is ready, then exits non-zero if any issues violate your policy, blocking the build. The default timeout is **600 seconds** (10 minutes). Override it with:

```groovy
sh 'fossa test --timeout 300'
```

See the [fossa test reference](https://github.com/fossas/fossa-cli/blob/master/docs/references/subcommands/test.md#specifying-a-timeout) for details.

## Full Jenkinsfile example

```groovy
pipeline {
    agent any
    environment {
        FOSSA_API_KEY = credentials('FOSSA_API_KEY')
    }
    stages {
        stage('Checkout') {
            steps {
                git 'https://github.com/your-org/your-repo.git'
            }
        }
        stage('Build') {
            steps {
                sh 'npm install'
            }
        }
        stage('Fossa Analyze') {
            steps {
                sh 'curl -H \'Cache-Control: no-cache\' https://raw.githubusercontent.com/fossas/fossa-cli/master/install-latest.sh | bash'
                sh 'fossa analyze'
            }
        }
        stage('Test') {
            steps {
                sh 'npm test'
            }
        }
        stage('Fossa Test') {
            steps {
                sh 'fossa test'
            }
        }
    }
}
```

---

Source: https://docs.fossa.com/docs/integrations/jfrog-artifactory

# JFrog Artifactory

When FOSSA analyses a project, it resolves dependencies from the same registries your build tool uses. If your team proxies public packages through Artifactory (or hosts private packages there) you need to give FOSSA credentials so it can fetch those dependencies too.

Configure private registry credentials under [**Account Settings → Languages**](https://app.fossa.com/account/settings/languages/java). Each language has its own settings page.

## How it works

FOSSA passes the credentials you configure here to the relevant package manager fetcher at analysis time. For Maven, it injects a custom `settings.xml`; for npm it sets the registry URL and auth token; for other languages it follows the same pattern. Credentials are stored encrypted and never appear in logs or scan output.

## Supported languages

| Language | Settings page | Auth method |
|---|---|---|
| Java (Maven) | [/account/settings/languages/java](https://app.fossa.com/account/settings/languages/java) | Repository URL + Server credentials (ID, username, password) |
| JavaScript (npm) | [/account/settings/languages/npm](https://app.fossa.com/account/settings/languages/npm) | Registry URL + token **or** username/password |
| Python (pip) | [/account/settings/languages/python](https://app.fossa.com/account/settings/languages/python) | Repository URL + username/password |
| Rust (Cargo) | [/account/settings/languages/rust](https://app.fossa.com/account/settings/languages/rust) | Registry URL + token **or** username/password |
| Ruby (Gems) | [/account/settings/languages/ruby](https://app.fossa.com/account/settings/languages/ruby) | Source URL + username/password |
| .NET (NuGet) | [/account/settings/languages/dotnet](https://app.fossa.com/account/settings/languages/dotnet) | Source URL + username/password |

## Configuring Java (Maven)

Java uses two separate config sections that mirror Maven's `settings.xml`: **Repositories** define where to fetch packages from, and **Servers** supply the credentials for those repositories. The **Repository ID** and **Server ID** must match.

{% steps %}
{% step title="Add a repository" %}
Go to [**Account Settings → Languages → Java**](https://app.fossa.com/account/settings/languages/java) and click **Add Repository**.

| Field | Value |
|---|---|
| **ID** | An identifier you choose (e.g. `artifactory-central`) |
| **URL** | Your Artifactory virtual repository URL (e.g. `https://artifactory.yourcompany.com/artifactory/libs-release`) |
{% /step %}
{% step title="Add a server" %}
Click **Add Server** and fill in the credentials for the repository you just added.

| Field | Value |
|---|---|
| **ID** | Must exactly match the Repository ID from the previous step |
| **Username** | Your Artifactory username or service account name |
| **Password** | Your Artifactory password or API key |
{% /step %}
{% step title="Save" %}
Click **Save Settings**. FOSSA will use these credentials when it fetches Maven dependencies for your projects.
{% /step %}
{% /steps %}

{% callout type="info" %}
Add one entry per Artifactory virtual repository. If you have separate repos for releases and snapshots, add both with matching server entries.
{% /callout %}

## Configuring other languages

For all other supported languages, the settings page has a single section: add a registry or repository URL and supply credentials. The specific field names differ slightly by language but the pattern is the same.

{% steps %}
{% step title="Open the language settings page" %}
Go to [**Account Settings → Languages**](https://app.fossa.com/account/settings/languages/java) and select your language from the sidebar.
{% /step %}
{% step title="Add your Artifactory registry URL" %}
Enter the Artifactory virtual repository URL for that package type. Examples:

| Language | Example Artifactory URL format |
|---|---|
| npm | `https://artifactory.yourcompany.com/artifactory/api/npm/npm-virtual/` |
| pip | `https://artifactory.yourcompany.com/artifactory/api/pypi/pypi-virtual/simple` |
| Cargo | `https://artifactory.yourcompany.com/artifactory/api/cargo/cargo-local/` |
| Ruby Gems | `https://artifactory.yourcompany.com/artifactory/api/gems/gems-virtual/` |
| NuGet | `https://artifactory.yourcompany.com/artifactory/api/nuget/nuget-virtual/` |

{% /step %}
{% step title="Enter credentials" %}
Supply a username and password (or API key), or a token if the language settings page offers that option (npm and Cargo both support token auth). Click **Save Settings**.

{% callout type="info" %}
If you see `npm ERR! Unable to authenticate, need: Basic realm="Artifactory Realm"` after saving, switch from username/password to a **token**. Some Artifactory configurations require token auth for npm even when basic auth works for other package types.
{% /callout %}
{% /step %}
{% /steps %}

---

Source: https://docs.fossa.com/docs/integrations/nexus

# Nexus

When FOSSA analyses a project, it resolves dependencies from the same registries your build tool uses. If your team proxies public packages through Nexus (or hosts private packages there) configure credentials so FOSSA can fetch those dependencies too.

Configure private registry credentials under [**Account Settings → Languages**](https://app.fossa.com/account/settings/languages/java). Each language has its own settings page.

## How it works

FOSSA passes the credentials you configure here to the relevant package manager fetcher at analysis time. For Maven, it injects a custom `settings.xml`; for other languages it sets the registry URL and credentials equivalently. Credentials are stored encrypted and never appear in logs or scan output.

## Supported languages

| Language | Settings page | Auth method |
|---|---|---|
| Java (Maven) | [/account/settings/languages/java](https://app.fossa.com/account/settings/languages/java) | Repository URL + Server credentials (ID, username, password) |
| JavaScript (npm) | [/account/settings/languages/npm](https://app.fossa.com/account/settings/languages/npm) | Registry URL + username/password or token |
| Python (pip) | [/account/settings/languages/python](https://app.fossa.com/account/settings/languages/python) | Repository URL + username/password |
| Rust (Cargo) | [/account/settings/languages/rust](https://app.fossa.com/account/settings/languages/rust) | Registry URL + token or username/password |
| Ruby (Gems) | [/account/settings/languages/ruby](https://app.fossa.com/account/settings/languages/ruby) | Source URL + username/password |
| .NET (NuGet) | [/account/settings/languages/dotnet](https://app.fossa.com/account/settings/languages/dotnet) | Source URL + username/password |

## Configuring Java (Maven)

Java uses two separate config sections that mirror Maven's `settings.xml`: **Repositories** define where to fetch packages from, and **Servers** supply the credentials. The **Repository ID** and **Server ID** must match.

{% steps %}
{% step title="Add a repository" %}
Go to [**Account Settings → Languages → Java**](https://app.fossa.com/account/settings/languages/java) and click **Add Repository**.

| Field | Value |
|---|---|
| **ID** | An identifier you choose (e.g. `nexus-central`) |
| **URL** | Your Nexus repository URL (e.g. `https://nexus.yourcompany.com/repository/maven-public/`) |
{% /step %}
{% step title="Add a server" %}
Click **Add Server** and fill in credentials for the repository you just added.

| Field | Value |
|---|---|
| **ID** | Must exactly match the Repository ID from the previous step |
| **Username** | Your Nexus username or service account name |
| **Password** | Your Nexus password or user token |
{% /step %}
{% step title="Save" %}
Click **Save Settings**. FOSSA will use these credentials when it fetches Maven dependencies for your projects.
{% /step %}
{% /steps %}

{% callout type="info" %}
Add one entry per Nexus repository. If you have separate proxy and hosted repos, add both with matching server entries.
{% /callout %}

## Configuring other languages

For all other supported languages, add a registry or repository URL and supply credentials.

{% steps %}
{% step title="Open the language settings page" %}
Go to [**Account Settings → Languages**](https://app.fossa.com/account/settings/languages/java) and select your language from the sidebar.
{% /step %}
{% step title="Add your Nexus repository URL" %}
Enter the Nexus repository URL for that package type. Nexus URLs use the repository path directly, no `/api/<type>/` prefix.

| Language | Example Nexus URL format |
|---|---|
| npm | `https://nexus.yourcompany.com/repository/npm-proxy/` |
| pip | `https://nexus.yourcompany.com/repository/pypi-proxy/simple` |
| Cargo | `https://nexus.yourcompany.com/repository/cargo-proxy/` |
| Ruby Gems | `https://nexus.yourcompany.com/repository/rubygems-proxy/` |
| NuGet | `https://nexus.yourcompany.com/repository/nuget-proxy/index.json` |
{% /step %}
{% step title="Enter credentials" %}
Supply a username and password, or a token where the settings page offers that option. Click **Save Settings**.
{% /step %}
{% /steps %}

---

Source: https://docs.fossa.com/docs/integrations/openid-connect

# OpenID Connect

FOSSA's OIDC integration lets CI/CD pipelines authenticate without storing long-lived API keys. Your platform (GitHub Actions, GitLab CI, CircleCI) generates a short-lived JWT automatically; FOSSA validates it and issues a scoped token that expires after the build.

## How it works

1. Your CI/CD platform generates a signed JWT for the running job.
2. Your pipeline exchanges the JWT for a FOSSA API token via `POST /api/oidc/token-exchange`.
3. The FOSSA token is used for `fossa analyze` or other API calls.
4. The token expires automatically (15 minutes to 12 hours; default 1 hour).

**Requirements:**
- Service accounts only, not regular user accounts
- Identity provider must support OIDC with JWT issuance over HTTPS
- Provider must use asymmetric signing (RSA, ECDSA, or EdDSA)

## Setting up OIDC

### Creating an OIDC provider

{% steps %}
{% step title="Open OIDC Providers" %}
Go to **Integrations → OIDC Providers → Add an OIDC provider**.

{% img src="/images/integrations/oidc-add-provider.png" alt="Create a new OIDC Provider dialog with the Issuer URL field and Organization/Team scope options" /%}
{% /step %}
{% step title="Fill in the provider details" %}

| Field | Value |
|---|---|
| **Issuer URL** | HTTPS URL of your identity provider. Common values: GitHub Actions → `https://token.actions.githubusercontent.com`; GitLab CI → `https://gitlab.com`; CircleCI → `https://oidc.circleci.com/org/{YOUR_ORG_ID}` |
| **Scope** | `Organization`: visible to all teams, requires org admin to create. `Team`: visible only to that team. |

FOSSA auto-discovers the provider's JWKS from `{issuer}/.well-known/openid-configuration`. After saving, note the numeric **Provider ID**; you will need it in the token exchange call.

{% img src="/images/integrations/oidc-providers-list.png" alt="OIDC Providers list showing the created provider with its numeric Provider ID, issuer, and scope" /%}
{% /step %}
{% /steps %}

### Selecting a service account

The FOSSA token issued by OIDC runs as a service account. Navigate to **Organization → Users** to find existing service accounts (shown with a **Service Account** badge), or go to **Integrations → API Service Accounts** to create one.

{% callout type="info" %}
Full guidance on creating, permissioning, and rotating service accounts will be in a dedicated page. For now: the account must be enabled, must belong to your organization, and must be a service account type, not a regular user.
{% /callout %}

Note the service account's **username**; you will pass it in the token exchange request.

{% img src="/images/integrations/oidc-service-accounts.png" alt="API Service Accounts page with the Create a Service Account form" /%}

### Configuring a trust relationship

A trust relationship defines which JWTs are allowed to authenticate as a specific service account. Without one, the token exchange will fail.

{% steps %}
{% step title="Open the provider and add a trust relationship" %}
Go to **Integrations → OIDC Providers**, click the view icon for your provider, then click **Add a trust relationship**.

{% img src="/images/integrations/oidc-trust-relationship.png" alt="OIDC Provider Details drawer showing the Trust Relationships table and the Add a trust relationship button" /%}
{% /step %}
{% step title="Configure the trust relationship" %}

**Scope:** Controls who can view and modify this trust relationship (does not affect the service account's permissions).

| Scope | Visibility | Who can modify |
|---|---|---|
| Org-scoped | Everyone | Org admins only |
| Team-scoped | Org admins + team admins | Org admins + team admins |

The trust relationship scope cannot be less restrictive than the provider's scope. An org-scoped provider allows org or team trust relationships; a team-scoped provider only allows that team.

**Service Account:** Select the service account this trust relationship authenticates as.

**Audiences:** One or more valid JWT `aud` claim values accepted from this provider (up to 100). Recommended: use a FOSSA-specific audience such as `app.fossa.com` for additional security.

**Required Claims:** JWT claims that must match for authentication to succeed. At least one `sub` claim is required (pre-filled). Supports wildcards: `*` (zero or more characters), `?` (exactly one character).

{% img src="/images/integrations/oidc-trust-relationship-form.png" alt="Add a Trust Relationship dialog with the scope, service account selector, audiences, and required claims fields" /%}
{% /step %}
{% /steps %}

**Common claim patterns:**

{% tabs %}
{% tab name="GitHub Actions" %}
```json
{
  "claim": "sub",
  "value": "repo:your-org/*",
  "hasWildcards": true
}
```

Available GitHub Actions claims: `sub` (`repo:org/repo:ref:refs/heads/branch`), `repository_owner`, `repository`, `ref`, `workflow`.
{% /tab %}
{% tab name="GitLab CI" %}
```json
{
  "claim": "sub",
  "value": "project_path:mygroup/myproject:*",
  "hasWildcards": true
}
```

Available GitLab CI claims: `sub` (`project_path:group/project:ref_type:branch:ref:refs/heads/branch`), `project_path`, `namespace_path`, `ref`, `ref_type`.
{% /tab %}
{% /tabs %}

## Implementation examples

### GitHub Actions

```yaml
name: FOSSA Analysis
on: push

jobs:
  fossa-check:
    runs-on: ubuntu-latest
    permissions:
      id-token: write  # Required for OIDC
      contents: read
    steps:
      - uses: actions/checkout@v5

      - name: Get FOSSA token via OIDC
        run: |
          JWT=$(curl -H "Authorization: bearer $ACTIONS_ID_TOKEN_REQUEST_TOKEN" \
            "$ACTIONS_ID_TOKEN_REQUEST_URL&audience=app.fossa.com" | jq -r '.value')

          FOSSA_API_KEY=$(curl --request POST \
            --url https://app.fossa.com/api/oidc/token-exchange \
            --header 'accept: application/json' \
            --header 'content-type: application/json' \
            --data '{
              "token": "'$JWT'",
              "providerId": 5,
              "username": "github-oidc-service-account",
              "expiresIn": 3600,
              "isPushOnly": true
            }' \
            | jq -r '.credential.token')

          echo "FOSSA_API_KEY=$FOSSA_API_KEY" >> "$GITHUB_ENV"

      - name: Run FOSSA analysis
        run: |
          curl -H 'Cache-Control: no-cache' https://raw.githubusercontent.com/fossas/fossa-cli/master/install-latest.sh | bash
          fossa analyze
          fossa test
```

{% callout type="info" %}
- `id-token: write` permission is required to generate the JWT.
- Specify the audience in the request URL: `&audience=app.fossa.com`.
- `ACTIONS_ID_TOKEN_REQUEST_TOKEN` and `ACTIONS_ID_TOKEN_REQUEST_URL` are only available when `id-token: write` is set.
{% /callout %}

### GitLab CI

```yaml
fossa-analysis:
  image: ubuntu:latest
  id_tokens:
    GITLAB_OIDC_TOKEN:
      aud: app.fossa.com
  script:
    - |
      FOSSA_API_KEY=$(curl --request POST \
        --url https://app.fossa.com/api/oidc/token-exchange \
        --header 'accept: application/json' \
        --header 'content-type: application/json' \
        --data "{
          \"token\": \"$GITLAB_OIDC_TOKEN\",
          \"providerId\": 2,
          \"username\": \"gitlab-ci-service-account\",
          \"expiresIn\": 3600,
          \"isPushOnly\": true
        }" \
        | jq -r '.credential.token')
    - curl -H 'Cache-Control: no-cache' https://raw.githubusercontent.com/fossas/fossa-cli/master/install-latest.sh | bash
    - fossa analyze
    - fossa test
```

{% callout type="info" %}
- Use `id_tokens:` to request a JWT with the specified audience.
- Requires GitLab 15.7 or later.
{% /callout %}

## Security

### Token security

- Tokens expire automatically based on `expiresIn` (900s–43200s; default 3600s).
- OIDC-issued tokens are prefixed with `oidc-` for identification.
- `isPushOnly: true` (the default) limits the token to push-only endpoints, which is recommended for CI/CD.

### JWT validation

- Only asymmetric algorithms accepted (RSA, ECDSA, EdDSA); HMAC rejected.
- Signature validated against the provider's JWKS public keys.
- Issuer and audience claims verified against your provider configuration.

## Troubleshooting

{% callout type="info" %}
For security, FOSSA returns generic error messages to prevent probing. Detailed validation errors are logged internally. If you are stuck, contact FOSSA support and share the full token exchange request (redact the JWT value).
{% /callout %}

### JWT validation failures

**Symptom:** Generic error on token exchange.

Check:
1. `providerId` matches a provider in your organization
2. Issuer URL in FOSSA exactly matches the `iss` claim in your JWT
3. Provider's `/.well-known/openid-configuration` is reachable from FOSSA
4. All required claims exist in the JWT and match (or match the wildcard pattern)
5. At least one `sub` claim is configured
6. JWT `aud` claim matches a configured audience
7. JWT is not expired
8. JWT uses an asymmetric signing algorithm (not HS256/HS384/HS512)

Decode your JWT at [jwt.io](https://jwt.io) to inspect claims.

### Token exchange errors

| Error | Cause | Fix |
|---|---|---|
| `400 Bad Request: Provider not found` | `providerId` doesn't exist or isn't accessible | Verify the provider ID and your org membership |
| `400 Bad Request: Service account not found` | `username` doesn't match a service account | Check the username exactly; confirm it's a service account type and is enabled |
| `400 Bad Request: No trust relationships found` | No trust relationship links this service account to this provider | Create a trust relationship; verify it's in the same org and the scope is compatible |
| `401 Unauthorized` | All trust relationships failed JWT validation | Work through the JWT validation checklist above |

### Platform-specific issues

**GitHub Actions**

- `id-token: write` permission is required; without it, `ACTIONS_ID_TOKEN_REQUEST_TOKEN` and `ACTIONS_ID_TOKEN_REQUEST_URL` are not available.
- Set the audience in the request URL, not in headers.

**GitLab CI**

- Requires GitLab 15.7 or later.
- Configure the audience in the `id_tokens:` block, not as a separate step.

**CircleCI**
- Only available on CircleCI Cloud, not self-hosted.
- Issuer URL format: `https://oidc.circleci.com/org/{YOUR_ORG_ID}`; obtain your org ID from CircleCI settings.

## Limitations

| Limit | Value |
|---|---|
| Token minimum lifetime | 900 seconds (15 minutes) |
| Token default lifetime | 3600 seconds (1 hour) |
| Token maximum lifetime | 43200 seconds (12 hours) |
| Token refresh | Not supported; exchange a new JWT for each build |
| Maximum audiences per trust relationship | 100 |
| Required claims | At least one `sub` claim |
| Claim value types | String, number, or boolean; no arrays or objects |
| Provider scope | `org` and `team` only |
| Service accounts | Must be a service account type, enabled, and in the same org as the provider |

## Migrating from long-lived API tokens

{% steps %}
{% step title="Create an OIDC provider" %}

Follow the setup steps above.

{% /step %}
{% step title="Create a trust relationship" %}

Link your CI/CD platform to a service account.

{% /step %}
{% step title="Update your pipelines" %}

Replace the static `FOSSA_API_KEY` environment variable with the JWT exchange flow from the examples above.

{% /step %}
{% step title="Test in a non-production pipeline" %}

Confirm scans succeed before rolling out broadly.

{% /step %}
{% step title="Revoke the old long-lived token" %}

Once all pipelines are migrated, revoke the static API token from **Settings → API Tokens**.

{% /step %}
{% /steps %}

---

Source: https://docs.fossa.com/docs/integrations/slack

# Slack

Connect FOSSA to Slack to receive issue notifications in your team's channels. You can add as many channels as you need, then enable notifications per project.

## Connecting FOSSA to Slack

{% steps %}
{% step title="Open Slack integration settings" %}
Go to [**Settings → Integrations → Slack**](https://app.fossa.com/account/settings/integrations/slack).

{% img src="/images/integrations/356727e-slack-org-settings.png" alt="FOSSA Slack integration settings page with Connect to Slack button" /%}
{% /step %}
{% step title="Authorise FOSSA" %}
Click **Connect to Slack**. Select the Slack workspace you want FOSSA to connect to, then choose the channel FOSSA will post messages to.

{% img src="/images/integrations/7eac1d38c28bf1f723f30edeaead865757f2a7b299f4430438c3ef9ad448def2-Screenshot_2025-05-27_at_4.25.06_PM.png" alt="Slack channel selection screen" /%}

{% callout type="info" %}
Repeat this step to add as many channels as you need. Each channel gets its own webhook connection.
{% /callout %}
{% /step %}
{% /steps %}

## Enabling project notifications

Slack notifications are configured per project. After connecting at least one channel, enable notifications for each project you want to monitor.

{% steps %}
{% step title="Open project settings" %}
Navigate to the project in FOSSA and go to its **Settings** tab.
{% /step %}
{% step title="Enable Slack notifications" %}
Select which notification types you want enabled for this project.

{% img src="/images/integrations/220660da3faa3fd7c09f903a26301e6aec81cc206403813ac890f8e87d1fbacf-Screenshot_2025-05-27_at_4.30.14_PM.png" alt="Project settings showing Slack notification toggles" /%}
{% /step %}
{% /steps %}

## On-Prem configuration

{% callout type="warning" %}
The `input-values.yaml` schema is defined in the FOSSA On-Prem Helm chart, not the application code. Confirm key names against your installed chart version before deploying.
{% /callout %}

Add the following block to your `input-values.yaml` when installing FOSSA with Helm:

```yaml
###
# Slack Configuration
###

# FOSSA can send notifications to a Slack channel. This requires creating an
# OAuth app on Slack, and providing the client id and secret here.
slack:
  clientId: <your-slack-client-id>
  clientSecret: <your-slack-client-secret>
```

Create a Slack OAuth app at [api.slack.com/apps](https://api.slack.com/apps) to obtain the client ID and secret.

---

Source: https://docs.fossa.com/docs/integrations/teamcity

# TeamCity

Add FOSSA to your TeamCity build configuration to upload dependency data on every build and optionally gate builds on your FOSSA policy status.

## Prerequisites

- A FOSSA API key from [**Settings → Integrations → API Tokens**](https://app.fossa.com/account/settings/integrations/api_tokens).

  {% img src="/images/integrations/7851253-api-token-creation.png" alt="FOSSA API token creation screen" /%}

  {% callout type="info" %}
  If you maintain a public repository, use a **Push Only** token so the key cannot be used to read sensitive data from your FOSSA account.
  {% /callout %}

## Adding FOSSA_API_KEY to TeamCity

{% steps %}
{% step title="Open Build Parameters" %}
In your TeamCity build configuration, go to **Parameters** and click **Add new parameter**.

{% img src="/images/integrations/e3f225b-parameter_one_a.png" alt="TeamCity Parameters page showing Add new parameter button" /%}
{% /step %}
{% step title="Create the environment variable" %}
Set the **Kind** to **Environment variable (env.)** and enter `FOSSA_API_KEY` as the name. Paste your FOSSA API key as the value.

{% img src="/images/integrations/ef9f152-parameter_two.png" alt="TeamCity parameter form with Kind set to Environment variable and FOSSA_API_KEY as the name" /%}
{% /step %}
{% /steps %}

## Adding the fossa analyze build step

{% steps %}
{% step title="Add a new build step" %}
In your build configuration, go to **Build Steps** and click **Add build step**.

{% img src="/images/integrations/905ee44-allbuildsteps.png" alt="TeamCity Build Steps page showing Add build step button" /%}
{% /step %}
{% step title="Select Command Line" %}
Choose **Command Line** from the runner type drop-down.

{% img src="/images/integrations/58d2080-step_command_line.png" alt="TeamCity runner type selection with Command Line highlighted" /%}
{% /step %}
{% step title="Enter the custom script" %}
In the **Custom script** field, enter:

```shell
curl -H 'Cache-Control: no-cache' https://raw.githubusercontent.com/fossas/fossa-cli/master/install-latest.sh | bash
fossa analyze
```

The `FOSSA_API_KEY` environment variable you configured in the previous section is picked up automatically.

{% img src="/images/integrations/2cde4dd-analyze.png" alt="TeamCity build step custom script field with fossa analyze command" /%}
{% /step %}
{% step title="Save and verify" %}
Save the build step. Run the build configuration to confirm FOSSA uploads a dependency report successfully.
{% /step %}
{% /steps %}

For more on `fossa analyze` options, see the [FOSSA CLI documentation](https://github.com/fossas/fossa-cli/blob/master/docs/README.md#fossa-cli-documentation).

## Blocking builds on FOSSA policy status

Add a second **Command Line** build step after `fossa analyze` to fail the build when FOSSA detects policy violations.

{% steps %}
{% step title="Add the fossa test build step" %}
Add another **Command Line** build step with the following custom script:

```shell
fossa test
```

{% img src="/images/integrations/f7accee-test_a.png" alt="TeamCity build step for fossa test" /%}
{% /step %}
{% step title="Configure execution condition" %}
Expand **Advanced options** and set **Execute step** to **If all previous steps finished successfully**. This ensures `fossa test` only runs when the build and analysis both succeeded.
{% /step %}
{% /steps %}

`fossa test` polls FOSSA until the scan result is ready, then exits non-zero if any issues violate your policy, blocking the build. The default timeout is **600 seconds** (10 minutes). Override it with:

```shell
fossa test --timeout 300
```

See the [fossa test reference](https://github.com/fossas/fossa-cli/blob/master/docs/references/subcommands/test.md#specifying-a-timeout) for details.

---

Source: https://docs.fossa.com/docs/integrations/travisci

# Travis CI

Add FOSSA to your Travis CI pipeline to upload dependency data on every build and optionally gate builds on your FOSSA policy status.

## Prerequisites

- A FOSSA API key from [**Settings → Integrations → API Tokens**](https://app.fossa.com/account/settings/integrations/api_tokens).

  {% img src="/images/integrations/7851253-api-token-creation.png" alt="FOSSA API token creation screen" /%}

  {% callout type="info" %}
  If you maintain a public repository, use a **Push Only** token. Note that Travis CI's [pull request security restrictions](https://docs.travis-ci.com/user/pull-requests/#pull-requests-and-security-restrictions) may require you to define `FOSSA_API_KEY` directly in your `.travis.yml` if you accept PRs from forked repositories.
  {% /callout %}

- Store the key as a Travis CI environment variable named `FOSSA_API_KEY` in your repository settings.

  {% img src="/images/integrations/ab4560e-settings-env-vars.png" alt="Travis CI repository settings showing environment variables" /%}

## Adding FOSSA to `.travis.yml`

{% steps %}
{% step title="Install the CLI in before_script" %}
Add a `before_script` entry to download and install `fossa-cli` before your build runs:

```yaml
before_script:
  - curl -H 'Cache-Control: no-cache' https://raw.githubusercontent.com/fossas/fossa-cli/master/install-latest.sh | sudo bash
```
{% /step %}
{% step title="Run fossa analyze in script" %}
In your `script` section, add `fossa analyze` after your build steps so FOSSA has access to a fully-built dependency graph:

```yaml
script:
  - <your build command>
  - fossa analyze
```

Every build will now upload a dependency report to FOSSA.
{% /step %}
{% /steps %}

{% callout type="info" %}
To control which targets FOSSA analyses, add a `.fossa.yml` file to the root of your repository. See the [.fossa.yml reference](https://github.com/fossas/fossa-cli/blob/master/docs/references/files/fossa-yml.md) on GitHub.
{% /callout %}

## Blocking builds on FOSSA policy status

Add `fossa test` to your `script` section after `fossa analyze` to fail the build when FOSSA detects policy violations:

```yaml
script:
  - <your build command>
  - fossa analyze
  - fossa test
```

`fossa test` polls FOSSA until the scan result is ready, then exits non-zero if any issues violate your policy, failing the build. The default timeout is **600 seconds** (10 minutes). Override it with:

```yaml
  - fossa test --timeout 300
```

See the [fossa test reference](https://github.com/fossas/fossa-cli/blob/master/docs/references/subcommands/test.md#specifying-a-timeout) for details.

## Triggering updates via webhook

In exceptional cases you may need Travis CI to notify FOSSA to pull an update directly. This is not required for most users. Use the `fossa analyze` step above instead.

Add the following to your `.travis.yml`:

```yaml
notifications:
  webhooks: https://app.fossa.com/hooks/travisci
```

Then in FOSSA, go to **Project → Settings → Update Hooks** and select **Travis CI** in the dropdown.

---

Source: https://docs.fossa.com/docs/fossabot

# fossabot

fossabot is FOSSA's AI agent for keeping your code healthy. It makes strategic dependency updates, reviews changed code for security issues, and guards against problematic AI-generated code. fossabot works where your engineers already work: in pull requests on GitHub and merge requests on GitLab.

## What fossabot does

- **[Dependency upgrades](/docs/fossabot/dependency-upgrades):** Proposes and applies dependency updates, including the large, complex ones, and fixes the breaking changes they introduce.
- **[SAST security review](/docs/fossabot/sast-security-review):** Reviews the code changed in a pull request for security issues, with a summary comment and inline findings.
- **[AI guardrails](/docs/fossabot/ai-guardrails):** Flags AI-generated code that carries problematic license obligations before it merges.

## How it works

fossabot draws on three things: your application source code, your third-party dependencies, and hosted AI models from Anthropic. See [System Architecture](/docs/fossabot/system-architecture) for how these fit together and how your code is isolated.

## What's in this section

- **[Setup](/docs/fossabot/setup):** Connect fossabot to your GitHub or GitLab repositories.
- **[fossabot for Dependency Upgrades](/docs/fossabot/dependency-upgrades):** Propose upgrades, group related updates, and fix breaking changes.
- **[fossabot for SAST Security Review](/docs/fossabot/sast-security-review):** Catch security issues in changed code before merge.
- **[fossabot for AI Guardrails](/docs/fossabot/ai-guardrails):** Block AI-generated code with license problems.
- **[Supported Ecosystems & Tools](/docs/fossabot/supported-ecosystems):** Language support and private registry configuration.
- **[System Architecture](/docs/fossabot/system-architecture):** Data sources and security boundaries.
- **[Tips for Continuous Integration](/docs/fossabot/continuous-integration):** Get more out of fossabot by feeding it your CI results.

---

Source: https://docs.fossa.com/docs/fossabot/setup

# Setup

fossabot connects to your source host as a GitHub App or a GitLab integration. You install and manage it from the fossabot dashboard at [bot.fossa.com](https://bot.fossa.com).

Once a repository is connected, fossabot runs automatically on new pull or merge requests. You can also trigger it manually:

- **GitHub:** comment `@fossabot analyze` on the pull request.
- **GitLab:** comment `/fossabot analyze` on the merge request.

## Connecting fossabot to GitHub

For repositories on github.com or GitHub Enterprise Cloud, install the GitHub App from [bot.fossa.com](https://bot.fossa.com). Your engineers keep viewing analysis and pull requests in GitHub. Each repository can be set to trigger fossabot automatically or manually.

### GitHub Enterprise Server or Cloud Data Residency

GitHub Enterprise Server (GHES) and GitHub Enterprise Cloud with Data Residency (GHEC-DR) require the GitHub App to be registered within your instance, so you create your own app and register its credentials with fossabot. The steps are the same for both. Only your instance URL differs (your GHES server host such as `https://github.your-company.com`, or your `*.ghe.com` tenant for GHEC-DR).

{% steps %}
{% step title="Start in fossabot" %}
Log in to [bot.fossa.com](https://bot.fossa.com), go to **Settings > Integrations > Install GitHub app**, expand **Using GitHub Enterprise Server or Cloud Data Residency?**, and enter your instance URL.
{% /step %}
{% step title="Create a GitHub App on your instance" %}
Create the app under the organization or enterprise that should own it:

- **Organization:** `https://<your-instance>/organizations/<your-org>/settings/apps/new`
- **Enterprise:** `https://<your-instance>/enterprises/<your-enterprise>/settings/apps/new`

An enterprise-owned app can only be installed on organizations within that enterprise.
{% /step %}
{% step title="Configure the app" %}
**Basic information**
- **GitHub App name:** `fossabot` (or any name; fossabot uses it for its `@fossabot` mentions)
- **Homepage URL:** `https://bot.fossa.com`

**Identifying and authorizing users**: add both Callback URLs, and leave **Request user authorization (OAuth) during installation** and **Enable Device Flow** unchecked:
- `https://bot.fossa.com/api/auth/callback/github`
- `https://vcs.fossa.com/api/v1/connections/github/oauth/callback`

**Post installation**
- **Setup URL:** `https://vcs.fossa.com/api/v1/connections/github_app/app/callback`
- Leave **Redirect on update** unchecked.

**Webhook**
- Check **Active** and keep **Enable SSL verification** on.
- **Webhook URL:** `https://vcs.fossa.com/webhooks/github`
- **Webhook secret:** generate one (you'll paste it into fossabot in the next steps).

**Permissions and events:** set them as listed under [Required permissions](#required-permissions) below.
{% /step %}
{% step title="Generate credentials" %}
Generate a **Client secret** and a **Private key** (download the `.pem` file).
{% /step %}
{% step title="Register with fossabot" %}
Back in the Install GitHub app form, enter your **App ID**, **App name** (the slug from the app's URL), **Client ID**, **Client Secret**, **Private Key** (the contents of the `.pem`), and **Webhook Secret**, then select **Register & Install**.
{% /step %}
{% step title="Install and allowlist" %}
fossabot redirects you to your instance to install the app, then choose the repositories fossabot should access. Make sure your network allows FOSSA to reach your instance and receive webhooks (see [IP Space Allowlisting](https://docs.fossa.com/docs/ip-space-allowlisting)).
{% /step %}
{% /steps %}

{% img src="/images/fossabot-ghes-install.png" alt="fossabot Install GitHub app screen for GitHub Enterprise Server with the API server URL field" /%}

### Required permissions

The fossabot GitHub App requests these **repository permissions**:

| Permission | Access |
|---|---|
| Actions | Read |
| Administration | Read |
| Checks | Read & Write |
| Code scanning alerts | Read |
| Commit statuses | Read |
| Contents | Read & Write |
| Dependabot alerts | Read |
| Issues | Read & Write |
| Metadata | Read (auto-selected) |
| Pull requests | Read & Write |
| Repository security advisories | Read |
| Webhooks | Read & Write |

One **organization permission**:

| Permission | Access |
|---|---|
| Members | Read |

It subscribes to these events:

- Issues
- Issue comment
- Pull request
- Pull request review
- Pull request review comment
- Pull request review thread
- Push

### Bulk onboarding of repos

If you have hundreds or thousands of repositories, onboard them in bulk with a scoped token instead of installing one repository at a time.

{% steps %}
{% step title="Generate a token" %}
Create a [personal access token (classic)](https://github.com/settings/tokens) with the `repo` scope, using a GitHub account that has admin access to the target repositories. The `PUT` endpoint used below only works for a classic PAT (`ghp_`) with the `repo` scope; a fine-grained or user-to-server (`ghu_`) token is rejected with a 404.
{% /step %}
{% step title="Find your repository IDs" %}
Bulk onboarding uses numeric repository IDs (for example `1296269`), not `owner/name`. List them with the GitHub CLI:

```
gh api --paginate /orgs/<ORG>/repos -q '.[] | "\(.id) \(.full_name)"'
```
{% /step %}
{% step title="Add each repository" %}
Using the scoped token, add each repository to the installation:

```
export GH_TOKEN="ghp_xxxxxxxxxxxxxxxxxxxx"
gh api --method PUT \
  /user/installations/<INSTALLATION_ID>/repositories/{REPO_ID}
```
{% /step %}
{% /steps %}

## Connecting fossabot to GitLab

For GitLab, cloud or self-managed, connect from [bot.fossa.com](https://bot.fossa.com) using OAuth or a GitLab access token. Your engineers keep viewing analysis and merge requests in GitLab. Each repository can trigger fossabot automatically or manually with a `/fossabot analyze` comment or from the UI.

### GitLab access token requirements

If you connect with an access token, it needs the following scopes.

**Legacy scopes:** `api`, `read_repository`, `write_repository`

**Fine-grained scopes:**

| Category | Scopes and permissions |
|---|---|
| CI/CD | Job (Read, Run Job); Pipeline (Read) |
| Repository | Branch (Read, Create, Delete); Code (Read); Commit (Read, Create); Merge Request (Read, Create, Update); Repository (Read); Tag (Read) |
| Group | Group (Read) |
| Project | Project (Read) |

## What's next

- **[fossabot for Dependency Upgrades](/docs/fossabot/dependency-upgrades):** Configure how fossabot proposes and fixes upgrades.
- **[Supported Ecosystems & Tools](/docs/fossabot/supported-ecosystems):** Confirm your languages are covered and configure private registries.

---

Source: https://docs.fossa.com/docs/fossabot/dependency-upgrades

# fossabot for Dependency Upgrades

fossabot is an AI agent for making strategic dependency updates. It is built for the large, complex upgrades that usually need a senior engineer, the ones that turn into an unexpected multi-hour research and coding task.

{% img src="/images/fossabot-dependency-reasoning.png" alt="fossabot comment on a GitHub pull request explaining why an upgrade is safe, with a list of what it checked" /%}

## Using fossabot with Dependabot, Renovate, or Snyk

fossabot works alongside the dependency tools you already use. When it sees a pull request from Dependabot, Renovate, or Snyk, fossabot analyzes the proposed upgrade for breaking changes and evaluates the impact on your application.

## Using fossabot to propose upgrades

fossabot can also propose upgrades on its own, which helps teams work down a dependency backlog. By default it groups related dependencies into a single pull request, with no manual configuration required.

fossabot chooses which upgrades to propose through a weekly scoring process, described in [How fossabot selects the best upgrades](#how-fossabot-selects-the-best-upgrades) below.

You can tune this behavior with a configuration file committed to your repository. Monorepos are supported: place multiple configuration files in a single repository.

```yaml
# yaml-language-server: $schema=https://api.fossabot.fossa.com/schemas/fossabot-config.v1.json
version: 1

defaults:
  maxOpenPRs: 3
  minimumReleaseAge: 7
  securityCvssThreshold: 7.0
```

| Field | Description |
|---|---|
| `version` | Configuration schema version. Use `1`. |
| `defaults.maxOpenPRs` | Maximum number of fossabot pull requests open at once. |
| `defaults.minimumReleaseAge` | Minimum age, in days, before a release is eligible for an upgrade, acting as a cooldown period. |
| `defaults.securityCvssThreshold` | CVSS score at or above which fossabot prioritizes a security upgrade. |

{% img src="/images/fossabot-grouped-pr.png" alt="A fossabot pull request that groups several related dependency updates together" /%}

## Using fossabot to fix breaking changes

When an upgrade introduces a breaking change, ask fossabot to fix it:

- **GitHub:** comment `@fossabot fix`.
- **GitLab:** comment `/fossabot fix`.

fossabot generates a prompt for the fix and attempts the correction automatically, using your CI failure output to guide the change.

{% img src="/images/fossabot-fixes.png" alt="fossabot proposing a fix for a breaking change in a pull request" /%}

{% img src="/images/fossabot-fix-commit.png" alt="fossabot committing a fix directly to the pull request branch" /%}

## How fossabot selects the best upgrades

Once a week, fossabot runs a multi-step selection process to find the best upgrades to propose for each repository. What counts as "best" depends on the current state of your code, but the process optimizes for a few goals:

- Lower noise by grouping related dependencies.
- Propose routine maintenance bumps alongside security fixes.
- Stay within your open pull request limit (`maxOpenPRs`, default 3).
- Score important security updates highly, and let them skip the open pull request limit.
- Explore patch, minor, and major upgrade paths to balance new features and performance against breaking changes and deprecations.

### Scoring process

The Available Updates list on each repository is a visual representation of the final result. Overlapping groups are expected, such as a patch and a minor upgrade of the same package, because this gives fossabot the widest range to research.

{% img src="/images/fossabot-available-updates.png" alt="fossabot Available Updates list showing dependency groups ranked by score, each with an upgrade type, status, and a create or view pull request action" /%}

fossabot scores upgrades in these steps:

1. Take an inventory of the out-of-date packages in the repository.
2. Recognize sub-projects, if the repository is a monorepo.
3. Group related dependencies.
4. Annotate groups that are tied to vulnerable dependencies.
5. Fetch and process details about each upgrade from several sources:
   - Release notes and changelogs.
   - Migration guides and README content.
   - The commits contained in the release.
6. Score positive indicators: bug fixes, new features, performance enhancements, and security improvements.
7. Score negative indicators: breaking changes and deprecations.
8. Finalize scores and deduplicate overlapping upgrades.

### Making pull requests

After scoring, fossabot does two things:

1. Closes out-of-date pull requests.
2. Opens new pull requests, following your configured policy.

This happens automatically in the background. The result is that most low-value upgrades and noise are filtered out, leaving engineers with a short list of high-quality proposals. Once the pull requests are open, fossabot runs its detailed application impact analysis, drawing on your test suites and other [continuous integration](/docs/fossabot/continuous-integration) signals.

---

Source: https://docs.fossa.com/docs/fossabot/sast-security-review

# fossabot for SAST Security Review

fossabot is an AI agent for code maintenance, including Static Application Security Testing (SAST). It reviews the code changed in a pull or merge request and reports the security issues it finds.

Before relying on SAST review, check [Supported Ecosystems & Tools](/docs/fossabot/supported-ecosystems) to confirm your programming languages are covered.

## SAST review in pull requests

fossabot runs its SAST review against the files changed in a pull or merge request. Findings and recommendations appear in two places:

- A summary comment on the request.
- An inline comment on the relevant line, when fossabot can attribute the finding to a specific location.

Most teams run SAST review on every code change before it merges.

{% img src="/images/fossabot-sast-summary.png" alt="fossabot SAST review summary comment with an executive summary and recommendations" /%}

{% img src="/images/fossabot-sast-inline.png" alt="fossabot inline comment on a specific line flagging a SAST issue" /%}

## Block issues with a pre-merge check

You can enforce SAST review as a pre-merge check. This cuts down on noise: when there are no findings, the pull request simply gets a green check mark. When there are findings, the check reports them.

It is optional whether the check blocks the merge. Make it blocking when you want SAST findings to gate merges, or leave it non-blocking when you want the signal without the gate.

{% img src="/images/fossabot-sast-precheck.png" alt="A fossabot pre-merge check reporting two SAST findings that need to be addressed" /%}

---

Source: https://docs.fossa.com/docs/fossabot/ai-guardrails

# fossabot for AI Guardrails

fossabot is an AI agent for code maintenance, including analysis of AI-generated code for problematic license issues. It flags cases where code an LLM was trained on could introduce licensing complications if it merges into your project.

## AI and snippet review in pull requests

fossabot reviews the files changed in a pull or merge request for problematic snippets. Each snippet is flagged by the file it appears in and the license that FOSSA has attributed to the code. Only files that match your organization's deny list are flagged.

{% img src="/images/fossabot-ai-guardrails-block.png" alt="fossabot blocking a pull request that introduces GPL-licensed code" /%}

## Block issues with a pre-merge check

You can enforce AI guardrails as a pre-merge check. As with SAST review, this cuts down on noise: when there are no findings, the pull request simply gets a green check mark.

Administrators control whether the check blocks the merge.

{% img src="/images/fossabot-ai-guardrails-check.png" alt="A failed fossabot pre-merge check after problematic AI-generated code was detected" /%}

---

Source: https://docs.fossa.com/docs/fossabot/supported-ecosystems

# Supported Ecosystems & Tools

fossabot's support for a language ecosystem depends on our automated testing and on the availability of ground truth and evaluation dataset coverage.

To analyze your project, fossabot installs your application's full dependency tree, so it needs access to all of your dependencies, both public and private.

## Supported ecosystems

| Ecosystem | Dependency Review | Dependency PR Creation | SAST Review |
|---|---|---|---|
| Javascript/Typescript | Strong/Well-supported | Strong/Well-supported | Strong/Well-supported |
| Java (incl. Kotlin) | Strong/Well-supported | Strong/Well-supported | Strong/Well-supported |
| Python | Beta quality | Not supported | Strong/Well-supported |
| Go (Golang) | Beta quality | Not supported | Strong/Well-supported |
| Ruby | Beta quality | Not supported | Strong/Well-supported |
| Rust | Beta quality | Not supported | Strong/Well-supported |
| Clojure | Alpha quality | Not supported | Strong/Well-supported |
| Elixir | Alpha quality | Not supported | Strong/Well-supported |
| iOS (Objective-C, Swift) | Alpha quality | Not supported | Strong/Well-supported |
| .NET (C#, F# VB) | Alpha quality | Not supported | Strong/Well-supported |
| PHP | Alpha quality | Not supported | Strong/Well-supported |
| Dart | Alpha quality | Not supported | Not supported |
| Erlang | Alpha quality | Not supported | Not supported |
| Fortran | Alpha quality | Not supported | Not supported |
| Haskell | Alpha quality | Not supported | Not supported |
| Perl | Alpha quality | Not supported | Not supported |

## Configuring a private registry or code mirror

If your dependencies come from a private registry or code mirror, configure credentials in your **Organization Settings** in the FOSSA web UI.

{% img src="/images/fossabot-private-registry.png" alt="Organization Settings page where private registry and code mirror credentials are configured" /%}

### NPM-style code mirrors

Credentials for an npm-style code mirror are configured in Organization Settings. Common examples are Artifactory, GitHub Package Registry, and NPM's native private packages.

{% img src="/images/fossabot-npm-mirror.png" alt="Organization Settings panel for configuring npm-style code mirror credentials" /%}

### Maven code mirrors

Maven code mirror credentials are also configured in Organization Settings. Common examples are Artifactory, Sonatype Nexus, and GitHub Packages for Maven.

{% img src="/images/fossabot-maven-mirror.png" alt="Organization Settings panel for configuring Maven code mirror credentials" /%}

---

Source: https://docs.fossa.com/docs/fossabot/system-architecture

# System Architecture

fossabot's job is to manage dependency updates and review code through intelligent automation. To do that, it relies on three data sources.

## Data sources

1. **Application source code**, from a supported version control system: GitHub.com, GitHub Enterprise Cloud, GitHub Enterprise Server, and GitLab (cloud and self-hosted).
2. **Third-party dependencies.** Package manager databases connect the packages declared in your app with their published source code, pulled from public repositories or your configured private mirrors.
3. **Hosted AI models.** fossabot exclusively uses LLM and AI services from Anthropic, under an enterprise agreement with no training on or retention of your data.

{% img src="/images/fossabot-architecture-diagram.png" alt="Diagram showing how GitHub, FOSSA services, external package metadata, and Anthropic LLM services interact" /%}

## First-party code

Your first-party code is cloned during each operation. Each analysis worker is dedicated to a single customer's analysis at a time, and your cloned code is deleted immediately after the analysis completes.

First-party analysis happens locally first, through static analysis tools, and then with AI to understand the relevant call sites. Only then are small code snippets sent to AI services to assess the impact of a change.

## Context building and security boundaries

fossabot separates its analysis into stages, with security boundaries between them:

1. **Direct access:** code is on disk during the initial processing and filtering stages.
2. **Indirect access:** later steps work only with metadata and small snippets of code derived from that earlier direct access, which keeps the AI models focused on specific context.
3. **Collection steps:** these run AI web search with the minimum context needed to complete the task.
4. **Code generation:** this is limited to specific call sites, through the `@fossabot fix` workflow.
5. **Third-party communication:** this never runs AI. It only transmits data that was already constructed.

{% img src="/images/fossabot-isolation.png" alt="Diagram showing the isolation and security boundaries between fossabot's analysis steps" /%}

---

Source: https://docs.fossa.com/docs/fossabot/continuous-integration

# Tips for Continuous Integration

fossabot reads your CI results from GitHub Actions, including output from linters, test runners, and UI testing tools like Storybook and Playwright.

It uses that data in three ways:

- To decide whether an upgrade is compatible.
- To shape its code fix recommendations.
- To construct automated commits that address the issues it finds.

The better your CI signal, the better fossabot's decisions.

## Secret access

fossabot acts through pull requests, so make sure bot pull requests can reach the secrets your CI needs to run. Where that is a concern, create reduced-scope or read-only credentials for these runs.

## UI testing tools

Linters and test suites usually run on pull requests already. UI testing suites should run on bot pull requests too, both those created by Dependabot, Renovate, or Snyk and those created by fossabot. Enabling them lets fossabot use UI test results that are otherwise checked by hand.

- [Storybook](https://storybook.js.org/docs/writing-tests) supports test automation you can run in CI.
- [Playwright](https://playwright.dev/docs/ci) documents how to run UI tests in CI.

---

Source: https://docs.fossa.com/docs/fossabot/intended-uses

# Intended Use

fossabot is an AI agent intended to strategically manage different parts of your application life-cycle.

1. Upgrade application dependencies to react to vulnerabilities found and to maintain regular upgrade cadence
2. Adapt application code to changes in dependencies to maintain compatibility
3. Review code as it's proposed for license issues caused by AI coding agents
4. Review code as it's proposed for security and logic issues
5. Audit code as it's released to ensure it meets your compliance obligations

## How fossabot Uses AI

fossabot is an AI system within the meaning of the EU AI Act. Its analysis results, pull request descriptions, review comments, and proposed code changes are generated by large language models.

fossabot exclusively uses LLM and AI services from Anthropic, under an enterprise agreement with no training on or retention of your data. The data sent to these services includes dependency manifests, diffs, changelog excerpts, and small snippets of your source code derived from earlier local analysis. See [System Architecture](/docs/fossabot/system-architecture) for how this context is built and the security boundaries between analysis stages.

## Capabilities and Limitations

fossabot's output is generated by AI and can be incorrect or incomplete. For example, it may recommend the wrong fix version, misread a changelog, or miss a breaking change in a dependency upgrade. Results are also non-deterministic: running the same analysis twice can produce different findings or proposed changes.

Coverage and accuracy vary by language, package manager, and ecosystem. See [Supported Ecosystems](/docs/fossabot/supported-ecosystems) for what fossabot analyzes today.

These limitations are why fossabot only proposes changes and never merges them, as described in [Human Oversight](#human-oversight) below.

## Trusted Repositories

fossabot is intended to be used with code repositories that you trust and control. Security controls exist to protect the availability and integrity of the system and the confidentiality of any processed code, but the first line of defense is using fossabot with trusted application code.

fossabot's access to your code is bounded by the permissions you granted its source control integration (see [Setup](/docs/fossabot/setup) for the current permission list). If a new feature requires additional permissions, your organization administrator must review and approve the new permission grant before fossabot can use it.

## Human Oversight

fossabot's output is always a proposal: a pull request, a review comment, or a check result. fossabot never merges code on its own. The engineer who reviews and merges a fossabot change retains responsibility for that change, the same as any other code they approve.

To keep this oversight enforced by your tooling rather than by convention, enable branch protection and required reviews on any repository fossabot writes to.

fossabot is intended to pass through your organization's existing change management policies. If your policy requires human review or sign off before changes are merged, fossabot dependency upgrades or code fixes should be reviewed accordingly.

fossabot code review takes in application context to provide an accurate assessment and attempts to remove as many false positives as possible. Engineers should always double check the assessment for correctness before merging code.

## Out-of-Scope Uses

fossabot is not intended for high-risk uses under the EU AI Act. Specifically, fossabot is not intended to be:

- A substitute for a security review, legal review, or legal advice. Its security findings and compliance audit output are inputs to your own review processes, not a replacement for them.
- A component of a high-risk AI system under Annex III of the EU AI Act, such as systems used in employment, credit, or law enforcement decisions.
- Part of an unattended pipeline that merges its proposals automatically without human review.

## fossabot SaaS Service

fossabot is a hosted service that is regularly updated with new features, bug fixes and security improvements. You cannot opt-out of the service's automatic upgrades.

Security controls protect the availability and integrity of the service and the confidentiality of your processed code. See [System Architecture](/docs/fossabot/system-architecture) for how your code is isolated during analysis. 

Material changes to data handling or retention, such as changes to what is stored after analysis or for how long, will be reflected in the [Privacy Policy](/docs/legal/privacy-policy).

Material changes to fossabot's use of AI, such as a change of model provider or significant new AI-powered features, will be reflected in this documentation so that you can keep your own AI inventory current.

Configuration changes you make, such as enabling new integrations or expanding fossabot to additional repositories, expand the code and metadata that fossabot accesses and transmits for analysis, including transient processing by Anthropic as described in the [Privacy Policy](/docs/legal/privacy-policy). Review these changes through your own change management process, as described above.

### Decommission

Should you wish to decommission your usage of fossabot, you can revoke access to your code at any time and remove all integrations in your fossabot settings. Revoking access and removing integrations stop all future access to your code, but do not delete existing analysis results or related metadata, which are retained only as long as necessary to provide the service. Your source code is processed transiently and is not stored beyond what is required to complete each analysis, as described in the [Privacy Policy](/docs/legal/privacy-policy).

You may request account or organization deletion via support ticket, and request deletion of Personal Data collected by fossabot by contacting [privacy@fossa.com](mailto:privacy@fossa.com).

## fossabot Private Saas Tenancy

fossabot is available to be hosted as a dedicated/private tenancy that is separated from other customers. These instances are upgraded by FOSSA engineers but customers have more control on when the upgrades take place.

Upon decommissioning, the entire tenancy is destroyed.

---

Source: https://docs.fossa.com/docs/organization-management

# Organization Management

Organization Management covers the controls owners and admins use to manage access and configure FOSSA across the whole organization.

## What this covers

- **Users, teams & roles**: invite users and control what they can see and do.
- **Organization structure**: organize projects, teams, and ownership.
- **Single sign-on (SSO)**: connect your identity provider (SAML, Azure AD, and more).
- **Settings & auditing**: configure org-wide defaults and review activity.

For self-hosted deployments, see [On-Premises](/docs/on-premises).

---

Source: https://docs.fossa.com/docs/organization-management/organization-settings

# Organization Settings

Organization Settings hold the organization-wide defaults FOSSA applies across your projects and reports. The **General** tab is where owners and admins set your organization's identity (title and billing email), the default role for new users, [project labels](/docs/project-setup/project-labels) and [package labels](/docs/organization-management/package-labels), and internal package signatures.

To open it, hover over your username in the top-right corner of FOSSA, select **Settings**, then open **Organization**. The General tab loads first.

## General settings

The General tab is divided into the sections below, in the order they appear on the page. Some sections only show for paid plans or when a feature is enabled for your organization, so you may not see all of them.

{% img src="/images/organization-management/organization-settings-general.png" alt="Organization Settings General tab showing the General, Users, Features, Projects, Packages, Snippets, and Contributors sections" /%}

### General

**Organization Title** (required): Your organization's display name; defaults to your email address.

**Billing Email**: The address FOSSA uses for billing-related communication.

### Users

{% callout type="info" %}
The Users section is available on paid plans (Business and Enterprise) and is hidden on the free tier.
{% /callout %}

**Default Role for New Users**: The role automatically applied to each new user invited to your organization. Defaults to **None**. When your organization uses single sign-on for role management, this field is locked and the role is controlled by your identity provider.

**Enable FOSSA default team roles**: Toggle that controls whether FOSSA's built-in, out-of-the-box roles are available. Disabling it hides those roles and leaves only your custom roles.

### Features

Shown only when License Conclusion is enabled for your organization.

**License Conclusion**: Toggle that enables concluding licenses and adds the related license-policy settings. This global setting takes effect on each project at its next analysis.

### Projects

{% callout type="info" %}
Project labels are available on paid plans (Business and Enterprise) and are hidden on the free tier.
{% /callout %}

**Labels**: User-defined metadata you apply to projects individually. Use them to filter projects on the Projects, Global Issues, and Global Reports pages. Labels must be unique (case-insensitive), can be up to 50 characters long, and are capped at 500 per organization. The labels you define here are applied to projects in Project Settings.

### Packages

{% callout type="info" %}
Package Labels are available on paid plans (Business and Enterprise) and are hidden on the free tier. Internal Package Signatures are available on all plans.
{% /callout %}

**Package Labels**: Labels you assign to packages, visible across your entire organization. Label names must be 1 to 50 characters and contain only letters, numbers, underscores, hyphens, periods, or spaces, with a limit of 500 per organization.

**Internal Package Signatures**: A comma-separated list of naming signatures that mark internal packages. FOSSA treats any package whose name contains one of these signatures as an internal dependency and ignores it.

{% callout type="warning" %}
A signature excludes **every** matching package from all reports, projects, and issue scans across the entire organization, not just the project you're viewing.
{% /callout %}

### Snippets

{% callout type="info" %}
Snippet settings are available on paid plans (Business and Enterprise), and only when snippet detection is enabled for your organization.
{% /callout %}

**Source Code Retention**: Controls how long, in days, FOSSA retains the source code snippets collected during analysis.

### Contributors

**Email Weekly Contributor Report**: Sends a weekly snapshot of contributors across your analyzed projects to your account email. You need view access to at least one project to use it.

## Default project settings

FOSSA also lets you set the default **Security**, **Licensing**, and **Quality** policy settings that new projects inherit, and propagate them onto existing projects. That behavior has its own rules, so it lives on its own page: see [Default Project Settings](/docs/organization-management/default-project-settings).


## Navigating Settings

Settings is organized into top-level areas, shown across the top of the page in this order: **Account**, **Organization**, **Projects**, **Integrations**, **Languages**, **Subscription**, and **Audit Logs**. The General tab above lives under **Organization**. Each area opens a sidebar of its own pages, and an item appears only if you have permission to view it. The map below mirrors that navigation and links to the docs for each page.

### Organization

The General tab covered above, plus:

- **Portal**: Set up your SBOM portal, FOSSA's public portal for publishing your SBOM files. See [Sharing SBOMs](/docs/sbom/sharing).
- **Teams**: Create teams and assign users and projects to them. Users without org-level permissions can only access data associated with their teams. See [Teams](/docs/organization-management/role-based-access-control).
- **Roles**: Manage roles and permissions. See [Role-Based Access Control](/docs/organization-management/role-based-access-control).
- **Users**: Invite users and edit their roles. See [Inviting Users](/docs/organization-management/inviting-users).
- **Banners**: Create notification banners that display information to your colleagues on the sign-in and project index pages.
- **Authentication**: Set up your authentication method and add a login subdomain. See [Single Sign-On](/docs/organization-management/single-sign-on).

### Projects

Organization-wide defaults for projects:

- **General**: Default project-level settings. See [Project Settings](/docs/project-setup/project-settings).
- **Issue Policies**: Default security, licensing, and quality policies new projects inherit. See [Policies](/docs/policies) and [Default Project Settings](/docs/organization-management/default-project-settings).
- **Notifications**: Configure how FOSSA notifies you about projects. See [Notifications](/docs/project-setup/notifications).
- **Hooks**: Configure hooks that fire when projects update.

### Integrations

- **Jira**: Connect Jira to create and sync tickets from FOSSA issues. See [Jira](/docs/integrations/jira).
- **GitHub**: Connect GitHub for project import and pull request checks. See [GitHub](/docs/integrations/github).
- **Slack**: Send FOSSA notifications to Slack. See [Slack](/docs/integrations/slack).
- **Bitbucket**: Connect Bitbucket for project import. See [Bitbucket Cloud](/docs/integrations/bitbucket-cloud) and [Bitbucket Server](/docs/integrations/bitbucket-server).
- **GitLab**: Connect GitLab for project import and merge request checks. See [GitLab](/docs/integrations/gitlab).
- **API**: Create and manage API tokens. See [API Tokens](/docs/organization-management/api-tokens).
- **API Service Accounts**: Manage non-user service accounts for automation. See [API Tokens](/docs/organization-management/api-tokens).
- **OIDC Providers**: Configure OpenID Connect providers for keyless authentication. See [OpenID Connect](/docs/integrations/openid-connect).
- **Custom License Scans**: Define custom license detection rules. See [Custom License Scans](/docs/licenses/custom-license-scans).

### Languages

Configure private registry credentials per language so FOSSA can fetch dependencies from your internal registries. Each language has its own page in the sidebar: Java, NPM, Bower, Cocoapods, Ruby, Rust, Python, .NET, Git, Go, and Pub. These settings apply org-wide and are used at analysis time. See [JFrog Artifactory](/docs/integrations/jfrog-artifactory) and [Nexus](/docs/integrations/nexus) for setup details.

### Subscription

Review your plan and the features included at each tier in your organization's subscription settings. This area is hidden on on-premises deployments.

### Audit Logs

A timestamped record of significant actions across your organization. See [Audit Logs](/docs/organization-management/audit-logs).

## Editing settings

{% steps %}
{% step title="Open the General tab" %}
Hover over your username, select **Settings**, then open **Organization**.
{% /step %}
{% step title="Change a setting" %}
Update any field, for example, edit **Billing Email** or pick a **Default Role for New Users**.
{% /step %}
{% step title="Save" %}
Click **Save** in the page header to apply your changes.
{% /step %}
{% /steps %}

{% callout type="info" %}
Editing these settings requires admin permission: the **Edit** action on **Organization General Settings**. Without it, the fields are read-only.
{% /callout %}

## FAQ

**Why don't I see the Project Labels or Package Labels fields?**
Labels are a paid feature and are hidden on the free tier. Contact your FOSSA account team to enable them.

**Why is the Default Role for New Users field locked?**
Your organization uses single sign-on to manage user roles, so the default role is controlled by your identity provider rather than set here.

## What's next

- **[Inviting Users](/docs/organization-management/inviting-users)**: Add team members to your FOSSA organization.
- **[Role-Based Access Control](/docs/organization-management/role-based-access-control)**: Configure roles and permissions to control what users can do.
- **[Single Sign-On](/docs/organization-management/single-sign-on)**: Set up SSO to let users sign in through your identity provider.

---

Source: https://docs.fossa.com/docs/organization-management/default-project-settings

# Default Project Settings

Default project settings are the Security, Licensing, Quality, and other configuration values FOSSA applies to every newly imported project. You manage them from the **General** tab of [Organization Settings](/docs/organization-management/organization-settings). Each settings group gives you two choices: **Save** the defaults for future projects, or **Propagate** them onto projects that already exist.

## Save vs. Propagate

| Action | What it does |
| --- | --- |
| **Save** | New projects imported after you save begin using the new defaults. Existing projects keep their current settings. |
| **Propagate settings** | Pushes the selected defaults onto existing projects too. You choose which settings groups to override, so you can update one (for example, the security policy) without touching the others. |

## Propagating a default to existing projects

This example changes the default security policy for all projects while leaving each project's licensing policy untouched.

{% img src="/images/organization-management/default-project-settings-issue-policies.png" alt="Default Issue Policies Settings page with Quick Import Defaults and Licensing sections and per-section Propagate settings buttons" /%}

{% steps %}
{% step title="Select the new default and save" %}
On the General tab, choose a new security policy and click **Save**.
{% /step %}
{% step title="Propagate it to existing projects" %}
Click **Propagate settings**, then select **Override all projects to use security policy "_your policy_"**.
{% /step %}
{% /steps %}

Every existing and new project now uses the new security policy, while existing projects keep their individual licensing policy.

{% callout type="warning" %}
Changing a project's policy queues a fresh issue scan for that project, so the updated policy is used to scan the latest project revision. Only projects whose policy **actually changes** are re-scanned, projects already using the selected policy are left untouched.
{% /callout %}

{% callout type="info" %}
Propagate settings replaces the older **Make default** and **Propagate and Make Default** options. Choosing settings groups individually gives you granular control over which defaults get pushed to existing projects.
{% /callout %}

---

Source: https://docs.fossa.com/docs/organization-management/package-labels

# Package Labels

Package Labels let you annotate your dependencies with additional information, enabling better reporting, filtering, and automated issue management. Labels provide context about how a package is used within your projects or organization, helping your team make informed decisions about licensing obligations and compliance.

{% callout type="info" %}
Assigning package labels requires a paid (premium) subscription.
{% /callout %}

## Key concepts

**Label:** A string applied to a package. Names are 1–50 characters and may contain letters, numbers, dashes, underscores, periods (`.`), and spaces.

**Scope:** Defines where a label is applied. Package labels support three scopes:

| Scope | Where the label applies |
| --- | --- |
| **Organization** | Across all projects in your organization |
| **Project** | Only within the project |
| **Revision** | Only within the current revision of the project |

## Use cases

Package Labels are flexible and support a variety of scenarios, including:

**Usage-based labeling:**

- Marking dependencies as "Modified" or "Unmodified" to track changes that might affect license compliance.
- Indicating linkage type ("Statically Linked" or "Dynamically Linked") to determine how licensing rules apply.
- Tagging dependencies as "Dev", "Test", or "Production" to differentiate their usage context.

**Attribute-based labeling:**

- Adding Export Control Classification Numbers (ECCN) for export compliance reporting.
- Tracking FIPS compliance status.

## Managing labels

Labels are created and managed in **Organization Settings → General → Package Labels**.

{% callout type="info" %}
Label names must be 1–50 characters and may contain letters, numbers, dashes, underscores, periods (`.`), and spaces.
{% /callout %}

### Creating a label

{% steps %}
{% step title="Open Organization Settings" %}
Open the Settings page from the menu under your user account, then select the **Organization** tab.
{% /step %}
{% step title="Go to Package Labels" %}
Under **General**, navigate to the **Package Labels** section.

{% img src="/images/organization-management/package-labels-widget.png" alt="Package Labels section of Organization Settings with the search box, Add Label control, label count, and the list of existing labels" /%}
{% /step %}
{% step title="Add the label" %}
Click **Add Label** to create a label. Created labels are available across the organization.
{% /step %}
{% /steps %}

### Editing a label

In **Organization Settings → General → Package Labels**, click the edit icon beside a label to change its name.

### Deleting a label

In **Organization Settings → General → Package Labels**, click the **x** icon beside a label to delete it.

## Assigning a label to a package

{% steps %}
{% step title="Open the dependency list" %}
Navigate to the list of dependencies within a project.
{% /step %}
{% step title="Open the package menu" %}
Click the 3-dot menu to the right of a package and select **Manage Labels**.
{% /step %}
{% step title="Select labels" %}
In the modal, select the label(s) you want applied to the package.
{% /step %}
{% /steps %}

Package labels can also be applied to a package via the [Package Index](https://app.fossa.com/packages).

## Adding a package label ignore rule

{% steps %}
{% step title="Open an issues view" %}
Navigate to Quality, Security, or Licensing issues.
{% /step %}
{% step title="Add an ignore rule" %}
Click **Ignore Rules**, then **Add Ignore Rule**.
{% /step %}
{% step title="Select the package label condition" %}
Select the option **"If the dependency has Package Labels assigned"** and add the package labels you want the rule to apply to.
{% /step %}
{% step title="Save" %}
Complete the form and click **Ignore** to save the rule.
{% /step %}
{% /steps %}

Package label ignore rules are viewable alongside other ignore rules on the ignore rules page.

## Reports with package labels

- Include package labels in a report by checking the **Package Labels** box when generating a report in the UI, or by using the `?includePackageLabels=true` parameter via the API. Package labels appear in-line with each package in the report.
- Exclude packages from a report based on their package labels by selecting the labels to exclude from the dropdown in the UI when generating a report.

## Filtering packages by label

Dependencies across the product can be filtered by applied package label(s) by selecting the label(s) in the filter dropdown.

## Permissions

- **Creating and deleting labels:** Org Admins can create and delete labels by default. This uses the existing Project labels permission.
- **Assigning project-scoped labels:** Team Admins can assign project-scoped labels by default.
- **Assigning organization-scoped labels:** Admins can assign organization-scoped labels by default.

## Managing package labels via the API

The API reference for package labels is available in the [Package Labels API reference](/docs/api/reference/package-labels).

## Managing package labels via the FOSSA CLI

Package labels are supported when using a `fossa-deps` file. See the [fossa-deps documentation](https://github.com/fossas/fossa-cli/blob/master/docs/references/files/fossa-deps.md).

---

Source: https://docs.fossa.com/docs/organization-management/audit-logs

# Audit Logs

Audit logs give you a timestamped record of significant actions taken across your FOSSA organization, who changed a policy, resolved an issue, invited a user, or imported a project. They help administrators answer *who did what, when, and where*, reconstruct how your environment reached its current state, and recover from mistakes (an accidental policy change, a project uploaded to the wrong place, an issue resolved without sign-off). To prevent those mistakes in the first place, tighten who can do what with [Role-Based Access Control](/docs/organization-management/role-based-access-control).

## How audit logging works

FOSSA records an entry automatically whenever a user performs a tracked action. This happens for every organization, with nothing to turn on or configure, the log always accumulates on its own. What the Enterprise plan unlocks is the ability to **view and export** that history, not the recording itself.

- **Every entry captures the actor and the change**: the user (by email or username), their role at the time, a timestamp, and a human-readable description of what happened.
- **Actions are organized by topic and action type**: for example *Policy → Change Project Policy* or *User → Update User Role*. These power the filters on the page.
- **Entries are immutable and organization-wide**: the log spans every team, project, and setting in the organization; it is a read-only history, not something users can edit.

## Viewing and filtering audit logs

{% steps %}
{% step title="Open the Audit Logs page" %}
Go to **Account Settings → Audit Logs**. The page opens showing the most recent activity first.

{% img src="/images/organization-management/audit-logs-page.png" alt="Audit Logs page showing the activity table with email, role, date, and action columns and the filter bar" /%}
{% /step %}
{% step title="Narrow the results" %}
Use the filter bar to focus the view:

- **Users**: filter by one or more people, selected by email or username.
- **Actions**: filter by specific action types, grouped by the resource they affect (e.g. Policy, User, Project).
- **Date range**: click the date button to choose a range. The view defaults to the **last month**.
{% /step %}
{% step title="Sort and page through entries" %}
Click a column header to sort by that column. Use the controls at the bottom of the table to move between pages or change the page size.
{% /step %}
{% /steps %}

## Exporting audit logs to CSV

{% callout type="warning" %}
The export always uses your current filters, and a **start and end date must be set**. Adjust the date range and any user/action filters before exporting to scope the file.
{% /callout %}

{% steps %}
{% step title="Set the filters you want to export" %}
Choose the date range, users, and actions that define the slice of activity you need. The export mirrors whatever filters are applied on screen.
{% /step %}
{% step title="Click Export logs as CSV" %}
FOSSA generates the file in the background as a report job, so you can keep working while it runs.
{% /step %}
{% step title="Retrieve the CSV" %}
You'll be notified when the export is ready. The completed report is delivered to your account email.
{% /step %}
{% /steps %}

## What gets logged

FOSSA tracks actions across roughly thirty resource types. The table below groups the most common ones with example actions, it's representative, not exhaustive.

| Category | Example logged actions |
| :--- | :--- |
| **Users, roles & teams** | Add, delete, enable, or disable a user; invite a user; change a user's role (organization or team); create, edit, or delete roles; create, rename, or delete a team; add or remove team members; manage service accounts |
| **Projects, releases & dependencies** | Import or upload a project (CLI, archive, VCS); delete a project; add a revision; queue a scan; add, remove, overwrite, or ignore dependencies; change project labels, filters, or settings; add or remove projects from a release group; create a release |
| **Issues** | Resolve or unresolve; ignore or unignore; export; create an issue ignore rule; add, update, or remove a license on a package |
| **Policies & licenses** | Create a policy; change the default, project, or release-group policy; add, update, or remove policy rules; change the default action for uncategorized licenses; conclude or unconclude a license |
| **Organization & security settings** | Edit SAML or LDAP settings; edit organization domains; set up or remove MFA; manage API tokens, OIDC providers, and webhooks; share an SBOM; publish or unpublish a report; manage public portal tokens |

## Audit log entry fields

Each entry shown on the page consists of these fields:

| Field | Description |
| :--- | :--- |
| **Email or Username** | The user who performed the action, shown by current email or username. |
| **Role** | The user's role at the time the action occurred. |
| **Date** | Timestamp of when the action occurred. |
| **Action** | A human-readable description of what happened. |

{% callout type="info" %}
These four columns are what the page displays. Depending on the type of action or resource, an entry may also record additional structured fields behind the scenes, for example a `teamId`, `projectId`, or the before-and-after values of a changed setting. The complete set of fields for an entry is returned by the [audit logs API](/docs/api).
{% /callout %}

## Who can view audit logs

Access is governed by [Role-Based Access Control](/docs/organization-management/role-based-access-control), not by a fixed role. A user can view the audit log only if their role grants the **Organization Audit → View** permission.

- The **Audit Logs** tab appears under **Account Settings** only for users whose role has that permission, others won't see it at all.
- Owners and admins can grant the permission to additional roles through RBAC role configuration, so view access is no longer limited to administrators.
- Audit logs are scoped to the whole organization.

## FAQ

**Why don't I see the Audit Logs page?**
Two things gate it. First, Audit Logs is an Enterprise feature; it's unavailable on other plans. Second, even on Enterprise the **Audit Logs** tab (under **Account Settings**) only appears if your role has the **Organization Audit → View** permission. Ask an owner or admin to grant it.

**Who can view audit logs?**
Any user whose role has the **Organization Audit → View** permission, not just administrators. Configure this through [Role-Based Access Control](/docs/organization-management/role-based-access-control).

**Can I access audit logs through the API?**
Yes. `GET /api/audit_logs` returns the same entries and supports the same filters (user, action, topic, and date range). See the [API reference](/docs/api).

---

Source: https://docs.fossa.com/docs/organization-management/counting-contributors

# Counting Contributors

FOSSA tracks the unique developers ("contributors") who have committed to the git projects your organization analyzes. The count is the basis for contributor-based plans, so administrators use it to understand current usage and how it trends over time. This page explains how the count is calculated and how to email yourself the contributor report.

## How contributor counting works

FOSSA derives the count from commit history across the git projects running in your organization. Two things shape the number you see:

- **Two rolling windows are tracked**: FOSSA records both the contributors active in the **last 90 days** and the **last 365 days**. The 365-day count is the one that reflects your organization's overall contributor usage; the 90-day count shows more recent activity. Both appear in the report.
- **Similar emails are de-duplicated**: where it can, FOSSA groups commits from similar email addresses for the same person into a single contributor, so one developer committing under several addresses is not over-counted.

A weekly snapshot of both counts is captured automatically, building a history you can use to see how your contributor count changes over time.

{% callout type="info" %}
For projects imported from a **git** provider, FOSSA reads contributors from the repository's commit history. For projects uploaded with the **FOSSA CLI**, contributor data is gathered on the CLI side at analysis time. Either way, the contributors roll up into the same organization count.
{% /callout %}

## Emailing your contributor report

The contributor report is delivered by email as a downloadable archive. FOSSA does not render it in the browser.

{% steps %}
{% step title="Open organization settings" %}
Go to **Settings → Organization**.
{% /step %}
{% step title="Send the report" %}
Scroll to the **Contributors** section at the bottom of the page and click **Email Weekly Contributor Report to {your email}**. A confirmation appears: *Report will be emailed to you within a few hours.*
{% /step %}
{% step title="Download from the email" %}
Open the email FOSSA sends you and use the download link. The link expires **24 hours** after the report is generated.
{% /step %}
{% /steps %}

{% callout type="warning" %}
You need permission to **View All Projects** across the organization to see the Contributors section and request the report. If the button is disabled, ask an administrator to grant org-wide project access. See [Role-Based Access Control](/docs/organization-management/role-based-access-control).
{% /callout %}

## What the report contains

The report downloads as a single `.zip` archive holding several CSV files:

| File | Contents |
| --- | --- |
| **Summary** | One row per weekly snapshot, with the active contributor count in the last 90 days and last 365 days, a trend of your count over the past year. |
| **Latest weekly report** | The current contributor breakdown, listing each contributor and whether they were active in the last 90 days. |
| **Per-snapshot reports** | The individual weekly contributor reports captured over the last year. |

## FAQ

**Which number does my plan use?**
The **last 365 days** unique-contributor count is the one that reflects your organization's overall usage. The 90-day count is provided alongside it to show more recent activity.

**A developer shows up more than once: why?**
FOSSA de-duplicates similar email addresses, but it can only group what it can match. Commits made under unrelated email addresses (for example, a personal address and a work address that share nothing in common) may appear as separate contributors.

**My CLI project's contributors look different from its git history.**
Contributors for CLI-uploaded projects are collected by the CLI at analysis time, not read from the remote repository, so the set reflects what was available in the environment where `fossa analyze` ran.

---

Source: https://docs.fossa.com/docs/organization-management/inviting-users

# Inviting Users

Invite teammates to your FOSSA organization by email. Each person you invite receives a link, creates their FOSSA account, and is added to your organization automatically. Inviting users lives under **Settings → Organization → Users**.

{% callout type="warning" %}
If your organization authenticates through **SSO** (or OAuth), email invites are disabled, the **Invite Users** flow won't appear. Users join through the SSO sign-on workflow instead. To send invites, an administrator must switch the organization's authentication mode away from SSO/OAuth.
{% /callout %}

## Inviting users by email

{% steps %}
{% step title="Open the Users page" %}
Go to **Settings → Organization → Users**.

{% img src="/images/organization-management/inviting-users-page.png" alt="Users settings page with the members list, Invite Users button, and per-user organization role and teams" /%}
{% /step %}
{% step title="Open the invite dialog" %}
Click **Invite Users** to open the invite dialog.
{% /step %}
{% step title="Enter email addresses" %}
In the **Email Address(es)** field, type an email address and press **Enter** to add it to the list. Repeat for each person you want to invite.
{% /step %}
{% step title="Send the invites" %}
Click **Send Invite**. Each invited person receives an email containing an invite link.
{% /step %}
{% /steps %}

Invited users must click the link in their email and create a FOSSA account. Once they do, they're added to your organization automatically.

## Result

Pending invitations appear under the **Invites** tab on the Users page, where you can track who hasn't yet accepted. As people accept, they move to the **Members** tab.

{% callout type="info" %}
An invite link is valid for 48 hours. If it expires before the recipient accepts, repeat the steps above to send a fresh invitation.
{% /callout %}

## What's next

- **[Role-Based Access Control](/docs/organization-management/role-based-access-control)**: Assign roles to control what your invited users can view and edit.
- **[Organization Settings](/docs/organization-management/organization-settings)**: Set the default role applied automatically to new users.

---

Source: https://docs.fossa.com/docs/organization-management/role-based-access-control

# Roles & Permissions

Role-Based Access Control (RBAC) governs which FOSSA features a user can reach, which projects they can see, and what they're allowed to do with them. Access is granted two ways: an **organization role** that applies across your whole org, and **team roles** that scope access to specific projects and release groups.

## How RBAC works

There are two scopes, and a user's effective access is the combination of both:

- **Organization role**: applies to every project in the organization and to org-level settings such as billing, policies, and user management. A user has at most one organization role.
- **Team roles**: scope access to the projects and release groups owned by a team. A user is assigned a role in each team they belong to, and can be on multiple teams.

A user can have no organization role at all. In that case they get no org-level access, only the projects granted through their team memberships.

## Organization roles

Assign organization roles on the **Settings → Organization → Users** page. **Admin**, **Editor**, and **Viewer** are built in and can't be edited or deleted. **None** isn't a role, it's the option you pick to leave a user with no organization role at all.

{% img src="/images/organization-management/rbac-roles.png" alt="Roles settings page listing the built-in Admin, Editor, Team Admin, Team Editor, Team Viewer, and Viewer roles with an Add Role button" /%}

| Role | Access |
| :--- | :--- |
| **Admin** | Full access to every project; import projects; create, edit, and delete policies; manage teams, users, and roles; access and change billing; correct licensing information and metadata for dependencies. |
| **Editor** | Full access to every project; import projects; view and edit policies; change project settings; rebuild and rescan projects; correct licensing information and metadata for dependencies. |
| **Viewer** | Read-only access to all projects, issues, and policies. Cannot import projects, create Jira tickets, modify packages, or resolve issues. |
| **None** | No organization-level access. The user can only reach projects granted through their team memberships. |

{% callout type="info" %}
New users are assigned your organization's **default role**, configured under **Default Role for New Users** on the [Organization settings](/docs/organization-management/organization-settings) page. Set it to match how much access new members should get out of the box.
{% /callout %}

## Team roles

Manage teams on the **Settings → Organization → Teams** page. A user with a team role must belong to a team before they can see any projects. The three team roles are built in and can't be edited or deleted.

| Role | Access (within their teams only) |
| :--- | :--- |
| **Team Admin** | Import and delete projects; change project settings and metadata; rebuild and rescan projects; manage the team's users; manage team options. |
| **Team Editor** | Import projects; change project settings; rebuild and rescan projects. |
| **Team Viewer** | Read-only access to the team's projects. |

Team roles only grant access to that team's projects, not to org-wide features like policies.

{% callout type="warning" %}
Team Admins and Team Editors have full access to project metadata, but editing a **dependency** changes it across the entire organization. That requires an organization role (**Admin** or **Editor**), a team role alone isn't enough.
{% /callout %}

## Assigning an organization role

{% steps %}
{% step title="Open the Users page" %}
Go to **Settings → Organization → Users**.
{% /step %}
{% step title="Set the user's role" %}
Find the user and assign **Admin**, **Editor**, **Viewer**, or **None**. **None** leaves the user with no organization role, limiting them to team-based access.
{% /step %}
{% /steps %}

## Creating teams and assigning team roles

Teams gate which projects a user can see. Create a team, add members, and give each member a team role.

{% steps %}
{% step title="Open the Teams page" %}
Go to **Settings → Organization → Teams**.
{% /step %}
{% step title="Create or open a team" %}
Create a new team, or open an existing one to manage its members and projects.
{% /step %}
{% step title="Add users and assign team roles" %}
Add users to the team and give each one a team role, **Team Admin**, **Team Editor**, or **Team Viewer**.
{% /step %}
{% step title="Add projects" %}
Add the projects and release groups the team should have access to.
{% /step %}
{% /steps %}

## Creating a custom role

Beyond the built-in roles, you can create custom roles with your own set of permissions at either the organization or team scope.

{% steps %}
{% step title="Choose the scope" %}
When you create a role, choose its **scope**, **Organization** or **Team**. The scope determines which permissions are available; some org-level capabilities, such as managing users, can only be granted by an organization-scoped role.
{% /step %}
{% step title="Select permissions" %}
Select every permission that users with this role should have.
{% /step %}
{% step title="Save and assign" %}
Save the role, then assign it to users just like a built-in role.
{% /step %}
{% /steps %}

{% callout type="warning" %}
A role's scope can't be changed after it's created. To move a role to a different scope, create a new one.
{% /callout %}

## Auto-assigning roles through SSO

When integrated with **Single Sign-On**, FOSSA can assign organization roles and team memberships from SAML attributes every time a user logs in.

**`role` attribute**; sets the user's organization role. Accepted values are case-insensitive:

| Value | Role |
| :--- | :--- |
| `admin` | Admin |
| `editor` | Editor |
| `viewer` | Viewer |

Any other value is matched against an organization-scoped **custom role** of that name.

**`teams` attribute**, a team name or list of team names. FOSSA assigns the user to exactly those teams; any team that doesn't already exist is created automatically.

{% callout type="info" %}
Configuring these attributes is part of your SAML setup. See [Single Sign-On](/docs/organization-management/single-sign-on), or contact [support@fossa.com](mailto:support@fossa.com) for help.
{% /callout %}

## FAQ

**Can I edit or delete the built-in roles?**
No. The three organization roles and three team roles are built in and can't be changed or removed. Create a custom role instead.

**What happens if a user has no organization role?**
They get no organization-level access. They can still see and work on projects through any teams they belong to, according to their team role.

**Can a team role let someone edit a dependency?**
No. Editing a dependency changes it across the whole organization, so it requires an organization role (Admin or Editor), even for Team Admins and Team Editors.

**Can I change a custom role's scope after creating it?**
No. Scope is fixed at creation. Create a new role with the scope you need.

**Why don't email invites appear for my organization?**
If you use SSO, email invites are disabled and users join through the SSO sign-on flow instead. See [Inviting Users](/docs/organization-management/inviting-users).

## What's next

- **[Inviting Users](/docs/organization-management/inviting-users)**: Add team members and assign them roles.
- **[Organization Settings](/docs/organization-management/organization-settings)**: Set the default role for new users joining your organization.

---

Source: https://docs.fossa.com/docs/organization-management/single-sign-on

# Single Sign-On

In addition to FOSSA's built-in authentication, you can let your users sign in through your corporate identity provider. FOSSA supports login and account provisioning through **G Suite** (Google Workspace), **SAML** identity providers such as Okta, Auth0, Microsoft Entra ID (Azure AD), and Active Directory Federation Service, and **LDAP**.

Enabling single sign-on bypasses FOSSA's own authentication and verifies your users against your identity provider instead. How a user signs in depends on the provider you configure.

## How your users sign in

| Identity provider | How users sign in |
| --- | --- |
| G Suite (Google Workspace) | Click **Log in with Google** on the FOSSA login page. |
| SAML (Okta, Auth0, Entra ID, ADFS) | Enter their email on the FOSSA login page and get redirected to your provider; or launch FOSSA directly from your provider's portal. |
| LDAP | Enter their username and password at your organization's `org-name.fossa.app` subdomain. |

## Set up your identity provider

- [Active Directory Federation Service](/docs/organization-management/single-sign-on/active-directory-federation-service)
- [Auth0](/docs/organization-management/single-sign-on/auth0)
- [G Suite (Google Workspace)](/docs/organization-management/single-sign-on/g-suite)
- [LDAP](/docs/organization-management/single-sign-on/ldap)
- [Microsoft Entra ID (Azure AD)](/docs/organization-management/single-sign-on/microsoft-entra-id)
- [Okta](/docs/organization-management/single-sign-on/okta)

## Claiming email domains

Domain claiming lets you associate one or more email domains with your FOSSA organization, so that any user who signs in with an email address on a claimed domain is automatically routed through your SSO provider rather than FOSSA's built-in login.

When a domain is claimed:

- Users who enter an email on that domain at the FOSSA login page are redirected to your SSO provider automatically.
- New users on the domain cannot bypass SSO by registering directly with a password.
- Existing users on the domain who previously had a password-based account will be prompted to authenticate through SSO on their next login.

To claim a domain, go to **Settings → Organization → Authentication** and use the domain claiming flow in the SSO configuration panel. FOSSA will verify domain ownership before activating the claim. If you run into issues, contact [support@fossa.com](mailto:support@fossa.com).

## Provisioning and login methods

When an account is provisioned through single sign-on, password-based login is disabled for that user. To add users who keep password login, invite them by email. See [Inviting Users](/docs/organization-management/inviting-users). Invited users can use both password and single sign-on login.

---

Source: https://docs.fossa.com/docs/organization-management/single-sign-on/active-directory-federation-service

# Active Directory Federation Service

Active Directory Federation Service (ADFS) acts as a SAML 2.0 identity provider for FOSSA. To connect them, you create a Relying Party Trust for FOSSA in ADFS, map your Active Directory attributes to the claims FOSSA expects, then give FOSSA your ADFS sign-on URL and token-signing certificate.

{% callout type="info" %}
SAML single sign-on must be enabled for your organization before the settings below appear. SSO is a [premium feature](/docs/organization-management/single-sign-on), contact your FOSSA account team to enable it.
{% /callout %}

Before you start, open FOSSA's authentication settings in another tab: go to **Settings → Organization → Authentication**. The **Callback URL** and **Audience URI / SP Entity ID** values there are needed while configuring ADFS.

## Configuring the Relying Party Trust

{% steps %}
{% step title="Open the AD FS Management console" %}
On your ADFS server, open **Server Manager**, then choose **Tools → AD FS Management**.
{% /step %}
{% step title="Start the Add Relying Party Trust wizard" %}
Click **Add Relying Party Trust** to open the wizard. Select **Claims aware** and click **Start**, then choose to **enter data about the relying party manually**.
{% /step %}
{% step title="Enable the SAML 2.0 WebSSO protocol" %}
Tick **Enable support for the SAML 2.0 WebSSO protocol**. In the box underneath, paste the **Callback URL** from FOSSA's **Settings → Organization → Authentication** page.
{% /step %}
{% step title="Set the relying party trust identifier" %}
Add a relying party trust identifier that matches the **Audience URI / SP Entity ID** value shown on FOSSA's Authentication page.

{% callout type="warning" %}
The identifier must equal the **Audience URI / SP Entity ID** that FOSSA generates for your organization. Older setups used the literal string `FOSSA`; copy the current value from the Authentication page instead, a mismatch causes the SAML audience check to fail.
{% /callout %}
{% /step %}
{% step title="Enable the claims issuance policy" %}
Tick **Configure claims issuance policy for this application**, then finish the wizard. This opens the policy editor, where you define what Active Directory sends to FOSSA at login.
{% /step %}
{% step title="Map Active Directory attributes to claims" %}
Click **Add Rule** and choose the **Send LDAP Attributes as Claims** template. Give the rule a name, set **Active Directory** as the attribute store, and add these mappings:

| LDAP attribute | Outgoing claim type |
| --- | --- |
| E-Mail-Addresses | Name ID |
| Given-Name | firstName |
| Surname | lastName |

{% callout type="warning" %}
FOSSA reads the user's email from the **Name ID**, and reads `firstName` and `lastName` to build their display name. Spell the outgoing claim types exactly as shown, a mismatch leaves new users without a name or blocks login entirely.
{% /callout %}
{% /step %}
{% step title="Export the token-signing certificate" %}
In the AD FS Management tool, go to **Service → Certificates** in the left sidebar. Select the token-signing certificate and click **View Certificate**. On the **Details** tab, click **Copy to File** and export it as **Base-64 encoded X.509 (.CER)**. Open the exported file in a text editor, you'll paste its contents into FOSSA next.
{% /step %}
{% step title="Finish setup in FOSSA" %}
Back in FOSSA, on the **Settings → Organization → Authentication** page:

1. In **Identity Provider Single Sign On URL**, enter your ADFS server URL with `/adfs/ls` appended (for example, `https://adfs.example.com/adfs/ls`).
2. In **Certificate**, paste the contents of the certificate you exported.
3. Click **Save Changes**.
{% /step %}
{% /steps %}

## Result

ADFS is now configured to authenticate users to FOSSA. For their first login, users sign in one of two ways:

- Visit the SAML login link shown on FOSSA's **Authentication** page, **or**
- Go to `/adfs/ls/idpinitiatedsignon` on your ADFS server, if IdP-initiated sign-on is enabled.

After their first login, users can sign in by entering their email address on the FOSSA login page.

{% callout type="info" %}
FOSSA can also set each user's organization role and synchronize their team membership from SAML attributes. See the [SAML attributes guide](/docs/organization-management/single-sign-on/saml-attributes) for the supported `role` and `teams` claims.
{% /callout %}

---

Source: https://docs.fossa.com/docs/organization-management/single-sign-on/auth0

# Auth0

Auth0 acts as a SAML 2.0 identity provider for FOSSA. To connect them, you create an application in Auth0, enable its SAML2 Web App addon, then exchange a signing certificate and sign-on URLs between Auth0 and FOSSA.

{% callout type="info" %}
SAML single sign-on must be enabled for your organization before the settings below appear. SSO is a [premium feature](/docs/organization-management/single-sign-on), contact your FOSSA account team to enable it.
{% /callout %}

Before you start, open FOSSA's authentication settings in another tab: go to **Settings → Organization → Authentication**. The **Callback URL** shown there is needed while configuring Auth0, and you'll paste Auth0's certificate and sign-on URL back into this page at the end.

## Configuring the Auth0 application

{% steps %}
{% step title="Create an application in Auth0" %}
In the Auth0 admin panel, go to **Applications → Create Application** and choose **Single Page App** as the application type. You can ignore the Quick Start wizard that opens.
{% /step %}
{% step title="Open advanced settings" %}
Open the **Settings** tab from the bar at the top, scroll to the bottom, and click **Show Advanced Settings**.
{% /step %}
{% step title="Copy the signing certificate into FOSSA" %}
On the **Certificates** tab, copy the **Signing Certificate**. In FOSSA, on the **Settings → Organization → Authentication** page, paste it into the **Certificate** field.
{% /step %}
{% step title="Enable and configure the SAML2 addon" %}
Scroll back to the top and open the **Addons** tab, then click **SAML2 Web App**. Copy the **Callback URL** from FOSSA's Authentication page into the **Application Callback URL** field in Auth0. In the **Settings** box, paste the following, then click **Save**:

```json
{
  "nameIdentifierProbes": [
    "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress"
  ]
}
```

The `nameIdentifierProbes` value tells Auth0 to send the user's email address as the SAML Name ID, which FOSSA uses to identify the user.
{% /step %}
{% step title="Copy the identity provider login URL into FOSSA" %}
Open the **Usage** tab and copy the **Identity Provider Login URL**. In FOSSA, paste it into the **Identity Provider Single Sign On URL** field on the Authentication page.
{% /step %}
{% step title="Save in FOSSA" %}
Click **Save Changes** on FOSSA's Authentication page.
{% /step %}
{% /steps %}

## Result

Auth0 is now configured to authenticate users to FOSSA. For their first login, users must visit the **Identity Provider Login URL** from Auth0, which redirects them to FOSSA and creates their account. After that, they can sign in directly from Auth0, or by entering their email address on the FOSSA login page.

{% callout type="info" %}
FOSSA can also set each user's organization role and synchronize their team membership from SAML attributes. See the [SAML attributes guide](/docs/organization-management/single-sign-on/saml-attributes) for the supported `role` and `teams` claims.
{% /callout %}

---

Source: https://docs.fossa.com/docs/organization-management/single-sign-on/g-suite

# G Suite

G Suite (Google Workspace) acts as a single sign-on provider for FOSSA. Once you claim your Google Workspace domain, anyone with a Google account on that domain can sign in to FOSSA with Google, and first-time users are added to your organization automatically, with no invite required.

{% callout type="info" %}
Single sign-on is a premium feature, contact your FOSSA account team to enable it. You also need an organization admin account with permission to edit authentication settings, and a Google account on the Workspace domain you want to claim.
{% /callout %}

{% callout type="warning" %}
Self-hosted deployments need extra configuration before Google Workspace SSO will work. Contact [support@fossa.com](mailto:support@fossa.com) for details.
{% /callout %}

## Claiming your Google Workspace domain

{% steps %}
{% step title="Open your authentication settings" %}
Go to **Settings → Organization → Authentication**.
{% /step %}
{% step title="Choose an authentication method" %}
Under **Authentication Method**, pick how your users sign in:

- **SSO + Email Address**: users can join and sign in through Google Workspace SSO, *and* invited users can still sign in with a password or another social login.
- **SSO Only**: every user must authenticate through SSO. Password login is disabled and no invites are required.
{% /step %}
{% step title="Select Google Workspace as the SSO method" %}
Under **SSO Configuration**, open the **SSO Method** dropdown and choose **Google Workspace (G Suite)**.
{% /step %}
{% step title="Claim your domain" %}
Under **Redirect Email Domains**, click **Claim New Domain**.

{% callout type="warning" %}
The **Claim New Domain** button stays disabled until you save your authentication settings. Save your changes first, then claim the domain.
{% /callout %}
{% /step %}
{% step title="Sign in with Google" %}
In the dialog, follow the prompts and click **Sign in with Google**. Sign in with a Google account whose email is on the domain you want to claim, for example, `you@your-company.com`, not a personal `@gmail.com` address.
{% /step %}
{% step title="Confirm the connection" %}
Google redirects you back to FOSSA. The claimed domain now appears under **Redirect Email Domains**, confirming the connection succeeded.
{% /step %}
{% /steps %}

{% callout type="warning" %}
You can only claim a Google Workspace (hosted) domain, personal `gmail.com` and `googlemail.com` addresses are rejected. A domain can also be claimed by only one organization, and can't be claimed if it's already in use with another SSO method.
{% /callout %}

## Result

Users whose email is on the claimed domain can now click **Sign in with Google** on the FOSSA login page. Anyone signing in for the first time is added to your organization automatically, no invite needed.

To add users who should keep password login, invite them by email instead. See [Inviting Users](/docs/organization-management/inviting-users). Invited users can sign in with both a password and single sign-on.

---

Source: https://docs.fossa.com/docs/organization-management/single-sign-on/ldap

# LDAP

LDAP authentication lets your users sign in to FOSSA with their existing corporate directory credentials. FOSSA connects to your directory with a read-only service account, verifies each user at login, provisions their FOSSA account automatically on first sign-in, and can synchronize [Teams](/docs/organization-management/role-based-access-control) from your directory groups.

To configure LDAP, you need details about how to reach your directory server and how your users and groups are structured. Before you start, open FOSSA's authentication settings in another tab: go to **Settings → Organization → Authentication**.

## Configuring LDAP authentication

{% steps %}
{% step title="Open your authentication settings" %}
Go to **Settings → Organization → Authentication** and choose **LDAP**.
{% /step %}
{% step title="Enter your server connection details" %}
Provide your directory's host, port, and SSL setting. See **Server settings** below.
{% /step %}
{% step title="Add bind credentials" %}
Provide the read-only account FOSSA uses to connect. See **Bind credentials** below.
{% /step %}
{% step title="Configure the user schema" %}
Tell FOSSA where to find users and which attributes hold their email and name. See **User schema settings** below.
{% /step %}
{% step title="Synchronize teams from directory groups (optional)" %}
Enable **Synchronize teams** and configure your group schema to mirror directory groups as FOSSA Teams. See **Group and team sync settings** below.
{% /step %}
{% step title="Test the connection" %}
Click **Test Connection**. FOSSA simulates a user login and shows the information returned by your directory, so you can confirm your settings before saving.
{% /step %}
{% step title="Save your configuration" %}
Once the test succeeds, save your changes to enable LDAP authentication for your organization.
{% /step %}
{% /steps %}

## Server settings

| Setting | Description |
| --- | --- |
| **Hostname or IP Address** | The host where your directory is reachable, for example `ldap.example.com` or `ad.example.com`. |
| **Port** | The port your directory server listens on, for example `389`, or `636` for SSL. |
| **Use SSL** | Enable this to connect to your directory over SSL. |

## Bind credentials

FOSSA uses these credentials to open a read-only connection to your directory, enough to verify that the authenticating user exists and, optionally, which groups they belong to.

| Setting | Description |
| --- | --- |
| **Distinguished Name** | The distinguished name of the account FOSSA uses to connect to your directory server. |
| **Secret** | The password for that account. |

## User schema settings

| Setting | Description |
| --- | --- |
| **User Base Distinguished Name** | The root DN for user search queries, for example `dc=example,dc=com` or `o=fossa-users,dc=example,dc=com`. |
| **User Search Filter** | The filter used to find a user. Must include `{{username}}`, which FOSSA replaces with the login username, for example `(uid={{username}})` or `(&(objectCategory=Person)(uid={{username}}))`. |
| **User Email attribute** | The attribute that holds the user's email, for example `mail`. |
| **Name attribute** | The attribute that holds the user's display name, for example `cn` or `displayName`. |
| **Username attribute** | The attribute that holds the user's username. *Self-hosted deployments only.* |

## Group and team sync settings

When **Synchronize teams** is enabled, FOSSA creates a Team for each group your directory returns and adds the user to it. If a user is later removed from a group in your directory, FOSSA removes them from the matching Team on their next login.

| Setting | Description |
| --- | --- |
| **Synchronize teams** | Enable to create FOSSA Teams from your directory groups and keep membership in sync at each login. |
| **Group Base Distinguished Name** | The root DN for group search queries, for example `dc=example,dc=com` or `o=fossa-users,dc=example,dc=com`. |
| **Group Name attribute** | The attribute that holds the group's name, for example `cn`. |
| **Group DN attribute** | The attribute from the user object used to find the user's group membership, for example `dn`. |
| **Group Search Filter** | The filter used to find a user's groups. May include `{{username}}` or `{{dn}}` (the user attribute named above), for example `(&(objectclass=group)(uniqueMember={{username}}))` or `(&(objectclass=groupOfUniqueNames)(uniqueMember={{dn}}))`. |

## How your users sign in

After you save your LDAP configuration, users sign in with their directory username and password at your organization's subdomain (`your-org.fossa.app`). FOSSA verifies each user against your directory and creates their FOSSA account automatically on first login.

{% callout type="info" %}
Synchronized Teams appear in FOSSA just like manually created ones. To control what their members can do, see [role-based access control](/docs/organization-management/role-based-access-control).
{% /callout %}

---

Source: https://docs.fossa.com/docs/organization-management/single-sign-on/microsoft-entra-id

# Microsoft Entra ID (Azure AD)

Microsoft Entra ID (formerly Azure AD) acts as a SAML 2.0 identity provider for FOSSA. To connect them, you register FOSSA as an enterprise application in Entra, exchange a few values between Entra and FOSSA's authentication settings, then hand FOSSA your Entra sign-on URL and signing certificate.

{% callout type="info" %}
SAML single sign-on must be enabled for your organization before the settings below appear. SSO is a [premium feature](/docs/organization-management/single-sign-on), contact your FOSSA account team to enable it.
{% /callout %}

Before you start, open FOSSA's authentication settings in another tab: go to **Settings → Organization → Authentication**. The **Callback URL** and **Audience URI / SP Entity ID** values shown there are needed while configuring Entra.

## Configuring SSO with Microsoft Entra ID

{% steps %}
{% step title="Set the authentication method in FOSSA" %}
On the **Settings → Organization → Authentication** page, set the access method to **SSO + Email Address** and the SSO method to **SAML**. Keep this page open; you'll copy its **Callback URL** and **Audience URI / SP Entity ID** into Entra next.
{% /step %}
{% step title="Create the FOSSA enterprise application in Entra" %}
In the Azure portal, go to **Microsoft Entra ID → Enterprise applications → New application → Create your own application**. Name it FOSSA and register it as a non-gallery app. Open the application's **Single sign-on** page and choose **SAML**.
{% /step %}
{% step title="Enter FOSSA's SAML values in Entra" %}
Edit the **Basic SAML Configuration** section and set:

| Entra field | Value from FOSSA |
| --- | --- |
| Identifier (Entity ID) | **Audience URI / SP Entity ID** |
| Reply URL (Assertion Consumer Service URL) | **Callback URL** |

{% callout type="warning" %}
Copy the **Audience URI / SP Entity ID** exactly as FOSSA generates it for your organization. Don't put a `login.microsoftonline.com` URL in the Identifier field; that URL is Entra's sign-on URL, which you'll add to FOSSA in a later step.
{% /callout %}
{% /step %}
{% step title="Download the certificate and copy the login URL from Entra" %}
In the **SAML Certificates** section, download the **Certificate (Base64)**. Then, in the **Set up FOSSA** section, copy the **Login URL**.
{% /step %}
{% step title="Finish setup in FOSSA" %}
Back on FOSSA's **Settings → Organization → Authentication** page:

1. In **Identity Provider Single Sign On URL**, paste the **Login URL** you copied from Entra.
2. In **Certificate**, paste the contents of the Base64 certificate you downloaded.
3. Set both access-control options to **Mixed control**. This keeps local admin access available if you ever need to sign in without SSO.
4. Click **Save Changes**.
{% /step %}
{% step title="Register your email domain" %}
On the Authentication page, register your organization's email domain. FOSSA sends a verification email to the domain's designated address; click **Approve** in that email to link the domain to your organization.
{% /step %}
{% /steps %}

## Result

Microsoft Entra ID is now configured to authenticate users to FOSSA. Users sign in one of two ways:

- Enter their email address on the FOSSA login page and get redirected to Entra, **or**
- Launch FOSSA from the Entra **My Apps** portal.

{% callout type="info" %}
FOSSA can also set each user's organization role and synchronize their team membership from SAML attributes. See the SAML attributes guide for the supported `role` and `teams` claims.
{% /callout %}

## Mapping Entra ID groups to FOSSA teams

This step is optional. Configure it to have Entra send each user's group memberships so FOSSA can assign them to teams automatically at login.

{% steps %}
{% step title="Open the FOSSA application's claims editor" %}
In the Azure portal, go to **Microsoft Entra ID → Enterprise applications**, select your **FOSSA** application, open **Single sign-on**, and click **Edit** under **Attributes & Claims**.
{% /step %}
{% step title="Add the group claim" %}
Add or edit the group claim `http://schemas.microsoft.com/ws/2008/06/identity/claims/groups`. Under **Which groups associated with the user should be returned in the claim?**, select **Groups assigned to the application**.
{% /step %}
{% step title="Name the claim `teams`" %}
Check **Customize the name of the group claim** and set the name to:

```
teams
```

FOSSA reads the `teams` claim and assigns each user to the matching teams in your organization.
{% /step %}
{% /steps %}

---

Source: https://docs.fossa.com/docs/organization-management/single-sign-on/okta

# Okta

Okta acts as a SAML 2.0 identity provider for FOSSA. To connect them, you create a SAML app in Okta, point it at FOSSA's callback and audience values, then copy Okta's sign-on URL and signing certificate back into FOSSA.

{% callout type="info" %}
SAML single sign-on must be enabled for your organization before the settings below appear. SSO is a [premium feature](/docs/organization-management/single-sign-on), contact your FOSSA account team to enable it.
{% /callout %}

Before you start, open FOSSA's authentication settings in another tab: go to **Settings → Organization → Authentication**. The **Callback URL** and **Audience URI / SP Entity ID** values there are needed while configuring Okta, and you'll paste Okta's certificate and sign-on URL back into this page at the end.

## Configuring the Okta application

{% steps %}
{% step title="Create a SAML app in Okta" %}
In your Okta admin panel, go to **Applications → Add Application → Create New App**. Choose **Web** as the platform and **SAML 2.0** as the sign-on method.
{% /step %}
{% step title="Name the app" %}
Name the app "FOSSA" and, optionally, upload a logo. Continue to the SAML settings.
{% /step %}
{% step title="Enter FOSSA's SAML values" %}
From FOSSA's **Settings → Organization → Authentication** page, copy the values into Okta's SAML settings:

| In Okta | Paste from FOSSA |
| --- | --- |
| Single sign on URL | **Callback URL** |
| Audience URI | **Audience URI / SP Entity ID** |

Then set **Name ID format** to **EmailAddress** and **Application username** to **Email**.

{% callout type="warning" %}
FOSSA identifies each user by the email address in the SAML **Name ID**. If the Name ID format isn't the user's email, logins fail to match an account.
{% /callout %}
{% /step %}
{% step title="Copy Okta's sign-on URL and certificate into FOSSA" %}
Click next and finish creating the app. On the application settings page Okta redirects you to, click **View Setup Instructions**. This opens a page with two values you need:

1. In **Identity Provider Single Sign On URL**, enter Okta's **Identity Provider Single Sign-On URL**.
2. In **Certificate**, paste Okta's **X.509 Certificate**.
{% /step %}
{% step title="Save in FOSSA" %}
Click **Save Changes** on FOSSA's Authentication page.
{% /step %}
{% /steps %}

## Result

Okta is now configured to authenticate users to FOSSA. For their first login, users click the **FOSSA** icon on their Okta dashboard, which redirects them to FOSSA and creates their account. After that, they can sign in directly from Okta, or by entering their email address on the FOSSA login page.

{% callout type="info" %}
FOSSA can also set each user's organization role and synchronize their team membership from SAML attributes. See the [SAML attributes guide](/docs/organization-management/single-sign-on/saml-attributes) for the supported `role` and `teams` claims.
{% /callout %}

---

Source: https://docs.fossa.com/docs/organization-management/single-sign-on/saml-attributes

# SAML Attributes

When a user signs in through a SAML identity provider, FOSSA can read attributes from the SAML assertion to set the user's organization role and synchronize their team membership. You define these attributes in your identity provider's claim mapping, alongside the rest of its SAML configuration.

{% callout type="info" %}
These attributes apply to SAML single sign-on, which must be enabled for your organization; SSO is a [premium feature](/docs/organization-management/single-sign-on). You set the attributes in your identity provider; see your provider's setup guide, such as [Active Directory Federation Service](/docs/organization-management/single-sign-on/active-directory-federation-service) or [Auth0](/docs/organization-management/single-sign-on/auth0).
{% /callout %}

## How attribute provisioning works

Each time a user signs in through SAML, FOSSA reads the attribute statement in the assertion and applies two optional attributes:

- `role` sets the user's organization role.
- `teams` synchronizes the teams the user belongs to.

FOSSA takes the user's email from the SAML **Name ID** and builds their display name from the `firstName` and `lastName` claims, your provider's setup guide covers mapping those.

## Supported attributes

| Attribute | Sets | Accepted values | Multiple values? | Case sensitivity |
| --- | --- | --- | --- | --- |
| `role` | The user's organization role | `admin`, `editor`, or `viewer` (the three built-in roles), or the name of a custom organization role | No | Not case-sensitive |
| `teams` | The user's team membership, synchronized on every login | A team name, or `Team Name::Role Name` to also set the user's role on that team | Yes, repeat the attribute to add the user to multiple teams | Team names are case-sensitive; role names are not |

## Setting the organization role

The `role` attribute maps to one of the three built-in organization roles (`admin`, `editor`, or `viewer`) or to any custom organization role, matched by name. The value is not case-sensitive, so `Admin` and `admin` are equivalent.

{% callout type="warning" %}
If the value doesn't match a built-in or custom organization role, FOSSA doesn't apply it. New users fall back to your organization's default role.
{% /callout %}

## Synchronizing team membership

On each login, FOSSA synchronizes the user's team membership to match the `teams` attribute exactly:

- **Adds** the user to every team listed.
- **Creates** a listed team that doesn't exist, only if your organization allows SAML to create missing teams. Otherwise the user is added only to teams that already exist.
- **Removes** the user from any team they currently belong to that isn't listed.

Set the user's role on a team with the format `Team Name::Role Name` (for example, `Platform::Team Admin`). If the role name can't be matched, FOSSA assigns that team's default role. Repeat the `teams` attribute to add the user to multiple teams. Team names are case-sensitive; role names are not.

{% callout type="warning" %}
Because each login replaces the user's membership with exactly the teams in the assertion, the user is removed from any team that isn't listed. Include every team the user should remain in.
{% /callout %}

## Example

{% callout type="info" %}
Your SAML provider can use conditional logic to give different access levels to different teams, using the format `Team Name::Role Name`.
{% /callout %}

```xml
<saml:AttributeStatement xmlns:xs="http://www.w3.org/2001/XMLSchema"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">

    <saml:Attribute Name="role" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic">
        <saml:AttributeValue xsi:type="xs:string">
            Admin
        </saml:AttributeValue>
    </saml:Attribute>
    <saml:Attribute Name="teams" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic">
        <saml:AttributeValue xsi:type="xs:string">
            Team A::Team Admin
        </saml:AttributeValue>
        <saml:AttributeValue xsi:type="xs:string">
            Team B
        </saml:AttributeValue>
    </saml:Attribute>
</saml:AttributeStatement>
```

This assertion gives the user the **admin** organization role, makes them a **Team Admin** on **Team A**, and adds them to **Team B** with its default role.

## Related

- [Active Directory Federation Service](/docs/organization-management/single-sign-on/active-directory-federation-service)
- [Auth0](/docs/organization-management/single-sign-on/auth0)
- [Single Sign-On overview](/docs/organization-management/single-sign-on)

---

Source: https://docs.fossa.com/docs/organization-management/api-tokens

# API Tokens

Every call to the FOSSA API authenticates with a token. Tokens come in a few forms depending on *who or what* is making the request: a person exploring the API, an automated pipeline, or a CI job using federated identity. This page explains each form and how to create it.

{% callout type="info" %}
All three are managed under **Account Settings → Integrations**. Despite the "Account Settings" label, creating service accounts and OIDC providers requires organization-level permissions.
{% /callout %}

## Token access levels

Whichever form you use, a FOSSA API token has one of two access levels, chosen when the token is created:

| Access level | What it can do |
| --- | --- |
| **Push-Only** | Send data *to* FOSSA, used by the CLI and CI integrations to push analysis results. It can't be used for most read APIs. This is the **default** when creating a token. |
| **Full** | The same access as the account the token belongs to. Required for most API endpoints and management tasks. |

{% callout type="warning" %}
A token's access level is fixed once created; you can't switch a Push-Only token to Full later. To change it, delete the token and create a new one. Deleting a token is also how you **revoke** it.
{% /callout %}

## Personal API tokens

A personal token is the classic, simplest form: a token you generate for yourself. Apps using it **impersonate your identity** and inherit your permissions.

Create one under **Account Settings → Integrations → API**:

{% steps %}
{% step title="Open API Tokens" %}
Go to **Account Settings → Integrations → API**.

{% img src="/images/organization-management/api-tokens-page.png" alt="API Tokens page under Integrations with the Add New Token button and the token list" /%}
{% /step %}
{% step title="Create a token" %}
Click to create a new token, give it a **Name**, and choose its access level with the **Push Only** checkbox: leave it checked for a Push-Only token, or uncheck it for Full access.
{% /step %}
{% step title="Copy the token" %}
Copy the token immediately and store it somewhere secure. It impersonates your account, and it can't be viewed or changed after creation.
{% /step %}
{% /steps %}

{% callout type="info" %}
Because a personal token carries your identity, it stops working if your account is deactivated, and its access changes when your permissions do. For shared automation (CI pipelines, scripts owned by a team), prefer a **service account** instead, so the credential doesn't depend on one person.
{% /callout %}

## Service accounts

A **service account** is a special non-human user built for automation. It interacts with the FOSSA API using either an API token or OIDC, is **not subject to your organization's SSO configuration**, and **cannot log in with a username and password**. Service accounts appear in your organization's user list with a **Service Account** badge.

Use a service account when a credential should belong to a *system* rather than a *person*: CI/CD, integrations, or any long-lived automation.

Create one under **Account Settings → Integrations → API Service Accounts**:

{% steps %}
{% step title="Open API Service Accounts" %}
Go to **Account Settings → Integrations → API Service Accounts** and select **Create a Service Account**.

{% img src="/images/organization-management/api-service-account-create.png" alt="Create a Service Account form with username, name, email, organization and team roles, and the push-only and full API token options" /%}
{% /step %}
{% step title="Configure the account" %}
Provide a **Username** (required), and optionally a **Name** and **Email**. Assign access by giving it an **Organization Role**, or a **Team** plus **Team Role**; at least one is required. These roles govern what the account's tokens can do.
{% /step %}
{% step title="Generate its tokens" %}
Choose **Create a push-only API token** and/or **Create a full API token**. The generated tokens are shown **once**; copy them immediately, as they're never displayed again.
{% /step %}
{% /steps %}

{% callout type="info" %}
Creating and managing service accounts requires permission to manage service accounts (organization-wide, or scoped to a team). See [Roles & Permissions](/docs/organization-management/role-based-access-control).
{% /callout %}

## OpenID Connect (OIDC)

OIDC lets CI/CD pipelines authenticate **without storing a long-lived token at all**. Your CI platform issues a short-lived JWT for the running job; the pipeline exchanges it for a FOSSA token that **runs as a service account** and expires automatically after the build (15 minutes to 12 hours; default 1 hour).

This is the most secure option for CI because there's no static secret to leak or rotate. It builds on service accounts (the issued token is bound to one) and is configured under **Account Settings → Integrations → OIDC Providers**.

For the full setup (providers, trust relationships, and GitHub Actions / GitLab CI examples), see **[OpenID Connect](/docs/integrations/openid-connect)**.

## Choosing the right form

| If you're… | Use |
| --- | --- |
| Exploring the API or scripting something just for yourself | A **personal token** (Full for read APIs, Push-Only to push results) |
| Setting up shared automation, an integration, or CI that stores a credential | A **service account** with a Push-Only or Full token |
| Running CI on a platform with an OIDC identity provider | **OIDC**: no stored secret, short-lived tokens |

## Keeping tokens secure

{% callout type="warning" %}
API tokens carry the same privileges as the account that created them. Never commit a token to source control, embed it in client-side code, or share it in a publicly accessible location.
{% /callout %}

- Prefer **Push-Only** tokens for CI/CD; they can push results but can't read or modify your data.
- Prefer **service accounts** or **OIDC** over personal tokens for anything shared, so a credential never depends on one person's account.
- Rotate long-lived tokens periodically and revoke any that may be exposed. See [Rotating access tokens](/docs/api/examples/rotating-access-tokens).

For how to send a token in a request, see [API Authentication](/docs/api/authentication).

## What's next

- **[Fail CI/CD Checks](/docs/integrations/fail-cicd-checks)**: Use your API token to integrate `fossa test` into your CI/CD pipeline.
- **[Role-Based Access Control](/docs/organization-management/role-based-access-control)**: Understand which permissions apply to service accounts using API tokens.

---

Source: https://docs.fossa.com/docs/on-premises

# On-Premises Deployment

Run FOSSA inside your own environment when data residency, network isolation, or compliance requirements call for it.

## What this covers

- **Installation**: deploy FOSSA on Kubernetes with the official Helm chart.
- **Maintenance**: upgrades, backups, and day-2 operations.
- **Configuration**: networking, storage, and integration with your infrastructure.

Day-to-day user and access management is the same as the hosted product. See [Organization Management](/docs/organization-management).

---

Source: https://docs.fossa.com/docs/on-premises/architecture-overview

# Architecture Overview

When FOSSA is installed behind your firewall, the entire analysis pipeline runs inside your organization's network. This page explains how FOSSA's services connect to one another and to the outside world, so you can evaluate the deployment against your security and data-residency requirements.

```mermaid
---
config:
  themeVariables:
    fontSize: 14px
  flowchart:
    nodeSpacing: 20
    rankSpacing: 40
    padding: 6
    diagramPadding: 8
---
graph LR
    web(("The Web"))
    vulnFeed(("FOSSA Vulnerability Feed"))
    firewall["Firewall"]
    users["Users / Employees"]

    subgraph intranet["Enterprise Intranet"]
        subgraph fossa["FOSSA Services"]
            analysis["Analysis Cluster"]
            db[("Database / Build Queue")]
            webserver["Web Server Cluster"]
        end
        subgraph it["Internal IT Tools"]
            artifacts["Code &amp; Artifact Hosts"]
            cicd["Build &amp; Test Cluster (CI/CD)"]
            workflow["Workflow Tools, Issue Trackers &amp; Notifications"]
            devs["Developer Machines"]
        end
    end

    web --> firewall
    firewall -- Download OSS Code --> artifacts
    firewall -. Optional .-> analysis
    artifacts -- "Analyze OSS &amp; Private Code" --> analysis

    analysis -- "Vulnerability Updates (when security enabled)" --> firewall
    firewall --> vulnFeed

    analysis <--> db
    db <--> webserver

    webserver -- Publish Results --> workflow
    webserver -- Publish Results --> cicd

    webserver <--> users
    devs <--> webserver

    classDef service fill:#edf7f2,stroke:#1d7a54,color:#171717,stroke-width:2px
    classDef external fill:#eff6ff,stroke:#1558c0,color:#171717,stroke-width:2px
    classDef db fill:#edf7f2,stroke:#1d7a54,color:#171717,stroke-width:2px
    classDef tool fill:#ffffff,stroke:#737373,color:#525252,stroke-width:2px

    class analysis,webserver service
    class db db
    class web,firewall,users,vulnFeed external
    class artifacts,cicd,workflow,devs tool

    style intranet fill:#edf7f2,stroke:#289E6D,color:#171717,stroke-width:2px
    style fossa fill:#f0f0f0,stroke:#a3a3a3,color:#171717,stroke-width:2px
    style it fill:#f5f5f5,stroke:#737373,color:#666666,stroke-width:2px,stroke-dasharray:5 5
```

## A sealed environment

When FOSSA runs on-premises, your code and its analysis never leave your network:

- **Your proprietary code never leaves your premises.** FOSSA clones, builds, and analyzes your code entirely within your intranet.
- **Your scan results stay in your environment.** Analysis data, signatures, and project findings are stored in your own database, not sent to FOSSA.
- **No added InfoSec footprint.** FOSSA downloads and analyzes third-party open-source code anonymously from the public web, the same way a developer machine or CI runner already does.

{% callout type="info" %}
The guarantee applies to your **proprietary code and scan results**; those stay inside your network. Your FOSSA instance still makes outbound connections to download open-source packages and to receive vulnerability intelligence. Those paths are described under [How data flows](#how-data-flows) below.
{% /callout %}

## How data flows

Inside your network, three groups of FOSSA services work together:

- **Analysis Cluster**: clones and analyzes your code and its open-source dependencies.
- **Database / Build Queue**: stores analysis results and coordinates scan jobs.
- **Web Server Cluster**: serves the dashboard, reports, and API to your users.

FOSSA makes two kinds of **outbound** connection. Both *receive* data into your instance rather than sending your data out:

| Outbound connection | Purpose | When it's used |
| --- | --- | --- |
| Public package registries & code hosts | Download third-party open-source code to analyze | Optional, only when analyzing dependencies fetched from the public internet |
| FOSSA vulnerability feed (`vulns.fossa.com`) | Keep your vulnerability database current with the latest CVE/CPE intelligence | **Required when FOSSA's security (vulnerability) scanning is enabled** |

{% callout type="warning" %}
If you enable FOSSA's security features, your instance must be able to reach FOSSA's vulnerability feed to receive over-the-air vulnerability data updates. Confirm the required egress (and whether an air-gapped or offline data-import option fits your environment) with your FOSSA account team.
{% /callout %}

For the specific hosts and IP ranges to allow through your firewall, see [IP Space Allowlisting](/docs/on-premises/ip-space-allowlisting).

## Inside the FOSSA cluster

The three groups above are a simplification. Internally, FOSSA is a set of cooperating services running in your Kubernetes cluster, backed by several PostgreSQL databases and a Redis cache. This is the **same architecture that powers FOSSA's hosted cloud**; an on-premises installation runs the identical services, just inside your own infrastructure rather than FOSSA's.

```mermaid
---
config:
  themeVariables:
    fontSize: 14px
  flowchart:
    nodeSpacing: 24
    rankSpacing: 48
    padding: 6
    diagramPadding: 8
---
graph LR
    userBrowser[User Browser]
    cli[CLI]
    fossaFeed["FOSSA Vulnerability Feed (vulns.fossa.com)"]
    issueTrackers["Issue Trackers (Jira, etc.)"]
    subgraph sources["External Sources"]
        codeHosts["Code Hosts (GitHub, GitLab, etc.)"]
        pkgApi["Package Registries (npm, PyPI, NuGet, etc.)"]
    end

    subgraph env["Your Environment"]
        subgraph k8s["Kubernetes Cluster"]
            subgraph coreApp["Core Web Application"]
                core[Core]
                fetchers[Fetchers Service]
                vulns[Vulns Service]
            end
            hubble[Hubble API]
            sparkle[Sparkle API]
            ramjet[Ramjet]
            sherlock[Sherlock]
            faktory["Faktory (Async Jobs)"]
            updater["Vulns OTA Updater (CronJob)"]
        end
        subgraph data["Data Stores"]
            redis[("Redis Cache")]
            custData[("Customer &amp; Dependency Data (PostgreSQL)")]
            analysisData[("Analysis Data (PostgreSQL)")]
            threatData[("Threat Data (PostgreSQL)")]
            compData[("Components Data (PostgreSQL)")]
            hashData[("Component File Hash Data (PostgreSQL)")]
        end
    end

    userBrowser --> core
    cli --> core
    cli --> vulns
    codeHosts --> fetchers
    pkgApi --> fetchers
    core --> fetchers
    core --> vulns
    core --> faktory
    core --> hubble
    core --> sparkle
    core --> issueTrackers
    fetchers --> faktory
    vulns --> faktory
    hubble --> sparkle
    hubble --> ramjet
    sparkle --> ramjet
    sparkle --> sherlock
    fossaFeed --> updater
    core --> redis
    core --> custData
    core --> analysisData
    core --> compData
    fetchers --> redis
    fetchers --> custData
    fetchers --> compData
    vulns --> redis
    vulns --> threatData
    vulns --> analysisData
    updater --> threatData
    hubble --> custData
    hubble --> analysisData
    hubble --> compData
    sparkle --> compData
    sparkle --> hashData
    ramjet --> hashData
    sherlock --> hashData

    classDef service fill:#edf7f2,stroke:#1d7a54,color:#171717,stroke-width:2px
    classDef external fill:#eff6ff,stroke:#1558c0,color:#171717,stroke-width:2px
    classDef db fill:#edf7f2,stroke:#1d7a54,color:#171717,stroke-width:2px

    class userBrowser,cli,core,fetchers,vulns,faktory,hubble,sparkle,ramjet,sherlock,updater service
    class fossaFeed,codeHosts,issueTrackers,pkgApi external
    class redis,custData,threatData,analysisData,compData,hashData db

    style env fill:#edf7f2,stroke:#289E6D,color:#171717,stroke-width:2px
    style k8s fill:#ffffff,stroke:#d4d4d4,color:#171717,stroke-width:2px
    style coreApp fill:#f0f0f0,stroke:#a3a3a3,color:#171717,stroke-width:2px
    style sources fill:#f5f5f5,stroke:#737373,color:#666666,stroke-width:2px,stroke-dasharray:5 5
    style data fill:#f0f0f0,stroke:#a3a3a3,color:#171717,stroke-width:2px
```

Mapping these services back to the three groups above:

- **Web Server Cluster**: **Core** serves the dashboard, reports, and API to your users and the CLI, and orchestrates the other services; **Hubble** and **Sparkle** back the component and reporting experiences.
- **Analysis Cluster**: **Fetchers** clones and downloads your source code and its open-source dependencies from code hosts and public package registries; **Ramjet** and **Sherlock** handle component identification and file-hash analysis; the **Vulns** service serves vulnerability data for security scans.
- **Database / Build Queue**: the PostgreSQL databases store customer, analysis, component, and threat data, **Redis** provides caching, and **Faktory** runs the asynchronous job queue.

### How vulnerability data differs from the cloud

This is the one place where the on-premises topology departs from FOSSA's hosted cloud. In the cloud, the Vulns service aggregates raw vulnerability intelligence directly from upstream sources such as the NVD and security bulletins. On-premises, your instance does **not** reach out to those upstream feeds. Instead, FOSSA curates that intelligence centrally and publishes it to its vulnerability feed, and a **Vulns OTA Updater** CronJob in your cluster pulls the prepared snapshots into your local threat database. See [On-Prem Vulnerability Database Updates](/docs/on-premises/maintenance/vulnerability-database-updates) for how to enable and monitor it.

## Results flow into your internal tools

FOSSA publishes scan results back into the tools your developers already use, surfacing issues in CI/CD pipelines, issue trackers, notifications, and the FOSSA dashboard. Configuring these connections is covered in [Integrations](/docs/integrations).

## What this means for you

- If you have strict data-residency requirements, your source code and analysis results remain within your network boundary.
- Plan your outbound egress around two needs: access to public package registries (when analyzing public open-source code) and access to FOSSA's vulnerability feed (when using security scanning).
- For day-to-day user and access management, see [Organization Management](/docs/organization-management). It works the same as the hosted product.

---

Source: https://docs.fossa.com/docs/on-premises/ip-space-allowlisting

# IP Space Allowlisting

If your FOSSA on-premises instance runs behind a firewall, you may need to allowlist FOSSA's public IP addresses so it can reach the FOSSA cloud services it depends on. This page lists the public IP ranges for each service.

{% callout type="warning" %}
FOSSA's cloud IP addresses are operational infrastructure and may change over time. Confirm the current values with your FOSSA account team before relying on them for long-lived firewall rules, and prefer allowlisting by hostname where your network allows it.
{% /callout %}

## `vulns.fossa.com` and `app.fossa.com`

```
52.223.16.182
35.71.190.183
44.238.207.42
44.238.247.59
44.226.239.166
```

## AWS S3

The S3 IP space FOSSA uses is based in **us-west-2**. As of this writing, the range is `52.94.76.0/22`.

To confirm this is still valid, open [the AWS IP ranges feed](https://ip-ranges.amazonaws.com/ip-ranges.json) and find the entry in the `prefixes` array whose `region` is `us-west-2`.

---

Source: https://docs.fossa.com/docs/on-premises/installation

# Installing FOSSA On-Premises

This guide walks through installing FOSSA Enterprise into an existing Kubernetes cluster using the official Helm chart. By the end, you'll have a running, verified FOSSA instance that your users can sign in to and import their first project.

The installation has four stages, and they build on each other in order:

1. **Set up Helm** and add the FOSSA chart repository.
2. **Configure your Helm values** for your environment.
3. **Prepare your external services** (database and object storage).
4. **Install and verify** the release.

## Prerequisites

Before you start, confirm your cluster, database, object storage, and network meet the [installation requirements](/docs/on-premises/installation/installation-requirements). You'll also need the **FOSSA image credentials** from your account manager.

## Set up Helm

FOSSA is distributed as an on-premises application using [Helm](https://helm.sh/), a tool for distributing applications that run on Kubernetes.

{% steps %}
{% step title="Install helm" %}
Follow [Installing Helm](https://helm.sh/docs/intro/install/), choosing a version compatible with your cluster (see Helm's [Version Support Policy](https://helm.sh/docs/topics/version_skew/#supported-version-skew)).

Verify the install by running `helm list`. You should see a list of releases in your cluster's default namespace. It may be empty if you haven't installed any charts yet.

{% callout type="warning" %}
If `helm` can't connect to your cluster, first confirm `kubectl cluster-info` works. If that fails too, contact your Kubernetes cluster administrator; **FOSSA does not install or manage Kubernetes clusters.**
{% /callout %}
{% /step %}

{% step title="Add the FOSSA chart repository" %}
FOSSA's official charts are hosted at `https://charts.fossa.com`. Add the repository and pull the latest chart metadata:

```bash
# Add the FOSSA Helm chart repository.
$ helm repo add fossa https://charts.fossa.com
"fossa" has been added to your repositories

# Load the latest information from all chart repositories.
$ helm repo update
```
{% /step %}

{% step title="Test your image credentials" %}
Confirm the FOSSA image credentials from your account manager work by logging in and pulling an image:

```bash
# Follow the prompts for username and password
$ docker login quay.io

$ docker pull quay.io/fossa/fossa
```

If the pull succeeds, your credentials are working.
{% /step %}
{% /steps %}

### Inspecting the chart (optional)

As a best practice, inspect a chart before installing it. FOSSA's `fossa-core` chart bundles a `docs` folder with this installation guide, a `CHANGELOG.md` (with breaking changes highlighted), and a commented `values.yaml` documenting every possible value.

```bash
# Download and unpack the chart into a temporary folder
$ helm pull --untardir /tmp/fossa-helm --untar fossa/fossa-core
```

The `fossa-core` chart pulls in several sub-charts:

| Sub-chart | Purpose | Required |
| --- | --- | --- |
| `faktory` | Task scheduler | Yes |
| `redis` (aliased `cache`) | Cache and queue backing store | Yes |
| `hubble` | Source-code analysis (Quick Import, Archive Upload) | Yes |

{% callout type="info" %}
Sparkle, FOSSA's analysis-ingestion service, is bundled directly into `fossa-core` and is mandatory; it isn't a separately pullable sub-chart. Earlier charts also bundled `fetchers-api` (since removed, with no remaining callers) and `minio` / `postgres` sub-charts for self-hosting; recent charts configure object storage and Postgres as external services instead. For the current, authoritative list, inspect `fossa-core/Chart.yaml`.
{% /callout %}

Don't use the chart's `values.yaml` directly. Instead, start from one of the provided initial value files, described next.

## Configure your Helm values

With Helm set up, create a values file that describes your installation. Start from one of the three [starter values files](/docs/on-premises/installation/helm-values-reference):

- **`simplified.values.yaml`** *(recommended)*: for managed external hosting. Uses YAML anchors for simpler configuration.
- **`simplified.self-hosted.values.yaml`**: for self-hosting FOSSA's dependencies in-cluster.
- **`advanced.values.yaml`**: exposes the full chart configuration directly, without anchors.

All three configure the same underlying schema. As you edit, you can preview the fully rendered output (with anchors resolved) using:

```bash
# helm template RELEASE_NAME CHART_NAME [FLAGS]
$ helm template fossa fossa/fossa-core --values YOUR_VALUES_FILE.yaml
```

### Basic configuration

Start with the basics:

- **Image credentials**: set `global.imageCredentials.username` and `global.imageCredentials.password` to the values from your account manager.
- **Encryption secret**: set `encryptionSecret` to a random 64-character hexadecimal string. It encrypts application-level secrets such as VCS API keys. You generally shouldn't change it later; if you do, you may need to reconfigure all application-level credentials.
- **Hostname and port**: set `hostname` (a string) and `port` (an integer). The hostname must be reachable by your end users; you'll add a DNS entry for it later.

### Configuring external services

Next, point FOSSA at its database, object storage, and email server. The field names below are for the simplified charts; for the advanced chart, reference the comments on each field.

#### Database connection

For a database using **managed external hosting**, set:

- `postgres.host`
- `postgres.username`
- `postgres.password`
- `postgres.database` (the `dbname` FOSSA should use in your Postgres server)

For a **self-hosted** database, FOSSA creates an in-cluster Postgres instance for you; set only the user to create:

- `postgresAuth.username`
- `postgresAuth.password`

{% callout type="warning" %}
`fossa-core` 6.x removed in-cluster Postgres provisioning, the chart no longer includes a Postgres installation, and managed external Postgres (version 17) is required on current charts. A `global.allowProvisionedDatabaseTemporarily` flag exists as a transition escape hatch. If you self-host Postgres today, follow [Migrating to Postgres 17](/docs/on-premises/maintenance/migrating-to-postgres-17).
{% /callout %}

#### S3-compatible object storage

For object storage using **managed external hosting**, set:

- `storageCoreBucket`
- `storageHubbleBucket`
- `storageEndpoint`
- `storageRegion`
- `storageAuth.accessKey`
- `storageAuth.secretKey`

For **self-hosted** object storage, FOSSA creates MinIO instances for you. The web application's object storage must be reachable by your end users (FOSSA uses CORS to upload and download files directly), so set `storageHostname` to a user-accessible hostname and add a DNS entry for it later. With managed external hosting you don't need `storageHostname`; the S3 endpoint is used instead.

{% callout type="warning" %}
Recent charts no longer provision MinIO. Configure S3-compatible backends (including a MinIO you run yourself) the same way as regular S3: provide credentials, set the endpoint and region, and optionally enable `forcePathStyle`. See [Decoupling MinIO from fossa-core](/docs/on-premises/maintenance/decoupling-minio).
{% /callout %}

#### Email server

All FOSSA installations use an external email server. Configure:

- `email.from`
- `email.host`
- `email.port`
- `email.auth.user`
- `email.auth.pass`

Make sure FOSSA can reach the SMTP server you configure.

### Terminating SSL

If you host FOSSA behind HTTPS, you can [configure its Kubernetes Ingress to terminate SSL](https://kubernetes.io/docs/concepts/services-networking/ingress/#tls):

- If your ingress controller automates HTTPS certificates via annotations, use `ingressAnnotations` to set them on the web application's `Ingress`.
- To manage TLS certificates manually, use `ingressTLS` to set the `tls` field of the web application's `Ingress`. You'll need to construct the corresponding `Secret` containing the certificate yourself.

### Trusting self-signed certificates

If your network uses self-signed certificates, configure FOSSA to trust them with the `trustedCertificates` field. Its value is a map where each key is the certificate's hash with `.0` appended, and the value is the certificate's contents. Generate the hash with `openssl x509 -noout -hash -in certificate.pem`:

```yaml
trustedCertificates:
  5a7a72df.0: |-
    -----BEGIN CERTIFICATE-----
    MIIFATCCAumgAwIBAgIRAKc9ZKBASymy5TLOEp57N98wDQYJKoZIhvcNAQELBQAw
    ...
    8iyIYUyQAbsvx8oD2M8kRvrIRSrRJSl6L957b4AFiLIQ/GgV2curs0jje7Edx34c
    idWw1VrejtwclobqNMVtG3EiPUIpJGpbMcJgbiLSmKkrvQtGng==
    -----END CERTIFICATE-----
```

## Prepare your external services

If you're using managed external hosting, some setup happens on the service host itself, outside FOSSA and Kubernetes. Skip the section for any service you're self-hosting.

### Database

{% steps %}
{% step title="Create the database" %}
A Postgres server can host multiple databases. FOSSA connects to the one named in your chart configuration, make sure it exists. For example, if your `dbname` is `fossa`:

```sql
CREATE DATABASE fossa;
```
{% /step %}

{% step title="Grant schema permissions" %}
FOSSA creates two schemas within the database, `fossa` and `hubble`. Ensure the database user you configured has permission to create schemas.
{% /step %}
{% /steps %}

### Object storage

{% steps %}
{% step title="Create your buckets" %}
You may need to create the S3 buckets manually before they can be used. Use the same bucket names you configured in your chart.
{% /step %}

{% step title="Grant IAM permissions" %}
For each bucket, FOSSA needs `GetObject`, `ListBucket`, and `PutObject`. Configure these on the access/secret key or the IAM role attached to FOSSA's pods. Substitute your bucket names for `<CORE_BUCKET_NAME>` and `<HUBBLE_BUCKET_NAME>`:

```json
{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "FOSSA",
            "Effect": "Allow",
            "Action": [
                "s3:PutObject",
                "s3:GetObject",
                "s3:ListBucket"
            ],
            "Resource": [
                "arn:aws:s3:::<CORE_BUCKET_NAME>/*",
                "arn:aws:s3:::<CORE_BUCKET_NAME>",
                "arn:aws:s3:::<HUBBLE_BUCKET_NAME>/*",
                "arn:aws:s3:::<HUBBLE_BUCKET_NAME>"
            ]
        }
    ]
}
```
{% /step %}

{% step title="Configure CORS" %}
The web application's bucket must allow CORS, since FOSSA serves bucket contents over CORS requests. Substitute your hostname for `<FOSSA_HOSTNAME>`:

```json
[
    {
        "AllowedHeaders": [
            "*"
        ],
        "AllowedMethods": [
            "PUT"
        ],
        "AllowedOrigins": [
            "<FOSSA_HOSTNAME>"
        ],
        "ExposeHeaders": [
            "Content-Type",
            "X-Content-Type-Options"
        ],
        "MaxAgeSeconds": 3000
    }
]
```
{% /step %}
{% /steps %}

## Install and verify FOSSA

With your cluster configured, external services ready, and values prepared, you're ready to install.

{% steps %}
{% step title="Choose a release name" %}
Installing a chart creates a [Helm release](https://helm.sh/docs/glossary/#release), identified by a name that's unique within the cluster. This lets you run multiple FOSSA instances side by side (for example, staging alongside production). Name a release by how it'll be used, e.g. `fossa-production` or `fossa-staging`.
{% /step %}

{% step title="Install the release" %}
```bash
# helm install RELEASE_NAME CHART_NAME [FLAGS]
$ helm install fossa-production fossa/fossa-core --values YOUR_VALUES_FILE.yaml --timeout 60m
```
{% /step %}

{% step title="Configure DNS" %}
While the install runs, set up DNS for your chosen hostnames:

- A DNS entry for the FOSSA web application.
- If you self-host object storage, a DNS entry for it as well.

Point each entry at your configured Kubernetes ingress. The exact setup depends on your ingress controller. Consult its documentation for serving external DNS.
{% /step %}

{% step title="Verify your installation" %}
Once DNS is configured and `helm install` has completed, navigate to your new FOSSA instance. You'll be prompted to create a user and an organization, after which you can import your first project for analysis using the FOSSA CLI.
{% /step %}
{% /steps %}

Congratulations, you've completed a base installation of FOSSA. 🎉

## What's next

- [Customizing your deployment](/docs/on-premises/installation/post-install-configuration): integrations, SSO, SAML/LDAP, and notification banners.
- [Updating Helm values](/docs/on-premises/maintenance/updating-helm-values): apply configuration changes after install.
- [Architecture Overview](/docs/on-premises/architecture-overview): how FOSSA's services connect inside your network.

---

Source: https://docs.fossa.com/docs/on-premises/installation/installation-requirements

# Installation Requirements

Before installing FOSSA Enterprise into your Kubernetes cluster, make sure your infrastructure meets the requirements below. The FOSSA application runs inside your cluster and depends on two external services: an S3-compatible object storage backend and a Postgres-compatible SQL database.

## Choosing your hosting model

For both object storage and the database, you can either **self-host** the dependency in-cluster or use **managed external hosting** (Amazon S3 and Amazon RDS, or equivalents). FOSSA ships with self-hosted options (MinIO for object storage and in-cluster Postgres) but they require extra CPU, memory, and disk in your cluster.

{% callout type="warning" %}
We strongly recommend managed external hosting for **both** the object storage backend (Amazon S3 or equivalent) and the database (Amazon RDS or equivalent). The self-hosted options are suitable only for proof-of-concept deployments, not for production.

Recent `fossa-core` chart versions (6.x) have removed in-cluster Postgres provisioning and decoupled MinIO from the chart. If you self-host today, plan your migration with [Migrating to Postgres 17](/docs/on-premises/maintenance/migrating-to-postgres-17) and [Decoupling MinIO from fossa-core](/docs/on-premises/maintenance/decoupling-minio).
{% /callout %}

## FOSSA image credentials

To download the FOSSA application images, you'll need a username and password. Contact your FOSSA account manager to get these credentials.

## Kubernetes cluster

| Requirement | Minimum |
| --- | --- |
| Kubernetes | 1.29 or newer (we recommend 1.35 as of May 30, 2026) |
| `kubectl` | Compatible with your cluster |
| `helm` | 3.11.0 or newer |
| CPU | 32 vCPU |
| Memory | 64 GB |
| Storage | 500 GB available |

To use the simplified charts, your cluster also needs **dynamic volume provisioning** and an **ingress controller**.

## Database

| Requirement | Value |
| --- | --- |
| Postgres | 17 or newer |
| CPU | 4 vCPU |
| Memory | 8 GB |
| Storage | 200 GB available |

If you self-host Postgres, FOSSA's database image sets up the correct Postgres version for you. Add these resources to your cluster's requirements instead.

## S3-compatible object storage

If you're using managed external hosting, your storage host should provide:

| Requirement | Value |
| --- | --- |
| CPU | 2 vCPU |
| Memory | 4 GB |
| Storage | 500 GB available |

If you self-host object storage, add these resources to your cluster's requirements.

## Email

FOSSA sends user invites, notifications, and other transactional emails over SMTP. You'll need to provide an SMTP server for FOSSA to send mail through.

## Networking

FOSSA needs access to the following ports:

| Direction | Port(s) | Purpose |
| --- | --- | --- |
| Inbound | 443 (HTTPS) | Users access FOSSA |
| Outbound | 22 (SSH), 80 (HTTP), 443 (HTTPS), all required | Access public package registries, download code for analysis, integrate with other tools |
| Outbound | 25 / 465 / 587 (SMTP, pick one) | Send email over SMTP |
| Outbound | 5432 (Postgres) | Connect to Postgres when using managed external hosting |

## DNS and SSL

Once FOSSA is installed, configure DNS so users can reach it:

- Add a DNS entry for the FOSSA web application.
- If you self-host object storage, add a DNS entry for the self-hosted MinIO instance too.

If you terminate SSL at the FOSSA application, you'll also need SSL certificates for each domain name, one for the web application, and one for object storage if you self-host it.

## Self-signed certificates

If your network uses self-signed certificates, FOSSA can be configured to trust them. Have these certificates ready to reference during configuration. See [Trusting self-signed certificates](/docs/on-premises/installation#trusting-self-signed-certificates) in the install guide.

## Next step

Once your infrastructure is ready, start the [installation guide](/docs/on-premises/installation).

---

Source: https://docs.fossa.com/docs/on-premises/installation/helm-values-reference

# Helm Values Reference

FOSSA provides three starter values files to begin configuring your `fossa-core` Helm release. All three configure the same underlying schema, the simplified files only add YAML anchors and references to make common configuration tasks more convenient. Pick the one that matches your hosting model, then customize it as described in [Configuring your Helm values](/docs/on-premises/installation#configure-your-helm-values).

- **Simplified (managed hosting)**: recommended when you use managed external hosting (Amazon S3, Amazon RDS, or equivalents) for FOSSA's dependencies.
- **Simplified (self-hosted)**: when you want FOSSA to self-host its dependencies in-cluster.
- **Advanced**: exposes the full chart configuration directly, without anchors. Reference the comments in the chart's `values.yaml` when using it.

{% callout type="warning" %}
The self-hosted starter file provisions Postgres and MinIO in-cluster. `fossa-core` 6.x has **removed in-cluster Postgres provisioning** and **decoupled MinIO** from the chart. On current charts, configure Postgres (version 17) and S3-compatible storage as external services. See [Migrating to Postgres 17](/docs/on-premises/maintenance/migrating-to-postgres-17) and [Decoupling MinIO from fossa-core](/docs/on-premises/maintenance/decoupling-minio), and always check the chart's own `CHANGELOG.md` for breaking changes before upgrading.
{% /callout %}

{% tabs %}
{% tab name="Simplified (managed hosting)" %}
```yaml
---
################################################################################
## FOSSA on-premises Helm values (simplified)
################################################################################

################################################################################
##
## Modify these values
##
################################################################################
global:
  # Environment name (used for logging).
  environment: production
  # The FOSSA image credentials that you were given by your account manager.
  imageCredentials:
    username:
    password:

# 64-character hexadecimal string, used to encrypt application secrets. Please
# pick something more random than the default value.
encryptionSecret: 0000000000000000000000000000000000000000000000000000000000000000

# The URL hostname and port that the FOSSA web server should listen on.
#
# This hostname must be accessible to users, and you'll need to configure a DNS
# record for this hostname.
hostname: &core-web-hostname fossa.local
port: 80

# If you want your ingress controller to serve FOSSA via HTTPS, you'll need to
# configure that here. Please see your ingress controller's relevant
# documentation to set the correct annotations, if required.
coreIngressAnnotations: &coreIngressAnnotations {}
coreIngressTLS: &coreIngressTLS []

# Set Postgres connection configuration.
postgres: &postgres
  # The URL of the database.
  host:
  # Database user credentials.
  username:
  password:

  # Database name to use for the FOSSA web application's database.
  database: fossa

# Set S3-compatible object storage configuration.
#
# Bucket name for web application file storage.
storageCoreBucket: &storage-core-bucket files.fossa.local
# Bucket name for analysis results storage.
storageHubbleBucket: &storage-hubble-bucket analysis.fossa.local
# The endpoint of the S3 service, including protocol.
storageEndpoint: &storage-endpoint https://s3.us-east-2.amazonaws.com
# The S3 endpoint's region.
storageRegion: &storage-region
# The S3 access key and secret key.
storageAuth: &storage-auth
  accessKey:
  secretKey:

# Configuration for the self-hosted job queue instances.
#
# Password to use for self-hosted web application job queue.
faktoryCorePassword: &faktory-core-password "password"
# Password to use for self-hosted code analysis job queue.
faktoryHubblePassword: &faktory-hubble-password "password"

# Email server for FOSSA web application.
email:
  # The address from which FOSSA will send email.
  from: support@fossa.local

  # SMTP server configuration.
  host: smtp.fossa.local
  port: 1025
  # Credentials for the SMTP server. Remove this section if no auth is required.
  auth:
    user: user
    pass: password

# Self-signed certificates configuration.
trustedCertificates:

# Third-party integrations.
#
# Other providers include `google`, `slack`, and `azureRepos`. For details, see
# the reference documentation in the chart's top-level `values.yaml` file.
github: {}
  # clientId:
  # clientSecret:

################################################################################
##
## Generated configuration values.
##
## DO NOT MODIFY THESE unless you know what you're doing.
##
################################################################################

faktory:
  auth:
    password: *faktory-core-password

storageCommonConfig: &storage
  endpoint: *storage-endpoint
  region: *storage-region
  auth: *storage-auth

storage:
  <<: *storage
  bucket: *storage-core-bucket

hubble:
  postgres: *postgres

  faktory:
    auth:
      password: *faktory-hubble-password

  storage:
    <<: *storage
    bucket: *storage-hubble-bucket

ingress:
  enabled: true
  annotations: *coreIngressAnnotations
  tls: *coreIngressTLS
  hosts:
    - *core-web-hostname

enabledFeatureFlags:
  # Dependency Path in Global Issues Report
  - dependencyPathGlobalIssuesReport
  # Release Groups
  - projectGrouping
  # Disable Org Alert Banner
  - disableOrgAlertBanner
  # License Headers In Reports
  - licenseHeaderReports
  # File Path in Reports
  - filePathInReports
  # Copyright Notices in Reports
  - copyrightReports
  # Show Locators in Plaintext Reports
  - locatorsInPlainTextReports
  # Show Depth in Plaintext Reports
  - depthInPlainTextReports
```
{% /tab %}
{% tab name="Simplified (self-hosted)" %}
```yaml
---
################################################################################
## FOSSA on-premises Helm values (simplified, self-hosted)
################################################################################

################################################################################
##
## Modify these values
##
################################################################################
global:
  # Environment name (used for logging).
  environment: production
  # The FOSSA image credentials that you were given by your account manager.
  imageCredentials:
    username:
    password:

# 64-character hexadecimal string, used to encrypt application secrets. Please
# pick something more random than the default value.
encryptionSecret: 0000000000000000000000000000000000000000000000000000000000000000

# The URL hostname and port that the FOSSA web server should listen on.
#
# This hostname must be accessible to users, and you'll need to configure a DNS
# record for this hostname.
hostname: &core-web-hostname fossa.local
port: 80

# If you want your ingress controller to serve FOSSA via HTTPS, you'll need to
# configure that here. Please see your ingress controller's relevant
# documentation to set the correct annotations, if required.
coreIngressAnnotations: &coreIngressAnnotations {}
coreIngressTLS: &coreIngressTLS []

# Postgres credentials that match your in-cluster Postgres releases. fossa-core
# no longer provisions Postgres in-cluster, so deploy the standalone
# `fossa/postgres` chart (Postgres 17) and point FOSSA at it below. See
# Migrating to Postgres 17 (/docs/on-premises/maintenance/migrating-to-postgres-17).
postgresAuth: &postgres-auth
  username:
  password:

# In-cluster hostnames of your standalone Postgres releases (from the
# `fossa/postgres` chart).
postgresHost: &postgres-host postgres-core
hubblePostgresHost: &hubble-postgres-host postgres-hubble

# In-cluster endpoints of your standalone MinIO releases. fossa-core no longer
# bundles MinIO, so deploy the standalone `fossa/minio` chart and point FOSSA at
# it below. Endpoints must include the `http` prefix. See Decoupling MinIO from
# fossa-core (/docs/on-premises/maintenance/decoupling-minio).
storageEndpoint: &storage-endpoint http://fossa-core-minio
hubbleStorageEndpoint: &hubble-storage-endpoint http://fossa-hubble-minio

# Set the access key and secret key that match your standalone MinIO releases.
storageAuth: &storage-auth
  accessKey:
  secretKey:

# Bucket name for web application file storage.
storageCoreBucket: &storage-core-bucket files.fossa.local
# Bucket name for analysis results storage.
storageHubbleBucket: &storage-hubble-bucket analysis.fossa.local

# Configuration for the self-hosted job queue instances.
#
# Password to use for self-hosted web application job queue.
faktoryCorePassword: &faktory-core-password "password"
# Password to use for self-hosted code analysis job queue.
faktoryHubblePassword: &faktory-hubble-password "password"

# Email server for FOSSA web application. This is never self-hosted.
email:
  # The address from which FOSSA will send email.
  from: support@fossa.local

  # SMTP server configuration.
  host: smtp.fossa.local
  port: 1025
  # Credentials for the SMTP server. Remove this section if no auth is required.
  auth:
    user: user
    pass: password

# Self-signed certificates configuration.
trustedCertificates:

# Third-party integrations.
#
# Other providers include `google`, `slack`, and `azureRepos`. For details, see
# the reference documentation in the chart's top-level `values.yaml` file.
github: {}
  # clientId:
  # clientSecret:

################################################################################
##
## Generated configuration values.
##
## DO NOT MODIFY THESE unless you know what you're doing.
##
################################################################################

# S3-compatible object storage requires `iam.kind: AccessKey` and
# `iam.region: minio` when using MinIO.
iam:
  kind: AccessKey
  region: minio

postgres:
  <<: *postgres-auth
  host: *postgres-host
  database: fossa

storage:
  bucket: *storage-core-bucket
  endpoint: *storage-endpoint
  forcePathStyle: true
  auth: *storage-auth

faktory:
  auth:
    password: *faktory-core-password

hubble:
  iam:
    kind: AccessKey
    region: minio

  postgres:
    <<: *postgres-auth
    host: *hubble-postgres-host
    database: fossa

  faktory:
    auth:
      password: *faktory-hubble-password

  storage:
    bucket: *storage-hubble-bucket
    endpoint: *hubble-storage-endpoint
    forcePathStyle: true
    auth: *storage-auth

ingress:
  enabled: true
  annotations: *coreIngressAnnotations
  tls: *coreIngressTLS
  hosts:
    - *core-web-hostname

enabledFeatureFlags:
  # Dependency Path in Global Issues Report
  - dependencyPathGlobalIssuesReport
  # Release Groups
  - projectGrouping
  # Disable Org Alert Banner
  - disableOrgAlertBanner
  # License Headers In Reports
  - licenseHeaderReports
  # File Path in Reports
  - filePathInReports
  # Copyright Notices in Reports
  - copyrightReports
  # Show Locators in Plaintext Reports
  - locatorsInPlainTextReports
  # Show Depth in Plaintext Reports
  - depthInPlainTextReports
```
{% /tab %}
{% tab name="Advanced" %}
```yaml
---
################################################################################
## FOSSA on-premises Helm values (advanced)
################################################################################
global:
  # Environment name (used for logging).
  environment: production
  # The FOSSA image credentials that you were given by your account manager.
  imageCredentials:
    username:
    password:

# 64-character hexadecimal string, used to encrypt application secrets. Please
# pick something more random than the default value.
encryptionSecret: 0000000000000000000000000000000000000000000000000000000000000000

# The URL hostname and port that the FOSSA web server should listen on.
#
# This hostname must be accessible to users, and you'll need to configure a DNS
# record for this hostname.
hostname: &core-web-hostname fossa.local
port: 80

# Postgres database for the FOSSA web application.
postgres:
  # Database name to use for the FOSSA web application's database.
  database: fossa

  # Username for the database user. If using self-hosted Postgres, this will be
  # the username of the database user that FOSSA creates automatically.
  username:
  # Password for the database user. If using self-hosted Postgres, this will be
  # the password of the database user that FOSSA creates automatically.
  password:

  # If using self-hosted Postgres, set to true. Helm will create and manage a
  # Postgres database as part of this installation. `provisionInstance: true` is
  # mutually exclusive with setting `host`.
  provisionInstance: false
  # If using external managed hosting for Postgres, provide the URL here. Leave
  # blank otherwise. If set, mutually exclusive with `provisionInstance: true`.
  host:

# Object storage for the FOSSA web application.
storage:
  # Access key and secret key for S3 or MinIO.
  auth:
    accessKey:
    secretKey:
  # The bucket name to store FOSSA web application files in.
  bucket: files-fossa.domain.com

  # The endpoint of the S3 service, including protocol. If using S3, this should
  # be an S3 endpoint. If using MinIO, this should be one of the values of
  # `ingress.hosts[]`.
  #
  # Example: https://s3.us-east-2.amazonaws.com
  endpoint:
  # The S3 region. Only required if using S3. Leave empty if using MinIO.
  region:

  # Set to true if using MinIO.
  provisionInstance: false
  # Ingress configuration for MinIO. Configure only if
  # `provisionInstance: true`.
  ingress:
    # Set to true when `provisionInstance: true`.
    enabled: false
    # Set the hostname that MinIO will be accessible at. This should be the
    # hostname of the URL you use in the `endpoint` value.
    #
    # This hostname must be accessible to users, and you'll need to configure a
    # DNS record for this hostname if `provisionInstance: true`.
    hosts:
      - minio-core.local
    # TLS configurations. See your ingress controller for documentation.
    annotations: {}
    tls: []

# Job queue for FOSSA web application. This is always self-hosted.
faktory:
  # Set a password for the self-hosted instance.
  auth:
    password:
  # This configures ingress access for the web dashboard. You probably want to
  # leave this on, although you can turn it off if you need to.
  ui:
    ingress:
      enabled: true
      # The hostname of the URL at which the job queue's web dashboard will be
      # accessible.
      hosts:
        - faktory-core.local
      # TLS configurations. See your ingress controller for documentation.
      annotations: {}
      tls: []

# Email server for FOSSA web application. This is never self-hosted.
email:
  # The address from which FOSSA will send email.
  from: support@fossa.local

  # SMTP server configuration.
  host: smtp.fossa.local
  port: 1025
  # Credentials for the SMTP server. Remove this section if no auth is required.
  auth:
    user: user
    pass: password

# Ingress for the FOSSA web application. This makes the FOSSA service accessible
# from outside the cluster.
ingress:
  enabled: true
  annotations: {}
  tls: []
  hosts:
    - *core-web-hostname

# Self-signed certificates configuration.
trustedCertificates:

# Configuration for Hubble, which is an internal service that FOSSA uses for
# analyzing source code.
hubble:
  # The database for Hubble. Configured the same way as the FOSSA web
  # application's database. See the FOSSA web application configuration
  # comments.
  #
  # NOTE: You can reuse the same database as the FOSSA web application here.
  # Hubble will be careful to use a separate Postgres schema.
  postgres:
    database: fossa
    username:
    password:

    provisionInstance: false
    host:

  # The object storage for Hubble. Configured almost the same way as the FOSSA
  # web application's object storage. See the FOSSA web application
  # configuration comments.
  storage:
    auth:
      secretKey:
      accessKey:
    bucket: analysis-fossa.domain.com

    endpoint: https://s3.us-east-2.amazonaws.com
    region:

    provisionInstance: false
    # Note that Hubble's object storage does not require an ingress.

  # The job queue for Hubble. Configured the same way as the FOSSA web
  # application's job queue. See the FOSSA web application configuration
  # comments.
  faktory:
    auth:
      password:
    ui:
      ingress:
        enabled: true
        hosts:
          - faktory-hubble.local

# Third-party integrations.
#
# Other providers include `google`, `slack`, and `azureRepos`. For details, see
# the reference documentation in the chart's top-level `values.yaml` file.
github: {}
  # clientId:
  # clientSecret:

enabledFeatureFlags:
  # Dependency Path in Global Issues Report
  - dependencyPathGlobalIssuesReport
  # Release Groups
  - projectGrouping
  # Disable Org Alert Banner
  - disableOrgAlertBanner
  # License Headers In Reports
  - licenseHeaderReports
  # File Path in Reports
  - filePathInReports
  # Copyright Notices in Reports
  - copyrightReports
  # Show Locators in Plaintext Reports
  - locatorsInPlainTextReports
  # Show Depth in Plaintext Reports
  - depthInPlainTextReports
```
{% /tab %}
{% /tabs %}

---

Source: https://docs.fossa.com/docs/on-premises/installation/post-install-configuration

# Customizing Your Deployment

Once your installation succeeds, these are common follow-up tasks to tailor FOSSA to your organization. All of them are optional, but it's worth reading through to confirm you haven't missed anything.

Some of these changes require editing your Helm values. To apply changed values to your cluster, see [Updating Helm values](/docs/on-premises/maintenance/updating-helm-values).

## Configuring integrations

FOSSA supports integrations with many third-party tools and services.

### Google SSO

To configure Google Workspace SSO, add your Google Workspace OAuth application's client ID and secret to your Helm values:

```yaml
google:
  clientId: 0123456789abcdef.apps.googleusercontent.com
  clientSecret: fakeSecret0123456789
```

### Quick Import from SCM (GitHub, GitLab, Bitbucket, Azure Repos)

To use Quick Import, integrate FOSSA with the SCM provider that hosts your repositories. Add a client ID and secret for your SCM's OAuth application to your Helm values:

```yaml
# See your values file template for examples for other service providers.
github:
  clientId: 0123456789abcdef
  clientSecret: fakeSecret000000000000000
```

SCM integrations double as SSO, configuring the GitHub integration, for example, also lets users sign in to FOSSA with GitHub. To restrict which sign-in options your organization permits, use the application's UI under **Organization Settings**.

Each SCM integration has vendor-specific fields. For the details of each, see the reference comments in the chart's `values.yaml`.

### Slack notifications

FOSSA can send notifications to a Slack channel. Create a Slack OAuth app, then add its client ID and secret to your Helm values:

```yaml
slack:
  clientId: abcdef
  clientSecret: abcdef
```

## Setting up SAML and LDAP

Once FOSSA is installed, configure SAML and LDAP from the **Organization Settings** page in the application's UI. For day-to-day user and access management, see [Organization Management](/docs/organization-management).

## Setting notification banners

As a FOSSA administrator, you can send instance-wide messages to all FOSSA users. On-premises installations support setting notification banners from your organization settings.

---

Source: https://docs.fossa.com/docs/on-premises/maintenance

# Maintaining FOSSA On-Premises

Once FOSSA is installed and verified, these guides cover the day-2 operations you'll perform against a running deployment. For first-time setup, see [Installing FOSSA On-Premises](/docs/on-premises/installation).

{% callout type="warning" %}
Before upgrading the `fossa-core` chart, always check the chart's own `CHANGELOG.md` for breaking changes; major versions have removed in-cluster Postgres and decoupled MinIO.
{% /callout %}

## What's inside

**Upgrading and configuration**

- [Upgrading FOSSA](/docs/on-premises/maintenance/upgrading-fossa): fetch the new chart, read its changelog, and run `helm upgrade`.
- [Helm Chart 5.0.0 Breaking Change](/docs/on-premises/maintenance/helm-chart-500-breaking-change): MinIO is no longer bundled with the chart; move to external storage.
- [Helm Chart 6.0.0 Breaking Change](/docs/on-premises/maintenance/helm-chart-600-breaking-change): the `redis` Helm values are renamed to `cache`.
- [Helm Chart 7.0.0 Breaking Change](/docs/on-premises/maintenance/helm-chart-700-breaking-change): starts the dependency metadata backfill; must be installed before 8.0.0.
- [Helm Chart 8.0.0 Breaking Change](/docs/on-premises/maintenance/helm-chart-800-breaking-change): removes the legacy dependency-metadata table; install only after the backfill completes.
- [Updating Helm values](/docs/on-premises/maintenance/updating-helm-values): apply configuration changes to a running release.

**Migrating external services**

- [Migrating to Postgres 17](/docs/on-premises/maintenance/migrating-to-postgres-17): move off in-cluster Postgres to managed external Postgres 17, required on current charts.
- [Decoupling MinIO from fossa-core](/docs/on-premises/maintenance/decoupling-minio): move object storage to externally managed MinIO when upgrading to `fossa-core` 5.0.0.
- [Migrating to SeaweedFS](/docs/on-premises/maintenance/migrating-to-seaweedfs): move object storage from MinIO to SeaweedFS.

**Data operations**

- [Vulnerability database updates](/docs/on-premises/maintenance/vulnerability-database-updates): keep your local threat database current with FOSSA's vulnerability feed.
- [Global License Corrections](/docs/on-premises/maintenance/global-license-corrections): override FOSSA's license detection for a package across all of its revisions.

**Troubleshooting and diagnostics**

- [Bitnami image pull errors](/docs/on-premises/maintenance/bitnami-image-pull-errors): resolve `ErrImagePull` / `ImagePullBackOff` on Bitnami Postgres, Redis, and MinIO images.
- [Debug bundle](/docs/on-premises/maintenance/debug-bundle): collect cluster diagnostics for troubleshooting and FOSSA support.

---

Source: https://docs.fossa.com/docs/on-premises/maintenance/upgrading-fossa

# Upgrading FOSSA

Upgrading is a routine part of maintaining your on-premises installation. FOSSA ships as a set of services that are designed to be deployed and upgraded together through Helm, so the supported path is always a single `helm upgrade` of the `fossa-core` chart; never upgrading individual services on their own.

{% callout type="warning" %}
Don't upgrade individual FOSSA services independently. Mismatched component versions can cause performance degradation or, in the worst case, an outage. Always upgrade the whole release with `helm upgrade`.
{% /callout %}

Helm performs a rolling upgrade, so as long as you run more than one replica of `fossa-core-api` there is generally no downtime. Confirm your replica count with `kubectl -n NAMESPACE get deployments`.

## Prerequisites

- Helm is configured to talk to your cluster and the FOSSA chart repository is added. See [Set up Helm](/docs/on-premises/installation#set-up-helm) if you need to reconnect.
- The [Helm release name](https://helm.sh/docs/glossary/#release) of your FOSSA instance, the name you chose in [Install and verify FOSSA](/docs/on-premises/installation#install-and-verify-fossa). The default is `fossa`; run `helm ls -A` to confirm.
- Your values file(s).

## Upgrading your instance

{% steps %}
{% step title="Fetch the latest chart" %}
Update your local copy of the FOSSA chart repository:

```bash
$ helm repo update
Hang tight while we grab the latest from your chart repositories...
...Successfully got an update from the "fossa" chart repository
Update Complete. ⎈Happy Helming!⎈
```

Check the latest chart version available to you:

```bash
$ helm search repo fossa/fossa-core
NAME               	CHART VERSION	APP VERSION	DESCRIPTION
fossa/fossa-core   	6.3.7        	4.33.65    	Deploys the fossa-core monolith
```

If an update is available, you'll see a newer version of `fossa/fossa-core` in this list.
{% /step %}

{% step title="Read the changelog" %}
**Always read the chart's changelog before upgrading.** FOSSA bundles the changelog inside the chart itself, and it's where breaking changes are documented. Breaking upgrades may require action outside of Helm or changes to your values.

Download and unpack the chart into a temporary folder, then read the changelog:

```bash
# Download and unpack the chart
helm pull --untardir /tmp/fossa-helm --untar fossa/fossa-core

# Show the changelog
cat /tmp/fossa-helm/fossa-core/CHANGELOG.md
```

Follow any instructions for breaking upgrades before proceeding. Most upgrades are not breaking and need no action beyond the usual commands; breaking upgrades are always clearly marked. Recent major versions are also documented here: [Helm Chart 5.0.0 Breaking Change](/docs/on-premises/maintenance/helm-chart-500-breaking-change), [Helm Chart 6.0.0 Breaking Change](/docs/on-premises/maintenance/helm-chart-600-breaking-change), [Helm Chart 7.0.0 Breaking Change](/docs/on-premises/maintenance/helm-chart-700-breaking-change), and [Helm Chart 8.0.0 Breaking Change](/docs/on-premises/maintenance/helm-chart-800-breaking-change).
{% /step %}

{% step title="Back up your database" %}
We recommend taking a backup of your database before upgrading. (You can skip this if you use a managed Postgres service with its own backups, such as Amazon RDS.)

```bash
pg_dump -h DATABASE_HOST -U USERNAME -d DATABASE_NAME > /path/to/backup.sql

# For example:
pg_dump -h db.internal -U fossa -d fossa > /opt/fossa_backup/fossa_core_backup.sql
```
{% /step %}

{% step title="Verify the upgrade with a dry run" %}
Run the upgrade with `--dry-run` first to render the manifests and verify your values before applying anything:

```bash
helm upgrade RELEASE_NAME fossa/fossa-core --values YOUR_VALUES_FILE.yaml --reset-values --dry-run --debug
```
{% /step %}

{% step title="Run the upgrade" %}
Once the changelog is reviewed and any out-of-band changes are made, run the upgrade:

```bash
helm upgrade RELEASE_NAME fossa/fossa-core --values YOUR_VALUES_FILE.yaml --reset-values --timeout 60m
```

`--reset-values` ensures you pick up the latest chart defaults and then apply your values file on top.
{% /step %}
{% /steps %}

{% callout type="danger" %}
Pass your configuration with `--values` (optionally with `--reset-values`). Avoid `--reuse-values`: Helm merges values differently and surprisingly with it, and in particular it will **not** merge *new* values introduced by the updated chart.

FOSSA's charts protect you from this with a "minimum values version" field. If you see an error like `FOSSA has updated its default values. You're using X and the latest version is Y. Please upgrade without --reuse-values.`, you likely used `--reuse-values` by accident.
{% /callout %}

Helm takes a while to start the new services, and FOSSA may become briefly unavailable as services restart. Once the upgrade completes, your installation is up to date. 🎉

If you have questions or run into issues, contact your customer support manager or reach out through [FOSSA support](https://support.fossa.com).

---

Source: https://docs.fossa.com/docs/on-premises/maintenance/helm-chart-500-breaking-change

# Helm Chart 5.0.0 Breaking Change

Starting with release 5.0.0, MinIO is no longer bundled with the `fossa-core` Helm chart and is instead treated as an external storage backend. On-premises customers currently relying on the bundled MinIO deployment need to decouple it from fossa-core and migrate to either SeaweedFS or an S3-compatible storage provider.

This change follows the deprecation of MinIO on December 3, 2025, after which it no longer receives new features or security updates.

The following guides walk through the decoupling process and migration to SeaweedFS:

1. [Decoupling MinIO from fossa-core](/docs/on-premises/maintenance/decoupling-minio)
2. [Migrating to SeaweedFS](/docs/on-premises/maintenance/migrating-to-seaweedfs)

---

Source: https://docs.fossa.com/docs/on-premises/maintenance/helm-chart-600-breaking-change

# Helm Chart 6.0.0 Breaking Change

Starting with release 6.0.0, the `redis` Helm settings are renamed to `cache` to support the transition to the open-source version of Redis. Settings previously defined under `redis.*` move to `cache.*`, and settings under `redis.master.*` move to `cache.redis.*`.

{% callout type="warning" %}
When `cache.provisionInstance` is `true`, use `cache.auth.password` to set the Redis password. When `cache.provisionInstance` is `false`, use `cache.password`. This is by design: it segregates the passwords defined by fossa-core from those of the dependent Redis Helm chart (aliased as `cache`).
{% /callout %}

Update your values file as shown below, then run the upgrade as usual (see [Upgrading FOSSA](/docs/on-premises/maintenance/upgrading-fossa)).

## Provisioned Redis (`provisionInstance: true`)

Old format:

```yaml
redis:
  provisionInstance: true
  auth:
    password: "hello-world"
  master:
    resources:
      requests:
        memory: 128Mi
        cpu: 100m
```

New format:

```yaml
cache:
  provisionInstance: true
  auth:
    password: "hello-world"
  redis:
    resources:
      requests:
        memory: 128Mi
        cpu: 100m
```

## External Redis (`provisionInstance: false`)

Old format:

```yaml
redis:
  provisionInstance: false
  host: clustercfg.redis-abcd.usw2.cache.amazonaws.com
  port: 6379
  clustered: true
  scaleReads: all
  enableAutoPipelining: true
  useTLS: true
  password: "hello-world"
```

New format:

```yaml
cache:
  provisionInstance: false
  host: clustercfg.redis-abcd.usw2.cache.amazonaws.com
  port: 6379
  clustered: true
  scaleReads: all
  enableAutoPipelining: true
  useTLS: true
  password: "hello-world"
```

---

Source: https://docs.fossa.com/docs/on-premises/maintenance/helm-chart-700-breaking-change

# Helm Chart 7.0.0 Breaking Change

Starting with release 7.0.0, FOSSA begins migrating dependency-graph data out of the legacy `DependencyLocks` table and into a newer storage service. Deploying this version automatically enqueues a background backfill job that copies all existing dependency data into the new storage.

The upgrade itself is routine: no downtime, no maintenance window, and no values-file changes. The breaking part is the ordering constraint it creates.

{% callout type="warning" %}
Do not upgrade to `8.0.0` until the backfill started by `7.0.0` has completed and you have received the backfill completion email. Removing the legacy table early can result in the loss of dependency details for scans that had not yet been migrated.
{% /callout %}

## Required upgrade order

1. Upgrade to `7.0.0` and let the backfill run in the background.
2. Wait for the `[FOSSA] Sparkle depgraph backfill complete` email sent to your super users.
3. Only then upgrade to [`8.0.0`](/docs/on-premises/maintenance/helm-chart-800-breaking-change).

Before upgrading, confirm that at least one enabled super-user account has a valid, monitored email address, since that is where the completion notification is sent.

For how long the backfill takes, what to expect while it runs, and how to check progress, see [Dependency Metadata Migration](/docs/on-premises/maintenance/dependency-metadata-migration).

---

Source: https://docs.fossa.com/docs/on-premises/maintenance/helm-chart-800-breaking-change

# Helm Chart 8.0.0 Breaking Change

Starting with release 8.0.0, the legacy `DependencyLocks` dependency-metadata table is removed. Dependency data is served entirely from the newer storage service that [`7.0.0`](/docs/on-premises/maintenance/helm-chart-700-breaking-change) backfills into.

The upgrade itself is routine: no downtime, no maintenance window, and no values-file changes. The breaking part is the prerequisite.

{% callout type="warning" %}
Install this release only after the backfill started by `7.0.0` has completed and you have received the `[FOSSA] Sparkle depgraph backfill complete` email. Installing it early can result in the loss of dependency details for scans that had not yet been migrated. If you have not received the email, contact FOSSA support rather than proceeding.
{% /callout %}

## Required upgrade order

1. Upgrade to [`7.0.0`](/docs/on-premises/maintenance/helm-chart-700-breaking-change) first, which starts the backfill.
2. Wait for the backfill completion email.
3. Upgrade to `8.0.0`.

Skipping straight to `8.0.0` from a version earlier than `7.0.0` is not supported, since the backfill never runs.

For what the migration does, what happens to historical dependency data afterward, and answers to common questions, see [Dependency Metadata Migration](/docs/on-premises/maintenance/dependency-metadata-migration).

---

Source: https://docs.fossa.com/docs/on-premises/maintenance/updating-helm-values

# Updating Helm Values

After your initial installation, you'll sometimes need to change the Helm values FOSSA is running with, for example, to configure an integration or adjust a setting. Applying new values is a straightforward `helm upgrade`.

{% steps %}
{% step title="Confirm Helm is set up" %}
Make sure `helm` is configured to talk to your cluster. See [Set up Helm](/docs/on-premises/installation#set-up-helm) if you need to reconnect or re-add the FOSSA chart repository.
{% /step %}

{% step title="Prepare your new values" %}
Edit your values file with the changes you want to apply.
{% /step %}

{% step title="Find your release name" %}
You'll need the [Helm release name](https://helm.sh/docs/glossary/#release) of the FOSSA instance you're upgrading, the name you chose in [Install and verify FOSSA](/docs/on-premises/installation#install-and-verify-fossa). If you don't remember it, run `helm list` to see every release in your cluster.
{% /step %}

{% step title="Run the upgrade" %}
```bash
$ helm upgrade --namespace NAMESPACE RELEASE_NAME fossa/fossa-core --values YOUR_VALUES_FILE.yaml --timeout 60m
```

This creates a new version of your release using the updated values.
{% /step %}
{% /steps %}

{% callout type="info" %}
The upgrade may take some time to finish. Some upgrades cause FOSSA to become briefly unavailable as services restart.
{% /callout %}

---

Source: https://docs.fossa.com/docs/on-premises/maintenance/migrating-to-postgres-17

# Migrating to Postgres 17

This guide walks through migrating a FOSSA-managed Postgres database (version 11.8) to a standalone Postgres 17.x instance. For customers running databases inside Kubernetes, the example steps use the `fossa/postgres` Helm chart, but any properly configured Postgres 17.x database is supported.

{% callout type="warning" %}
After **June 16, 2025**, FOSSA no longer bundles a Postgres database within the FOSSA Helm charts. If you currently rely on the built-in provisioned instances (`postgres.provisionInstance`, `hubble.postgres.provisionInstance`, or `sparklePostgres.provisionInstance`), you must migrate to an **externally provisioned Postgres 17 database** to keep receiving updates.

For Postgres running inside your cluster, we recommend the `fossa/postgres` 2.0.0+ Helm chart as a convenient, tested deployment method. Any properly configured Postgres 17.x database (Amazon RDS, Aurora Postgres, or self-managed Postgres 17) is also supported.
{% /callout %}

## Prerequisites

- `psql` client 17.x (Postgres 17.2)
- `helm` 3.17+
- `kubectl` 1.28+ with Kubernetes API access
- FOSSA Helm charts, including the `fossa/postgres` chart version `2.0.0`+ (see [Set up Helm](/docs/on-premises/installation#set-up-helm))
- Quay pull secrets

## Recommendations

- The default resource values for database deployments match FOSSA Core's defaults. If your application has customized resource requirements, adjust the database configuration files accordingly.
- If you use external Postgres services (e.g. RDS or self-hosted instances), ensure that:
  - Required extensions (`pgcrypto`, `uuid-ossp`) are available.
  - The database is reachable from the FOSSA application. (SSL is not currently supported.)
  - Authentication credentials and roles allow schema migrations.
- If your vulns updater is disabled, ignore the associated configuration steps in this guide.

## Assumptions

The example commands assume:

- Your Helm release is named `fossa`.
- Database credentials are `fossa` / `fossa123` for Core, Sparkle, and Hubble, with services:
  - **Core**: old: `fossa-core-postgres`, new: `postgres-core`
  - **Sparkle**: old: `fossa-sparkle-postgres`, new: `postgres-sparkle`
  - **Hubble**: old: `fossa-hubble-postgres`, new: `postgres-hubble`
- Resource settings align with Core's defaults unless otherwise specified.
- The vulns updater is enabled.
- Quay.io pull secrets are username `fossa+customer`, password `HELLOWORLD1`.

## Migration steps

{% steps %}
{% step title="Add the FOSSA chart repository" %}
```shell
helm repo add fossa https://charts.fossa.com
helm repo update
```
{% /step %}

{% step title="Set the namespace" %}
```shell
kubectl config set-context --current --namespace=fossa
```
{% /step %}

{% step title="Create a values file for each database" %}
Create a values file for the Core, Sparkle, and Hubble databases with the appropriate credentials and resources for the Postgres chart.

**Core: `core-psql-values.yml`**

```yaml
database: fossa
username: fossa
password: fossa123
image.registry: quay.io
image.repository: fossa/postgres
image.tag: 17.2-1

imageCredentials:
  username: fossa+customer
  password: HELLOWORLD1

resources:
  limits:
    cpu: 4000m
    memory: 4Gi
  requests:
    cpu: 2000m
    memory: 4Gi
```

**Sparkle: `sparkle-psql-values.yml`**

```yaml
database: sparkle
username: fossa
password: fossa123
image.registry: quay.io
image.repository: fossa/postgres
image.tag: 17.2-1

imageCredentials:
  username: fossa+customer
  password: HELLOWORLD1

resources:
  limits:
    cpu: 4000m
    memory: 4Gi
  requests:
    cpu: 2000m
    memory: 4Gi
```

**Hubble: `hubble-psql-values.yml`**

```yaml
database: hubble
username: fossa
password: fossa123
image.registry: quay.io
image.repository: fossa/postgres
image.tag: 17.2-1

imageCredentials:
  username: fossa+customer
  password: HELLOWORLD1

resources:
  limits:
    cpu: 4000m
    memory: 4Gi
  requests:
    cpu: 2000m
    memory: 4Gi
```
{% /step %}

{% step title="Install the Postgres chart for each database" %}
```shell
helm upgrade -i postgres-core fossa/postgres --values core-psql-values.yml
helm upgrade -i postgres-sparkle fossa/postgres --values sparkle-psql-values.yml
helm upgrade -i postgres-hubble fossa/postgres --values hubble-psql-values.yml
```
{% /step %}

{% step title="Set the application to maintenance mode" %}
```shell
helm upgrade -i fossa fossa/fossa-core --set global.maintenanceMode.enabled=true --set vulns.updater.enabled=false --reuse-values
```

If your vulns updater is disabled, omit the vulns parameters:

```shell
helm upgrade -i fossa fossa/fossa-core --set global.maintenanceMode.enabled=true --reuse-values
```
{% /step %}

{% step title="Back up the databases" %}
Back up the Core, Hubble, and Sparkle databases, terminating each port-forward when the dump completes.

**Core**

```shell
kubectl port-forward service/fossa-core-postgres 5432:5432 &
pg_dumpall -h localhost -U fossa -f fossa-core-backup.bkp
# Terminate the port-forward using `fg` and `Ctrl+C`
fg
```

**Sparkle**

```shell
kubectl port-forward service/fossa-sparkle-postgres 5432:5432 &
pg_dumpall -h localhost -U fossa -f fossa-sparkle-backup.bkp
# Terminate the port-forward using `fg` and `Ctrl+C`
fg
```

**Hubble**

```shell
kubectl port-forward service/fossa-hubble-postgres 5432:5432 &
pg_dumpall -h localhost -U fossa -f fossa-hubble-backup.bkp
# Terminate the port-forward using `fg` and `Ctrl+C`
fg
```
{% /step %}

{% step title="Restore the databases" %}
Restore each database from its backup into the new instance.

**Core**

```shell
kubectl port-forward service/postgres-core 5432:5432 &
psql -h localhost -U fossa -d fossa -f fossa-core-backup.bkp
# Terminate the port-forward using `fg` and `Ctrl+C`
fg
```

**Sparkle**

```shell
kubectl port-forward service/postgres-sparkle 5432:5432 &
psql -h localhost -U fossa -d sparkle -f fossa-sparkle-backup.bkp
# Terminate the port-forward using `fg` and `Ctrl+C`
fg
```

**Hubble**

```shell
kubectl port-forward service/postgres-hubble 5432:5432 &
psql -h localhost -U fossa -d hubble -f fossa-hubble-backup.bkp
# Terminate the port-forward using `fg` and `Ctrl+C`
fg
```
{% /step %}

{% step title="Check database health" %}
```shell
kubectl logs sts/postgres-core -f
kubectl logs sts/postgres-sparkle -f
kubectl logs sts/postgres-hubble -f
```
{% /step %}

{% step title="Point the applications at the new databases" %}
**Core**

```shell
helm upgrade -i fossa fossa/fossa-core --set postgres.host=postgres-core --reuse-values
```

**Sparkle**

```shell
helm upgrade -i fossa fossa/fossa-sparkle --set sparklePostgres.externalHost=postgres-sparkle --reuse-values
```

**Hubble**

```shell
helm upgrade -i fossa fossa/fossa-hubble --set hubble.postgres.host=postgres-hubble --reuse-values
```
{% /step %}

{% step title="Set the application to production mode" %}
```shell
helm upgrade -i fossa fossa/fossa-core --set global.maintenanceMode.enabled=false --set vulns.updater.enabled=true --reuse-values
```

If your vulns updater is disabled, omit the vulns parameters:

```shell
helm upgrade -i fossa fossa/fossa-core --set global.maintenanceMode.enabled=false --reuse-values
```
{% /step %}

{% step title="Confirm the application is healthy" %}
```shell
kubectl logs deployment/fossa-fossa-core-api -f
kubectl logs deployment/fossa-fossa-core-workers-primary -f
kubectl logs deployment/fossa-fossa-hubble-api -f
kubectl logs deployment/fossa-fossa-core-sparkle-api -f
```
{% /step %}

{% step title="Update your main values file" %}
After confirming the applications are healthy, update your values file to use the new databases.

```yaml
postgres:
  host: postgres-core

sparklePostgres:
  externalHost: postgres-sparkle

hubble:
  postgres:
    host: postgres-hubble
```
{% /step %}
{% /steps %}

## Connecting to an external database

If you're connecting FOSSA Core to an external Postgres 17.x service such as Amazon RDS, Aurora, or self-hosted Postgres:

- You don't need to deploy the Postgres Helm charts.
- Update your FOSSA Helm values to point at the external database hostnames.
- Ensure firewall/endpoint access between FOSSA pods and your database.
- Ensure required extensions (`pgcrypto`, `uuid-ossp`) are enabled.
- Review resource sizing and connection-pool settings for performance.

Example for an external RDS database:

```yaml
postgres:
  host: your-rds-endpoint.amazonaws.com
  username: fossa
  password: your-fossa-password
  database: fossa
```

Repeat similar configuration for Sparkle and Hubble if those services are deployed.

## Final verification

Once all updates are complete:

- Ensure all FOSSA pods are healthy.
- Verify schema migrations completed successfully.
- Confirm FOSSA Core, Sparkle, and Hubble are operating normally.
- Confirm the data from before the upgrade is still available in the web interface.

---

Source: https://docs.fossa.com/docs/on-premises/maintenance/decoupling-minio

# Decoupling MinIO from fossa-core

As of `fossa-core` **5.0.0**, MinIO is no longer a sub-chart dependency. Instead, MinIO is deployed via its own Helm chart for both fossa-core and Hubble. Migrating off the bundled MinIO requires a scheduled maintenance window of roughly 30 minutes to 1 hour.

The following configuration changes are required during the migration:

- `storage.endpoint` must include the `http` prefix.
- `iam.kind` must be set to `AccessKey`, and `iam.region` must be set to `minio`.
- `storage.forcePathStyle` must be set to `true` when using MinIO.
- `hubble.storage.endpoint` must include the `http` prefix.
- `hubble.iam.kind` must be set to `AccessKey`, and `hubble.iam.region` must be set to `minio`.
- `storage.provisionInstance` and `hubble.storage.provisionInstance` must be removed. They are deprecated flags.

## Assumptions

The example commands assume:

- Namespace: `fossa`
- fossa-core release name: `fossa`
- Values files:
  - MinIO bundled config: `fossa-core-config.yml`
  - New decoupled config: `decoupled-fossa-core-config.yml`
- Persistent Volume Claims (PVCs): `fossa-core-minio`, `fossa-hubble-minio`
- Existing buckets: `fossa.test` (core), `hubble.fossa.test` (hubble)
- `storage.endpoint`: `http://fossa-core-minio`, `storage.forcePathStyle`: `true`
- `hubble.storage.endpoint`: `http://fossa-hubble-minio`
- IAM overrides: `iam.kind: AccessKey`, `iam.region: minio` (and the same under `hubble.iam`)

{% callout type="danger" %}
This migration deletes the fossa-core release. Your MinIO data survives only if its PVCs are annotated with `helm.sh/resource-policy: keep`. Verify this (Step 3) before proceeding; if the annotation is missing, **do not continue**.
{% /callout %}

## Decoupling steps

{% steps %}
{% step title="Set the namespace" %}
```shell
kubectl config set-context --current --namespace=fossa
```
{% /step %}

{% step title="Locate the MinIO PVCs" %}
Find the MinIO PVCs and note them. They follow the pattern `RELEASE-minio` for fossa-core and `RELEASE-hubble-minio` for Hubble:

- `fossa-core-minio`
- `fossa-hubble-minio`
{% /step %}

{% step title="Confirm the PVC resource policy is `keep`" %}
Ensure both PVCs have the resource-policy annotation set to `keep`. **If this is not the case, do not proceed.**

```shell
kubectl get pvc fossa-core-minio -o jsonpath='{.metadata.annotations.helm\.sh/resource-policy}'
kubectl get pvc fossa-hubble-minio -o jsonpath='{.metadata.annotations.helm\.sh/resource-policy}'
```
{% /step %}

{% step title="Enable maintenance mode" %}
This triggers a downtime event.

```shell
helm upgrade -i fossa fossa/fossa-core --values fossa-core-config.yml --set global.maintenanceMode.enabled=true --version "^4.0.0"
```
{% /step %}

{% step title="Delete the fossa-core release" %}
This triggers a downtime event. The MinIO PVCs are retained because of their `keep` resource policy.

```shell
helm delete fossa
```
{% /step %}

{% step title="Deploy externally managed MinIO releases" %}
Deploy standalone MinIO releases for fossa-core and Hubble, reusing the existing PVCs with `persistence.existingClaim`:

```shell
helm upgrade -i fossa-core-minio fossa/minio --set bucket=fossa.test --set auth.accessKey=minio --set auth.secretKey=minio123 --set persistence.existingClaim=fossa-core-minio

helm upgrade -i fossa-hubble-minio fossa/minio --set bucket=hubble.fossa.test --set auth.accessKey=minio --set auth.secretKey=minio123 --set persistence.existingClaim=fossa-hubble-minio
```
{% /step %}

{% step title="Upgrade fossa-core to 5.0.0" %}
Ensure `storage.endpoint`, `iam.kind`, `iam.region`, `hubble.storage.endpoint`, `hubble.iam.kind`, and `hubble.iam.region` are defined in your values file.

Example `decoupled-fossa-core-config.yml`:

```yaml
# decoupled-fossa-core-config.yml

iam:
  kind: AccessKey
  region: minio

storage:
  endpoint: http://fossa-core-minio
  bucket: fossa.test
  forcePathStyle: true
  auth:
    accessKey: minio
    secretKey: minio123

hubble:
  iam:
    kind: AccessKey
    region: minio

  storage:
    bucket: hubble.fossa.test
    endpoint: http://fossa-hubble-minio
    auth:
      accessKey: minio
      secretKey: minio123
```

Upgrade:

```shell
helm upgrade -i fossa fossa/fossa-core --values decoupled-fossa-core-config.yml --version "^5.0.0"
```
{% /step %}

{% step title="Verify pod health and data" %}
Ensure all pods become healthy and your data is still available:

```shell
kubectl exec fossa-core-minio-0 -- /opt/bitnami/minio-client/bin/mc ls local/fossa.test/BUILDS/
kubectl exec fossa-hubble-minio-0 -- /opt/bitnami/minio-client/bin/mc ls local/hubble.fossa.test/BUILDS/
```
{% /step %}

{% step title="Confirm in the UI" %}
Log in to the FOSSA UI and confirm your data is available.
{% /step %}
{% /steps %}

---

Source: https://docs.fossa.com/docs/on-premises/maintenance/migrating-to-seaweedfs

# Migrating to SeaweedFS

This guide moves your on-premises object storage backend from MinIO to **SeaweedFS**, FOSSA's S3-compatible storage option. FOSSA uses two SeaweedFS instances (one for Core analysis artifacts and one for Hubble compliance data) and the migration copies your existing MinIO data into them before cutting the deployment over.

The migration has two phases: **prepare** the SeaweedFS deployments, then **execute** the cutover during a maintenance window.

{% callout type="warning" %}
The cutover requires maintenance mode and a data transfer. Plan for downtime proportional to how much object data you're migrating.
{% /callout %}

## Preparation

Create SeaweedFS deployments for Core and Hubble sized to your storage needs. FOSSA requires two instances:

- `core-seaweedfs`: stores analysis artifacts for FOSSA Core
- `hubble-seaweedfs`: stores compliance data for FOSSA Hubble

The template below documents installation, upgrade, and the sizing guide:

```yaml
# =============================================================================
# SeaweedFS Storage Values Template for FOSSA Deployment
# =============================================================================
#
# FOSSA requires two SeaweedFS instances for S3-compatible object storage:
#   1. core-seaweedfs   - Stores analysis artifacts for FOSSA Core
#   2. hubble-seaweedfs - Stores compliance data for FOSSA Hubble
#
# Adjust storage sizes based on your expected workload. See the "Sizing Guide"
# at the bottom of this file for recommendations.
#
# Prerequisites:
#   - A Kubernetes cluster with a default StorageClass configured
#   - Helm 3.x
#
# Installation:
#   helm repo add fossa https://charts.fossa.com
#   helm repo update
#
#   helm install core-seaweedfs fossa/seaweedfs \
#     --namespace <namespace> \
#     --version 4.17.0 \
#     -f core-seaweedfs-values.yaml
#
#   helm install hubble-seaweedfs fossa/seaweedfs \
#     --namespace <namespace> \
#     --version 4.17.0 \
#     -f hubble-seaweedfs-values.yaml
#
# Upgrade:
#   helm upgrade core-seaweedfs fossa/seaweedfs \
#     --namespace <namespace> \
#     --version 4.17.0 \
#     -f core-seaweedfs-values.yaml
#
#   helm upgrade hubble-seaweedfs fossa/seaweedfs \
#     --namespace <namespace> \
#     --version 4.17.0 \
#     -f hubble-seaweedfs-values.yaml
#
# =============================================================================
# Sizing Guide
# =============================================================================
#
# The main values to adjust are volume.dataDirs[].size fields. These control
# how much raw data each SeaweedFS instance can store.
#
# Recommended volume sizes by deployment scale:
#
#   Deployment Size         | Core volume.size | Hubble volume.size | Notes
#   ------------------------|------------------|--------------------|-------------------
#   Small  (<100 projects)  |  50Gi            |  25Gi              | Dev/eval environments
#   Medium (<500 projects)  | 100Gi            |  50Gi              | Standard production
#   Large  (<2000 projects) | 250Gi            | 100Gi              | Large organizations
#   XLarge (2000+ projects) | 500Gi+           | 250Gi+             | Enterprise scale
#
# Other parameters:
#
#   master.data.size   - Volume metadata. 1Gi is sufficient for all but the
#                        largest deployments (10k+ volumes).
#
#   filer.data.size    - File index. 1Gi handles millions of objects. Increase
#                        to 5-10Gi only if you expect tens of millions of files.
#
#   maxVolumes         - Upper limit on the number of logical volumes SeaweedFS
#                        can create. The defaults (10000 for core, 6000 for
#                        hubble) are generous and rarely need adjustment.
#
#   storageClass       - Uncomment and set if you need a specific Kubernetes
#                        StorageClass (e.g., for SSD-backed storage, specific
#                        provisioners, or cloud-specific volume types). If left
#                        commented out, the cluster default StorageClass is used.
#
# Storage can be expanded after initial deployment by increasing the PVC size,
# provided your StorageClass supports volume expansion
# (allowVolumeExpansion: true).
# =============================================================================
```

**Core: `core-seaweedfs-values.yaml`**

After installation, the Core S3 endpoint is available at `http://core-seaweedfs-s3:8333`.

```yaml
nameOverride: core-seaweedfs

global:
  serviceAccountName: core-seaweedfs
  imagePullSecrets: test-fossa-core-quay.io # <-- existing pull secret created by fossa-core when release name is `test`; list them with `kubectl get secrets --field-selector type=kubernetes.io/dockerconfigjson`

# -- S3 API Configuration
s3:
  enabled: true
  enableAuth: true
  createBuckets:
    - name: fossa.test
      anonymousRead: false

# -- Master Server Storage (volume metadata and cluster topology; lightweight)
master:
  data:
    type: persistentVolumeClaim
    size: 1Gi                            # <-- Adjust if needed (rarely necessary)
    # storageClass: ""                   # <-- Uncomment to use a specific StorageClass

# -- Filer Storage (file-to-chunk mapping index)
filer:
  data:
    type: persistentVolumeClaim
    size: 1Gi                            # <-- Adjust if needed
    # storageClass: ""                   # <-- Uncomment to use a specific StorageClass
  logs:
    type: emptyDir

# -- Volume Server Storage (primary data storage)
volume:
  dataDirs:
    - name: data1
      type: persistentVolumeClaim
      size: 100Gi                        # <-- ADJUST: Set based on expected data volume
      maxVolumes: 10000
      # storageClass: ""                 # <-- Uncomment to use a specific StorageClass
```

**Hubble: `hubble-seaweedfs-values.yaml`**

After installation, the Hubble S3 endpoint is available at `http://hubble-seaweedfs-s3:8333`.

```yaml
nameOverride: hubble-seaweedfs

global:
  serviceAccountName: hubble-seaweedfs
  imagePullSecrets: test-hubble-quay.io # <-- existing pull secret created by fossa-core when release name is `test`; list them with `kubectl get secrets --field-selector type=kubernetes.io/dockerconfigjson`

# -- S3 API Configuration
s3:
  enabled: true
  enableAuth: true
  createBuckets:
    - name: hubble.fossa.test
      anonymousRead: false

# -- Master Server Storage (volume metadata and cluster topology; lightweight)
master:
  data:
    type: persistentVolumeClaim
    size: 1Gi                            # <-- Adjust if needed (rarely necessary)
    # storageClass: ""                   # <-- Uncomment to use a specific StorageClass

# -- Filer Storage (file-to-chunk mapping index)
filer:
  data:
    type: persistentVolumeClaim
    size: 1Gi                            # <-- Adjust if needed
    # storageClass: ""                   # <-- Uncomment to use a specific StorageClass
  logs:
    type: emptyDir

# -- Volume Server Storage (primary data storage)
volume:
  dataDirs:
    - name: data1
      type: persistentVolumeClaim
      size: 100Gi                         # <-- ADJUST: Set based on expected data volume
      maxVolumes: 6000
      # storageClass: ""                 # <-- Uncomment to use a specific StorageClass
```

## Execution

{% steps %}
{% step title="Schedule a maintenance window" %}
Pick a window long enough to transfer your object data and verify the cutover.
{% /step %}

{% step title="Set the application to maintenance mode" %}
Assuming the namespace is `fossa`:

```shell
kubectl config set-context --current --namespace=fossa
helm upgrade -i fossa fossa/fossa-core --values fossa-core-config.yml --set global.maintenanceMode.enabled=true --version "^4.0.0"
```
{% /step %}

{% step title="Deploy SeaweedFS for Core and Hubble" %}
```shell
helm upgrade -i core-seaweedfs fossa/seaweedfs --values core-seaweedfs-values.yaml
helm upgrade -i hubble-seaweedfs fossa/seaweedfs --values hubble-seaweedfs-values.yaml
```
{% /step %}

{% step title="Transfer data from MinIO to SeaweedFS" %}
The Job below uses `rclone` to copy all data from Core and Hubble MinIO into SeaweedFS. Update the `rclone.conf` endpoints and credentials to match your deployment. The example assumes:

- **Core**: bucket `fossa.test`; MinIO `minio` / `minio123` at `http://fossa-core-minio:80`; SeaweedFS at `http://core-seaweedfs-s3:8333`
- **Hubble**: bucket `hubble.fossa.test`; MinIO `minio` / `minio123` at `http://fossa-hubble-minio:80`; SeaweedFS `seaweedfs` / `seaweedfs123` at `http://hubble-seaweedfs-s3:8333`

```yaml
# rclone-migration-minio-seaweedfs.yaml
apiVersion: v1
kind: ConfigMap
metadata:
  name: rclone-migration-config
data:
  rclone.conf: |
    [minio-core]
    type = s3
    provider = Minio
    access_key_id = minio
    secret_access_key = minio123
    endpoint = http://fossa-core-minio:80
    region = minio

    [minio-hubble]
    type = s3
    provider = Minio
    access_key_id = minio
    secret_access_key = minio123
    endpoint = http://fossa-hubble-minio:80
    region = minio

    [seaweedfs-core]
    type = s3
    provider = Other
    access_key_id = seaweedfs
    secret_access_key = seaweedfs123
    endpoint = http://core-seaweedfs-s3:8333
    region = us-east-1
    force_path_style = true

    [seaweedfs-hubble]
    type = s3
    provider = Other
    access_key_id = seaweedfs
    secret_access_key = seaweedfs123
    endpoint = http://hubble-seaweedfs-s3:8333
    region = us-east-1
    force_path_style = true

  core-bucket: "fossa.test"
  hubble-bucket: "hubble.fossa.test"
  migrate.sh: |
    #!/bin/sh
    set -e

    echo "============================================"
    echo "  MinIO -> SeaweedFS Migration"
    echo "  Started: $(date -u +%Y-%m-%dT%H:%M:%SZ)"
    echo "============================================"

    # ---------- tuning knobs (adjust for production) ----------
    # TRANSFERS:  number of file transfers in parallel
    # CHECKERS:   number of parallel hash-checking threads
    # S3_CONCURRENCY: multipart upload concurrency per file
    # S3_CHUNK:   multipart chunk size (bigger = fewer API calls for large files)
    # BUFFER:     in-memory buffer per transfer
    TRANSFERS="${RCLONE_TRANSFERS:-16}"
    CHECKERS="${RCLONE_CHECKERS:-8}"
    S3_CONCURRENCY="${RCLONE_S3_UPLOAD_CONCURRENCY:-4}"
    S3_CHUNK="${RCLONE_S3_CHUNK_SIZE:-64M}"
    BUFFER="${RCLONE_BUFFER_SIZE:-32M}"

    COMMON_FLAGS="--transfers=$TRANSFERS \
      --checkers=$CHECKERS \
      --s3-upload-concurrency=$S3_CONCURRENCY \
      --s3-chunk-size=$S3_CHUNK \
      --buffer-size=$BUFFER \
      --stats=10s \
      --stats-one-line \
      --log-level=INFO \
      --checksum \
      --retries=3 \
      --retries-sleep=5s \
      --low-level-retries=10"

    # ---------- pre-flight checks ----------
    echo ""
    echo ">>> Pre-flight: listing source buckets"
    echo "--- minio-core ---"
    rclone lsd minio-core: 2>&1
    echo "--- minio-hubble ---"
    rclone lsd minio-hubble: 2>&1
    echo "--- seaweedfs-core ---"
    rclone lsd seaweedfs-core: 2>&1
    echo "--- seaweedfs-hubble ---"
    rclone lsd seaweedfs-hubble: 2>&1

    echo ""
    echo ">>> Source object counts"
    CORE_SRC=$(rclone size minio-core:$CORE_BUCKET --json 2>/dev/null)
    HUBBLE_SRC=$(rclone size minio-hubble:$HUBBLE_BUCKET --json 2>/dev/null)
    echo "  core:   $CORE_SRC"
    echo "  hubble: $HUBBLE_SRC"

    # ---------- migration: core ----------
    echo ""
    echo "============================================"
    echo "  [1/2] Migrating core: minio -> seaweedfs"
    echo "============================================"
    eval rclone sync minio-core:$CORE_BUCKET seaweedfs-core:$CORE_BUCKET $COMMON_FLAGS 2>&1
    CORE_RC=$?
    echo "  core migration exit code: $CORE_RC"

    # ---------- migration: hubble ----------
    echo ""
    echo "============================================"
    echo "  [2/2] Migrating hubble: minio -> seaweedfs"
    echo "============================================"
    eval rclone sync minio-hubble:$HUBBLE_BUCKET seaweedfs-hubble:$HUBBLE_BUCKET $COMMON_FLAGS 2>&1
    HUBBLE_RC=$?
    echo "  hubble migration exit code: $HUBBLE_RC"

    # ---------- post-migration validation ----------
    echo ""
    echo "============================================"
    echo "  Post-migration validation"
    echo "============================================"

    echo ""
    echo ">>> Destination object counts"
    CORE_DST=$(rclone size seaweedfs-core:$CORE_BUCKET --json 2>/dev/null)
    HUBBLE_DST=$(rclone size seaweedfs-hubble:$HUBBLE_BUCKET --json 2>/dev/null)
    echo "  core src:    $CORE_SRC"
    echo "  core dst:    $CORE_DST"
    echo "  hubble src:  $HUBBLE_SRC"
    echo "  hubble dst:  $HUBBLE_DST"

    echo ""
    echo ">>> Checking for differences (core)..."
    rclone check minio-core:$CORE_BUCKET seaweedfs-core:$CORE_BUCKET --one-way $COMMON_FLAGS 2>&1
    CORE_CHECK=$?

    echo ""
    echo ">>> Checking for differences (hubble)..."
    rclone check minio-hubble:$HUBBLE_BUCKET seaweedfs-hubble:$HUBBLE_BUCKET --one-way $COMMON_FLAGS 2>&1
    HUBBLE_CHECK=$?

    echo ""
    echo "============================================"
    echo "  Migration Summary"
    echo "  Finished: $(date -u +%Y-%m-%dT%H:%M:%SZ)"
    echo "============================================"
    echo "  Core   sync=$CORE_RC   check=$CORE_CHECK"
    echo "  Hubble sync=$HUBBLE_RC check=$HUBBLE_CHECK"

    if [ "$CORE_RC" -ne 0 ] || [ "$HUBBLE_RC" -ne 0 ] || [ "$CORE_CHECK" -ne 0 ] || [ "$HUBBLE_CHECK" -ne 0 ]; then
      echo "  STATUS: FAILED (see logs above)"
      exit 1
    fi

    echo "  STATUS: SUCCESS"
---
apiVersion: batch/v1
kind: Job
metadata:
  name: rclone-minio-to-seaweedfs
spec:
  backoffLimit: 2
  ttlSecondsAfterFinished: 86400
  template:
    metadata:
      labels:
        app: rclone-migration
    spec:
      restartPolicy: OnFailure
      containers:
      - name: rclone
        image: rclone/rclone:latest
        imagePullPolicy: IfNotPresent
        command: ["/bin/sh", "/scripts/migrate.sh"]
        env:
        - name: CORE_BUCKET
          valueFrom:
            configMapKeyRef:
              name: rclone-migration-config
              key: core-bucket
        - name: HUBBLE_BUCKET
          valueFrom:
            configMapKeyRef:
              name: rclone-migration-config
              key: hubble-bucket
        # --- Tune these for production (1-4TB) ---
        # For a Kind test, keep conservative to avoid overwhelming the node
        - name: RCLONE_TRANSFERS
          value: "8"
        - name: RCLONE_CHECKERS
          value: "4"
        - name: RCLONE_S3_UPLOAD_CONCURRENCY
          value: "4"
        - name: RCLONE_S3_CHUNK_SIZE
          value: "16M"
        - name: RCLONE_BUFFER_SIZE
          value: "16M"
        resources:
          requests:
            cpu: 500m
            memory: 256Mi
          limits:
            cpu: "2"
            memory: 1Gi
        volumeMounts:
        - name: rclone-config
          mountPath: /config/rclone
          readOnly: true
        - name: scripts
          mountPath: /scripts
          readOnly: true
      volumes:
      - name: rclone-config
        configMap:
          name: rclone-migration-config
          items:
          - key: rclone.conf
            path: rclone.conf
      - name: scripts
        configMap:
          name: rclone-migration-config
          items:
          - key: migrate.sh
            path: migrate.sh
            mode: 0755
```

Apply the Job:

```shell
kubectl config set-context --current --namespace=fossa
kubectl apply -f rclone-migration-minio-seaweedfs.yaml
```
{% /step %}

{% step title="Follow the migration progress" %}
```shell
kubectl logs jobs/rclone-minio-to-seaweedfs --follow
```
{% /step %}

{% step title="Point your values file at SeaweedFS" %}
Update `fossa-core-config.yml` with the SeaweedFS endpoints, `iam.region`, and `iam.kind`:

```yaml
iam:
  region: seaweedfs
  kind: AccessKey

storage:
  forcePathStyle: true
  endpoint: http://core-seaweedfs-s3:8333
  bucket: fossa.test
  auth:
    type: AccessKey
    accessKey: seaweedfs
    secretKey: seaweedfs123

hubble:
  iam:
    region: seaweedfs
    kind: AccessKey

  storage:
    endpoint: http://hubble-seaweedfs-s3:8333
    bucket: hubble.fossa.test
    auth:
      type: AccessKey
      accessKey: seaweedfs
      secretKey: seaweedfs123
```
{% /step %}

{% step title="Cut over and disable maintenance mode" %}
Once the data migration completes, upgrade the deployment to use SeaweedFS and turn off maintenance mode:

```shell
helm upgrade -i fossa fossa/fossa-core --values fossa-core-config.yml --set global.maintenanceMode.enabled=false --version "^5.0.0"
```
{% /step %}

{% step title="Verify your data" %}
Log in to the console and confirm your data is still available.
{% /step %}

{% step title="Decommission MinIO" %}
After a week or two of healthy operation, delete the MinIO deployments:

```shell
helm delete fossa-core-minio
helm delete fossa-hubble-minio
```

If you're certain the MinIO data is no longer needed, delete its PVCs:

```shell
kubectl delete pvc fossa-core-minio
kubectl delete pvc fossa-hubble-minio
```
{% /step %}
{% /steps %}

---

Source: https://docs.fossa.com/docs/on-premises/maintenance/dependency-metadata-migration

# Dependency Metadata Migration

FOSSA is retiring a legacy dependency-metadata table (`DependencyLocks`) and moving all dependency-graph data into a newer storage service. This improves query performance and keeps dependency data consistent across the platform.

For on-premises instances, this rolls out across **two separate upgrades**:

1. A **backfill release** that copies all of your existing dependency data into the new storage.
2. A later **cleanup release** that removes the old table.

You must run the backfill release and wait for it to finish before installing the cleanup release.

{% callout type="warning" %}
Do not install the cleanup release until you have received the backfill completion email described in this guide. Removing the table before the backfill finishes can result in the loss of dependency details for scans that had not yet been migrated.
{% /callout %}

{% callout type="info" %}
Running the backfill preserves your historical dependency data. It copies the dependencies for every project revision on your instance into the new storage before the old table is removed, so you will not lose dependency details for any of your scans, no matter how old.
{% /callout %}

## The two releases

| Step | Helm chart version | What it does |
|------|--------------------|--------------|
| 1. Backfill | `7.0.0` | On deploy, automatically starts a background job that copies all dependency data into the new storage. |
| 2. Cleanup | `8.0.0` | Removes the legacy `DependencyLocks` table. Safe to install only after the backfill has completed. |

Install them in order. The two upgrades follow the standard [Upgrading FOSSA](/docs/on-premises/maintenance/upgrading-fossa) process; nothing about the upgrade mechanics changes.

## Before you begin

Confirm that at least one enabled super-user account on your instance has a valid, monitored email address. The backfill completion notification is sent to super users, and that email is your signal to proceed to the cleanup release.

## Running the migration

{% steps %}

{% step title="Upgrade to the backfill release" %}
Upgrade your instance to Helm chart version `7.0.0` using the standard [Upgrading FOSSA](/docs/on-premises/maintenance/upgrading-fossa) process.

The upgrade completes normally and does not require a maintenance window or downtime. When the new version starts, it automatically enqueues a background job that begins copying your dependency data into the new storage. The upgrade does not wait for this job to finish, so your deploy completes in the usual amount of time.
{% /step %}

{% step title="Let the backfill run" %}
The backfill runs entirely in the background on a low-priority queue and is paced deliberately so it does not compete with normal scanning and analysis. No action is required from you during this period, and FOSSA remains fully usable.

See [Timeline and impact](#timeline-and-impact) for how long to expect this to take.
{% /step %}

{% step title="Wait for the completion email" %}
When every dependency record has been copied successfully, FOSSA automatically emails all super-user accounts on your instance:

- **Subject:** `[FOSSA] Sparkle depgraph backfill complete`
- **Body:** confirmation that the dependency-graph backfill has finished and all export jobs have run.

This email is your signal that it is safe to continue. If you do not receive it, do not proceed. Contact FOSSA support instead.
{% /step %}

{% step title="Upgrade to the cleanup release" %}
Once you have received the completion email, upgrade to Helm chart version `8.0.0`. This release removes the legacy table. Because the data has already been migrated, this is a routine upgrade with no dependency-data impact.
{% /step %}

{% /steps %}

## Timeline and impact

### How long the backfill takes

The backfill is paced to protect instance performance rather than to finish as fast as possible. It processes roughly 500,000 to 600,000 project revisions per day, so completion time scales with the size of your instance:

| Approximate project revisions | Expected completion |
|-------------------------------|---------------------|
| Up to ~250,000 | Within a day |
| ~500,000 to ~1 million | 1 to 2 days |
| ~2 million | 3 to 4 days |
| 4 million or more | Up to ~7 to 10 days |

Most instances complete within a few days. Rather than tracking these estimates, treat the completion email as the definitive signal that the backfill is done.

### What you will see during the backfill

- **No downtime.** The application stays fully available throughout.
- **No maintenance window required** for the backfill itself.
- **Minimal load impact.** Work runs on a low-priority queue and is spread out over time, so normal scanning and analysis are not disrupted.
- **No user-facing changes** while the backfill runs. Dependency details continue to display as normal.

### After the cleanup release

Once the legacy table is removed, your dependency data continues to display as before. Because the backfill copies every project revision on your instance into the new storage, dependency details remain available for all of your scans, regardless of age. This includes original SBOMs from SBOM imports and any revisions referenced in a release group.

If any historical scan is ever found to be missing dependency details, re-running an analysis of that project restores them.

## Checking progress

The completion email is the definitive signal, and no monitoring is required. If you would like to watch progress in the meantime, the options below all give an approximate view of how much work remains.

{% callout type="warning" %}
These are progress indicators, not completion criteria. The backfill is done only when you receive the completion email. Do not proceed to the cleanup release based on these signals alone.
{% /callout %}

### Job-queue depth

The backfill runs as background jobs on FOSSA's `low-priority` job queue. While signed in as a **super user**, open the following on your instance:

```
https://YOUR-FOSSA-HOST/api/jobs/faktory
```

This returns a JSON snapshot of the background-job system. Two values track the remaining backfill work:

- `faktory.queues["low-priority"]`: jobs that are due to run now.
- `faktory.tasks.Scheduled.size`: jobs scheduled for a future time slot. The backfill deliberately spreads its work into future slots, so early on most pending work sits here.

Both counts trend toward zero as the backfill progresses. Because other routine jobs also share these queues, read the numbers as an approximate trend rather than an exact remaining count.

### Application logs

The pods that run FOSSA's background jobs log two milestones you can search for:

- **Enqueue complete** (logged near the start; reports the totals):

  ```
  Completed on-prem Sparkle depgraph sweep: enqueued <N> chunks (<M> revisions)
  ```

  Each chunk is up to 1,000 revisions, so this line tells you the total volume that will be processed.

- **Backfill complete** (the same event that sends the email):

  ```
  Sparkle depgraph backfill complete
  ```

For example:

```
kubectl -n NAMESPACE logs <core-worker-pod> | grep "Sparkle depgraph"
```

Adjust the namespace and pod name to match your installation.

### Faktory dashboard

If your deployment exposes the Faktory dashboard, you can watch the `low-priority` queue and the scheduled-jobs set drain there directly. The backfill appears as a batch named `Sparkle depgraph backfill`.

## Frequently asked questions

**Do I need to schedule downtime?**
No. Both upgrades are routine, and the backfill runs in the background with the application fully online.

**Can I keep using FOSSA while the backfill runs?**
Yes. All functionality remains available. Scanning, analysis, and dependency views work normally.

**What if the backfill is interrupted, for example by a restart during the run?**
The process is safe to re-run. Contact FOSSA support and we will help you re-trigger it. Re-running does not duplicate or corrupt data.

**What happens if I install the cleanup release too early?**
Do not do this. Installing the cleanup release before the backfill completes can result in the loss of dependency details for scans that had not yet been migrated. Always wait for the completion email.

**Who receives the completion email?**
Every enabled super-user account on your instance that has an email address configured.

## Need help?

If you have any questions or concerns, or if you do not receive the completion email within the expected window for your instance size, contact your Customer Success representative or [support@fossa.com](mailto:support@fossa.com).

---

Source: https://docs.fossa.com/docs/on-premises/maintenance/global-license-corrections

# Global License Corrections

Global License Corrections (GLC) let you override FOSSA's license detection results for a package at a **global scope**. The correction applies to every revision (version) of that component, not just the one you're looking at. This is useful when FOSSA's automated detection is consistently wrong for a package your organization relies on.

## Enabling Global License Corrections

To enable GLC, add the `globalLicenseCorrections` flag to the `enabledFeatureFlags` section of your Helm values for the org IDs that should have access, then apply the change (see [Updating Helm values](/docs/on-premises/maintenance/updating-helm-values)):

```yaml
enabledFeatureFlags:
  - globalLicenseCorrections
```

## How corrections are scoped

A GLC override is keyed to a **component locator** and applies to all revisions of that component. Locators uniquely identify a package and take the form:

```
<fetcher>+<package_spec>$<rev_spec>
```

| Part | Meaning | Example |
| --- | --- | --- |
| `fetcher` | The ecosystem the package comes from | `npm` |
| `package_spec` | The package name | `react` |
| `rev_spec` | The specific revision (version) | `16.2.0` |

For example, `npm+react$16.2.0` identifies React 16.2.0 from npm. Because corrections apply to all revisions of a component, the `rev_spec` is not required when supplying a locator for GLC.

### Finding a component locator

{% tabs %}
{% tab name="From the UI" %}
If your organization has the **Packages** product enabled, search for any package. The locator is shown beneath the package name.
{% /tab %}
{% tab name="From the API" %}
Open a project's **Dependencies** view with your browser network tab open, and look for the request named `dependencies?include_ignored=true&limit=750&offset=0`. Its response lists the component locators for every dependency in that project.
{% /tab %}
{% /tabs %}

## Applying a correction

{% steps %}
{% step title="Open the correction tool" %}
In the **Admin Dashboard**, scroll to **Update Licenses**.

{% img src="/images/on-premises/346d0de-Screen_Shot_2023-07-25_at_10.17.14_AM.png" alt="The Update Licenses section of the Admin Dashboard" /%}
{% /step %}

{% step title="Supply a component locator" %}
Enter the [component locator](#how-corrections-are-scoped) for the package you want to correct. FOSSA shows the licenses detected for that component along with their file matches.
{% /step %}

{% step title="Edit the detected licenses" %}
Select the **X** next to a file match or a license name to remove that file match, or to remove the license from the component entirely.
{% /step %}

{% step title="Add a license" %}
Select **Add License** at the bottom left. Search for an existing license, or add a custom one by searching for `custom-license`. After choosing the license and entering any applicable raw license text and copyright headers, select **Add**.
{% /step %}
{% /steps %}

{% callout type="danger" %}
Editing licenses here changes the detected licenses for **all revisions (versions)** of the component, regardless of which revision is currently displayed.
{% /callout %}

## Reverting a correction

Any change (adding a license, removing a file match, or removing a license) can be undone. Where the **X** icon was, you'll find a **Revert this override** action.

---

Source: https://docs.fossa.com/docs/on-premises/maintenance/vulnerability-database-updates

# On-Prem Vulnerability Database Updates

When FOSSA runs on-premises, its vulnerability database lives in your own environment. The over-the-air (OTA) updater keeps that database current by periodically pulling the latest data from FOSSA's vulnerability feed at `vulns.fossa.com`. This page explains how the updater works and how to enable and monitor it.

{% callout type="warning" %}
The updater authenticates to the feed with a **Vulnerability Service API token** (a token ID and secret), which is separate from your main FOSSA API token. See [Vulnerability Service API Token Provisioning](/docs/vulnerabilities/vulnerability-service-api-token-provisioning) to request one.
{% /callout %}

## How the updater works

- The updater runs inside your cluster as a Kubernetes **CronJob** (`onprem-vulns-updater`).
- It polls FOSSA's vulnerability feed **once per hour**, but only downloads a new snapshot when FOSSA has published new data, so most runs are no-ops. FOSSA publishes new data roughly daily.
- Enabling the updater also turns on the **Security product** in your installation and runs a vulnerability database migration as part of your next Helm upgrade.
- The updater only pulls vulnerability intelligence *into* your instance; your proprietary code and scan results never leave your network. See the [Architecture Overview](/docs/on-premises/architecture-overview) for how outbound connections are scoped.

## Enabling OTA updates

{% steps %}
{% step title="Locate the vulns configuration" %}
In your Helm values, the vulnerability updater is disabled by default:

```yaml
vulns:
  # URL of the FOSSA Vulns update service.
  host: https://vulns.fossa.com

  # Provided by FOSSA to authenticate your installation to the update service.
  auth:
    id: ""
    secret: ""

  updater:
    enabled: false
```
{% /step %}
{% step title="Add your credentials and enable the updater" %}
Set `updater.enabled` to `true` and fill in the token ID and secret provisioned by FOSSA:

```yaml
vulns:
  host: https://vulns.fossa.com

  auth:
    id: "<provisioned key ID>"
    secret: "<provisioned key secret>"

  updater:
    enabled: true
```

{% callout type="warning" %}
`host` and `auth` sit directly under `vulns:`, **not** nested inside `updater:`. The updater requires `vulns.auth.id` and `vulns.auth.secret` to be set.
{% /callout %}
{% /step %}
{% step title="Apply the change" %}
Run `helm upgrade` to apply the updated values. The updater runs on a schedule, so it may not run immediately, the first update typically lands within an hour.
{% /step %}
{% /steps %}

## Monitoring updates

Once enabled, the updater runs unattended; no further action is needed. To confirm updates are landing, check the status of the `onprem-vulns-updater` CronJob, or query the database for the time elapsed since the last successful update:

```sql
SELECT (now() - (SELECT "createdAt" FROM "VulnMigrations" ORDER BY id DESC LIMIT 1))
-- example: 0 years 0 mons 0 days 4 hours 23 mins 9.114582 secs
```

## Required network egress

If your cluster sits behind a firewall, allow outbound access to FOSSA's vulnerability feed and its file storage. See [IP Space Allowlisting](/docs/on-premises/ip-space-allowlisting) for the exact hosts and IP ranges.

## FAQ

**How often does the updater run?**
It polls hourly, but only downloads data when FOSSA has published a new snapshot, so you'll typically see roughly one new update per day.

**Can I update vulnerabilities in an air-gapped environment?**
If your installation cannot reach `vulns.fossa.com`, you can pull the dataset manually instead. See [Vulnerability Snapshot Downloads](/docs/vulnerabilities/vulnerability-snapshot), and ask your FOSSA account team about an offline import path.

**Do I need to enable anything else to use vulnerability data?**
No. Enabling the updater automatically turns on the Security product in your installation.

---

Source: https://docs.fossa.com/docs/on-premises/maintenance/bitnami-image-pull-errors

# Bitnami image pull errors

Bitnami has discontinued publishing image tags for several of the Helm chart dependencies FOSSA historically relied on. When a tag your chart references is no longer available, the affected pods fail to start with `ErrImagePull` or `ImagePullBackOff`.

FOSSA maintains mirrored copies of these images so you can keep running. Use the fixes below as a short-term bridge; the long-term solution is to upgrade to a fossa-core version that pulls images from FOSSA's `quay.io/fossa` registry.

## ErrImagePull / ImagePullBackOff on `bitnami/postgresql`, `bitnami/postgresql-exporter`, or `bitnami/os-shell`

**Cause:** Bitnami stopped publishing the Postgres image tags referenced by the chart's database dependencies.

**Fix:** Point the existing Bitnami Postgres chart at FOSSA's mirrored images on `quay.io`. Run the matching command for each database you deploy:

```shell
# Core database
helm upgrade -i fossa-core-db oci://registry-1.docker.io/bitnamicharts/postgresql --set global.security.allowInsecureImages=true --set global.imageRegistry=quay.io --set image.repository=fossa/postgres --set volumePermissions.image.repository=fossa/os-shell --set metrics.image.repository=fossa/postgres-exporter --version 16.4.7 -n fossa --reuse-values

# Sparkle database
helm upgrade -i fossa-sparkle-db oci://registry-1.docker.io/bitnamicharts/postgresql --set global.security.allowInsecureImages=true --set global.imageRegistry=quay.io --set image.repository=fossa/postgres --set volumePermissions.image.repository=fossa/os-shell --set metrics.image.repository=fossa/postgres-exporter --version 16.4.7 -n fossa --reuse-values

# Hubble database
helm upgrade -i fossa-hubble-db oci://registry-1.docker.io/bitnamicharts/postgresql --set global.security.allowInsecureImages=true --set global.imageRegistry=quay.io --set image.repository=fossa/postgres --set volumePermissions.image.repository=fossa/os-shell --set metrics.image.repository=fossa/postgres-exporter --version 16.4.7 -n fossa --reuse-values
```

## ErrImagePull / ImagePullBackOff on `bitnami/redis`, `bitnami/redis-exporter`, `bitnami/os-shell`, or `bitnami/minio`

**Cause:** Bitnami stopped publishing the Redis and MinIO image tags referenced by the chart.

{% callout type="info" %}
This fix is a short-term bridge for customers still on fossa-core `3.0.6` who haven't yet upgraded to `4.X.X`.
{% /callout %}

**Fix:** Point Redis and MinIO at the `bitnamilegacy` images. Ideally make these changes in your values file:

- **Core MinIO**: `storage.image.repository: bitnamilegacy/minio`, `storage.image.tag: 2020.6.3`, `storage.image.registry: docker.io`
- **Core Redis**: `redis.image.repository: bitnamilegacy/redis`, `redis.image.tag: 6.2.9`, `redis.image.registry: docker.io`
- **Hubble MinIO**: `hubble.storage.image.repository: bitnamilegacy/minio`, `hubble.storage.image.tag: 2020.6.3`, `hubble.storage.image.registry: docker.io`

In a pinch, you can apply the same overrides directly on the command line:

```shell
helm upgrade -i fossa fossa/fossa-core --reuse-values --set storage.image.repository=bitnamilegacy/minio --set storage.image.tag=2020.6.3 --set storage.image.registry=docker.io --set redis.image.repository=bitnamilegacy/redis --set redis.image.tag=6.2.9 --set redis.image.registry=docker.io --set hubble.storage.image.repository=bitnamilegacy/minio --set hubble.storage.image.tag=2020.6.3 --set hubble.storage.image.registry=docker.io --version=3.0.3
```

## Long-term solution

These mirrored-image workarounds keep an existing chart running, but they're not a permanent fix. We strongly recommend upgrading to **fossa-core `4.4.1`+**, which pulls images from FOSSA's `quay.io/fossa` registry rather than depending on Bitnami tags. See [Upgrading FOSSA](/docs/on-premises/maintenance/upgrading-fossa).

## Still stuck?

If pods continue to fail to pull images after applying these changes, collect a [debug bundle](/docs/on-premises/maintenance/debug-bundle) and share it with FOSSA support.

---

Source: https://docs.fossa.com/docs/on-premises/maintenance/debug-bundle

# On-Premises Debug Bundle

When you hit a problem with an on-premises FOSSA deployment, support will often ask for a *debug bundle*: a ZIP file containing information about your FOSSA application and the Kubernetes cluster it runs in. Generating one is a cluster-operator task. Enable it in your Helm values, let it collect, then copy the result off the pod and send it in.

The `debugBundle` deployment has shipped with the `fossa/fossa-core` chart since chart version **2.6.0**. You generally won't need it unless FOSSA support asks.

{% callout type="info" %}
Two different things are called a "debug bundle." This page covers the **on-premises cluster bundle**, which captures the state of your FOSSA deployment. If you're diagnosing a problem with a `fossa analyze` scan instead, you want the **CLI debug bundle** (`fossa.debug.json.gz`). See [Debugging the FOSSA CLI](/docs/cli/references/debugging).
{% /callout %}

## What the bundle collects

The bundle is an exact snapshot of your release and cluster, written to a temporary directory on the debug-bundle pod. It includes:

- **Application configuration**: `FOSSAConfigs`, `FeatureFlags`, and `SequelizeMeta` tables.
- **Build data**: recent `Builds`, and the related `Tasks`, `Revisions`, and `DependencyLocks`.
- **Cluster state**: pods (with per-container logs), services, deployments, statefulsets, daemonsets, jobs, cronjobs, config maps, events, persistent volumes and claims, and the rendered Helm release values and manifest.
- **Node diagnostics**: nodes and node leases, *only* when cluster-role access is granted (see below).
- **Endpoint connectivity**: reachability checks to the external hosts FOSSA depends on (for example `app.fossa.com`, `vulns.fossa.com`, `pypi.org`, and `s3.amazonaws.com`).

Because this is a faithful copy of your cluster, the bundle can contain secrets. You'll redact those before sending. See [Redact and send the bundle](#generating-the-bundle).

## Generating the bundle

{% steps %}

{% step title="Enable the debug bundle" %}
Set `deployment.debugBundle.enabled: true` in your `fossa/fossa-core` values:

```yaml
deployment:
  debugBundle:
    enabled: true
```

If you have permission to create cluster roles, also set `createClusterRole: true`. This lets the bundle collect diagnostics about your cluster's compute nodes, which helps FOSSA diagnose hardware-provisioning and performance issues:

```yaml
deployment:
  debugBundle:
    enabled: true
    createClusterRole: true
```

Both values default to `false`.

{% callout type="warning" %}
If the bundle logs errors about being unable to retrieve information about nodes and node leases, you most likely left `deployment.debugBundle.createClusterRole` at its default of `false`. The bundle is still useful without node data; it just won't include diagnostics about your underlying compute nodes.
{% /callout %}
{% /step %}

{% step title="Apply the new Helm values" %}
Apply the values the same way you apply any update, for most operators that's `helm upgrade`:

```bash
helm upgrade RELEASE_NAME fossa/fossa-core --values NEW_VALUES_FILE
```

Once the upgrade completes, you should see a `RELEASE_NAME-fossa-core-debug-bundle` deployment with a single pod:

```bash
$ kubectl get deployments
NAME                                   READY   UP-TO-DATE   AVAILABLE   AGE
RELEASE_NAME-fossa-core-debug-bundle   1/1     1            1           24h

$ kubectl get pods
NAME                                                    READY   STATUS    RESTARTS   AGE
RELEASE_NAME-fossa-core-debug-bundle-85bdd985d9-c8hm4   1/1     Running   0          71m
```

{% callout type="tip" %}
The deployment already exists at `0` replicas. Instead of editing values, you can scale it up directly, then pick up at the next step:

```bash
kubectl scale deployment RELEASE_NAME-fossa-core-debug-bundle --replicas=1
```
{% /callout %}
{% /step %}

{% step title="Wait for collection to finish" %}
Once the pod is running, follow its logs:

```bash
kubectl logs -f -l app.kubernetes.io/component=debug-bundle
```

When collection finishes, the pod prints a completion message and a ready-to-run copy command, then exits about an hour later (removing the collected data with it):

```
[INFO] Collection of data is complete, this process will exit in an hour and data will be removed.
[INFO] Use kubectl to copy the data: kubectl cp RELEASE_NAME-fossa-core-debug-bundle-85bdd985d9-c8hm4:/tmp/debug_167969928 LOCAL_DEBUG_BUNDLE_LOCATION
[WARN] Information collected may contain secrets, please parse output and remove secrets.
```

Copy the command from your own log output, the pod name and temp directory are unique to your run, and the command includes a `--namespace` flag when your release sets one.
{% /step %}

{% step title="Copy the bundle off the pod" %}
Run the `kubectl cp` command from the log output, replacing `LOCAL_DEBUG_BUNDLE_LOCATION` with a path on your machine:

```bash
kubectl cp RELEASE_NAME-fossa-core-debug-bundle-85bdd985d9-c8hm4:/tmp/debug_167969928 ./fossa-debug-bundle
```

The contents of that folder are the debug bundle.
{% /step %}

{% step title="Redact and send the bundle" %}
The bundle reproduces your cluster's state and may contain any secrets present in your Kubernetes manifests. Review and redact before sending. The most common places secrets appear:

| File | What to check |
| --- | --- |
| `values_sh.*.json` | Passwords in the saved Helm values |
| `manifest_sh.*.yaml` | Passwords in the rendered Kubernetes manifests |
| `config_maps.json` | Passwords in the `ConfigMap` dump |

{% callout type="warning" %}
Depending on your cluster's configuration, secrets may appear elsewhere too. Treat the table above as a starting point, not a complete inventory.
{% /callout %}

Once you've redacted it, ZIP up the folder and attach it to your support email or ticket.
{% /step %}

{% /steps %}

---

Source: https://docs.fossa.com/docs/help

# Help & Support

Stuck on something? This is where to find answers and reach a human.

## Get support

- **Email**: [support@fossa.com](mailto:support@fossa.com). Let us know what you ran into and we'll help.
- **Support site**: [support.fossa.com](https://support.fossa.com) for in-app help and ticketing. We're generally available during business hours (Pacific Time).
- **Enterprise support & SLAs**: professional support options are included with FOSSA Enterprise plans. Contact [sales@fossa.com](mailto:sales@fossa.com) to learn more.
- **Reporting a security vulnerability**: follow the [Responsible Disclosure Policy](/docs/legal/responsible-disclosure-policy).

## Troubleshooting

- **[Generate a debug bundle](/docs/help/cli-debug-bundle)**: capture CLI logs to attach to a support ticket.
- **[Fixing incorrect dependency data](/docs/help/faq#troubleshooting)**: reanalyze and correct wrong license or copyright data.
- **[License Conclusions vs. License Corrections](/docs/help/license-conclusions-vs-corrections)**: which tool to use when a dependency's license looks wrong.

## FAQ

Quick answers to the questions we hear most, see the **[FAQ](/docs/help/faq)**, which covers:

- **[Account & organization](/docs/help/faq#account-and-organization)**: moving a user between orgs, deleting an account or org.
- **[Data & storage](/docs/help/faq#data-and-storage)**: what FOSSA stores and how long it's retained.
- **[Analysis](/docs/help/faq#analysis)**: what the CLI uploads, static vs dynamic, supported languages.

For deployment-specific issues, start with [On-Premises](/docs/on-premises).

---

Source: https://docs.fossa.com/docs/help/faq

# FAQ

## General

**Why is FOSSA always capitalized?**
It's an acronym: **F**ree and **O**pen **S**ource **S**oftware **A**nalysis.

**Does FOSSA have a free plan?**
Yes, up to 5 public or private repositories, with continuous dependency tracking and license checks. The open-source [`fossa-cli`](https://github.com/fossas/fossa-cli) is also free to run locally (without CI or automated updates).

**Do you discount non-commercial projects?**
We offer plans for non-profits, educational institutions, and open source projects. [Get in touch](mailto:support@fossa.com).

**Do you offer annual plans?**
Yes, and on-prem deployments are priced annually by default. Contact us for details.

## Pricing

**How does code-contributor pricing work?**
FOSSA tracks unique committers to private repos actively running in FOSSA, with no limit on repository count, so you can start small and scale across your org. Contact us about contributors outside your staff.

## Analysis

**Does the FOSSA CLI send my code to the FOSSA server?**
No. The CLI queries your package managers for installed dependencies and sends only that **dependency metadata**, not your source code. Run `fossa analyze -o` to see exactly what's uploaded. See [What data gets uploaded](/docs/cli/walkthroughs/what-data-gets-uploaded).

**Why is dynamic build analysis important?**
Static strategies parse files (like a `package-lock.json`) to build a dependency graph. Dynamic strategies run a build command or plugin (required for package managers without complete lockfiles, e.g. Gradle, Go) and give more accurate results. See [CLI vs Quick Import](/docs/get-started/cli-vs-quick-import).

**Which languages does FOSSA support?**
See [Supported Languages](/docs/project-setup/supported-languages) for the full list of languages and build tools.

## Account and organization

**Inviting a user fails because they're already in another organization: what do I do?**
This usually happens when the user previously signed in via SSO but your org only supports email/password sign-in. Have an **organization admin** [contact support](https://support.fossa.com/) or email [support@fossa.com](mailto:support@fossa.com), CC'ing the user, to request a transfer; it's typically resolved the same day. Afterward, confirm the move on the [Users](https://app.fossa.com/account/settings/organization/users) page and check the user's permissions.

**How do I delete my account or organization?**
Email [support@fossa.com](mailto:support@fossa.com) from the email tied to your FOSSA account. Deleting an **organization** requires an administrator. If you're not one, have your admin request it (or CC an admin so we can confirm the request). Include your organization's name or OrgID for an org deletion.

## Data and storage

**What does FOSSA store in object storage?**
FOSSA keeps files that contain **licenses or copyright headers**, from your first-party code (via CLI vendored/first-party scans with Full-File Upload, or Quick Import archive/repo scans) and from dependencies (public and configured private registries).

{% callout type="warning" %}
Archive Upload and Full-File Upload are **opt-in**. If proprietary data is uploaded by mistake, or you want data deleted, contact [support](https://support.fossa.com) as soon as possible.
{% /callout %}

**How long is data retained?**

- Quick-imported archives and (with Full-File Upload) vendored dependencies are stored in S3 in their entirety for **30 days**.
- Files **without** a license match are never stored; they're used in temporary directories during analysis and deleted immediately after.
- Files **with** a license match are retained indefinitely unless you request deletion; end users can access them by viewing a project's license matches.
- On-prem retention timelines may differ, but the same conditions apply; ask your Customer Success Engineer.

## Troubleshooting

**A dependency's license or copyright data looks wrong: how do I fix it?**
Always **reanalyze** the dependency first; this clears the cache and re-runs the latest license scanner.

{% steps %}
{% step title="Open the dependency" %}
On your project's **Dependencies** tab, find the dependency, click the **⋯** menu, and select **Edit Package**.

{% img src="/images/help/48a290f-docs1-edit-package.png" alt="Opening the Edit Package menu for a dependency" /%}
{% /step %}
{% step title="Reanalyze" %}
In the **Edit Package** modal, click **Reanalyze** (top right), then wait 4–5 minutes and refresh. Hover **Reanalyze** again to confirm the date updated.

{% img src="/images/help/35a21eb-docs2-reanalyze.png" alt="The Reanalyze button in the Edit Package modal" /%}
{% /step %}
{% /steps %}

If reanalysis doesn't fix it, correct the data in the **Edit Package** modal (**Save Changes**). For a wrong license specifically, see [license mis-detection](/docs/licenses). Still stuck? Open a ticket at [support.fossa.com](https://support.fossa.com).

**Why does a dependency show "0 Files Matched"?**
This appears when a dependency has a **declared** license (the license the author specified for their work) but no **discovered** one (a license FOSSA found by scanning a file). With no discovered match there's no file to show, but FOSSA still surfaces the declared license.

{% img src="/images/help/c887e19-image.png" alt="A dependency showing 0 Files for its license file matches" /%}

You can filter by declared vs. discovered on the Issues tab. This also shows up when a license was added via **Global License Corrections**, since that adds a license without an associated file. If your file matches still look wrong, reach out to [support@fossa.com](mailto:support@fossa.com).

---

Source: https://docs.fossa.com/docs/help/cli-debug-bundle

# Generate a debug bundle

If a project scan fails through the FOSSA CLI, send a debug bundle to [support@fossa.com](mailto:support@fossa.com) (and/or your Customer Success team). It's the fastest way for us to diagnose the issue.

## FOSSA CLI v3.13.0 and later

The bundle is a single `fossa.debug.zip` containing:

- `fossa.debug.json`
- `fossa.telemetry.json`
- `Ficus` debug logs (when snippet scanning is enabled)

This single-file format simplifies collection, especially for snippet scans.

## Prior to v3.13.0

Run `fossa analyze` with the `--debug` flag:

```bash
fossa analyze --debug
```

This writes `fossa.debug.json.gz` (and a `fossa.telemetry.json`) to the directory where the CLI ran. Send both along with your support request.

---

Source: https://docs.fossa.com/docs/help/why-cicd-integration

# Why CI/CD Integration Delivers the Best Results

To get the most accurate and complete picture of your software's open source components, FOSSA works best when integrated into your **CI/CD pipeline**, the stage where your application is built.

During the build process, FOSSA can access and run the same package managers (such as npm, Maven, or pip) that your application uses to pull in dependencies. This lets it build a complete and precise dependency map (including both direct and indirect (transitive) components) based on what is actually resolved in the build.

This approach is called the **dynamic strategy**: FOSSA dynamically runs package manager commands to discover the exact set of dependencies in use.

By contrast, when FOSSA runs only through a source control (SCM) integration like GitHub, it relies on reading static manifest files in the repository (such as `package-lock.json` or `requirements.txt`) and inferring the dependency graph, because it cannot run the build or package manager commands. This static approach still provides valuable insights, but it may miss details, especially when:

- lock files are missing or outdated
- custom or nonstandard build steps are involved
- dependencies are generated dynamically at build time

Dynamic strategies run only in the FOSSA CLI, and they allow FOSSA to:

- Run package managers (npm, Maven, pip, etc.) directly
- Detect *all* dependencies, including indirect (transitive) ones
- Reflect the exact components that will ship in production

FOSSA supports different analysis strategies for different languages. For details on how the CLI discovers and analyzes dependencies, see the [FOSSA CLI documentation](/docs/cli) and [CLI scanning](/docs/project-setup/cli).

## Static vs. dynamic strategy: an analogy

Think of it this way:

- **Dynamic strategy** (used in the CLI and CI/CD integration) is like looking inside a fully baked cake to see exactly which ingredients were used, based on what the kitchen (your build process) actually mixed and baked. FOSSA runs the package managers and sees exactly which dependencies were pulled in, giving you a precise, real-world picture of what is in your software.
- **Static strategy** (used in SCM integrations like GitHub) is like reading a recipe on paper and guessing what went into the cake based only on the listed ingredients, without watching what the kitchen actually did. FOSSA reads files in your repository to infer dependencies, but if those files are missing, outdated, or incomplete, the results can be less reliable.

By plugging FOSSA into your CI/CD pipeline, you let it run the dynamic strategy (for supported languages) and see the full picture, helping you catch all licenses, security issues, and hidden components with confidence.

## Benefits of CI/CD integration

- Most accurate dependency graph
- Stronger license and security risk insights
- Less manual effort and fewer surprises downstream

## Summary

For the most accurate and comprehensive scan results, we recommend running FOSSA inside your CI/CD pipeline. This gives your team the most complete and actionable results, helping you meet compliance and security goals with confidence.

---

Source: https://docs.fossa.com/docs/help/incomplete-dependencies

# Incomplete and Unknown Dependencies

When FOSSA cannot locate or resolve a dependency during analysis, it appears in **Inventory → Dependencies** with a status of **Unknown** or **Failed**. There are three ways to address this:

- **Add authentication**: if the dependency is hosted in a private registry, configure credentials so FOSSA can access it
- **Overwrite**: replace the unresolved entry with a manually specified version
- **Add**: introduce a net-new dependency that FOSSA didn't detect automatically

## Adding authentication for a private registry

If the dependency is hosted in a private registry such as Artifactory or Nexus, FOSSA can't access it without credentials. Open the three-dot action menu on the dependency and select **Add authentication**. This navigates you directly to the language settings page where you can configure access for the relevant ecosystem.

Once credentials are saved, trigger a new analysis for the data to populate.

## Overwriting an unknown dependency

Use this when FOSSA found the dependency in your manifest but couldn't resolve it, for example, because it's in a private registry or has an incorrectly formatted locator.

{% img src="/images/help/e78fda5edd39c30642abf343203eb750255e7d44dfc21e2c02555ca72f940e9e-image.png" alt="Dependencies list showing a dependency with Unknown status" /%}

{% steps %}
{% step title="Open the action menu" %}
Find the Unknown dependency in **Inventory → Dependencies**. Open its action menu and select **Overwrite package**.
{% /step %}

{% step title="Fill in the dependency details" %}
The **Overwrite Dependency** dialog gives you three options:

- **Search**: find the package in FOSSA's database
- **Upload**: upload a package binary
- **Create**: manually enter the package name, version, description, and homepage

Copy the description and homepage if available; this metadata will be visible in the FOSSA web app and may be useful later.

{% img src="/images/help/a1c0f45-Incomplete_Dependencies_01_Example.png" alt="Overwrite Dependency modal with fields for package details" /%}
{% /step %}

{% step title="Submit" %}
Click **Overwrite**. The modal closes and the project re-queues for analysis.

{% img src="/images/help/4b715bf-Incomplete_Dependencies_03_Queued.png" alt="Project status showing build queued after overwrite" /%}
{% /step %}

{% step title="Verify" %}
Once analysis completes, the overwritten dependency moves to the top of the dependencies list and is tagged **Manual Dependency**.

{% img src="/images/help/869ade7-Incomplete_Dependencies_05_Manual_Dependencies.png" alt="Dependencies list showing the resolved dependency tagged as Manual Dependency" /%}
{% /step %}
{% /steps %}

## Adding a new dependency

Use this when FOSSA didn't detect a dependency at all and you need to add it manually, for example, a statically bundled library with no manifest entry.

{% steps %}
{% step title="Open the Add Dependency dialog" %}
At the top of **Inventory → Dependencies**, click **Add Dependency**.

{% img src="/images/help/3146eca-Incomplete_Dependencies_06_Add_Dependency.png" alt="Add Dependency button at the top of the dependencies view" /%}
{% /step %}

{% step title="Fill in the dependency details" %}
The **Add Dependency** dialog gives you three options:

- **Search**: find the package in FOSSA's database
- **Upload**: upload a package binary
- **Create**: manually enter the package name, version, description, and homepage
{% /step %}

{% step title="Submit" %}
Click **Add**. The page reloads and the new dependency appears in the list alongside any existing entries.

{% img src="/images/help/29ce0d4-Incomplete_Dependencies_09_Full_View.png" alt="Dependencies list after adding the new dependency, showing both the added entry and the original unknown entry" /%}
{% /step %}
{% /steps %}

{% callout type="info" %}
If you're still seeing Unknown dependencies after overwriting or adding, contact [support@fossa.com](mailto:support@fossa.com) with your project locator and the affected dependency names.
{% /callout %}

---

Source: https://docs.fossa.com/docs/help/license-conclusions-vs-corrections

# License Conclusions vs. License Corrections

FOSSA gives you two distinct tools for getting a dependency's license right, and they're easy to mix up because both touch the **Licenses** tab of the dependency drawer. They solve different problems:

- A **[License Conclusion](/docs/licenses/license-conclusions)** picks the single dominant license from the data FOSSA *already detected*. It doesn't change the underlying detected data; it decides which of the detected licenses wins.
- A **[License Correction](/docs/licenses/license-corrections)** changes the detected data itself: adding, changing, or removing a license when FOSSA got it wrong.

In short: **conclude** when the detected data is right but you need one authoritative answer; **correct** when the detected data is wrong.

## At a glance

| | License Conclusion | License Correction |
|---|---|---|
| **Question it answers** | "Which of the detected licenses is the dominant one?" | "What is the dependency's license, really?" |
| **Acts on** | A choice *among* declared and discovered licenses | The detected license data itself |
| **Origin** | Auto-computed during analysis (optionally overridden by hand) | Always a manual edit |
| **Default behavior** | Disabled until enabled at the org level | Always available |
| **Scope** | Per dependency version, with optional scoping (org → project → revision) | Org-wide for that dependency, across every project and every version |
| **Drives policy?** | Yes, has dedicated policy settings | Indirectly, corrected data is what policy evaluates |
| **Surfaced in SBOMs** | As `PackageLicenseConcluded` (SPDX) | As the dependency's license data |

## What a License Conclusion does

FOSSA detects licenses two ways: **Declared** licenses from package manifests and **Discovered** licenses from scanning source code. A dependency can carry several of each. A **conclusion** combines those inputs into a single authoritative license that drives policy evaluation and attribution, mirroring the `PackageLicenseConcluded` field in SPDX.

Conclusions are generated automatically during analysis. When the inputs are unambiguous (exactly one declared, or exactly one discovered) FOSSA concludes to that license; when they conflict or are missing, FOSSA either resolves a dominant license, concludes multiple licenses with `AND`, or leaves the dependency **Unconcluded** for review. You can also override the automated result by hand with **Conclude** / **Unconclude**.

Because a conclusion is a *decision layer* on top of detected data, it has its own [policy settings](/docs/licenses/license-conclusions#policy-settings) (for example, *Only create issues for Concluded Licenses* and *Intelligent Auto-Ignore*) and must be [enabled at the organization level](/docs/licenses/license-conclusions#enabling-license-conclusion) before it appears in projects.

{% callout type="info" %}
A conclusion never edits the Declared or Discovered data underneath it. Unconcluding a dependency simply returns to FOSSA's automated result; the original detected licenses are still there.
{% /callout %}

## What a License Correction does

A **correction** fixes the detected data when it's wrong: FOSSA found no license and you know what it should be, or it detected a false positive (for example, a license name picked up from a code comment). You [add, change, or remove](/docs/licenses/license-corrections) the license directly.

Corrections are **org-wide**. Editing a dependency applies the change to every project and every version of that dependency across your organization; fix it once and it takes effect everywhere. This is why corrections require an appropriate organization-level role.

{% callout type="warning" %}
Unlike a conclusion, which you can scope to a single project or revision, a correction always applies to the dependency everywhere it appears in your organization. Use it for facts that are universally true about the package, not project-specific preferences.
{% /callout %}

## How they interact

Corrections and conclusions are not independent; **a correction feeds into the conclusion**, but not the other way around:

- When you correct a dependency's licenses, FOSSA re-runs the conclusion against the corrected data and reconciles any existing conclusions. If a correction removes a license, that license is also dropped from any conclusion that referenced it.
- Concluding or unconcluding a license never alters the corrected or detected data. Conclusions are stored separately from the dependency's license records.

So the pipeline reads **detected data → (optional correction) → conclusion → policy evaluation**. Correct first when the raw data is wrong; conclude (or let FOSSA conclude) to choose the dominant license from whatever data remains.

## Which one should I use?

| If you want to… | Use |
|---|---|
| Choose one dominant license among several FOSSA correctly detected | **Conclusion** |
| Reduce issue noise so only the dominant license generates issues | **Conclusion** (policy settings) |
| Flag dependencies FOSSA couldn't resolve to a single license | **Conclusion** (*Create issues when a license can't be concluded*) |
| Add a license FOSSA missed entirely | **Correction** |
| Remove a license FOSSA detected by mistake | **Correction** |
| Replace a wrong license with the correct one for the whole org | **Correction** |
| Apply a license decision to just one project, not the whole org | **Conclusion** (scoped) |

{% callout type="info" %}
Still seeing the wrong license after concluding? Check whether the detected data itself is wrong; a conclusion can only choose among what FOSSA detected, so a bad detection needs a **correction** first. For anything you can't resolve, contact [support@fossa.com](mailto:support@fossa.com) with your project locator and the affected dependency.
{% /callout %}

---

Source: https://docs.fossa.com/docs/help/dependencylocks-deprecation

# Dependency Metadata Table Sunset

To optimize the performance and efficiency of all FOSSA environments, we are initiating a database migration to retire a legacy dependency metadata table. This update will reduce system bottlenecks and improve overall query response times, enabling a more responsive user experience.

What this means for you:
- Benefits
  - Performance Optimization
  - Data Consistency across platform 

- Changes 
  - Any project revisions last analyzed before May 2025 will no longer display dependency details. To restore visibility for these historical projects, simply [trigger a re-analysis](/docs/project-setup).

- Unchanged
  - This change only impacts dependency details for these older scans. The following project metadata remains unchanged and will continue to persist indefinitely  
  - Project revisions analyzed after May 2025
  - All original SBOMs from SBOM imports 
  - Any project revisions before May 2025 that are referenced in any release group 


We will make this change by August 31st 2026. We have analyzed our customer base and the vast majority of customers will see zero impact to dependency metadata as a result of this change. If you have any concerns please reach out to your Customer Success contact or support@fossa.com. Thank you for your continued partnership and we look forward to the improved performance and data consistency on the back half of this change.

---

Source: https://docs.fossa.com/docs/legal

# Legal

The legal agreements and policies that govern your use of FOSSA.

## Terms

- **[Terms of Service](/docs/legal/terms-of-service):** the agreement governing use of FOSSA's products.
- **[Enterprise Terms of Service](/docs/legal/enterprise-terms-of-service):** terms for enterprise and on-premises customers.
- **[Acceptable Use Policy](/docs/legal/acceptable-use-policy):** what's permitted when using FOSSA.

## Privacy & security

- **[Privacy Policy](/docs/legal/privacy-policy):** how FOSSA collects, uses, and protects data.
- **[Security](/docs/legal/security):** FOSSA's security practices and posture.
- **[Responsible Disclosure Policy](/docs/legal/responsible-disclosure-policy):** how to report a security vulnerability to FOSSA.
- **[DMCA Notice](/docs/legal/dmca-notice):** copyright takedown procedures.

---

Source: https://docs.fossa.com/docs/legal/terms-of-service

# Terms of Service

These Terms of Service (“Terms”) are provided by FOSSA, Inc. (“FOSSA,” “we,” “our,” or “us”) and govern your use of our websites located at [https://fossa.com](https://fossa.com), [https://fossa.io](https://fossa.io), and [https://bot.fossa.com](https://bot.fossa.com) and the software we make available to you and other users (collectively, the “Service”). To use the Service, Users must at all times agree to and abide by these Terms. The Service allows you to automatically analyze your code and certain other information related to your organization and your code (such code and information, collectively, “User Data”).

FOSSA provides a software platform designed to analyze you or your organization’s code for compliance with open source licenses. That is, our Service produces insights about the open source code used by your developers and teams and provides simple and effective intelligence to leverage the open source code effectively. Other parts of our Service use large language models to analyze your organization’s code and automatically detect and fix code issues.

Our Service may be made available on a hosted and/or on-premises basis, as set forth in the applicable order form, or otherwise mutually agreed in writing, with FOSSA or its authorized resellers. In all cases, your usage of the Service will be subject to these Terms. In addition, certain portions of these Terms will apply only to those Users who have purchased a license to use certain features of the Service that are made available to Users subject to such Users’ payment of additional fees (the “Premium Features”).

These Terms of Service constitute a legal contract between you and your company, organization, or entity (“you” or, collectively with other users, “Users”), on the one hand, and FOSSA on the other regarding your and your company, organization, or entity’s use of the Service. FOSSA may have different roles with respect to different types of Users, and “you” as used in these Terms will apply to the appropriate type of User under the circumstances (e.g., an individual User and/or a Subscribing Organization). If you are using or opening an account with FOSSA on behalf of a company, entity, or organization (collectively, the “Subscribing Organization”) then you represent and warrant that you: (i) are an authorized representative of that entity with the authority to bind such entity to these Terms; (ii) have read these Terms; (iii) understand these Terms, and (iv) agree to these Terms on behalf of such Subscribing Organization.

Please read carefully the following terms and conditions. By registering for and/or using or subscribing to the Service, or by clicking “I Agree,” or otherwise affirmatively manifesting your intent to be bound by these Terms of Service, you signify that you have read, understood, and agree to be bound by the following terms, including any additional guidelines and any future modifications by FOSSA (collectively, the “Terms”), and you acknowledge and consent to the collection and use of your personal information as set forth in the our Privacy Policy ([https://docs.fossa.com/docs/privacy-policy](https://docs.fossa.com/docs/privacy-policy)).

Please read these Terms carefully to ensure that you understand each provision. This Agreement contains a mandatory individual arbitration and class action/jury trial waiver provision that requires the use of arbitration on an individual basis to resolve disputes, rather than jury trials or class actions.

## 1. Licenses

1.1.	General License Grant. Subject to the terms and conditions of these Terms, FOSSA hereby grants to you a limited, non-exclusive, non-sublicensable, non-transferable license during your applicable purchased subscription license term to use the Service in the manner contemplated by these Terms and any applicable order form approved by FOSSA, solely for your internal business purposes in accordance with the documentation for the applicable portion of the Service; provided that this Section 1.1 does not grant you any right to use any Premium Features unless otherwise mutually agreed in an order form. Users shall have no right to sub-license or resell the Service or any component thereof.

1.2.	Premium Features License Grant. Subject to the terms and conditions of these Terms, and in addition to the rights granted above in Section 1.1, to the extent that you have purchased a license to use any set or sub-set of the Premium Features and are current on all amounts due and payable with respect thereto, FOSSA hereby grants to you a limited, non-exclusive, non-sublicensable, non-transferable license during your applicable purchased subscription license term to use the Premium Features (only in object code form or as SaaS solution hosted by FOSSA, as applicable to your license) in the manner contemplated by these Terms solely for your internal business purposes in accordance with the documentation for the applicable Service.

1.3.	Limitations on Use. You may not use the Service except as permitted in this Agreement. Except with FOSSA’s prior written consent or as expressly permitted under this Agreement, you may not: (a) alter, modify or create any derivative works of the Service, the underlying source code, or the documentation in any way, including without limitation customization, translation or localization; (b) port, reverse compile, reverse assemble, reverse engineer, or otherwise attempt to separate any of the components of the Service or derive the source code for the Service (except to the extent applicable laws specifically prohibit such restriction); (c) copy, redistribute, encumber, sell, rent, lease, sublicense, or otherwise transfer rights to the Service or documentation; (d) remove or alter any trademark, logo, copyright or other proprietary notices, legends, symbols or labels in the Service or documentation; (e) permit a number of Users more than has been authorized by FOSSA in writing to access or use the service, or otherwise exceed the authorized usage restrictions; (f) use the Service other than in accordance with this Agreement and all applicable law (including, without limitation, all privacy, data protection and intellectual property laws); or (g) access or use the Service or documentation for the purpose of building a product or service with functionality substantially similar to the Service. You may not release the results of any performance or functional evaluation of any of the Service to any third party without prior written approval of FOSSA for each such release. You may not cause or permit any third party to do any of the foregoing.

## 2. Privacy

User privacy is important to us. Please read our Privacy Policy( [https://docs.fossa.com/docs/privacy-policy](https://docs.fossa.com/docs/privacy-policy)) carefully for details relating to the collection, use, and disclosure of your personal information.

## 3. No Professional Advice

If FOSSA or the Service provides professional information (for example, legal information about license compliance), such information is for informational purposes only and should not be construed as professional or legal advice. You should seek independent professional advice from a person who is licensed and/or qualified in the applicable area.

## 4. Additional Terms

4.1.	Certain features of the Service may have their own terms and conditions that you must agree to when you sign up for that particular product, function, feature, or service. Such terms supplement these Terms and are hereby incorporated by reference.

4.2.	Support Schedule, Support levels, Support. FOSSA and/or your authorized FOSSA Reseller (“FOSSA Reseller”), as applicable, will provide reasonable commercial efforts to support customers in a timely manner. Specific support levels are available for all business and enterprise customers. All business and enterprise customers are supported via online ticket submission with a 72-hour response time. To upgrade and increase support level, please reach out to [support@fossa.com](mailto:support@fossa.com) or your FOSSA Reseller, as applicable, for additional information.

4.3.	Support Hours. Our support team is available Monday through Friday from 9:00 am Pacific Standard Time to 6:00 pm Pacific Standard Time. Support Hours are not available during United States Federal Holidays.

4.4.	The software associated with the Service may include open source software that may be governed by separate open source licenses, as further defined at [https://app.fossa.com/attribution/7a1f1d24-d314-4f3f-8e03-09e84facdcb0](https://app.fossa.com/attribution/7a1f1d24-d314-4f3f-8e03-09e84facdcb0).

4.5.	fossabot Terms. fossabot is an AI-based code analysis tool that uses large language models (“LLMs”) to automatically detect and fix issues in your source code (“fossabot”). fossabot is available in two deployment models: (i) a cloud-hosted service where you authenticate via GitHub or similar platforms and grant fossabot access to your code repositories; and (ii) a self-hosted service where you deploy and operate fossabot within your own infrastructure. When using the cloud-hosted fossabot service, by authenticating via GitHub, you grant fossabot the credentials and permissions necessary to access your code repositories. You represent and warrant that you have all necessary rights and authority to grant such access to your code repositories. You acknowledge and agree that fossabot will transmit your code to, and it will be processed by, our third-party AI service provider Anthropic PBC (“Anthropic”), or other similar LLM service providers, for the sole purpose of enabling fossabot to provide the service of detecting and fixing issues in your code. Anthropic's processing of your code is subject to Anthropic's Terms of Service (available at [https://www.anthropic.com/legal/consumer-terms](https://www.anthropic.com/legal/consumer-terms)) and Privacy Policy (available at [https://www.anthropic.com/legal/privacy](https://www.anthropic.com/legal/privacy)). You should review Anthropic's terms and policies to understand how Anthropic processes your data. You acknowledge that by using fossabot, you are directing FOSSA to transmit your code to Anthropic for processing. While FOSSA takes commercially reasonable measures to select and monitor sub-processors, you acknowledge and agree that: (i) FOSSA acts as a data processor on your behalf when transmitting your code to Anthropic; (ii) Anthropic's processing of your code is subject to Anthropic's own terms, policies, and security practices; (iii) FOSSA disclaims responsibility for Anthropic’s processing of your code to the maximum extent permissible by law. You should refer to our Privacy Policy to understand how FOSSA processes your data through fossabot. To the extent your code repositories, uploaded files, and related metadata processed by fossabot contain Personal Data, you assume full responsibility for: (i) ensuring that you have all necessary rights, consents, and legal bases to submit such data to fossabot; (ii) complying with all applicable privacy and data protection laws in connection with your use of fossabot; and (iii) providing any required notices to individuals whose personal data may be processed through fossabot. When using a self-hosted instance of fossabot, you are responsible for deploying, operating, and maintaining the fossabot service within your own infrastructure. In self-hosted deployments: (i) you control access to your code repositories; (ii) code may still be transmitted to Anthropic for LLM processing unless you configure the service otherwise; and (iii) you are responsible for ensuring compliance with all applicable laws and regulations governing your deployment and use of the fossabot service. In addition to the restrictions set forth in Section 1.3, you may not use fossabot: (i) to process code that you do not have the legal right to access, use, or share; or (ii) to process code containing malicious code, viruses, or other harmful components. You acknowledge that the fossabot service is provided “as is”, that artificial intelligence services contain inherent limitations, you assume all risks that the fossabot service may contain errors and generate code with errors or omit detecting issues in your code, and you waive any claims against fossabot that you may have with respect to any errors or omissions of the fossabot service.

## 5. Evaluations

From time to time, you may be invited to try certain products at no charge for a free trial or evaluation period or if such products are not generally available to licensees (collectively, “Evaluation Services”). Evaluation Services will be designated or identified as beta, pilot, evaluation, trial or the like. Notwithstanding anything to the contrary, Evaluation Services are licensed for your internal evaluation purposes only to determine if you desire to proceed with a further license (and not for production use), are provided “as is” without warranty or indemnity of any kind, and may be subject to additional terms. Unless otherwise stated, any Evaluation Service trial period shall expire thirty (30) days from the trial start date. Notwithstanding the foregoing, FOSSA may discontinue Evaluation Services at any time at its sole discretion and might never make any Evaluation Service generally available. FOSSA will have no liability for any harm or damage arising out of or in connection with any Evaluation Service.

## 6. Eligibility; Termination

You agree that FOSSA, in its sole discretion and for any or no reason, may terminate any account (or any part thereof) you may have with FOSSA and/or these Terms. In addition, FOSSA reserves the right to discontinue any aspect of the Service at any time, including the right to discontinue the display and analysis of any User Data. You agree that any termination of your access to the Service or any account you may have or portion thereof may be affected without prior notice, and you agree that FOSSA will not be liable to you or any third party for such termination. Any suspected fraudulent, abusive, or illegal activity that may be grounds for termination of your use of the Service may be referred to appropriate law enforcement authorities. These remedies are in addition to any other remedies FOSSA may have at law or in equity.

At the end of your subscription license term, or upon any other termination or expiration of these Terms, you shall cease accessing and all use of the Services, and shall return any software and other Materials relating to the Service to FOSSA.

## 7. Payment Terms; Charges and Taxes

If you have purchased a license to use any paid features of the Service, such as Premium Features, the following provisions apply to you:

7.1.	You are responsible for paying any applicable fees at our then-current standard price list or as otherwise mutually agreed in an order form executed by FOSSA and/or your FOSSA Reseller, subject to Section 7.4, and applicable taxes associated with the Service in a timely manner with a valid payment method. Unless otherwise stated, all fees are quoted in U.S. Dollars. All payments must be made electronically by the methods specified by us either on our website or via the Service or by the methods specified by your FOSSA Reseller. You agree that we or your FOSSA Reseller may charge your selected payment method for any such fees owed. You are required to keep your billing information current, complete, and accurate (e.g., a change in billing address, credit card number, or expiration date) and to notify FOSSA or your FOSSA Reseller if your selected payment method is cancelled (e.g., for loss or theft). All fees and charges are earned upon receipt by us and are nonrefundable (and there are no credits) except (a) as expressly set forth herein, and/or (b) as required by applicable law.  Late payments are subject to a finance charge of 1.5% per month, or the maximum rate permitted by law, whichever is lower, on any outstanding balance, plus all reasonable costs of collection.

7.2.	You are responsible for all charges incurred under your account made by you or anyone who uses your account (including your co-workers, colleagues, team-members, etc.). If your payment method fails or you are past due on amounts owed, we or your FOSSA Reseller may collect fees owed using other collection mechanisms. Your account may be deactivated without notice to you if payment is past due, regardless of the dollar amount. You are also responsible for paying any governmental taxes imposed on your use of the Service, including, but not limited to, sales, use, or value-added taxes. To the extent FOSSA or your FOSSA Reseller is obligated to collect such taxes, the applicable tax will be added to your invoices and shall by paid from your billing account.

7.3.	In the event that you license the Services directly from FOSSA (and not through a FOSSA Reseller), authorization to charge your chosen payment method account will remain in effect until you cancel or modify your preferences within the Service; provided, however, that such notice will not affect charges submitted before FOSSA could reasonably act. Your charges may be payable in advance, in arrears, per usage, or as otherwise described when you ordered the applicable service or at [https://fossa.com/pricing](https://fossa.com/pricing), as appliable. You agree that charges may be accumulated as incurred and may be submitted as one or more aggregate charges during or at the end of the applicable billing cycle.

7.4.	All fees and charges may be automatically increased by FOSSA annually by the greater of five percent (5%) and the increase in the relevant Consumer Price Index in the prior twelve (12) month period.  Any changes to fees and charges will apply only on a prospective basis. If you do not agree to any such changes to fees, charges, or terms, your sole remedy is to cancel your subscription. Fees paid for any subscription term are paid in advance and are not refundable in whole or in part. If you have a balance due on any Service account, you agree that FOSSA can charge these unpaid fees to any payment method that you have previously provided. If you purchase the Services from your FOSSA Reseller, the price change policy shall be set forth in the purchase agreement between you and your FOSSA Reseller.

7.5.	Your Service will be automatically renewed and your credit card account (or other payment method account) will be charged as follows without further authorization from you: (a) every month for monthly subscriptions; (b) upon every one (1) year anniversary for annual subscriptions; (c) such other periodic rate you have selected from among the options offered on the Service. You acknowledge that your subscription is subject to automatic renewals and you consent to and accept responsibility for all related recurring charges to your applicable payment method without further authorization from you and without further notice unless required by law. You acknowledge that the amount of the recurring charge may change if the applicable tax rates change or if there has been a change in the applicable fees. If you purchase the Services from your FOSSA Reseller, the renewal policy shall be set forth in the purchase agreement between you and your FOSSA Reseller.

7.6.	Unless otherwise required by applicable law, for annual subscriptions, you must provide us with written notice of your intention not to renew at least thirty (30) days prior to the end of the then-current term of your subscription. If you do so, your subscription will be cancelled at the end of the then-current term. If you purchase the Services from your FOSSA Reseller, the cancellation policy shall be set forth in the purchase agreement between you and your FOSSA Reseller.

7.7.	You shall provide all information reasonably requested by FOSSA to verify your compliance with the usage restrictions and other terms and conditions of this Agreement.

## 8. User Data

8.1.	Use of User Data. By analyzing your User Data with the Service, you hereby grant, and represent and warrant that you have all rights necessary to grant, all rights and licenses to the User Data required for FOSSA to provide the features and functionality of the Service. While your User Data will remain on your systems, FOSSA collects certain information about your use of the Service, including aggregated data about your User Data. You agree that FOSSA may collect, analyze, and use data derived from User Data, as well as data about you, and other Users’ access and use of the Service, for purposes of operating, analyzing, improving, or marketing the Service and any related services. If FOSSA shares or publicly discloses information (e.g., in marketing materials, or in application development) that is derived from User Data, such data will be aggregated or anonymized to reasonably avoid identification of a specific individual or the User. By way of example and not limitation, FOSSA may: (a) track the number of Users on an anonymized aggregate basis as part of FOSSA’s marketing efforts to publicize the total number of Users of the Service; (b) analyze aggregated usage patterns for product development efforts; or (c) use aggregated or anonymous data derived from User Data in a form which may not reasonably identify either a particular individual or the User to develop further analytic frameworks and application tools. You further agree that FOSSA will have the right, both during and after the term of these Terms, to use, store, transmit, distribute, modify, copy, display, sublicense, and create derivative works of the anonymized, aggregated data.

8.2.	Your Responsibilities for User Data. In connection with User Data, you hereby represent, warrant, and agree that: (a) you have obtained the User Data lawfully, and the User Data does not and will not violate any applicable laws or any person or entity’s proprietary or intellectual property rights; (b) the User Data is free of all viruses, Trojan horses, and other elements that could interrupt or harm the systems or software used by FOSSA or its subcontractors to provide the Service; (c) you are solely responsible for ensuring compliance with all privacy laws in all jurisdictions that may apply to User Data provided hereunder; (d) FOSSA may exercise the rights in User Data granted hereunder without liability or cost to any third party; and (e) the User Data complies with the terms of these Terms. For purposes of clarity, FOSSA takes no responsibility and assumes no liability for any User Data, and you will be solely responsible for your User Data. You may not submit any User Data that includes any information that can be used to identify, locate, or contact any of your employees, customers, users or potential customers or users, including: (1) first and last name; (2) home or other physical address; (3) telephone number; (4) email address or online identifier associated with an individual; (5) social security number, passport number, driver’s license number, or similar identifier; (6) credit or debit card number; (7) employment, financial or health information; or (8) any other information relating to an individual, including cookie information and usage and traffic data or profiles, that is combined with any of the foregoing (collectively, “Personal Data”) without FOSSA’s prior written approval. Notwithstanding the foregoing, you acknowledge that if you use fossabot, your code repositories and uploaded files may inherently contain Personal Data such as developer names, email addresses in commit messages, comments, or other metadata, and you accept responsibility for ensuring compliance with all applicable privacy laws when you make such Personal Data available to FOSSA and the fossabot.

8.3.	Rights to User Data. For purposes of clarity, you own all right, title and interest (including all intellectual property rights) in and to your User Data.

## 9. Ownership; Proprietary Rights

The Service is owned and operated by FOSSA. The visual interfaces, graphics, design, compilation, information, computer code, products, software, services, and all other elements of the Service provided by FOSSA, but expressly excluding any of the foregoing owned or licensed by and posted to the Service at the direction of Users (including without limitation User Data) (“Materials”) are protected by intellectual property and other applicable laws. Except for any technology licensed by FOSSA, which is owned by and provided by our third-party licensors, all Materials contained in the Service, including without limitation the intellectual property rights therein and thereto, are the property of FOSSA or its subsidiaries or affiliated companies. All trademarks, service marks, and trade names are proprietary to FOSSA or its affiliates and/or third-party licensors. Except as expressly provided herein, nothing in these Terms shall be deemed to create a license in or under any such Materials or the intellectual property rights therein or thereto, you agree not to sell, license, distribute, copy, modify, publicly perform or display, transmit, publish, edit, adapt, create derivative works from, or otherwise make unauthorized use of the Materials.  For the avoidance of doubt, as between the parties, FOSSA retains all right, title and interest in and to the Service, and all improvements, modifications, and derivatives thereof, and all intellectual property rights relating to the foregoing. You shall not use or disclose any FOSSA software or Materials except as expressly authorized herein.

Neither party may use the other party’s name, logo or marks without such other party’s written pre-approval; provided that FOSSA may: (a) issue one (1) or more press releases or similar materials announcing that you are a customer and user of the Service; (2) refer to you or your usage on its customer lists, website, and other marketing materials; and (3) develop use cases based on your use of the Service, with respect to which you will provide all reasonable cooperation requested by FOSSA.

You may choose to or we may invite you to submit comments or ideas about the Service, including without limitation about how to improve the Service or our products (“Ideas”). By submitting any Idea, you agree that your disclosure is gratuitous, unsolicited and without restriction and will not place FOSSA under any fiduciary or other obligation, and that we are free to use, exercise and exploit the Idea on a nonexclusive basis without any additional compensation to you, and/or to disclose the Idea on a non-confidential basis or otherwise to anyone. You further acknowledge that, by acceptance of your submission, FOSSA does not waive any rights to use similar or related ideas previously known to FOSSA, or developed by its employees, or obtained from sources other than you.

## 10. Third-Party Sites, Information, and Software

10.1.	The Service may call the servers of other websites or services solely at the direction of and as a convenience to Users (“Third-Party Sites”). FOSSA makes no express or implied warranties with regard to the information, or other material, products, or services that are contained on or accessible through Third-Party Sites. Access and use of Third-Party Sites, including the information, material, products, and services on such sites or available through such sites, is solely at your own risk. Further, you acknowledge that the Service may contain copyrighted software of our suppliers which are obtained under a license from such suppliers (“Third-Party Software”). All third-party licensors and suppliers retain all right, title and interest in and to such Third-Party Software and all copies thereof, including all copyright and other intellectual property rights. Your use of any Third-Party Software shall be subject to, and you shall comply with, the terms and conditions of this Agreement, and the applicable restrictions and other terms and conditions set forth in any Third-Party Software documentation or printed materials, including without limitation an end user license agreement.

10.2.	You acknowledge that FOSSA does not manage or control the User Data that you analyze with the Service, and accepts no responsibility or liability for that information regardless of whether such User Data is analyzed by you in breach of these Terms.

10.3.	You acknowledge that fossabot uses third-party large language models, such as Anthropic, to analyze customer source code and automatically detect and fix code issues. Anthropic shall be considered a Third-Party Site for the purposes of these Terms. If you use fossabot, you consent to giving fossabot access to your source code and allowing it to make changes to that source code based on the detection of issues through the use of large language models like that provided by Anthropic. You consent to Anthropic’s terms of service and acknowledge having read their privacy policy. In addition, if you use fossabot, you may provide us with your GitHub credentials and repository access tokens, and you authorize fossabot to access your code repository on GitHub for the purpose of detecting code issues and fixing them automatically on your behalf, in which case you consent to GitHub’s terms and of service and acknowledge having read their privacy policy.

## 11. Security and Privacy Settings

We have implemented commercially reasonable technical and organizational measures designed to secure information you provide us from accidental loss and from unauthorized access, use, alteration or disclosure. However, we cannot guarantee that unauthorized third parties will never be able to defeat those measures or use your information for improper purposes. You understand that internet technologies have the inherent potential for disclosure. You acknowledge that you are under no obligation to provide Personal Data or other sensitive information in order to use the Service and that you provide any such information at your own risk.

## 12. Disclaimers; No Warranties

12.1.	The Service and any third-party or User Data, software, services, or applications made available in conjunction with or through the Service is provided “as is” and “as available” without warranties of any kind either express or implied. To the fullest extent permissible pursuant to applicable law, FOSSA, its suppliers, licensors, and partners disclaim all warranties, statutory, express or implied, including, but not limited to, implied warranties of merchantability, fitness for a particular purpose, and non-infringement of proprietary rights.

12.2.	FOSSA, its suppliers, licensors, and partners do not warrant that the functions contained in the Service will be uninterrupted or error-free, that the Service will meet your requirements, that defects will be corrected, or that the Service or the server that makes it available is free of viruses or other harmful components.  You acknowledge that FOSSA Resellers have no authority to make any representations, warranties, or guarantees about the Service.

12.3.	FOSSA, its suppliers, licensors, and partners do not warrant or make any representations regarding the use or the results of the use of the Service in terms of correctness, accuracy, reliability, or otherwise. You understand and agree that you download or otherwise obtain third-party or User Data, material, or data through the use of the Service at your own discretion and risk and that you will be solely responsible for any damage to your computer system or loss of data that results from the download of such third-party or User provided information, material, or data. FOSSA will not be responsible or liable for the deletion, correction, destruction, damage, loss, or failure to store or maintain any third-party or User Data.

12.4.	Certain state laws do not allow limitations on implied warranties or the exclusion or limitation of certain damages. If these laws apply to you, some or all of the above disclaimers, exclusions, or limitations may not apply to you, and you might have additional rights.

## 13. Limitation of Liability

13.1.	Under no circumstances, including, but not limited to, negligence, will FOSSA or its affiliates, contractors, employees, agents, or third-party partners, licensors, or suppliers be liable for any special, indirect, incidental, consequential, punitive, reliance, or exemplary damages (including without limitation losses or liability resulting from loss of data, loss of revenue, anticipated profits,  or loss of business opportunity) that result from your use or your inability to use the information or materials on the Service, your use of code generated by fossabot or failure of fossabot to identify and fix issues with your code, or any other interactions with FOSSA, even if FOSSA or a FOSSA authorized representative has been advised of the possibility of such damages. Applicable law may not allow the limitation or exclusion of liability for incidental or consequential damages, so the above limitation or exclusion may not apply to you. In such cases, FOSSA’s liability will be limited to the fullest extent permitted by applicable law.

13.2.	In no event will FOSSA’s or its affiliates’, contractors’, employees’, agents’, or third-party partners’, licensors’, or suppliers’ total liability to you for all damages, losses, and causes of action arising out of or relating to these terms or your use of the Service, including without limitation your interactions with other users, (whether in contract, tort including negligence, warranty, or otherwise) exceed the amount paid by you, if any, for accessing the Service during the twelve (12) months immediately preceding the day the act or omission occurred that gave rise to your claim or one hundred dollars, whichever is greater.

13.3.	FOSSA shall not have any liability for any matter beyond its reasonable control.

13.4.	You acknowledge and agree that FOSSA and its FOSSA Resellers (as applicable) has offered its products and services, set its prices, and entered into these terms in reliance upon the disclaimers of warranty and the limitations of liability set forth herein, that the disclaimers of warranty and the limitations of liability set forth herein reflect a reasonable and fair allocation of risk between the parties (including the risk that a contract remedy may fail of its essential purpose and cause consequential loss), and that the disclaimers of warranty and the limitations of liability set forth herein form an essential basis of the bargain between you and FOSSA.

## 14. Indemnification

You agree to defend, indemnify and hold harmless FOSSA and its subsidiaries, agents, managers, and other affiliated companies, and their employees, contractors, agents, officers and directors, from and against any and all claims, damages, obligations, losses, liabilities, costs or debt, and expenses (including but not limited to attorney's fees) arising from: (a) your use of and access to the Service, including any data or work transmitted or received by you, any source code or repositories you authorize fossabot to access via GitHub or self-hosted instances, and any consequences of fossabot’s analysis of your code and fixes it implements; (b) your violation of any term of these Terms, including without limitation, your breach of any of the representations and warranties above; (c) your violation of any third-party right, including without limitation any right of privacy, publicity rights or intellectual property rights; (d) your violation of any law, rule or regulation of the United States or any other country; (e) any claim or damages that arise as a result of any of your User Data or any other data that are submitted via your account, including source code, repositories, or files accessed or uploaded through fossabot; (f) any Personal Data contained within source code or files you provide to FOSSA; or (g) any other party’s access and use of the Service with your unique username, password or other appropriate security code, including unauthorized access to your GitHub account or repositories resulting from your credential management practices. FOSSA will have the right to control the defense, settlement, adjustment or compromise of any such claims, actions or proceedings by using counsel selected by FOSSA. FOSSA will use reasonable efforts to notify you of any such claims, actions, or proceedings upon becoming aware of the same.

## 15. Location of the Service; Export Controls

The hosted version of the Service is controlled and operated from our facilities in the United States. The on-premises version of the Service is controlled and operated at your facility. FOSSA makes no representations that the Service is appropriate or available for use in other locations. Those who access or use the Service from other jurisdictions do so at their own volition and are entirely responsible for compliance with local law, including but not limited to export and import regulations. You may not use the Service if you are a resident of a country embargoed by the United States, or are a foreign person or entity blocked or denied by the United States government. Unless otherwise explicitly stated, all materials found on the Service are solely directed to individuals, companies, or other entities located in the U.S. By using the Service, you are consenting to have your personal data transferred to and processed in the United States.

If you use fossabot, source code and related data accessed via GitHub authentication or uploaded files are processed in the United States and may be transmitted to Anthropic’s systems for LLM-based analysis, which may involve processing in jurisdictions where Anthropic operates. The Self-Hosted version of fossabot is controlled and operated at your chosen facility, but may still transmit data to Anthropic for analysis, unless configured otherwise.

The Service and the underlying information and technology may not be downloaded or otherwise exported or re-exported (a) into (or to a national or resident of) any country to which the U.S. has embargoed goods; or (b) to anyone on the U.S. Treasury Department’s list of Specially Designated Nationals or the U.S. Commerce Department’s Table of Deny Orders. By downloading or using the Service, you are agreeing to the foregoing and you represent and warrant that you are not located in, under the control of, or a national or resident of any such country or on any such list and you agree to comply with all export laws and other applicable laws.

## 16. Governing Law; Arbitration; and Class Action/Jury Trial Waiver

16.1.	Governing Law. This Agreement shall be governed by the internal substantive laws of the State of California, without respect to its conflict of laws principles. Notwithstanding the preceding sentence with respect to the substantive law, any arbitration conducted pursuant to the terms of these Terms shall be governed by the Federal Arbitration Act (9 U.S.C. §§ 1-16). The application of the United Nations Convention on Contracts for the International Sale of Goods is expressly excluded. You agree to submit to the personal jurisdiction of the federal and state courts located in Santa Clara County, California for any actions for which we retain the right to seek injunctive or other equitable relief in a court of competent jurisdiction to prevent the actual or threatened infringement, misappropriation or violation of a our copyrights, trademarks, trade secrets, patents, or other intellectual property or proprietary rights, as set forth in the Arbitration provision below, including any provisional relief required to prevent irreparable harm. You agree that Santa Clara County, California is the proper forum for any appeals of an arbitration award or for trial court proceedings if the arbitration provision below is found to be unenforceable.

16.2.	Arbitration. Read this section carefully because it requires the parties to arbitrate their disputes and limits the manner in which you can seek relief from FOSSA. For any dispute with FOSSA, you agree to first contact us at [support@fossa.com](mailto:support@fossa.com) and attempt to resolve the dispute with us informally. In the unlikely event that FOSSA has not been able to resolve a dispute it has with you after sixty (60) days, we each agree to resolve any claim, dispute, or controversy (excluding any claims for injunctive or other equitable relief as provided below) arising out of or in connection with or relating to these Terms, or the breach or alleged breach thereof (collectively, “Claims”), by binding arbitration by JAMS, under the Optional Expedited Arbitration Procedures then in effect for JAMS, except as provided herein. JAMS may be contacted at [www.jamsadr.com.](http://www.jamsadr.com.) The arbitration will be conducted in Santa Clara County, California, unless you and FOSSA agree otherwise. If you are using the Service for commercial purposes, each party will be responsible for paying any JAMS filing, administrative and arbitrator fees in accordance with JAMS rules, and the award rendered by the arbitrator shall include costs of arbitration, reasonable attorneys’ fees and reasonable costs for expert and other witnesses. Any judgment on the award rendered by the arbitrator may be entered in any court of competent jurisdiction. Nothing in this Section shall be deemed as preventing FOSSA from seeking injunctive or other equitable relief from the courts as necessary to prevent the actual or threatened infringement, misappropriation, or violation of our data security, intellectual property or other proprietary rights.

16.3.	Class Action/Jury Trial Waiver. With respect to all persons and entities, regardless of whether they have obtained or used the Service for personal, commercial or other purposes, all claims must be brought in the parties’ individual capacity, and not as a plaintiff or class member in any purported class action, collective action, private attorney general action or other representative proceeding. This waiver applies to class arbitration, and, unless we agree otherwise, the arbitrator may not consolidate more than one person’s claims. You agree that, by entering into these Terms, you and FOSSA are each waiving the right to a trial by jury or to participate in a class action, collective action, private attorney general action, or other representative proceeding of any kind.

## 17. Miscellaneous

17.1.	Notice and Modifications. FOSSA may provide you with notices, including those regarding changes to FOSSA’s terms and conditions, by email, regular mail, or postings on the Service. Notice will be deemed given twenty-four hours after email is sent, unless FOSSA is notified that the email address is invalid. Alternatively, we may give you legal notice by mail to a postal address, if provided by you through the Service. In such case, notice will be deemed given three days after the date of mailing. Notice posted on the Service is deemed given five (5) days following the initial posting. FOSSA reserves the right to determine the form and means of providing notifications to our Users, provided that you may opt out of certain means of notification as described in these Terms. FOSSA is not responsible for any automatic filtering you or your network provider may apply to email notifications we send to the email address you provide us. FOSSA may, in its sole discretion, modify or update these Terms from time to time, and so you should review this page periodically. When we change the Agreement in a material manner, we will update the ‘last modified’ date at the bottom of this page and notify you that material changes have been made to the Agreement. Your continued use of the Service after any such change constitutes your acceptance of the new Terms of Service. If you do not agree to any of these terms or any future Terms of Service, do not use or access (or continue to access) the Service.

17.2.	U.S. Government End Users. The Service was developed by private financing and constitutes a “Commercial Item,” as that term is defined at 48 C.F.R. §2.101. The Service consists of “Commercial Computer Software” and “Commercial Computer Software Documentation,” as such terms are used in 48 C.F.R. §12.212. Consistent with 48 C.F.R. §12.212 and 48 C.F.R. §227.7202-1 through 227.7202-4, all U.S. Government End Users acquire only those rights in the Service and the Documentation that are specifically provided by this Agreement. Consistent with 48 C.F.R. §12.211, all U.S. Government End Users acquire only technical data and the rights in that data customarily as specifically provided in this Agreement.

17.3.	Waiver. The failure of FOSSA to exercise or enforce any right or provision of these Terms will not constitute a waiver of such right or provision. Any waiver of any provision of these Terms will be effective only if in writing and signed by FOSSA.

17.4.	Severability. If any provision of these Terms is held to be unlawful, void, or for any reason unenforceable, then that provision will be limited or eliminated from these Terms to the minimum extent necessary and will not affect the validity and enforceability of any remaining provisions; except that in the event of unenforceability of the universal Class Action/Jury Trial Waiver, the entire arbitration agreement shall be unenforceable.

17.5.	Assignment. These Terms and any rights and licenses granted hereunder, may not be transferred or assigned by you, but may be assigned by FOSSA without restriction.

17.6.	Survival. Upon termination of these Terms, any provision which, by its nature or express terms should survive, shall survive such termination or expiration, including, but not limited to, all payment obligations and Sections 1.3, 3, 8.1, 9, and 12 through 17. Upon termination, you must immediately revoke any fossabot access to your GitHub account and any repositories, though FOSSA may retain logs and metadata as described in these Terms and the Privacy Policy.

17.7.	Headings. The heading references herein are for convenience only, do not constitute a part of these Terms, and will not be deemed to limit or affect any of the provisions hereof.

17.8.	Entire Agreement. This, including the agreements incorporated by reference, constitutes the entire agreement between you and FOSSA relating to the subject matter herein and will not be modified except in writing, signed by both parties, or by a change made by FOSSA as set forth in these Terms.

17.9.	Claims. To the extent permissible under applicable law, you and FOSSA agree that any cause of action you may have arising out of or related to the Service must commence within one (1) year after the cause of action accrues. Otherwise, such cause of action is permanently barred.

17.10.	Disclosures. The Service is offered by FOSSA, Inc., located at 595 Market Street, FL10, San Francisco, CA, 94105, and can be reached via email at [support@fossa.com.](mailto:support@fossa.com.) If you are a California resident, (a) you may have this same information emailed to you by sending a letter to the foregoing address with your email address and a request for this information; and (b) in accordance with Cal. Civ. Code §1789.3, you may report complaints to the Complaint Assistance Unit of the Division of Consumer Services of the California Department of Consumer Affairs by contacting them in writing at 1625 North Market Blvd., Suite N 112 Sacramento, CA 95834, or by telephone at (800) 952-5210 or (916) 445-1254.

---

Source: https://docs.fossa.com/docs/legal/enterprise-terms-of-service

# Enterprise Terms of Service

These FOSSA Subscription Terms and Conditions (this “Agreement”) are entered into by and between FOSSA, Inc., a Delaware corporation with principal offices located at 595 Market Street, FL10, San Francisco, California, 94105 (“FOSSA”) and the entity identified on a mutually executed Subscription Order (“Subscriber”), and is effective as of the initial subscription start date set forth on such Subscription Order (the “Effective Date”). This Agreement sets forth the terms and conditions under which Subscriber may access and use FOSSA’s hosted open source service, associated websites located at [https://fossa.com](https://fossa.com), [https://fossa.io](https://fossa.io), and [https://bot.fossa.com](https://bot.fossa.com), and software made available to Subscriber (collectively, the “Service”). The parties agree as follows::

## 1. Definitions

1.1. “Authorized User” means any Subscriber personnel who uses the Service on Subscriber’s behalf or through Subscriber’s account. For the avoidance of doubt, Subscriber is not authorized to provide direct access to the Service to any third party.

1.2. “Code Base” means the source code of Subscriber’s project or product software that is the subject of a scan using the Service in accordance with this Agreement.

1.3. “Contributor” means any individual who, in the trailing ninety (90) day period at any time during the Subscription Period, has contributed to or has been a developer of the Code Base; but excludes any third-party developer who only contributed to third-party open-source software, outside of Subscriber’s repositories, that is integrated with the Code Base.

1.4. “Intellectual Property Rights” means (i) copyrights and other rights in works of authorship, (ii) patents and other rights in inventions, (iii) trademarks, service marks, and other rights in indicia of origin, (iv) trade secrets and other rights in confidential business information, (v) mask work rights, (vi) moral rights, (vii) database rights, (viii) all similar and analogous rights to each of the foregoing in every jurisdiction in the world, and (ix) registrations of, applications for, and renewals of each of the foregoing.

1.5. “Privacy Policy” means FOSSA’s privacy policy, available at [www.fossa.io/privacy/](http://www.fossa.io/privacy/), as FOSSA may update from time to time.

1.6. “Subscription Fees” means the fees charged to Subscriber by FOSSA in exchange for access to the Service as set forth in a Subscription Order or as amended pursuant to Section 11.5.

1.7. “Subscription Order” means a standard FOSSA ordering document executed by the parties and setting forth the Subscription Period, the Subscription Fees, and the features, and levels of usage, that Subscriber is authorized to access through the Service.

1.8. “Subscription Period” means, with respect to any Subscription Order, the period of time during which the Subscription Order is applicable, which begins on the start date set forth on such Subscription Order (or if no such start date is set forth on the Subscription Order, then the Subscription Order date) and ends on the end date expressly set forth on such Subscription Order (or if no such end date is expressly set forth therein, then one year after such start date).

1.9. “Term” has the meaning set forth in Section 6.2.

## 2. Access to Service; Licenses

2.1. Access to Service. Subject to compliance with all of the terms and conditions of this Agreement and the Subscription Order, Subscriber may access the Service in accordance with this Agreement during the Subscription Period for Subscriber’s internal business purposes. Depending on the options selected in the Subscription Order, the Service may include FOSSA’s software platform for (i) analyzing Subscriber’s code for compliance with open source licenses, (ii) providing insights about open source code used by Subscriber’s developers and teams for using open source code more effectively, or (iii) using large language models to analyze Subscriber’s code and automatically detect and fix issues.

2.2. Subscription Order. To access the Service, Subscriber must have entered into a Subscription Order with FOSSA. No Subscription Order will be effective until executed by both parties, and each Subscription Order will remain valid only during its Subscription Period and as set forth in Section 6.2. To the extent this Agreement conflicts with the express terms of a Subscription Order, the terms of the Subscription Order will prevail. No different, additional, or contrary provisions set forth on any purchase order or similar document (other than a mutually executed Subscription Order as set forth in this section) will be effective, and all such different, additional, and contrary provisions are hereby expressly rejected.

## 3. Fees and Payment

3.1. Subscription Fees. Subscriber shall pay FOSSA the Subscription Fees set forth on each agreed Subscription Order, including renewals thereof, if any. Subscription Fees are based on the features of the Service that are ordered and not on actual usage. If Subscriber exceeds the number of authorized Contributors included in the subscription licenses as set forth in the Subscription Order, then FOSSA shall invoice Subscriber for the same and Subscriber agrees to and shall pay the Add-On Contributor Fees set forth in the Subscription Order for the same (or in the absence of such terms in the Subscription Order, then an additional fee per Contributor calculated based on multiplying 1.25 by the quotient of the Subscription Fees divided by the authorized number of Contributors included therein) (“Add-On Contributor Fees”). Such fees shall be pro-rated applicable to the remainder of the Subscription Period (amortized on a twelve (12) month straight-line basis) and subscription licenses with respect thereto are co-terminus with the initial subscription licenses. The parties shall meet quarterly to discuss Contributor quantities in good faith and to disclose information relevant thereto to enable calculation of any applicable Add-On Contributor Fees.

3.2. Invoices and Payment. FOSSA will invoice Subscriber in advance for Subscription Fees, including for renewals, if any; and for any Add-On Contributor Fees as and when Code Base scanned using the Services involves software contributed to or developed by such additional Contributors. All fees and charges may be automatically increased by FOSSA annually by the greater of five percent (5%) and the increase in the relevant Consumer Price Index in the prior twelve (12) month period.  Any changes to fees and charges will apply only on a prospective basis. If you do not agree to any such changes to fees, charges, or terms, your sole remedy is to cancel your subscription. Subscriber will pay invoices from FOSSA within thirty (30) days following the date of the invoice, unless a different period of time for payment of invoices is set forth on an applicable Subscription Order. All payments pursuant to this Agreement will be made in United States dollars. If Subscriber elects to pay any invoice with a credit or debit account, Subscriber hereby (a) authorizes FOSSA to charge the invoiced amount to such credit or debit account and verify that such account has the necessary funds or credit available to cover Subscriber’s purchase, and (b) agrees to provide FOSSA with updated information regarding Subscriber’s credit or debit account promptly when the information changes.  Late payments are subject to a finance charge of 1.5% per month, or the maximum rate permitted by law, whichever is lower, on any outstanding balance, plus all reasonable costs of collection.

3.3. Taxes. The Subscription Fees do not include taxes. Subscriber will pay any and all sales taxes, use taxes, goods and services taxes, and other taxes and fees imposed by any government on the amounts payable by Subscriber hereunder, but in no event including taxes imposed on FOSSA’s net U.S. income. If FOSSA is required to pay any such taxes, FOSSA may invoice Subscriber for the amount of such taxes, such invoice to include suitable documentation showing the amount of such taxes, and Subscriber will pay such invoice. If Subscriber is required under any applicable law or regulation to withhold or deduct any portion of the payments due to FOSSA, then the sum payable to FOSSA will be increased by the amount necessary so that FOSSA receives an amount equal to the sum it would have received had Subscriber made no such withholdings or deductions.

## 4. Subscriber Responsibilities and Restrictions

4.1. Acceptable Use. Subscriber shall not: (a) use the Service for any illegal purpose or in violation of any applicable law or regulation; (b) permit more Authorized Users to access the Service than are authorized in an applicable Subscription Order; (c) exceed any applicable usage restrictions authorized in an applicable Subscription Order (e.g. quantity of authorized Contributors) unless Subscriber pays for the same in accordance with the terms hereof or otherwise approved in writing by FOSSA; (d) impersonate any person or attempt to access the Service account or data of any other user; (e) rent, lease, resell, sublicense, distribute, or otherwise transfer access to the Service, or use the Service for service bureau purposes or for the benefit of third parties, or in any other way allow third parties to exploit the Service; (f) disable or circumvent any feature of the Service that provides or enhances security, restricts access, monitors use, or enforces limitations on use; (g) interfere with or impair the operation of the Service by any means including introduction of malware or excessive usage or network traffic; (h) provide Service passwords or other log-in information to any third party; (i) share non-public Service features or content with any third party; or (j) use any automated methods (including “robots” or “crawlers”) or excessive numbers of data requests to access the Service.

4.2. Misuse. In the event of any suspected breach of Section 4.1 or any suspected risk to the integrity of the Service or the security of the data of any user, FOSSA may suspend the Service or Subscriber’s access to the Service without advanced notice, in addition to and without prejudice to any other remedies FOSSA may have.

4.3. Unauthorized Access. Subscriber shall take reasonable steps to prevent unauthorized access to the Service, including without limitation by protecting its passwords and other log-in information. Subscriber shall notify FOSSA immediately of any known or suspected unauthorized use of the Service or breach of its security and shall use best efforts to stop such breach.

4.4. Compliance with Laws. In its use of the Service, Subscriber shall comply with all applicable laws and regulations.

4.5. Use of Fossabot.

4.5.1. Fossabot Service. This section applies if Subscriber uses the Fossabot service as provided in a Subscription Order. Fossabot is an AI-based code analysis tool that uses large language models (“LLMs”) to automatically detect and fix issues in an organization’s source code (“Fossabot”).

4.5.2. Consent to Fossabot Changes to Code. Subscriber consents to giving Fossabot access to Subscriber’s source code and allowing Fossabot to make changes to that source code based on the detection of issues through the use of large language models like that provided by Anthropic. In addition, Subscriber may provide FOSSA with Subscriber’s GitHub credentials and repository access tokens, and Subscriber authorizes Fossabot to access Subscriber’s code repository on GitHub for the purpose of detecting code issues and fixing them automatically on Subscriber’s behalf.

4.5.3. Fossabot Deployment Models. Fossabot is available in two deployment models: (i) a cloud-hosted service where Subscriber authenticates via GitHub or similar platforms and grants Fossabot access to Subscriber’s code repositories; and (ii) a self-hosted service where Subscriber deploys and operates Fossabot within Subscriber’s own infrastructure.

4.5.4. Use of Cloud-Hosted Fossabot Service. When using the cloud-hosted Fossabot service, by authenticating via GitHub, Subscriber grants Fossabot the credentials and permissions necessary to access Subscriber’s code repositories. Subscriber represents and warrants that it has all necessary rights and authority to grant such access to its code repositories. Subscriber acknowledges and agrees that Fossabot will transmit Subscriber’s code to, and it will be processed by, FOSSA’s third-party AI service provider Anthropic PBC (“Anthropic”), or other similar LLM service providers, for the sole purpose of enabling Fossabot to provide the service of detecting and fixing issues in Subscriber’s code. Anthropic’s processing of Subscriber’s code is subject to Anthropic's Terms of Service (available at [https://www.anthropic.com/legal/consumer-terms](https://www.anthropic.com/legal/consumer-terms)) and Privacy Policy (available at [https://www.anthropic.com/legal/privacy](https://www.anthropic.com/legal/privacy)). Subscriber should review Anthropic’s terms and policies to understand how Anthropic processes Subscriber’s data. Subscriber acknowledges that by using Fossabot, Subscriber is directing FOSSA to transmit Subscriber’s code to Anthropic for processing. While FOSSA takes commercially reasonable measures to select and monitor sub-processors, Subscriber acknowledges and agrees that: (i) FOSSA acts as a data processor on Subscriber’s behalf when transmitting Subscriber’s code to Anthropic; (ii) Anthropic’s processing of Subscriber’s code is subject to Anthropic’s terms, policies, and security practices; (iii) FOSSA disclaims responsibility for Anthropic’s processing of Subscriber’s code to the maximum extent permissible by law. Subscriber should refer to FOSSA’s Privacy Policy to understand how FOSSA processes Subscriber’s data through Fossabot. To the extent Subscriber’s code repositories, uploaded files, and related metadata processed by Fossabot contain Personal Data, Subscriber assumes full responsibility for: (i) ensuring that Subscriber has all necessary rights, consents, and legal bases to submit such data to Fossabot; (ii) complying with all applicable privacy and data protection laws in connection with Subscriber’s use of Fossabot; and (iii) providing any required notices to individuals whose personal data may be processed through Fossabot.

4.5.5. Use of Self-Hosted Fossabot Service. When using a self-hosted instance of Fossabot, Subscriber is responsible for deploying, operating, and maintaining the Fossabot service within Subscriber’s own infrastructure. In self-hosted deployments: (i) Subscriber controls access to its code repositories; (ii) code may still be transmitted to Anthropic for LLM processing unless Subscriber configures the service otherwise; and (iii) Subscriber is responsible for ensuring compliance with all applicable laws and regulations governing Subscriber’s deployment and use of the Fossabot service.

4.5.6. Restrictions on Use of Fossabot. In addition to the restrictions set forth in Section 4.1, Subscriber may not use Fossabot: (i) to process code that Subscriber does not have the legal right to access, use, or share; or (ii) to process code containing malicious code, viruses, or other harmful components.

4.5.7. Fossabot Disclaimers. Subscriber acknowledges that the Fossabot service is provided “as is”, that artificial intelligence services contain inherent limitations, Subscriber assume all risks that the Fossabot service may contain errors and generate code with errors or omit detecting issues in Subscriber’s code, and Subscriber waives any claims against Fossabot that Subscriber may have with respect to any errors or omissions of the Fossabot service. Subscriber’s code repositories and uploaded files may inherently contain Personal Data such as developer names, email addresses in commit messages, comments, or other metadata, and Subscriber accepts responsibility for ensuring compliance with all applicable privacy laws when it makes such Personal Data available to FOSSA and Fossabot.

## 5. Confidential Information

5.1. Definition. “Confidential Information” means (a) in the case of Subscriber, the Code Base, and (b) in the case of FOSSA, all non-public features, functions, pricing, and implementations of the Service; except that Confidential Information does not include information that: (i) is or becomes publicly known or publicly available through no fault of the receiving party including, without limitation, all publicly available open source code; (ii) is already in receiving party’s possession at the time of disclosure; (iii) is provided to receiving party by a third party, without breach of any confidentiality obligations by such third party; or (iv) is independently developed without use of or reference to the other party’s Confidential Information.

5.2. Non-Use and Non-Disclosure. Receiving party (i) will not, without disclosing party’s prior written consent, use Confidential Information for any purpose other than to provide, facilitate, access or use the Service as allowed under this Agreement and to perform and enforce this Agreement, and (ii) will use reasonable efforts, and no less than the level of effort set forth in Section 4.3, to prevent the unauthorized disclosure of Confidential Information to any third party, except as set forth in Section 5.4.

5.3. Protective Measures. Receiving party will protect Confidential Information with the same degree of care it uses to protect its own confidential information of similar nature and importance, but in any event, with no less than reasonable care.

5.4. Compelled Disclosure. Receiving party may disclose Confidential Information to the extent such disclosure is required by applicable law, judicial process, or governmental order, provided that receiving party will, to the extent allowed by law, give disclosing party prompt notice of any such required disclosure and reasonably cooperate with disclosing party in any effort to seek a protective order or otherwise to contest such required disclosure by lawful means, at disclosing party’s expense.

5.5. Injunctive Relief. Each party agrees that any breach or threatened breach of Section 5.2 may cause irreparable injury for which monetary relief may not provide adequate compensation, and that in addition to any other remedies available, the injured party is entitled to seek injunctive relief against such breach or threatened breach, without the necessity of proving actual damages or posting a bond or other security.

## 6. Term and Termination

6.1. Initial Term. The initial term of this Agreement (the “Initial Term”) is the Subscription Period.

6.2. Renewal. Unless either party provides written notice at least thirty (30) days before the last day of the Initial Term or then-current Renewal Term that such party does not wish to renew this Agreement, this Agreement will automatically renew for successive additional terms of one year (each, a “Renewal Term”, and all Renewal Terms collectively and together with the Initial Term, the “Term”).

6.3. Termination for Breach. Either party may terminate this Agreement immediately upon notice if the other party materially breaches this Agreement and fails to cure such breach within thirty (30) days of receiving written notice describing the manner in which the Agreement has been breached.

6.4. Termination for Bankruptcy. Either party may terminate this Agreement immediately upon notice if the other party files for bankruptcy, makes an assignment for the benefit of creditors, has a bankruptcy trustee, receiver, or similar official appointed to manage such party’s assets or affairs, or has a bankruptcy petition filed against it, which petition is not dismissed in such party’s favor within sixty (60) days of the filing thereof.

6.5. Survival. The following provisions will survive termination or expiration of this Agreement: (a) any obligation of either party, accrued prior to such expiration or termination, to pay money to the other party, and (b) Sections 5, 6.5, 7.1, 7.3, 7.4, 8.2, 9, 10, and 11. Upon termination, Subscriber must immediately revoke any Fossabot access to Subscriber’s GitHub account and any repositories, though FOSSA may retain logs and metadata as described in this Agreement and the Privacy Policy.

## 7. Intellectual Property

7.1. No Transfer or Assignment of Intellectual Property. Nothing in this Agreement transfers any Intellectual Property Right of either party to the other party.

7.2. Code Base. Without limiting the generality of Section 7.1, Subscriber retains all ownership rights and title that Subscriber has in the Code Base.

7.3. FOSSA Service. Without limiting the generality of Section 7.1, FOSSA retains all ownership rights and title that FOSSA has in the Service, and any improvements, modifications or derivatives thereof, and all intellectual property rights related to the foregoing. While performing its obligations under this Agreement, FOSSA may add information and features to the Service (for example, adding code signatures and license information about additional open source software projects, or developing aggregated statistical data about the frequency with which certain licenses or vulnerabilities tend to appear). FOSSA shall be free to use, exercise and exploit before, during, and after the Term, for free and for any purpose, all suggestions, ideas and/or feedback, and all aggregated de-identified data, relating to the Service (collectively, “Feedback”) provided by or obtained from Subscriber and Authorized Users, notwithstanding anything else.

7.4. No Implied Licenses. Except as expressly set forth in this Agreement, nothing in this Agreement grants any license to any Intellectual Property Right or Confidential Information of either party, whether by implication, estoppel, or otherwise.

7.5. Subscriber’s Name and Logo. FOSSA may include Subscriber’s name and logo in listings of FOSSA’s customers on FOSSA’s website.

## 8. Representations; Disclaimer of Warranties

8.1. Corporate Organization and Authority. Each party represents and warrants that: (a) it is a corporation or other business entity, properly organized and in good standing in its state of incorporation and (b) it has the full corporate right and authority to enter into, execute, and perform its obligations under this Agreement. The individual executing this Agreement on each party’s behalf represents and warrants that he or she has the authority to bind such party to this Agreement.

8.2. Warranty Disclaimers. OTHER THAN AS SET FORTH IN SECTION 8.1, NEITHER PARTY MAKES ANY REPRESENTATIONS OR WARRANTIES TO THE OTHER PARTY. SUBSCRIBER ACCEPTS THE SERVICE “AS IS,” AND FOSSA, FOR ITSELF AND ON BEHALF OF ITS LICENSORS, HEREBY DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING WITHOUT LIMITATION IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE, NON-INFRINGEMENT, OR ANY IMPLIED WARRANTY ARISING FROM STATUTE, COURSE OF DEALING, COURSE OF PERFORMANCE, OR USAGE OF TRADE, TO THE MAXIMUM EXTENT ALLOWED BY LAW. FOSSA DOES NOT WARRANT THAT THE SERVICE OR THE INFORMATION OBTAINED THROUGH THE SERVICE IS ACCURATE, COMPLETE, CURRENT, FREE OF ERRORS OR OMISSIONS, SECURE, RELIABLE, OR ACCESSIBLE AT ANY PARTICULAR TIME.

## 9. Indemnification

9.1. Indemnification by FOSSA. Subject to Section 9.3, FOSSA shall defend, indemnify, and hold harmless Subscriber against any and all costs, losses, liabilities, and expenses arising out of any claim, suit or proceeding brought by a third party (“Claim”) to the extent alleging that the Service infringes or misappropriates such third party’s United States Intellectual Property Rights; provided, however, that FOSSA’s indemnity obligation does not extend to Claims arising out of (i) a combination of the Service with any hardware, software, services, or other materials not provided by FOSSA, if such Claim would not have occurred but for such combination, or (ii) Subscriber’s use of the Service in breach of this Agreement.

9.2. Indemnification by Subscriber. Subject to Section 9.3, Subscriber shall defend, indemnify, and hold harmless FOSSA against any and all costs, losses, liabilities, and expenses arising out of any Claim to the extent arising from: (a) an allegation that Code Base infringes or misappropriates the Intellectual Property Rights or privacy rights of such third party, (b) Subscriber’s violation of applicable law or breach of this Agreement, (c) Subscriber’s gross negligence or willful misconduct; (d) Subscriber’s use of and access to the Service, including any data or work transmitted or received by Subscriber, any source code or repositories Subscriber authorizes Fossabot to access via GitHub or self-hosted instances, and any consequences of Fossabot’s analysis of Subscriber’s code and fixes it implements; (e) any claim or damages that arise as a result of any data Subscriber submits via its account, including source code, repositories, or files accessed or uploaded through Fossabot; (f) any Personal Data contained within source code or files Subscriber provide to FOSSA; or (g) any other party’s access and use of the Service with Subscriber’s unique username, password or other appropriate security code, including unauthorized access to Subscriber’s GitHub account or repositories resulting from Subscriber’s credential management practices..

9.3. Procedure. Any party seeking indemnification under this section will give the other party (a) prompt notice of any Claim for which indemnification is or may be sought, (b) sole control over the defense and settlement of the Claim, provided that such other party will not, without indemnified party’s consent, settle the Claim on terms that admit any wrongdoing by the indemnified party or impose any obligations upon the indemnified party, and (c) reasonable cooperation in such defense or settlement, at such other party’s expense.

9.4. Sole Remedy. This Section 9 sets forth FOSSA’s sole obligation, and Subscriber’s sole remedy, with respect to  any infringement, misappropriation, or alleged infringement or misappropriation of third-party rights arising in connection with the Service.

## 10. Limitation of Liability

10.1. Limit on Indirect Damages. TO THE FULLEST EXTENT PERMITTED BY APPLICABLE LAW, AND EXCEPT FOR A PARTY’S GROSS NEGLIGENCE OR WILLFUL MISCONDUCT, OR OBLIGATIONS ARISING UNDER SECTION 9 (Indemnification), NEITHER PARTY SHALL BE LIABLE FOR ANY INDIRECT, INCIDENTAL, CONSEQUENTIAL, SPECIAL, EXEMPLARY, OR PUNITIVE DAMAGES ARISING OUT OF OR RELATED TO THIS AGREEMENT, INCLUDING WITHOUT LIMITATION, LOSS OF BUSINESS, PROFITS, DATA, COSTS OF PROCUREMENT OF SUBSTITUTE GOODS, SERVICES, OR RIGHTS, OR LOSS THAT RESULT FROM USE OR INABILITY TO USE THE INFORMATION OR MATERIALS ON THE SERVICE OR FROM SUBSCRIBER’S USE OF CODE GENERATED BY FOSSABOT OR FAILURE OF FOSSABOT TO IDENTIFY AND FIX ISSUES WITH SUBSCRIBER’S CODE.

10.2. Liability Cap. TO THE FULLEST EXTENT PERMITTED BY APPLICABLE LAW, AND EXCEPT FOR A PARTY’S GROSS NEGLIGENCE OR WILLFUL MISCONDUCT OR OBLIGATIONS ARISING UNDER SECTION 9 (Indemnification), UNDER NO CIRCUMSTANCES WILL EITHER PARTY’S TOTAL LIABILITY FOR ANY MATTERS ARISING OUT OF OR RELATED TO THIS AGREEMENT REGARDLESS OF THE CAUSE OF ACTION (WHETHER IN CONTRACT, TORT, BREACH OF WARRANTY, NEGLIGENCE, OR OTHERWISE), EXCEED THE FEES PAID OR PAYABLE BY SUBSCRIBER TO FOSSA FOR THE SERVICE IN RESPECT OF THE 12-MONTH PERIOD PRECEDING THE EVENTS OR CIRCUMSTANCES GIVING RISE TO THE CLAIM.

10.3. Application. THE LIMITATIONS AND EXCLUSIONS OF THIS ARTICLE 10 APPLY EVEN IF THE RELEVANT PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES, EVEN IF SUCH DAMAGES WERE FORESEEABLE, AND EVEN IF A LIMITED REMEDY FAILS OF ITS ESSENTIAL PURPOSE. IF APPLICABLE LAW LIMITS THE APPLICATION OF THE PROVISIONS OF THIS ARTICLE 10, THE LIMITATIONS WILL APPLY TO THE MAXIMUM EXTENT PERMISSIBLE UNDER SUCH LAW.

## 11. General Provisions

11.1. Independent Contractors. The relationship between the parties is that of independent contractors. Neither party is an agent of, or authorized to bind, the other party.

11.2. Governing Law; Venue. This Agreement shall be governed by the laws of the State of California without regard to conflict of law principles. The parties hereby submit to the personal and exclusive jurisdiction of the state courts and federal courts located in San Francisco, California, for the purpose of litigating all claims or disputes arising in connection with this Agreement, and waive any and all objections or motions regarding inconvenient forum or venue in such courts.

11.3. Assignment. Neither party may assign this Agreement without the prior written consent of the other party, except that either party may assign this Agreement in its entirety without consent to such party’s successor in interest by way of a merger, acquisition, consolidation, or reorganization of such party, or the sale of substantially all of such party’s business or assets to which this Agreement pertains. Any assignment or purported assignment in violation of this section is void.

11.4. No Third Party Beneficiaries. Nothing in this Agreement confers or is intended to confer any right or privilege on any person other than FOSSA and the Subscriber.

11.5. Amendment.

11.5.1. Changes to the Service. FOSSA continually strives to improve its products and services, and reserves the right to improve or modify the Service and its features in any manner and at any time, including during the Term, at its sole discretion, provided however that such modifications will not materially reduce the functionality of the Service to Subscriber.

11.5.2. Changes to this Agreement.  In addition to FOSSA’s rights in Section 3.2, at the beginning of any Renewal Term as defined in Section 6.2, FOSSA may amend the terms of this Agreement, including without limitation the availability of the Service or any feature thereof (notwithstanding the provisions of Section 11.5.1), provided however that FOSSA notifies Subscriber of any such amendments at least sixty (60) days before the beginning of such Renewal Term in a message sent through the Service or by email to the email address on Subscriber’s account. The Subscriber may reject such amendments by timely exercising the option not to renew the Agreement pursuant to Section 6.2. If the Subscriber does not reject the amendments in the manner set forth in the preceding sentence, the Subscriber will be deemed to have accepted the amendments effective on the first day of the Renewal Term.

11.5.3. Online Policies. FOSSA may modify online policies such as the Privacy Policy from time to time by posting a revised version at its website. Subscriber acknowledges and consents to the collection and use of Personal Data associated with Subscriber as set forth in the Privacy Policy.

11.5.4. Written Amendments. Except as expressly stated in this Section 11.5, this Agreement may not be amended other than by a written instrument executed by both parties.

11.6. Entire Agreement. This Agreement, together with the Subscription Order and any other agreements expressly incorporated by reference, constitutes the entire understanding between Subscriber and FOSSA regarding Subscriber’s use of and access to the Service, and supersedes all prior or contemporaneous writings, negotiations, and discussions with respect to the subject matter hereof.

11.7. Waiver; Severability. A party’s failure to require performance of any provision shall not affect its right to require performance at any time thereafter, nor shall a waiver of any breach or default constitute a waiver of any subsequent breach or default. In the event that any part of the Agreement is held to be invalid or unenforceable, the unenforceable part shall be given effect to the greatest extent possible and the remaining parts will remain in full force and effect.

11.8. Interpretation. Use of paragraph headers in the Agreement is for convenience only and shall not have any impact on the interpretation of this Agreement.

11.9. Subcontractors. Each party may exercise its rights and perform its obligations through third-party contractors, provided, however, that (i) each party will remain fully responsible for all its performance hereunder, including any performance that may be undertaken by such subcontractors, and (ii) each such subcontractor that will have access to or use of any Confidential Information of the other party will be bound by a written confidentiality agreement no less protective of such Confidential Information than the provisions of this Agreement.

11.10. Notices and Contact Information. Except as otherwise set forth in Section 11.5, notices made pursuant to this Agreement will be made in writing and will be deemed given (i) four days after being sent by postal delivery or (ii) two days after being sent by a reputable next-day courier service such as Federal Express next-day delivery, in either case with all postage and delivery fees pre-paid and a delivery confirmation required, to the address provided for such party on an applicable Subscription Order, or to such updated address as such party provides by notice in accordance with this section. Subscriber questions or communications regarding FOSSA, the Service, or the Agreement may be sent to [support@fossa.com](mailto:support@fossa.com) but will not serve as notice under this Agreement.

11.11. Force Majeure. If a party’s performance under this Agreement, other than a failure to pay money when due, is delayed or prevented by hurricane, earthquake, fire, flood, natural disaster, pandemic, acts of terror or war, labor unrest, general failure of the Internet or of communications systems, or other forces beyond the performing party’s reasonable control (collectively, “Force Majeure”), the time allowed for such performance will be extended for a period equal to the duration of the Force Majeure event, and such delay or failure will not constitute a breach of this Agreement. The party suffering a Force Majeure event will  
use reasonable efforts to minimize the delays, to notify the other party promptly, and to inform the other party of its plans to resume performance.

11.12. Counterparts. This Agreement may be executed in counterparts, each of which will be deemed an original, but all of which together will constitute one instrument.

11.13. Government End-Users. Both parties acknowledge and agree that the Service (including without limitation, CLI instructions) will not be used or transferred or otherwise exported or re-exported to countries as to which the United States or any other governmental authority relevant to this Agreement maintains an embargo or other applicable sanctions (“Embargoed Countries”), or to or by a national or resident thereof, or any person or entity on the U.S. Department of Treasury’s List of Specially Designated Nationals or the U.S. Department of Commerce’s Table of Denial Orders, or any similar lists maintained by any governmental authority relevant to this Agreement  
(“Designated Nationals”). Elements of the Service are commercial computer software and commercial computer software documentation, pursuant to FAR section 2.101 and DFAR Section 252.227-7041. If the user or licensee of the Service is an agency, department, or other entity of the United States Government, the use, duplication, reproduction, release, modification, disclosure, or transfer of the Service, or any related documentation of any kind, including technical data and manuals, is restricted by this license agreement to the exclusion of all other terms, in accordance with Federal Acquisition Regulation 12.212 for civilian purposes and Defense Federal Acquisition Regulation Supplement 227.7202 for military purposes, and all other use is prohibited. The Service was developed fully at private expense. All other use is prohibited.

---

Source: https://docs.fossa.com/docs/legal/privacy-policy

# Privacy Policy

Effective date: October 23, 2025

FOSSA, Inc. (“Fossa,” "us", "we", or "our") operates the [https://fossa.com](https://fossa.com), [https://fossa.io](https://fossa.io), and [https://bot.fossa.com](https://bot.fossa.com) websites (the "Site") and provides its customers with a cloud-based platform and AI tools to assist in the management and improvement of its customers’ open source software (the “Platform" and together with the Site, the “Service”).

This page informs you of our policies regarding the collection, use, and disclosure of personal data when you use our Service and the choices you have associated with that data.

We use your data to provide and improve the Service. By using the Service, you agree to the collection and use of information in accordance with this policy. Unless otherwise defined in this Privacy Policy, terms used in this Privacy Policy have the same meanings as in our Terms and Conditions, accessible from [https://fossa.com/terms](https://fossa.com/terms)

## 1. Definitions

* **Service**

  The Service is the [https://fossa.com](https://fossa.com), [https://fossa.io](https://fossa.io), and [https://bot.fossa.com](https://bot.fossa.com) websites and underlying services operated by FOSSA, Inc. and the Platform.

* **Personal Data**

  Personal Data means data about a living individual who can be identified from such data (or from such data and other information either in our possession or likely to come into our possession).

* **Platform**

  The Platform consists of our cloud-based platform and AI tools offered to our customers, which assist in the management of open source software and software vulnerabilities and the detection and fixing of software code issues.

* **Fossabot**

  Fossabot is our agentic AI service that analyzes customer source code and automatically detects and fixes code issues using large-language-model analysis.

* **Usage Data**

  Usage Data is data collected automatically either generated by the use of the Service or from the Service infrastructure itself (for example, the duration of a page visit).

* **Cookies**

  Cookies are small pieces of data stored on your device (computer or mobile device).

* **Data Controller**

  Data Controller means the natural or legal person who (either alone or jointly or in common with other persons) determines the purposes for which and the manner in which any personal information is, or will be, processed.

  For the purpose of this Privacy Policy, we are a Data Controller of your Personal Data.

* **Data Processors (or Service Providers)**

  Data Processor (or Service Provider) means any natural or legal person who processes the data on behalf of the Data Controller.

  We may use the services of various Service Providers in order to process your data more effectively in connection with the Services. In connection with the Platform, our current sub-processors are:

  * AWS (data center provider)
  * BackEngine (customer analytics)
  * DataDog (platform monitoring, alarming, logging)
  * Delighted (customer sentiment)
  * DevRev (customer support management)
  * Google Analytics (user analytics)
  * PagerDuty (incident response)
  * Koala (customer analytics)
  * Anthropic (LLM-based code analysis)
  * PostHog (customer analytics)

* **Data Subject (or User)**

  Data Subject is any living individual who is using our Service and is the subject of Personal Data.

## 2. Information Collection and Use

We collect several different types of information for various purposes to provide and improve our Service to you.

### Types of Data Collected

**Personal Data**

While using our Service, we may ask you to provide us with certain personally identifiable information that can be used to contact or identify you ("Personal Data"). Personally identifiable information may include, but is not limited to:

* Email address
* First name and last name
* Professional and employment-related information
* Phone number
* Address, State, Province, ZIP/Postal code, City
* Cookies and Usage Data
* Source code and metadata
* GitHub credentials and repository access tokens

We may use your Personal Data to contact you with newsletters, marketing or promotional materials and other information that may be of interest to you. You may opt out of receiving any, or all, of these communications from us by following the unsubscribe link or instructions provided in any email we send or by contacting us.

**Usage Data**

We may also collect information about how the Service is accessed and used ("Usage Data"). This Usage Data may include information such as your computer's Internet Protocol address (e.g. IP address), browser type, browser version, the pages of our Service that you visit, the time and date of your visit, the time spent on those pages, unique device identifiers and other diagnostic data.

**Tracking & Cookies Data**

We use cookies and similar tracking technologies to track the activity on our Service and hold certain information.

Cookies are files with small amount of data which may include an anonymous unique identifier. Cookies are sent to your browser from a website and stored on your device. Tracking technologies also used are beacons, tags, and scripts to collect and track information and to improve and analyze our Service.

You can instruct your browser to refuse all cookies or to indicate when a cookie is being sent. However, if you do not accept cookies, you may not be able to use some portions of our Service.

Examples of Cookies we use:

* **Session Cookies.** We use Session Cookies to operate our Service.
* **Preference Cookies.** We use Preference Cookies to remember your preferences and various settings.
* **Security Cookies.** We use Security Cookies for security purposes.

## 3. Use of Data

FOSSA, Inc. uses the collected data for various purposes:

* To provide and maintain our Service
* To notify you about changes to our Service
* To allow you to participate in interactive features of our Service when you choose to do so
* To provide customer support
* To gather analysis or valuable information so that we can improve our Service
* To market and monitor the usage of our Service
* To detect, prevent and address technical issues
* To provide you with news, special offers and general information about goods, services and events which we offer that may be similar to those that you have already purchased, visited, or enquired about unless you have opted not to receive such information
* To provide code analysis, fixes, and improvements as part of our Service

## 5. Legal Basis for Processing Personal Data Under General Data Protection Regulation (GDPR)

If you are from the European Economic Area (EEA), FOSSA, Inc. legal basis for collecting and using the personal information described in this Privacy Policy depends on the Personal Data we collect and the specific context in which we collect it.

FOSSA, Inc. may process your Personal Data because:

* We need to perform a contract with you
* You have given us permission to do so
* The processing is in our legitimate interests and it's not overridden by your rights
* For payment processing purposes
* To comply with the law

For any questions please email us at [privacy@fossa.com](mailto:privacy@fossa.com)

## 6. Retention of Data

FOSSA, Inc. will retain your Personal Data only for as long as is necessary for the purposes set out in this Privacy Policy. We will retain and use your Personal Data to the extent necessary to comply with our legal obligations (for example, if we are required to retain your data to comply with applicable laws), resolve disputes, and enforce our legal agreements and policies.

FOSSA, Inc. will also retain Usage Data for internal analysis purposes. Usage Data is generally retained for a shorter period of time, except when this data is used to strengthen the security or to improve the functionality of our Service, or we are legally obligated to retain this data for longer time periods.

## 7. Transfer of Data

Your information, including Personal Data, may be transferred to, and maintained on, computers located outside of your state, province, country or other governmental jurisdiction where the data protection laws may differ from those from your jurisdiction.

If you are located outside the United States and choose to provide information to us, please note that we and our sub-processors will process the data, including Personal Data, in the United States.

FOSSA, Inc. will take all steps reasonably necessary to ensure that your data is treated securely and in accordance with this Privacy Policy and no transfer of your Personal Data will take place to an organization or a country unless there are adequate controls in place including the security of your data and other personal information.

In relation to the onward transfer, FOSSA, Inc. is responsible for the processing of personal data it receives under the EU-U.S. DPF and the UK Extension to the EU-U.S. DPF and the Swiss-U.S. DPF and subsequently transfers to a third party acting as an agent on its behalf. We comply with the DPF Principles for all onward transfers of personal data from the EU and Switzerland, including the onward transfer liability provisions. In most cases, FOSSA maintains contracts with these third parties restricting their access, use, and disclosure of personal data in compliance with FOSSA’s DPF obligations.

## 8. Fossabot Data Processing

If you use Fossabot, you may provide us with your GitHub credentials, repository access tokens, and source code, which may itself contain Personal Data such as developer names, email addresses, or other identifiable information included in code comments, commit histories, or file contents.

We share Personal Data collected via Fossabot with our Service Provider Anthropic PBC as necessary to provide LLM-based code analysis to you through our Service. Anthropic processes this data solely to generate code analysis results that enable Fossabot to fix and improve your code. Anthropic’s processing of your Personal Data is governed by its Privacy Policy located here: [https://www.anthropic.com/legal/privacy](https://www.anthropic.com/legal/privacy). Neither FOSSA nor Anthropic will use your code to train AI models or for any purpose other than providing services to you.

We retain code analysis results and related metadata only as long as necessary to provide the Service. Your source code is processed only transiently and is not stored permanently by us or Anthropic beyond what is required to complete the analysis and deliver the Fossabot services. You may revoke Fossabot’s access to your GitHub repositories at any time through your GitHub account settings or request deletion of Personal Data collected by Fossabot by contacting [privacy@fossa.com](mailto:privacy@fossa.com).

While we carefully select our Service Providers and maintain appropriate contractual safeguards, you acknowledge that use of Fossabot involves transmitting your code to Anthropic for processing. We encourage you to review Anthropic’s Privacy Policy and we disclaim responsibility for Anthropic’s privacy and data processing practices to the maximum extent permitted by applicable law.

## 9. Other Disclosures of Data

### Business Transaction

If FOSSA, Inc. is involved in a merger, acquisition or asset sale, your Personal Data may be transferred. We will provide notice before your Personal Data is transferred and becomes subject to a different Privacy Policy.

### Disclosure for Law Enforcement

Under certain circumstances, FOSSA, Inc. may be required to disclose your Personal Data if required to do so by law or in response to valid requests by public authorities (e.g. a court or a government agency).

### Legal Requirements

FOSSA, Inc. may disclose your Personal Data in the good faith belief that such action is necessary to:

* To comply with a legal obligation
* To protect and defend the rights or property of FOSSA, Inc.
* To prevent or investigate possible wrongdoing in connection with the Service
* To protect the personal safety of users of the Service or the public
* To protect against legal liability

## 10. Security of Data

The security of your data is important to us, but remember that no method of transmission over the Internet, or method of electronic storage is 100% secure. While we strive to use commercially acceptable means to protect your Personal Data, we cannot guarantee its absolute security.

## 11. "Do Not Track" Signals

We do not support Do Not Track ("DNT"). Do Not Track is a preference you can set in your web browser to inform websites that you do not want to be tracked.

You can enable or disable Do Not Track by visiting the Preferences or Settings page of your web browser.

## 12. Data Privacy Framework and Your Data Protection Rights (EEA, UK, and Switzerland)

FOSSA, Inc complies with the EU-U.S. Data Privacy Framework (EU-U.S. DPF) and the UK Extension to the EU-U.S. DPF, and the Swiss-U.S. Data Privacy Framework (Swiss-U.S. DPF) as set forth by the U.S. Department of Commerce.  FOSSA, Inc has certified to the U.S. Department of Commerce that it adheres to the EU-U.S. Data Privacy Framework Principles (EU-U.S. DPF Principles) with regard to the processing of personal data received from the European Union and the United Kingdom in reliance on the EU-U.S. DPF and the UK Extension to the EU-U.S. DPF.  FOSSA, Inc has certified to the U.S. Department of Commerce that it adheres to the Swiss-U.S. Data Privacy Framework Principles (Swiss-U.S. DPF Principles) with regard to the processing of personal data received from Switzerland in reliance on the Swiss-U.S. DPF.  If there is any conflict between the terms in this privacy policy and the EU-U.S. DPF Principles and/or the Swiss-U.S. DPF Principles, the Principles shall govern.  To learn more about the Data Privacy Framework (DPF) Program, and to view our certification, please visit [https://www.dataprivacyframework.gov/](https://www.dataprivacyframework.gov/)

If you are a resident of the European Economic Area (EEA) or Switzerland, you have certain data protection rights. FOSSA, Inc. aims to take reasonable steps to allow you to correct, amend, delete, or limit the use of your Personal Data.

If you wish to be informed what Personal Data we hold about you and if you want it to be removed from our systems, please contact us.

In all circumstances, individuals will always reserve the right to access their personal data.

In certain circumstances, you have the following data protection rights:

* **The right to access, update or to delete the information we have on you.** Whenever made possible, you can access, update or request deletion of your Personal Data directly within your account settings section. If you are unable to perform these actions yourself, please contact us to assist you.

* **The right of rectification.** You have the right to have your information rectified if that information is inaccurate or incomplete.

* **The right to object.** You have the right to object to our processing of your Personal Data.

* **The right of restriction.** You have the right to request that we restrict the processing of your personal information.

* **The right to data portability.** You have the right to be provided with a copy of the information we have on you in a structured, machine-readable and commonly used format.

* **The right to withdraw consent.** You also have the right to withdraw your consent at any time where FOSSA, Inc. relied on your consent to process your personal information.

Please note that we may ask you to verify your identity before responding to such requests.

You have the right to complain to a Data Protection Authority about our collection and use of your Personal Data. For more information, please contact your local data protection authority in the European Economic Area (EEA)) or Switzerland. Additionally, in compliance with the EU-U.S. DPF and the UK Extension to the EU-U.S. DPF and the Swiss-U.S. DPF, FOSSA, Inc commits to cooperate and comply respectively with the advice of the panel established by the EU data protection authorities (DPAs) and the UK Information Commissioner’s Office (ICO) and the Swiss Federal Data Protection and Information Commissioner (FDPIC) with regard to unresolved complaints concerning our handling of human resources data received in reliance on the EU-U.S. DPF and the UK Extension to the EU-U.S. DPF and the Swiss-U.S. DPF in the context of the employment relationship.

## 13. Service Providers

We may employ third party companies and individuals to facilitate our Service ("Service Providers"), to provide the Service on our behalf, to market our Service, and to perform Service-related services or to assist us in analyzing how our Service is used.

These third parties have access to your Personal Data only to perform these tasks on our behalf and are obligated not to disclose or use it for any other purpose.

### Analytics

We may use third-party Service Providers to monitor and analyze the use of our Service.

* **Google Analytics**

  Google Analytics is a web analytics service offered by Google that tracks and reports website traffic. Google uses the data collected to track and monitor the use of our Service. This data is shared with other Google services. Google may use the collected data to contextualize and personalize the ads of its own advertising network.

  You can opt-out of having made your activity on the Service available to Google Analytics by installing the Google Analytics opt-out browser add-on. The add-on prevents the Google Analytics JavaScript (ga.js, analytics.js, and dc.js) from sharing information with Google Analytics about visits activity.

  For more information on the privacy practices of Google, please visit the Google Privacy & Terms web page: [http://www.google.com/intl/en/policies/privacy/](http://www.google.com/intl/en/policies/privacy/)

### Behavioral Remarketing

FOSSA, Inc. uses remarketing services to advertise on third party websites to you after you visited our Service, including those remarketing services set forth below. We and our third-party vendors use cookies to inform, optimize and serve ads based on your past visits to our Service.

* **Google AdWords**

  Google AdWords remarketing service is provided by Google Inc.

  You can opt-out of Google Analytics for Display Advertising and customize the Google Display Network ads by visiting the Google Ads Settings page: [http://www.google.com/settings/ads](http://www.google.com/settings/ads)

  Google also recommends installing the Google Analytics Opt-out Browser Add-on - [https://tools.google.com/dlpage/gaoptout](https://tools.google.com/dlpage/gaoptout) - for your web browser. Google Analytics Opt-out Browser Add-on provides visitors with the ability to prevent their data from being collected and used by Google Analytics.

  For more information on the privacy practices of Google, please visit the Google Privacy & Terms web page: [http://www.google.com/intl/en/policies/privacy/](http://www.google.com/intl/en/policies/privacy/)

* **Twitter**

  Twitter remarketing service is provided by Twitter Inc.

  You can opt-out from Twitter's interest-based ads by following their instructions: [https://support.twitter.com/articles/20170405](https://support.twitter.com/articles/20170405)

  You can learn more about the privacy practices and policies of Twitter by visiting their Privacy Policy page: [https://twitter.com/privacy](https://twitter.com/privacy)

* **Facebook**

  Facebook remarketing service is provided by Facebook Inc.

  You can learn more about interest-based advertising from Facebook by visiting this page: [https://www.facebook.com/help/164968693837950](https://www.facebook.com/help/164968693837950)

  To opt-out from Facebook's interest-based ads follow these instructions from Facebook: [https://www.facebook.com/help/568137493302217](https://www.facebook.com/help/568137493302217)

  Facebook adheres to the Self-Regulatory Principles for Online Behavioral Advertising established by the Digital Advertising Alliance. You can also opt-out from Facebook and other participating companies through the Digital Advertising Alliance in the USA [http://www.aboutads.info/choices/](http://www.aboutads.info/choices/), the Digital Advertising Alliance of Canada in Canada [http://youradchoices.ca/](http://youradchoices.ca/) or the European Interactive Digital Advertising Alliance in Europe [http://www.youronlinechoices.eu/](http://www.youronlinechoices.eu/), or opt-out using your mobile device settings.

  For more information on the privacy practices of Facebook, please visit Facebook's Data Policy: [https://www.facebook.com/privacy/explanation](https://www.facebook.com/privacy/explanation)

* **Retention.com**

  Retention.com is an online data partner that provides us with information they have in their databases about individuals who are associated with activity on or visitors to our Site and/or Platform (only in the US), which may include Personal Data. We may use this information to remarket and send emails and advertising to you directly and through our service providers.  To learn more about the privacy practices of Retention.com, please review their Privacy Policy: [https://retention.com/privacy-policy/](https://retention.com/privacy-policy/)

  You may opt out of having your information associated with their databases and prevent certain other activities by visiting [https://app.retention.com/optout](https://app.retention.com/optout) and [https://app.retention.com/ccpa_details/](https://app.retention.com/ccpa_details/)

### Payments

We may provide paid products and/or services within the Service. In that case, we use third-party services for payment processing (e.g. payment processors).

We will not store or collect your payment card details. That information is provided directly to our third-party payment processors whose use of your personal information is governed by their Privacy Policy. These payment processors adhere to the standards set by PCI-DSS as managed by the PCI Security Standards Council, which is a joint effort of brands like Visa, Mastercard, American Express and Discover. PCI-DSS requirements help ensure the secure handling of payment information.

The payment processors we work with are:

* **Stripe**

  Their Privacy Policy can be viewed at [https://stripe.com/us/privacy](https://stripe.com/us/privacy)

## 14. Links to Other Sites

Our Service may contain links to other sites that are not operated by us. If you click on a third party link, you will be directed to that third party's site. We strongly advise you to review the Privacy Policy of every site you visit.

We have no control over and assume no responsibility for the content, privacy policies or practices of any third party sites or services.

## 15. Children's Privacy

Our Service does not address anyone under the age of 18 ("Children").

We do not knowingly collect personally identifiable information from anyone under the age of 18. If you are a parent or guardian and you are aware that your Children has provided us with Personal Data, please contact us. If we become aware that we have collected Personal Data from children without verification of parental consent, we take steps to remove that information from our servers.

## 16. Changes to This Privacy Policy

We may update our Privacy Policy from time to time. We will notify you of any changes by posting the new Privacy Policy on this page.

We will let you know via email and/or a prominent notice on our Service, prior to the change becoming effective and update the "effective date" at the top of this Privacy Policy.

You are advised to review this Privacy Policy periodically for any changes. Changes to this Privacy Policy are effective when they are posted on this page.

## 17. Disputes

In compliance with the EU-U.S. DPF and the UK Extension to the EU-U.S. DPF and the Swiss-U.S. DPF, FOSSA, Inc commits to refer unresolved complaints concerning our handling of personal data received in reliance on the EU-U.S. DPF and the UK Extension to the EU-U.S. DPF and the Swiss-U.S. DPF JAMS ADR, an alternative dispute resolution provider based in the United States. If you do not receive timely acknowledgment within 45 days of your DPF Principles-related complaint from us, or if we have not addressed your DPF Principles-related complaint to your satisfaction, please visit [https://www.jamsadr.com/dpf-dispute-resolution](https://www.jamsadr.com/dpf-dispute-resolution) for more information or to file a complaint.  The services of JAMS ADR are provided at no cost to you.

For any Data Privacy Framework disputes that cannot be resolved by the methods above, you may be able to invoke a binding arbitration process under certain conditions. To find out more about the Data Privacy Framework’s binding arbitration scheme, please see: [https://www.dataprivacyframework.gov/framework-article/ANNEX-I-introduction](https://www.dataprivacyframework.gov/framework-article/ANNEX-I-introduction)

The Federal Trade Commission has investigation and enforcement authority over FOSSA’s compliance with the Data Privacy Framework.

## 18. Contact Us

If you have any questions about this Privacy Policy, please contact us: [support@fossa.com](mailto:support@fossa.com)

In compliance with the EU-U.S. DPF and the UK Extension to the EU-U.S. DPF and the Swiss-U.S. DPF, FOSSA, Inc commits to resolve DPF Principles-related complaints about our collection and use of your personal information.  EU and UK individuals and Swiss individuals with inquiries or complaints regarding our handling of personal data received in reliance on the EU-U.S. DPF and the UK Extension to the EU-U.S. DPF, and the Swiss-U.S. DPF should first contact FOSSA, Inc at: [privacy@fossa.com](mailto:privacy@fossa.com)

If you have any comments, concerns or questions about our privacy practices in general, please send an email to [privacy@fossa.com](mailto:privacy@fossa.com) or send mail to:

FOSSA, Inc. Attn: Privacy 595 MARKET ST FL 10, SAN FRANCISCO, CA 94105

Your right to file a complaint with a data supervisory authority about our privacy practices remains unaffected.

---

Source: https://docs.fossa.com/docs/legal/acceptable-use-policy

# Acceptable Use Policy

Last Updated & Effective: May 15, 2019

This Acceptable Use Policy applies to the use of any product, service, or website provided by FOSSA. Here at FOSSA, our goal is to help you and your team manage and utilize open source software efficiently. For us to build a great product we rely on our users not to misuse or abuse our products and services. In addition, this policy helps make sure we’re compliant with applicable laws and regulations around the service we offer. This Acceptable Use Policy is an extension and governed by our [Terms of Service](https://docs.fossa.com/docs/terms-of-service) or other similar written agreements between you (Customer) and FOSSA (the “FOSSA Subscription Agreement”). The Subscription Agreement contains definitions of capitalized terms not otherwise in this Acceptable Use Policy and takes precedence over any conflicting provisions in this document.

We recommend always using your best judgment and be friendly to others in the open source community.

## Policy

By using FOSSA, you are agreeing to the Acceptable Use Policy.  You may not use FOSSA without agreeing to this Acceptable Use Policy. Therefore, you agree not to utilize or encourage any Users to use FOSSA services in the following prohibited ways:

* Attempting to bypass or compromise the integrity of our systems. This could include probing, scanning, or testing the vulnerability of any system or network that hosts our services.
* Reverse-engineering or hacking the FOSSA services by circumventing our security measures to gain unauthorized access in order to find limitations, vulnerabilities, or evade filtering capabilities.
* Transmitting any material that contains viruses, trojan horses, spyware, worms, or any other malicious, harmful, or deleterious programs that can compromise FOSSA services
* Using the FOSSA services to conduct any fraudulent activities
* Using the Services for any illegal purpose, or in violation of any laws (including without limitation data, privacy, and export control laws)
* Soliciting our users for commercial purposes, unless expressly permitted by FOSSA
* Disparaging FOSSA or our partners, vendors, or affiliates
* Modifying, disabling, or compromising the integrity or performance of the services or related systems, network or data
* Deciphering any transmissions to or from the servers running the services
* Overwhelming or attempting to overwhelm our infrastructure by imposing an unreasonably large load on our systems that consume extraordinary resources (CPUs, memory, disk space, bandwidth, etc.)
* Misrepresentation of yourself, or disguising the origin of any content (including by “spoofing”, “phishing”, manipulating headers or other identifiers, impersonating anyone else, or falsely implying any sponsorship or association with FOSSA or any third party)
* Accessing or searching any part of the services by any means other than our publicly supported interfaces (for example, “scraping”)

Without affecting any other remedies available to us, FOSSA may permanently or temporarily terminate or suspend a user’s account or access to the services without notice or liability if FOSSA (in its sole discretion) determines that a user has violated this Acceptable Use Policy.

---

Source: https://docs.fossa.com/docs/legal/dmca-notice

# DMCA Notice

Since we respect content owner rights, it is FOSSA's policy to respond to alleged infringement notices that comply with the Digital Millennium Copyright Act of 1998 (“DMCA”).

If you believe that your copyrighted work has been copied in a way that constitutes copyright infringement and is accessible via the Service, please notify FOSSA's copyright agent as set forth in the DMCA. For your complaint to be valid under the DMCA, you must provide the following information in writing:

An electronic or physical signature of a person authorized to act on behalf of the copyright owner;\
Identification of the copyrighted work that you claim has been infringed;\
Identification of the material that is claimed to be infringing and where it is located on the Service;\
Information reasonably sufficient to permit FOSSA to contact you, such as your address, telephone number, and, e-mail address;\
A statement that you have a good faith belief that use of the material in the manner complained of is not authorized by the copyright owner, its agent, or law; and\
A statement, made under penalty of perjury, that the above information is accurate, and that you are the copyright owner or are authorized to act on behalf of the owner.\
The above information must be submitted to the following DMCA Agent:

FOSSA, Inc.\
Attn: Copyright Agent\
351 9th st #300\
San Francisco, CA 94103\
Email: [support@fossa.com](mailto:support@fossa.com)

UNDER FEDERAL LAW, IF YOU KNOWINGLY MISREPRESENT THAT ONLINE MATERIAL IS INFRINGING, YOU MAY BE SUBJECT TO CRIMINAL PROSECUTION FOR PERJURY AND CIVIL PENALTIES, INCLUDING MONETARY DAMAGES, COURT COSTS, AND ATTORNEYS’ FEES.

Please note that this procedure is exclusively for notifying FOSSA and its affiliates that your copyrighted material has been infringed. The preceding requirements are intended to comply with FOSSA's rights and obligations under the DMCA, including 17 U.S.C. §512(c), but do not constitute legal advice. It may be advisable to contact an attorney regarding your rights and obligations under the DMCA and other applicable laws.

In accordance with the DMCA and other applicable law, FOSSA has adopted a policy of terminating, in appropriate circumstances, Users who are deemed to be repeat infringers. FOSSA may also at its sole discretion limit access to the Service and/or terminate the accounts of any Users who infringe any intellectual property rights of others, whether or not there is any repeat infringement.

---

Source: https://docs.fossa.com/docs/legal/responsible-disclosure-policy

# Responsible Disclosure Policy

FOSSA aims to keep its Services safe for everyone, and data security is of utmost priority. If you are a security researcher and have discovered a security vulnerability in the Services, we appreciate your help in disclosing it to us in a responsible manner.

FOSSA will engage with security researchers when vulnerabilities are reported to us in accordance with this Responsible Disclosure Policy. We will validate, respond and fix vulnerabilities in accordance with our commitment to security and privacy. We won't take legal action against or suspend or terminate access to the Services of those who discover and report security vulnerabilities in accordance with this Responsible Disclosure Policy. FOSSA reserves all of its legal rights in the event of any noncompliance.

Capitalized terms used in this Responsible Disclosure Policy and not otherwise defined have the meaning ascribed to such terms in our [Terms of Service](https://docs.fossa.com/docs/terms-of-service).

## Testing

You may test only against an Account for which you are the Account owner or a Member authorized by the Account owner to conduct such testing. In no event are you permitted to access, download or modify data residing in any other Account or that does not belong to you or attempt to do any of the foregoing. You are also prohibited from:

* executing or attempting to execute any "Denial of Service" attack;
* knowingly posting transmitting, uploading, linking to, sending or storing any Malicious Software;
* testing in a manner that would result in the sending unsolicited or unauthorized junk mail, spam, pyramid schemes or other forms of duplicative or unsolicited messages;
* testing in a manner that would degrade the operation of the Services;
* testing third party applications or websites or services that integrate with or link to the Services.

## Reporting

Share the details of any suspected vulnerabilities with the FOSSA Security Team by sending an email to [security@fossa.com](mailto:security@fossa.com). Please do not publicly disclose these details without express written consent from FOSSA. In reporting any suspected vulnerabilities, please include the following information:

* Vulnerability details with information to allow us to efficiently reproduce your steps
* Your email address

## Compensation Requests

Requests for monetary compensation in connection with any identified or alleged vulnerability will be deemed noncompliant with this Responsible Disclosure Policy.

## Our Commitment

If you identify a verified security vulnerability in compliance with this Responsible Disclosure Policy, FOSSA commits to:

* Promptly acknowledge receipt of your vulnerability report
* Schedule a resolution to the issue in our project backlog

---

Source: https://docs.fossa.com/docs/legal/security

# Security & Compliance Policy

FOSSA is committed to the security of your application’s data. As part of this commitment, we use a variety of industry-standard security technologies and procedures to protect your information from unauthorized access, use, or disclosure.

FOSSA's security program covers the following areas:

* Application Security
* Infrastructure and Network Security
* Compliance
* Privacy
* Corporate Security
* Physical Security

Our employees are required to attend annual security awareness training and are informed of their security responsibilities as part of an extensive and regularly reviewed Information Security Policy.

## Application, Quality & Code Security

* Code is pulled and analyzed in ephemeral, isolated containers or virtualized environments
* Company employs engineers & contractors dedicated to Application Quality & Testing
* FOSSA engineers employ regular peer code review
* Fully encrypted one-way access of sensitive data (i.e. user passwords, access tokens, etc.)
* FOSSA never generates permanent (non-revokable) access credentials for 3rd-party services. Tokens are regularly churned upon expiration and follow the OAuth spec.

## Independent Audits & Vulnerability / Penetration Testing

FOSSA undergoes third-party penetration tests on a regular basis. All items found in the testing are addressed, mitigated, or remediated depending on the severity of the finding. A summary report is available to customers that are currently under contract with FOSSA at the Enterprise level under NDA.

In addition to regular penetration testing, we have continual third-party and internal vulnerability scanning performed throughout our infrastructure and development process. This is meant to complement the regular penetration test and to ensure there are no gaps throughout periods.

In addition to internal and third-party security testing we commission directly, we encourage outside security researchers to test the FOSSA application and report any vulnerabilities found to the FOSSA Security Team, in accordance with our Responsible Disclosure Policy. Testing is performed by account owners or members authorized by the account owner to conduct testing. We will respond and fix vulnerabilities in accordance with our commitment to security and privacy, and will not take legal action against or terminate access to FOSSA for those who discover and report security vulnerabilities through proper channels.

FOSSA maintains a documented Incidence Response Plan.

## Web / Infrastructure Security

FOSSA's web infrastructure is secured behind firewalls and multiple levels of isolation.

* All application data transmitted over HTTPs
* 24/7 application monitoring and DDoS protection
* Multiple firewalls, load balancers, virtualization and network infrastructure isolate application from the outside world
* Hosted in Amazon Web Services datacenters (ISO 27001 and FISMA certified)

## ISO 27001 / FISMA, SSAE16 / ISAE 3402 Type II Attestations

We utilize Amazon Web Services to host the entirety of FOSSA's environment.

Amazon undergoes annual independent audits for the following:

* SOC 1
* SOC 2
* [SOC 3 public audit report](https://aws.amazon.com/compliance/soc-faqs/)  
  For further details, see [Amazon's Compliance and Security Page](https://aws.amazon.com/compliance/).

## Disaster Recovery, Availability and SLAs

We have a documented and tested Contingency Plan and Disaster Recovery plan. These plans are tested at least annually or when there is a major change in the FOSSA environment. Lessons learned from the tests are compiled and are remediated by our engineering department.

FOSSA employs daily data backups and has a distributed, self-healing infrastructure that implements high-availability best practices. We also depend on infrastructure that implements disaster recovery and high availability.

FOSSA's Enterprise plan offers custom SLA's to complement and guarantee availability.

## On-Prem Security

FOSSA's on-prem option is fully sealed. All data (including open source analysis, cache, etc...) is located and communicated behind the firewall.  See our [Architecture Overview](https://docs.fossa.com/docs/architecture-overview).

* Native HTTPs support baked into on-prem offering
* Application is distributed with multiple layers of containerization, virtualization & sandboxing across the stack
* Successfully passed security review for Fortune 50 on-prem deployments

## Corporate, Physical, Operational & Information Privacy

* 2-Factor authentication required for all employees across SaaS accounts
* All employees operate off of company-owned hardware with IT on-boarding and off-boarding support, malware detection and firewalls.
* Office located in private facilities with 24/7 security, surveillance and access cards
* Office facilities have a separate "Guest" network and internal employee network

All FOSSA employees, upon initial hire, go through security awareness training. This training includes some of the best practices and guidelines from the security industry.

## User Security Controls

### SAML-Based Single Sign On

On designated FOSSA plans, you can enable SAML-based single sign-on (SSO) using Google Apps for Work, Okta, or Bitium. SSO not only improves the user experience by making it seamless to log into the FOSSA application, SSO also enhances security by allowing companies to control and maintain their own identity management, which translates into fewer user identities and simpler accessibility across trusted domains.

Read the documentation for detailed instruction on how to setup SSO.

### Role-Based Access Control

The FOSSA application has a set of Enterprise level access controls, including:

* Single Sign On
* Two-Factor Authentication
* Password complexity settings
* Session timeout
* Role Based Access Control

Roles can be configured for a variety of permissions including read-only, editing and administrative roles.  FOSSA's RBAC implementation integrates directly with SAML / LDAP permissions.

Read FOSSA's documentation to learn more about role-based permissions.