(unclickable, full content)Codenotary Trustcenter User Guide v3.1.4 with extended search

1. Getting started 

2. TC Dashboard

2.1 Creating users

Role-based Permissions

To Create a New User

Managing Existing Users

User Management Options

Azure AD integration

2.2 Create Ledger

Errors Creating a Ledger

Ledgers Page

Ledger Management Features

Querying a Ledger

2.3 Create Ledger API Key

2.4 Query a ledger

To Run a Query

Search terms

Search by artifact name

Other fields to search

Available fields

Sorting

Export Query Results

Extended Search Capabilities

Available fields

Advanced syntax

Regular expressions

Multivalue field (eg. metadata, labels)

DateTime fields

2.5 Get messages and notifications

The Messages Page 

Acknowledging a Message

View Message Detail

Message Types

3. VCN - Command Line Interface

3.1 Quick start

3.1.1 Install

3.1.2 Login

3.1.2 Authenticate digital objects

3.1.3 Notarize digital objects

3.1.3 Labels

Adding and removing labels

Viewing current labels

Authenticating with labels

3.1.4 Attachments

3.1.5 Metadata attributes

3.1.6 Software Bill of Materials (SBOM)

Working with builds

Resolving dependencies

Authentication

Notarization

Output options

Looking up builds by dependency

Cascade operations

3.1.7 Extra commands

Getting more information about vcn

Authenticate multiple assets

Authenticate by a specific signer

Wildcard support and recursive notarization

Authenticate using the asset's hash

1. Getting started 

Codenotary Trustcenter (formerly known as Codenotary Cloud - CNC) service has three main components, and their communication is defined in Figure 1.

Figure 1 - TrustCenter architecture ● TC Dashboard - it’s a web platform that allows you to perform

○ User management 

○ Ledger management 

○ Credentials management (API Key, Signer ID) 

○ Profile management 

○ Artifact search 

○ Exploring dependency tree

● VCN - it’s a command-line interface that allows you to to login with API Key and perform the following: 

○ Notarize assets 

○ Authenticate assets 

○ Software Bill of Materials 

○ Upload assets

○ Inspect assets 

● TC APIs 

○ All the actions that can be performed on dashboard are available via API REST 

○ APIs for Notarization, Authentication and the main VCN features 

Appliance info: 

● VCN general download link: downloads.codenotary.com 

○ username: cnccli 

○ password: GetCLI4CNC  

2. TC Dashboard 

In this section explore how the GUI is used for: 

● Creating users 

● Creating a ledger 

● Creating an API Key and a signerID for a Ledger 

● Querying a Ledger 

● Getting messages and notifications

2.1 Creating users 

To add a user to the system, you'll need their email address, desired username, their role in the system and, optionally, their first and last name.  

Role-based Permissions 

Note that some limitations to user administration are imposed by your assigned role.

● Tenant admin - Full read-write access to all functions in the UI. 

● Ledger admin - Read-write access to user functions in the UI, but no access to admin functions. Can create a ledger, can update and delete its own ledgers. Can create, rotate and delete API keys for ledgers created by her/him. 

● Auditor - Read-only permissions on Ledgers and their contents. Will see an empty Home page. Can’t create Read only API key. 

● Visitor - only basic access

To Create a New User 

1. Go to the Local users page 

2. Click the Add user button in the upper right. 

3. Complete the form by filling in the following fields: 

○ User name 

○ email address 

○ password 

○ first name (optional) 

○ last name (optional)

4. Select a role from the User role drop down menu. 

5. Click the Create user button.

You can change any of these parameters after creating a user, provided you have appropriate permissions.

Managing Existing Users 

Tenant admin can quickly change or delete a user's account from the options popup menu by clicking the gear icon in the users row.

User Management Options

All options open a simple text form that lets you enter changes.

Azure AD integration 

Trustcenter integrates with Azure for user management. To receive a detailed manual please contact the Codenotary support team.

 2.2 Create Ledger 

