github.com/vchain-us/vcn@v0.9.11-0.20210921212052-a2484d23c0b3/docs/user-guide/bom.md

# Bill of Materials (BoM)

`vcn` can identify, authenticate and notarize dependencies of the software assets.

## Supported languages/environments

| Language(s)/environment | Component scheme | Source | Package manager |
|-|-|-|--|
| Go | `gocom` |compiled binary | |
| | | directory with `go.sum` file | |
| | | directory with `*.go` file(s) | |
| Python | `pythoncom` | `Pipfile.lock` file or directory containing this file | pipenv |
| | | `poetry.lock` file or directory containing this file | poetry |
| | | `requirements.txt` file or directory containing this file | pip |
| JVM (Java, Scala, Kotlin) | `javacom` | JAR file containing `pom.xml` | maven |
| .Net (C#, F#, Visual Basic) | `dotnet` | `*.sln` file or directory containing this file | NuGet |
|   - C#, F# only| | `*.csproj` file or directory containing this file | |
|   - Visual Basic only| | `*.vbproj` file or directory containing this file | |
| JavaScript | `nodecom` | `package-lock.json` file or directory containing this file | npm |

## Working with builds

### Resolving dependencies

`vcn bom <source> [--bom-file <BoM file>] [bom output options]`

This command resolves the dependencies for the source and prints out the list of dependencies. If `--bom-file` option is specified, it also stores the dependencies in the file for processing by notarization process.

Examples:
```
vcn bom immudb/immuclient
vcn bom immudb-py --bom-spdx immudb-py.spdx
vcn bom immudb-py/requirements.txt --bom-file .bom
```

### Authentication

`vcn a --bom <source> [bom options] [bom output options]`

This command resolves the dependencies for the source, authenticates the dependencies and the source, and prints out the list of dependencies with their trust levels.

Following options modify the behavior of this command:

| Option | Default | Description |
|-|-|-|
| `--signerID` | current user | Signer ID to use for dependency and asset authentication. This isn't a BoM-specific options, but it has a special meaning for BoM |
| `--bom-trust-level` | `trusted` | Minimal accepted trust level for the dependencies (or its abbreviation), one of: |
||| `untrusted` (`unt`) |
||| `unsupported` (`uns`) |
||| `unknown` (`unk`) |
||| `trusted` (`t`) |
| `--bom-max-unsupported` | `0` | Max number of unsupported/unknown dependencies to accept, in percent. If number of unsupported/unknown dependencies doesn't exceed this threshold, authentication is considered successful |
| `--bom-file` || Name of the file to store dependencies for later processing by notarization process |
| `--bom-deps-only` |`false` (unset) | Authenticate only the dependencies, do not authenticate the BoM source|

Any of this options (except `--signerID`) implies `--bom` mode.

This command returns one of the following exit codes:

- `0` - success
- `1` - any dependency or BoM source is untrusted
- `2` - any dependency or BoM source is unknown and there are no untrusted or unsupported dependencies
- `3` - any dependency or BoM source is unknown and there are no untrusted dependencies

Examples:
```
vcn a immudb/immuclient --signerID auditor --bom-deps-only
vcn a immudb/cmd/immudb/ --bom-trust-level 3 --bom-spdx immudb.spdx --bom-file .bom
vcn a immudb-py --bom-max-unsupported 12.5
```

### Notarization

`vcn n --bom <source> [bom options] [bom output options]`

This command resolves the dependencies for the source, authenticates and notarizes the dependencies (only the non-notarized ones which are not untrusted or unsupported) and the source, and prints out the list of dependencies with their trust levels.

Following options modify the behavior of this command:

| Option | Default | Description |
|-|-|-|
| `--bom-signerID` | current user | Signer ID to use for dependency authentication |
| `--bom-force` | `false` (unset) | Force notarization of all dependencies regardless of their trust levels. If unset, only unsupported and unknown dependencies are notarized. Also forces cascade operation |
| `--bom-file` || If specified, `vcn` uses the data from this file, previously created by `vcn bom` or `vcn a`,rather than resolve the dependencies (it may greatly improve the performance) |
| `--bom-deps-only` |`false` (unset) | Notarize only the dependencies, do not notarize the BoM source|
| `--bom-hashes` || If specified, don't resolve the dependencies but use components with provided hashes as dependencies. These components must be trusted. This option is incompatible with `--bom-deps-only` and BoM output options |

Any of this options implies `--bom` mode.

Examples:
```
vcn n immudb/immuclient --bom-signerID auditor --bom-deps-only
vcn n immudb/immudb/cmd/immudb/ --bom-trust-level 3 --bom-file .bom --attr version=v1.2.3
vcn n immudb-py --bom-force --bom-spdx immudb.spdx --attach immudb.spdx
```

### Output options

User can specify one or several options to output BoM in different supported standard formats.

| Option | Description |
|-|-|
| `--bom-spdx` | Name of output SPDX tag-value file |
| `--bom-cyclonedx-json` | Name of output CycloneDX JSON file |
| `--bom-cyclonedx-xml` | Name of output CycloneDX XML file |

Any of this options implies `--bom` mode.

## Working with individual components

`vcn a|n|ut|us <scheme>://<name>@<version> | --hash <hash>`

Individual components are authenticated/notarized/unsupported/untrusted as any other asset, but you need to specify either component hash with `--hash` option, or component path in the form `<scheme>://<name>@<version>`. Scheme specifies the type of software component, and should be the one from the [supported types](#supported-languagesenvironments).

Examples:
```
vcn a gocom://golang.org/x/text@v0.3.6
vcn n --hash 691631371bfa886425c956999a4e998181036be260d7c0f179b3d2adde9b8353
vcn ut pythoncom://six@1.14.0
```

## Looking up builds by dependency

`vcn a --bom-what-includes (<scheme>://<name>@<version> | --hash <hash>)`

This command lists all assets where specified component is used as a dependency. Component must be specified by hash with `--hash` option, or component path in the form `<scheme>://<name>@<version>`. Scheme specifies the type of software component, and should be the one from the [supported types](#supported-languagesenvironments).

Examples:
```
vcn a --bom-what-includes gocom://golang.org/x/text@v0.3.6
vcn a --bom-what-includes --hash 691631371bfa886425c956999a4e998181036be260d7c0f179b3d2adde9b8353
```

## Support for Docker

`vcn <command> docker://<image>:<tag> [command options] [--bom-container-binary <list_of_binaries>]`

When asset has `docker` scheme, `vcn` starts the container for the specified `<image>:<tag>` and finds the dependencies, therefore it is required that docker daemon is running and required image is already pulled to the system. Supported Linux distributions that use `apk` (Alpine), `dpkg` (Debian, Ubuntu) or `rpm` (RedHat, Fedora, CentOS, AlmaLinux, openSUSE etc.) package managers.

If `--bom-container-binary` is specified, `vcn` only processes the packages, required for the specified dynamically-linked binaries, otherwise it processes all the installed packages.

Examples:
```
vcn bom docker://alpine:latest --bom-spdx docker.spdx
vcn a --bom docker://debian:latest --bom-container-binary /usr/bin/wget,/usr/bin/curl
vcn n --bom docker://nginx:stable-alpine --bom-container-binary /usr/sbin/nginx
```

## Cascade operations

`vcn notarize|untrust|unsupport [command options ...] --bom-cascade [--bom-force]`

It is possible to automatically propagate the action on the asset to other assets that include the one being processed, by specifying `--bom-cascade` option.

When this option is specified, `vcn` shows the list of assets that include current one, which has a status, different from desired one, and requests the confirmation (unless `--bom-force` is specified) from the user.

Examples:
```
vcn n --hash 0fcc60c04098ec262fc7e6369f8b01cfddc99fd251bf1762cb2a3c0937ee29a6 --bom-cascade
vcn untrust gocom://gopkg.in/yaml.v2@v2.4.0 --bom-cascade --bom-force
```