@mitre/inspec-objects 1.0.1 → 2.0.1

package/lib/parsers/xccdf.js

@@ -1,6 +1,8 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.processXCCDF = exports.extractAllComplexChecks = exports.extractAllRules = void 0;
+exports.extractAllRules = extractAllRules;
+exports.extractAllComplexChecks = extractAllComplexChecks;
+exports.processXCCDF = processXCCDF;
 const tslib_1 = require("tslib");
 const profile_1 = tslib_1.__importDefault(require("../objects/profile"));
 const xccdf_1 = require("../utilities/xccdf");
@@ -9,6 +11,12 @@ const lodash_1 = tslib_1.__importDefault(require("lodash"));
 const CciNistMappingData_1 = require("../mappings/CciNistMappingData");
 const pretty_1 = tslib_1.__importDefault(require("pretty"));
 const logging_1 = require("../utilities/logging");
+/**
+ * Extracts all rules from the given benchmark groups, including nested groups.
+ *
+ * @param groups - An array of benchmark groups to extract rules from.
+ * @returns An array of contextualized rules, each rule includes its parent group context.
+ */
 function extractAllRules(groups) {
     const rules = [];
     groups.forEach((group) => {
@@ -26,7 +34,16 @@ function extractAllRules(groups) {
     });
     return rules;
 }
-exports.extractAllRules = extractAllRules;
+/**
+ * Extracts all nested complex checks from a given `RuleComplexCheck` object.
+ *
+ * This function recursively traverses the `complex-check` property of the input
+ * `RuleComplexCheck` object and collects all nested complex checks into a flat array.
+ * Each complex check in the resulting array will have its own `complex-check` property omitted.
+ *
+ * @param complexCheck - The `RuleComplexCheck` object to extract complex checks from.
+ * @returns An array of `RuleComplexCheck` objects with the `complex-check` property omitted.
+ */
 function extractAllComplexChecks(complexCheck) {
     const complexChecks = [lodash_1.default.omit(complexCheck, 'complex-check')];
     if (complexCheck['complex-check']) {
@@ -37,25 +54,81 @@ function extractAllComplexChecks(complexCheck) {
     }
     return complexChecks;
 }
-exports.extractAllComplexChecks = extractAllComplexChecks;
-function ensureDecodedXMLStringValue(input) {
-    return lodash_1.default.get(input, '[0].#text') ? lodash_1.default.get(input, '[0].#text') : input;
+/**
+ * Ensures that the input is decoded to a string 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.isArray(input)
+            ? lodash_1.default.get(input, '[0].#text', defaultValue)
+            : lodash_1.default.get(input, '#text', defaultValue);
 }
-// Moving the newline removal to diff library rather than processXCCDF level
+/**
+ * Processes an XCCDF 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.
+ * @param useRuleId - Specifies the rule ID format to use. Can be 'group', 'rule', 'version', or 'cis'.
+ * @param ovalDefinitions - Optional OVAL definitions to use for resolving values.
+ * @returns A Profile object representing the processed XCCDF data.
+ * @throws Will throw an error if the XCCDF file is not properly formatted or if required data is missing.
+ */
 function processXCCDF(xml, removeNewlines, useRuleId, ovalDefinitions) {
-    const logger = (0, logging_1.createWinstonLogger)();
+    const logger = (0, logging_1.createWinstonLogger)('ts-inspec-objects');
     const parsedXML = (0, xccdf_1.convertEncodedXmlIntoJson)(xml);
     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']")) {
@@ -69,6 +142,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);
@@ -79,38 +156,67 @@ 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'].toLowerCase().startsWith('sv')) {
-                    control.id = rule['@_id'].split('r')[0];
+                if (rule['@_id'][0].toLowerCase().startsWith('sv')) {
+                    control.id = rule['@_id'][0].split('r')[0];
                 }
                 else {
-                    control.id = rule['@_id'];
+                    control.id = rule['@_id'][0];
                 }
                 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) : `[[[MISSING SEVERITY FROM BENCHMARK]]] ${ensureDecodedXMLStringValue(rule.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]) || '';
         }
@@ -123,13 +229,16 @@ function processXCCDF(xml, removeNewlines, useRuleId, ovalDefinitions) {
         else {
             logger.warn(`Invalid value for extracted description: ${extractedDescription}`);
         }
-        control.impact = (0, xccdf_1.severityStringToImpact)(rule['@_severity'] || 'medium', rule.group['@_id']);
+        // 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'] : 'Missing description');
+                control.descs.check = (0, xccdf_1.removeXMLSpecialCharacters)(rule.check ? rule.check[0]['check-content'][0] : 'Missing description');
                 control.tags.check_id = rule.check[0]['@_system'];
             }
             else if (rule.check.some((ruleValue) => 'check-content-ref' in ruleValue) && ovalDefinitions) {
@@ -145,7 +254,8 @@ function processXCCDF(xml, removeNewlines, useRuleId, ovalDefinitions) {
                     }
                 }
                 if (referenceID && referenceID in ovalDefinitions) {
-                    control.descs.check = (0, xccdf_1.removeXMLSpecialCharacters)(ovalDefinitions[referenceID].metadata[0].title);
+                    // May need to further check if ovalDefinitions[referenceID].metadata[0].title[0] are not populated?
+                    control.descs.check = (0, xccdf_1.removeXMLSpecialCharacters)(ovalDefinitions[referenceID].metadata[0].title[0]);
                 }
                 else if (referenceID) {
                     logger.warn(`Could not find OVAL definition for ${referenceID}`);
@@ -164,7 +274,7 @@ function processXCCDF(xml, removeNewlines, useRuleId, ovalDefinitions) {
                     if (complexCheck.check) {
                         complexCheck.check.forEach((check) => {
                             var _a;
-                            if ((_a = check['@_system']) === null || _a === void 0 ? void 0 : _a.toLowerCase().includes('oval')) {
+                            if ((_a = check['@_system']) === null || _a === void 0 ? void 0 : _a.toString().toLowerCase().includes('oval')) {
                                 const ovalReference = check['check-content-ref'][0]['@_name'];
                                 if (!ovalDefinitions) {
                                     logger.warn(`Missing OVAL definitions! Unable to process OVAL reference: ${ovalReference}`);
@@ -200,15 +310,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 === 'string') {
-            control.descs.fix = (0, xccdf_1.removeXMLSpecialCharacters)(rule.fixtext);
+        else if (typeof rule.fixtext === 'undefined') {
+            if (rule.fix && rule.fix[0]) {
+                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.removeHtmlTags)(rule.fixtext[0]);
         }
-        else if (typeof rule.fixtext === 'object') {
-            if (Array.isArray(rule.fixtext)) {
-                control.descs.fix = (0, xccdf_1.removeXMLSpecialCharacters)((0, pretty_1.default)((0, xccdf_1.convertJsonIntoXML)(rule.fixtext.map((fixtext) => {
+        else if (typeof rule.fixtext[0] === 'object') {
+            if (Array.isArray(rule.fixtext[0])) {
+                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;
                     }
@@ -218,18 +335,14 @@ function processXCCDF(xml, removeNewlines, useRuleId, ovalDefinitions) {
                 }))));
             }
             else {
-                control.descs.fix = (0, xccdf_1.removeXMLSpecialCharacters)((0, pretty_1.default)((0, xccdf_1.convertJsonIntoXML)(rule.fixtext)));
-            }
-        }
-        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)((0, xccdf_1.removeXMLSpecialCharacters)((0, pretty_1.default)((0, xccdf_1.convertJsonIntoXML)(rule.fixtext)))).replace('\n', ' ').trim();
             }
         }
         else {
             control.descs.fix = 'Missing fix text';
         }
-        control.tags.severity = (0, xccdf_1.impactNumberToSeverityString)((0, xccdf_1.severityStringToImpact)(rule['@_severity'] || 'medium', control.id || 'Unknown'));
+        // 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'];
@@ -237,7 +350,10 @@ function processXCCDF(xml, removeNewlines, useRuleId, ovalDefinitions) {
             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'));
+            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'];
@@ -245,11 +361,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;
@@ -259,34 +384,46 @@ 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 (typeof value === 'string') {
+            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]);
+                }
+            }
+            else if (typeof value === 'string') {
                 return (0, xccdf_1.removeXMLSpecialCharacters)(value);
             }
             else {
                 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;
                 // Get CCIs
-                if (identifier['@_system'].toLowerCase().includes('cci')) {
+                if (identifier['@_system'][0].toLowerCase().includes('cci')) {
                     if (!('cci' in control.tags)) {
                         control.tags.cci = [];
                     }
                     (_a = control.tags.cci) === null || _a === void 0 ? void 0 : _a.push(identifier['#text']);
                 }
                 // Get legacy identifiers
-                else if (identifier['@_system'].toLowerCase().includes('legacy')) {
+                else if (identifier['@_system'][0].toLowerCase().includes('legacy')) {
                     if (!('legacy' in control.tags)) {
                         control.tags.legacy = [];
                     }
                     (_b = control.tags.legacy) === null || _b === void 0 ? void 0 : _b.push(identifier['#text']);
                 }
                 // Get NIST identifiers
-                else if (identifier['@_system'].toLowerCase().includes('nist')) {
+                else if (identifier['@_system'].toString().toLowerCase().includes('nist')) {
                     if (!('nist' in control.tags)) {
                         control.tags.nist = [];
                     }
@@ -294,17 +431,18 @@ 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'));
+                (_a = control.refs) === null || _a === void 0 ? void 0 : _a.push(lodash_1.default.get(reference, '#text', 'undefined href'));
             }
             else {
                 try {
                     const referenceText = lodash_1.default.get(reference, '#text') || '';
                     const referenceURL = lodash_1.default.get(reference, '@_href') || '';
                     if (referenceURL) {
-                        const parsedURL = new URL(lodash_1.default.get(reference, '@_href'));
+                        const parsedURL = new URL(lodash_1.default.get(reference, '@_href', 'undefined href'));
                         if (parsedURL.protocol.toLowerCase().includes('http') || parsedURL.protocol.toLowerCase().includes('https')) {
                             (_b = control.refs) === null || _b === void 0 ? void 0 : _b.push({
                                 ref: referenceText,
@@ -320,7 +458,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 §
@@ -341,8 +485,7 @@ function processXCCDF(xml, removeNewlines, useRuleId, ovalDefinitions) {
                             }
                         }
                         else {
-                            logger.warn('Reference parts of invalid length:');
-                            logger.info(referenceParts);
+                            logger.warn('Reference parts of invalid length: ', referenceParts);
                         }
                     }
                 }
@@ -370,4 +513,3 @@ function processXCCDF(xml, removeNewlines, useRuleId, ovalDefinitions) {
     profile.controls = lodash_1.default.sortBy(profile.controls, 'id');
     return profile.toUnformattedObject();
 }
-exports.processXCCDF = processXCCDF;

package/lib/utilities/diff.d.ts

@@ -1,8 +1,50 @@
 import Profile from '../objects/profile';
 import { ProfileDiff } from '../types/diff';
 import winston from 'winston';
+/**
+ * Removes newlines from all string values within a nested object.
+ *
+ * This function recursively traverses the provided object and replaces
+ * newline characters (`\n`) in string values with the placeholder `{{{{newlineHERE}}}}`.
+ * It also trims any leading or trailing whitespace from the string values.
+ *
+ * @param control - The object from which to remove newlines. If not provided,
+ *                  an empty object is returned.
+ * @returns A new object with newlines removed from all string values.
+ */
 export declare function removeNewlines(control?: Record<string, unknown>): Record<string, unknown>;
+/**
+ * Processes a diff object to ignore formatting differences such as whitespace.
+ * Goal is to use a linter for the formatting and compare characters without
+ * whitespaces here.
+ *
+ * The function performs the following:
+ * - If the diff value has a `__new` property, it compares the `__new` and
+ *   `__old` values after removing whitespace. If they are different, it sets
+ *   the result to the `__new` value.
+ * - If the diff value is an array, it maps and filters the array to include
+ *   only the new values.
+ * - If the diff value is an object, it recursively processes the object.
+ * - If the key ends with `__deleted`, it ignores the value.
+ * - Otherwise, it sets the result to the diff value.
+ *
+ * @param diffData - The diff object containing differences to process.
+ * @returns A new object with formatting differences ignored.
+ *
+
+ */
 export declare function ignoreFormattingDiff(diffData: Record<string, unknown>): Record<string, unknown>;
+/**
+ * Computes the differences between two profiles and logs the process.
+ *
+ * @param fromProfile - The original profile to compare from.
+ * @param toProfile   - The target profile to compare to.
+ * @param logger      - The logger instance to use for logging information.
+ *
+ * @returns An object containing two properties:
+ *  - `ignoreFormattingDiff`: The profile differences ignoring formatting changes.
+ *  - `rawDiff`: The raw profile differences.
+ */
 export declare function diffProfile(fromProfile: Profile, toProfile: Profile, logger: winston.Logger): {
     ignoreFormattingDiff: ProfileDiff;
     rawDiff: Record<string, unknown>;

package/lib/utilities/diff.js

@@ -1,11 +1,24 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.diffProfile = exports.ignoreFormattingDiff = exports.removeNewlines = void 0;
+exports.removeNewlines = removeNewlines;
+exports.ignoreFormattingDiff = ignoreFormattingDiff;
+exports.diffProfile = diffProfile;
 const tslib_1 = require("tslib");
 const json_diff_1 = require("json-diff");
 const lodash_1 = tslib_1.__importDefault(require("lodash"));
 const update_1 = require("./update");
 const global_1 = require("./global");
+/**
+ * Removes newlines from all string values within a nested object.
+ *
+ * This function recursively traverses the provided object and replaces
+ * newline characters (`\n`) in string values with the placeholder `{{{{newlineHERE}}}}`.
+ * It also trims any leading or trailing whitespace from the string values.
+ *
+ * @param control - The object from which to remove newlines. If not provided,
+ *                  an empty object is returned.
+ * @returns A new object with newlines removed from all string values.
+ */
 function removeNewlines(control) {
     if (!control) {
         return {};
@@ -20,16 +33,34 @@ function removeNewlines(control) {
         return value;
     });
 }
-exports.removeNewlines = removeNewlines;
-// Goal is to use a linter for the formatting and compare characters without whitespaces here
+/**
+ * Processes a diff object to ignore formatting differences such as whitespace.
+ * Goal is to use a linter for the formatting and compare characters without
+ * whitespaces here.
+ *
+ * The function performs the following:
+ * - If the diff value has a `__new` property, it compares the `__new` and
+ *   `__old` values after removing whitespace. If they are different, it sets
+ *   the result to the `__new` value.
+ * - If the diff value is an array, it maps and filters the array to include
+ *   only the new values.
+ * - If the diff value is an object, it recursively processes the object.
+ * - If the key ends with `__deleted`, it ignores the value.
+ * - Otherwise, it sets the result to the diff value.
+ *
+ * @param diffData - The diff object containing differences to process.
+ * @returns A new object with formatting differences ignored.
+ *
+
+ */
 function ignoreFormattingDiff(diffData) {
     return lodash_1.default.transform(diffData, (result, diffValue, key) => {
         if (lodash_1.default.has(diffValue, '__new')) {
             // Remove any trailing space
             if (typeof lodash_1.default.get(diffValue, '__new') === 'string' &&
                 typeof lodash_1.default.get(diffValue, '__old') === 'string') {
-                if ((0, global_1.removeWhitespace)(lodash_1.default.get(diffValue, '__new')) !==
-                    (0, global_1.removeWhitespace)(lodash_1.default.get(diffValue, '__old'))) {
+                if ((0, global_1.removeWhitespace)(lodash_1.default.get(diffValue, '__new', 'undefined')) !==
+                    (0, global_1.removeWhitespace)(lodash_1.default.get(diffValue, '__old', 'undefined'))) {
                     lodash_1.default.set(result, key, lodash_1.default.get(diffValue, '__new'));
                 }
             }
@@ -53,9 +84,20 @@ function ignoreFormattingDiff(diffData) {
         }
     });
 }
-exports.ignoreFormattingDiff = ignoreFormattingDiff;
+/**
+ * Computes the differences between two profiles and logs the process.
+ *
+ * @param fromProfile - The original profile to compare from.
+ * @param toProfile   - The target profile to compare to.
+ * @param logger      - The logger instance to use for logging information.
+ *
+ * @returns An object containing two properties:
+ *  - `ignoreFormattingDiff`: The profile differences ignoring formatting changes.
+ *  - `rawDiff`: The raw profile differences.
+ */
 function diffProfile(fromProfile, toProfile, logger) {
     var _a;
+    logger.info(`Processing diff between: ${fromProfile.name}(v:${fromProfile.version}) and: ${toProfile.name}(v:${toProfile.version})`);
     const profileDiff = {
         addedControlIDs: [],
         removedControlIDs: [],
@@ -72,9 +114,7 @@ function diffProfile(fromProfile, toProfile, logger) {
         addedControls: {},
         changedControls: {},
     };
-    const fromControlIDs = fromProfile.controls
-        .map((control) => control.id)
-        .sort();
+    const fromControlIDs = fromProfile.controls.map((control) => control.id).sort();
     const toControlIDs = toProfile.controls.map((control) => control.id).sort();
     // Find new controls
     const controlIDDiff = (_a = (0, json_diff_1.diff)(fromControlIDs, toControlIDs)) === null || _a === void 0 ? void 0 : _a.filter((item) => !(item.length === 1 && item[0] === ' '));
@@ -95,12 +135,12 @@ function diffProfile(fromProfile, toProfile, logger) {
                     const controlDiff = lodash_1.default.omit((0, json_diff_1.diff)(existingControl, newControl), 'code__deleted');
                     // logger.info("CONTROL DIFF:" + JSON.stringify(controlDiff, null, 2))
                     const renamedControlIgnoredFormatting = ignoreFormattingDiff(controlDiff);
-                    logger.info(JSON.stringify(renamedControlIgnoredFormatting));
                     profileDiff.changedControls[newControl.id] = renamedControlIgnoredFormatting;
                     profileDiff.changedControlIDs.push(newControl.id);
                     originalDiff.changedControls[newControl.id] = controlDiff;
                     originalDiff.changedControlIDs.push(newControl.id);
                     logger.verbose(`Control ${existingControl.id} has been updated to ${newControl.id}`);
+                    logger.debug(`Updated control content: ${JSON.stringify(renamedControlIgnoredFormatting)}`);
                 }
                 else {
                     profileDiff.removedControlIDs.push(diffValue[1]);
@@ -147,4 +187,3 @@ function diffProfile(fromProfile, toProfile, logger) {
     }
     return { ignoreFormattingDiff: profileDiff, rawDiff: originalDiff };
 }
-exports.diffProfile = diffProfile;

package/lib/utilities/diffMarkdown.d.ts

@@ -1,4 +1,17 @@
 import { ProfileDiff } from '../types/diff';
+/**
+ * Generates a markdown representation of the differences between two profiles.
+ *
+ * The function processes the differences to create a renderable data structure
+ * that includes added controls, renamed controls, and updated properties such as
+ * checks, fixes, impacts, titles, and descriptions. It then uses a mustache template
+ * to render the markdown output.
+ *
+ * @param diff - An object containing the differences between two profiles.
+ * @param diff.ignoreFormattingDiff - The profile differences ignoring formatting changes.
+ * @param diff.rawDiff - The raw differences between the profiles.
+ * @returns A string containing the markdown representation of the differences.
+ */
 export declare function createDiffMarkdown(diff: {
     ignoreFormattingDiff: ProfileDiff;
     rawDiff: any;