C/C++ SBOMs

tip

The most straightforward way to generate C/C++ SBOMs with RunSafe is by connecting your projects to the RunSafe Platform. This documentation exists for the cases when that is not possible.

License Acquisition

New Account Creation

Create an account through the RunSafe Platform and login. You will be prompted to create an organization. This is necessary to do before a license key is issued.

Where To Find the License Key

After creating an account on the RunSafe Platform, visit the License Key page to view your organization's license key. Save the key for future use.

Offline License Verification

Contact support@runsafesecurity.com for the necessary license files.

Further details on running in an offline environment can be found in the Retrieving Offline License Files section.

Package Preparation

RunSafe Security will provide you with packages for your operating system. If you do not have those files, contact support@runsafesecurity.com.

Linux

Locate the provided package and install through the system installer.

Redhat-based systems:

sudo rpm -i runsafe-sbom-<ver>.<arch>.rpm

Debian-based systems:

sudo dpkg -i runsafe-sbom-<ver>.<arch>.deb

The only dependency requirement is a GLIBC v2.17 or newer.

Windows

Locate the provided package runsafe_sbom_<ver>.zip and unpack to a temporary location. Further installation will be handled during the Initialization section.

Initialization

If running in an offline environment, refer to the Retrieving Offline License Files section.

The following sub-sections assume an unattended environment that would best mimic a pipeline integration.

Linux

Export the license key retrieved during the License Acquisition section, and leverage the installed runsafe_sbom executable to configure the environment.

export RUNSAFE_LICENSE_KEY=<acquired_key>
runsafe_sbom init -y

This will handle

preparing the current terminal environment for initialization, and
starting the RunSafe SBOM service for SBOM data handling.

For a full list of runsafe_sbom init options, see the Commandline Arguments appendix section.

Windows

Export the license key retrieved during the License Acquisition section, and leverage the installed runsafe_sbom executable to configure the environment. This must be done in the unpacked runsafe_sbom_<ver> directory.

cd runsafe_sbom_<ver>
set RUNSAFE_LICENSE_KEY=<acquired_key>
.\bin\runsafe_sbom.exe init -y

This will handle

copying all necessary program files into your %LOCALAPPDATA% directory, and
starting the RunSafe SBOM service for SBOM data handling.

For a full list of runsafe_sbom init options, see the Commandline Arguments appendix section.

Usage

RunSafe SBOM usage relies on the installed runsafe_sbom binary. For a full list of runsafe_sbom options, see the Commandline Arguments appendix section.

Note: In a Windows environment, the runsafe_sbom binary will not automatically be added to the %PATH%. You can do this manually in your working command prompt environment. The changes will not be permanent system-wide.

set PATH=%PATH%;%LOCALAPPDATA%\RunSafe\bin

RunSafe SBOM Service

The RunSafe SBOM service is started during the Initialization section and is used for data collection and enrichment. Verify the service is running.

runsafe_sbom service status

In some cases, especially when using a custom configuration files, it is helpful to see a more detailed status view. To see a more detailed view, including the running service configuration, add the --verbose flag.

runsafe_sbom service status --verbose

Build Integration

To build with the RunSafe SBOM Generation Tool enabled, prefix the build command with the runsafe_sbom wrapper command.

runsafe_sbom -- make -j4

Post-processing

Post-processing is required to format and enrich the generated data into a CycloneDX v1.6 SBOM. SBOMs can be selected through the SBOM ID and Audit ID or by defaulting to the most recently generated SBOM. SBOMs can be selected as either the most recently generated data, or through unique indentifiers specificied per SBOM.

To view the current SBOM(s) ready for post-processing and see their unique identifiers, use

runsafe_sbom report

The easiest way to post-process an SBOM is by selecting the most most recently generated data.

runsafe_sbom generate --most-recent \
    --output-file=<path/to/desired/output/file>

In cases where relying on the most recently generated data isn't feasible, post-process using the IDs found above.

