FOSSA - Guides & Documentation

The fossa Developer Hub

Welcome to the fossa developer hub. You'll find comprehensive guides and documentation to help you start working with fossa as quickly as possible, as well as support if you get stuck. Let's jump right in!

Get Started    

Java / Scala

FOSSA supports Java and Scala code via Maven, Gradle and Sbt.

Tool
Automated
Provided

Maven

pom.xml

pom.xml or custom mvn build cmd

Gradle

build.gradle or custom *.gradle

build.gradle or custom *.gradle

Sbt (Scala Build Tool)

build.sbt

build.sbt

Ant

Only through sbt/gradle

Only through sbt/gradle

Automated Builds

After importing Java code, FOSSA will attempt to get results out of the box by incrementally running your build and statically resolving dependency signatures that are produced.

This method supports a wide variety of build states, but will often require configuration or inlined settings for more complicated builds.

Automated Builds in the Java Ecosystem

Since Java builds are generally complicated, it is both impossible to generically build codebases OR get accurate results from pure static analysis of pom.xml or build.gradle files.

For larger builds that require significant configuration, we recommend using Provided Builds for fast and accurate results. Scroll down to view the Provided Builds documentation.

Configuring Automated Builds

FOSSA provides a wide variety of options to configure Java ecosystem builds under each project's settings page (Project > Settings > Builds & Languages > Java):

Configuring automated build settings for Java

Configuring automated build settings for Java

To provide the best OOTB experience, FOSSA will elect sane defaults and configuration magic. These include choosing only compile and runtime scopes, setting default build profiles, intelligently handling optional dependencies and more.

Default Handling for Java Build Parameters

FOSSA automatically provides handling logic for optional dependencies, scopes, transitive dependencies, tags and more. See the Extended Documentation section at the bottom of this page.

If you'd like to provide any environment variables (such as GRADLE_OPTS) during the Automated Build, you can add them under Project Settings > Builds and Languages > General.

Learn more about customizing [Automated Builds].

Provided Builds

For complex builds, you can use fossa-cli, our open-sourced dependency analysis client, to upload results from an existing Java build in CI or on your local development machine.

To get started, install the latest release of fossa-cli from our GitHub releases page:

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

Once installed, run fossa init inside of your repo's root directory. Below, we've included extended documentation on configuring for different ecosystems:

Since fossa-cli is open source, you can view our raw implementation of how we get dependency data directly in the repo.

Authentication

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, visit your Java Language Settings under Account Settings > Languages > Java.

By default, when FOSSA encounters a package in the Java ecosystem, it will try to resolve it from the following public registries (in order):

Adding a Public Registry

To add a new public registry, you can simple add a new entry under Repositories and FOSSA will begin checking that registry (in order) for packages that your projects are bringing in.

Adding a Private Registry

To add an authenticated registry, add two entries to Repositories and Servers with a corresponding Id and include your credentials under the Servers entry:

Example private Artifactory configuration

Example private Artifactory configuration

Improving Resolution Performance

If you know what registries you'd like FOSSA to prefer, you can re-order to your preference in the Java Language Settings. This way, if you have a set of registries that you know will succeed, FOSSA will check those first and resolve dependencies without having to cycle through subsequent registries.

Package Data

FOSSA will parse data from all package metadata as well as scan all code provided in an artifact or associated code archives. If references to license webpages are found, FOSSA will crawl the web to seek licensing information.

In cases where no source code is included in an artifact, FOSSA will attempt to resolve it to a known codebase that the artifact was built from 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.

If FOSSA encounters a META-INF folder in a Maven archive, it treats it as data from deeper dependencies.

Extended Documentation on Automated Builds

In this section, you'll find extended documentation on how FOSSA's Automated Builds resolves dependencies. If you are using Provided Builds, then these notes do not apply.

Maven Dependencies

The Maven build system (http://maven.apache.org/) pulls in dependencies based on:

  1. Group ID
  2. Artifact ID
  3. Version

Fossa derives dependencies by building your project and seeing which dependencies are brought in. Other metadata is fetched directly from repositories.

Here's some of the metadata that's pulled in:

  • Home page URL
  • Dependencies
    • Group ID
    • Artifact ID
    • Resolved version
    • Transitive excludes
    • Optional
    • Scopes

Optional

Optional dependencies are included in analysis and are grok'ed by Fossa. The optional dependencies are tagged as Optional by Fossa and are not included beyond depth 1.

Scope

Dependency Scope is included in analysis and is selectable in Fossa. Choosing different project scopes allows you to choose which dependencies are included in issue scans and in the UI.

Transitive Excludes

Dependencies that are excluded transitively are also grok'ed by Fossa. If a transitive dependency is expicitly excluded, Fossa will exclude that dependency from its issue scans and in the UI. If another dependency brings in the excluded transitive dependency, then it will be included. These excludes are scoped to dependencies, not projects.

Scala Dependencies

The Scala build tool (http://www.scala-sbt.org/) pulls in dependencies from several kinds of repositories. FOSSA can scan them if they are published in the Maven-compatible file layout (default). FOSSA does not yet support artifacts in the Ivy file layout.

Gradle Dependencies

The Gradle build system (https://docs.gradle.org/) pulls in dependencies based on the repository it's pulling from:

  1. Maven (Supported)
  2. Ivy (Unsupported)
  3. Local (Unsupported)

The metadata pulled in is similar to maven:

  • Available versions
  • Home page URL
  • Dependencies
    • Group ID
    • Artifact ID
    • Resolved version
    • Transitive excludes
    • Scopes

Properties

Gradle properties can be set via environment variables as defined above. Gradle property names should be prefixed with ORG_GRADLE_PROJECT_ as per the gradle documentation.

Gradle Properties

Dependencies

See the Maven section for more detail.

Java / Scala