Getting Started

System Prerequisites

Surfactant requires Python 3.8 or newer. Tests are regularly run on Linux, macOS, and Windows, though it should also work on other operating systems such as FreeBSD.

Installation

For Users:

  1. Create a virtual environment with python >= 3.8 [Optional, but recommended]

python -m venv cytrics_venv
source cytrics_venv/bin/activate

  1. Install Surfactant with pip

pip install surfactant

For Developers:

  1. Create a virtual environment with python >= 3.8 [Optional, but recommended]

python -m venv cytrics_venv
source cytrics_venv/bin/activate

  1. Clone sbom-surfactant

git clone git@github.com:LLNL/Surfactant.git

  1. Create an editable surfactant install (changes to code will take effect immediately):

pip install -e .

To install optional dependencies required for running pytest and pre-commit:

pip install -e ".[test,dev]"

Understanding the SBOM Output

The following is a brief overview of the default SBOM file output format (which follows the CyTRICS schema). It is not an exhaustive guide to the SBOM format. When the schema is made publicly available a link will be included here.

Software

This section contains a list of entries relating to each piece of software found in the sample. Metadata including file size, vendor, version, etc are included in this section along with a uuid to uniquely identify the software entry.

Relationships

This section contains information on how each of the software entries in the previous section are linked.

Uses: this relationship type means that x software uses y software i.e. y is a helper module to x
Contains: this relationship type means that x software contains y software (often x software is an installer or archive such as a zip file)

Star Relationships

This section contains information on how analysis data or observation entries are related/linked to software (or hardware) entries.

Observations

This section contains observations, typically related to CVEs that impact a piece of software.

Analysis Data

This section is for listing files that are output by plugins/analysis tools.

Hardware

This section contains information on hardware, ranging from a fairly high-level down to individual components on a PCB. Surfactant does not currently populate this section, it is either filled in manually or using other tools that are aimed at analyzing based on pictures of circuit boards.

System

This section contains information on the overall system that software and hardware entries are a part of. Typically it will be manually added to an SBOM that has been generated by Surfactant, though the merge command can also be given an option to generate a system entry.