Community Attestation Service (CAS)

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

⚠️ From version v0.10 a major refactoring has replaced the old VCN CLI. While the old VCN versions are available to download in the release section, we don't provide support and maintenance anymore.

Table of contents

• Quick start
• DevSecOps in mind
• What kind of behaviors can Codenotary cas detect
• Installation
• Usage
• Integrations
• Documentation
• Advanced Usage
• License

Quick start

1. Create your identity (free) - You will get an API_KEY from our free cloud CAS Cloud.

2. Download Codenotary CAS

   bash <(curl https://getcas.codenotary.io -L)
   

For Windows users, donwload your binay here.

3. Login

   export CAS_API_KEY=<your API KEY>; cas login

4. Create a Software Bill of Materials (SBOM)

   cas bom docker://wordpress

5. Attest your assets Attestation is the combination of Notarization (creating digital proof of an asset) and Authentication (getting the authenticity of an asset).

   Notarize an asset:

   cas notarize docker://wordpress

   Authenticate an asset:

   cas authenticate docker://wordpress

Table of contents

• DevSecOps in mind
• What kind of behaviors can Codenotary cas detect
• Installation
• Usage
• Integrations
• Documentation
• More Examples
• License

DevSecOps in mind

Codenotary cas is a solution written by 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 cas detect

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

cas detects or acts 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

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 cas, then run it from anywhere.

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

Homebrew / Linuxbrew

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

brew tap codenotary/cas
brew install cas

Build from Source

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

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

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

Installing packages (yum/deb) from codenotary repository

If you are using a linux distribution based on .deb or .rpm packages, you can install cas using package from the codenotary repository.

RPM

For .rpm based distributions (RedHat / AlmaLinux / CentOS ...) you have to add the repository by creating a .repo file (say codenotary.repo) in the /etc/yum.repos.d/ directory:

[codenotary-repo]
name=Codenotary repository
baseurl=https://packages.codenotary.org/rpm/vcn
gpgcheck=1
gpgkey=https://packages.codenotary.org/packages.codenotary.org.gpp.key
enabled=1

This command will do that for you:

wget https://packages.codenotary.org/codenotary.repo -O /etc/yum.repos.d/codenotary.repo

Then you can install cas with the command:

yum install cas

DEB

For debian based distributions, you just add this line to /etc/apt/sources.list, or create a .list file in /etc/apt/sources.list.d with this content:

deb https://packages.codenotary.org/debian/ stable main

You then have to install the Codenotary public key used for signing the package:

apt-key adv --fetch-keys https://packages.codenotary.org/packages.codenotary.org.gpp.key

And then you can install cas using regular apt commands:

apt-get update
apt-get install cas

Usage

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

• a file
• 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/cas.md or just run cas 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.

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

Notarization

Register an account with codenotary.com first.

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

cas login

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

cas notarize <file>
cas notarize docker://<imageId>
cas notarize podman://<imageId>
cas notarize git://<path_to_git_repo>
cas notarize --hash <hash>

Change the asset's status:

cas unsupport <asset>
cas untrust <asset>

Finally, to fetch all assets you've notarized:

cas list

Authentication

cas authenticate <file>
cas authenticate docker://<imageId>
cas authenticate podman://<imageId>
cas authenticate git://<path_to_git_repo>
cas authenticate --hash <hash>

💡 Public authentication is also possible without having an CAS_API_KEY - more info here Public Authentication

To output results in json or yaml formats:

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

Check out the user guide for further details.

Integrations

• Github Action - GitHub Actions to notarize, authenticate within your Github workflow
• hub.docker.com/r/codenotary/cas - The cas's DockerHub repository.

Documentation

• Command line usage
• CAS Bill of Materials for Docker
• Configuration
• Environments
• Formatted output (json/yaml)
• Notarization explained (TBD)

Advanced Usage

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.

cas 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 cas:

ls | xargs cas 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 or its email.

cas authenticate --signerID <signer-email|signer-id> docker://hello-world

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:

cas 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 using the cas list command. Then, in the CLI, use:

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

TLS

By default, cas will try to establish a secure connection (TLS) with Community Attestation Service.

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

cas login --port 443 --host cas.codenotary.com --cert mycert.pem

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

cas login --port 443 --host cas.codenotary.com --cert mycert.pem --skip-tls-verify

Verify CAS server identity

Every message returned by CAS is cryptographically signed. In order to verify the identity of the server you can calculate locally the fingerprint and compare it with the following:

SHA256:Re5IAHGkYk32xfnG8txbwJuJPVFe8Mf5AOv3bLg6XsY

To generate local fingerprint use the following commands:

ssh-keygen -i -m PKCS8 -f ~/.cas-trusted-signing-pub-key > mykey.pem.pub
ssh-keygen -l -v -f mykey.pem.pub
rm mykey.pem.pub

Add custom metadata when signing assets

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

cas 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:

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

cas inspect document.pdf --last 10

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

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

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

Signer Identifier

It's possible to filter results by signer identifier:

cas inspect document.pdf --signerID CygBE_zb8XnprkkO6ncIrbbwYoUq5T1zfyEF6DhqcAI=

Public Authentication

The authentication is performed by a user possessing an CAS_API_KEY issued by the Community Attestation Service. But there are situations in which an anonymous authentication is needed: for example the authentication is performed by a GitHub action in an Open Source repository. For such scenarios, a public authentication is possible, where the authentication process does not need an CAS_API_KEY - nevertheless the SIGNER_ID has to be defined. Example:

cas authenticate --signerID 0xxxxxxxxxxxxxxxxxxxxxxxxxxx docker://hello-world

License

This software is released under Apache 2.0.