@mitre/inspec-objects 2.0.0 → 2.0.2

package/.github/workflows/auto-approve-and-merge.yml

@@ -4,17 +4,14 @@ on:
     types: [labeled]
 permissions:
   pull-requests: write
-  contents: write
 
 jobs:
   approve:
     name: Auto-approve dependabot PRs
     if: github.event.pull_request.user.login == 'dependabot[bot]' && contains(github.event.pull_request.labels.*.name, 'dependencies')
-    runs-on: ubuntu-latest
+    runs-on: ubuntu-24.04
     steps:
-    - uses: hmarr/auto-approve-action@v3
-      with:
-        github-token: "${{ secrets.GITHUB_TOKEN }}"
+    - uses: hmarr/auto-approve-action@v4
     - name: Enable auto-merge for Dependabot PRs
       run: gh pr merge --auto --merge "$PR_URL"
       env:

package/.github/workflows/draft-release.yml

@@ -8,9 +8,9 @@ on:
 
 jobs:
   update_draft_release:
-    runs-on: ubuntu-latest
+    runs-on: ubuntu-24.04
     steps:
       # Drafts your next Release notes as Pull Requests are merged into "master"
-      - uses: toolmantim/release-drafter@v5.2.0
+      - uses: release-drafter/release-drafter@v6
         env:
-          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

package/.github/workflows/e2e-test.yml

@@ -7,15 +7,15 @@ on:
 jobs:
   build:
     name: Run TS-InSpec-Objects E2E Tests
-    runs-on: ubuntu-20.04
+    runs-on: ubuntu-24.04
 
     steps:
-     - uses: actions/checkout@v3
+     - uses: actions/checkout@v4
 
      - name: Setup Node.js
-       uses: actions/setup-node@v3
+       uses: actions/setup-node@v4
        with:
-        node-version: 18
+        node-version: 22
         cache: 'npm'
 
      - name: Install dependencies

package/.github/workflows/linter.yml

@@ -7,16 +7,16 @@ on:
 jobs:
   build:
     name: Lint TS-InSpec-Objects
-    runs-on: ubuntu-20.04
+    runs-on: ubuntu-24.04
 
     steps:
      - name: Checkout code
-       uses: actions/checkout@v3
+       uses: actions/checkout@v4
 
      - name: Setup Node.js
-       uses: actions/setup-node@v3
+       uses: actions/setup-node@v4
        with:
-        node-version: 18
+        node-version: 22
         cache: 'npm'
 
      - name: Install project dependencies

package/.github/workflows/push-to-gpr.yml

@@ -6,31 +6,28 @@ on:
 
 jobs:
   build-deploy:
-    runs-on: ubuntu-20.04
+    runs-on: ubuntu-24.04
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
 
       - name: Setup node
-        uses: actions/setup-node@v3
+        uses: actions/setup-node@v4
         with:
-          node-version: 18
-          registry-url: https://npm.pkg.github.com/
+          node-version: 22
+          registry-url: 'https://npm.pkg.github.com'
           scope: '@mitre'
 
       - name: Build the NPM Package
         run: |
           npm install
+          rm -rf test
           npm run build
+
       - name: Pack all items that are published
         run: npm pack
-      # Setup .npmrc file to publish to GitHub Package Registry
-      - uses: actions/setup-node@v1
-        with:
-          registry-url: 'https://npm.pkg.github.com'
-          scope: '@mitre'
 
       # Publish inspec-objects to GitHub Package Registry
       - name: Publish inspec-objects to GPR
         run: npm publish mitre-inspec-objects-*.tgz
         env:
-          NODE_AUTH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          NODE_AUTH_TOKEN: ${{ secrets.GITHUB_TOKEN }}

package/.github/workflows/push-to-npm.yml

@@ -6,14 +6,14 @@ on:
 
 jobs:
   build-deploy:
-    runs-on: ubuntu-20.04
+    runs-on: ubuntu-24.04
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
 
       - name: setup node
-        uses: actions/setup-node@v3
+        uses: actions/setup-node@v4
         with:
-          node-version: 18
+          node-version: 22
           registry-url: 'https://registry.npmjs.org'
 
       - name: Install project dependencies

package/README.md

@@ -1,12 +1,14 @@
 # ts-inspec-objects
-Typescript objects for InSpec profiles
+Typescript objects for InSpec Profiles
 
