chainguard-dev/edu

Educational Resources for Software Supply Chain Security

edu's Issues

Headers content

For discussion — I wanted to know what we think about the current headers @jamonation @erikaheidi

For example, on the tutorial about how to sign an SBOM, they look like this in markdown:

---
title: "How to Sign an SBOM with Cosign"
type: "article"
description: "Signing software bills of materials with Cosign"
lead: "Use Cosign to sign a software bill of materials"
date: 2022-13-07T15:22:20+01:00
lastmod: 2022-13-07T15:22:20+01:00
draft: false
images: []
menu:
  docs:
    parent: "sigstore"
weight: 620
toc: true
---

On the site it looks like this:

We don't have the lead or description coming into the blog post cards:

But the description I believe will be indexed by search engines.

We also don't have the date coming into the front end.

In terms of authors, we don't have authors either in the headers or on the frontend. And we may want to have that as well as author landing pages. But authorship may be less important for straight documentation.

What are your thoughts?

Resource | How to connect your Kubernetes clusters to Enforce for Kubernetes

What topic are you requesting a resource about?

• Chainguard product -- Enforce for Kubernetes

Proposed title:

How to connect your Kubernetes clusters to Enforce for Kubernetes

Description:

There are three different approaches for connecting your Kubernetes clusters to Enforce for Kubernetes:

• Agentful -- Runs the Chainguard agent on your cluster
  • Without --private -- this is good for clusters with a publically accessible OIDC endpoint (GCP and EKS)
  • With --private -- good for must other clusters but some limitations
