02.the-bomshell-model.md

2. The bomshell Model

In essence, bomshell is a runtime that executes small CEL scripts or programs we call "recipes". Recipes are statements that perform operations on SBOM data and evaluate to a result. This result will often be a new SBOM (a Document in protobom lingo). Expressions in protobom recipes can also evaluate to NodeLists or even Nodes.

An invocation of protobom has three main tasks:

1. It sets some options, according to defaults and user preferences
2. Preloads one or more SBOMs into the bomshell environment (not required).
3. Reads a protobom recipe and executes it.

The results are output to STDOUT by default. The results format can be configured by the user or an embedding application using the bomshell format.

The bomshell Runtime Environment

When execution starts, the recipe logic runs in an environment that has two predefined variables:

• A global bomshell object. This object houses the main functions that are not methods of the SBOM data elements (Documents, Nodes, etc).
• A collection of SBOMs. Any SBOMs preloaded into the runtime environment are parsed and exposed in a global sboms[] list. The list is a numerical array and documents are indexed in the order they were defined.

Expression Evaluation

All bomshell functions return an SBOM data elements such as Documents or NodeLists. En expression is said to evaluate as a result of the last function called. If a function is called and it returns a Document, the CEL expression evaluates to the Document.

The result of the evaluation will be output (to STDOUT by default). Documents can be output as standard SPDX or CycloneDX documents. NodeLists can be extracted in more data formats designed to work with data applications or converted to new Documents.