A ledger is like a separated database and API keys in the same ledger have the ability to verify notarized assets of each other. Therefore it is recommended to create a ledger whenever data separation is required, i. e. different developer teams, different asset types, different locations.  

New Ledgers are created in the web UI from the Home page by clicking the + Add Ledger button.

Alternatively you can navigate to the Ledgers page from the left-side navigation bar. The Ledgers page opens.

    1.Click the + Add Ledger button. The Define Ledger panel opens. 

2.Enter a unique Ledger name in the Ledger name field. Your Ledger name appears in tabular views. It must be globally unique and can contain only alphanumeric characters as well as dash and underscore ('-','_'). Note that you have the option to change the Ledger name at any time. Add Data Labels (optional) Under Data Labeling you can create one or more labels to associate with the Ledger. Enter a plain-text label and click + or hit the Enter key to add it. Click the X on any label to remove it. Labels are user-defined tags you can use to help categorize, group or otherwise track identifying aspects of the Ledger. The remaining is associated with the Ledger as metadata. Click the Next step button when you're ready to continue. The Define Signer ID panel opens.

Click the Previous step button to return to the Define Ledger panel.

3. Enter a unique name for the Signer ID in the Signer ID field. The key name must be globally unique, and can contain only alphanumeric characters as well as dash, underscore, dot and ‘at’ sign ('-', '_', ’.’, ‘@’). The key name is simply an identifier that allows you to select it in other contexts. 

4. Click the Next step button when you're ready to continue. The Summary panel opens.

• NOTE If you have exceeded the total number of Ledgers allowed by your user license you will see an error when you click the Next step button on the Define Signer ID panel. (See Errors Creating a Ledger below.) 

• Click the Previous step button to return to the Define Signer ID panel.

Errors Creating a Ledger 

A red error message may pop up If the system can't validate or process an entry, or if your action exceeds limits set by your user license. Most error messages explain in detail what the problem is.

Illegal characters 

Most text fields in the UI will accept numbers and letters, as well as dashes and underscores. 

Be sure to remove punctuation and spaces to ensure your text is validated. 

Duplicate name 

All Ledger names and Signer IDs must be unique across the entire system. Rename the Ledger if this happens.  

Ledgers Page 

The Ledgers page displays a searchable (by name), paginated table of all Ledgers in the system. The top-level Ledgers page lists all the Ledgers currently defined in the system, along with usage information.

• Clicking the name of the ledger directs to the Ledgers/Query Ledger page 
• By clicking the Actions icon, privileged users can enable/disable a Ledger. Clicking on a Ledger name takes you to its Dashboard page.

Ledger Management Features 

After a Ledger is created, you can enable/disable it, generate new Signer IDs or delete keys no longer in use and query it. To access management tools, select the appropriate tab at the top of the page.  

Managing Signer IDs 

The Signer IDs tab lists every API configured for the selected Ledger - its name, type (SDK, CI/CD, Postgres), and most recent usage date. You can have multiple Signer IDs for the same Ledger. That way you can assign a unique key to each application when you have more than one access to the same Ledger. 

By clicking the Actions icon you can add new keys, get the value for existing keys, delete a key or show the Signer ID (for CI/CD keys). 

    Caution: Deleting a Signer ID here will prevent any application currently using it from authenticating with the API.

To create a new Signer ID by clicking on "Create Signer ID" and provide a Signer ID. Only alphanumeric characters, plus dash, underscore, dot and ‘at’ sign ('-', '_', ‘.’, ‘@’) are valid. After creating your Signer ID, you can copy it or download to a file on your local system. 

To copy the Signer ID string to the clipboard, click the copy icon to the right of the key. Once a key is created, if you need to reset it, you can use the Rotate key function. 

NOTE Once a key is created, if you need to reset it, you can use the Rotate key function. If you suspect a key is compromised, you can also use the "Revoke key" option to disable it from being used. Assets notarized with a revoked key will be not shown as trusted.