runsafe_sbom generate --sbom-id=<sbom_id> --audit-id=<audit_id> \
    --output-file=<path/to/desired/output/file>

There will be a generated CycloneDX 1.6 SBOM at the specified output file.

NOTE This will check your license. If it fails to validate your license, refer to the Troubleshooting section on License Validation.

Configuration File

Some data may be manually overridden through the use of a configuration file.

File Location

Linux

The configuration file on any supported Linux system will be located at /usr/share/runsafe/config.toml.

An example configuration file can also be found at /usr/share/runsafe/example-config.toml.

Windows

The configuration file on a Windows system will be located at %LOCALAPPDATA%\RunSafe\config.toml.

An example configuration file can also be found at %LOCALAPPDATA%\RunSafe\example-config.toml.

Edit the Configuration File

Open the appropriate config.toml as specified in the File Location section using your favorite text editor and update as desired.

A full list of configuration file options is located in the Configuration File Settings section of the appendix.

Validate the Configuration File

It is recommended to validate the configuration file after any changes are made to prevent any errors when the service is restarted.

runsafe_sbom config validate

For a full list of runsafe_sbom config options, see the Commandline Arguments appendix section.

Load the Configuration File

After configuration file changes have been validated, it is necessary to restart the service to apply the changes. Note: In a Windows environment, this will need to be done in a privileged command prompt.

runsafe_sbom service stop
runsafe_sbom service start

Verify the new configuration profile is recognized by the service.

runsafe_sbom service status --verbose

For a full list of runsafe_sbom service options, see the Commandline Arguments appendix section.

Appendix

Retrieving Offline License Files

When running in a disconnected environment, it is necessary to acquire offline license files as there will be no connection to the RunSafe license server.

Contact support@runsafesecurity.com for the necessary license files. There will be two files provided:

runsafe.res and
runsafe.sig.

Linux

Place the license files in the /usr/share/runsafe/license directory, and configure the environment as normal.

runsafe_sbom init

Windows

Place the license files in the %LOCALAPPDATA%\RunSafe\license directory, and configure the environment as normal in a privileged command prompt.

cd runsafe_sbom_<ver>
.\bin\runsafe_sbom.exe init -y

Troubleshooting

For all questions not answered in this section, please contact support@runsafesecurity.com for further assistance.

Logging

Logging can be enabled through the use of the RUNSAFE_SBOM_LOG_LEVEL environment variable.

export RUNSAFE_SBOM_LOG_LEVEL=<log_level>

Supported log levels include: error, warn, debug, info.

By default, logs are reported to stdout. Logs can optionally be directed to a file by enabling the RUNSAFE_SBOM_FILE_LOGGER environment variable.

export RUNSAFE_SBOM_FILE_LOGGER=true

On a Linux system, logs are located at /tmp/runsafe/logs/.

In Windows, logs are located at C:\Windows\SystemTemp\runsafe\logs.

Note: Logging must be enabled before the service is started. If you need to restart the service, run the following

runsafe_sbom service stop
runsafe_sbom service start

Be aware, this will drop all previously generated SBOM data.

License Validation

No License Key Specified

If the license key is not correctly specified, you will encounter the following error message.

No Runsafe license information provided.

To configure the license key, see the Initialization and Retrieving Offline License Files sections as needed.

Unable To Communicate With Server

If installed RunSafe SBOM package is unable to communicate with the RunSafe license server, you will encounter the following error message.

License checker failed to communicate with license server.

If in a debian-based Linux environment, ensure the ca-certificates dependency is installed, and try again.

If the RunSafe SBOM generator must be run in an offline environment, or the ca-certificates dependency cannot be installed, refer to the Retrieving Offline License Files section.

Invalid License

If a license key is found, but considered invalid, you will encounter the following error message.

Your RunSafe license is invalid.

Verify the license key is correct in the config.toml. On a Linux system that will be located at /usr/share/runsafe/config.toml. In Windows, it will be located at %LOCALAPPDATA%\RunSafe\config.toml.

