Incorporated feedback, added passkey references, more links, and new …

…video

README.md

@@ -34,13 +34,13 @@
   <p align="center">
     Developer guide to teach you how to maximize the power of the YubiKey to secure your software supply chain. This guide contains examples on how to use the YubiKey to enable account protections, commit signing, and code signing. By the end of this guide you, and your organization will have the tools needed to quickly onboard developers to allow them to focus more time on producing code, and less time configuring their environment. 
     <br />
-    <a href="https://github.com/YubicoLabs/passkey-relying-party-example/tree/master#about-the-project"><strong>Explore the docs »</strong></a>
+    <a href="https://github.com/YubicoLabs/secure-software-supply-chain-guide/tree/master#about-the-project"><strong>Explore the docs »</strong></a>
     <br />
     <br />
     ·
-    <a href="https://github.com/YubicoLabs/secure-software-supply-chain-guide">Report Bug</a>
+    <a href="https://github.com/YubicoLabs/secure-software-supply-chain-guide/issues/new?assignees=&labels=&projects=&template=bug_report.md&title=">Report Bug</a>
     ·
-    <a href="https://github.com/YubicoLabs/secure-software-supply-chain-guide">Request Feature</a>
+    <a href="https://github.com/YubicoLabs/secure-software-supply-chain-guide/issues/new?assignees=&labels=&projects=&template=feature_request.md&title=">Request Feature</a>
   </p>
 </div>
 

docs/docs/guides/administrators.mdx

@@ -68,6 +68,14 @@ Next let’s dive into steps that administrators can take to ensure that users a
 
 We are focused on enforcing branch protection rules that require commit signing, but you should also take the opportunity to add other requirements such as requiring pull requests and approvals for your main branch.
 
+:::tip
+
+Requiring commit signing is a tactic that works well for developers in a contained ecosystem, such as an organization. In these cases, a security team, or admin, is able to communicate and enforce commit signing based on internal mandates or requirements. The keys are also correlated to trusted internal accounts that are owned, and managed by the organization.
+
+Commit signing may not work well in an open ecosystem, such as an open-source project being built by an anonymous population. Open-source contributors will be utilizing accounts not part of your organization, therefore the signed commit doesn't provide the assurance that the code came from a trustworthy source. In this case you should focus on requiring high assurance MFA of your administrators who are able to merge the pull requests from anonymous accounts into the main branch.
+
+:::
+
 ### Enforce branch protection rules
 
 <Tabs groupId="source-control-type" className="my_tabs">

docs/docs/guides/deployments.md

@@ -28,4 +28,9 @@ The YubiHSM2 is capable of generating a key pair that could be used for code sig
 
 Follow the steps on the link below to see an example of how to sign a JAR file using the YubiHSM2.
 
