Mapper Creation Course

src/.vuepress/navbar.ts

@@ -10,7 +10,8 @@ export default navbar([
       { text: "Beginner Security Automation Developer Class", link: "/courses/beginner/", icon: "creative" },
       { text: "Advanced Security Automation Developer Class", link: "/courses/advanced/", icon: "creative" },
       { text: "Security Guidance Developer Class", link: "/courses/guidance/", icon: "creative" },
-      { text: "InSpec Profile Development & Testing", link: "/courses/profile-dev-test/", icon: "creative"}
+      { text: "InSpec Profile Development & Testing", link: "/courses/profile-dev-test/", icon: "creative"},
+      { text: "OHDF Mapper Development Class", link: "/courses/mappers/", icon: "creative"}
     ]},
   { text: "Resources",
     icon: "book",

src/.vuepress/sidebar.ts

@@ -32,12 +32,19 @@ export default sidebar({
       children: "structure",
       collapsible: true
     },
-        {
+    {
       icon: "creative",
       text: "InSpec Profile Development & Testing",
       prefix: "courses/profile-dev-test/",
       children: "structure",
       collapsible: true
     },
+    {
+      icon: "creative",
+      text: "OHDF Mapper Development Class",
+      prefix: "courses/mappers/",
+      children: "structure",
+      collapsible: true
+    },
   ],
 });

src/README.md

@@ -21,6 +21,9 @@ actions:
   - text: InSpec Profile Updating & Development
     link: /courses/profile-dev-test/
     type: primary
+  - text: OHDF Mapper Development Class
+    link: /courses/mappers/
+    type: primary
 
 highlights:
   - header: What You Will Learn

src/courses/mappers/02.md