Querying a Ledger 

The Query Ledger tab lets you query Ledger contents directly through the UI. The functionality is described in detail in the

Query a Ledger chapter below. 

Note an important distinction between Ledger/Query Ledger tab and Query Ledger/Query tab that was introduced in TC 3.1. 

• The Ledger/Query Ledger tab allows you to query one ledger at the same time. You can see in the search bar that the previously selected ledger’s name is there. You can remove or edit the signer_id term. 
• In the Query Ledger/Query tab you can search all ledgers at the same time. The search term ledger_name is optional here.

2.3 Create Ledger API Key 

The Signer ID is used to identify and route data to the correct ledger. The Signer ID creation is automatically creating a unique API Key as well that can be used to verify notarized assets. 

2.4 Query a ledger 

There are two tabs on the Query Ledger page. The default tab is Query, where the search form is. The second tab Read-only Signer IDs redirects to a page where you can create a Signer ID that serves for authentication or inspection of artifacts in the vcn tool on all the ledgers.

You can run queries from the Query Ledger tab on the Ledgers page (described above) or from the Query tab on the Query Ledgers page. Note and important distinction between Ledger/Query Ledger tab and Query Ledger/Query tab that was introduced in TC 3.1: 

• The Ledger/Query Ledger tab allows you to query one ledger at the same time. You can see in the search bar that the previously selected ledger’s name is there. You can remove or edit the signer_id term. 
• In the Query Ledger/Query tab you can search all ledgers at the same time. The search term ledger_name is optional here. 

The form at the top of the page lets you select filter parameters, run the query and export results to a CSV file. Trustcenter allows you to search for artifacts notarized in the vcn tool. An artifact is any object that was the target of the vcn notarize CLI command: container, dir, docker, dpkg, file, git, go, image, python etc. 

To Run a Query 

1. Fill out the search bar with search terms. Press Enter when you finish inserting any one of the search terms.

When you confirm a search term this way it turns into a chip in the search bar. You can delete it by clicking the ‘x’ or edit it by clicking anywhere else on the chip. 

You can move around the text using arrows on the keyboard. You can press Esc to escape from editing the search term.

Clicking anywhere on the search bar brings out the keyword auto-suggestion dropdown. You can choose the available keywords for your next search terms by clicking on them and completing it by entering the desired value. 

2. Next to the search bar you will find a DateTime field that allows you to filter the search results with regard to notarization time.

You can select either: 

• a period relative to the present moment using two dropdown fields at the top, ie. selecting number of periods and the period itself (hours, days, weeks) - “Relative” mode, 
• or specify the period manually by clicking on the calendar twice, first to choose the “From” date and the second time to choose the “To” date - “Absolute” mode. 

You can adjust the “From”and “To” times at the bottom of the component. 

Both conditions from the search bar and DateTime field are joined by the “AND” operator when executing the query to the database.

The search results update every time you add or modify the search terms and press Enter or modify the DateTime field. 

Search terms

You can enter one or many search terms in the search bar. Important notes: 

• The search is performed as if all the search terms were joined by “AND” operator so only those documents will be found that fulfill all the search criteria, 
• You can use asterisk * for searching for parts of the artifact name or in other fields described below, 
• The quotes “ are usually optional in search queries. They are mandatory if the value contains special characters such as dot, hyphen or other, 
• There are no spaces before and after the colon “:”.
• It is also possible to use “OR” in search bar if it is entered as one search term, for example enter name:*immudb* OR kind:dir and press Enter after the whole term to create one chip 

Search by artifact name

 name:html 

This example will search for the full name of an entry, eg. directories named “html”. 

name:*log4j*

This will search for documents that contain the string “log4j” as part of the name. 

name:log4j* 

This will search for document names that begin with the string “log4j”. 

name:*log4j 

This will search for document names that end with the string “log4j”. 

Other fields to search 

ledger_name:"l02" 

