User manual (#46)

* uploading user manual, no screenshots

Signed-off-by: ssayed118 <[email protected]>

* updated filename & added screenshots

* fixed grammar + format

* added links for Vulcan

* updated format to match previous courses & added images (also left a notes page for future edits)

Signed-off-by: ssayed118 <[email protected]>

* adding objectives and intitial class overview

Signed-off-by: Emily Rodriguez <[email protected]>

* change language from coming soon to there

Signed-off-by: Emily Rodriguez <[email protected]>

* security guidance background wip, srgs vs stigs

Signed-off-by: wdower <[email protected]>

* added more pages, added TODOs for more of an outline of the content we want to get through

Signed-off-by: wdower <[email protected]>

* updated npm audit

Signed-off-by: Aaron Lippold <[email protected]>

---------

Signed-off-by: ssayed118 <[email protected]>
Signed-off-by: Emily Rodriguez <[email protected]>
Signed-off-by: wdower <[email protected]>
Signed-off-by: Aaron Lippold <[email protected]>
Co-authored-by: ssayed118 <[email protected]>
Co-authored-by: sumaa <[email protected]>
Co-authored-by: Emily Rodriguez <[email protected]>
Co-authored-by: Aaron Lippold <[email protected]>

README.md

@@ -15,7 +15,7 @@ actions:
   - text: Start the Advanced Security Automation Developer Class!
     link: /courses/advanced/
     type: primary
-  - text: COMING SOON! Security Guidance Developer Class
+  - text: Security Guidance Developer Class
     type: primary
     link: /courses/guidance/
   - text: Go To the Development Lab

courses/guidance/02.md

@@ -1,8 +1,36 @@
 ---
 index: 2
-title: 2. Get Started - Soon!
+title: 2. What is security guidance?
 author: Emily Rodriguez
 headerDepth: 3
 ---
 
-## Start Developing Guidance - Coming Soon!
+## Security Guidance
+
+Before we go further, let's discuss what we mean by "security guidance" and some of its characteristics that matter to us as security (and automation!) practitioners.
+
+**Security guidance** is human-readable content which defines what constitutes a secure configuration for a software component or category of components. It answers the important question that all developers and engineers ask when they want to secure their software -- "What counts as 'secure' for my system in the first place?"
+
+Most software projects will (or at least *should*) align themselves to a particular source for security guidance and follow it as a baseline that answers this question. For example, many commercial companies (and even some civilian government agencies) use the Center for Internet Security Benchmarks (CIS Benchmarks) as their baseline, while software deployed by the US Department of Defense is required to comply with the Defense Information Systems Agency's Security Technical Implementation Guides (STIGs), broadly speaking. 
+
+### Tailoring Guidance
+
+Of course, if you have ever had to implement a security baseline for a software component before, you probably noticed that the baselines don't always line up exactly with the realities of your software's requirements. Securely configuring a software component often also means *decreasing its functionality* to the bare minimum in order to decrease the attack surface as much as possible.
+
+It is also the case that many organizations that use popular secrity guidance documents as their baselines have their own organizational security policies that conflict with the baseline. For example, let's say that the STIG for the Red Hat operating system specifies that users should have, at minimum, 15 characters in their passwords, but your company's security policy requires a minimum of 20. 
+
+### Finding Security Guidance Documentation Baselines
+
+You are likely already familiar with some common sources of security guidance, such as the Center for Internet Security (which publishes CIS Benchmarks) and, on the government side, the Defense Information Systems Agency (which publishes Secure Technical Implementation Guides, or STIGs). 
+
+
+
+
+
+
+### What Makes for Good Security Guidance?
+
+This class intends to teach you how to create security guidance documentation for use as a blueprint for building secure software. We want to write **clear** and **easy-to-implement** guidance. We want to write guidance that considers **all common deployment strategies** for the software component we are deploying -- does my piece of software meaningfully change if it is deployed in the cloud as opposed to on-prem? What happens if I deploy it as a container?
+
+
+

courses/guidance/03.md

@@ -0,0 +1,22 @@
+---
+index: 3
+title: 3. Security Technical Implementation Guides
+author: Sumaa Sayed
+headerDepth: 3
+---
+
+## 3. Security Resource Guidelines
+
+Now we have some idea of what a STIG is. But where do they come from?
+
+STIGs are created based off of high-level, general guidance documents called Security Requirements Guides (SRGs), also published by DISA. SRGs describe security requirements for entire categories of software components, and all STIG requirements are essentially sets of instructions for how to get a particular component to comply with a general SRG.
+
+For example, there is an SRG that covers operating systems in general ("	General Purpose Operating System Security Requirements Guide"). That piece of guidance is full of requirements for an operating system -- *any* operating system -- to be considered reasonably secure. There is a requirement in that SRG (SRG ID: SRG-OS-000021-GPOS-00005) which states that "The operating system must enforce the limit of three consecutive invalid logon attempts by a user during a 15-minute time period."
+
+This requirement is saying that an attacker shouldn't be able to brute force a user's password by throwing a high number of guesses at the system. Simple enough, right?
+
+However, this guidance isn't particularly useful unless we know how to **implement it** on a particular operating system. That's where the STIG comes in. The STIG for, say, Red Hat 8 ("Red Hat Enterprise Linux 8 STIG") has its own requirement for limiting consecutive logon attempts (Rule ID: SV-230334r627750_rule) that cites the relevant SRG IDs that it satisfies. That STIG rule tells us exactly how to configure Red Hat to satisfy this requirement, down to which configuration files we need to edit.
+
+### Challenges with the Traditional Process for STIG Authorship
+
+TODO: describe non-Vulcan process for STIG-writing and why it was inefficient

courses/guidance/04.md

@@ -0,0 +1,46 @@
+---
+index: 4
+title: 4. Starting Your First Vulcan Project
+author: Sumaa Sayed
+headerDepth: 3
+---
+
+## 4. Starting The Project
+
+### 4.1 Consider Your Application's Requirements
+- What is the **goal** of the application?
+- What type of security guidelines does it need?
+
+### 4.2 Choosing an SRG
+- At the top of the page, click the "SRGs" button.
+
+![Alt text](../../assets/img/Vulcan_Menu.png)
+
+- You'll need to decide which high level guidance you want to base your STIG off of. Or you can upload your own, as long as it's in XCCDF format or an XML document.
+
+*Note: For this course, the "Application_Security_Development_STIG" is going to be chosen.
+
+### 4.3 
+- Now you can start your project, after outlining the needs of your application and choosing an SRG.
+
+- At the top of the page, click the "Start New Project" button. 
+
+![Alt text](../../assets/img/Vulcan_Main_Page.png)
+
+- Name your project, give it a description, and choose its visibility.
+
+TODO: flesh out visibility concept
+
+### 4.4 Optional: Adding Members to Your Project
+* Optional: Once your project has been created, there's a tab titled "Members" where you can add users to your project and assign them a role.
+- The types of roles include:
+
+*Viewer: Read only access to the Project or Component
+
+*Author: Edit, comment, and mark Controls as requiring review. Cannot sign-off or approve changes to a Control. Great for individual contributors.
+
+*Reviewer: Author and approve changes to a Control.
+
+*Admin: Full control of a Project or Component. Lock Controls, revert controls, and manage members.
+
+TODO: briefly describe why we want a Reviewer role -- best practice to get peer review, etc.

courses/guidance/05.md

@@ -0,0 +1,35 @@
+---
+index: 5
+title: 5. Components Of a Vulcan Project
+author: Sumaa Sayed
+headerDepth: 3
+---
+
+## 5. Components
+
+### 5.1 What is a Component?
+[add text here]
+
+### 5.2 Creating a Component for Your Project
+- Go to the "Components" tab on the page, and click "Create a New Component"
+Here, you'll select the SRG of your choice, name the component, enter the version and release, a STIG ID prefix, and a title. 
+
+- Optional: You can also enter a description, a point of contact, and a Slack Channel ID if you want.
+
+- Once you're done, click "Create Component"
+
+![Alt text](../../assets/img/Create_Vulcan_Component.png)
+
+### 5.3 Opening Components
+- After the component has been created, click the "Open Component" button
+
+![Alt text](../../assets/img/Open_Vulcan_Component.png)
+
+- The page should look something like this: 
+
+![Alt text](../../assets/img/Open_Component_Page.png)
+
+
+- Note: On the left side of the page, scroll down a little, and there is a section titled "All Controls". These are all of the controls in the SRG chosen, and you can tailor them for your application. 
+
+![Alt text](../../assets/img/All_Controls_Vulcan_View.png)

courses/guidance/06.md

@@ -0,0 +1,29 @@
+---
+index: 6
+title: 6. Editing Componenets
+author: Sumaa Sayed
+headerDepth: 3
+---
+
+## 6. Tailoring Your Components
+
+### 6.1
+- For your application, you'll need to decide what controls will be appliable to your application, which ones need some tailoring, and which ones will not be applicable to your application.
+
+### 6.2 Editing Components
+- If you want to make any changes/edits to the controls, click the "Edit Component Controls" button at the top.
+
+![Alt text](../../assets/img/Open_Component_Page.png)
+
+- For each control, its status can be updated to the following:
+
+*Applicable – Configurable: The product requires configuration or the application of policy settings to achieve compliance.
+
+*Applicable – Inherently Meets: The product is compliant in its initial state and cannot be subsequently reconfigured to a noncompliant state.
+
+*Applicable – Does Not Meet: There are no technical means to achieve compliance.
+
+*Not Applicable: The requirement addresses a capability or use case that the product does not support
+
+### STIG Format
+TODO: describe how to write a professional STIG, ergo being extremely clear about what counts as a finding, caveats for different deployment strategies, applicabilities, etc.

courses/guidance/07.md

@@ -0,0 +1,22 @@
+---
+index: 7
+title: 7. Automated InSpec Testing
+author: Sumaa Sayed
+headerDepth: 3
+---
+
+## 7. Automated Validation Tests
+
+### 7.1 Writing Tests for Controls
+- For the controls that are applicable, you can click the tab that says "InSpec Control Body" and write an automated validation test for the control.
+
+![Alt text](../../assets/img/Vulcan_InSpec_Page.png)
+
+- As an example, control MYCO-00-00001 requires that the application must limit the number of logon sessions per user. The test written in the example will parse through a file called "session.conf" and make sure that the max_logon_sessions variable/input is set to a value. In this example, it is set to 5.
+
+### 7.2 Saving Controls & Revision History
+- Once you are done with writing a test, be sure to click the "Save Control" button at the top.
+- You can also see that the control changes were saved by looking on the right side of the page, under "Revision History". 
+- To see the entire control, with the documentation and InSpec test, click the tab that says "InSpec Control (Read Only)"
+
+![Alt text](../../assets/img/Vulcan_InSpec_Full.png)

courses/guidance/08.md

@@ -0,0 +1,16 @@
+---
+index: 8
+title: 8. Exporting Your Content
+author: Will Dower
+headerDepth: 3
+---
+
+## Exporting Your Content
+
+### Exporting
+
+### Exporting the InSpec Profile
+
+### Creating a New Release 
+
+#### Diff Viewer

courses/guidance/README.md

@@ -1,8 +1,27 @@
 ---
 next: 02.md
-title: Coming Soon!
+title: 1. Class Overview
 author: Emily Rodriguez
 headerDepth: 3
 ---
 
-## Security Guidance Course Coming Soon!
+## 1.1 Class Overview
+The purpose of this class is to outline how security guidance fits in the security validation lifecycle and equip participants with the tools and knowledge to create and use security guidance. There is a survey at the end to give feedback on the class.
+
+### 1.1.1 Class Objectives:
+By the end, you should be able to achieve all of the following objectives. 
+-	Identify and locate security guidance for a software component.
+-	Differentiate between different types of security guidance, such as SRGs and STIGs.
+-	Create tailored security guidance using Vulcan.
+-	Classify security controls as Applicable - Configurable, Applicable - Inherently Meets, Applicable - Does Not Meet, Not Applicable, or Not Yet Determined for a given software component.
+-   Export security guidance as InSpec stubs to assist in automated security validation.
+
+## 1.2 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).
+
+This challenge is what the [MITRE Security Automation Framework](https://saf.mitre.org) or MITRE SAF was developed to simplify -- to make the journey from a Requirement Document to an automated test profile and back again a little easier to navigate.
+
+
+
+![Alt text](../../assets/img/saf-lifecycle.png)

courses/guidance/notes.md

@@ -0,0 +1,25 @@
+---
+#index: 1
+title: User Manual for Vulcan -- notes
+author: Sumaa Sayed
+headerDepth: 3
+---
+User Manual for Vulcan -- notes 
+
+This guide assumes that the user is logged into the website: https://mitre-vulcan-prod.herokuapp.com/ -- use the vulcan.mitre.org to write this out
+
+-use the readme: https://github.com/mitre/saf-training-lab-environment#readme
+-launch it locally (codespace training)
+- for any ss, ![Alt text](../../assets/img/SAF_Capabilities_Validate.png) -- add them to the assets folder, rename them so you know what the ss is
+- each step should be a separate page (for now)
+
+
+Other important things to note:
+*mention that you can revert changes in vulcan
+*review process should be discussed (marked as 'for review', another user needs to peer-review)
+*option to export content (formats are: disa specific, stubbed inspec profile (inspec tab))
+*diff viewer to compare (duplicate component for ss) -- can work on next version w/o ruining the first one
+*look into the revision history tab, if fail then blank page 
+
+to-do:
+*need a section for overlay components -- just make a blank page for it

courses/user/04.md

@@ -41,4 +41,4 @@ Navigate to the [Validate page](https://saf.mitre.org/#/validate) to find librar
 ### 4.4. What if there is no content for a software component?
 - First, reach out to the SAF team at [[email protected]](mailto:[email protected]) to find out if there is a profile in development or otherwise available but not listed that could meet your needs.
 - Second, if there is still no profile available, identify the security guidance to which the profile should comply and reach out to find out how to best create that profile. We help teams do this and provide training courses on that as well!
-- Third, if there is no guidance available for your particular component, talk with us about developing the guidance using [MITRE's Vulcan application](https://vulcan.mitre.org/). A training course on security guidance development will be coming soon.
+- Third, if there is no guidance available for your particular component, talk with us about developing the guidance using [MITRE's Vulcan application](https://vulcan.mitre.org/). Reference the [training class](../guidance) on security guidance development.