@@ -0,0 +1,128 @@
+---
+order: 2
+next: 03.md
+title: What Is OHDF?
+author: Charles Hu
+---
+
+## What is OHDF?
+
+OASIS Heimdall Data Format (OHDF) is a security data format used to normalize generated data exports from various security tools into a single common data format usable by the Security Automation Framework (SAF) tool suite. The format is defined by the [OHDF schema](https://saf.mitre.org/framework/normalize/ohdf-schema) and its goal is to provide a simple and intuitive means for representing security validation profiles, controls, and results.
+
+[OASIS Open](https://www.oasis-open.org/) is an international standards body that works on the development and advancement of open source technological standards. OHDF is currently in the process of becoming an OASIS Open standard. For more information on the OHDF charter for OASIS Open, [refer here](https://groups.oasis-open.org/communities/tc-community-home2?CommunityKey=f8888caa-8401-46f8-bf10-018dc7d3f577).
+
+## Why OHDF?
+
+- Many security tools do not provide context to relevant compliance standards for comparison across security tools.​
+- Security tools typically generate data in unique formats that require multiple dashboards and utilities to process.​
+- OHDF reduces the time it takes to process security assessments, data in disparate locations, and inconsistent semantics of a data element between formats.​
+
+## Features
+
+### 1. Consistent integration, aggregation, and analysis of security data from all available sources.​
+
+- Enforces consistent schema fields through consciously designed data format mappings.
+- Supports data format conversion from numerous established security tools such as AWS Security Hub's AWS Security Finding Format (ASFF) and Tenable Nessus' Nessus file format.
+- Allows the integration of currently unsupported security tool data formats through the development of OHDF mappers for the OHDF Converters tool.
+
+![](../../assets/img/OHDF_Inputs.png)
+
+### 2. Preserving data integrity with original source data.
+
+- Uses mappings which maximize meaningful schema field conversions.
+- Leverages schema fields `passthrough` and `raw` to preserve the original data in its entirety.
+- Allows for bidirectional format conversions to and from OHDF.
+
+See below for an example of how *some* fields in a source file are mapped to OHDF (not all the mappings are pictured, for the sake of not cluttering the figure).
+
+![Example of some mappings between a source file and OHDF](../../assets/img/ExampleSchemaMappings.png)
+
+### 3. Maximizing interoperability and data sharing.​
+
+- Provides a consistent and standardized format for communication.
+- Provides an easily ingestible data format and tools to improve user readability.
+
+### 4. Facilitating the transformation and transport of data between security/management processes or technologies.​
+
+- Provides a clear schema for technologies/processes to support.
+- Includes a simple file format that technologies/processes can accept.
+- Compatible with [Heimdall](./03.md#what-is-heimdall) to provide data visualization.
+
+### 5. Allowing for the mapping and enrichment of security data to relevant compliance standards (GDPR, NIST SP 800-53, CCIs, PCI-DSS, etc.).
+
+- Uses mappers which provide and append relevant compliance standards to converted security tool data.
+
+:::::::note What Are All These Abbreviations?
+
+The aforementioned terms are all security compliance related guidelines, frameworks, or implementations. The following are explanations on terms that are commonly used in this course:
+
+:::details NIST
+The National Institute of Standards and Technology (NIST) is a U.S. agency that "promotes U.S. innovation and industrial competitiveness by advancing measurement science, standards, and technology in ways that enhance economic security and improve quality of life."
+
+More information can be found [here](https://www.nist.gov/).
+:::
+
+:::details NIST RMF
+The NIST Risk Management Framework (NIST RMF) provides "a process that integrates security, privacy, and cyber supply chain risk management activities into the system development life cycle."
+
+More information can be found [here](https://csrc.nist.gov/projects/risk-management/about-rmf).
+:::
+
+:::::details NIST SP 800-53
+- The NIST Special Publication 800-53 (**NIST SP 800-53**) "provides a catalog of security and privacy controls for information systems and organizations to protect organizational operations and assets, individuals, other organizations, and the Nation from a diverse set of threats and risks."
+
+More information can be found [here](https://csrc.nist.gov/pubs/sp/800/53/r5/upd1/final).
+
+:::details NIST SP 800-53 Excerpt
+AC-17 REMOTE ACCESS
+Control:
+a. Establish and document usage restrictions, configuration/connection requirements, and
+implementation guidance for each type of remote access allowed; and
+b. Authorize each type of remote access to the system prior to allowing such connections.
+:::
+:::::
+
+:::details DISA
+The Defense Information Systems Agency (DISA) is a U.S. agency conducting "DODIN (Department of Defense information networks) operations to enable lethality across all warfighting domains in defense of our nation."
+
+More information can be found [here](https://www.disa.mil/).
+:::
+
+:::::details CCIs
+Control Correlation Identifiers (**CCIs**) are "standard identifiers and descriptions by DISA that aim to correlate high-level policy expressions and low-level technical implementations of security requirements." They are analogous to NIST SP 800-53s in that they both provide security and privacy controls.
+
+More information can be found [here](https://public.cyber.mil/stigs/cci/).
+
+:::details CCI Excerpt
+CCI-000002: Disseminate the organization-level; mission/business process-level; and/or system-level access control policy that addresses purpose, scope, roles, responsibilities, management commitment, coordination among organizational entities, and compliance to organization-defined personnel or roles.
+
+References:
+- NIST: NIST SP 800-53 (v3): AC-1 a
+- NIST: NIST SP 800-53 Revision 4 (v4): AC-1 a 1
+- NIST: NIST SP 800-53 Revision 5 (v5): AC-1 a 1 (a)
+- NIST: NIST SP 800-53A (v1): AC-1.1 (iii)
+:::
+:::::
+:::::::
+
+## What Else?
+
+You can read more about OHDF [here](https://saf.mitre.org/framework/normalize).
+
+## Knowledge Check
+
+:::details What is OHDF?
+OHDF is a security data format used to normalize generated data exports from various security tools into a single common data format usable by the SAF tool suite.
+:::
+
+:::details What are some uses of OHDF?
+Some uses include:
+
+- Aggregating security data formats into a single standard format.
+
+- Facilitating the transformation/transport of data across different processes and technologies.
+
+- Enhancing security data with relevant compliance standards.
+
+- And more.
+:::

src/courses/mappers/03.md

@@ -0,0 +1,60 @@
+---
+order: 3
+next: 04.md
+title: Where Is OHDF Used?
+author: Charles Hu
+---
+
+## Where Is OHDF Used?
+
+OHDF is a cornerstone of the Security Automation Framework and is officially implemented and used in a plethora of tools and libraries including InspecJS, OHDF Converters, the SAF CLI, and Heimdall.
+
+## What Is the Security Automation Framework?
+
+The Security Automation Framework (SAF) is a suite of open-source security automation tools that facilitate the development, collection, and standardization of content for use by government and industry organizations to​:
+
+- Accelerate ATO.
+
+- Establish security requirements.
+
+- Build security in.
+
+- Assess/monitor vulnerabilities.
+
+SAF has five core capabilities, of which OHDF is involved in varying degrees:
+
+- **Plan**: OHDF is defined such that it includes all information described in the guidance, as well as relevant metadata. Thus, the information provided by the guidance is incorporated with the security tool results.
+
+- **Harden**: OHDF is not typically used in this capability.
+
+- **Validate**: InSpec's results format is a subset of the OHDF, meaning that InSpec is natively supported. Moreover, it's easy to write InSpec such that all the guidance information is passed through into both the OHDF profile and OHDF results formats.
+
+- **Normalize**: With the use of OHDF Converters, we are able to map many different security results formats to our standard format, OHDF. These converters can either be accessed directly or via the SAF CLI.
+
+- **Visualize**: OHDF is ingested by a variety of tools and transformed in many different ways. For example, a results file can be turned into a threshold file for pipeline use, turned into a POAM for ingestion by eMASS, or ingested by Heimdall directly for display purposes.
+
+![SAF has five core capabilities, which we have developed/identified tooling and scripts to address.](./img/saf_security_validation_lifecycle.png)
+
+You can read more about SAF [here](../user/03.md).
+
+## What Is InspecJS?
+
+[InspecJS](https://github.com/mitre/heimdall2/tree/master/libs/inspecjs) is a library that provides schema definitions, classes, and utilities for OHDF file handling. InspecJS plays a pivotal role in the contextualization process where it performs tasks such as converting the individual statuses for each finding into an overall status for the control.
+
+## What Is OHDF Converters?
+
+[OHDF Converters](https://github.com/mitre/heimdall2/tree/master/libs/hdf-converters) is a custom data normalization library which hosts and leverages OHDF mappers for transforming various security data formats to and from OHDF. It is currently integrated in tools such as [Heimdall](https://github.com/mitre/heimdall2) and the [SAF CLI](https://github.com/mitre/saf), which collectively are part of the [Security Automation Framework (SAF)](https://saf.mitre.org/#/), a set of tools and processes which aim to standardize and ease security compliance testing and verification for systems such as automated build pipelines.
+
+## What Is the SAF CLI?
+
+The Security Automation Framework Command Line Interface (SAF CLI) brings together applications, techniques, libraries, and tools developed by MITRE and the security community to streamline security automation for systems and DevOps pipelines.
+
+An example use case of the SAF CLI is for automating certain security processes in a CI/CD pipeline. One process would be normalizing security data into OHDF using the `saf convert` command.  One can set up the SAF CLI to automatically ingest security reports generated from the build pipeline, and then forward the newly generated OHDF files to a visualization tool such as Heimdall that allows a security assessor to review the state of the current software build.
+
+![SAF CLI utility overview: Attest, Convert, View, Validate, and Generate](./img/saf_cli_features.png)
+
+## What Is Heimdall?
+
+[Heimdall](https://github.com/mitre/heimdall2) is a visualization tool that provides a GUI-based means for managing and analyzing security data. Data that is imported into Heimdall is automatically converted to OHDF through OHDF Converters, which serves as the underlying library that services data format conversion requests in Heimdall.
+
+![An instance of Heimdall visualizing a security result set. Results are displayed with figures, charts, and compliance level percentages to quickly convey important takeaways at a glance.](./img/heimdall_view.png)

src/courses/mappers/04.md

@@ -0,0 +1,70 @@
+---
+order: 4
+next: 05.md
+title: What Is an OHDF Mapper?
+author: Charles Hu
+---
+
+## What Is a Mapper?
+
+A mapper is an example of the Adapter Design Pattern which is used to correlate (or map) items in two different objects with one another. Mappers are useful in that they allow us to correlate values in objects that are nominally different but semantically the same. A result of this is that we can easily transform one object type into another through the use of mappings which define the direct relationship of values in each object type. An important aspect of the transformation process is that while the objects containing the values are transformed, the values themselves typically remain the same.
+
+Mappings are the actual correlation of values between two different objects. They are the basis for mappers and are responsible for defining which values between two objects are semantically the same. Mappers are the implementation of mappings which perform the necessary processing to transform the objects according to relationships found in the mappings. In order to have a mapper that is as accurate as possible in its transformations, the mappings should ideally include correlations for all values in the objects.
+
+Here is a scenario which demonstrates some key aspects of mappers:
+
+::: details Transferring IDs
+Say we have a business that is changing its employee identification software and needs to transfer the current credentials of its employees from Software A to Software B. The data formats the softwares use for IDs are as follows:
+```json
+// Software A
+{Name, DoB, Age, Title}
+
+// Software B
+{employee, employeeBirthday, employeeAge, jobTitle}
+```
+
+How do we transfer John's credentials from Software A to Software B?
+```json
+{Name: 'John Doe', DoB: 10-6-1992, Age: 32, Title: 'Security Technician'}
+```
+
+What we can do is create a mapping which correlates the items from Software A's ID scheme to Software B's:
+```json
+{employee: Name, employeeBirthday: DoB, employeeAge: Age, jobTitle: Title}
+```
+
+With this, we can then develop a mapper which takes John's credentials from Software A and transforms it to Software B's format as so:
+```json
+{Name: 'John Doe', DoB: 10-6-1992, Age: 32, Title: 'Security Technician'}
+
+                                 ||
+                                \  /
+                                 \/
+
+                               MAPPER
+
+                                 ||
+                                \  /
+                                 \/
+
+{employee: 'John Doe', employeeBirthday: 10-6-1992, employeeAge: 32, jobTitle: 'Security Technician'}
+``` 
+
+The important thing to note here is that mappers rely on underlying mappings which match semantically similar fields between two objects. These matches allow us to correctly convert each item in one object to the other.
+:::
+
+## What Is an OHDF Mapper?
+
+An OHDF mapper is a mapper specifically focused on transforming security data to and from OHDF. It consists of a mapping and a number of helper functions which facilitate the actual application of the mapping. In the case of the SAF tool suite, these mappers allow for the conversion of any given data format to OHDF (\*-to-OHDF) and vice versa (OHDF-to-\*) using helper functions and utilities provided by the existing conversion infrastructure in OHDF Converters.
+
+OHDF mappers are built upon an understanding of the security data format (whether through formal schemas or on-hand export examples) and the OHDF schema, and the mechanics of the mappers revolve around correlating the fields in each as accurately as possible.
+
+## Knowledge Check
+
+:::details Where are OHDF mappers located?
+OHDF mappers are located in OHDF Converters, which hosts and leverages the mappers to provide mapping services to and from OHDF.
+:::
+
+::: details What is the difference between a mapping and a mapper?
+A mapping shows the correlation between fields, while a mapper actually implements the transformation of correlated fields.
+:::

src/courses/mappers/05.md

@@ -0,0 +1,53 @@
+---
+order: 5
+next: 06.md
+title: OHDF Schema Basics
+author: Charles Hu
+---
+
+## An Overview of the OHDF Schema
+
+In order to make an OHDF mapper, it is important to understand the specifics of how OHDF is actually structured through the OHDF schema.
+
+The OHDF schema is designed to provide a simple, structured, and hierarchal view of security tool results. OHDF actually consists of several related schema formats; however, the <i>Exec JSON</i> format is the most common and is typically the one being referred to when speaking of the OHDF schema. Any file or object that implements the schema can be broken down into a hierarchy of four main structures. These structures are:
+
+### 1. <i>**Exec JSON**</i>
+
+This is the top level structure that contains both the security data (which is stored in the <i>Profiles</i> structure) and relevant metadata on the tool used to generate the OHDF file (stored in structures such as <i>Platform</i>, <i>Statistics</i>, and <i>Version</i>). 
+
+### 2. <i>**Profiles**</i>
+
+This structure contains metadata on the target system of the original security tool export and on the specific run performed by the security tool. <i>Profiles</i> provide a high-level overview of the security tool result and the targeted system, which are formatted in a manner which is digestible and immediately accessible to the assessor. There is typically only one <i>profiles</i> structure. Further instances of <i>profiles</i> are additional overlays.
+
+### 3. <i>**Controls**</i>
+
+Controls are security requirements that are used to prevent, mitigate, and address various security risks to sensitive information and infrastructure. In the case of OHDF, the <i>controls</i> structure is a collection of requirements tested for by an external security tool to ensure that the target complies with vulnerability and weakness prevention standards. Any given <i>profile</i> contains some number of <i>controls</i> which were tested against the target system during the original security tool run.
+
+### 4. <i>**Results**</i>
+
+The <i>results</i> structure contains information on the results of specific tests ran by the security tool on the target system against a security requirement/control. These results will always correlate to a certain <i>control</i> and will either report `passed` or `failed` to indicate the test status (other statuses include `skipped` and `error`) which cumulatively influence the determined compliance level of the target system for some set of requirements/controls. Any given <i>control</i> contains some number of <i>results</i> which reflect the implemented tests to check if the target system is actually compliant.
+
+## Overall Hierarchy
+
+These aforementioned main structures cumulatively result in the following generalized structure:
+
+```json
+// Data fields have been removed for the sake of demonstration
+execjson: {
+  profiles: [
+    0: {
+      controls: [
+        0: {
+          results: [
+            0: {
+            },
+            ...
+          ]
+        },
+        ...
+      ]
+    },
+    ...
+  ]
+}
+```