Search for all documents notarized in “l02” ledger. 

signer_id:"user1" 

Search for all documents notarized by SignerID “user1”. 

status:"untrusted"  

Search for all untrusted documents. Other options are “trusted” or “unsupported”. 

kind:"dir" 

Search for all directory artifacts. 

Available fields

Sorting 

The search results are sortable by clicking on the table header by: 

• artifact name, 
• kind,
• notarization date.

Export Query Results

After running a query, you can click the Export button to download a CSV file with the search results to your local hard drive. 

Extended Search Capabilities 

To verify if your license is extended with regards to search, check the License Management screen which is available in the top right corner:

If your license is extended with search capabilities, you should see the following line: 

With extended search the list of available fields to search in is the following: 

Available fields

Advanced syntax 

file_size:[0 TO 200] 

File size in range inclusive. 

Note: There are spaces before and after the “TO” keyword. 

file_size:{121 TO 126} 

File size in range exclusive. 

file_size:[121 TO *] 

File size equal or larger than 121. 

-kind:"dir" 

Artifact kind is other than “dir”. 

(ledger_name:test AND metadata:purl*) OR kind:php 

Example using AND and OR in one search. Searches for artifacts that are either in ledger test with metadata starting with purl or are PHP files. 

Note: Keywords such as “AND”, “OR”, “TO” must be spelled using capital letters. 

Regular expressions 

name:/[a-z]{5}/ 

You can also search using some functionality of regular expressions. The example searches for names that consist of five uncapitalized letters. 

Note: Regular expressions must be enclosed by ‘/’. 

name:/[a-z]{1}.{3}[0-9]{2}/ 

Find artifacts that have a letter in beginning, any 3 characters and ends with two digits. 

name:/.*\d{5,10}.*/ 

The artifact name contains a string that is made of 5 to 10 consecutive digits anywhere in it. 

Note: When using the regular expressions it may take a little longer for the results to appear.

Multivalue field (eg. metadata, labels) 

metadata:(*) 

Returns documents with a nonempty metadata field. 

metadata:(system* AND *GIT) 

In the strings set in metadata there is either a string beginning with “system” or ending with “GIT”. 

-labels:[* TO *] 

Searches for documents where field “labels” does not exist (no labels have been specified). 

DateTime fields 

It is preferable to conduct the search for DateTime (local time) using the dedicated field (which filters results using the notarized time). However, you can also include date and time conditions using syntax similar to the following examples. Please be aware, that both these fields will be considered in parsing and returning the search results conforming to conditions from both fields. 

notarized_time:["2022-08-15T09:11:25.887Z" TO "2022-08-16T09:11:25.887Z"] 

Searching in a declared time period in a typical timestamp format. 

notarized_time:[NOW-1DAY TO NOW] 

Last 24 hours. 

notarized_time:[NOW-1MONTH TO NOW] 

Last month. 

notarized_time:[NOW/HOUR-1DAY TO NOW/HOUR] 

Period from yesterday at the beginning of the current hour to today at the beginning of the current hour.  

2.5 Get messages and notifications

The Codenotary Cloud platform reports resource usage and displays such information on the Messages page in tabular format. Users can see separate lists to distinguish active messages from those that have already been read and acknowledged. 

Note: in TC 3.1 the number of messages has been limited in comparison to the previous version to show only important messages about resource usage. 

All new messages are displayed on the Messages page under the Active messages tab. When any new messages are waiting to be read, the UI alerts users in three different locations: 

1. Alert Icon 

2. Home Page The messages panel on the Home page turns red and indicates the number of messages waiting.

3. Ledger Management Page For messages related to a particular Ledger, the messages panel on the management page for that Ledger red and indicates the number of messages waiting. 

Additionally, the platform can see notification emails automatically through your SMTP server. Any number of recipients can be configured, and TO addresses are not constrained to users configured in the system.

The Messages Page 

