Merge pull request #283 from mitre/profile-dev-updates

profile dev updates

src/courses/profile-dev-test/02.md

@@ -1,42 +1,79 @@
 ---
 order: 2
 next: 03.md
-title: Repository Organization
+title: 2. Understanding Repository Organization
 author: Aaron Lippold
 ---
 
-## Repository Organization
+## Learning Objectives
 
-The repository and profile are organized into two primary branches: `main` and `TBD`. The repository has a set of `tags` representing iterative releases of the STIG from one Benchmark major version to the next. It also has a set of releases for fixes and updates to the profile between STIG Benchmark Releases.
+By the end of this section, you will:
 
-## Branches
+- Understand the branch strategy for STIG profiles
+- Learn about semantic versioning in the context of STIG releases
+- Know how to navigate tags and releases
 
-### `main` branch
+## Repository Structure Overview
 
-The `main` branch contains the most recent code for the profile. It may include bugs and is typically aligned with the latest patch release for the profile. This branch is primarily used for development and testing workflows for the various testing targets. For production validation, use the latest stable patch release.
+The InSpec profile repository should have a structured branching and tagging strategy to manage STIG profile versions and updates. This organizational strategy ensures reliable tracking of changes and stable releases for production use.
 
-### `v{x}r{xx}` branches
+## Branch Strategy
 