If it is incorrect in the config.toml, update the loaded license key by following the steps listed in the Initialization section again.

If the license key in the config.toml is correct, and you continue to experience an invalid license error, contact support@runsafesecurity.com for further assistance.

Environment Variables

Shared Environment Variables

Variable	Value(s)	Use
`RUNSAFE_SBOM_ID`	ex: `ci_job_id`	Manually define the unique identifier of the SBOM.
`RUNSAFE_AUDIT_ID`	ex: `ci_pipeline_id`	Manually define the unique identifier of the audit - particularly useful for grouping sboms by project.
`RUNSAFE_SBOM_LOG_LEVEL`	`error`, `warn`, `debug`, `trace`	Control logging verbosity. Default to `stdout`.
`RUNSAFE_SBOM_FILE_LOGGER`	`true`, `false`	Log to a file. See readmes for more info.

Library-specific Environment Variables

Variable	Value(s)	Use
`RUNSAFE_SBOM_LIBRARY_ONLY`	`true`, `false`	Don't report on source files. Data would have to be regenerated to include them. Data is filtered at the library level so `report --raw-data` will not be useful.

Note: Avoid using RUNSAFE_SBOM_LIBRARY_ONLY unless absolutely necessary. It will be deprecated in favor of a package-only mode and often confuses customers more because they expect a library package instead of a library file. It is better to explain the value of included source files, specifically with regards to the author, copyright, and license fields.

Service-specific Environment Variables

Variable	Value(s)	Use
`RUNSAFE_LICENSE_KEY`	acquired license key	Override the key value specified in the `config.toml` for license verification with the RunSafe license server.
`RUNSAFE_SBOM_SERVER`	app.runsafesecurity.com	Override the default sbom server URL for use with an on-prem RunSafe Identify instantiation.
`RUNSAFE_SBOM_LOG_DIR`	ex: `/var/log/runsafe`	Override the default directory where service logs are stored.
`RUNSAFE_LICENSE_DIR`	ex: `/runsafe/license`	Override the default directory where license files are stored. NOTE This directory must have the `key.pub` in this directory for the service to work.
`RUNSAFE_SBOM_VERSION_ID`	ex: `2`	Set the SBOM Version ID as denoted in the CycloneDX v1.6 SBOM.
`RUNSAFE_SBOM_METADATA_COMPONENT_NAME`	ex: `WolfSSL`	Set the top-level component name as denoted in the CycloneDX v1.6 SBOM.
`RUNSAFE_SBOM_METADATA_COMPONENT_VERSION`	ex: `5.8.2`	Set the top-level component version as denoted in the CycloneDX v1.6 SBOM.
`RUNSAFE_SBOM_METADATA_COMPONENT_SUPPLIER`	ex: `WolfSSL`	Set the top-level component supplier as denoted in the CycloneDX v1.6 SBOM.
`RUNSAFE_SBOM_MASK_PATHS`	ex: `true`	Set the component's path based off of the root component masking absolute paths.
`RUNSAFE_SBOM_NO_PROXY`	ex: `true`	Sets the license checker to not use a proxy when connecting to Platform.
`RUNSAFE_SBOM_PKG_GROUPING`	ex: `true`	Group files by package where available in the generated SBOM.
`RUNSAFE_SBOM_PKG_TIMEOUT_SECS`	ex: `15`	Set the package source timeout to reduce the time cost during generate.

Commandline Arguments

Note: The --help flag is the best way to gain detailed information about the possible commandline arguments and is available for every command and sub-command.

The runsafe_sbom executable has seven top-level commands.

Command	Description
upload-sbom	Upload an SBOM directly to the RunSafe Identify Platform.
config	Operate on the configuration file.
generate	Generate a CycloneDX SBOM.
service	Interact with the SBOM service.
init	Initialize the environment for SBOM generation.
report	Generate SBOM status reports.
logs	Interact with any logs not flushed to a file yet.

