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,91 @@
+---
+order: 2
+next: 03.md
+title: OHDF Background
+author: Charles Hu
+---
+
+## What is OHDF?
+
+OASIS Heimdall Data Format (OHDF) is a security data format used to normalize generated security 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.
+
+You can read more about OHDF [here](https://saf.mitre.org/framework/normalize).
+
+### 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.​
+
+- OHDF enables:
+
+    - Consistent integration, aggregation, and analysis of security data from all available sources.​
+    - Preserving data integrity with original source data.
+    - Maximizing interoperability and data sharing.​
+    - Facilitating the transformation and transport of data between security/management processes or technologies.​
+    - Allowing for the mapping and enrichment of security data to relevant compliance standards (GDPR, NIST SP 800-53, PCI-DSS, etc.).
+
+## What Is a Mapper?
+
+A mapper is a design pattern used to correlate (or map) items in two different objects with one another. Mappers are useful in that they allow us to connect items 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 items in each object type.
+
+Here are some scenarios which demonstrate some key aspects of mappers:
+
+::: details Transferring IDs
+Say we have to transfer the credentials of an employee who is moving from Business A to Business B. The data formats the businesses use for IDs are as follows:
+```
+// Business A
+{Name, DoB, Age, Title}
+
+// Business B
+{employee, employeeBirthday, employeeAge, jobTitle}
+```
+How do we transfer John's credentials from Business A to Business B?
+```
+{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 Business A's ID scheme to Business B's:
+```
+{employee: Name, employeeBirthday: DoB, employeeAge: Age, jobTitle: Title}
+```
+
+With this, we can then develop a mapper which takes John's credentials from Business A and transforms it to Business B's format as so:
+```
+{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.
+:::
+
+::: details Translating a foreign language
+Say we are given the job to translate the traditional Chinese sentence '我愛貓' into English.
+
+Without knowledge of the language, this is an impossible task.
+
+However, say we now also had a mapper which utilized the following mapping:
+```
+{'愛': 'love', '我': 'I', '貓': 'cats'}
+```
+
+Now this task becomes much more easier. We can apply this mapper which will translate the sentence from '我愛貓' to 'I love cats' and vice versa.
+
+The important thing to note here is that mappers make translating between two objects trivial, which means that anyone can do it and we can automate mappers to perform object conversions for us.
+:::
+
+
+## What Is an OHDF Mapper?
+
+An OHDF mapper is a mapper that allows the underlying conversion infrastructure found in OHDF Converters to correlate certain objects or values from one overarching security data format to another overarching security data format. In the case of the SAF tool suite, these mappers allow for the conversion of some given security service format to HDF (\*-to-HDF) and vice versa (HDF-to-\*) using the tools provided by the existing conversion infrastructure.

src/courses/mappers/03.md

@@ -0,0 +1,195 @@
+---
+order: 3
+next: 04.md
+title: Understanding the OHDF Schema
+author: Charles Hu
+---
+
+## An Overview of the OHDF Schema
+
+The OHDF schema is designed to provide a simple, structured, and hierarchal view of security validation results. Any file or object that implements the schema can be broken down into a hierarchy of three structures. These structures are:
+
+1) <i>**Profiles**</i>: This structure contains metadata on the scan target of the original security service export and on the run performed by the security tool. <i>Profiles</i> provide a high-level overview of the security service scan and the targeted system, which are formated in a manner which is digestible and immediately accessible to the assessor.
+
+2) <i>**Controls**</i>: Controls are security standards 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 controls tested for by an external security service to ensure that the target complies with vulnerability and weakness prevention standards. Any given <i>profile</i> contains any number of <i>controls</i> which were tested against the target system during the original security service analysis.
+
+3) <i>**Results**</i>: The <i>results</i> structure contains information on the results of specific tests ran by the security service on the scan target against a security control. These results will always correlate to a certain control and will either report `passed` or `failed` to indicate the test status (other statuses exist but are rare) which cumulatively influence the determined compliance level of the scan target for some set of controls. Any given <i>control</i> contains any number of <i>results</i> which reflect the implemented tests to check if the target system is actually compliant with the control.
+
+## Breaking Down the Formal OHDF Schema
+
+::: note Full OHDF Schema
+The following section contains a breakdown of a streamlined version of the OHDF schema. For the full and up-to-date version, see [here](https://saf.mitre.org/framework/normalize/ohdf-schema).
+:::
+
+We can break down the formal OHDF schema in the same manner as before by observing each structure in the hierarchy from a top-down view.
+
+1) <i>**Profiles**</i>:
+```
+profiles: [
+  0: {
+    name             // Name of profile, usually the original security service tool; should be unique
+    version          // Version of security service tool
+    sha256           // Checksum of the profile; NOTE: AUTOMATICALLY GENERATED BY HDF CONVERTERS, DO NOT POPULATE
+    title            // Title of security service scan; should be human readable
+    maintainer       // Maintainer
+    summary          // Summary of security service export (e.g., the STIG header)
+    license          // Copyright license
+    copyright        // Copyright holder
+    copyright_email  // Copyright holder's email
+    supports         // Supported platform targets
+    attributes       // Inputs/attributes used in scan
+    groups           // Set of descriptions for the control groups (e.g., control IDs)
+    controls         // Controls substructure (see below)
+    status           // Status of profile (typically 'loaded')
+  }
+  ... // More items may exist if the security service produces multiple profiles per export
+]
+```
+
+2) <i>**Controls**</i>:
+
+```
+controls: [
+  0: {
+    id               // ID of control; used for sorting, should be unique for each unique control
+    title            // Title of control
+    desc             // Description of the control
+    descriptions     // Additional descriptions; usually 'check' and 'fix' text for control
+    impact           // Security severity of control
+    refs             // References to external control documentation
+    tags             // Control tags; typically correlate to existing vulnerability/weakness database (e.g., NIST, CVE, CWE)
+    code             // Control source code for code preservation
+    source_location  // Location of control within source code
+    results          // Results substructure (see below)
+  }
+  ... // More items may exist if there are multiple controls reported per profile
+]
+```
+
+3) <i>**Results**</i>:
+
+```
+results: [
+  0: {
+    status         // Pass/fail status of test (other statuses exist but are rare)
+    code_desc      // Test expectations as defined by control
+    message        // Demonstration of expected and actual result of test to justify test status
+    run_time       // Overall runtime of test
+    start_time     // Starting time of test
+  }
+  ... // More items may exist if there are multiple results tested per control
+]
+```
+
+These aforementioned structures cumulatively result in the following generalized structure which primarily defines OHDF:
+
+```
+// Data fields have been removed for the sake of demonstration
+profiles: [
+  0: {
+    controls: [
+      0: {
+        results: [
+          0: {
+          },
+          ...
+        ]
+      },
+      ...
+    ]
+  },
+  ...
+]
+```
+
+There are additional structures in the OHDF schema which are used for metadata/extraneous information storage. These exist alongside the <i>profiles</i> structure on the top level of the HDF schema. The general structure for the top level of the HDF schema is as follows:
+
+```
+{
+  platform: {               // Information on the platform producing the export
+    name                    // Name of platform export was run on
+    release                 // Platform version
+    target_id               // Platform target ID (i.e., further identifying information on platform)
+  }
+  version                   // Platform version
+  statistics: {             // Statistics relating to target scan run
+    duration                // Duration of run
+  }
+  profiles                  // Profiles structure
+  passthrough: {            // Extraneous information storage
+    auxiliary_data: [       // Storage for unused data from the sample file
+      0: {
+        name                // Name of auxiliary data source
+        data                // Auxiliary data
+      }
+      ... // More items may exist if there are multiple auxiliary data sources available
+    ]
+    raw                     // Raw data dump of input security service export
+  }
+}
+```
+
+## The OHDF Schema
+
+The final OHDF schema is as follows:
+```
+{
+  platform: {                // required field
+    name                     // required field
+    release                  // required field
+    target_id
+   }
+  version                    // required field
+  statistics: {              // required field
+    duration
+   }
+  profiles: [                // required field
+    0: {
+      name                   // required field
+      version
+      sha256                 // required field
+      title
+      maintainer
+      summary
+      license
+      copyright
+      copyright_email
+      supports               // required field
+      attributes             // required field
+      groups                 // required field
+      controls: [            // required field
+        0: {
+          id                 // required field
+          title
+          desc
+          descriptions
+          impact             // required field
+          refs               // required field
+          tags               // required field
+          code
+          source_location    // required field
+          results: [         // required field
+            0: {
+              status
+              code_desc      // required field
+              message
+              run_time
+              start_time     // required field
+            }
+          ]
+        }
+      ]
+      status
+    }
+  ]
+  passthrough: {
+    auxiliary_data: [
+      0: {
+        name
+        data
+      }
+    ]
+    raw
+  }
+}
+```