vChain CodeNotary

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

• Quick start
• DevSecOps in mind
• What kind of behaviors can CodeNotary vcn detect
• How it works
• Installation
• Usage
• Integrations
• Documentation
• Testing
• Cross-compiling for various platforms
• License

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

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

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

3. 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)

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

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

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

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

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

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.

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

Register an account with codernotary.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

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

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

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

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.

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.

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

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.

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

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>

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>

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.

make test

The C libraries of go-ethereum make a more sophisticated cross-compilation necessary. The make dist target takes care of all steps by using xgo and docker.

This software is released under GPL3.