The Messages page consists of two tabs - Active messages and Acknowledged messages. Messages listed on the Active messages tab have not yet been acknowledged by any user. 

After a user acknowledges a particular message, the system shifts it from the unread messages table and lists it under the Acknowledged messages tab.  

Acknowledging a Message 

To acknowledge any message, simply click the Acknowledge button on the far right of the row. 

View Message Detail 

To see the message detail, click any data field in the row. 

Message Types 

The system categorizes messages into the following types. 

• Tamper: suspected tampering ongoing on a Ledger (a malicious user could have tried to edit or forge data). 
• Application: issue with receiving data from an external source (plugin, SDK). 
• License: license expiration warning. 
• Memory: low memory warning. 
• Disk: low disk space warning. 
• CPU: high CPU usage warning. 
• Container: unhealthy status for an application component.

3. VCN - Command Line Interface

3.1 Quick start

3.1.1 Install 

In order to download VCN, please check the latest version here: https://downloads.codenotary.com 

username: cnccli 

password: GetCLI4CNC 

We recommend storing vcn in your PATH - Linux example: 

sudo cp vcn-v-linux-amd64 /usr/local/bin/vcn

3.1.2 Login

vcn login --lc-host example.com 

Then enter the API Key. 

scripted: 

export VCN_LC_API_KEY=apikeyhere 

export VCN_LC_HOST=yourTCdomainhere 

export VCN_LC_PORT=443 

vcn login --lc-host example.com 

or 

VCN_LC_API_KEY=apikeyhere vcn login --lc-host example.com  

3.1.2 Authenticate digital objects

vcn authenticate<asset>

You can authenticate different types of objects: 

vcn authenticate <file>

vcn authenticate dir://<directory>

vcn authenticate image://<imageId>

vcn authenticate docker://<imageId> (deprecated, please use image) 

vcn authenticate podman://<imageId> 

vcn authenticate git://<path_to_git_repo> 

vcn authenticate --hash <hash>

Authenticate assets based on a signerID:

vcn authenticate --signerID identityname image://hello-world

Note: Support of bulk mode for authentication is planned.

3.1.3 Notarize digital objects

vcn notarize<asset>

You can notarize different types of objects: 

vcn notarize <file>

vcn notarize dir://<directory>

vcn notarize image://<imageId>

vcn notarize docker://<imageId> (deprecated, please use image)

vcn notarize podman://<imageId>

vcn notarize git://<path_to_git_repo> 

vcn notarize --hash<hash> 

Notarization can also be done using bulk mode and CSV file containing hashes, artifact names and optional list of labels. The format of csv file is as follows: 

<hash>, <name>, <semecolon separated list of labels>

example: 

FfBaFcAdbbCEADfFfEFfaeceEFdEAbfaBCCeBCeEdACAFAfDaadCEFACDCDcAFBE,test61504536,label33;attr433 dAdeceBEbCbbbaDCACBfaAfAebDFdeBBdcaFaEcBCBFDAcfeCDCDFAFFDBEDbfdB,test61504537,label39;attr39 DfaAbFCAffDEFEdDfCBCdBefAdfbBbEFDddcbbADfFCCAaaDeaBfBceAdbbFDCCA,test61504538,label46;attr146

To run notarization with import file: 

vcn notarize –import-file myFile.csv 

Furthermore, you can change the trust level 

vcn unsupport <asset>

vcn untrust<asset>

3.1.3 Labels 

Each artifact stored in the Codenotary Trustcenter can be assigned a set of labels that can be modified over time. 

Adding and removing labels 

Labels can be added, removed, or set with vcn notarize command. Multiple labels can be set using comma-separated argument values. Invoking the command for an artifact that was already notarized updates the labels list accordingly. 

To add labels: 

vcn n artifact --labels-add “label1,label2,label3” 

To delete labels: 

vcn n artifact --labels-del “label1,label2” 

To set (overwrite previous) labels: 

vcn n artifact --labels-set “label1,label2” 

