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

Navigate to your organization's Settings -> License Key. Save the key for future use.

Offline License Verification

Contact [email protected] for the necessary license files.

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

Installation

If an older version of the RunSafe SBOM tool is already installed, follow the steps listed in the Upgrading section instead.

Linux

Configure the RunSafe package repository and install the runsafe-sbom package.

Redhat-based systems:

curl -1sLf \
  'https://packages.runsafesecurity.com/public/runsafe/setup.rpm.sh' \
  | sudo -E bash
sudo yum install runsafe-sbom

Debian-based systems:

curl -1sLf \
  'https://packages.runsafesecurity.com/public/runsafe/setup.deb.sh' \
  | sudo -E bash
sudo apt install runsafe-sbom

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

Windows

RunSafe Security will provide you with packages for your operating system. If you do not have those files, contact [email protected].

Locate the provided package runsafe_sbom_<ver>.zip and unpack to a temporary location. From a privileged command prompt in the unpackaged directory, run:

.\bin\runsafe_sbom.exe install -y

This will copy all necessary program files into the %LOCALAPPDATA%\RunSafe directory. 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 online, unattended environment that would best mimic a pipeline integration.

Linux

Validate the installation against the license key retrieved during the License Acquisition section, and start the RunSafe SBOM service.

runsafe_sbom login -l <acquired_key>
runsafe_sbom service start

Windows

Validate the installation against the license key retrieved during the License Acquisition section, and start the RunSafe SBOM service. This must be done in a privileged command prompt (not Powershell).

cd "%LOCALAPPDATA%\RunSafe"
.\bin\runsafe_sbom.exe login -l <acquired_key>
.\bin\runsafe_sbom.exe service start

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

Not Recommended: Shared RunSafe SBOM Service Configuration

In unique cases where multiple builds run against a shared instance of the RunSafe SBOM Service, it is necessary to specify a pre-defined SBOM_ID to assign to the build.

runsafe_sbom --sbom_id=<sbom_id> -- 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 defaulting to the most most recently generated data.

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

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

runsafe_sbom generate --sbom-id=<sbom_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 [email protected] for the necessary license files. There will be a .zip archive containing three files:

runsafe.res, and
runsafe.sig, and
key.pub.

Verify the license zip file and start the RunSafe SBOM service.

Linux

sudo runsafe_sbom login -o <license_zip>
runsafe_sbom service start

Windows

cd "%LOCALAPPDATA%\RunSafe"
.\bin\runsafe_sbom.exe login -o <license_zip>
.\bin\runsafe_sbom.exe service start

Troubleshooting

For all questions not answered in this section, please contact [email protected] 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 [email protected] for further assistance.

Upgrading

Linux

Upgrade the installed runsafe-sbom package using the system's package manager, and restart the service.

Redhat-based systems:

sudo yum update runsafe-sbom
runsafe_sbom service start

Debian-based systems:

sudo apt update
sudo apt upgrade runsafe-sbom
runsafe_sbom service start

Windows

Make sure that the RunSafe SBOM service is stopped before upgrading to a new version. From a privileged command prompt, run:

cd "%LOCALAPPDATA%\RunSafe"
.\bin\runsafe_sbom.exe service stop

After the service is stopped, follow the steps listed in the Installation section.

Uninstalling

Linux

Uninstall the installed runsafe-sbom package using the system's package manager and remove the RunSafe repository.

Redhat-based systems:

sudo yum remove runsafe-sbom
sudo rm /etc/yum.repos.d/runsafe-security-runsafe.repo

Debian-based systems:

sudo apt remove runsafe-sbom
sudo rm /etc/apt/sources.list.d/runsafe-security-runsafe.list
sudo apt update

Windows

Make sure that the SBOM service is stopped and remove the RunSafe directory. From a privileged command prompt, run:

