Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

WIP: Add Filter Documentation #10

Draft
wants to merge 1 commit into
base: main
Choose a base branch
from
Draft

WIP: Add Filter Documentation #10

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
293 changes: 293 additions & 0 deletions ics_sbom_libs/sbom_import/FilterSpec.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,293 @@
# ISCBOM Filter Spec

## Intro

The `icsbom` application takes in SBOM input files, looks for the packages in the SBOM files, and will produce a report
of all the CVEs for each package that it finds. Unfortunately, not all SBOMs are complete or have accurate information
To fix this we use a filter file to adjust the information coming from the SBOMs packages. This document describes the
filter format used when processing the SBOM files.

## File Format

The base form of the filter file is a JSON document and it follows this basic form:

```json
{
"packageName": {
"action": {
"actionProperty": "propertyValue"
},
...
}
}
```

Below is an example of renaming a simple package:

```json
{
"libcurl3": {"rename": "libcurl"}
}
```

In the example, we see that if the package `libcurl3` is found, that the action `rename` should be applied to the package
renaming it to `libcurl`.

## Actions

### Package Actions

The table below describes the different actions that can be applied to packages within the SBOM.

<table>
<tr><td>Action</td><td>Parameter</td><td>Description</td></tr>
<tr>
<td>

`"rename"`

</td>
<td>

`"<new_name>"`

</td>
<td>

This action renames a package from what is found in the SBOM file to what is listed in `<new_name>` as its replacement.

```json
{
"libcurl3": {"rename": "libcurl"}
}
```

</td>
</tr>
<tr>
<td>

`"remove"`

</td>
<td></td>
<td>
Removes the package from the SBOM package list. It will not appear in the resulting VEX report.
</td>
</tr>
<tr>
<td>

`"duplicate"`

</td>
<td>

`{<actions>}`

</td>
<td>

This action duplicates the SBOM package, but requires `<actions>` to know what to do with either the original or the duplicate.

```json
{
"qtbase": {
"duplicate": {
"rename": "qt"
},
"sub_cpe": {
"product": {
"orig": "qt",
"new": "<name>"
}
}
}
}
```
</td>
</tr>
</table>

### CPE Actions:

The following table describes the actions that can be applied to the CPE string for a package within the SBOM. The parts
that are currently available to be changed in the CPE string are `"vendor"`, `"product"`, and `"version"`. These will be
placed in the CPE string, `"cpe:2.3:a:<vendor>:<product>:<version>:*:*:*:*:*:*:*"`, for the package the action is being
applied too.

When setting the `"product"` and `"version"` of the cpe filter, you can use `"<name>"` and `"<version>"` for those
key/value pairs respectively. `"<name>"` will automatically fill in the cpe `"product"` value with the package name.
`"<version>"` will automatically use the package version from the SBOM package description to fill in the version number
of the string. You can use any other strings for the `"product"` and `"version"` fields as well.

<table>
<tr><td>Action</td><td>Parameter</td><td>Description</td></tr>
<tr>
<td>

`"add_cpe"`

</td>
<td>

```json
{
"vendor": "<cpe_vendor>",
"product": "<cpe_package_name>",
"version": "<cpe_package_version>"
}
```

</td>
<td>

Adds a new CPE string to the package. This command should be used with all three CPE string parts: `"vendor"`,
`"product"`, and `"version"`. The examples below are two filters that we use. As can be seen, for `"perl"` we are using
the SBOM name and version, and for `"libflac8"` we give it a specific product name.

```json
{
"libflac8": {
"add_cpe": {
"vendor": "flac_project",
"product": "flac",
"version": "<version>"
}
},
"perl": {
"add_cpe": {
"vendor": "perl",
"product": "<name>",
"version": "<version>"
}
}
}
```

</td>
</tr>
<tr>
<td>

`"sub_cpe"`

</td>
<td>

```json
{
"<cpe_part>": {
"orig": "<cpe_part_match_criteria>",
"new": "<replacement_value>"
},
...
}
```