The --labels-add, --labels-del and --labels-set argument also allows the use of a csv file with labels to be processed. It is automatically detected if the argument contains a single name ending with .csv 

extension: 

vcn n artifact --labels-add “./myLabels.csv”

The format of CSV file is one column list of labels: 

label1 

label2 

label3 

label4 

label77

The output of VCN notarize command with labels operation shows the operations that were performed for labels: 

Labels: label1 (added), label2 (added), label3 (added) 

Viewing current labels 

To see the current list of labels attached to the artifact you can use inspect command with –labels argument: 

vcn inspect artifact --labels --last 1 

Authenticating with labels

When authenticating assets you can specify a label to check against 

vcn authenticate artifact --label “label1” 

If the artifact was trusted and has label1 assigned, the status will be trusted. If the artifact was trusted and does not have label1 assigned, the status will be unknown. If the artifact was untrusted/unsupported and has a label1 assigned, the status will be untrusted/unsupported. If the artifact was untrusted/unsupported and does not have label1 assigned, the status will be unknown. 

Note: Support for authenticating against multiple labels is planned. 

3.1.4 Attachments

When notarizing an asset you can add attachments to the transaction: 

vcn n artifact --attach attachment1:label1 --attach attachment2:label1 --attach attachment3:label2 

This is especially useful when running a CI pipeline in multiple steps and each step provides a different result that should be attached (i. e. vulnerability scanner result, compliance scanner result, dependency scanner result). 

To retrieve these attachments you can either use the notarization transaction uid or the labels. When using the uid all attachments of the specific notarization transaction will be downloaded. 

vcn a go.sum --lc-uid 1624700334893475066 --output attachments  

When using labels you can either download a specific attachment or all attachments with the same label. 

vcn a go.sum --attach attachment2:label1 --output attachments 

vcn a go.sum --attach label1 --output attachments 

Another example that shows the artifact attachment's download across all notarizations. Upload attachments one at a time: 

vcn n asset.bin --attach file1.txt:labelXYZ 

vcn n asset.bin --attach file2.txt:labelXYZ 

vcn n asset.bin --attach file3.txt:labelXYZ 

# downloads all attached files 

vcn a asset.bin --attach labelXYZ --output attachments 

The label-only command --attach label1 downloads the latest version of all attachments that have the requested label. Existing files will not be overwritten. In case you want to download and overwrite existing files use the --force flag. If there are multiple versions of a specific attachment the file will be downloaded with an enumerated postfix. 

vcn a go.sum --attach lab1 --output attachments --force

3.1.5 Metadata attributes 

When notarizing an asset you can add metadata to the transaction in the form of attributes. 

To one custom attribute: 

vcn n artifact --attr “key=value” 

You can add as many attributes as needed in one transaction: 

vcn n artifact --attr “key=value” –attr “key2=value2”

These metadata attributes can be searched for in Trustcenter using the metadata keyword described in chapter Query a ledger. 

In practice metadata attributes could hold many useful information about the software artifact: build version, build pipeline, location, commit data, PGP Signature, data on approval process, supplier, flag if the software is internal or external, ID of employees involved, test coverage, environment, release data, production status and many more.  

3.1.6 Software Bill of Materials (SBOM)

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

Supported languages/environments

Working with builds

Resolving dependencies 

vcn bom  [bom options] [bom output options] 

This command resolves the dependencies for the asset and prints out the list of dependencies.

Following bom options modify the behavior of this command:  

See output options for details about outputting BoM in standard formats. 

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  [bom options] [bom output options]

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

Following bom options modify the behavior of this command:

Any of these options (except --signerID and --github-token) implies --bom mode. 

See output options for details about outputting BoM in standard formats. 

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 unknown --bom-spdx immudb.spdx --bom-file .bom

vcn a immudb-py --bom-max-unsupported 12.5

Notarization

vcn n --bom  [bom options] [bom output options] 

