vcn

README

vcn

** CodeNotary.io & CNIL vcn CLI for notarization and authentication of digital artifacts**

The Trust and Integrity platform for the Cloud native environment

Give any digital asset a meaningful, globally-unique, immutable identity that is authentic, verifiable, traceable from anywhere.

When using CodeNotary vcn in source code, release, deployment or at runtime, you allow a continuous trust verification that can be used to detect unusual or unwanted activity in your workload and act on it.
Powered by CodeNotary's digital identity infrastructure, vcn lets you notarize all of your digital assets that add a trust level of your choice, custom attributes and a meaningful status without touching or appending anything (unlike digital certificates). That allows change and revocation post-release without breaking any customer environment.
Everything is done in a global, collaborative way to break the common silo solution architecture. Leveraging an immutable, always-on DLT platform allows you to avoid complex setup of Certificate authorities or digital certificates (that are unfit for DevOps anyway).

Table of contents

• Quick start

• DevSecOps in mind

• What kind of behaviors can CodeNotary vcn detect

• How it works

• Installation

• Usage

• Integrations

• Documentation

• Testing

• Codenotary Cloud

• License

Quick start

1. Download CodeNotary vcn. There are releases for different platforms:

• Download the latest release and then read the Usage section below.
• We recommend storing vcn in your PATH - Linux example:

  cp vcn-v<version>-linux-amd64 /usr/local/bin/vcn
  

1. Authenticate digital objects You can use the command as a starting point.

   vcn authenticate <file|dir://directory|docker://dockerimage|git://gitdirectory>
   

