Skip to content

Prepare and export an SBOM for FSTEC requirements

Context

For certification-related work it is not enough to export a generic SBOM. You need a machine-readable software component list that follows additional FSTEC expectations and still reflects the full composition of the project, including dependencies that are not always exposed by manifests by default.

CodeScoring can export SBOM files in the extended CycloneDX v1.6 Ext JSON and CycloneDX v1.7 Ext JSON formats adapted for those requirements. To make such an export useful, first build a complete component inventory and then fill in the dependency properties that are not determined automatically.

The example below uses a Python project with pip, because it is a clear way to show why a complete component list sometimes requires dependency resolution in the local environment and an explicit package manager path. The same approach applies to other ecosystems where dependency resolution is needed to build a complete inventory.

What you get

After completing the scenario:

  • CodeScoring will contain a project with a full component inventory saved from a local agent run;
  • key dependencies will have the properties needed for the exported component list;
  • you will be able to download CycloneDX v1.6 Ext JSON or CycloneDX v1.7 Ext JSON from the interface.

Requirements

Before you start, make sure you have:

  • access to an on-premise CodeScoring installation;
  • a CodeScoring license with the SCA module enabled;
  • a platform API token for the local agent run;
  • a local checkout of the project for which the SBOM has to be prepared;
  • the required package manager installed locally and its path known, for example /usr/local/bin/pip3;
  • permissions to view the project and export its SBOM.

Steps

Step 1. Prepare the Johnny agent for a local run

First make sure the local run can be started without last-minute setup.

  1. Open [platform-url]/download/ in your CodeScoring installation.
  2. If needed, check the current version at [platform-url]/download/johnny_version.
  3. Download the agent binary for your system.
  4. Make the file executable:
chmod +x ./johnny

After that the agent can be used for local inventory collection and for saving results to the platform.

Step 2. Build the full component inventory locally first

To get a full dependency graph including transitive dependencies, you need either a lock file from the corresponding package manager or a run with dependency resolution in the build environment. With pip, a separate lock file is usually not available, so this example uses the second option and passes the package manager path explicitly.

Example of a local run that also saves results to CodeScoring

./johnny scan dir . \
  --api_token <api_token> \
  --api_url <api_url> \
  --project "ppk-fstec-demo" \
  --save-results \
  --create-project \
  --localization en \
  --pip-resolve \
  --pip-path /usr/local/bin/pip3 \
  --bom-path bom-local.json

What matters in this command:

  • --pip-resolve enables dependency resolution in the environment;
  • --pip-path tells the agent which local pip should be used;
  • --save-results and --create-project save the result to a separate CLI project in CodeScoring;
  • --bom-path bom-local.json keeps a local SBOM copy next to the project;
  • the full list of flags and run modes is available in the Johnny scan command guide.

When resolve is actually needed

In some ecosystems package managers do not expose transitive dependencies in manifests by default. In such cases CodeScoring recommends dependency resolution in the environment. If a lock file already exists, the agent uses it and does not run a separate resolve step.

Below is a shortened interactive demo. It shows the difference between a manifest-only run and a run with resolve. With pip, this mode should be used only in an isolated project environment, because otherwise extra packages from the local environment can leak into the result even if they are not part of the scanned application.

After this run the platform contains a CLI project with the full component inventory, and bom-local.json is saved locally.

Step 3. Annotate dependency properties before export

An extended SBOM for FSTEC differs from a generic one because extra component properties must be added. Some of them require manual annotation in the project.

  1. Open the saved project in CodeScoring.
  2. Go to the dependencies table.
  3. Click Configure dependencies.
  4. For the components that need more precise representation in the SBOM, fill in the required fields:
    • VCS — a repository or source archive link;
    • Attack surface — yes, indirect, or no;
    • Security function — yes, indirect, or no;
    • Provided by — if the component was borrowed from another product.
  5. Save the changes.

What is not filled automatically

The fields related to attack surface, security function, and product origin require expert judgment and should not be treated as fully automatic. That is why it is worth checking and filling them before export.

These values apply only to the current project and are taken into account in its future exports.

After that these values are taken into account in subsequent SBOM exports from the project.

Step 4. Export the SBOM in the extended CycloneDX format

Now you can get the machine-readable file that already includes the project annotations.

  1. On the project page click Export SBOM.
  2. In the list of formats choose:
    • CycloneDX v1.6 Ext JSON, or
    • CycloneDX v1.7 Ext JSON.
  3. If needed, set the file name.
  4. Confirm the export.

Why the Ext format matters

A regular CycloneDX JSON export is not enough for this scenario. You need the extended Ext format, where the additional component properties are included in properties.

After that the local machine receives a component list file in a format adapted to the additional FSTEC requirements.

Step 5. Check the downloaded file

The final check is needed to confirm that the result is not just an SBOM export, but a file that includes the extra properties and is ready for further review.

  1. Open the downloaded JSON file in a text editor or JSON viewer.
  2. Find one of the components annotated in the previous step.
  3. Confirm that:
    • the component contains a properties block;
    • the block includes values for the properties related to attack surface, security function, and product origin;
    • the repository or source archive link appears in externalReferences.

After this check you can be confident that the file contains not only the base component list, but also the additional annotations needed for this SBOM workflow.

Result

You can consider the scenario complete if:

  • the local agent run produced the full component inventory and saved the result to a CodeScoring project;
  • the required dependency properties are filled in for the components that matter for export;
  • CycloneDX v1.6 Ext JSON or CycloneDX v1.7 Ext JSON has been downloaded from the interface;
  • the downloaded file contains additional component properties and source code links where they were specified.

At this point the component list can be used as a machine-readable result for internal review and further preparation of supporting materials.

What next

Страница была полезна?