This command resolves the dependencies for the asset, authenticates and notarizes the dependencies (only the unknown one, is --bom-force is not specified) and the asset, and prints out the list of dependencies with their trust levels. 

Following options modify the behavior of this command:  

Examples: 

vcn n immudb/immuclient --bom-signerID auditor --bom-deps-only 

vcn n immudb/immudb/cmd/immudb/ --bom-file .bom --attr version=v1.2.3

vcn n immudb-py --bom-force --bom-spdx immudb.spdx --attach immudb.spdx 

Output options 

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

Option Description  

Any of these options implies --bom mode. 

Working with individual dependencies 

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. 

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 the specified component is used as a dependency. Components 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 (except docker scheme). 

Examples: 

vcn a --bom-what-includes gocom://golang.org/x/text@v0.3.6 

vcn a --bom-what-includes --hash 691631371bfa886425c956999a4e998181036be260d7c0f179b3d2adde9b8353 

Support for containers 

vcn  <command><scheme>://<image_or_container> [command options] 

Supported schemes: 

• docker - Docker image ID or tag, requires running docker deamon 
• container - Docker container ID or tag, requires running docker deamon 
• image - container image in container registry. URL format: image://[<registry_server>/]image_tag. If <registry_server> is not specified, Docker Hub is used. By default vcn tries to connect to the registry using active Docker session, however users can always override it by using image-registry-user/image-registry-password CLI parameters. 

For the image:// schema you can specify several additional options: 

• --image-docker-daemon - use local Docker as a container registry. Image must be pulled first. Usually vcn works much faster as it doesn’t need the network connection to Docker Hub or other registries. 
• --image-platform - in case when remote registry is used, you can optionally specify the platform, eg. --image-platform linux/amd64 . By default your local platform is used. 
• --image-tar - you can process archives of images if they are saved locally as tar files, using eg. vcn n image://alpine.tar --image-tar 
• If you intend to scan images from a remote registry (Docker Hub) you need to provide --image-registry-user and --image-registry-password. Other options are explained in help files.

If an asset is specified as a TAR file which contains exported images, vcn processes it as image. 

Examples:

vcn a --bom docker://alpine:latest --bom-spdx docker.spdx 

vcn a --bom container://magical_hoover 

vcn n --bom image://codenotary/immudb:1.3 --image-docker-daemon 

vcn n --bom image://my_registry.com/my_image --image-registry-user my_user --image-registry-password my_API_key 

vcn n --bom debian_11.tar

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 the --bom-cascade option. 

When this option is specified, vcn shows the list of assets that include the current one, which has a status different from the desired one, and requests 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

3.1.7 Extra commands

Getting more information about vcn

You can learn about all the options and ways vcn is working by issuing 

vcn --help 

More help on notarizing is available through: 

vcn n --help 

There is also help available for authenticating and other functions of vcn: 

vcn a --help 

vcn i --help 

…  

Authenticate multiple assets

You can authenticate multiple assets by piping other command outputs into vcn: 

ls | xargs vcn authenticate

The exit code will be 0 only if all the assets in your other command outputs are verified. 

Authenticate by a specific signer

By adding --signerID, you can authenticate that your asset has been signed by a specific SignerID. A SignerID is the signer's public address (represented as a 40 hex characters long string prefixed with 0x). 

vcn authenticate --signerID identityname docker://hello-world 

Be aware that using the --signerID flag will take precedence over VCN_SIGNERID. The asset authentication will succeed only if the asset has been signed by at least one of the signers. 

Wildcard support and recursive notarization

It's also possible to notarize assets using wildcards. With the --recursive flag it is possible to iterate over inner directories. 

./vcn n "*.md" --recursive 

Notarize all files in the current directory: 

./vcn n -r "./*"

Authenticate using the asset's hash 

If you want to authenticate an asset using only its hash, you can do so by using the command as shown below: 

vcn authenticate --hash fce289e99eb9bca977dae136fbe2a82b6b7d4c372474c9235adc1741675f587e