FossID-DA Pipeline Guide

Using FDA in a build environment

Supported Ecosystems

• Gradle (Maven repository compatible)

Requirements

Before using FDA in your build pipeline, ensure the following prerequisites are met:

1. The following binaries must be added to your project environment:
   • fossid-cli binary must be placed in /fossid/bin folder
   • fossid-da binary must be placed in /fossid/bin folder
2. The configuration file must be present:
   • fossid.conf must be placed in /fossid/etc/fossid.conf
3. The following service must be running in the pipeline environment where FDA is executed:
   • fossid-shinobi.service

FossID bin folder:

-rwxr-xr-x 1 runner docker  7938824 Jun 19 15:20 fossid-cli
-rwxr-xr-x 1 runner docker 29710114 Jun 19 15:20 fossid-da
-rw-r--r-- 1 runner docker 63334904 Jun 19 15:20 shinobi.jar

Running FDA in a build pipeline

Generate a local report

To run FDA in your build pipeline and generate a local dependency report in the output folder (-o):

sudo -E /fossid/bin/fossid-da --pipeline -m gradle -i /PATH/TO/PROJECT -o reports

Where:

• sudo -E - Run as superuser while preserving environment settings (Java settings, etc.).
• /fossid/bin/fossid-da - Path to the FDA binary.
• --pipeline - Run the FDA in pipeline mode.
• -m gradle - Specify which ecosystem to analyze (Gradle in this example).
• -i /PATH/TO/PROJECT - Input path to the project that needs to be scanned.
• -o reports - Output path where the dependency report will be saved (analyzer-results.json).

Generate a report and upload results to Workbench

To run FDA and also export results to a specific scan code in a Workbench instance, use:

sudo -E /fossid/bin/fossid-da --pipeline -m gradle -i /PATH/TO/PROJECT -o reports --scan-code EXISTING_WB_SCAN_CODE

Parameters (in addition to the above)::

• --scan-code EXISTING_WB_SCAN_CODE - Scan code from a Workbench instance where the dependency analysis results will be uploaded.

Additional options that can be used when running FDA in pipeline mode

Gradle project scan

For the Gradle ecosystem, if the project contains multiple subprojects, each may have its own distinct dependencies:

Root project 'TEST_APP'
├── Project ':core'
├── Project ':api'
└── Project ':app'

In such cases, you can use the --gradle-projects option to select which specific Gradle project to process.

Example: Running FDA on a single project

sudo -E /fossid/bin/fossid-da --pipeline -m gradle -i /PATH/TO/PROJECT -o reports --scan-code EXISTING_WB_SCAN_CODE --gradle-projects app

In this example, only the :app project will be used to extract dependency graph information.

Example: Running FDA on multiple projects

Multiple Gradle subprojects can be selected by providing a comma-separated list:

sudo -E /fossid/bin/fossid-da --pipeline -m gradle -i /PATH/TO/PROJECT -o reports --scan-code EXISTING_WB_SCAN_CODE --gradle-projects app,core

In this example, both :app and :core projects will be processed.

If multiple projects exist and --gradle-projects is not specified, FDA will attempt to gather dependency information from all available projects.

Force build project with build system

If you need the build system to build the project in order to gather dependencies, use the --force-pipeline-build option:

sudo -E /fossid/bin/fossid-da --pipeline -m gradle -i /PATH/TO/PROJECT -o reports --scan-code EXISTING_WB_SCAN_CODE --force-pipeline-build

Where:

• --force-pipeline-build - Forces the build system to build the project when running FDA in pipeline mode. This option only works when used together with --pipeline.

Setting up fossid.conf

If the dependency analysis report generated by FDA needs to be exported to a Workbench instance, add the following settings to fossid.conf:

; FossID-DA Test Workbench Settings
da_wb_user="USER"
da_wb_token="TOKEN"
da_wb_api="https://Workbench/Instance/api.php"

Reports

The dependency report (analyzer-results.json) will be exported by default to a reports directory created in the pipeline workspace.

Example Jobs in a Pipeline

  - name: Create reports folder
    run: sudo mkdir reports
  - name: Create fossid bin folder
    run: sudo mkdir -p /fossid/bin
  - name: Create fossid etc folder
    run: sudo mkdir -p /fossid/etc/
  - name: Move tools to bin folder
    # In this example, we assume the binaries (fossid-cli, fossid-da, shinobi.jar) are already available in a bin/ folder.
    run: |
      sudo mv bin/shinobi.jar /fossid/bin
      sudo chmod +x bin/fossid-cli
      sudo mv bin/fossid-cli /fossid/bin
      sudo chmod +x bin/fossid-da
      sudo mv bin/fossid-da /fossid/bin
  - name: Setup fossid.conf
    run: sudo cp path/to/fossid.conf /fossid/etc/fossid.conf
  - name: Show tools versions 
    run: |
      /fossid/bin/fossid-cli --version
      /fossid/bin/fossid-da --help
      java -jar /fossid/bin/shinobi.jar -version
  - name: FDA - Gradle 1
    run: |
      sudo -E /fossid/bin/fossid-da --pipeline -m gradle -i /PATH/TO/PROJECT -o reports --scan-code EXISTING_WB_SCAN_CODE
    continue-on-error: true
  - name: Show scan results (optional, used to test if the report was correctly generated)
    run: cat reports/analyzer-result.json