Upload-sbom

Flags

Argument	Description
--input	SBOM file path for upload.

Config

Positional Arguments

Argument	Values(s)	Description
action	validate	Action to take on the configuration file.

Flags

Argument	Default Value	Description
--config-file	/usr/share/runsafe/config.toml	SBOM file path for upload.

Generate

Flags

Argument	Description
--sbom-id	SBOM ID of the data to generate an SBOM for.
--audit-id	Audit ID of the data to generate an SBOM for.
--most-recent	Generate an SBOM of the most recently created data.
--output-file	Output path for the generated SBOM.

Service

Sub-Commands

Argument	Description
start	Start the service.
stop	Stop the service.
status	Display the status of the service.

Flags

Argument	Description
--verbose	Display verbose data output by the `status` command

Init

Flags

Argument	Description
--yes	Display verbose data output by the `status` command

Report

Flags

Argument	Description
--output-file	Direct output to a file instead of stdout.
--unrecognized	Reports on all unrecognized components.
--raw-data	Create a detailed report log of all collected components, sorted by SBOM ID and audit ID pairs.
--sbom-id	SBOM ID of the data to generate an SBOM for.
--audit-id	Audit ID of the data to generate an SBOM for.

Logs

Sub-Commands

Argument	Description
flush	Flush any remaining logs to the log file.

Configuration File Settings

Field	Type	Example	Description
`license_key`	`optional[string]`	`"super_secret_key"`	RunSafe License Key, optional if you want to use `offline` mode
`sbom_id`	`optional[string]`	`"myprojectname"`	SBOM Identifier used during gathering of data and as part of the output file name
`audit_id`	`optional[string]>`	`"companyname"`	Audit Identifier used during gathering of data and as part of the output file name
`exclude_directories`	`optional[array[string]]`	`["/my_project_dir/test"]`	Array of directories to exclude, can be glob format i.e. `/test/*`.
`log_level`	`optional[string]`	`"debug"`	Specify log level of the tooling, default is `off`. Can be one of `debug`, `info`, `warn`, `error`
`file_logger`	`optional[boolean]`	`true`	Determines logs to go a file instead of `stdout` by default.
`log_dir`	`optional[path]`	`"/tmp/runsafe/logs/"`	Directory to place the log files
`metadata_component_name`	`optional[string]`	`"tool_name"`	The tool's root component name.
`metadata_component_version`	`optional[string]`	`"1.0.0"`	The tool's root component version.
`metadata_component_supplier`	`optional[string]`	`"companyname"`	The tool's root component supplier.
`components`	`optional[array[component_config]]`	N/A	An array of `component_config` elements.
`component_config.by_name`	`string`	`"foo*"`	Required way to match components by name of the component. Mutually exclusive with `by_path`
`component_config.by_path`	`string` OR `array[string]`	`"/usr/runsafe/bin/"` or `["/usr/runsafe/bin/", "/tmp/runsafe/*"]`	Required way to match components by path of the component. Mutually exclusive with `by_name`
`component_config.license`	`optional[string]`	`"MIT"`	Assign component license with this license.
`component_config.cpe`	`optional[string]`	`"cpe:2.3:a:bar:foo:1.22.0:::::::*"`	Override CPE definition if not found (does not account for found packages during purl detection)
`component_config.aliases`	`optional[array[string]]`	`"foobar"`	Add aliases to the component.
`component_config.supplier`	`optional[string]`	`"RunSafe"`	Specify the supplier for the component.
`component_config.version`	`optional[string]`	`"0.1.0"`	Specify the version for the component.
`component_config.copyright`	`optional[string]`	`"Copyright RunSafe @ 2025"`	Specify the copyright for the component.
`component_config.properties`	`optional[array[property]]`	N/A	An array of `property` elements for the component.
`component_config.tags`	`optional[array[string]]`	`["compiled"]`	An array of tags for the component.
`property.name`	`string`	`"is_local"`	Name of the property
`property.value`	`string`	`"true"`	Value of the property