</td>
<td>

The `"sub_cpe"` action modifies in-place any CPE string found in the SBOM package its filtering. The substitutions can
be stacked into the same action call making multiple modifications. Each step uses the same format. When specifying
the `"orig"` matching criteria, a glob (`"*"`) can be used to tell the filter to replace the `"<cpe_part>"` in all CPE
strings found for that package.

**NOTE:** There is currently no support for partial matching.

```json
{
"flac": {
"sub_cpe": {
"vendor": {
"orig": "*",
"new": "flac_project"
},
"product": {
"orig": "libflac",
"new": "<name>"
}
}
}
}
```


</td>
</tr>
<tr>
<td>

`"rem_cpe"`

</td>
<td>

```json
{
"<cpe_part>": "<cpe_part_match_criteria>"
}
```

</td>
<td>

This action removes the CPE string that matches the CPE part criteria from the SBOM package.

```json
{
"curl": {
"rem_cpe": {
"product": "libcurl"
}
}
}
```

</td>
</tr>
</table>

## Current Filter

Below, is the current filter used as default in the ICS_SBOM_LIBS.

```json
{
"qtbase": {"duplicate": {"rename": "qt"}, "sub_cpe": {"product": {"orig": "qt", "new": "<name>"}}},
"qtsvg": {"sub_cpe": {"product": {"orig": "qt", "new": "<name>"}}},
"qtdeclarative": {"sub_cpe": {"product": {"orig": "qt", "new": "<name>"}}},
"qtgraphicaleffects": {"sub_cpe": {"product": {"orig": "qt", "new": "<name>"}}},
"qtmultimedia": {"sub_cpe": {"product": {"orig": "qt", "new": "<name>"}}},
"qtquickcontrols": {"sub_cpe": {"product": {"orig": "qt", "new": "<name>"}}},
"qtquickcontrols2": {"sub_cpe": {"product": {"orig": "qt", "new": "<name>"}}},
"qtserialport": {"sub_cpe": {"product": {"orig": "qt", "new": "<name>"}}},
"qttools": {"sub_cpe": {"product": {"orig": "qt", "new": "<name>"}}},
"qtvirtualkeyboard": {"sub_cpe": {"product": {"orig": "qt", "new": "<name>"}}},
"qtwebsockets": {"sub_cpe": {"product": {"orig": "qt", "new": "<name>"}}},
"qtxmlpatterns": {"sub_cpe": {"product": {"orig": "qt", "new": "<name>"}}},
"flex": {"add_cpe": {"vendor": "westes", "product": "<name>", "version": "<version>"}},
"dbus": {"duplicate": {"rename": "libdbus", "sub_cpe": {"product": {"orig": "dbus", "new": "<name>"}}}},
"flac": {
"sub_cpe": {
"vendor": {"orig": "*", "new": "flac_project"},
"product": {"orig": "libflac", "new": "<name>"},
}
},
"bzip2": {"add_cpe": {"vendor": "bzip", "product": "compress-raw-bzip2", "version": "<version>"}},
"libflac++6": {"add_cpe": {"vendor": "flac_project", "product": "flac", "version": "<version>"}},
"libflac8": {"add_cpe": {"vendor": "flac_project", "product": "flac", "version": "<version>"}},
"curl": {
"duplicate": {"rename": "libcurl", "rem_cpe": {"product": "curl"}},
"rem_cpe": {"product": "libcurl"},
},
"libcurl3": {"rename": "libcurl"},
"libcurl4": {"rename": "libcurl"},
"expat": {
"duplicate": {"rename": "libexpat", "rem_cpe": {"product": "expat"}},
"rem_cpe": {"product": "libexpat"},
},
"file": {"add_cpe": {"vendor": "file_project", "product": "<name>", "version": "<version>"}},
"perl": {"add_cpe": {"vendor": "perl", "product": "<name>", "version": "<version>"}},
}
```