Lab instructions (#227)

* adding codespace instructions Signed-off-by: Will <[email protected]> * typoi Signed-off-by: Will <[email protected]> * adding a note about pushing code to the lab creation notes, referencing the lab creation process in the start of each class Signed-off-by: Will <[email protected]> * explaining the build script Signed-off-by: Will <[email protected]> --------- Signed-off-by: Will <[email protected]>
mitre · Oct 8, 2024 · 1875ca9 · 1875ca9
1 parent 37626f2
commit 1875ca9
Show file tree

Hide file tree

Showing 12 changed files with 82 additions and 1 deletion.
diff --git a/src/assets/img/codespace_button.png b/src/assets/img/codespace_button.png
diff --git a/src/assets/img/codespace_modal.png b/src/assets/img/codespace_modal.png
diff --git a/src/assets/img/create_codespace.png b/src/assets/img/create_codespace.png
diff --git a/src/assets/img/creating_the_fork.png b/src/assets/img/creating_the_fork.png
diff --git a/src/assets/img/fork.png b/src/assets/img/fork.png
diff --git a/src/assets/img/my_fork.png b/src/assets/img/my_fork.png
diff --git a/src/assets/img/vs_code.png b/src/assets/img/vs_code.png
diff --git a/src/courses/advanced/README.md b/src/courses/advanced/README.md
@@ -29,6 +29,10 @@ The purpose of this class is to take you beyond profile development and give you
 - Agnostic to other DevOps tools and techniques
 - Integrates into multiple configuration managament tools
 
+### 1.2.1 The Lab Environment
+
+This class will use GitHub Codespaces for a consistent environment for all students. See instructions for setting up your own lab environment [here](../../resources/05.md).
+
 ## 1.3 The Road to Security Automation
 
 InSpec is one of the primary tools in the Security Automation workflow. It integrates easily with orchestration and configuration management tools found in the DevOps world.

diff --git a/src/courses/beginner/README.md b/src/courses/beginner/README.md
@@ -30,6 +30,10 @@ The purpose of this class is to give you the fundamentals of how to develop secu
 - Agnostic to other DevOps tools and techniques
 - Integrates into multiple configuration management tools
 
+### The Lab Environment
+
+This class will use GitHub Codespaces for a consistent environment for all students. See instructions for setting up your own lab environment [here](../../resources/05.md).
+
 ## The Road to Security Automation
 
 InSpec is one of the primary tools in the Security Automation workflow. It integrates easily with orchestration and configuration management tools found in the DevOps world.

diff --git a/src/courses/user/08.md b/src/courses/user/08.md
@@ -21,7 +21,7 @@ To execute the Chef Supermarket profile on your target system, run this `inspec
 
 Sometimes, there are multiple profiles available for the same software component. This could be because there are different people or teams who both wrote automation content, or it could be because one profile is based on one set of guidance (such as a DISA STIG) and another profile could be based on different guidance (such as a CIS Benchmark). 
 
-If you see multiple profiles available and are unsure what to use, read the READMEs in each to see what guidance they are based on to understand what is most useful for your situation. You can also run mutliple profiles and compare the results to see which is more informative for your assessment. Lastly, you can always reach out to [email protected] if you have more questions.
+If you see multiple profiles available and are unsure what to use, read the READMEs in each to see what guidance they are based on to understand what is most useful for your situation. You can also run multiple profiles and compare the results to see which is more informative for your assessment. Lastly, you can always reach out to [email protected] if you have more questions.
 :::
 
 ### 8.2 Forming the InSpec Command

diff --git a/src/courses/user/README.md b/src/courses/user/README.md
@@ -31,6 +31,10 @@ By the end of the SAF User Class, you should be able to achieve all of the follo
 -	Visualize InSpec results and third party security tool data.
 -   Automatically export checklist results from a security assessment.
 
+### 1.3.1 The Lab Environment
+
+This class will use GitHub Codespaces for a consistent environment for all students. See instructions for setting up your own lab environment [here](../../resources/05.md).
+
 ## 1.4 The Road to Security Automation
 
 As you can see from the picture below, the process for developing automated security tests starts with requirements documents like SRGs, STIGs or CIS Benchmark that are written in regular, human language and then implemented as code. We need that code to record test results in a standardized format so that we can easily export our security data somewhere people can use it to make decisions (like the Heimdall visualization app).

diff --git a/src/resources/05.md b/src/resources/05.md
@@ -0,0 +1,69 @@
+---
+index: true
+icon: page
+title: Lab Environments
+author: Will Dower
+headerDepth: 3
+---
+
+# Using Codespaces for a Lab Environment
+
+You can follow along with each exercise given in these training classes by creating a GitHub Codespace from one of the MITRE SAF team's GitHub repositories.
+
+## What is GitHub Codespaces?
+
+[Codespaces](https://github.com/features/codespaces) is GitHub's built-in cloud-based development environment service. Creating a Codespace creates a new virtual machine in GitHub's cloud that is prepopulated with that repository's code. The user can then access a Virtual Studio window in their browser that points to this virtual machine.
+
+Overall, Codespaces allow for a user to make a few clicks on a repository's page and get a simple way to view and edit code, with no local dependencies required, since all the compute is happening in GitHub's cloud.
+
+## Why Codespaces?
+
+Using a Codespace means that we, the instructors, can know for certain what capabilities and tools are available to the students in their development environments. It allows us to standardize the lab experience. If you're formally taking our classes, we will be using this method to do the exercises. If you are taking the classes as a self-taught experience, we still recommend you create a Codespace and follow along.
+
+## How do I launch a Codespace for my lab environment?
+
+You'll need to create a fork of the [SAF training lab environment repository](https://github.com/mitre/saf-training-lab-environment). That repository contains all the install scripts and sample code you will need for the User, Beginner, and Advanced classes.
+
+### Instructions
+
+1. Log into github.com. If you do not have one already, you'll need to create a [GitHub account](https://github.com/signup). You need to do this so that you can create your "own" copy of the lab environment repository by forking it.
+2. Access the [lab environment repository](https://github.com/mitre/saf-training-lab-environment).
+3. Click the **fork** button:
+![Forking a Repo](../../assets/img/fork.png)
+You'll be taken to the fork creation screen. Make sure you select the option to create the fork under your own profile, and not under an organizational account (if you are part of one).
+![Fork Menu](../../assets/img/creating_the_fork.png)
+4. You'll be taken to the new webpage for your fork. Note that it is a complete copy of the original MITRE-managed codebase, but you are now the owner.\
+![My Fork](../../assets/img/my_fork.png)
+5. Click the Code button to bring up the Codespaces modal (by default you might see a set of options for downloading the code _locally_, make sure you select the "codespace" tab on this modal).
+![Code Button](../../assets/img/codespaces_button.png)
+![Codespaces Modal](../../assets/img/codespaces_modal.png)
+6. Click the '+' to create a new codespace on the main branch of your forked repository. Note that if you leave your Codespace tab and return to this page, you will find a link to any existing virtual machines.
+You can click on the ellipses next to the '+' if you want to customize the VM running the Codespace, but none of the class exercises require anything more than a very basic 2-core machine.
+![Create a Codespace](../../assets/img/create_codespace.png)
+You will immediately be taken to a new tab, which will load a Virtual Studio Code window pointing to your shiny new VM running in GitHub's cloud.
+![Your Editing Window](../../assets/img/vs_code.png)
+7. The MITRE SAF team has included a script in this repository (`build-lab.sh`) that you can use to easily install all the tools we will be using for the classes. It installs:
+- InSpec
+- Ansible
+- The SAF CLI
+- Helpful extensions for VSCode to handle Ruby code (and therefore InSpec code)
+- A UBI8 and a NGINX container for practicing running Ansible and InSpec
+
+Once you have launched your codespace and your browser connects to it, run:
+
+```sh
+source ./build-lab.sh
+```
+
+to execute the install script.
+
+You can always re-run this script if one of your dependencies runs into a problem (for instance, if your containers go down because the Codespace automatically turned off to save resources). You could also run `source ./test-lab.sh` to do a quick spot check that InSpec, the SAF CLI, and your containers are present.
+
+
+### Your Lab Environment After the Class
+
+We suggest you fork the lab environment because it gives you ownership over the code you will write for these classes. If you use the `git` utility to commit your changes inside the Codespace, you will be committing to your own fork, which you own. Feel free to play around with the tools we will introduce you to inside your codespace; it's yours.
+
+NOTE that Codespaces are eventually turned off by GitHub if you do not use them for long enough -- if you ever want to refer back to what you did in these classes, be sure to not just commit your code with `git commit`, but push it back to the upstream repository with `git push`!
+
+