-[Configuring YubiHSM 2 for Java code signing](https://github.com/YubicoLabs/yubihsm-java-enrollment)
+- [Configuring YubiHSM 2 for Java code signing](https://github.com/YubicoLabs/yubihsm-java-enrollment)
+
+The YubiHSM2 isn't the only Yubico tool that can be used for code signing. Your YubiKey can also utilize it's PIV module to perform code signing. See the links below for examples on signing Android, and Apple based (iOS, macOS) applications
+
+- [Mac code signing](https://developers.yubico.com/PIV/Guides/Mac_code_signing.html)
+- [Android code signing](https://developers.yubico.com/PIV/Guides/Android_code_signing.html)

docs/docs/guides/developers.mdx

@@ -4,6 +4,7 @@ sidebar_position: 2
 
 import Tabs from "@theme/Tabs";
 import TabItem from "@theme/TabItem";
+import ReactPlayer from "react-player";
 
 # Developer guide
 
@@ -27,13 +28,25 @@ If you don't want to read all of the content below, then just perform the follow
 <Tabs groupId="source-control-type" className="my_tabs">
   <TabItem value="GitHub" label="GitHub" default>
 
-[Configuring two-factor authentication using a security key](https://docs.github.com/en/authentication/securing-your-account-with-two-factor-authentication-2fa/configuring-two-factor-authentication#configuring-two-factor-authentication-using-a-security-key)
+:::tip Security keys vs passkeys
+GitHub allows you to leverage authentication through either a passkey or security key as 2FA. YubiKeys do support passkeys in the form of a device-bound discoverable credential. It's up to your security policy to decide which preference you have for your users, as YubiKeys will support both options.
 
-  </TabItem>
-  <TabItem value="GitLab" label="GitLab">
+Yubico generally recommends to generate a passkey on a YubiKey as it enables passwordless login, and removes the need to utilize a passkey
 
-[Set up a WebAuthn device](https://docs.gitlab.com/ee/user/profile/account/two_factor_authentication.html#set-up-a-webauthn-device)
+:::
 
+<ul>
+<li>
+    <a href="https://docs.github.com/en/authentication/authenticating-with-a-passkey/managing-your-passkeys">Managing your passkeys</a>
+  </li>
+  <li>
+    <a href="https://docs.github.com/en/authentication/securing-your-account-with-two-factor-authentication-2fa/configuring-two-factor-authentication#configuring-two-factor-authentication-using-a-security-key">Configuring two-factor authentication using a security key</a>
+  </li>
+</ul>
+  </TabItem>
+  <TabItem value="GitLab" label="GitLab">
+  <a href="https://docs.gitlab.com/ee/user/profile/account/two_factor_authentication.html#set-up-a-webauthn-device">Set up a WebAuthn
+    device</a>
   </TabItem>
 </Tabs>
 
@@ -112,13 +125,25 @@ Browser based authentication is presented to the user when they attempt to acces
 <Tabs groupId="source-control-type" className="my_tabs">
   <TabItem value="GitHub" label="GitHub" default>
 
-[Configuring two-factor authentication using a security key](https://docs.github.com/en/authentication/securing-your-account-with-two-factor-authentication-2fa/configuring-two-factor-authentication#configuring-two-factor-authentication-using-a-security-key)
+:::tip Security keys vs passkeys
+GitHub allows you to leverage authentication through either a passkey or security key as 2FA. YubiKeys do support passkeys in the form of a device-bound discoverable credential. It's up to your security policy to decide which preference you have for your users, as YubiKeys will support both options.
 
-  </TabItem>
-  <TabItem value="GitLab" label="GitLab">
+Yubico generally recommends to generate a passkey on a YubiKey as it enables passwordless login, and removes the need to utilize a passkey
 
-[Set up a WebAuthn device](https://docs.gitlab.com/ee/user/profile/account/two_factor_authentication.html#set-up-a-webauthn-device)
+:::
 
+<ul>
+<li>
+    <a href="https://docs.github.com/en/authentication/authenticating-with-a-passkey/managing-your-passkeys">Managing your passkeys</a>
+  </li>
+  <li>
+    <a href="https://docs.github.com/en/authentication/securing-your-account-with-two-factor-authentication-2fa/configuring-two-factor-authentication#configuring-two-factor-authentication-using-a-security-key">Configuring two-factor authentication using a security key</a>
+  </li>
+</ul>
+  </TabItem>
+  <TabItem value="GitLab" label="GitLab">
+  <a href="https://docs.gitlab.com/ee/user/profile/account/two_factor_authentication.html#set-up-a-webauthn-device">Set up a WebAuthn
+    device</a>
   </TabItem>
 </Tabs>
 
@@ -127,6 +152,8 @@ Once the security key is added, the user will then be prompted for it when they
 <Tabs groupId="source-control-type" className="my_tabs">
   <TabItem value="GitHub" label="GitHub" default>
 
+[Signing in with a passkey](https://docs.github.com/en/authentication/authenticating-with-a-passkey/signing-in-with-a-passkey)
+
 [Using a security key](https://docs.github.com/en/authentication/securing-your-account-with-two-factor-authentication-2fa/accessing-github-using-two-factor-authentication#using-a-security-key)
 
   </TabItem>
@@ -242,6 +269,14 @@ Git commit signing is traditionally done with GPG keys, but many of the popular
 
 ### Using SSH
 
+You can follow along with this video, or use the instructions below
+
+<ReactPlayer
+  controls
+  url="https://www.youtube.com/watch?v=2M2vKQwbCDk"
+  style={{ marginBottom: "2em" }}
+/>
+
 1. [Follow the steps above](#generate-an-ssh-key) to generate an SSH key using your YubiKey.
 2. [Follow the steps above](#add-the-ssh-key-to-your-account) to add the SSH key for commit signing - **Ensure that when prompted for `Key type` that you select `Signing key`**
 3. Once added to your account, run the following commands to ensure that commits are always signed, and that signing is performed using SSH

docs/docs/mitigation.md

@@ -23,6 +23,8 @@ The content above is meant to act as a high level summary of the guidance provid
 
 This section with provide actionable paths that you can take to protect the integrity of your software projects. These concepts will be used through the rest of this guide when highlighting the different actions that can be taken to protect the potential targets in your organization.
 
+Keep in mind that the concepts below are not encompassing of every technique that can be used to protect your software supply chain (such as static analysis, vulnerability scanning, etc). The concepts covered below are areas that can be specifically hardened through the use of a YubiKey or YubiHSM.
+
 ### Account protection
 
 Account protection is important as it prevents malicious users from gaining access to accounts, and making changes on someone's behalf. Developers would not want someone making changes to their account, or to the code that they have written. Administrators would not want someone with access to their accounts to change repository or organizational settings.
@@ -33,9 +35,9 @@ A YubiKey provides two factors of authentication: possession of the security key
 
 ### Commit signing
 
-Commit protection is important as it allows you to verify that the code added to a repository is coming from a trusted source. It is possible to make a commit seem as if it came from someone else by just changing the name and email details in your `git.config` file. In the eyes of git this isn't a problem as the metadata sent with a commit is not meant to act as a form of authentication. In the case of GitHub, you wouldn't be able to push code to another user's GitHub account, this would require authentication. Regardless, even with account protection you would want some form of git signing to combat:
+Commit protection is important as it allows you to verify that the code added to a repository is coming from a trusted source. It is possible to impersonate a user by making a commit seem as if it came from someone else by just changing the name and email details in your `git.config` file. In the eyes of git this isn't a problem as the metadata sent with a commit is not meant to act as a form of authentication. In the case of GitHub, you wouldn't be able to push code to another user's GitHub account, this would require authentication. Regardless, even with account protection you would want some form of git signing to combat:
 
-1. Commits coming from a compromised account
+1. Commits coming from a compromised or impersonated account
 2. Commits coming from a machine where your signing key is not present
 
 The YubiKey is able to generate cryptographic keys that are capable of signing commits. This ensures that any commit that is entering your codebase is coming from a legitimate user who has possession of the security key with the signing key present.

docs/docs/targets.md

@@ -16,7 +16,7 @@ Note that this material is not encompassing of every risk associated with this t
 
 Any topic that relates to software development will have developers at the forefront. The term developers is used to describe this persona, but this can be encompassed by any member of your organization who contributes code/material to your software projects, including: architects, technical writers, designers, and more. This isn’t limited to just people in your organization, this can also include 3rd party developers being contracted by your company, and the developers who maintain the open source or SaaS projects being leveraged from your software.
 
-Compromising a developer's account would allow an attacker to add their own malicious functions to a software project, making them a prime target.
+Compromising a developer's account would allow an attacker to add their own malicious functions to a software project, making them a prime target. Keep in mind, that this isn't only the code being written directly to your repository, but the 3rd party dependencies and packages that are being used to support your core business logic.
 
 ### Administrators
 
@@ -49,4 +49,4 @@ Some developers may see secure software development practices as hindering to th
 
 ### Dependency on SaaS, OSS, and MSPs
 
-The use of Software-as-a-service (SaaS) and open-source software (OSS) tools has continued to increase. More and more developers are including code that they did not write into their solutions. Enterprises that leverage managed service providers (MSPs) are now also allowing external developers to contribute to their software projects. Developers now need to manage the complexities of secure software development and tooling not just for their organization, but for the external ones that are contributing to a project.
+The use of Software-as-a-service (SaaS) and open-source software (OSS) tools has continued to increase. More and more developers are including code that they did not write into their solutions. Enterprises that leverage managed service providers (MSPs) are now also allowing external developers to contribute to their software projects. Open-source software projects are also a prime target, as these 3rd party dependencies are often installed and updated without much thought behind the code that the packages could be introducing. With these challenges, developers now need to manage the complexities of secure software development and tooling not just for their organization, but for the external ones that are contributing to a project.

docs/docusaurus.config.js

@@ -6,15 +6,15 @@ const darkCodeTheme = require('prism-react-renderer/themes/dracula');
 
 /** @type {import('@docusaurus/types').Config} */
 const config = {
-  title: 'Secure Software Supply Chain Guide',
-  tagline: 'Learn how to leverage the YubiKey and YubiHSM to help enhance, streamline, and secure your software development practices.',
+  title: 'Protect your software supply chain with YubiKeys and YubiHSMs',
+  tagline: 'Learn how to leverage the YubiKey and YubiHSM to help enhance, streamline, and secure your software development practices. This guide is for developers, architects, and administrators looking to get the most of their Yubico tools to improve their developer experience.',
   favicon: 'img/favicon.ico',
 
   // Set the production url of your site here
   url: 'https://yubicolabs.github.io',
   // Set the /<baseUrl>/ pathname under which your site is served
   // For GitHub pages deployment, it is often '/<projectName>/'
-  baseUrl: '/',
+  baseUrl: '/secure-software-supply-chain-guide',
 
   // GitHub pages deployment config.
   // If you aren't using GitHub pages, you don't need these.
@@ -57,12 +57,12 @@ const config = {
     /** @type {import('@docusaurus/preset-classic').ThemeConfig} */
     ({
       // Replace with your project's social card
-      image: 'img/yubico-logo.png',
+      image: '/img/yubico-logo.png',
       navbar: {
         title: 'Secure Software Supply Chain Guide',
         logo: {
           alt: 'My Site Logo',
-          src: 'img/yubico-logo.png',
+          src: '/img/yubico-logo.png',
         },
         items: [
           {

docs/src/components/HomepageFeatures/index.js

@@ -1,32 +1,52 @@
-import React from 'react';
-import clsx from 'clsx';
-import styles from './styles.module.css';
+import React from "react";
+import clsx from "clsx";
+import styles from "./styles.module.css";
+import ReactPlayer from "react-player";
 
 const FeatureList = [
   {
-    title: 'Protection for every person',
+    title: "Protection for every stage of your software supply chain",
     image: "/secure-software-supply-chain-guide/img/full_flow.png",
     description: (
-      <>
-        Note how Yubico's products can be used to protect each actor present in building, maintaining, and using an application. 
-      </>
+      <div>
+        <p>
+          After completing this guide, you'll have an understanding of some
+          simple security techniques that can be used to harden the security
+          around your application's development environment.
+        </p>
+        <p>
+          Often times these techniques get overlooked as they're seen as
+          friction to the developer experience. With Yubico's tools, you never
+          have to sacrifice security for ease of use. By the end of this guide
+          you'll understand how a one time setup can provide both a secure, and
+          easy to use development environment.
+        </p>
+        <p>
+          The graph below shows what a secure environment looks like between an
+          organization's administrators, developers, and infrastructure that are
+          all equipped with Yubico solutions.
+        </p>
+      </div>
     ),
   },
 ];
 
-function Feature({image, title, description}) {
+function Feature({ image, title, description }) {
   return (
-    <div className={clsx('col col--12')}>
+    <div className={clsx("col col--12")} style={{ marginBottom: "3em" }}>
       <div className="text--center padding-horiz--md">
         <h3>{title}</h3>
-        <p>{description}</p>
+        <div>{description}</div>
       </div>
       <div>
-      <img src={image} style={{
-        display: "block",
-        marginLeft: "auto",
-        marginRight: "auto",
-      }} />
+        <img
+          src={image}
+          style={{
+            display: "block",
+            marginLeft: "auto",
+            marginRight: "auto",
+          }}
+        />
       </div>
     </div>
   );
@@ -41,6 +61,29 @@ export default function HomepageFeatures() {
             <Feature key={idx} {...props} />
           ))}
         </div>
+        <div className="row">
+          <div className={clsx("col col--12")}>
+            <div className="text--center padding-horiz--md">
+              <h3>Set up your YubiKey for Git signing with FIDO2</h3>
+              <p>
+                One of the topics included in this guide is git signing with a
+                YubiKey. See the video below to learn how easy it is to sign a
+                commit with FIDO2. This guide includes a script that
+                automatically generates and configures a signing key directly on
+                your YubiKey
+              </p>
+            </div>
+          </div>
+        </div>
+        <div
+          className="row row--align-center"
+          style={{ justifyContent: "center" }}>
+          <ReactPlayer
+            controls
+            className="react-player"
+            url="https://www.youtube-nocookie.com/embed/2M2vKQwbCDk"
+          />
+        </div>
       </div>
     </section>
   );

docs/src/css/custom.css

@@ -42,7 +42,12 @@ video {
 }
 
 .tabs-container {
-  border:2px solid #9aca3c;
+  border: 2px solid #9aca3c;
   padding: 1em;
   box-shadow: rgba(0, 0, 0, 0.24) 0px 3px 8px;
+}
+
+.player-wrapper {
+  position: relative;
+  /* Player ratio: 100 / (1280 / 720) */
 }