Introduction

In the first part of this series, I explored the importance of ensuring that software builds are secure and trustworthy. I introduced the basic flow of authentication with the following actions: authentication of sources, notarization of packages, and authentication of packages during deployment. This flow aims to provide security by allowing the integration pipeline to finish without error only if all the sources received from the software repository are trusted. Similarly, the deployment pipeline is allowed to finish without error only if the packages built as a result have already been built before in the same manner and have thus been trusted. 

Here is the link to part 1 of this series.

The previous part introduced also an authorization chain that can be used to secure every software supply chain by a chain of roles/identities. This concerns any software supply chain, even one consisting of multiple workflows and jobs running at different moments. 

I also described vcn and Trustcenter/Enterprise are tools that enable performing all the actions of notarization, authentication, SBOM generation, vulnerability scanning, and more.

I will concentrate on practical applications with code samples in this part of the series. We will build steps in GitHub Actions that perform authentication and notarization. The examples provided can be easily customized to particular needs making use of the rich set of options provided by the vcn tool.

vcn GitHub Action

To make building Actions with vcn simpler, Codenotary released a free open-source GitHub Action in the Marketplace.  You can use vcn-github-action stored in the public repository along with a user guide that introduces this tool. We have also written a blog post about this GitHub Action. In this part of the series, I will attempt to describe in more detail how to use this action in practice.

In general, the vcn-github-action action has two ways of operating. 

• Standard. This is the default behavior. In short, it means that in one step you can only notarize or authenticate one file.
• Custom. This is configured by including with standard_usage: false in the step. You will find an example of this below. It only serves to download the latest version of the vcn tool to the runner which is an enabler to run commands with it. You can run the vcn command in the next steps of this job using all the advantages that the rich syntax of this tool allows for.

Prerequisites

To configure notarization and authentication using Trustcenter/Enterprise you need to sign up for free evaluation. Once you have your tenant in Trustcenter, log in, create your first ledger, and set up your signer id to create your API key. This will be the read&write key that you will use to notarize and write data to Trustcenter Enterprise.

Next in your GitHub repository go to Settings/Secrets and variables and create a new secret. Name it TC_API_KEY and as a value paste the API key copied from Trustcenter/Enterprise.

Configuring the pipeline using standard syntax

As a first attempt, we will create a simple GitHub Action that follows the standard_usage pattern. For this purpose we will add two steps to the .yaml workflow:

• Checkout the repository into the current subdirectory;
• Use the vcn-github-action that downloads the latest version of the vcn tool and notarizes the file

The GH Action will work every time you push changes to the main branch, however, you can modify this behavior following standard GH Action syntax.

Create a file notarize.yaml in .github/workflows directory in your repository with the following code:

name: notarize-one-file

on:

  push:

    branches: [main]

jobs:

  notarize-on-Linux:

    runs-on: ubuntu-latest

    steps:

      - uses: actions/checkout@v3

      - name: Download vcn and notarize binary

        uses: Codenotary/vcn-github-action@v2

        with:

            mode: notarize

            asset: score-single-image.sh

            cnc_host: tc.codenotary.com

            cnc_grpc_port: 443

            cnc_api_key: $

Instead of copy-pasting these examples, you can download them from this GitHub wiki page.

In this example, we notarize one file score-single-image.sh. Modify this example to provide your filename. Then save and push this change to GitHub. Once it is there you should see the Action accomplished in Actions and in Trustcenter/Enterprise you should be able to see your notarization in Query Ledger.

It is worth noting that instead of notarizing you can authenticate the file - just replace the mode argument with the authenticated value in the example. However you don’t currently see the fact of authentication in Trustcenter/Enterprise - you can only validate that the authentication was successful by seeing that the GH Action was completed successfully. If the file authenticated is unknown or untrusted in Trustcenter/Enterprise, or the API Key has been revoked, the vcn action returns a non-zero exit code and the Action fails.

Configuring the pipeline using custom syntax