-The `v{x}r{xx}` branches represent the changes between releases of the benchmark. They align with the STIG releases for the Benchmark found at the DISA STIG [Document Library](https://public.cyber.mil/stigs/downloads/).
+Security developers and engineers should be putting actively developed changes and updates into feature branches.  Once those feature branches have been completed and peer reviewed, they should be merged into the version branch for the respective guidance release.  Once all required features, changes, bugfixes, etc. have been merged in, a release should be created - this means that the version branch should be merged into your main branch and a tag should be created.  The main branch of the repository ought to be the latest, working version of the codebase.  
 
-## Releases
+::: tip Branches are not releases
+Sometimes code ends up merged directly to the main branch - this is fine - the main branch is not a formal release.
+:::
 
-Releases use Semantic Versioning (SemVer), aligning with the STIG Benchmark versioning system of Major Version and Release. The SemVer patch number is used for updates, bug fixes, and code changes between STIG Benchmark Releases for the given product. STIG Benchmarks use a Version and Release tagging pattern `v{x}r{xx}` - like V1R12 - and we mirror that pattern in our SemVer releases.
+<table>
+  <thead>
+    <tr>
+      <th></th>
+      <th scope="col">Main Branch</th>
+      <th scope="col">Version Branch (`v{x}r{xx}`)</th> 
+    </tr>
+  </thead>
+  <tbody>
+    <tr>
+      <th scope="row">Purpose</th>
+      <td>Active development and testing</td>
+      <td>Work-in-progress tracking a major STIG benchmark release</td>
+    </tr>
+    <tr>
+      <th scope="row">Contains</th>
+      <td>Latest code and patches</td>
+      <td><p>Code that is becoming aligned to an official guidance release</p><p>DISA usually releases updates to STIGs on a quarterly basis.  See the [DISA STIG Document Library](https://public.cyber.mil/stigs/downloads/).</p></td>
+    </tr>
+    <tr>
+      <th scope="row">Example branch name</th>
+      <td>`main` or `master`</td>
+      <td>`v1r12` for Version 1, Release 12</td>
+    </tr>
+  </tbody>
+</table>
 
-## Tags
+## Version Control and Tagging Strategy
 
-### Current Tag
+### Tags
 
-We don't use a specific `current` or `latest` tag. The `current`/`latest` tag for the profile and repository will always be the latest major tag of the benchmark. For example, if `v1.12.3` is the latest Benchmark release from the STIG author, then the tag `v1.12` will point to the `v1.12.3` release of the code.
+#### Current Tag
 
-To use the current `main`, point directly to the GitHub repo.
+We do not recommend using a `current` or `latest` tag - if someone needs the latest and greatest, they can pull directly from the main branch of the repository.
 
-### Major Tags
+#### Major Tags
 
-Major tags point to the latest patch release of the benchmark. For example, `v1.3` and `v1.3.0` represent the first release of the Red Hat Enterprise Linux 8 STIG V1R3 Benchmark. The `v1.12.xx` tag(s) would represent the V1R12 Benchmark releases as we find bugs, fixes, or general improvements to the testing profile. This tag will point to its `v{x}r{xx}` counterpart.
+Major tags point to the latest patch releases of the benchmark. For example, `v1`, `v1.3`, and `v1.3.0` all should point at the same commit representing the first release of the Red Hat Enterprise Linux 8 STIG V1R3 Benchmark. The `v1.12.xx` tag(s) would represent the V1R12 Benchmark releases as we find bugs, fixes, or general improvements to the testing profile.
 
-## Patch Releases
+#### Patch Releases
 
 The latest patch release always points to the major release for the profile.
 
-For example, after releasing `v1.12.0`, we will point `v1.12` to that patch release: `v1.12.0`. When an issue is found, we will fix, tag, and release `v1.12.1`. We will then 'move' the `v1.12` tag so that it points to tag `v1.12.1`. This way, your pipelines can choose if they want to pin on a specific release of the InSpec profile or always run 'current'.
+For example, after releasing `v1.12.0`, we will point `v1.12` to that patch release: `v1.12.0`. When an issue is found, we will fix, tag, and release `v1.12.1`. We will then 'move' the `v1.12` tag so that it points to tag `v1.12.1`. This way, your pipelines can choose if they want to pin on a specific release of the InSpec profile or always run using the latest code on the main branch.
+
+### Semantic Versioning (SemVer)
+
+Format: `MAJOR.RELEASE.PATCH`
+
+- MAJOR: Matches STIG version
+- RELEASE: Matches STIG release
+- PATCH: Profile updates between STIG releases

src/courses/profile-dev-test/03.md

@@ -1,31 +1,51 @@
 ---
 order: 3
 next: 04.md
-title: Environment Setup
+title: 3. Environment Setup Guide
 author: Aaron Lippold
 ---
 
-## Required Software
+## Prerequisite Knowledge
 
-- RVM, or another Ruby Management Tool
-- Ruby v3 or higher
-- Git
-- VS Code or another IDE
-- Docker (if you want to test hardened and non-hardened containers)
-- AWS CLI
-- AWS Account
+- Basic command line experience
+- Familiarity with package managers
+- Understanding of environment variables
+- Basic Docker concepts
 
-## Required Accounts
+## Required Software Overview
 
-1. [AWS Console Account](https://aws.amazon.com/console/ "AWS Console Account")
-2. [Platform One Account](https://login.dso.mil/register "Platform One Account") (used for container testing)
-3. [P1 Harbor Token](https://login.dso.mil/auth/realms/baby-yoda/protocol/openid-connect/auth?client_id=harbor&redirect_uri=https%3A%2F%2Fregistry1.dso.mil%2Fc%2Foidc%2Fcallback&response_type=code&scope=openid+profile+email+offline_access&state=WS3BsNb5JevECV4aiy3irfegFETBHfRd "DSO Harbor Login") (used for container testing)
+Each tool listed below is essential for the course. We'll explain why you need each one:
 
-## Test Suite Environment Variables
+- **RVM (Ruby Version Manager)** - Manages Ruby installations
+- **Ruby v3+** - Core programming language for our testing framework
+- **Git** - Version control for managing code
+- **VS Code/IDE** - For writing and editing code
+- **Docker** - For container-based testing
+- **AWS CLI** - For interacting with AWS services
 
-1. Environment Variables used by Test Kitchen
+## Required Accounts Setup
 
-- `INSPEC_CONTROL`: Specifies which single control to run in the `bundle exec kitchen verify` phase, useful for testing and debugging a single requirement.
+Create accounts with these services before proceeding:
+
+1. **AWS Console Account**
+   - Purpose: Cloud infrastructure testing
+   - Sign up: [AWS Console](https://aws.amazon.com/console/)
+
+2. **Platform One (P1) Account**
+   - Purpose: Access to hardened containers
+   - Register: [Platform One Registration](https://login.dso.mil/register)
+
+3. **P1 Harbor Access**
+   - Purpose: Container registry access
+   - Get CLI token from your user account page: [Harbor Login](https://login.dso.mil/auth/realms/baby-yoda/protocol/openid-connect/auth?client_id=harbor)
+
+## Environment Configuration
+
+### 1. Test Kitchen Variables
+
+Important variables that control testing behavior:
+
+- `INSPEC_CONTROL`: Specifies which single control to run in the `bundle exec kitchen verify` phase - useful for testing and debugging a single requirement.
   - default: `none`
 - `KITCHEN_LOCAL_YAML`: Specifies the target testing environment you want to use to run and validate the profile.
   - default: `none`
@@ -34,31 +54,45 @@ author: Aaron Lippold
 - `HARDENED_CONTAINER_IMAGE`: Specifies the Docker container image you consider 'hardened' (used by `kitchen.container.yml`).
   - default: `registry1.dso.mil/ironbank/redhat/ubi/ubi8`
 
-2. AWS Environment
+### 2. AWS Environment Setup
+
+**Option 1: AWS Profiles (Recommended)**
+
+- Easier management of multiple environments
+- More secure than environment variables
+- Setup guide: [AWS CLI Profiles](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-files.html)
+
+**Option 2: Environment Variables**
+
+- Traditional AWS environment variables
+- Documentation: [AWS CLI Installation](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html)
+
+## Step-by-Step Installation Guide
 
-You can either use standard AWS Profiles to configure your environment or use the standard AWS Environment variables to run the test suite. See: [AWS CLI Installation & Configuration](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html "AWS CLI Install Guide")
+1. **Ruby Setup**
+   - Install RVM or alternative Ruby manager
+   - Install Ruby 3.1+
+   - Configure OpenSSL and certificates
 
-- Use the `AWS_PROFILE` environment variable and AWS Credential Profiles to simplify testing on multiple AWS environments or segments. This will allow you to easily manage multiple sets of AWS secrets and access keys with adjustments to a single variable. (See: [AWS CLI and Profile Setup](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-files.html "AWS CLI Profiles Setup"))
+2. **AWS Configuration**
+   - Install AWS CLI
+   - Configure credentials
+   - Test connection
 
-## Setting Up Your Environment
+3. **Project Setup**
+   - Clone repository
+   - Configure Harbor CLI access
+   - Set up Docker registry access
+   - Install dependencies
 
-1. Set up your Ruby Version Management system.
-2. Install Ruby 3.1 or higher.
-3. Configure OpenSSL, organization certificates, etc., for your environment and tooling.
-4. Set up your AWS CLI.
-5. Clone the repository.
-6. Obtain your [Harbor CLI Secret](https://registry1.dso.mil/harbor/projects "DSO Harbor Projects Page").
-7. After logging in, click on your User Profile "About" to get the token.
-8. Log in to the P1 Docker Registry.
-9. Use the command `docker login -u {PI USER NAME} -p '{HARBOR CLI SECRET}' registry1.dso.mil`.
-10. Run `bundle install` in your isolated Ruby environment.
+## Verification Steps
 
-## Post-Setup Checks
+Run these commands to verify your setup:
 
 - Verify your newly installed Ruby environment by running `ruby --version`.
 - Confirm that InSpec was installed by running `bundle exec inspec --version`.
 - Check that Test Kitchen was installed by running `bundle exec kitchen version`.
 - Verify that your `aws-cli` is correctly configured by running `aws s3 ls` (or your preferred test command for AWS CLI).
 - Confirm your bundle installation by running `bundle exec inspec --version`.
 - Verify you can pull from RepoOne by running `docker pull https://repo1.dso.mil/dsop/redhat/ubi/ubi8`.
-- Celebrate 🎉️ if everything went well.
+- Celebrate 🎉️ if everything went well.

src/courses/profile-dev-test/04.md

@@ -1,24 +1,84 @@
 ---
 order: 4
 next: 05.md
-title: Test your Test Environment
+title: 4. Test your Test Environment
 author: Aaron Lippold
 ---
 
-## Getting to know the Testing Suite
+## Learning Objectives
 
-Once you've set up the necessary tools, you're ready to run the profile. The testing environment is determined by Test Kitchen using environment variables.
+- Understand the different testing environments available
+- Learn how to use Test Kitchen commands
+- Execute your first test run
+- Troubleshoot common testing issues
 
-There are four testing environments to choose from:
+## Introduction
 
-1. AWS VPC Testing: This environment uses an AWS VPC for testing.
-2. Docker Testing: This environment uses Docker containers for testing.
-3. Vagrant Testing: This environment uses Vagrant virtual machines for testing.
-4. Local Testing: This environment uses your local machine for testing.
+Before diving into testing your security profiles, let's understand the testing environment and tools we'll be using. This module will guide you through the Test Kitchen framework and help you run your first test.
 
-The specifics of each environment's configuration are detailed in the following sections.
+## Available Testing Environments
 
-## Getting Your First Test Kitchen (TK) Run
+You have four options for setting up your testing environment:
+
+📦 **Docker Testing**
+
+- Uses containers for lightweight, fast testing
+- Perfect for local development
+- Minimal resource requirements
+
+🌥️ **AWS VPC Testing**
+
+- Uses AWS infrastructure
+- Ideal for production-like environments
+- Requires AWS credentials
+
+🖥️ **Vagrant Testing**
+
+- Uses virtual machines locally
+- Great for isolated testing
+- Supports multiple OS environments
+
+💻 **Local Testing**
+
+- Uses your local machine
+- Fastest to set up
+- Best for initial development
+
+## Test Kitchen Lifecycle
+
+Test Kitchen follows a four-stage lifecycle:
+
+1. **Create** 🏗️
+   - Sets up testing instance
+   - Prepares login credentials
+   - Initializes testing environment
+
+2. **Converge** 🔄
+   - Runs configuration management
+   - Applies system settings
+   - Prepares system state
+
+3. **Verify** ✅
+   - Executes InSpec profile
+   - Runs security tests
+   - Reports results
+
+4. **Destroy** 🗑️
+   - Cleans up resources
+   - Removes test instances
+   - Resets environment
+
+## Running Your First Test
+
+### Prerequisites
+
+Before starting, ensure you have:
+
+- Test Kitchen installed
+- Proper environment variables set
+- Required credentials configured
+
+### Basic Commands
 
 For each of these examples, you need to update the `KITCHEN_LOCAL_YAML` environment variable to point to the correct `kitchen.<TEST-TARGET>.yaml` file. Ensure that any required supporting environment settings, environment variables, profiles, etc., are in place. See Environment Variables and Testing Target Environments for more information.
 
@@ -44,4 +104,4 @@ You can also isolate which of the 'target suites' - either `vanilla` or `hardene
 ## Useful Test Kitchen Commands
 
 - `login`: Allows you to easily log in using the credentials created when you ran `bundle exec kitchen create`.
-- `test`: Runs all the Test Kitchen stages starting with create through destroy to easily allow you to go through a full clean test run.
+- `test`: Runs all the Test Kitchen stages starting with create through destroy to easily allow you to go through a full clean test run.