• Agentless -- We run the Chainguard agent for you ourside your cluster, but you need to set up cloud account associations (point to #65 article)

This article would walk through the different options and describe when each should be used combined with a small how-to.

Terminal updates — Sept. 2022

A few things to add to the terminal:

• rekor command should be replaced with the rekor-cli command to match official documentation
• In the JS file, more space / padding should be added so that the full tutorials can be read, right now the terminal is blocking the ends of tutorials
• Add the functionality so that the X in the upper-right corner can close the terminal

Code blocks syntax highlighting not working consistently

The code blocks syntax highlighting are not rendering consistently, in this section for instance the PHP code is totally plain even though the code block contains the correct suffix ```php` .

YAML blocks are rendering ok, but it looks rather basic, as with shell / commands. We may have to check if syntax highlighting is really functional or if there is some missing configuration.

Unlisted articles are back now

Describe the bug

Some of the articles we've unlisted have returned to the menu now:

To Reproduce
Steps to reproduce the behavior:

1. Go to 'https://edu.chainguard.dev/chainguard/chainguard-enforce/chainguard-enforce-kubernetes/chainguard-enforce-user-onboarding/'
2. Look at the available articles in the left gutter nav

Expected behavior

Articles with unlisted: true metadata shouldn't be visible.

Screenshots

Desktop (please complete the following information):

• OS: Fedora
• Browser: Firefox
• Version [e.g. 22] ... something

Additional context

Add any other context about the problem here.

Explain chainctl better in onboarding docs

Feedback from Empathy Day

I wish the docs explained more what was going on. When I chainctl install what is happening. When I create a policy, what's that mean (what's the policy mean, and what's creating it going to do)

I am happy to work with the edu team on clearing this up.

Remove extra padding/margin on `layouts/index.html` Chainguard logo

The chainguard logo on the landing page seems to take up more width than other elements on the page. See the following screenshot for an example:

It seems like the row CSS class might be the issue, other sections are using container and then some grid classes.

Add links to next steps at the end of the enforce onboarding doc

Feedback from empathy day:
I'd love a bunch of links to next steps at the end of the onboarding

possible next steps:

• create more policies
• connect more clusters
• invite more users
• check your policy status
• sign your images and commits

change kind prereq to k8s cluster prereq

empathy day feedback

why do i need kind to do enforce?

Can we have a tutorial for GKE or EKS or Azure? can we just say in the docs that you need a k8s cluster?

Getting started with apko links to deprecated GH action

Describe the bug
The Getting Started with apko guide links to https://github.com/chainguard-dev/actions/tree/main/apko-build

If you want to run apko on CI/CD pipelines built on top of GitHub Actions, check the apko build action on GitHub.

It looks like that's deprecated

Verbose titles leading to crowded menus and breadcrumbs

Somewhat verbose self contained titles like "Chainguard Enforce User Onboarding" are good for SEO¹, but end up making our menus and breakcrumb navigation cramped and repetititve. For example:

Here the menu needs to fold because of how long the title is and the breadcrumb says Chainguard three times.

Can we make our titles and navigation a bit more clear without breaking SEO?

Footnotes

1. https://drive.google.com/file/d/1QlhluUL5RBjrz97Xdgql8vTM0XjJQlOc/view ↩

How to use Chainguard Images

Enforce onboarding doc improvements

Note that some of these items might be duplicates of other issues.

• we mention gcp and gcloud cli but then change to kind
• mentions a bash upgrade guide but does not link to one
• instead of adding the download location to the PATH, can we mv chainctl to a bin folder?
• add installing cosign to prerequisites
• add EXPERIMENTAL flag to cosign verify $TUTORIAL_IMAGE | jq
• writing style, avoid using “we”

Write Agentful (EKS + GKE) tutorial

Priority 0 issue from here:

https://docs.google.com/spreadsheets/d/1OfZE0DTIPc8gPxjmneTUEnlWgz1PBSyI9Jp0vIAcb0Q/edit#gid=1639611530

Making this issue because I track Github issues more closely.

Draft location: https://docs.google.com/document/d/1IKEyq_EC2XfLIUtz5GCA3lr7ncMR2X3gC8MtCjh2500/edit#heading=h.sz0ghv88zu5t

Explain infra hierarchy better in enforce (groups etc)

empathy day feedback from ville
I’m creating a group but I just got the email, so I have no idea what a group is, what does it taste like. Wonder if we should give a little blurp here what a group is. Just putting myself in the users shoes and cut&paste are working wonders, but just wondering if this would be a good time to at least give a little blurp about what the user is doing and why

Adam comments:
We should probably give an overview of how the enforce hierarchy maps to k8s and how users should use them.

Write Agentless (EKS + GKE) tutorial

Priority 0 issue from here:

https://docs.google.com/spreadsheets/d/1OfZE0DTIPc8gPxjmneTUEnlWgz1PBSyI9Jp0vIAcb0Q/edit#gid=1639611530

Making this issue because I track Github issues more closely.

Draft location: https://docs.google.com/document/d/1fBYVp0D_EBTgaMpkN5HDlmt3l8KyJtPF1Yk2rp8tGKE/edit#heading=h.sz0ghv88zu5t

Review placement of login warning in enforce onboarding docs

feedback from empathy day:
"we might want to move this section above the creation of the group. I read things up to cut&paste, then cut&paste (esp. since I switch to different window). So, I found it surprising that this was after the cut&paste here:
You'll be asked whether you want to continue and to confirm logging in again. Press y in response to each prompt"

let's review if that warning is in the best spot or if it should be moved

Block quotes have larger font size than paragraph text

It looks like the block quotes render with larger text font size than normal paragraphs. This might not be an issue, but I found it drew my eye to the block quotes as being more important than the rest of the text, but we often use these block quotes as an aside that is less important to read than everything else.

As an example here is how github markdown renders this:

Hello there! this is some block quote text

The font size appears the same and the text appears a bit more grey to drop emphasis a bit on the content.

Better draw attention to MacOS bash upgrade prerequisite in enforce onboarding

empathy day feedback

UX could be improved to better draw attention for mac users regarding the need to upgrade to bash v4

in the prerequisites section

suggestion:
Perhaps just add another bullet point called

• bash - macOS users may need to upgrade bash to version 4 using this guide.

onboarding doc mismatch with chainctl output

The onboarding doc uses a lowercase 'y' while chainctl requests uppercase Y

"You'll be asked whether you want to continue and to confirm logging in again. Press y in response to each prompt"

Add Enforce Overview and Architecture overview to Getting started docs

Feedback from empathy day:

"I think in general we should have an enforce overview and architecture overview, and a little better explanation of what each part of the onboarding steps do"

My thoughts are a section that explains the basic features of enforce: allows you to implement and enforce security policies on your kubernetes fleet, monitor the status of policies in real time, easily update and distribute policies across clusters, require image signatures, SBOMs, and secure registries, etc.

and also a quick overview of the components:

• enforce platform: a SaaS solution that does blah blah
• enforce agent: lightweight agent that runs on your K8s cluster nodes to distribute policies, continuously monitor the security of clusters, and report information to the enforce platform
• chainctl: a command line utility that lets you manage users, groups, define policies, authenticate to chainguard, and check status of clusters at the command line

Condense three existing onboarding tutorials into one

From slack: https://chainguard-dev.slack.com/archives/C03H64P08UT/p1661881821439859

I wanted to update some of the existing onboarding docs to use the simpler local kind flow instead of gcloud. I see three similar docs right now for onboarding:

• https://edu.chngrd.xyz/chainguard/enforce-kubernetes/chainguard-enforce-cloud-shell/
• https://edu.chngrd.xyz/chainguard/enforce-kubernetes/chainguard-enforce-quick-start-cloud-shell/
• https://edu.chngrd.xyz/chainguard/enforce-kubernetes/chainguard-enforce-user-onboarding/

Is anyone opposed to condensing these into a single "quick start" or "getting started" tutorial that uses chainctl cluster install --private to drop the requirement on gcloud / cloud shell?

This seems like a good idea, but we need to make sure we don't drop the existing tutorials if they're being used by anyone. @ltagliaferri suggested keeping them up and simply dropping them from the menu so that the links still work

Automatically remove H2 repetition within chainctl docs?

Can the automated set up scrub out the second H2 so that docs don't repeat themselves, as in:

The second chainctl is an H2, the first one is in the title: of the Hugo front matter.

Clarify policies output from initial setup

feedback from empathy day:

After the creation we list the policies, and there’s only one (and if that would be the case, seems redundant). But it says A few policies will be in place in addition to the policy you just created. But I only have one policy, expected?

Hugo Shortcode to include Rumble graphs

Instead of using a static image, I'd like to include the actual graphs from Rumble (as an iframe). To facilitate that, I will try to create a shortcode that we can reuse at any docs page.

Resource | How to set up cloud account associations

What topic are you requesting a resource about?

• Chainguard product -- Kubernetes Enforce

Proposed title:

How to set up cloud account associations

Description:

Cloud account associations are a key feature for folks using cloud providers like AWS and GCP (and Azure in the future). They enable the following features:

• Verifying Cloud KMS based signatures
• Connecting EKS and GKE clusters without the need for an agent running (agentless)
• Checking signatures and SBOMs in private ECR and GCR registries without the need for image pull secrets

This article would:

• Describe what account associates are and when to use them
• Walk through how to set up an AWS and GCP account association and verify its working
• Briefly describe how they work (enough to give folks a sense of the security posture and whats happening here)

Search bar

The search bar is not working, we should either figure out what library is missing here or kill the search bar

Resource | How to connect to Private Registries

What topic are you requesting a resource about?

• Chainguard product -- Enforce for Kubernetes

Proposed title:

How to connect to Private Registries

Description:

There is a small section on how to connect to a private registry at the bottom of the onboarding / getting started docs. I'd like to move this to its own article and just add a section to the bottom with a list of further reading perhaps if folks are interested in the topic. The content would be similar to what we have right now, but also discuss how to use cloud account associations to connect to private ECR and GCR registry using our impersonation methods (this would link to #65)

Resource: Document terraform defaults

What topic are you requesting a resource about? Enforce Terraform Provider

• Chainguard product - Enforce
• Open source related - No
• Conceptual security related - No
• Other (please describe)

Proposed title:
EKS Enforce Settings or something sufficiently vague 😂

Description:
Our terraform provider contains a lot of useful settings like impersonation values for AWS. There are also values for roles and the capabilities that we should document so folks who don't use our terraform provider can set manually.

Eventually I think we'll want further docs on the terraform provider once it's public

[Images] Include additional demonstration of SBOM and Signature features

As suggested by @danpopnyc :

We should include a demonstration / proof of the additional features built-in with Chainguard Images: SBOMs and Signatures. Currently the overview page has a CVE comparison graph that proves the point of "less CVEs", and we can add the commands to check and demonstrate the Sigstore queries for SBOM and container signatures:

COSIGN_EXPERIMENTAL=1 cosign verify cgr.dev/chainguard/nginx | jq

and

COSIGN_EXPERIMENTAL=1 cosign download sbom cgr.dev/chainguard/nginx | jq

The question is: is the Overview page the right place to include these, considering we also want to include the output and it can make the page very long? Should we have an additional page for these instructions that we can link from other places? With a separate page we may be able to use an interactive terminal (just an idea).

Cc @ltagliaferri @jamonation @SharpRake

missing space in onboarding doc between -o and json

empathy day feedback
Moved onto https://console.enforce.dev/onboarding/installation/inspect-containers
export CLUSTER_ID=$(kubectl get ns gulfstream -ojson | jq -r .metadata.uid)
Missing space in -ojson
Still functional, but personally prefer a space =D

format docker prerequisite in onboarding docs in monotype

Describe the bug
In enforce prerequisites, the apps needed are listed in monotype style (kind, curl, jq), but Docker is not.

To Reproduce
Steps to reproduce the behavior:

1. Go to enforce onboarding docs
2. Scroll down to prerequisites
3. See error

Expected behavior
docker should match the rest

Screenshots
If applicable, add screenshots to help explain your problem.

Preload some software to the terminal

I am trying to do the screencast part of the sizzle reel for @seemichelle but was not able to demo the terminal. Here are the issues I had:

Not sure if I am missing something but I added the terminal here https://edu.chainguard.dev/open-source/sigstore/cosign/how-to-sign-a-container-with-cosign/ and I was not able to go through the tutorial. I was eventually able to install through the binary install but I needed to first install many dependencies (curl, wget, vi, nano, etc. needed to be manually installed), and I could not use sudo which could be a user issue for copy / pasting. Once I did get the binary there I could not update permissions to use the cosign command.

With Cosign not working, I moved to apko but I was not able to install Docker.

Some questions:

• Is there an existing demo video I can use?
• Will pre-installed Sigstore and Docker (+ dependencies) be achievable for launch?

Update Enforce and chainctl docs to use single `install` command instead of `mv` and `chmod`

Using install on macOS and Linux can combine the two mv and chmod commands into one.

The following command moves the file into place, with executable permissions, while preserving ownership for things like unprivileged in-place upgrades:

sudo install -o $UID -g $GID -m 0755 chainctl /usr/local/bin/chainctl

There are a few places in the docs where this should be updated:

• content/ui/enforce-onboarding-quickstart.md
• content/chainguard/chainguard-enforce/chainguard-enforce-kubernetes/chainguard-enforce-user-onboarding.md
• content/chainguard/chainguard-enforce/chainctl-docs/how-to-install-chainctl.md

Log4Shell demo tutorial

Putting together a tutorial that walks readers through running a sample app that includes a vulnerable version of Log4j.

Add frontend link for readers to file an issue onto GitHub

Also create an issue template for this

Add links to icons on home page

These are currently placeholders, but I would expect to be able to click the icons to take me somewhere.

As in, the Glossary page I would expect to take me to the Chainguard Glossary, the Articles I would expect to take me to a link of all the articles (which I don't think we can currently do... maybe another issue 🤔 ).

I think something to add in before we go live 😄

User in Linux environments

Do we want to have $, #, % prefixes in our command prompt examples? Since we have the COPY buttons those would automatically copy those unless we suppress them.

I wonder because the commands and the output look exactly the same.

The Sigstore docs and Linux Foundation course keep the $ in command line examples.

Alternately, we can differentiate input / output in a different way.

Enforce FAQ

Working on a public-facing FAQ focusing on Enforce

Markdown output code blocks

Perhaps we can remove the "copy" button from the output code blocks and also make them not highlight text the way they currently do. I think it interferes with reader scanning, especially for those who would like to run through something quickly.

"Introduction to Cosign" and "How to Install Cosign" Sorted to the Bottom

Describe the bug
The "Introduction to Cosign" and "How to Install Cosign" navigation links are at the bottom of the list under the "Cosign" header.

To Reproduce
Steps to reproduce the behavior:

1. Go to https://edu.chainguard.dev/open-source/sigstore/
2. Scroll to the bottom
3. Click on "Cosign"
4. See the navigation list
5. Click on any of the items
6. See the navigation list under "Cosign" on the left

Expected behavior
The "Introduction to Cosign" and "How to Install Cosign" navigation links are at the top of the list under the "Cosign" header.

Screenshots

Desktop (please complete the following information):

N/A

Smartphone (please complete the following information):

N/A

Additional context
The fix is to adjust the weight in the front-matter of those 2 pages to be smaller than the rest. I just want to make sure you're all on board with this change and reasoning.

Add kubectl to enforce prerequisites

empathy day feedback:

Oh, one more thing. Regarding prerequisites, we need kubectl but it’s not in the prerequisites. We should probably add that to the prerequisites.

should also specify minimum version required

"What Is Software Supply Chain Security?" tutorial

Following our chat later today, a tutorial to be added to the security section of the site. I just refactored the organization, so you can add a markdown file right into the software-security directory. The header would be something like this:

---
title: "What Is Software Supply Chain Security?"
description: "An overview to software supply chain security"
lead: "An overview to software supply chain security"
type: "article"
date: 2022-10-13T15:21:01+02:00
lastmod: 2022-10-13T15:21:01+02:00
date: 2022-08-01T15:21:01+02:00
lastmod: 2022-08-01T15:21:01+02:00
draft: false
images: []
menu:
  docs:
    parent: "security"
weight: 130
    parent: "software-security"
weight: 10
toc: true
---

If you think of a better header that "Software Security" feel free to add that to the PR or you can file a separate issue. 

Thank you!

Rename Chainguard for Github to Chainguard for Git in the docs

It currently works with Github, but we eventually want to add support for gitlab etc.

Improve Syntax Highlighting

The current syntax highlighting theme doesn't have a good contrast on dark mode. Ideally, let's use the theme toggle button to also change the syntax highlighting theme when users change from light to dark mode.

Separate quickstart tutorial from onboarding docs

Feedback from empathy day:

The thinking between UI docs and edu/docs was to have the thorough explanations on docs and the quickstart tutorial on the UI itself, with that eventually becoming a more interactive onboarding experience. This will help us from cannibalizing our own stuff and avoid confusing users by directing them to multiple places. I would like to scope these two use cases right, so the feedback is helpful

Seems like a Q4 solutioning effort and Q1 development item maybe

Add DNS entry for edu.chainguard.dev pointing at App Engine

We'd like to get DNS set up ahead of the site launch and will need a bit of help @afeddersen. The Chainguard Academy site is hosted on App Engine at https://chainguard-academy.uc.r.appspot.com with IAP restricting access to chainguard.dev project members until launch.

The process to add a custom domain to App Engine is a little involved, requiring validation with a TXT record, and then adding a CNAME to point at App Engine itself.

Here's what Google shows when I start the process:

Once that TXT record is verified, I think the CNAME to point edu.chainguard.dev at is ghs.googlehosted.com. From there I'm fairly sure I can finish the rest in App Engine, e.g. TLS cert.

broken link to curl download docs in enforce prerequisites

the prerequisites for enforce inside the platform link to curl download docs, the link is broken

curl — follow the relevant curl download docs for your machine.

Document more Enforce for k8s policy examples

Providing customer with more policy examples is something high on our priority list for Q4. I believe we do have examples now for policies but have yet to document them in the Enforce product docs. There are example policies here and also upstream here. Here's another related doc we started on curated policy ideas for reference.

Improve Enforce docs structure

Consider splitting the Enforce docs into sections:

• Enforce overview and architecture maybe
  • Signing images, creating sboms
    • Link to sigstore projects and docs
    • Using signing keys vs. keyless
  • Cli vs web
  • Agent vs. agentless
  • Runtime enforcement vs continuous
  • IAM, groups, invite codes
• Getting started with enforce
  • Prereqs / compatible k8s distros, versions, etc.
  • Signing up
  • Signing your images, making sboms
  • Setting up chainctl
  • Sample policies
  • Applying policies to cluster
  • Viewing logs
• Chainctl CLI detailed docs. Why do i need this and what does it do that i can’t do with kubectl
• Enforce web UI detailed docs - what do i use this for?
• Separately, quickstart tutorial