We will create a new custom.yaml file with steps to both authenticate and notarize files. 

name: custom_authenticate_notarize

on:

  push:

    branches: [main]

jobs:

  auth-and-notarize-on-linux:

    runs-on: ubuntu-latest

    steps:

      - name: Checkout repository

        uses: actions/checkout@v3

      # This downloads the vcn binary, no other inputs are needed

      - name: Download vcn

        uses: Codenotary/vcn-github-action@v2

        with:

          standard_usage: false

      # Authenticate the source code  

      - name: Authenticate the source code

        run: ./vcn a score-single-image.sh -–bom --lc-host tc.codenotary.com --lc-port 443 --lc-api-key $

        shell: bash

      # Intermediate steps in which you build, test, scan, etc...

      # Notarize the source code

      - name: Notarize the image

        run: ./vcn n image://codenotary/immudb:latest -–bom --lc-host tc.codenotary.com --lc-port 443 --lc-api-key $

        shell: bash

To break down the code above:

1. We call the workflow custom_authenticate_notarize and the job that runs inside it auth-and-notarize-on-linux. The job runs on Ubuntu's latest version as before;
2. In the first step we check out the repository into the current subdirectory;
3. Then run a vcn authenticate command (shortened to vcn a) on an example file with SBOM (marked by the --bom option). This command has three other options: --lc-host to specify the Trustcenter/Enterprise instance, --lc-port with value 443, and --lc-api-key with the API key.
4. Next the comment marks a space where the compiler runs to build the final packages. Here comes the part where your existing code for building, testing, and scanning comes in.
5. Finally there is a step to notarize an image from Docker (as an example). The command has options explained above. Importantly, the --bom option instructs vcn to scan the image and generate the SBOM for it.
   

It is important to note at this point that vcn authenticate can be run against other identities as well. To accomplish this in Trustcenter/Enterprise you have two options:

• You can use your read&write API key or
• You can generate a read-only API key. In Trustcenter/Enterprise you can go to Query Ledger / Read only signerIDs and set up a read-only API key that can be used to authenticate an asset across all ledgers. Finally, enter it as a new secret in GitHub.

You can refer to the identity that you wish to authenticate against in the vcn authenticate command. To do this you should add both of the two following options: 

• --signerID <signerID> option to the command to authenticate the asset against notarization performed by this signerID;
• --lc-ledger <ledgerName> option to state in which project (ledger) is the asset that you wish to verify against.

Please refer to the "Authorization chain" section of the previous part of this series to see how you can leverage this vcn feature to bring security to your chain.

Conclusion

Let’s sum up the key points covered in the blog post, and highlight the benefits of implementing notarization and authentication using vcn and Trustcenter/Enterprise tools in the GitHub CI/CD pipeline.

In this series of blog posts, I discuss how to secure your CI/CD supply chain from unwanted software changes through notarization and authentication of artifacts. I explain the concepts of notarization and authentication and their importance in ensuring that software builds are secure and trustworthy. I then introduce the vcn tool working with Trustcenter/Enterprise and explain how it can be used to perform the actions of notarizing, authenticating, generating SBOMs, vulnerability scanning, and more.

I also describe the basic flow of authentication and notarization necessary to secure the software supply chain. Furthermore, the post explains the two ways of operating the vcn-github-action action in GitHub Actions and provides an example of how to use the tool in practice.

This blog post gives two examples of GitHub workflows, one using a simplified standard approach and the second being a more custom, advanced one, that gives more control and enables making use of all features of vcn with Trustcenter.

So don't leave your software vulnerable to unwanted components! By implementing these essential security measures, you can ensure that your final product is free from any hidden surprises that could harm your customers' trust. But don't worry, it's not a complicated process. With the powerful vcn tool and Trustcenter/Enterprise at your disposal, you can easily automate these crucial steps using APIs and integrate them seamlessly into your CICD pipelines. So why wait? Act now and safeguard your software's integrity today!