-This repository contains the source code that facilitates the writing of InSpec profiles (for use in things like stub generation and delta comparisons) more consistent with `Chef Cookstyle` formatting for ease of use when comparing with new changes from delta and when generating InSpec stubs that match a standard format. 
+This repository contains the source code that facilitates the writing of InSpec Profiles (for use in things like stub generation and delta comparisons) more consistent with `Chef Cookstyle` formatting for ease of use when comparing with new changes from delta and when generating InSpec stubs that match a standard format. 
 
 For more information about Chef Cookstyle see: 
  - [chef/cookstyle on GitHub](https://github.com/chef/cookstyle)
  - [Chef Cookstyle on Chef documents page](https://docs.chef.io/workstation/cookstyle/)
 
+The `ts-inspec-objects` provides the capability of updating InSpect Profiles and creating stub Profiles based on XCCDF Benchmarks. This is accomplished by providing `Profile` and `Control` classes and supporting methods (functions).
+
 ## How to Use
 The process code maintained in this repository generates a `npm` executable that is published to the `npm registry` as [mitre-inspec-objects](https://www.npmjs.com/package/@mitre/inspec-objects).
 
@@ -18,7 +20,7 @@ The package is a CommonJS-based npm written in TypeScript
 
 ## Parsing Process
 
-When using this library to parse `InSpec profiles` or `xccdf files` for the purposes of generating InSpec profiles, the general workflow is as follows:
+When using this library to parse `InSpec Profiles` or `xccdf files` for the purposes of generating InSpec profiles, the general workflow is as follows:
 ```
   - The input is processed, read into a typescript object
   - Operated on with any required action / logic
@@ -39,16 +41,46 @@ Here are some formatting choices that are being made.
 2. Tag keywords are not quoted (ex: tag severity: 'medium')
 3. Each control file ends with a newline
 
-### Workflow graphical representation
+---
+### XCCDF Workflow Process
+Processes an XCCDF (Extensible Configuration Checklist Description Format) XML string based on the `Rule Identifier` provided and converts it into a Profile object.
+If and OVAL definition is provided it retrives the oval objects and associated states and the Controls description check text is update with the content.
+<div align="center">
+  <img src="images/ts-inspec-objects-xccdf-workflow-process.png" alt="Typescript Objects XCCDF Conversion Workflow Process" title="Typescript Objects XCCDF Conversion Workflow Process">
+</div>
+
+### OVAL Workflow Process
+Processes an OVAL (Open Vulnerability and Assessment Language) XML string and converts it into a JSON object.
+The process extracts definitions and their associated criteria references and resolved values.
+The process executes the following steps:
+1. Converts the OVAL XML string into a JSON object.
+2. Iterates through the OVAL definitions and extracts each definition.
+3. For each definition, extracts criteria references and resolves the associated objects and states.
+4. Logs warnings if any objects or states cannot be found.
+<div align="center">
+  <img src="images/ts-inspec-objects-oval-workflow-process.png" alt="Typescript Objects Oval Conversion Workflow Process" title="Typescript Objects Oval Conversion Workflow Process">
+</div>
+
+### InSpec Profile Workflow Process
+Process a JSON string representing an InSpec profile, converts it, and processes it to return a `Profile` object.
+It handles different versions of the InSpec JSON format and sorts the controls by their ID.
+<div align="center">
+  <img src="images/ts-inspec-objects-inspec-profile-workflow-process.png" alt="Typescript Objects InSpec Profile Workflow Process" title="Typescript Objects InSpec Profile Workflow Process">
+</div>
+
+### Update Profile Using XCCDF Workflow Process
+Updates a Profile with new metadata from and XCCDF, based on the `Rule Indetefier` and logs the process.
 <div align="center">
-  <img src="images/ts-inspec-objects.jpg" alt="Typescript Objects Generation Process" title="Typescript Objects Generation Process">
+  <img src="images/ts-inspec-objects-updateProfileUsingXccdf-workflow.png" alt="Typescript Objects Update Profile Using XCCDF Workflow Process" title="Typescript Objects Update Profile Using XCCDF Workflow Process">
 </div>
 
-### Delta and Stub Process
+### Update Control Workflow Process
+Updates a given control object with the provided partial control and logs the process.
 <div align="center">
-  <img src="images/Delta_Process.jpg" alt="Delta and Stub Generation Process" title="Delta and Stub Generation Process">
+  <img src="images/ts-inspec-objects-process-updateControl-workflow.png" alt="Typescript Objects Update Control Workflow Process" title="Typescript Objects Update Control Workflow Process">
 </div>
 
+---
 ## Development Environment Configuration
 ### Installation
 To install the project, clone the repository and install the dependencies:

package/lib/parsers/oval.js

@@ -99,7 +99,7 @@ function processOVAL(oval) {
     if (!oval) {
         return undefined;
     }
-    const parsed = (0, xccdf_1.convertEncodedXmlIntoJson)(oval);
+    const parsed = (0, xccdf_1.convertEncodedXmlIntoJson)(oval, 'withArrayNoEntitiesOption');
     const extractedDefinitions = {};
     for (const ovalDefinitions of parsed.oval_definitions) {
         for (const definitionList of ovalDefinitions.definitions) {

package/lib/parsers/xccdf.d.ts

@@ -27,8 +27,13 @@ export type InputTextLang = {
     '@_lang': string;
 };
 /**
- * Processes an XCCDF XML string and converts it into a Profile object.
- * Note: Moved the newline removal to diff library rather than here.
+ * Processes an XCCDF (Extensible Configuration Checklist Description Format) XML
+ * string and converts it into a Profile object.
+ * NOTE: We are using the fast xml parser (FXP) V4 which requires to specify
+ *       which Whether a single tag should be parsed as an array or an object,
+ *       it can't be decided by FXP. We process every tag as an array, this is
+ *       the reason there are numerous tag test, were array index zero [0] is
+ *       tested.
  *
  * @param xml - The XCCDF XML string to process.
  * @param removeNewlines - A flag indicating whether to remove newlines from the processed data.

package/lib/parsers/xccdf.js

@@ -55,21 +55,33 @@ function extractAllComplexChecks(complexCheck) {
     return complexChecks;
 }
 /**
- * Ensures that the input is decoded as an XML string value.
+ * Ensures that the input is decoded to a string value.
  *
- * @param input - The input value which can be either a string or an array of
- *                InputTextLang objects.
- * @param defaultValue - The default string value to return if the input is
- *                       not a string.
- * @returns The decoded XML string value if the input is a string, otherwise the
- *          value from the first element of the input array or the default value.
+ * This function takes an input which can be either a string or an array of `InputTextLang` objects.
+ * If the input is a string, it returns the input as is.
+ * If the input is an array, it attempts to retrieve the `#text` property from the first element of the array.
+ * If the input is neither a string nor an array, it attempts to retrieve the `#text` property from the input.
+ * If the `#text` property is not found, it returns the provided default value.
+ *
+ * @param input - The input value which can be a string or an array of `InputTextLang` objects.
+ * @param defaultValue - The default value to return if the `#text` property is not found.
+ * @returns The decoded string value or the default value.
  */
 function ensureDecodedXMLStringValue(input, defaultValue) {
-    return lodash_1.default.isString(input) ? input : lodash_1.default.get(input, '[0].#text', defaultValue);
+    return lodash_1.default.isString(input)
+        ? input
+        : lodash_1.default.isArray(input)
+            ? lodash_1.default.get(input, '[0].#text', defaultValue)
+            : lodash_1.default.get(input, '#text', defaultValue);
 }
 /**
- * Processes an XCCDF XML string and converts it into a Profile object.
- * Note: Moved the newline removal to diff library rather than here.
+ * Processes an XCCDF (Extensible Configuration Checklist Description Format) XML
+ * string and converts it into a Profile object.
+ * NOTE: We are using the fast xml parser (FXP) V4 which requires to specify
+ *       which Whether a single tag should be parsed as an array or an object,
+ *       it can't be decided by FXP. We process every tag as an array, this is
+ *       the reason there are numerous tag test, were array index zero [0] is
+ *       tested.
  *
  * @param xml - The XCCDF XML string to process.
  * @param removeNewlines - A flag indicating whether to remove newlines from the processed data.
@@ -84,14 +96,40 @@ function processXCCDF(xml, removeNewlines, useRuleId, ovalDefinitions) {
     if (parsedXML.Benchmark === undefined) {
         throw new Error('Could not process the XCCDF file, check the input to make sure this is a properly formatted XCCDF file.');
     }
+    // Extracts all rules from the given benchmark groups.
     const rules = extractAllRules(parsedXML.Benchmark[0].Group);
+    // Variable used to store the profile data.
+    // The name is the benchmark Id, title and summary are from benchmark.
     const profile = new profile_1.default({
-        name: parsedXML.Benchmark[0]['@_id'],
-        title: parsedXML.Benchmark[0].title[0]['#text'],
-        summary: parsedXML.Benchmark[0].description[0]['#text']
+        //name: parsedXML.Benchmark[0]['@_id'],
+        // title: (parsedXML.Benchmark[0].title[0] as FrontMatter)['#text'],
+        // summary: (parsedXML.Benchmark[0].description[0] as RationaleElement)['#text']
+        name: Array.isArray(parsedXML.Benchmark[0]['@_id'])
+            ? parsedXML.Benchmark[0]['@_id'].map(n => n['@_id']).join(' ') === ''
+                ? parsedXML.Benchmark[0]['@_id'].map(n => n).join(' ')
+                : parsedXML.Benchmark[0]['@_id'].join(' ')
+            : parsedXML.Benchmark[0]['@_id'],
+        title: Array.isArray(parsedXML.Benchmark[0].title)
+            ? parsedXML.Benchmark[0].title.map(t => t['#text']).join(' ') === ''
+                ? parsedXML.Benchmark[0].title.map(t => t).join(' ')
+                : parsedXML.Benchmark[0].title.map(t => t['#text']).join(' ')
+            : parsedXML.Benchmark[0].title,
+        summary: Array.isArray(parsedXML.Benchmark[0].description)
+            ? parsedXML.Benchmark[0].description.map(d => d['#text']).join(' ') === ''
+                ? parsedXML.Benchmark[0].description.map(d => d['p'] || '').join(' ') === ''
+                    ? parsedXML.Benchmark[0].description.map(d => d).join(' ')
+                    : parsedXML.Benchmark[0].description.map(d => d['p'] || '').join(' ')
+                : parsedXML.Benchmark[0].description.map(d => d['#text']).join(' ')
+            : parsedXML.Benchmark[0].description
     });
+    // Process each rule, extracting the necessary
+    // data and save it to the profile variable.
     rules.forEach(rule => {
         var _a, _b, _c;
+        // The description tag contains the following tags:
+        //   "FalsePositives", "FalseNegatives", "Documentable", "Mitigations",
+        //   "SeverityOverrideGuidance", "PotentialImpacts", "ThirdPartyTools",
+        //   "MitigationControl", "Responsibility", "IAControls"
         let extractedDescription;
         if (typeof rule.description === 'object') {
             if (Array.isArray(rule.description) && lodash_1.default.get(rule, "description[0]['#text']")) {
@@ -105,6 +143,10 @@ function processXCCDF(xml, removeNewlines, useRuleId, ovalDefinitions) {
                     if (Array.isArray(lodash_1.default.get(rule.description, '[0].p'))) {
                         const joinedDescriptions = lodash_1.default.get(rule.description, '[0].p');
                         extractedDescription = (0, pretty_1.default)(joinedDescriptions.join('\n\n'));
+                        extractedDescription = (0, xccdf_1.removeHtmlTags)(extractedDescription).replace('\n', ' ');
+                    }
+                    else if (Array.isArray(rule.description)) {
+                        extractedDescription = (0, xccdf_1.convertEncodedHTMLIntoJson)(rule.description[0]);
                     }
                     else {
                         extractedDescription = JSON.stringify(rule.description);
@@ -115,10 +157,12 @@ function processXCCDF(xml, removeNewlines, useRuleId, ovalDefinitions) {
         else {
             extractedDescription = (0, xccdf_1.convertEncodedHTMLIntoJson)(rule.description);
         }
+        // Create a new control object and populate it with the necessary data.
         const control = new control_1.default();
+        // Update the control Id with the appropriate value based on the rule id.
         switch (useRuleId) {
             case 'group':
-                control.id = rule.group['@_id'];
+                control.id = rule.group['@_id'].toString();
                 break;
             case 'rule':
                 if (rule['@_id'][0].toLowerCase().startsWith('sv')) {
@@ -129,27 +173,51 @@ function processXCCDF(xml, removeNewlines, useRuleId, ovalDefinitions) {
                 }
                 break;
             case 'version':
-                control.id = rule.version;
+                if (rule.version !== undefined) {
+                    (lodash_1.default.isArray(rule.version))
+                        ? control.id = rule.version[0]
+                        : control.id = rule.version;
+                }
+                else {
+                    throw new Error('The rule type "version" did not provide an identification (Id) value');
+                }
                 break;
-            case 'cis':
-                // eslint-disable-next-line  no-case-declarations
+            case 'cis': {
+                // Regex explained
+                // \d:
+                //     matches a single digit (0-9), the required starting point of the match.
+                // (\d?):
+                //     matches an optional digit, there are three of these in sequence
+                // (.\d(\d?)(\d?)(\d?))?:
+                //     matches an optional group that starts with a period (.) followed
+                //     by one digit and up to three additional optional digits
+                // The pattern is repeated four times to match between zero and four
+                // groups of a period followed by one required digit and up to three
+                // additional optional digits. The pattern matches:
+                // 1, 123, 1.2, 1.234, 1.2.3.4.5, or 1.23.456.7.89
                 const controlIdRegex = /\d(\d?)(\d?)(\d?)(.\d(\d?)(\d?)(\d?))?(.\d(\d?)(\d?)(\d?))?(.\d(\d?)(\d?)(\d?))?(.\d(\d?)(\d?)(\d?))?/g;
-                // eslint-disable-next-line  no-case-declarations
                 const controlIdMatch = controlIdRegex.exec(rule['@_id']);
                 if (controlIdMatch) {
                     control.id = controlIdMatch[0];
                 }
                 else {
-                    throw new Error(`Could not parse control ID from rule ID: ${rule['@_id']}. Expecting something in this example format: 'xccdf_org.cisecurity.benchmarks_rule_1.1.11_Rule_title_summary`);
+                    throw new Error(`Could not parse control ID from rule ID: ${rule['@_id']}. Expecting something in this example format: xccdf_org.cisecurity.benchmarks_rule_1.1.11_Rule_title_summary`);
                 }
                 break;
+            }
             default:
-                throw new Error('useRuleId must be one of "group", "rule", or "version"');
+                throw new Error('useRuleId must be one of "group", "rule", "version" for STIG benchmarks, or "cis" for CIS benchmarks');
         }
         if (!(lodash_1.default.isArray(rule.title) && rule.title.length === 1)) {
             throw new Error('Rule title is not an array of length 1. Investigate if the file is in the proper format.');
         }
-        control.title = (0, xccdf_1.removeXMLSpecialCharacters)(rule['@_severity'] ? ensureDecodedXMLStringValue(rule.title[0], 'undefined title') : `[[[MISSING SEVERITY FROM BENCHMARK]]] ${ensureDecodedXMLStringValue(rule.title[0], 'undefined title')}`);
+        // Update the control title with the rule.tile content if a rule severity
+        // exists after removing any special characters, otherwise set the control
+        // title to [[[MISSING SEVERITY FROM BENCHMARK]]], undefined title.
+        control.title = (0, xccdf_1.removeXMLSpecialCharacters)(rule['@_severity'] || rule['@_weight']
+            ? ensureDecodedXMLStringValue(rule.title[0], 'undefined title')
+            : `[[[MISSING SEVERITY or WEIGHT FROM BENCHMARK]]] ${ensureDecodedXMLStringValue(rule.title[0], 'undefined title')}`);
+        // Update the control description (desc) with the extracted description content
         if (typeof extractedDescription === 'object' && !Array.isArray(extractedDescription)) {
             control.desc = ((_a = extractedDescription.VulnDiscussion) === null || _a === void 0 ? void 0 : _a.split('Satisfies: ')[0]) || '';
         }
@@ -162,10 +230,13 @@ function processXCCDF(xml, removeNewlines, useRuleId, ovalDefinitions) {
         else {
             logger.warn(`Invalid value for extracted description: ${extractedDescription}`);
         }
+        // Update the control impact with the severity value from the rule,
+        // default to medium (0.5) if not found.
         control.impact = (0, xccdf_1.severityStringToImpact)(rule['@_severity'] || 'medium');
         if (!control.descs || Array.isArray(control.descs)) {
             control.descs = {};
         }
+        // Update the control descriptions (descs) check with the check text from the rule,
         if (rule.check) {
             if (rule.check.some((ruleValue) => 'check-content' in ruleValue)) {
                 control.descs.check = (0, xccdf_1.removeXMLSpecialCharacters)(rule.check ? rule.check[0]['check-content'][0] : 'Missing description');
@@ -240,20 +311,22 @@ function processXCCDF(xml, removeNewlines, useRuleId, ovalDefinitions) {
                 control.descs.check = checkTexts.join('\n');
             }
         }
+        // Update the control descriptions (descs) fix with content from the rule
+        // fixtest, if not found, defaults to "Missing fix text"
         if (lodash_1.default.get(rule.fixtext, '[0]["#text"]')) {
             control.descs.fix = (0, xccdf_1.removeXMLSpecialCharacters)(rule.fixtext[0]['#text']);
         }
         else if (typeof rule.fixtext === 'undefined') {
             if (rule.fix && rule.fix[0]) {
-                control.descs.fix = (0, xccdf_1.removeXMLSpecialCharacters)(rule.fix[0]['#text'] || 'Missing fix text');
+                control.descs.fix = (0, xccdf_1.removeHtmlTags)(rule.fix[0]['#text'] || 'Missing fix text');
             }
         }
         else if (typeof rule.fixtext[0] === 'string') {
-            control.descs.fix = (0, xccdf_1.removeXMLSpecialCharacters)(rule.fixtext[0]);
+            control.descs.fix = (0, xccdf_1.removeHtmlTags)(rule.fixtext[0]);
         }
         else if (typeof rule.fixtext[0] === 'object') {
             if (Array.isArray(rule.fixtext[0])) {
-                control.descs.fix = (0, xccdf_1.removeXMLSpecialCharacters)((0, pretty_1.default)((0, xccdf_1.convertJsonIntoXML)(rule.fixtext[0].map((fixtext) => {
+                control.descs.fix = (0, xccdf_1.removeHtmlTags)((0, pretty_1.default)((0, xccdf_1.convertJsonIntoXML)(rule.fixtext[0].map((fixtext) => {
                     if (fixtext.div) {
                         return fixtext.div;
                     }
@@ -263,21 +336,25 @@ function processXCCDF(xml, removeNewlines, useRuleId, ovalDefinitions) {
                 }))));
             }
             else {
-                control.descs.fix = (0, xccdf_1.removeXMLSpecialCharacters)((0, pretty_1.default)((0, xccdf_1.convertJsonIntoXML)(rule.fixtext)));
+                control.descs.fix = (0, xccdf_1.removeHtmlTags)((0, xccdf_1.removeXMLSpecialCharacters)((0, pretty_1.default)((0, xccdf_1.convertJsonIntoXML)(rule.fixtext)))).replace('\n', ' ').trim();
             }
         }
         else {
             control.descs.fix = 'Missing fix text';
         }
+        // Update the control tags base on corresponding rule tags.
         control.tags.severity = (0, xccdf_1.impactNumberToSeverityString)((0, xccdf_1.severityStringToImpact)(rule['@_severity'] || 'medium'));
         control.tags.gid = rule.group['@_id'],
             control.tags.rid = rule['@_id'];
         control.tags.stig_id = rule['version'];
-        if (typeof rule.group.title[0] === 'string') {
-            control.tags.gtitle = (0, xccdf_1.removeXMLSpecialCharacters)(rule.group.title[0]);
+        if (typeof rule.group.title === 'string') {
+            control.tags.gtitle = (0, xccdf_1.removeXMLSpecialCharacters)(rule.group.title);
         }
         else {
-            control.tags.gtitle = (0, xccdf_1.removeXMLSpecialCharacters)(lodash_1.default.get(rule.group, 'title[0].#text', 'undefined title'));
+            const gtitle = lodash_1.default.get(rule.group, 'title[0].#text', 'undefined title') === 'undefined title'
+                ? lodash_1.default.get(rule.group, 'title[0]', 'undefined title')
+                : lodash_1.default.get(rule.group, 'title[0].#text', 'undefined title');
+            control.tags.gtitle = typeof gtitle === 'string' ? gtitle : gtitle['#text'] || 'undefined title';
         }
         if (rule['fix'] && rule['fix'].length > 0) {
             control.tags.fix_id = rule['fix'][0]['@_id'];
@@ -285,11 +362,20 @@ function processXCCDF(xml, removeNewlines, useRuleId, ovalDefinitions) {
         if (rule['rationale']) {
             control.tags.rationale = rule['rationale'][0]['#text'];
         }
+        // The description tag contains the following tags as well:
+        //   "FalsePositives", "FalseNegatives", "Documentable", "Mitigations",
+        //   "SeverityOverrideGuidance", "PotentialImpacts", "ThirdPartyTools",
+        //   "MitigationControl", "Responsibility", "IAControls"
         if (typeof extractedDescription === 'object') {
-            control.tags.satisfies = ((_b = extractedDescription.VulnDiscussion) === null || _b === void 0 ? void 0 : _b.includes('Satisfies: ')) && extractedDescription.VulnDiscussion.split('Satisfies: ').length >= 1 ? extractedDescription.VulnDiscussion.split('Satisfies: ')[1].split(',').map(satisfaction => satisfaction.trim()) : undefined;
+            control.tags.satisfies =
+                ((_b = extractedDescription.VulnDiscussion) === null || _b === void 0 ? void 0 : _b.includes('Satisfies: ')) && extractedDescription.VulnDiscussion.split('Satisfies: ').length >= 1
+                    ? extractedDescription.VulnDiscussion.split('Satisfies: ')[1].split(',').map(satisfaction => satisfaction.trim())
+                    : undefined;
             control.tags.false_negatives = extractedDescription.FalseNegatives || undefined;
             control.tags.false_positives = extractedDescription.FalsePositives || undefined;
-            control.tags.documentable = typeof extractedDescription.Documentable === 'boolean' ? extractedDescription.Documentable : undefined;
+            control.tags.documentable = typeof extractedDescription.Documentable === 'boolean'
+                ? extractedDescription.Documentable
+                : undefined;
             control.tags.mitigations = extractedDescription.Mitigations || undefined;
             control.tags.severity_override_guidance = extractedDescription.SeverityOverrideGuidance || undefined;
             control.tags.potential_impacts = extractedDescription.PotentialImpacts || undefined;
@@ -299,11 +385,15 @@ function processXCCDF(xml, removeNewlines, useRuleId, ovalDefinitions) {
             control.tags.responsibility = extractedDescription.Responsibility || undefined;
             control.tags.ia_controls = extractedDescription.IAControls || undefined;
         }
+        // Ensure that tags inside the tags array are not an array
         control.tags = lodash_1.default.mapValues(lodash_1.default.omitBy(control.tags, (value) => value === undefined), (value) => {
             if (value && Array.isArray(value)) {
                 if (Array.isArray(value[0])) {
                     return (0, xccdf_1.removeXMLSpecialCharacters)(value[0][0]);
                 }
+                else if (value.length > 1) {
+                    return value;
+                }
                 else {
                     return (0, xccdf_1.removeXMLSpecialCharacters)(value[0]);
                 }
@@ -315,7 +405,7 @@ function processXCCDF(xml, removeNewlines, useRuleId, ovalDefinitions) {
                 return value;
             }
         });
-        // Get all identifiers from the rule
+        // Get all identifiers from the rule; cci, nist, and legacy
         if (rule.ident) {
             rule.ident.forEach((identifier) => {
                 var _a, _b, _c;
@@ -342,8 +432,9 @@ function processXCCDF(xml, removeNewlines, useRuleId, ovalDefinitions) {
                 }
             });
         }
+        // Update control references with content from the benchmark rule object
         (_c = rule.reference) === null || _c === void 0 ? void 0 : _c.forEach((reference) => {
-            var _a, _b, _c, _d;
+            var _a, _b, _c, _d, _e;
             if (lodash_1.default.get(reference, '@_href') === '') {
                 (_a = control.refs) === null || _a === void 0 ? void 0 : _a.push(lodash_1.default.get(reference, '#text', 'undefined href'));
             }
@@ -368,7 +459,13 @@ function processXCCDF(xml, removeNewlines, useRuleId, ovalDefinitions) {
                     }
                     else {
                         if ('title' in reference) {
-                            (_d = control.refs) === null || _d === void 0 ? void 0 : _d.push(lodash_1.default.get(reference, 'title'));
+                            const title = lodash_1.default.get(reference, 'title');
+                            if (Array.isArray(title)) {
+                                (_d = control.refs) === null || _d === void 0 ? void 0 : _d.push(title[0]);
+                            }
+                            else {
+                                (_e = control.refs) === null || _e === void 0 ? void 0 : _e.push(lodash_1.default.get(reference, 'title'));
+                            }
                         }
                     }
                     // Add the reference to the control tags when separated by §

package/lib/utilities/diff.js

@@ -151,7 +151,7 @@ function diffProfile(fromProfile, toProfile, logger) {
                 logger.error(`Unable to find existing control ${diffValue[1]}`);
             }
         }
-        else if (diffValue[0] === '+' && !changedControlIds.includes(diffValue[1].toString().toLowerCase()) && diffValue[1]) {
+        else if (diffValue[0] === '+' && !changedControlIds.includes(diffValue[1].toLowerCase()) && diffValue[1]) {
             logger.info(JSON.stringify(diffValue));
             logger.info(JSON.stringify(changedControlIds));
             profileDiff.addedControlIDs.push(diffValue[1]);

package/lib/utilities/update.d.ts

@@ -74,4 +74,14 @@ export declare function updateControlDescribeBlock(from: Control, update: Partia
  * @throws Will throw an error if a new control is added but the control data is not available.
  */
 export declare function updateProfile(from: Profile, using: Profile, logger: winston.Logger): Omit<UpdatedProfileReturn, 'markdown'>;
+/**
+ * Update a Profile with with new metadata from a XCCDF benchmark
+ *
+ * @param from - A Profile object
+ * @param using - An XCCDF in string format (XML)
+ * @param id - Specifies the rule ID format to use ('group', 'rule', 'version', or 'cis').
+ * @param logger - A winston logger instance for logging debug information.
+ * @param ovalDefinitions - Optional OVAL definitions to use for resolving values.
+ * @returns The Updated Profile (profile, the diff between from and using, and the markdown)
+ */
 export declare function updateProfileUsingXCCDF(from: Profile, using: string, id: 'group' | 'rule' | 'version' | 'cis', logger: winston.Logger, ovalDefinitions?: Record<string, OvalDefinitionValue>): UpdatedProfileReturn;

package/lib/utilities/update.js

@@ -285,7 +285,7 @@ function getExistingDescribeFromControl(control) {
 function findUpdatedControlByAllIdentifiers(existingControl, updatedControls) {
     // Try to match based on IDs
     let updatedControl = updatedControls.find((updatedControl) => {
-        return updatedControl.id[0].toLowerCase() === existingControl.id[0].toLowerCase();
+        return updatedControl.id.toLowerCase() === existingControl.id.toLowerCase();
     });
     if (updatedControl) {
         return updatedControl;
@@ -377,9 +377,19 @@ function updateProfile(from, using, logger) {
         diff,
     };
 }
+/**
+ * Update a Profile with with new metadata from a XCCDF benchmark
+ *
+ * @param from - A Profile object
+ * @param using - An XCCDF in string format (XML)
+ * @param id - Specifies the rule ID format to use ('group', 'rule', 'version', or 'cis').
+ * @param logger - A winston logger instance for logging debug information.
+ * @param ovalDefinitions - Optional OVAL definitions to use for resolving values.
+ * @returns The Updated Profile (profile, the diff between from and using, and the markdown)
+ */
 function updateProfileUsingXCCDF(from, using, id, logger, ovalDefinitions) {
     logger.info(`Updating profile ${from.name} with control IDs type: ${id}`);
-    // Parse the XCCDF benchmark and convert it into a Profile
+    // Parse the XCCDF benchmark and convert it into a Profile object
     logger.debug('Loading XCCDF File');
     const xccdfProfile = (0, xccdf_1.processXCCDF)(using, false, id, ovalDefinitions);
     logger.debug('Loaded XCCDF File');

package/lib/utilities/xccdf.d.ts

@@ -1,23 +1,55 @@
 import { DecodedDescription } from '../types/xccdf';
 /**
- * Converts an encoded XML string into a JSON object.
+ * Converts an encoded XML string into a JSON object using specified
+ * parsing options.
  *
- * @param encodedXml - The encoded XML string to be converted.
+ * @param encodedXml      - The encoded XML string to be converted.
+ * @param xmlParserOption - The parsing option to be used. Defaults to
+ *                          'withArrayOption'.
+ *   Possible values are:
+ *     - 'withArrayOption': Parses XML with array option enabled.
+ *     - 'withArrayNoEntitiesOption': Parses XML with array option
+ *       enabled and processes entities.
+ *     - Any other value: Parses XML without array option.
  * @returns The JSON representation of the XML string.
  *
  * @remarks
  * This function uses the `fast-xml-parser` library to parse the XML string.
  * The parser options are configured to:
- * - Not ignore attributes.
+ * - Prevent the parser from converting XML entities (converting &lt into <)
+ * - Ignore attributes, allow or disallows attributes to be parsed
  * - Remove namespace prefixes.
  * - Prefix attribute names with '@_'.
- * - Stop parsing at 'div' and 'p' nodes.
- * - Treat all nodes as arrays.
+ * - Stop parsing 'div' and 'p' tags.
+ * - Treat all nodes as arrays or not
+ *
+ * Options being used for the XML parser (V4) are:
+ *  - processEntities: true or false (based on xmlParserOption)
+ *  - ignoreAttributes: false (allow attributes to be parsed)
+ *  - removeNSPrefix: true (remove namespace prefixes)
+ *  - attributeNamePrefix: '@_' (prefix all attribute names with @_)
+ *  - stopNodes: ["*.pre", "*.p"]
+ *  - isArray(): true or false (based on xmlParserOption)
+ *
+ * NOTE: The isArray can specify what tags to always convert into an array, we
+ *       do not specify specific fields as it could break parsing if future
+ *       fields are added, we parse all fields as an array.
  *
  * For more details on the parser options, see the documentation for the v4 or v5 version of the library:
  * {@link https://github.com/NaturalIntelligence/fast-xml-parser/tree/master/docs/v4}
  */
-export declare function convertEncodedXmlIntoJson(encodedXml: string): any;
+/**
+ * Converts an encoded XML string into a JSON object using specified parsing options.
+ *
+ * @param encodedXml - The encoded XML string to be converted.
+ * @param xmlParserOption - The parsing option to be used. Defaults to 'withArrayOption'.
+ *                          Possible values are:
+ *                          - 'withArrayOption': Parses XML with array option enabled.
+ *                          - 'withArrayNoEntitiesOption': Parses XML with array option enabled and processes entities.
+ *                          - Any other value: Parses XML without array option.
+ * @returns The JSON object resulting from the XML parsing.
+ */
+export declare function convertEncodedXmlIntoJson(encodedXml: string, xmlParserOption?: string): any;
 /**
  * Converts a JSON object into an XML string.
  *
@@ -35,6 +67,20 @@ export declare function convertJsonIntoXML(data: any): string;
  * @returns The decoded string with XML special characters removed.
  */
 export declare function removeXMLSpecialCharacters(str: string): string;
+/**
+ * Removes all of the HTML tags and leaves only the text content.
+  *
+ * @param input - The string from which HTML tags should be removed.
+ * @returns A new string with all HTML tags removed.
+ *
+ * @example
+ * ```typescript
+ * const str = '<div>Hello <b>World</b>!</div>';
+ * const stripped = removeHtmlTags(str);
+ * console.log(stripped); // Output: "Hello World!"
+ * ```
+ */
+export declare function removeHtmlTags(input: string): string;
 /**
  * Converts a severity string to a numerical impact value.
  *

package/lib/utilities/xccdf.js

@@ -3,6 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.convertEncodedXmlIntoJson = convertEncodedXmlIntoJson;
 exports.convertJsonIntoXML = convertJsonIntoXML;
 exports.removeXMLSpecialCharacters = removeXMLSpecialCharacters;
+exports.removeHtmlTags = removeHtmlTags;
 exports.severityStringToImpact = severityStringToImpact;
 exports.impactNumberToSeverityString = impactNumberToSeverityString;
 exports.convertEncodedHTMLIntoJson = convertEncodedHTMLIntoJson;
@@ -13,33 +14,85 @@ const htmlparser = tslib_1.__importStar(require("htmlparser2"));
 const lodash_1 = tslib_1.__importDefault(require("lodash"));
 const he_1 = tslib_1.__importDefault(require("he"));
 /**
- * Converts an encoded XML string into a JSON object.
+ * Converts an encoded XML string into a JSON object using specified
+ * parsing options.
  *
- * @param encodedXml - The encoded XML string to be converted.
+ * @param encodedXml      - The encoded XML string to be converted.
+ * @param xmlParserOption - The parsing option to be used. Defaults to
+ *                          'withArrayOption'.
+ *   Possible values are:
+ *     - 'withArrayOption': Parses XML with array option enabled.
+ *     - 'withArrayNoEntitiesOption': Parses XML with array option
+ *       enabled and processes entities.
+ *     - Any other value: Parses XML without array option.
  * @returns The JSON representation of the XML string.
  *
  * @remarks
  * This function uses the `fast-xml-parser` library to parse the XML string.
  * The parser options are configured to:
- * - Not ignore attributes.
+ * - Prevent the parser from converting XML entities (converting &lt into <)
+ * - Ignore attributes, allow or disallows attributes to be parsed
  * - Remove namespace prefixes.
  * - Prefix attribute names with '@_'.
- * - Stop parsing at 'div' and 'p' nodes.
- * - Treat all nodes as arrays.
+ * - Stop parsing 'div' and 'p' tags.
+ * - Treat all nodes as arrays or not
+ *
+ * Options being used for the XML parser (V4) are:
+ *  - processEntities: true or false (based on xmlParserOption)
+ *  - ignoreAttributes: false (allow attributes to be parsed)
+ *  - removeNSPrefix: true (remove namespace prefixes)
+ *  - attributeNamePrefix: '@_' (prefix all attribute names with @_)
+ *  - stopNodes: ["*.pre", "*.p"]
+ *  - isArray(): true or false (based on xmlParserOption)
+ *
+ * NOTE: The isArray can specify what tags to always convert into an array, we
+ *       do not specify specific fields as it could break parsing if future
+ *       fields are added, we parse all fields as an array.
  *
  * For more details on the parser options, see the documentation for the v4 or v5 version of the library:
  * {@link https://github.com/NaturalIntelligence/fast-xml-parser/tree/master/docs/v4}
  */
-function convertEncodedXmlIntoJson(encodedXml) {
-    const options = {
+/**
+ * Converts an encoded XML string into a JSON object using specified parsing options.
+ *
+ * @param encodedXml - The encoded XML string to be converted.
+ * @param xmlParserOption - The parsing option to be used. Defaults to 'withArrayOption'.
+ *                          Possible values are:
+ *                          - 'withArrayOption': Parses XML with array option enabled.
+ *                          - 'withArrayNoEntitiesOption': Parses XML with array option enabled and processes entities.
+ *                          - Any other value: Parses XML without array option.
+ * @returns The JSON object resulting from the XML parsing.
+ */
+function convertEncodedXmlIntoJson(encodedXml, xmlParserOption = 'withArrayOption') {
+    const withArrayOption = {
+        processEntities: false,
         ignoreAttributes: false,
         removeNSPrefix: true,
         attributeNamePrefix: '@_',
-        stopNodes: ['div', 'p'],
-        // eslint-disable-next-line @typescript-eslint/no-unused-vars
-        isArray: (_name, _jpath, _isLeafNode, _isAttribute) => true,
+        stopNodes: ['*.div', '*.p'],
+        isArray: () => true,
     };
-    const parser = new fast_xml_parser_1.XMLParser(options);
+    const withArrayNoEntitiesOption = {
+        processEntities: true,
+        ignoreAttributes: false,
+        removeNSPrefix: true,
+        attributeNamePrefix: '@_',
+        stopNodes: ['*.div', '*.p'],
+        isArray: () => true,
+    };
+    const noArrayOption = {
+        processEntities: false,
+        ignoreAttributes: false,
+        removeNSPrefix: true,
+        attributeNamePrefix: '@_',
+        stopNodes: ['*.div', '*.p'],
+        isArray: () => false,
+    };
+    const parser = new fast_xml_parser_1.XMLParser(xmlParserOption === 'withArrayOption'
+        ? withArrayOption
+        : xmlParserOption === 'withArrayNoEntitiesOption'
+            ? withArrayNoEntitiesOption
+            : noArrayOption);
     return parser.parse(encodedXml);
 }
 /**
@@ -61,11 +114,35 @@ function convertJsonIntoXML(data) {
  * @returns The decoded string with XML special characters removed.
  */
 function removeXMLSpecialCharacters(str) {
-    //console.log('Remove special characters: ', JSON.stringify(str, null, 2));
     const result = he_1.default.decode(str);
-    //console.log('Result of he.decode: ', JSON.stringify(result));
     return result;
 }
+/**
+ * Removes all of the HTML tags and leaves only the text content.
+  *
+ * @param input - The string from which HTML tags should be removed.
+ * @returns A new string with all HTML tags removed.
+ *
+ * @example
+ * ```typescript
+ * const str = '<div>Hello <b>World</b>!</div>';
+ * const stripped = removeHtmlTags(str);
+ * console.log(stripped); // Output: "Hello World!"
+ * ```
+ */
+function removeHtmlTags(input) {
+    // Regex explained
+    //    <: Matches the opening angle bracket of an HTML tag
+    //   /?: Matches zero or one forward slash /, to include closing tags
+    // [^>]: Matches any character except the > symbol
+    //    +: Ensures preceding pattern ([^>]) matches one or more characters
+    // (>|$):
+    //   > matches the closing angle bracket of an HTML tag.
+    //   $ matches the end of the string. This ensures the regex can handle
+    //     cases where the tag is incomplete or unclosed (e.g., <div)
+    // g: Global flag to find all matches in the input string
+    return input.replace(/<\/?[^>]+(>|$)/g, '');
+}
 /**
  * Converts a severity string to a numerical impact value.
  *
@@ -166,7 +243,7 @@ function convertEncodedHTMLIntoJson(encodedHTML) {
         });
         htmlParser.write(patchedHTML);
         htmlParser.end();
-        const converted = convertEncodedXmlIntoJson(xmlChunks.join(''));
+        const converted = convertEncodedXmlIntoJson(xmlChunks.join(''), 'noArrayOption');
         let cleaned = {};
         // Some STIGs have xml tags inside of the actual text which breaks processing,
         // e.g U_ASD_STIG_V5R1_Manual-xccdf.xml and all Oracle Database STIGs

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mitre/inspec-objects",
-  "version": "2.0.0",
+  "version": "2.0.2",
   "description": "Typescript objects for normalizing between InSpec profiles and XCCDF benchmarks",
   "main": "lib/index.js",
   "publishConfig": {
@@ -31,13 +31,13 @@
     "@types/lodash": "^4.14.178",
     "@types/mustache": "^4.2.0",
     "@types/pretty": "^2.0.1",
-    "fast-xml-parser": "^4.5.1",
+    "fast-xml-parser": "^5.0.7",
     "flat": "5.0.2",
     "he": "^1.2.0",
     "htmlparser2": "^10.0.0",
     "inspecjs": "^2.6.6",
     "json-diff": "^1.0.6",
-    "jstoxml": "^5.0.2",
+    "jstoxml": "^6.0.1",
     "lodash": "^4.17.21",
     "mustache": "^4.2.0",
     "pretty": "^2.0.0",
@@ -45,12 +45,12 @@
     "yaml": "^2.3.1"
   },
   "devDependencies": {
-    "@types/jest": "^29.5.12",
-    "@types/node": "^22.5.2",
+    "@types/jest": "^30.0.0",
+    "@types/node": "^24.0.0",
     "@typescript-eslint/eslint-plugin": "^6.4.1",
     "@typescript-eslint/parser": "^6.0.0",
     "eslint": "^8.30.0",
-    "jest": "^29.7.0",
+    "jest": "^30.0.0",
     "ts-jest": "^29.1.1",
     "tslib": "^2.4.0",
     "typescript": "^5.2.2"