The Black Duck GKE Binary Authorization solution provides the ability to control container deployment into GKE by using attestations tied to Black Duck policies. The Black Duck Policy Management feature enables you to create rules that govern your use of open source components in your code base, which can help you reduce open source security, license, and operational risks. Black Duck's Binary Authorization solution is an add-on to the Synopsys Black Duck Cloud Build Solution, and creates an attestation based on the Black Duck policy violation status. The Black Duck attestation attests that a container has passed Black Duck policy and is ready for deployment.
Are you using Binary Authorization? The Synopsys Cloud Build Scanner can write Container Analysis Notes to an Attestor tied to Black Duck scan. If, a policy violation occurs during a Black Duck scan in CloudBuild, an attestation will not be created and the image will not be deployable to GKE.
IMPORTANT NOTES:
This solution is currently in alpha release. Early adopters are welcome to provide design input.
This documentation is not fully tested and is currently used for design purposes only.
Please send any questions or suggestions to partner-solutions@synopsys.com.
Architecture
The following diagram shows the components in a Black Duck Binary Authorization Cloud Build setup:
The components are as follows:
Cloud Source Repositories or another secure repository that contains the source code used to build a container image
Cloud Build, which runs builds and tests, and outputs the container image to a Container Registry or another software registry that stores your built images
Synopsys Black Duck Cloud Build Scan added to Cloud Build when new image versions are built and makes an attestation if the image passes Black Duck policy
Container Analysis, which stores the attestations for Binary Authorization and the build records from Cloud Build
Binary Authorization, which enforces the policy requiring attestations by Black Duck before a container image can be deployed
Google Kubernetes Engine, which runs the deployed container images on Google Cloud Platform
Before you begin
There are several steps to prepare your GCP Project, GKE Cluster, and Cloud Build to attest a container image with Black Duck.
Set Up your Project and GKE Cluster
To use Binary Authorization, you must enable it for your Project and Cluster. The quickest way to achieve this, and become familiar with Binary Authorization is to use the Quickstart method.
Note: Do not delete the cluster, because it is required at a later stage.
Create a Service Account for Attesting
To perform an attestation, create a service account with the following permissions, or add them to the Cloud Build Service Account.
- Cloud Build Service Account
- Cloud KMS CryptoKey Decrypter
- Service Account Key Admin
- Storage Admin
- Binary Authorization Attestor Admin
Create the Attestor for Black Duck and configure a policy that requires Black Duck attestation
The attestor is responsible for attesting that the Black Duck scan has completed before a container image can be deployed. Click Create an Attestor to learn about creating an attestor for Black Duck.
When you configure the cryptographic keys, use the following values:
- ATTESTOR_NAME: blackduck-scan
- ATTESTOR_EMAIL: Any e-mail you choose (required in later steps)
After creating the attestor, Configure a policy that blocks images from being deployed unless blackduck-scan attests the image.
Encrypt your Black Duck API token, private key passphrase, and private key file by using KMS
As the private key that is associated with the Attestor is necessary to sign the Attestation Payload, you must make it available to the Synopsys Cloud Build scanner.
To do this, you export the private key, encrypt it with KMS, and store it in a Cloud Storage bucket. At build time, the encrypted file is passed to Cloud Build, decrypted, used, and then destroyed.
Export the Private Key from the KeyPair created in the previous step.
Export the Private Keygpg --output pv_key.pgp --armor --export-secret-key $ATTESTOR_EMAIL
Encrypt the file using KMS, then delete the original unencrypted file.
Encrypting the private key file by using KMSgcloud kms encrypt --location global \ --keyring [KEYRING-NAME] --key [KEY-NAME] \ --plaintext-file pv_key.pgp \ --ciphertext-file pv_key.pgp.enc
Upload the encrypted file to a cloud storage bucket.
Copy the private key to a cloud storage bucketgsutil mv pv_key.pgp.enc gs://[DESTINATION_BUCKET_NAME]/
Encrypt the Black Duck API token that is generated from the Black Duck application.
Encrypt the Black Duck token with KMSexport BLACKDUCK_TOKEN=<<Token from Black Duck>> echo -n $BLACKDUCK_TOKEN | gcloud kms encrypt \ --plaintext-file=- \ # - reads from stdin --ciphertext-file=- \ # - writes to stdout --location=global \ --keyring=[KEYRING-NAME] \ --key=[KEY-NAME] | base64
Encrypt the private key passphrase
Encrypt the private key passphraseexport PV_PASSPHRASE=<<Passphrase for the Exported Private Key>> echo -n $PV_PASSPHRASE | gcloud kms encrypt \ --plaintext-file=- \ # - reads from stdin --ciphertext-file=- \ # - writes to stdout --location=global \ --keyring=[KEYRING-NAME] \ --key=[KEY-NAME] | base64
Get the image that you to attest ready to pull in GCR
To perform an attestation, you must have an image to attest in GCR.
If you don't have one, follow the steps to push your own image to GCR, or follow the Synopsys Cloud Build example to build and push ducky-crm.
Adding Black Duck Binary Authorization to Cloud Build
Scanning and Attesting an Image from GCR
You can use the cloudbuild.yaml file in your Cloud Build with minor substitutions, as long as all the pre-requisites are satisfied.
Replace the following values:
- Fourth Step (gcloud slim) - the storage bucket where the encrypted private key file was stored above.
- Fifth Step (gsutil) - the KMS keyring and key name used to encrypt the secrets above.
- Sixth Step (Synopsys CloudBuild Scanner) - Black Duck URL
- Substitutions:
- Image Name you're attesting. Will also be the Black Duck project name.
- Image Tag. Will also be the Black Duck project version.
- Name of the Service Account Key, if you're using a different name in Step 3 below.
- Name of the private Key file from above, if you used a different name.
- Secrets:
- BD_TOKEN - use the base64 encrypted value for the Black Duck API token from the "Before you Begin" section.
- PRIVATE_KEY_PASSWD - use the base64 encrypted value for the private key passphrase from the 'Before you Begin' section.