Skip to content

Commit

Permalink
Sunsetting terminal
Browse files Browse the repository at this point in the history
  • Loading branch information
erikaheidi committed Oct 18, 2024
1 parent 8cdfe4f commit 735e86c
Show file tree
Hide file tree
Showing 16 changed files with 42 additions and 109 deletions.
Original file line number Diff line number Diff line change
Expand Up @@ -13,7 +13,6 @@ menu:
docs:
parent: "chainguard-images"
weight: 020
terminalImage: academy/chainguard-images:latest
toc: true
---

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -14,11 +14,10 @@ menu:
docs:
parent: "apko"
weight: 100
terminalImage: apko:latest
toc: true
---

[apko](http://github.com/chainguard-dev/apko) is a command-line tool to build container images using a declarative language based on YAML. apko is so named as it uses the [apk](https://wiki.alpinelinux.org/wiki/Package_management) package format and is inspired by the [ko](https://github.com/google/ko) build tool. It is part of the open source tooling Chainguard developed to create the [Wolfi](/open-source/wolfi) operating system which is used in [Chainguard Images](/chainguard/chainguard-images).
[apko](http://github.com/chainguard-dev/apko) is a command-line tool to build container images using a declarative language based on YAML. apko is so named as it uses the [apk](https://wiki.alpinelinux.org/wiki/Package_management) package format and is inspired by the [ko](https://github.com/google/ko) build tool. It is part of the open source tooling Chainguard developed to create the [Wolfi](/open-source/wolfi) operating system which is used in [Chainguard Images](/chainguard/chainguard-images).

## Why apko
Container images are typically assembled in multiple steps. A tool like Docker, for example, combines building steps (as in, running commands to copy files, build and deploy applications) and composition (as in, composing a base image with pre-built packages) in a single piece of software. apko, on the other hand, is solely a **composition** tool that focuses on producing lightweight, "flat" base images that are fully reproducible and contain auto generated [SBOM](https://www.cisa.gov/sbom) files for every successful build.
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -16,7 +16,6 @@ menu:
parent: "melange-tutorials"
weight: 100
toc: true
# terminalImage: melange:latest
---

[melange](https://github.com/chainguard-dev/melange) is an [apk](https://wiki.alpinelinux.org/wiki/Package_management) builder tool that uses declarative pipelines to create apk packages. From a single YAML file, users are able to generate multi-architecture apks that can be injected directly into [apko](https://github.com/chainguard-dev/apko) builds.
Expand Down
29 changes: 14 additions & 15 deletions content/open-source/sbom/getting-started-openvex-vexctl.md
Original file line number Diff line number Diff line change
Expand Up @@ -14,30 +14,29 @@ menu:
parent: "sbom"
weight: 10
toc: true
terminalImage: vexctl:latest
---

The `vexctl` CLI is a tool to make VEX work. As part of the open source [OpenVex](/open-source/sbom/what-is-openvex/) project, `vexctl` enables you to create, apply, and attest VEX (Vulnerability Exploitability eXchange) data in order to filter out false positive security alerts.
The `vexctl` CLI is a tool to make VEX work. As part of the open source [OpenVex](/open-source/sbom/what-is-openvex/) project, `vexctl` enables you to create, apply, and attest VEX (Vulnerability Exploitability eXchange) data in order to filter out false positive security alerts.

The `vexctl` tool was built to help with the creation and management of VEX documents, communicate transparently to users as time progresses, and enable the "turning off" of security scanner alerts of vulnerabilities known not to affect a given product. Using VEX, software authors can communicate to their users that an otherwise vulnerable component has no security implications for their product.

This tutorial will walk you through some common commands in `vexctl`.

## Installing vexctl

If you would like to install `vexctl` on your local or virtual machine, you will need Go 1.16 or higher. You can install by following the official [Go documentation](https://go.dev/doc/install).
If you would like to install `vexctl` on your local or virtual machine, you will need Go 1.16 or higher. You can install by following the official [Go documentation](https://go.dev/doc/install).

Using Go, run the following to install `vexctl`:

```sh
go install github.com/openvex/vexctl@latest
```

Alternately, you can follow along with this tutorial on the embedded browser terminal, which has `vexctl` already installed.
This command will install the latest version of `vexctl` on your machine.

## Confirming Installation

You can confirm that `vexctl` was installed and is ready to use by running the following command, which you can run on the embedded terminal.
You can confirm that `vexctl` was installed and is ready to use by running the following command:

```sh
vexctl version
Expand Down Expand Up @@ -65,7 +64,7 @@ This indicates the current version of `vexctl` on your working machine. You are

With `vexctl`, VEX data can be created to a file on disk, or it can be captured in a signed attestation that can be attached to a container image. You can create a VEX document by using the `vexctl create` command.

For example, to create a VEX document with a single statement asserting that the [WolfiOS](https://github.com/wolfi-dev/) package `git-2.38.1-r0` is not affected by a given common vulnerability and exposure (CVE) — let's say, `CVE-2014-123456` — because it has already been mitigated in the distribution, you can run the following.
For example, to create a VEX document with a single statement asserting that the [WolfiOS](https://github.com/wolfi-dev/) package `git-2.38.1-r0` is not affected by a given common vulnerability and exposure (CVE) — let's say, `CVE-2014-123456` — because it has already been mitigated in the distribution, you can run the following.

```sh
vexctl create --product="pkg:apk/wolfi/git@2.38.1-r0?arch=x86_64" \
Expand Down Expand Up @@ -112,13 +111,13 @@ You can also create a VEX document with abbreviated information. For instance, w
vexctl create "pkg:apk/wolfi/git@2.39.0-r1?arch=x86_64" CVE-2023-12345 fixed
```

The above workflow demonstrates how to create a VEX document with `vexctl` on the command line.
The above workflow demonstrates how to create a VEX document with `vexctl` on the command line.

## Merging Existing VEX Documents

When more than one stakeholder is issuing VEX metadata about a piece of software, `vexctl` can merge the documents to get the most up-to-date impact assessment of a vulnerability.
When more than one stakeholder is issuing VEX metadata about a piece of software, `vexctl` can merge the documents to get the most up-to-date impact assessment of a vulnerability.

Let's begin with two test documents. You can create these two test documents with a CLI editor such as nano.
Let's begin with two test documents. You can create these two test documents with a CLI editor such as nano.

The first document is `document1.vex.json`:

Expand Down Expand Up @@ -184,7 +183,7 @@ vexctl merge --product=pkg:apk/wolfi/bash@1.0.0 \
document2.vex.json
```

The resulting document combines the VEX statements that express data about `bash@1.0.0` into a single document.
The resulting document combines the VEX statements that express data about `bash@1.0.0` into a single document.

```json
{
Expand Down Expand Up @@ -215,7 +214,7 @@ The resulting document combines the VEX statements that express data about `bash
}
```

This final document tells the whole story of how `CVE-2014-123456` was `under_investigation` and then `fixed` four hours later, all documented in a single VEX file that was merged with `vexctl`.
This final document tells the whole story of how `CVE-2014-123456` was `under_investigation` and then `fixed` four hours later, all documented in a single VEX file that was merged with `vexctl`.

## Attesting and Attaching VEX Documents

Expand All @@ -227,25 +226,25 @@ For example, if you have a container image `your-username/your-container-image:l
vexctl attest --attach --sign hello.vex.json your-username/your-container-image:latest
```

Upon running this command, you'll be taken through a signing workflow with [Sigstore](https://www.sigstore.dev/). Your terminal output will indicate your progess.
Upon running this command, you'll be taken through a signing workflow with [Sigstore](https://www.sigstore.dev/). Your terminal output will indicate your progress.

```
Generating ephemeral keys...
Retrieving signed certificate...
```

A browser window will open for you to select an OIDC provider. When the attestation is complete, you'll receive feedback that it was successful.
A browser window will open for you to select an OIDC provider. When the attestation is complete, you'll receive feedback that it was successful.

```
Successfully verified SCT...
{"payloadType":"application/vnd.in-toto+json","payload":"e...o=","signatures":[{"keyid":"","sig":"MEY...z"}]}
```

This attestation with `.att` extension will now live in the container registry as an attachment to your container.
This attestation with `.att` extension will now live in the container registry as an attachment to your container.

## Chronology and VEX Documents

Assessing the impact of CVEs on a software product is process that takes time and the status will change over time. VEX is designed to communicate with users as the status changes, and there may therefore be multiple VEX documents associated with a product.
Assessing the impact of CVEs on a software product is process that takes time and the status will change over time. VEX is designed to communicate with users as the status changes, and there may therefore be multiple VEX documents associated with a product.

To understand how this may work in practice, below is an example timeline for the VEX documents associated with a given product and CVE.

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -12,25 +12,24 @@ menu:
docs:
parent: "cosign"
weight: 003
terminalImage: cosign:latest
toc: true
---

_An earlier version of this material was published in the [Cosign chapter](https://learning.edx.org/course/course-v1:LinuxFoundationX+LFS182x+2T2022/block-v1:LinuxFoundationX+LFS182x+2T2022+type@sequential+block@204b98f35bca48c194d1868e0356bef1/block-v1:LinuxFoundationX+LFS182x+2T2022+type@vertical+block@2f0ad9cb8f124a39ab555ac8bf1a114c) of the Linux Foundation [Sigstore course](https://learning.edx.org/course/course-v1:LinuxFoundationX+LFS182x+2T2022/home)._

Cosign is a tool you can use to sign software artifacts, which in turn allows you to verify that you are who you say you are, and instills trust across the software ecosystem. Signing software also allows people to understand the provenance of the software, and prevents tampering.
Cosign is a tool you can use to sign software artifacts, which in turn allows you to verify that you are who you say you are, and instills trust across the software ecosystem. Signing software also allows people to understand the provenance of the software, and prevents tampering.

Let’s step through signing a container with Cosign. We are using a container to provide a sense of how you may use Sigstore with containerized workloads, but the steps we are taking to sign a container are very similar to the steps that we would take to sign any other software artifact that can be published in a container registry, and we will discuss signing blobs a little later.
Let’s step through signing a container with Cosign. We are using a container to provide a sense of how you may use Sigstore with containerized workloads, but the steps we are taking to sign a container are very similar to the steps that we would take to sign any other software artifact that can be published in a container registry, and we will discuss signing blobs a little later.

## Prerequisites

Before beginning this section, ensure that you have Docker installed and that you are running Docker Desktop if that is relevant for your operating system. For guidance on installing and using Docker, refer to the [official Docker documentation](https://docs.docker.com/get-docker/). In order to push to the Docker container registry, you will need a [Docker Hub account](https://hub.docker.com/signup). If you are familiar with using a different container registry, feel free to use that.
Before beginning this section, ensure that you have Docker installed and that you are running Docker Desktop if that is relevant for your operating system. For guidance on installing and using Docker, refer to the [official Docker documentation](https://docs.docker.com/get-docker/). In order to push to the Docker container registry, you will need a [Docker Hub account](https://hub.docker.com/signup). If you are familiar with using a different container registry, feel free to use that.

Additionally, you will need Cosign installed, which you can achieve by following our [How to Install Cosign guide](/open-source/sigstore/cosign/how-to-install-cosign/).

## Creating a Container

You’ll now be creating a new container. Create a new directory within your user directory that is the same as your Docker username and, within that, a directory called `hello-container`. If you will be opting to use a registry other than Docker, feel free to use the relevant username for that registry.
You’ll now be creating a new container. Create a new directory within your user directory that is the same as your Docker username and, within that, a directory called `hello-container`. If you will be opting to use a registry other than Docker, feel free to use the relevant username for that registry.

```sh
mkdir -p ~/docker-username/hello-container
Expand All @@ -44,7 +43,7 @@ cd ~/docker-username/hello-container

Let’s create the Dockerfile that describes the container. This will be essentially a “Hello, World” container for demonstration purposes.

Use the text editor of your choice to create the Dockerfile. You can use [Visual Studio Code](https://code.visualstudio.com/) or a command line text editor like nano. Just ensure that the file is called exactly `Dockerfile` with a titlecase and no extension.
Use the text editor of your choice to create the Dockerfile. You can use [Visual Studio Code](https://code.visualstudio.com/) or a command line text editor like nano. Just ensure that the file is called exactly `Dockerfile` with a titlecase and no extension.

```sh
nano Dockerfile
Expand All @@ -59,7 +58,7 @@ CMD ["echo", "Hello, Cosign!"]

This file is instructing the container to use the Alpine Linux distribution, which is lightweight and secure. Then, it prints a “Hello, Cosign!” message onto the command-line interface.

Once you are satisfied that your Dockerfile is the same as the text above, you can save and close the file. Now you are ready to build the container.
Once you are satisfied that your Dockerfile is the same as the text above, you can save and close the file. Now you are ready to build the container.

## Building and Running a Container

Expand All @@ -74,16 +73,16 @@ If you receive an error message or a “failed” message, check that your user
You should get guidance in the output that your build was successful when you receive no errors.

```
=> => naming to docker.io/docker-username/hello-container
=> => naming to docker.io/docker-username/hello-container
```

At this point your container is built and you can verify that the container is working as expected by running the container.
At this point your container is built and you can verify that the container is working as expected by running the container.

```sh
docker run docker-username/hello-container
```

You should receive the expected output of the echo message you added to the Dockerfile.
You should receive the expected output of the echo message you added to the Dockerfile.

```
Hello, Cosign!
Expand All @@ -102,21 +101,21 @@ c828db494203 hello-container "echo 'Hello, Cosign…" 13 seconds ago Exi

Your output will be similar to the above, but the timestamps and name will be different.

Now that you have built your container and are satisfied that it is working as expected, you can publish and sign your container.
Now that you have built your container and are satisfied that it is working as expected, you can publish and sign your container.

## Publishing a Container to a Registry

We will be publishing our container to the Docker registry. If you are opting to use a different registry, your steps will be similar.
We will be publishing our container to the Docker registry. If you are opting to use a different registry, your steps will be similar.

At this point, you can access the Docker container registry at [hub.docker.com](https://hub.docker.com/) and create a new repository under your username called `hello-container`. We will be making this public, but you can make it private if you prefer. If you are happy for it to be public, you can skip this step as the repository will be created when pushing the container. In any case, you can delete this once you are satisfied that you have signed the container.
At this point, you can access the Docker container registry at [hub.docker.com](https://hub.docker.com/) and create a new repository under your username called `hello-container`. We will be making this public, but you can make it private if you prefer. If you are happy for it to be public, you can skip this step as the repository will be created when pushing the container. In any case, you can delete this once you are satisfied that you have signed the container.

Once this is set up, you can push the container you created to the Docker Hub repository.
Once this is set up, you can push the container you created to the Docker Hub repository.

```sh
docker push docker-username/hello-container
```

You should be able to now access your published container via your Docker Hub account. Once you ensure that this is there, you are ready to push a signature to the container.
You should be able to now access your published container via your Docker Hub account. Once you ensure that this is there, you are ready to push a signature to the container.

## Signing a Container and Pushing the Signature to a Registry

Expand All @@ -139,7 +138,7 @@ Retrieving signed certificate...
This information will be used for signing this artifact and will be stored in public transparency logs and cannot be removed later.
By typing 'y', you attest that you grant (or have permission to grant) and agree to have this information stored permanently in transparency logs.
Are you sure you would like to continue? [y/N]
Are you sure you would like to continue? [y/N]
Your browser will now be opened to:
...
```
Expand All @@ -148,7 +147,7 @@ You’ll receive output indicating that the signature was pushed to the containe

```
Successfully verified SCT...
tlog entry created with index:
tlog entry created with index:
Pushing signature to: index.docker.io/docker-username/hello-container
```

Expand All @@ -164,12 +163,12 @@ Let’s use Cosign to verify that the signature exists on the transparency log a
cosign verify \
--certificate-identity username@gmail.com \
--certificate-oidc-issuer https://accounts.google.com \
docker-username/hello-container
docker-username/hello-container
```

Here, we are passing the public key contained in the cosign.pub file to the `cosign verify` command.
Here, we are passing the public key contained in the cosign.pub file to the `cosign verify` command.

You should receive output indicating that the Cosign claims were validated.
You should receive output indicating that the Cosign claims were validated.

```
Verification for index.docker.io/docker-username/hello-container:latest --
Expand Down
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
---
title: "How to Install Sigstore Policy Controller"
aliases:
aliases:
- /open-source/sigstore/policy-controller/enforce-sbom-attestation-with-policy-controller/
type: "article"
description: "Install the Sigstore Policy Controller into a Kubernetes Cluster"
Expand All @@ -15,7 +15,6 @@ menu:
parent: "policy-controller"
weight: 001
toc: true
# terminalImage: policy-controller-install:latest
---

The [Sigstore Policy Controller](https://docs.sigstore.dev/policy-controller/overview/) is a Kubernetes [admission controller](https://kubernetes.io/docs/reference/access-authn-authz/admission-controllers/) that can verify image signatures and policies. You can define policies using the [CUE](https://cuelang.org/) or [Rego](https://www.openpolicyagent.org/docs/latest/policy-language/) policy languages.
Expand Down
Loading

0 comments on commit 735e86c

Please sign in to comment.