cd "%LOCALAPPDATA%"
.\RunSafe\bin\runsafe_sbom.exe service stop
rmdir /S RunSafe

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_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.
`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 the following top-level commands:

Command	Description
config	Operate on the configuration file.
generate	Generate a CycloneDX SBOM.
service	Interact with the SBOM service.
report	Generate SBOM status reports.
logs	Interact with any logs not flushed to a file yet.
platform	Communicate with the RunSafe Platform.
login	Perform a login to the external platform.

Wrapping Compilation

Configuration of the build for RunSafe SBOM generation is also handled through the use of the runsafe_sbom utility.

runsafe_sbom --sbom-id=<sbom_id> -- <build_cmd>

Positional Arguments

Argument	Description
--	Required to signal wrapping a build command. Anything after this argument will be executed as one command within the context of `runsafe_sbom`.
`<build_cmd>`	Substitute with your usual build command - ex: `make -j4`.

Flags

Argument	Description
--sbom-id	Optional: SBOM ID of the data to generate an SBOM for.

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.
--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

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.
--pkg-errors	Prints out the list of package errors that occurred during processing of new data.
--sbom-id	SBOM ID of the data to generate an SBOM for.
--select	Allows interactive selection of a specific sbom if applicable.
--verbose	Print more detailed output.

Logs

Sub-Commands

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

Platform

Sub-Commands

Argument	Description
upload-sbom	Upload an SBOM to the RunSafe Platform.
upload-binary	Upload a binary to the RunSafe Platform.

Flags

Argument	Description
--input	SBOM to be uploaded.
--name	Name to identify the risk reduction analysis for the binaries.

Flags

Argument	Description
--license-key	Provide the license key from an argument.
--license-server	Override default license server from environment and / or local remote.
--offline-files	Provide offline zip files that will get automatically checked.

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.
`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.
`server`	`optional[url]`	`"app.runsafesecurity.com"`	Override the default sbom server URL for use with an on-prem RunSafe Identify instantiation.
`no_proxy`	`optional[boolean]`	`true`	Sets the license checker to not use a proxy when connecting to Platform.
`pkg_only`	`optional[boolean]`	`true`	Only output the packages found in the SBOM.
`mask_paths`	`optional[path]`	`"/path/to/my_project_dir/"`	Directory to make all file paths relative to.
`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`.
`components.pkg_info`	`optional[array[pkg_config]]`	N/A	An array of `pkg_config` elements.
`pkg_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`.
`pkg_config.license`	`optional[string]`	`"MIT"`	Assign component license with this license.
`pkg_config.aliases`	`optional[array[string]]`	`"foobar"`	Add aliases to the component.
`pkg_config.supplier`	`optional[string]`	`"RunSafe"`	Specify the supplier for the component.
`pkg_config.version`	`optional[string]`	`"0.1.0"`	Specify the version for the component.
`pkg_config.copyright`	`optional[string]`	`"Copyright RunSafe @ 2025"`	Specify the copyright for the component.
`pkg_config.properties`	`optional[array[property]]`	N/A	An array of `property` elements for the component.
`pkg_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.

runsafe_sbom login -l <license_pulled_from_portal>
runsafe_sbom service start

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 --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>
.\bin\runsafe_sbom.exe install -y
cd "%LOCALAPPDATA%\RunSafe"
.\bin\runsafe_sbom.exe login -l <license_pulled_from_portal>
.\bin\runsafe_sbom.exe service start

# 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 --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 as RUNSAFE_LICENSE_KEY, 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 login
    - runsafe_sbom service start
    - runsafe_sbom -- make -C hello/
    - runsafe_sbom generate --output-file hello.cdx.json
  artifacts:
    paths:
      - hello.cdx.json

License Acquisition​

New Account Creation​

Where To Find the License Key​

Offline License Verification​

Installation​

Linux​

Windows​

Initialization​

Linux​

Windows​

Usage​

RunSafe SBOM Service​

Build Integration​

Not Recommended: Shared RunSafe SBOM Service Configuration​

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​

Upgrading​

Linux​

Windows​

Uninstalling​

Linux​

Windows​

Environment Variables​

Commandline Arguments​

Wrapping Compilation​

Config​

Generate​

Service​

Report​

Logs​

Platform​

Login​

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

Installation

Linux

Windows

Initialization

Linux

Windows

Usage

RunSafe SBOM Service

Build Integration

Not Recommended: Shared RunSafe SBOM Service Configuration

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

Upgrading

Linux

Windows

Uninstalling

Linux

Windows

Environment Variables

Commandline Arguments

Wrapping Compilation

Config

Generate

Service

Report

Logs

Platform

Login

Configuration File Settings

Example Process: Hello World

Linux

Windows

Example GitLab CI Yaml