To create an SBOM file with Pascal Analyzer, you may have to enter data in INI-files as key-value pairs. Pascal Analyzer will create templates for these INI-files. In the configuration dialog there are buttons to create and save different kinds of template files.
There is great flexibility for how these INI-files are handled. You can select which INI-files to include, or let Pascal Analyzer find them automatically. When generating the SBOM file in JSON format, Pascal Analyzer reads these INI-files, validates and uses their contents to build the resulting JSON file.
There are four kinds of INI-file templates:
- metadata INI-file template
- general INI-file template
- first-party INI-file template
- third-party INI-file template
The INI-file for the metadata section is central, and provides information about the SBOM itself. This INI-file only contains the required metadata section of the SBOM. Some data for this section can be set directly in the configuration dialog. For remaining data you will need to use an INI-file.
The second INI-file is the general INI-file, which is optional. If you want to add any other elements apart from components and dependencies, like for example known vulnerabilities to the SBOM, you will have to create and edit this kind of file.
First-party files are automatically added as components to the SBOM by Pascal Analyzer. These are files that are referenced in your project and that Pascal Analyzer can find and parse.
You can optionally provide a single INI-file template for your first-party files. This is needed if you want to add specific mutual values for your files, like version number. The version number will then be applied to each component element that is created for every first-party file. Some important data for first-party files can also be set directly in the configuration dialog.
There is also great flexibility when it comes to decide which files you consider first-party files. Normally it is only the files that you create and control yourself.
Third-party files on the other hand are external. They can be automatically recognized by Pascal Analyzer. We keep a growing list of popular third-party libraries, including for example OmniThreadLibrary and Spring4D.
You can also provide INI-files for third-party components that are not automatically recognized. Also use an INI-file if you want to replace and/or extend the data for third-party components that are automatically recognized.
These third-party INI-files include at least one rootfolders key. The value for this key is used to match against file paths, allowing a file to be associated with a particular third-party component. You can also leave the rootfolders value empty. This will lead to the third-party component always being included in the SBOM, without the need for any matching file path.
INI-files are probably best edited in a standalone text editor, like Notepad++ or RAD Studio itself. For each key you can enter a value. Most of the keys are optional, but some are required. There are also keys that are deprecated. The INI-file templates contain all possible keys, even if you will only use a few of them.
The INI-file templates that are produced by Pascal Analyzer, contain all possible key-value pairs for the selected type of template. For example, the metadata INI-file template will contain the “metadata” section key-value pairs. The general INI-file template contains all sections except “metadata” and “components”. First-party and third-party INI-files will only contain the key-value pairs for the “components” section.
All INI-file lines that contain empty values (after “=”) are ignored when reading and converting to JSON. This means that you can just leave them as they are. Do not delete them from the template.
Values after “=” are trimmed. Thus, any leading or trailing whitespace is deleted. So, it does not matter if you write “=MyProject” or “= MyProject”.
Comments are allowed in the INI-file, on lines that start with “;”. It is also possible to include comments on the key-value pair lines, as the last part of the line. All content from the last “;” on a line is interpreted as a comment. This means that you can add your own comments to the INI-file, either as separate lines, or as trailing comments on any line.
It is also possible to enter values that stretch over several lines (multi line values). On the first line, add "@" as the last character of the value string. On this line you can have comment starting with ";" but the "@" should be placed before the comment starts. All following lines that end with "@" will be interpreted as part of the multi-line value. The "@" characters will be converted to "\n" (line-break) in the JSON file.
Example:
...
metadata.component.description=This is a long description @
for my product.@
It is split over several lines.@
metadata.component.scope=
...
Here the value for metadata.component.description is split over several lines.
In the resulting JSON file it will be rendered as:
"description" : "This is a long description \\nfor my product.\\nIt is split over several lines."
Many keys in the INI-files function like arrays, for example components1. If you need another element, just copy all components1 to components2 etc. But make sure to keep the order, so all components1 keys come before components2 etc.
When filling out the INI-files it is important and helpful to consult the official documentation from CycloneDX, for the current 1.7 version: https://cyclonedx.org/docs/1.7/json/. This page contains information about each key in the SBOM, if it is required or optional, or even deprecated. Plus, it provides background information about the keys and their usage. INI-files may be saved anywhere. But a good idea may be to keep them in the same folder as your Pascal Analyzer project files (*.pap).
Also, to generate SBOM, you should make sure to select “All files” in the project properties dialog. The SBOM should always be based on all found files. In contrast with other Pascal Analyzer reports, it does not matter if files are included for reporting or not. Just make sure, as you always should in Pascal Analyzer, that all source files are found.
To finally create the SBOM: just run the report. If everything is successful, a JSON file will be created. In the report viewer you can also investigate any issued errors or warnings. You can of course make adjustments and rerun the report as many times you want.
By using our console application PALCMD.exe which is included with Pascal Analyzer, you can generate an SBOM integrated with your build process.
See also:
