@mitre/inspec-objects 1.0.1 → 2.0.1

package/lib/utilities/xccdf.d.ts

@@ -1,7 +1,127 @@
 import { DecodedDescription } from '../types/xccdf';
-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 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:
+ * - 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 '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}
+ */
+/**
+ * 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.
+ *
+ * @param data - The JSON object to be converted.
+ * @returns The XML string representation of the JSON object.
+ */
 export declare function convertJsonIntoXML(data: any): string;
+/**
+ * Removes XML special characters from a given string.
+ *
+ * This function decodes any XML special characters in the input string
+ * and returns the decoded result.
+ *
+ * @param str - The input string containing XML special characters.
+ * @returns The decoded string with XML special characters removed.
+ */
 export declare function removeXMLSpecialCharacters(str: string): string;
-export declare function severityStringToImpact(string: string, id: string): number;
+/**
+ * Removes HTML tags from the given input string.
+ *
+ * @param input - The string from which HTML tags should be removed.
+ * @returns A new string with all HTML tags removed.
+ */
+export declare function removeHtmlTags(input: string): string;
+/**
+ * Converts a severity string to a numerical impact value.
+ *
+ * The function matches the input string against various regular expressions
+ * to determine the corresponding impact value:
+ * - "none", "na", "n/a", "not applicable" (case insensitive) -> 0.0
+ * - "low", "category iii", "category 3" (case insensitive) -> 0.3
+ * - "medium", "category ii", "category 2" -> 0.5
+ * - "high", "category i", "category 1" -> 0.7
+ * - "critical", "severe" -> 1.0
+ *
+ * If no match is found, the default impact value is 0.5.
+ *
+ * @param string - The severity string to be converted.
+ * @returns The numerical impact value corresponding to the severity string.
+ */
+export declare function severityStringToImpact(string: string): number;
+/**
+ * Converts an impact number to a severity string.
+ *
+ * @param impact - A number representing the impact, which must be between 0.0 and 1.0 inclusive.
+ * @returns A string representing the severity level:
+ * - 'critical' for impact >= 0.9
+ * - 'high' for impact >= 0.7
+ * - 'medium' for impact >= 0.4
+ * - 'low' for impact >= 0.1
+ * - 'none' for impact < 0.1
+ * @throws {Error} If the impact is less than 0.0 or greater than 1.0.
+ */
 export declare function impactNumberToSeverityString(impact: number): string;
+/**
+ * Converts an encoded HTML string into a JSON object, handling specific edge
+ * cases related to XSS and XML tags.
+ *
+ * This function performs the following steps:
+ * 1. Replaces occurrences of `"&lt;"` with a placeholder to avoid
+ *    breaking parsing.
+ * 2. Parses the patched HTML to extract text chunks.
+ * 3. Converts the extracted text chunks into JSON.
+ * 4. Cleans the converted JSON by replacing placeholders with the original
+ *    characters and handling nested objects.
+ *
+ * Note: This function specifically addresses issues found in certain
+ *       STIGs (Security Technical Implementation Guides) where XML tags are
+ *       embedded within text fields.
+ *
+ * @param encodedHTML - The encoded HTML string to be converted.
+ *                      If not provided, an empty object is returned.
+ * @returns A `DecodedDescription` object containing the converted JSON data.
+ */
 export declare function convertEncodedHTMLIntoJson(encodedHTML?: string): DecodedDescription;

package/lib/utilities/xccdf.js

@@ -1,51 +1,178 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.convertEncodedHTMLIntoJson = exports.impactNumberToSeverityString = exports.severityStringToImpact = exports.removeXMLSpecialCharacters = exports.convertJsonIntoXML = exports.convertEncodedXmlIntoJson = void 0;
+exports.convertEncodedXmlIntoJson = convertEncodedXmlIntoJson;
+exports.convertJsonIntoXML = convertJsonIntoXML;
+exports.removeXMLSpecialCharacters = removeXMLSpecialCharacters;
+exports.removeHtmlTags = removeHtmlTags;
+exports.severityStringToImpact = severityStringToImpact;
+exports.impactNumberToSeverityString = impactNumberToSeverityString;
+exports.convertEncodedHTMLIntoJson = convertEncodedHTMLIntoJson;
 const tslib_1 = require("tslib");
-const fast_xml_parser_1 = tslib_1.__importDefault(require("fast-xml-parser"));
+const fast_xml_parser_1 = require("fast-xml-parser");
 const jstoxml_1 = require("jstoxml");
 const htmlparser = tslib_1.__importStar(require("htmlparser2"));
 const lodash_1 = tslib_1.__importDefault(require("lodash"));
 const he_1 = tslib_1.__importDefault(require("he"));
-function convertEncodedXmlIntoJson(encodedXml) {
-    return fast_xml_parser_1.default.parse(encodedXml, {
+/**
+ * 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 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:
+ * - 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 '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}
+ */
+/**
+ * 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'],
+        isArray: () => true,
+    };
+    const withArrayNoEntitiesOption = {
+        processEntities: true,
         ignoreAttributes: false,
-        ignoreNameSpace: true,
+        removeNSPrefix: true,
         attributeNamePrefix: '@_',
-        stopNodes: ['div', 'p'],
-        arrayMode: true
-    });
+        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);
 }
-exports.convertEncodedXmlIntoJson = convertEncodedXmlIntoJson;
+/**
+ * Converts a JSON object into an XML string.
+ *
+ * @param data - The JSON object to be converted.
+ * @returns The XML string representation of the JSON object.
+ */
 function convertJsonIntoXML(data) {
     return (0, jstoxml_1.toXML)(data);
 }
-exports.convertJsonIntoXML = convertJsonIntoXML;
+/**
+ * Removes XML special characters from a given string.
+ *
+ * This function decodes any XML special characters in the input string
+ * and returns the decoded result.
+ *
+ * @param str - The input string containing XML special characters.
+ * @returns The decoded string with XML special characters removed.
+ */
 function removeXMLSpecialCharacters(str) {
-    return he_1.default.decode(str);
+    const result = he_1.default.decode(str);
+    return result;
 }
-exports.removeXMLSpecialCharacters = removeXMLSpecialCharacters;
-function severityStringToImpact(string, id) {
+/**
+ * Removes HTML tags from the given input string.
+ *
+ * @param input - The string from which HTML tags should be removed.
+ * @returns A new string with all HTML tags removed.
+ */
+function removeHtmlTags(input) {
+    return input.replace(/<\/?[^>]+(>|$)/g, '');
+}
+/**
+ * Converts a severity string to a numerical impact value.
+ *
+ * The function matches the input string against various regular expressions
+ * to determine the corresponding impact value:
+ * - "none", "na", "n/a", "not applicable" (case insensitive) -> 0.0
+ * - "low", "category iii", "category 3" (case insensitive) -> 0.3
+ * - "medium", "category ii", "category 2" -> 0.5
+ * - "high", "category i", "category 1" -> 0.7
+ * - "critical", "severe" -> 1.0
+ *
+ * If no match is found, the default impact value is 0.5.
+ *
+ * @param string - The severity string to be converted.
+ * @returns The numerical impact value corresponding to the severity string.
+ */
+function severityStringToImpact(string) {
     var _a, _b, _c, _d, _e;
-    if ((_a = string.match(/none|na|n\/a|not[\s()*_|]?applicable/i)) === null || _a === void 0 ? void 0 : _a.length) {
+    if ((_a = RegExp(/none|na|n\/a|not[\s()*_|]?applicable/i).exec(string)) === null || _a === void 0 ? void 0 : _a.length) {
         return 0.0;
     }
-    if ((_b = string.match(/low|cat(egory)?\s*(iii|3)/i)) === null || _b === void 0 ? void 0 : _b.length) {
+    if ((_b = RegExp(/low|cat(egory)?\s*(iii|3)/i).exec(string)) === null || _b === void 0 ? void 0 : _b.length) {
         return 0.3;
     }
-    if ((_c = string.match(/med(ium)?|cat(egory)?\s*(ii|2)/)) === null || _c === void 0 ? void 0 : _c.length) {
+    if ((_c = RegExp(/med(ium)?|cat(egory)?\s*(ii|2)/).exec(string)) === null || _c === void 0 ? void 0 : _c.length) {
         return 0.5;
     }
-    if ((_d = string.match(/high|cat(egory)?\s*(i|1)/)) === null || _d === void 0 ? void 0 : _d.length) {
+    if ((_d = RegExp(/high|cat(egory)?\s*(i|1)/).exec(string)) === null || _d === void 0 ? void 0 : _d.length) {
         return 0.7;
     }
-    if ((_e = string.match(/crit(ical)?|severe/)) === null || _e === void 0 ? void 0 : _e.length) {
+    if ((_e = RegExp(/crit(ical)?|severe/).exec(string)) === null || _e === void 0 ? void 0 : _e.length) {
         return 1.0;
     }
-    console.log(`${string} is not a valid severity value. It should be one of the approved keywords. ${id} will be treated as medium severity`);
     return 0.5;
 }
-exports.severityStringToImpact = severityStringToImpact;
+/**
+ * Converts an impact number to a severity string.
+ *
+ * @param impact - A number representing the impact, which must be between 0.0 and 1.0 inclusive.
+ * @returns A string representing the severity level:
+ * - 'critical' for impact >= 0.9
+ * - 'high' for impact >= 0.7
+ * - 'medium' for impact >= 0.4
+ * - 'low' for impact >= 0.1
+ * - 'none' for impact < 0.1
+ * @throws {Error} If the impact is less than 0.0 or greater than 1.0.
+ */
 function impactNumberToSeverityString(impact) {
     // Impact must be 0.0 - 1.0
     if (impact < 0.0 || impact > 1.0) {
@@ -67,7 +194,26 @@ function impactNumberToSeverityString(impact) {
         return 'none';
     }
 }
-exports.impactNumberToSeverityString = impactNumberToSeverityString;
+/**
+ * Converts an encoded HTML string into a JSON object, handling specific edge
+ * cases related to XSS and XML tags.
+ *
+ * This function performs the following steps:
+ * 1. Replaces occurrences of `"&lt;"` with a placeholder to avoid
+ *    breaking parsing.
+ * 2. Parses the patched HTML to extract text chunks.
+ * 3. Converts the extracted text chunks into JSON.
+ * 4. Cleans the converted JSON by replacing placeholders with the original
+ *    characters and handling nested objects.
+ *
+ * Note: This function specifically addresses issues found in certain
+ *       STIGs (Security Technical Implementation Guides) where XML tags are
+ *       embedded within text fields.
+ *
+ * @param encodedHTML - The encoded HTML string to be converted.
+ *                      If not provided, an empty object is returned.
+ * @returns A `DecodedDescription` object containing the converted JSON data.
+ */
 function convertEncodedHTMLIntoJson(encodedHTML) {
     if (encodedHTML) {
         // Some STIGs regarding XSS put the < character inside of the description which breaks parsing
@@ -80,11 +226,17 @@ function convertEncodedHTMLIntoJson(encodedHTML) {
         });
         htmlParser.write(patchedHTML);
         htmlParser.end();
-        const converted = convertEncodedXmlIntoJson(xmlChunks.join(''));
+        const converted = convertEncodedXmlIntoJson(xmlChunks.join(''), 'noArrayOption');
         let cleaned = {};
-        if (typeof converted.VulnDiscussion === 'object') { // 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
+        // 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
+        if (typeof converted.VulnDiscussion === 'object') {
             let extractedVulnDescription = '';
-            const remainingFields = lodash_1.default.omit(converted.VulnDiscussion, ['FalsePositives', 'FalseNegatives', 'Documentable', 'Mitigations', 'SeverityOverrideGuidance', 'PotentialImpacts', 'ThirdPartyTools', 'MitigationControl', 'Responsibility', 'IAControls']);
+            const remainingFields = lodash_1.default.omit(converted.VulnDiscussion, [
+                'FalsePositives', 'FalseNegatives', 'Documentable', 'Mitigations',
+                'SeverityOverrideGuidance', 'PotentialImpacts', 'ThirdPartyTools',
+                'MitigationControl', 'Responsibility', 'IAControls'
+            ]);
             Object.entries(remainingFields).forEach(([field, value]) => {
                 extractedVulnDescription += `<${field}> ${value}`;
             });
@@ -114,4 +266,3 @@ function convertEncodedHTMLIntoJson(encodedHTML) {
     }
     return {};
 }
-exports.convertEncodedHTMLIntoJson = convertEncodedHTMLIntoJson;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mitre/inspec-objects",
-  "version": "1.0.1",
+  "version": "2.0.1",
   "description": "Typescript objects for normalizing between InSpec profiles and XCCDF benchmarks",
   "main": "lib/index.js",
   "publishConfig": {
@@ -24,36 +24,36 @@
   },
   "homepage": "https://github.com/mitre/ts-inspec-objects#readme",
   "dependencies": {
-    "@types/flat": "^5.0.2",
+    "@types/flat": "5.0.2",
     "@types/he": "^1.1.2",
-    "@types/json-diff": "^0.7.0",
+    "@types/json-diff": "^1.0.0",
     "@types/jstoxml": "^2.0.2",
     "@types/lodash": "^4.14.178",
     "@types/mustache": "^4.2.0",
     "@types/pretty": "^2.0.1",
-    "fast-xml-parser": "^3.1.19",
-    "flat": "^5.0.2",
+    "fast-xml-parser": "^4.5.1",
+    "flat": "5.0.2",
     "he": "^1.2.0",
-    "htmlparser2": "^7.2.0",
+    "htmlparser2": "^10.0.0",
     "inspecjs": "^2.6.6",
-    "jest": "^28.1.1",
-    "json-diff": "^0.9.0",
-    "jstoxml": "^3.2.3",
+    "json-diff": "^1.0.6",
+    "jstoxml": "^5.0.2",
     "lodash": "^4.17.21",
     "mustache": "^4.2.0",
     "pretty": "^2.0.0",
-    "ts-jest": "^28.0.4",
-    "typescript": "^4.5.5",
     "winston": "^3.8.1",
-    "yaml": "^1.10.2"
+    "yaml": "^2.3.1"
   },
   "devDependencies": {
-    "@types/jest": "^28.1.1",
-    "@types/node": "^17.0.18",
-    "@typescript-eslint/eslint-plugin": "^5.47.0",
-    "@typescript-eslint/parser": "^5.47.0",
+    "@types/jest": "^29.5.12",
+    "@types/node": "^22.5.2",
+    "@typescript-eslint/eslint-plugin": "^6.4.1",
+    "@typescript-eslint/parser": "^6.0.0",
     "eslint": "^8.30.0",
-    "tslib": "^2.4.0"
+    "jest": "^29.7.0",
+    "ts-jest": "^29.1.1",
+    "tslib": "^2.4.0",
+    "typescript": "^5.2.2"
   },
   "jest": {
     "rootDir": ".",