csbom 1.0.3

cli tool for analyzing sbom files

csbom cli tool

This is a cli tool that parses an SBOM outputted by Scribe Security valint tool, formatted as CycloneDX, and creates a csv file containing the following.

Installation

Notice: the tool is still in development, therefore it is suggested not to install it directly to your PATH. Instead, you could create a virtual python environment using python's virtualenv tool.

With this tool, you can create an environment with the command virtualenv <env_name>. virtualenv will create a directory in your current directory named <env_name>.

To activate your environment, on Linux/Mac you can run source <env_name>/bin/activate and on windows, .\env_name\Scripts\activate

To exit the environment, run deactivate and your terminal should go back to normal.

While in the venv, do this to install (this way, the tool will only be installed in the virtual environment):

Using the python package manager, run

pip install csbom==1.0.3

Example of installing and running csbom in a virtual environment:

# Create a virtual environment named `venv`
$ virtualenv venv
created virtual environment CPython3.10.10.final.0-64 in 159ms
  creator CPython3Posix(dest=<dest_path>, clear=False, no_vcs_ignore=False, global=False)
  seeder FromAppData(download=False, pip=bundle, setuptools=bundle, wheel=bundle, via=copy, app_data_dir=<app_dir> Application Support/virtualenv)
    added seed packages: pip==23.2.1, setuptools==68.0.0, wheel==0.41.0
  activators BashActivator,CShellActivator,FishActivator,NushellActivator,PowerShellActivator,PythonActivator

# Activate the virtual environment
$ source venv/bin/activate

# Install csbom tool
(venv) $ pip install csbom==1.0.3
Collecting csbom==1.0.3
  Obtaining dependency information for csbom==1.0.3 from https://files.pythonhosted.org/packages/9f/17/0350e4e05ed2a2adfa349a0da074e46f65f0a9d66ddecc485541eb78f799/csbom-1.0.1-py3-none-any.whl.metadata
  Downloading csbom-1.0.1-py3-none-any.whl.metadata (5.6 kB)
Collecting click>=7.1.2 (from csbom==1.0.3)
  Obtaining dependency information for click>=7.1.2 from https://files.pythonhosted.org/packages/00/2e/d53fa4befbf2cfa713304affc7ca780ce4fc1fd8710527771b58311a3229/click-8.1.7-py3-none-any.whl.metadata
  Downloading click-8.1.7-py3-none-any.whl.metadata (3.0 kB)
Downloading csbom-1.0.3-py3-none-any.whl (10 kB)
Downloading click-8.1.7-py3-none-any.whl (97 kB)
   ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 97.9/97.9 kB 3.7 MB/s eta 0:00:00
Installing collected packages: click, csbom
Successfully installed click-8.1.7 csbom-1.0.3

# Now, you can run csbom in your virtual environment!
(venv) $ which csbom
.../venv/bin/csbom

# Using the csbom tool
(venv) $ csbom dep2table bom.json -o analysis.csv
Dependency table successfully generated at `analysis.csv`!

# To exit the virtual environment
(venv) $ deactivate

# Notice that the (venv) disappears after calling deactivate
$ exit

The tool can still be installed and run normally without a virtual environment, this is just an example for how to install it exclusively in a virtual environment.

Usage & Explanations

csbom CMD [OPTIONS] ARG

General Options:
--help: display help information
-o (--output): Choose output filename (default dep/file/commit-analysis.csv, depending on command)
-a (--append-to): Optional, if present, csbom will append the output to the already existing csv specified \

Commands:
dep2table: Given an SBOM generated with the '--components files' flag, output a table of important info,
file2table: Given an SBOM as the argument, outputs a table of components of type file,
git2table: Given an SBOM generated from a Git repo (with --components commits), outputs a table with all commit information,
version: displays current version

file2table
This command takes the SBOM and generates a CSV with 5 columns, bomref, name, hash, mimetime, mode, and last_commit Each row contains an entry from the components array in the SBOM file with the corresponding information. If a component does not contain an entry for any of these 5 categories, it will be marked as None

dep2table
This command creates a CSV table of depender components mapped to dependee components, with information of name, type, purl, hashes, and group for each component.

git2table
This command creates a CSV table of git commits with 6 columns, bomref, type (which should always be commit), name, commit-author, commit-message, and commit-timestamp, for each commit in the SBOM.

version displays the current version information