Example Process: Hello World

Linux

Execute the following to generate an example SBOM assuming that the RunSafe SBOM tool is installed.

export RUNSAFE_LICENSE_KEY=<license_pulled_from_portal>
runsafe_sbom init

mkdir hello && cd hello
cat <<EOF > hello.c
##include <stdio.h>

int main() {
    printf("Hello, World!\n");

    return 0;
}
EOF

runsafe_sbom -- gcc hello.c -o hello
runsafe_sbom generate --most-recent \
    --output-file=hello.cdx.json

The hello SBOM will be available at hello.cdx.json.

Windows

Execute the following in a privileged command prompt.

cd <path\of\containing\runsafe_sbom_<ver>.zip>
tar -xf runsafe_sbom_<ver>.zip
cd runsafe_sbom_<ver>
set RUNSAFE_LICENSE_KEY=<license_pulled_from_portal>
.\bin\runsafe_sbom.exe init -y

## Ensure you have the 'gcc' tool for compilation.
md hello
cd hello

Create the hello.c source file.

##include <stdio.h>

int main() {
    printf("Hello, World!\n");

    return 0;
}

Continue with compilation in an unprivileged command prompt.

%LOCALAPPDATA%\RunSafe\bin\runsafe_sbom.exe gcc hello.c -o hello.o
%LOCALAPPDATA%\RunSafe\bin\runsafe_sbom.exe generate --most-recent --output-file hello.cdx.json

The hello SBOM will be available at hello.cdx.json.

Example GitLab CI Yaml

Add the RunSafe license key to the project's environment variables, and make the package available in the root directory of the project. Refer to the License Acquisition section for instructions on how to retrieve a license key.

We recommend using docker build to create a container image with the RunSafe SBOM Generator package already installed. However, for the purpose of this example, it is assumed the package is available through other means and needs to be installed as a part of the build.

build-hello:
  image: gcc
  stage: build
  script:
    - sudo apt update && apt install -y ca-certificates
    - sudo dpkg -i runsafe_sbom_<ver>.<arch>.deb
    - runsafe_sbom init -y
    - runsafe_sbom -- make -C hello/
    - runsafe_sbom generate --most-recent --output-file hello.cdx.json
  artifacts:
    paths:
      - hello.cdx.json

License Acquisition​

New Account Creation​

Where To Find the License Key​

Offline License Verification​

Package Preparation​

Linux​

Windows​

Initialization​

Linux​

Windows​

Usage​

RunSafe SBOM Service​

Build Integration​

Post-processing​

Configuration File​

File Location​

Linux​

Windows​

Edit the Configuration File​

Validate the Configuration File​

Load the Configuration File​

Appendix​

Retrieving Offline License Files​

Linux​

Windows​

Troubleshooting​

Logging​

License Validation​

No License Key Specified​

Unable To Communicate With Server​

Invalid License​

Environment Variables​

Commandline Arguments​

Upload-sbom​

Config​

Generate​

Service​

Init​

Report​

Logs​

Configuration File Settings​

Example Process: Hello World​

Linux​

Windows​

Example GitLab CI Yaml​

License Acquisition

New Account Creation

Where To Find the License Key

Offline License Verification

Package Preparation

Linux

Windows

Initialization

Linux

Windows

Usage

RunSafe SBOM Service

Build Integration

Post-processing

Configuration File

File Location

Linux

Windows

Edit the Configuration File

Validate the Configuration File

Load the Configuration File

Appendix

Retrieving Offline License Files

Linux

Windows

Troubleshooting

Logging

License Validation

No License Key Specified

Unable To Communicate With Server

Invalid License

Environment Variables

Commandline Arguments

Upload-sbom

Config

Generate

Service

Init

Report

Logs

Configuration File Settings

Example Process: Hello World

Linux

Windows

Example GitLab CI Yaml