File fingerprinting

Learn about Debricked's fingerprint analysis and how to set it up.

Debricked supports scanning for unmanaged dependencies not defined in manifest-files by examining fingerprints of the contents (including binary files) of your application (with some exclusions for non-relevant files).

Enabling file fingerprinting

To enable file fingerprint analysis, first you need to generate a debricked.fingerprints.txt file. This can be done using the Debricked CLI fingerprint command, which can be added to your integration, so that it is generated appropriately before making a Debricked scan. Ensure that your application has been built prior to running the fingerprint command, to ensure that the relevant dependencies are included in the scan. By default, we do not unpack archive files such as .jar, .nupkg, and .war, but it can be activated through the —fingerprint-compressed-content flag. To find out more about which files are unpacked with this file and more information on the command and the various available flags, run:

debricked fingerprint -h

It is also possible to fingerprint automatically before a scan by running debricked scan —fingerprint.

Example configuration

Here’s an example of how to run the fingerprint command directly prior to the scan. The command can be run in any stage of your pipeline, as long as the debricked.fingerprints.txt file is available to be picked up when running debricked scan.

# GitLab CI/CD template

image: debricked/cli:1-resolution-debian

stages:
  - scan
debricked:
  stage: scan
  script:
    - debricked fingerprint
    - debricked scan

The algorithm

The algorithm is built to make the match for each file in two stages: package matching and version resolution.

In the initial stage, we find the first occurrence for each file hash that we can match towards any open source and assign that file to that package. The exact version is yet to be decided in the next part of the algorithm, as this particular file may exist in multiple versions in this package.

To decide the version or versions for a set of matches that are assigned to a specific package, we optimize to find the version with the most matches. This is an iterative algorithm, so we run this part of the algorithm until all files have resolved a specific version. We prioritize stable versions with higher release dates first if they have the same amount of matches.

Manage or override results

It is possible that the resulting package and/or version differ from the dependency included in your application. In the pre-release of file fingerprinting, there is no native way of overriding these results. You can however ensure the correct results, by excluding fingerprinting of a certain file or path. This can be done using the --exclusion flag and adding the correct dependency to either a manifest file or a CycloneDX SBOM included in your scan.

The upcoming stable release will include functionality for natively overriding results through the CLI.

Last updated