@mitre/inspec-objects 1.0.1 → 2.0.1

package/lib/parsers/json.js

@@ -1,12 +1,21 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.processInSpecProfile = exports.processExecJSON = exports.processProfileJSON = exports.processEvaluation = void 0;
+exports.processEvaluation = processEvaluation;
+exports.processProfileJSON = processProfileJSON;
+exports.processExecJSON = processExecJSON;
+exports.processInSpecProfile = processInSpecProfile;
 const tslib_1 = require("tslib");
 const inspecjs_1 = require("inspecjs");
 const lodash_1 = tslib_1.__importDefault(require("lodash"));
 const control_1 = tslib_1.__importStar(require("../objects/control"));
 const profile_1 = tslib_1.__importDefault(require("../objects/profile"));
 const update_1 = require("../utilities/update");
+/**
+ * Processes a contextualized evaluation input and converts it into a Profile object.
+ *
+ * @param evaluationInput - The contextualized evaluation input containing profile and control data.
+ * @returns A Profile object populated with the data from the evaluation input.
+ */
 function processEvaluation(evaluationInput) {
     const topLevelProfile = evaluationInput.contains[0];
     const profile = new profile_1.default({
@@ -32,7 +41,12 @@ function processEvaluation(evaluationInput) {
     });
     return profile;
 }
-exports.processEvaluation = processEvaluation;
+/**
+ * Processes a contextualized profile JSON object and converts it into a Profile instance.
+ *
+ * @param profileInput - The contextualized profile input containing profile data and controls.
+ * @returns A Profile instance populated with the data from the input.
+ */
 function processProfileJSON(profileInput) {
     const profile = new profile_1.default({
         name: profileInput.data.name,
@@ -71,11 +85,29 @@ function processProfileJSON(profileInput) {
     });
     return profile;
 }
-exports.processProfileJSON = processProfileJSON;
+/**
+ * Processes the given ExecJSON execution object and returns a Profile.
+ *
+ * This function takes an ExecJSON execution object, contextualizes the evaluation,
+ * and then processes the evaluation to produce a Profile.
+ *
+ * @param execJSON - The ExecJSON execution object to be processed.
+ * @returns The processed Profile.
+ */
 function processExecJSON(execJSON) {
     return processEvaluation((0, inspecjs_1.contextualizeEvaluation)(execJSON));
 }
-exports.processExecJSON = processExecJSON;
+/**
+ * Processes an InSpec profile from a JSON string.
+ *
+ * This function takes 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.
+ *
+ * @param json - The JSON string representing the InSpec profile.
+ * @returns A `Profile` object containing the processed profile data.
+ * @throws Will throw an error if the JSON string does not match known InSpec formats.
+ */
 function processInSpecProfile(json) {
     const convertedFile = (0, inspecjs_1.convertFile)(json, true);
     let profile = new profile_1.default();
@@ -91,4 +123,3 @@ function processInSpecProfile(json) {
     profile.controls = lodash_1.default.sortBy(profile.controls, 'id');
     return profile;
 }
-exports.processInSpecProfile = processInSpecProfile;

package/lib/parsers/oval.d.ts

@@ -1,3 +1,31 @@
 import { OvalDefinitionValue, DefinitionCriterion } from '../types/oval';
+/**
+ * Extracts all test references from a list of initial criteria.
+ *
+ * This function recursively traverses the provided criteria and extracts
+ * all test references (`@_test_ref`) from each criterion. It returns an
+ * array of all found test references.
+ *
+ * @param initialCriteria - An array of `DefinitionCriterion` objects to extract test references from.
+ * @returns An array of strings containing all extracted test references.
+ */
 export declare function extractAllCriteriaRefs(initialCriteria: DefinitionCriterion[]): string[];
+/**
+ * Processes an OVAL (Open Vulnerability and Assessment Language) XML string and converts it into a JSON object.
+ * Extracts definitions and their associated criteria references and resolved values.
+ * The function performs 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.
+ *
+ * The returned record contains:
+ * - The original definition.
+ * - An array of criteria references.
+ * - An array of resolved values, each containing the original criteria, resolved objects, and resolved states.
+ *
+ * @param {string} [oval] - The OVAL XML string to be processed. If not provided, the function returns `undefined`.
+ * @returns {Record<string, OvalDefinitionValue> | undefined} - A record of extracted definitions with their
+ *  criteria references and resolved values, or `undefined` if no OVAL string is provided.
+ */
 export declare function processOVAL(oval?: string): Record<string, OvalDefinitionValue> | undefined;

package/lib/parsers/oval.js

@@ -1,9 +1,23 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.processOVAL = exports.extractAllCriteriaRefs = void 0;
+exports.extractAllCriteriaRefs = extractAllCriteriaRefs;
+exports.processOVAL = processOVAL;
 const xccdf_1 = require("../utilities/xccdf");
 const logging_1 = require("../utilities/logging");
-// https://stackoverflow.com/questions/9133500/how-to-find-a-node-in-a-tree-with-javascript
+/**
+ * Search through all arrays of the tree to find a value from a property
+ * Code provided by:
+ * https://stackoverflow.com/questions/9133500/how-to-find-a-node-in-a-tree-with-javascript
+ *
+ * @param aTree : The tree array
+ * @param fCompair : This function will receive each node. Define based on caller for specific
+                     condition necessary for the match. It must return true if the condition
+                     is matched. Example:
+                        function(oNode){ if(oNode["Name"] === "AA") return true; }
+ * @param bGreedy? : Set to `true` to search all node and not stopping after the first match, default is false
+ * @return An array with references to the nodes for which fCompair was true. In case no node was found an empty array
+ *         will be returned
+*/
 function searchTree(aTree, fCompair, bGreedy) {
     let oNode; // always the current node  
     const aInnerTree = []; // will contain the inner children
@@ -36,6 +50,16 @@ function searchTree(aTree, fCompair, bGreedy) {
     }
     return aReturnNodes;
 }
+/**
+ * Extracts all test references from a list of initial criteria.
+ *
+ * This function recursively traverses the provided criteria and extracts
+ * all test references (`@_test_ref`) from each criterion. It returns an
+ * array of all found test references.
+ *
+ * @param initialCriteria - An array of `DefinitionCriterion` objects to extract test references from.
+ * @returns An array of strings containing all extracted test references.
+ */
 function extractAllCriteriaRefs(initialCriteria) {
     const criteriaRefs = [];
     initialCriteria.forEach(criteria => {
@@ -51,14 +75,31 @@ function extractAllCriteriaRefs(initialCriteria) {
     });
     return criteriaRefs;
 }
-exports.extractAllCriteriaRefs = extractAllCriteriaRefs;
+/**
+ * Processes an OVAL (Open Vulnerability and Assessment Language) XML string and converts it into a JSON object.
+ * Extracts definitions and their associated criteria references and resolved values.
+ * The function performs 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.
+ *
+ * The returned record contains:
+ * - The original definition.
+ * - An array of criteria references.
+ * - An array of resolved values, each containing the original criteria, resolved objects, and resolved states.
+ *
+ * @param {string} [oval] - The OVAL XML string to be processed. If not provided, the function returns `undefined`.
+ * @returns {Record<string, OvalDefinitionValue> | undefined} - A record of extracted definitions with their
+ *  criteria references and resolved values, or `undefined` if no OVAL string is provided.
+ */
 function processOVAL(oval) {
     var _a;
-    const logger = (0, logging_1.createWinstonLogger)();
+    const logger = (0, logging_1.createWinstonLogger)('ts-inspec-objects');
     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) {
@@ -114,4 +155,3 @@ function processOVAL(oval) {
     }
     return extractedDefinitions;
 }
-exports.processOVAL = processOVAL;

package/lib/parsers/xccdf.d.ts

@@ -1,11 +1,46 @@
 import Profile from '../objects/profile';
 import { BenchmarkGroup, BenchmarkRule, RuleComplexCheck } from '../types/xccdf';
 import { OvalDefinitionValue } from '../types/oval';
-export declare type GroupContextualizedRule = BenchmarkRule & {
+export type GroupContextualizedRule = BenchmarkRule & {
     group: Omit<BenchmarkGroup, 'Rule' | 'Group'>;
 };
+/**
+ * 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.
+ */
 export declare function extractAllRules(groups: BenchmarkGroup[]): GroupContextualizedRule[];
+/**
+ * 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.
+ */
 export declare function extractAllComplexChecks(complexCheck: RuleComplexCheck): Omit<RuleComplexCheck, 'complex-check'>[];
+export type InputTextLang = {
+    '#text': string;
+    '@_lang': string;
+};
+/**
+ * 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.
+ */
 export declare function processXCCDF(xml: string, removeNewlines: false, useRuleId: 'group' | 'rule' | 'version' | 'cis', ovalDefinitions?: Record<string, OvalDefinitionValue & {
     criteriaRefs?: string[];
     resolvedValues?: any;