From 01c2fb6aee44355d85e018cb92c9881cee9849f5 Mon Sep 17 00:00:00 2001 From: ltagliaferri Date: Fri, 18 Aug 2023 10:10:29 -0400 Subject: [PATCH] =?UTF-8?q?Revert=20"Remove=20Console=20MDs=20=F0=9F=A7=B9?= =?UTF-8?q?=20"?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- content/ui/enforce.md | 38 ++++++++++++++++++++++++++++ content/ui/group.md | 28 +++++++++++++++++++++ content/ui/inspect.md | 22 +++++++++++++++++ content/ui/install.md | 49 +++++++++++++++++++++++++++++++++++++ content/ui/policy.md | 39 +++++++++++++++++++++++++++++ content/ui/prepare.md | 17 +++++++++++++ content/ui/prerequisites.md | 9 +++++++ content/ui/test.md | 27 ++++++++++++++++++++ 8 files changed, 229 insertions(+) create mode 100644 content/ui/enforce.md create mode 100644 content/ui/group.md create mode 100644 content/ui/inspect.md create mode 100644 content/ui/install.md create mode 100644 content/ui/policy.md create mode 100644 content/ui/prepare.md create mode 100644 content/ui/prerequisites.md create mode 100644 content/ui/test.md diff --git a/content/ui/enforce.md b/content/ui/enforce.md new file mode 100644 index 0000000000..3abd1a3404 --- /dev/null +++ b/content/ui/enforce.md @@ -0,0 +1,38 @@ +At this point, let’s enforce this policy requirement. We can use `kubectl` and the `namespace` label selectors to do this. + +```sh +kubectl label ns default policy.sigstore.dev/include=true --overwrite +``` + +We can check that our policy is enforced by trying to run an unsigned image. We’ll use an unsigned Ubuntu image as an example. + +```sh +kubectl run not-signed --image=ubuntu +``` + +You’ll receive output that this attempt at running an unsigned image has been rejected. + +``` +Error from server (BadRequest): admission webhook "enforcer.chainguard.dev" denied the request: validation failed: failed policy: sample-policy +``` + +Congratulations, you have completed onboarding to Chainguard Enforce! + +If you would like, you can now clean up your work by uninstalling `chainctl` and then deleting the cluster. + +```sh +chainctl cluster uninstall +``` + +```sh +kind delete cluster --name enforce-demo +``` + +To get up and running with Chainguard Enforce, you may want to review the following docs and resources: + +- [Overview of IAM model](https://edu.chainguard.dev/chainguard/chainguard-enforce/iam-groups/overview-of-enforce-iam-model/) +- [How to manage IAM groups in Chainguard Enforce](https://edu.chainguard.dev/chainguard/chainguard-enforce/iam-groups/how-to-manage-iam-groups-in-chainguard-enforce/) +- [Example policies to use with Chainguard Enforce](https://edu.chainguard.dev/chainguard/chainguard-enforce/policies/chainguard-enforce-policy-examples/) +- [`chainctl` reference](https://edu.chainguard.dev/chainguard/chainctl/) to effective use our CLI tool to interact with the account model that Chainguard Enforce provides, and enable you to make queries into the state of your clusters and policies registered with the platform + +Please review more of our [documentation on Chainguard Enforce](https://edu.chainguard.dev/chainguard/chainguard-enforce/) and other resources on [Chainguard Academy](https://edu.chainguard.dev) to learn more about software supply chain security. diff --git a/content/ui/group.md b/content/ui/group.md new file mode 100644 index 0000000000..a91bc1836c --- /dev/null +++ b/content/ui/group.md @@ -0,0 +1,28 @@ +Using `chainctl`, you can check for the ID of your group. + +```sh +chainctl iam groups ls -o table +``` + +You'll receive output in the form of a table with information about your current groups, similar to the following. + +``` + ID | NAME | DESCRIPTION +-------------------------------------------+------------------+-------------- + + b9adda06841c1d34dfa73d5902ed44b5448b7958 | enforce-demo-group | +``` + +> **Note**: If you don't receive output like the above at all, you can create a new group by running `chainctl iam groups create --no-parent` to create a new group. The `--no-parent` flag will ensure that the new group will be a new root group; this means it won't have any connections to your existing Chainguard resources, making it safe for experimentation. After group creation, you can run `chainctl iam groups ls -o table` again to retrieve the new group's ID. + +Next, create a variable that stores the ID in the left column for later steps in this tutorial. In the following command, replace `$GROUP_ID` with the relevant ID. + +```sh +export GROUP=$GROUP_ID +``` + +In the UI, you can also check for groups to which you belong from the filter modal, which you can open by using the group selector on the left navigation menu. + +![Group dropdown](/images/group-dropdown.png) + +You can check here to see the groups to which you belong and filter resources based on group ownership. diff --git a/content/ui/inspect.md b/content/ui/inspect.md new file mode 100644 index 0000000000..b88a8d3733 --- /dev/null +++ b/content/ui/inspect.md @@ -0,0 +1,22 @@ +The first place we can look for information about container compliance is the clusters main page, which you can find by clicking on the [**Clusters** tab](https://console.enforce.dev/clusters) in the main navigation menu. + +With our new policy, `sample-policy`, in place, information about policy compliance should be visible in the **Policy compliance** column. + +![Cluster compliance](/images/cluster-compliance.png) + +You can also find more information about policy compliance by clicking on either of the cards in the cluster list page. The links on these cards will take you to views that provide more information on policies that have failed, and the exact images that are failing policies. + +Additionally, the buttons on top of the cluster table will allow you to filter your clusters by compliance. + +You can also check that the **sample-policy** was distributed to the cluster by using `kubectl`. + +```sh +kubectl get clusterimagepolicies +``` + +You’ll get feedback that the **sample-policy** was distributed and how long ago. + +``` +NAME AGE +sample-policy 68s +``` diff --git a/content/ui/install.md b/content/ui/install.md new file mode 100644 index 0000000000..9b1f25094a --- /dev/null +++ b/content/ui/install.md @@ -0,0 +1,49 @@ +Our command line interface (CLI) tool, `chainctl`, will help you interact with the account model that Chainguard Enforce provides, enabling you to make queries into the state of your clusters and policies. + +Create a new directory called `enforce-demo`. + +```sh +mkdir ~/enforce-demo && cd $_ +``` + +To install `chainctl`, we’ll use the `curl` command to pull the application down. + +```sh +curl -o chainctl "https://dl.enforce.dev/chainctl/latest/chainctl_$(uname -s | tr '[:upper:]' '[:lower:]')_$(uname -m | sed 's/aarch64/arm64/')" +``` + +Move `chainctl` into your `/usr/local/bin` directory and elevate its permissions so that it can execute as needed. + +```sh +sudo install -o $UID -g $GID -m 0755 chainctl /usr/local/bin/chainctl +``` + +Finally, alias its path so that you can use `chainctl` on the command line. + +```sh +alias chainctl=/usr/local/bin/chainctl +``` + +You can verify that everything was set up correctly by checking the `chainctl` version. + +```sh +chainctl version +``` + +``` + ____ _ _ _ ___ _ _ ____ _____ _ + / ___| | | | | / \ |_ _| | \ | | / ___| |_ _| | | + | | | |_| | / _ \ | | | \| | | | | | | | + | |___ | _ | / ___ \ | | | |\ | | |___ | | | |___ + \____| |_| |_| /_/ \_\ |___| |_| \_| \____| |_| |_____| +chainctl: Chainguard Control +GitVersion: bf36b2b +GitCommit: bf36b2be08c0dca8e4d2174ee21c31b9679c4ece +GitTreeState: clean +BuildDate: 2022-10-13T21:13:11Z +GoVersion: go1.18.7 +Compiler: gc +Platform: darwin/arm64 +``` + +You can update `chainctl` at any time to ensure you have the most up-to-date version by running `chainctl update`. diff --git a/content/ui/policy.md b/content/ui/policy.md new file mode 100644 index 0000000000..3b5047b5e2 --- /dev/null +++ b/content/ui/policy.md @@ -0,0 +1,39 @@ +You can create a policy directly from the UI by navigating to the [**Policies** tab](https://console.enforce.dev/policies). In the policy table menu, there will be a **Create policy** button. Clicking this button will navigate to the policy catalog page. + +For now, we can select the [**Custom** option from the catalog](https://console.enforce.dev/policies/create/catalog/custom). + +![Create policy](/images/create-policy.png) + +On the policy create page, ensure that the correct group is displayed in the group field: `enforce-demo`. Then paste the following code into the code editor: + +``` +apiVersion: policy.sigstore.dev/v1beta1 +kind: ClusterImagePolicy +metadata: + name: sample-policy +spec: + images: + - glob: "ghcr.io/chainguard-dev/*/*" + - glob: "ghcr.io/chainguard-dev/*" + - glob: "index.docker.io/*" + - glob: "index.docker.io/*/*" + - glob: "cgr.dev/chainguard/**" + authorities: + - keyless: + url: https://fulcio.sigstore.dev + identities: + - issuerRegExp: ".*" + subjectRegExp: ".*" +``` + +This policy creates a cluster image policy with the Sigstore beta API, and with Fulcio as a keyless authority. Here, we are requiring that all images from container registries be signed. + +After you click the **Publish** button at the bottom of the modal, your new policy will be active. The next time you land on the policy list page, you will see the policy listed, as well as any violations it has and its group hierarchy. + +You can also list your policies with `chainctl`. + +```sh +chainctl policies ls +``` + +Depending on the policies your group has in place, you may see a few policies listed in the output, along with the policy you just created. diff --git a/content/ui/prepare.md b/content/ui/prepare.md new file mode 100644 index 0000000000..158401d7ff --- /dev/null +++ b/content/ui/prepare.md @@ -0,0 +1,17 @@ +In order to put Chainguard Enforce into action within a cluster, we'll now create a Kubernetes cluster using kind. We will name our cluster `enforce-demo` by passing that to the `--name` flag, but you may want to use another name. + +```sh +kind create cluster --name enforce-demo +``` + +Install the Chainguard Enforce agent in your cluster: + +```sh +chainctl cluster install --group=$GROUP --private --context kind-enforce-demo +``` + +If you click on the [**Clusters** tab](https://console.enforce.dev/clusters) in the main navigation menu, you should now see your cluster in the cluster table. + +![Cluster list](/images/cluster-list.png) + +From here, you can explore a detailed view of the cluster, including any policies that apply to it. diff --git a/content/ui/prerequisites.md b/content/ui/prerequisites.md new file mode 100644 index 0000000000..96a4e89ba4 --- /dev/null +++ b/content/ui/prerequisites.md @@ -0,0 +1,9 @@ +This walkthrough will quickly get Chainguard Enforce installed and running locally — from setting up an example cluster, to drafting a policy and observing how it behaves, to improving the policy, and finally enforcing that policy. If you'd like more information on working with Chainguard Enforce, we encourage you to to check out the [detailed tutorial on Chainguard Academy](https://edu.chainguard.dev/chainguard/chainguard-enforce/chainguard-enforce-user-onboarding/). + +Before running Chainguard Enforce locally, you’ll need to ensure you have the following installed: + +- **curl** — to retrieve files from the web, follow the relevant [curl download docs](https://curl.se/download.html) for your machine. +- **Docker** — you’ll need [Docker installed](https://docs.docker.com/get-docker/) and running in order to step through this tutorial. +- **kind** — to create a kind Kubernetes cluster on our laptop, you can download and install kind for your relevant operating system by following the [kind install docs](https://kind.sigs.k8s.io/docs/user/quick-start/#installation). +- **kubectl** — to work with your kind cluster, you can install for your operating system by following the official [Kubernetes kubectl documentation](https://kubernetes.io/docs/tasks/tools/#kubectl). +- For macOS users, you'll need to update to bash version 4 or higher, which is not preinstalled in the machine. Please [follow our guide](https://edu.chainguard.dev/open-source/update-bash-macos/) on how to update your version if you are getting version 3 or below when you run `bash --version`. diff --git a/content/ui/test.md b/content/ui/test.md new file mode 100644 index 0000000000..8ee4aa874a --- /dev/null +++ b/content/ui/test.md @@ -0,0 +1,27 @@ +So far, the information we have been seeing about our cluster concerns the containers and images running in the cluster's control plane. + +Now, let’s deploy a new image, starting with a generic NGINX image. + +```sh +kubectl create deployment nginx --image=nginx +``` + +Give this a few seconds to populate and then check what’s running again by navigating to the cluster's detail page. You can do this by clicking on the cluster's name from the cluster list table. + +In the **Policy violations** table, the image will be listed. + +![Image with violations](/images/problem-nginx.png) + +Clicking on the **Show diagnostic** button in the table will provide more information about the violation. + +Next, let’s pull in an image that has an SBOM and signature. This is an NGINX image from Chainguard. + +```sh +kubectl create deployment good-nginx --image=ghcr.io/chainguard-dev/nginx-image-demo +``` + +This image won't be listed in the violations table, but you can navigate to the **Images** table to retrieve it. + +![Image without violations](/images/good-nginx.png) + +This image passes the policy because it has both an SBOM and a signature.