2. Create your identity (free) You need an identity at CodeNotary to notarize objects yourself (btw, we're a data-minimum company and only ask for data that is really required)

3. Notarize existing digital objects Once you have an account you can start notarizing digital assets to give them an identity.

   vcn login
   vcn notarize <file|dir://directory|docker://dockerimage|git://gitdirectory>
   

DevSecOps in mind

Codenotary vcn is a solution written by a devops-obsessed engineers for Devops engineers to bring better trust and security to the the CloudNative source to deployment process

What kind of behaviors can CodeNotary vcn detect

vcn (and its extensions for Docker, Kubernetes, documents or CI/CD) can detect, authenticate and alert on any behavior that involves using unauthentic digital assets. vcn verification can be embedded anywhere and can be used to trigger alerts, updates or workflows.

vcn is so versatile, it can help detecting or acting on the following (but not limited to):

• Immutable tagging of source code, builds, and container images with version number, owner, timestamp, organization, trust level, and much more
• Simple and tamper-proof extraction of notarized tags like version number, owner, timestamp, organization, and trust level from any source code, build and container (based on the related image)
• Quickly discover and identify untrusted, revoked or obsolete libraries, builds, and containers in your application
• Detect the launch of an authorized or unknown container immediately
• Prevent untrusted or revoked containers from starting in production
• Verify the integrity and the publisher of all the data received over any channel

and more

• Enable application version checks and actions
• Buggy or rogue libraries can be traced by simple revoke or unsupport
• Revoke or unsupport your build or build version post-deployment (no complex certificate revocation that includes delivery of newly signed builds)
• Stop unwanted containers from being launched
• Make revocation part of the remediation process
• Use revocation without impairing customer environments
• Trace source code to build to deployment by integration into CI/CD or manual workflow
• Tag your applications for specific use cases (alpha, beta - non-commercial aso).

not just containers, also virtual machines - check out vCenter Connector, in case you're running VMware vSphere

• Newly created or existing virtual machines automatically get a unique identity that can be trusted or untrusted
• Prevent launch of untrusted VMs
• Stop or suspend running outdated or untrusted VMs
• Detect the cloning or export of VMs and alert

How it works

Installation

Download binary

It's easiest to download the latest version for your platform from the release page.

Once downloaded, you can rename the binary to vcn, then run it from anywhere.

For Linux and macOS you need to mark the file as executable: chmod +x vcn

Homebrew / Linuxbrew

If you are on macOS and using Homebrew (or on Linux and using Linuxbrew), you can install vcn with the following:

brew tap vchain-us/brew
brew install vcn

Build from Source

After having installed golang 1.12 or newer clone this repository into your working directory.

Now, you can build vcn in the working directory by using make vcn and then run ./vcn.

Alternatively, you can install vcn in your system simply by running make install. This will put the vcn executable into GOBIN which is accessible throughout the system.

Usage

Basically, vcn can notarize or authenticate any of the following kind of assets:

• a file
• an entire directory (by prefixing the directory path with dir://)
• a git commit (by prefixing the local git working directory path with git://)
• a container image (by using docker:// or podman:// followed by the name of an image present in the local registry of docker or podman, respectively)

It's possible to provide a hash value directly by using the --hash flag.

For detailed command line usage see docs/cmd/vcn.md or just run vcn help.

Wildcard support and recursive notarization

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

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

Local API server

It's possible to start a local API server. All commands are supported. The notarization password can be submitted with the x-notarization-password header. Examples:

curl --location --request GET '127.0.0.1:8080/inspect/e2b58ab102dbadb3b1fd5139c8d2a937dc622b1b0d0907075edea163fe2cd093' \
--header 'x-notarization-password: *********' \
--header 'Authorization: Basic ****' \
--header 'Content-Type: application/json' \
--data-raw '{
	"Kind":		"file",
	"Name":		"CONTRIBUTING.md",
	"Hash":		"e2b58ab102dbadb3b1fd5139c8d2a937dc622b1b0d0907075edea163fe2cd093",
	"Size":		1400,
	"ContentType":	"text/plain; charset=utf-8"
}'

Notarization

Register an account with codenotary.io first.

Then start with the login command. vcn will walk you through login and importing up your secret upon initial use.

vcn login

Once your secret is set you can notarize assets like in the following examples:

vcn notarize <file>
vcn notarize dir://<directory>
vcn notarize docker://<imageId>
vcn notarize podman://<imageId>
vcn notarize git://<path_to_git_repo>
vcn notarize --hash <hash>

By default all assets are notarized private, so not much information is disclosed about the asset. If you want to make that public and therefore, more trusted, please use the --public flag.

vcn notarize --public <asset>

Change the asset's status:

vcn unsupport <asset>
vcn untrust <asset>

Finally, to fetch all assets you've notarized:

vcn list

Authentication

vcn authenticate <file>
vcn authenticate dir://<directory>
vcn authenticate docker://<imageId>
vcn authenticate podman://<imageId>
vcn authenticate git://<path_to_git_repo>
vcn authenticate --hash <hash>

You can use vcn authenticate even without a codenotary.io account.

To output results in json or yaml formats:

vcn authenticate --output=json <asset>
vcn authenticate --output=yaml <asset>

Check out the user guide for further details.

Integrations

• Github Action - An action to verify the authenticity of your commits within your Github workflow
• docker - Out of the box support for notarizing and authenticating Docker images.
• hub.docker.com/r/codenotary/vcn - The vcn's DockerHub repository.
• kube-notary - A Kubernetes watchdog for verifying image trust with CodeNotary.
• vcn-watchdog - Continuous authentication with CodeNotary for Docker.
• jsvcn - CodeNotary JavaScript Client.
• jvcn - CodeNotary Java Bindings.
• jvcn-maven-plugin - Maven dependency authentication and enforcement.

Documentation

• Command line usage
• Configuration
• Environments
• Formatted output (json/yaml)
• Notarization explained

Examples

Authenticate a Docker image automatically prior to running it

First, you’ll need to pull the image by using:

docker pull hello-world

Then use the below command to put in place an automatic safety check. It allows only verified images to run.

vcn authenticate docker://hello-world && docker run hello-world

If an image was not verified, it will not run and nothing will execute.

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 you 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 public address (represented as a 40 hex characters long string prefixed with 0x).

vcn authenticate --signerID 0x8f2d1422aed72df1dba90cf9a924f2f3eb3ccd87 docker://hello-world

Authenticate by a list of signers

If an asset you or your organization wants to trust needs to be verified against a list of signers as a prerequisite, then use the vcn authenticate command and the following syntax:

• Add a --signerID flag in front of each SignerID you want to add (eg. --signerID 0x0...1 --signerID 0x0...2)
• Or set the env var VCN_SIGNERID correctly by using a space to separate each SignerID (eg. VCN_SIGNERID=0x0...1 0x0...2)

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.

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

Unsupport/untrust an asset you do not have anymore

In case you want to unsupport/untrust an asset of yours that you no longer have, you can do so using the asset hash(es) with the following steps below.

First, you’ll need to get the hash of the asset from your CodeNotary dashboard or alternatively you can use the vcn list command. Then, in the CLI, use:

vcn untrust --hash <asset's hash>
# or
vcn unsupport --hash <asset's hash>

Notarization within automated environments

First, you’ll need to make vcn have access to the ${HOME}/.vcn folder that holds your secret (the private key). Then, set up your environment accordingly using the following commands:

export VCN_USER=<email>
export VCN_PASSWORD=<login password>
export VCN_NOTARIZATION_PASSWORD=<notarization password>

It's possible to disable one time password requirement with:

export VCN_OTP_EMPTY=true

Once done, you can use vcn in your non-interactive environment using:

vcn login
vcn notarize <asset>

Other commands like untrust and unsupport will also work.

Testing

make test

Codenotary Cloud

Vcn was extended in order to be compatible with Codenotary Cloud . Notarized assets informations are stored in a tamperproof ledger with cryptographic verification backed by immudb, the immutable database. Thanks to this vcn is faster and provides more powerful functionalities like local data inclusion, consistency verification and enhanced CLI filters.

Obtain an API Key

To provide access to Immutable Ledger a valid API Key is required. This API Key is bound to a specific Ledger and it's required during vcn login. To obtain a valid key you need to get access to a licensed Codenotary Cloud installation.

Login

To login in Immutable Ledger provides --lc-port and --lc-host flag, also the user submit API Key when requested. Once host, port and API Key are provided, it's possible to omit them in following commands. Otherwise, the user can provide them in other commands like notarize, verify or inspect.

vcn login --lc-port 443 --lc-host cnlc-host.com

One time password (otp) is not mandatory

Alternatively, for using vcn in non-interactive mode, the user can supply the API Key via the VCN_LC_API_KEY environment variable, e.g.:

export VCN_LC_API_KEY=apikeyhere

# No vcn login command needed

# Other vcn commands...
vcn notarize asset.txt --lc-host cnlc-host.com --lc-port 443

TLS

By default, vcn will try to establish a secure connection (TLS) with a Immutable Ledger server.

The user can also provide a custom TLS certificate for the server, in case vcn is not able to download it automatically:

vcn login --lc-port 443 --lc-host cnlc-host.com --lc-cert mycert.pem

For testing purposes or in case the provided certificate should be always trusted by the client, the user can configure vcn to skip TLS certificate verification with the --lc-skip-tls-verify option:

vcn login --lc-port 443 --lc-host cnlc-host.com --lc-cert mycert.pem --lc-skip-tls-verify

Finally in case the Immutable Ledger Server is not exposed through a TLS endpoint, the user can request a cleartext connection using the --lc-no-tls option:

vcn login --lc-port 80 --lc-host cnlc-host.com --lc-no-tls

Signature verification

If the connected Codenotary Cloud server is cryptographically signing messages vcn will requests public key in order to verify signatures. It's possible to specify the public key with the environment vars VCN_SIGNING_PUB_KEY_FILE={an ECDSA public key file path} or VCN_SIGNING_PUB_KEY={an ECDSA public key payload}. In alternative also flags --signing-pub-key-file and --signing-pub-key are availables.

If no public key is provided vcn will automatically trust the first signature found while connecting on a server configured to sign messages and it will save in ~/.vcn-trusted-signing-pub-key the trusted public key. If --enforce-signature-verify flag or VCN_ENFORCE_SIGNATURE_VERIFY env var is provided and vcn is run inside a terminal it will requests for a fingerprint confirmation.

In order to verify the fingerprint on the public openssl key its possible to check CNC dashboard and verify that fingerprint match the server identity. To obtain the fingerprint from an openssl ECDSA private key use:

ssh-keygen -f mykey.key -y > mykey.pem
ssh-keygen -l -v -f mykey.pem

To obtain the fingerprint from an openssl ECDSA public key use:

ssh-keygen -i -m PKCS8 -f mykey.pub > mykey.pem.pub
ssh-keygen -l -v -f mykey.pem.pub

Commands

All commands reference didn't change.

Add custom metadata when signing assets

The user can upload custom metadata when doing an asset notarization using the --attr option, e.g.:

vcn n README.md --attr Testme=yes --attr project=5 --attr pipeline=test

This command would add the custom asset metadata Testme: yes, project: 5, pipeline: test.

The user can read the metadata back on asset authentication, i.e. using the jq utility:

vcn a README.md -o json | jq .metadata

Inspect

Inspect has been extended with the addition of new filter: --last, --first, --start and --end. With --last and --first are returned the N first or last respectively.

vcn inspect document.pdf --last 10

With --start and --end it's possible to use a time range filter:

vcn inspect document.pdf --start 2020/10/28-08:00:00 --end 2020/10/28-17:00:00

If no filters are provided only maximum 100 items are returned.

Signer Identifier

It's possible to filter results by signer identifier:

vcn inspect document.pdf --signerID CygBE_zb8XnprkkO6ncIrbbwYoUq5T1zfyEF6DhqcAI=

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 overwritte. 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

Local API server

Local API server is supported. The API Key can be submitted with the x-notarization-lc-api-key header.

Notarize example:

curl --location --request POST '127.0.0.1:8082/notarize' \
--header 'x-notarization-lc-api-key: oikfnlbjinhhclvjiotckgwfuyfjxntxmcau' \
--header 'Content-Type: application/json' \
--data-raw '{
"Kind":"file",
"Name":"CONTRIBUTING.md",
"Hash":"e2b58ab102dbadb3b1fd5139c8d2a937dc622b1b0d0907075edea163fe2cd093",
"Size":1400,
"ContentType":"text/plain; charset=utf-8"
}'

Authenticate example:

curl --location --request GET '127.0.0.1:8081/authenticate/e2b58ab102dbadb3b1fd5139c8d2a937dc622b1b0d0907075edea163fe2cd093' \
--header 'x-notarization-lc-api-key: oikfnlbjinhhclvjiotckgwfuyfjxntxmcau'

Inspect example:

curl --location --request GET '127.0.0.1:8082/authenticate/e2b58ab102dbadb3b1fd5139c8d2a937dc622b1b0d0907075edea163fe2cd093' \
--header 'x-notarization-lc-api-key: oikfnlbjinhhclvjiotckgwfuyfjxntxmcau'

Inspect with signerID example:

curl --location --request GET '127.0.0.1:8081/inspect/e2b58ab102dbadb3b1fd5139c8d2a937dc622b1b0d0907075edea163fe2cd093?signerid=yZtm26ZgmZr37NQ41TXbJ2jStMVWZhE-3cp4Wb7gKQo=' \
--header 'x-notarization-lc-api-key: oikfnlbjinhhclvjiotckgwfuyfjxntxmcau'

Untrust example:

curl --location --request POST '127.0.0.1:8081/untrust' \
--header 'x-notarization-lc-api-key: oikfnlbjinhhclvjiotckgwfuyfjxntxmcau' \
--header 'Content-Type: application/json' \
--data-raw '{
	"Kind":		"file",
	"Name":		"CONTRIBUTING.md",
	"Hash":		"e2b58ab102dbadb3b1fd5139c8d2a937dc622b1b0d0907075edea163fe2cd093",
	"Size":		1400,
	"ContentType":	"text/plain; charset=utf-8"
}'

License

This software is released under GPL3.