@mitre/hdf-converters 2.12.6 → 2.13.0

package/lib/src/ckl-mapper/checklist-mapper.d.ts

@@ -3,16 +3,50 @@ import { BaseConverter, ILookupPath, MappedTransform } from '../base-converter';
 import { ChecklistJsonixConverter, ChecklistObject } from './checklist-jsonix-converter';
 import { Checklist } from './checklistJsonix';
 export declare function getChecklistObjectFromHdf(hdf: ExecJSON.Execution): ChecklistObject;
+/**
+ * The `ChecklistResults` class extends the `ChecklistJsonixConverter` and is responsible for converting
+ * checklist data between different formats (XML CKL, HDF JSON).
+ *
+ * @extends ChecklistJsonixConverter
+ *
+ * @property {string | ExecJSON.Execution} data - The input data, which can be a string of XML data or an HDF JSON execution object.
+ * @property {Checklist} jsonixData - The JSON representation of the checklist data using the jsonix library.
+ * @property {ChecklistObject} checklistObject - The intermediate object representation of the checklist data.
+ * @property {boolean} withRaw - A flag indicating whether to include raw data in the output.
+ */
 export declare class ChecklistResults extends ChecklistJsonixConverter {
     data: string | ExecJSON.Execution;
     jsonixData: Checklist;
     checklistObject: ChecklistObject;
     withRaw: boolean;
+    /**
+     * @param {string | ExecJSON.Execution} data - The input data, which can be either an HDF JSON object
+     * or an XML CKL string, depending on the direction of the conversion.
+     * @param {boolean} [withRaw=false] - A flag indicating whether to include raw data in the output.
+     * Defaults to false.
+     *
+     * @throws Will throw an error if the asset metadata is invalid.
+     */
     constructor(data: string | ExecJSON.Execution, withRaw?: boolean);
+    /**
+     * @method getJsonix
+     * @returns {Checklist} - Returns the JSON representation of the checklist data.
+     */
     getJsonix(): Checklist;
+    /**
+     * @method toCkl
+     * @returns {string} - Converts JSON data in jsonix format to CKL (Checklist) XML format.
+     */
     toCkl(): string;
+    /**
+     * @method toHdf
+     * @returns {ExecJSON.Execution} - Converts JSON data in intermediate format to HDF (Heimdall Data Format).
+     */
     toHdf(): ExecJSON.Execution;
 }
+/**
+ * Checklist mapper
+ */
 export declare class ChecklistMapper extends BaseConverter {
     withRaw: boolean;
     mappings: MappedTransform<ExecJSON.Execution & {
@@ -20,3 +54,4 @@ export declare class ChecklistMapper extends BaseConverter {
     }, ILookupPath>;
     constructor(checklistObject: ChecklistObject, withRaw?: boolean);
 }
+//# sourceMappingURL=checklist-mapper.d.ts.map

package/lib/src/ckl-mapper/checklist-mapper.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"checklist-mapper.d.ts","sourceRoot":"","sources":["../../../src/ckl-mapper/checklist-mapper.ts"],"names":[],"mappings":"AAAA,OAAO,EAAC,QAAQ,EAAa,MAAM,UAAU,CAAC;AAI9C,OAAO,EACL,aAAa,EAEb,WAAW,EACX,eAAe,EAChB,MAAM,mBAAmB,CAAC;AAG3B,OAAO,EACL,wBAAwB,EACxB,eAAe,EAIhB,MAAM,8BAA8B,CAAC;AACtC,OAAO,EAAC,SAAS,EAAC,MAAM,mBAAmB,CAAC;AAqP5C,wBAAgB,yBAAyB,CACvC,GAAG,EAAE,QAAQ,CAAC,SAAS,GACtB,eAAe,CAKjB;AA0BD;;;;;;;;;;GAUG;AACH,qBAAa,gBAAiB,SAAQ,wBAAwB;IAC5D,IAAI,EAAE,MAAM,GAAG,QAAQ,CAAC,SAAS,CAAC;IAClC,UAAU,EAAE,SAAS,CAAC;IACtB,eAAe,EAAE,eAAe,CAAC;IACjC,OAAO,EAAE,OAAO,CAAC;IAEjB;;;;;;;OAOG;gBACS,IAAI,EAAE,MAAM,GAAG,QAAQ,CAAC,SAAS,EAAE,OAAO,UAAQ;IAqB9D;;;OAGG;IACH,SAAS,IAAI,SAAS;IAItB;;;OAGG;IACH,KAAK,IAAI,MAAM;IASf;;;OAGG;IACH,KAAK,IAAI,QAAQ,CAAC,SAAS;CA8B5B;AAED;;GAEG;AACH,qBAAa,eAAgB,SAAQ,aAAa;IAChD,OAAO,EAAE,OAAO,CAAC;IACjB,QAAQ,EAAE,eAAe,CACvB,QAAQ,CAAC,SAAS,GAAG;QAAC,WAAW,EAAE,OAAO,CAAA;KAAC,EAC3C,WAAW,CACZ,CAsKC;gBAEU,eAAe,EAAE,eAAe,EAAE,OAAO,UAAQ;CAI9D"}

package/lib/src/ckl-mapper/checklist-mapper.js

@@ -3,7 +3,8 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.ChecklistMapper = exports.ChecklistResults = exports.getChecklistObjectFromHdf = void 0;
+exports.ChecklistMapper = exports.ChecklistResults = void 0;
+exports.getChecklistObjectFromHdf = getChecklistObjectFromHdf;
 const inspecjs_1 = require("inspecjs");
 const lodash_1 = __importDefault(require("lodash"));
 const xml_formatter_1 = __importDefault(require("xml-formatter"));
@@ -22,13 +23,33 @@ var ImpactMapping;
     ImpactMapping[ImpactMapping["low"] = 0.3] = "low";
 })(ImpactMapping || (ImpactMapping = {}));
 const CCI_NIST_TWO_WAY_MAPPER = new CciNistMapping_1.CciNistTwoWayMapper();
+/**
+ * Tranformer function that splits a string and return array
+ * @param input - string of CCI references
+ * @returns ref - array of CCI references
+ */
 function cciRef(input) {
     return input.split('; ');
 }
+/**
+ * Transformer function that splits string and maps resulting array
+ * into NIST control tags
+ * @param input - string of CCI references
+ * @returns tag - array of NIST Control Tags
+ */
 function nistTag(input) {
     const identifiers = cciRef(input);
     return CCI_NIST_TWO_WAY_MAPPER.nistFilter(identifiers, global_1.DEFAULT_STATIC_CODE_ANALYSIS_NIST_TAGS);
 }
+/**
+ * Inner function to find the severity of the vuln
+ * Does not account for severity override, so this should
+ * not be taken as the final severity value
+ * Uses thirdPartyTools.hdfExistingData.severity first,
+ * then falls back to checklist severity tag
+ * @param vuln - checklist vulnerability object
+ * @returns - severity
+ */
 function findSeverity(vuln) {
     let severity = vuln.severity;
     const hdfExistingData = (0, parseJson_1.parseJson)(vuln.thirdPartyTools);
@@ -37,6 +58,13 @@ function findSeverity(vuln) {
     }
     return severity;
 }
+/**
+ * Inner function to find the severityoverride of the vuln
+ * Uses thirdPartyTools.hdfExistingData.severityoverride first,
+ * then falls back to checklist severityoverride tag
+ * @param vuln - checklist vulnerability object
+ * @returns - severityoverride
+ */
 function findSeverityOverride(vuln) {
     let severityOverride = vuln.severityoverride;
     const hdfExistingData = (0, parseJson_1.parseJson)(vuln.thirdPartyTools);
@@ -45,6 +73,14 @@ function findSeverityOverride(vuln) {
     }
     return severityOverride;
 }
+/**
+ * Function to find the computed severity of the given vuln
+ * with order of precedence as:
+ * thirdPartyTools.hdfSpecificData.severityoverride, severityoverride,
+ * thidPartyTools.hdfSpecificData.severity, severity
+ * @param vuln - checklist vulnerability object
+ * @returns severity - string none, low, medium, high, critical
+ */
 function computeSeverity(vuln) {
     const severity = findSeverity(vuln);
     const severityOverride = findSeverityOverride(vuln);
@@ -55,6 +91,12 @@ function computeSeverity(vuln) {
         throw new Error(`Severity "${computed}" does not match none, low, medium, high, or critical, please check severity for ${vuln.vulnNum}`);
     return computed;
 }
+/**
+ * Transformer function that checks if the status is 'Not Applicable' returning a 0.
+ * Otherwise, maps computed severity to ImpactMapping
+ * @param vuln - checklist vulnerability object
+ * @returns impact - number
+ */
 function transformImpact(vuln) {
     if (vuln.status === 'Not Applicable')
         return 0.0;
@@ -70,6 +112,13 @@ function transformImpact(vuln) {
         throw new Error(`Severity "${severity}" does not match low, medium, or high, please check severity for ${vuln.vulnNum}`);
     return impact;
 }
+/**
+ * Transformer function that returns appropriate enum value based on param
+ * This is required because the status value of the ControlResult object
+ * must be an ExecJSON.ControlResultStatus type
+ * @param input - string
+ * @returns enum ExecJSON.ControlResultStatus
+ */
 function getStatus(input) {
     const status = input.toLowerCase();
     switch (status) {
@@ -93,11 +142,19 @@ function checkMessage(typeCheck, messageType, message) {
         return null;
     }
 }
+/**
+ * Transformer function that uses current heimdall checklist export syntax for
+ * findingDetails attribute to separate a single string into multiple
+ * result objects
+ * @param input - array of one element consisting of {code_desc, status, start_time}
+ * @returns ExecJSON.ControlResult
+ */
 function parseFindingDetails(input) {
     const findings = input;
     const results = [];
     const findingDetails = findings[0].code_desc;
     const regex = /^(failed|passed|skipped|error) :: TEST (.*?)(?: :: (MESSAGE|SKIP_MESSAGE) (.*?))?$/s;
+    // check if code_desc is empty or does not match the above regular expression
     if (!RegExp(regex).exec(findingDetails)) {
         return [
             {
@@ -108,7 +165,13 @@ function parseFindingDetails(input) {
         ];
     }
     else {
+        // split into multiple findings details using heimdall2 CKLExport functionality
         for (const details of findingDetails.split('\n--------------------------------\n')) {
+            // regex of four groups (five if you count the full match) consisting of the four possible status
+            // followed by any number of characters after :: TEST which represents the code_desc
+            // followed by an optionally :: MESSAGE or SKIP_MESSAGE representing the message type
+            // followed by any number of characters representing the message
+            // split details for status
             const match = regex.exec(details.trim());
             if (match) {
                 const [, mStatus, mCode_dec, messageType, mMessage] = match;
@@ -161,7 +224,9 @@ function getChecklistObjectFromHdf(hdf) {
     }
     return lodash_1.default.get(hdf, 'passthrough.checklist', checklist_jsonix_converter_1.EmptyChecklistObject);
 }
-exports.getChecklistObjectFromHdf = getChecklistObjectFromHdf;
+// baseconverter makes it difficult to assign an array to attributes using just path+transformer in this case because i think it gets instantly redirected along the 'isString' pathway due to the path pointing at a stringified json blob
+// consequently we have to use the arraytransformer, but that doesn't run if we provide a path at the top level of the object for the same reason as specified above, so we have to put the 'hdfSpecificData' object into the subobject 'data'
+// which we can then extract here
 function getAttributes(input) {
     const passthrough = input;
     const data = passthrough[0].data;
@@ -181,7 +246,30 @@ function getHdfSpecificDataAttribute(attribute, input) {
         return undefined;
     return lodash_1.default.get(hdfSpecificData, attribute);
 }
+/**
+ * The `ChecklistResults` class extends the `ChecklistJsonixConverter` and is responsible for converting
+ * checklist data between different formats (XML CKL, HDF JSON).
+ *
+ * @extends ChecklistJsonixConverter
+ *
+ * @property {string | ExecJSON.Execution} data - The input data, which can be a string of XML data or an HDF JSON execution object.
+ * @property {Checklist} jsonixData - The JSON representation of the checklist data using the jsonix library.
+ * @property {ChecklistObject} checklistObject - The intermediate object representation of the checklist data.
+ * @property {boolean} withRaw - A flag indicating whether to include raw data in the output.
+ */
 class ChecklistResults extends checklist_jsonix_converter_1.ChecklistJsonixConverter {
+    data;
+    jsonixData;
+    checklistObject;
+    withRaw;
+    /**
+     * @param {string | ExecJSON.Execution} data - The input data, which can be either an HDF JSON object
+     * or an XML CKL string, depending on the direction of the conversion.
+     * @param {boolean} [withRaw=false] - A flag indicating whether to include raw data in the output.
+     * Defaults to false.
+     *
+     * @throws Will throw an error if the asset metadata is invalid.
+     */
     constructor(data, withRaw = false) {
         super(jsonixMapping_1.jsonixMapping);
         this.data = data;
@@ -196,18 +284,31 @@ class ChecklistResults extends checklist_jsonix_converter_1.ChecklistJsonixConve
             this.jsonixData = super.fromIntermediateObject(this.checklistObject);
         }
         else {
+            // CREATE Intermediate Object from HDF
             this.checklistObject = super.hdfToIntermediateObject(data);
             (0, checklist_metadata_utils_1.throwIfInvalidAssetMetadata)(this.checklistObject.asset);
             this.jsonixData = super.fromIntermediateObject(this.checklistObject);
         }
         this.withRaw = withRaw;
     }
+    /**
+     * @method getJsonix
+     * @returns {Checklist} - Returns the JSON representation of the checklist data.
+     */
     getJsonix() {
         return this.jsonixData;
     }
+    /**
+     * @method toCkl
+     * @returns {string} - Converts JSON data in jsonix format to CKL (Checklist) XML format.
+     */
     toCkl() {
         return (0, xml_formatter_1.default)(`<?xml version="1.0" encoding="UTF-8"?><!--Heimdall Version :: ${package_json_1.version}-->${super.fromJsonix(this.jsonixData)}`, { lineSeparator: '\n', collapseContent: true, indentation: '\t' });
     }
+    /**
+     * @method toHdf
+     * @returns {ExecJSON.Execution} - Converts JSON data in intermediate format to HDF (Heimdall Data Format).
+     */
     toHdf() {
         const numberOfStigs = this.checklistObject.stigs.length;
         if (numberOfStigs === 1) {
@@ -241,165 +342,175 @@ class ChecklistResults extends checklist_jsonix_converter_1.ChecklistJsonixConve
     }
 }
 exports.ChecklistResults = ChecklistResults;
+/**
+ * Checklist mapper
+ */
 class ChecklistMapper extends base_converter_1.BaseConverter {
-    constructor(checklistObject, withRaw = false) {
-        super(checklistObject);
-        this.mappings = {
-            platform: {
-                name: 'Heimdall Tools',
-                release: package_json_1.version
-            },
-            version: package_json_1.version,
-            statistics: {},
-            profiles: [
-                {
-                    path: 'stigs',
-                    name: { path: 'header.stigid' },
-                    version: {
-                        path: 'header',
-                        transformer: (input) => {
-                            const ret = getHdfSpecificDataAttribute('version', input.customname) ||
-                                input.version;
-                            return ret;
-                        }
-                    },
-                    title: { path: 'header.title' },
-                    maintainer: {
-                        path: 'header.customname',
-                        transformer: lodash_1.default.partial(getHdfSpecificDataAttribute, 'maintainer')
-                    },
-                    summary: { path: 'header.description' },
-                    license: { path: 'header.notice' },
-                    copyright: {
-                        path: 'header.customname',
-                        transformer: lodash_1.default.partial(getHdfSpecificDataAttribute, 'copyright')
-                    },
-                    copyright_email: {
-                        path: 'header.customname',
-                        transformer: lodash_1.default.partial(getHdfSpecificDataAttribute, 'copyright_email')
-                    },
-                    supports: [],
-                    attributes: [
-                        {
-                            arrayTransformer: getAttributes,
-                            data: { path: 'header.customname' }
-                        }
-                    ],
-                    groups: [],
-                    status: 'loaded',
-                    controls: [
-                        {
-                            path: 'vulns',
-                            key: 'id',
-                            tags: {
-                                gtitle: { path: 'groupTitle' },
-                                rid: { path: 'ruleId' },
-                                gid: { path: 'vulnNum' },
-                                stig_id: { path: 'ruleVer' },
-                                cci: {
-                                    path: 'cciRef',
-                                    transformer: cciRef
-                                },
-                                nist: {
-                                    path: 'cciRef',
-                                    transformer: nistTag
-                                },
-                                severity: {
-                                    transformer: findSeverity
-                                },
-                                weight: { path: 'weight' },
-                                transformer: (input) => {
-                                    const tags = [
-                                        ['IA_Controls', 'iaControls'],
-                                        ['Legacy_ID', 'legacyId'],
-                                        ['False_Positives', 'falsePositives'],
-                                        ['False_Negatives', 'falseNegatives'],
-                                        ['Mitigations', 'mitigations'],
-                                        ['Mitigation_Controls', 'mitigationControl'],
-                                        ['Potential_Impact', 'potentialImpact'],
-                                        ['Responsibility', 'responsibility'],
-                                        ['STIGRef', 'stigRef'],
-                                        ['Security_Override_Guidance', 'securityOverrideGuidance'],
-                                        ['severityjustification', 'severityjustification']
-                                    ];
-                                    const fullTags = {};
-                                    for (const [key, path] of tags) {
-                                        const tagValue = lodash_1.default.get(input, path);
-                                        if (tagValue && tagValue !== '; ') {
-                                            fullTags[key] = tagValue;
-                                        }
-                                    }
-                                    const severityOverride = findSeverityOverride(input);
-                                    if (severityOverride) {
-                                        fullTags['severityoverride'] = severityOverride;
-                                    }
-                                    return fullTags;
-                                }
+    withRaw;
+    mappings = {
+        platform: {
+            name: 'Heimdall Tools',
+            release: package_json_1.version
+        },
+        version: package_json_1.version,
+        statistics: {},
+        profiles: [
+            {
+                path: 'stigs',
+                name: { path: 'header.stigid' },
+                version: {
+                    path: 'header',
+                    transformer: (input) => {
+                        const ret = getHdfSpecificDataAttribute('version', input.customname) ||
+                            input.version;
+                        return ret;
+                    }
+                },
+                title: { path: 'header.title' },
+                maintainer: {
+                    path: 'header.customname',
+                    transformer: lodash_1.default.partial(getHdfSpecificDataAttribute, 'maintainer')
+                },
+                summary: { path: 'header.description' },
+                license: { path: 'header.notice' },
+                copyright: {
+                    path: 'header.customname',
+                    transformer: lodash_1.default.partial(getHdfSpecificDataAttribute, 'copyright')
+                },
+                copyright_email: {
+                    path: 'header.customname',
+                    transformer: lodash_1.default.partial(getHdfSpecificDataAttribute, 'copyright_email')
+                },
+                supports: [],
+                attributes: [
+                    {
+                        arrayTransformer: getAttributes,
+                        data: { path: 'header.customname' }
+                    }
+                ],
+                groups: [],
+                status: 'loaded',
+                controls: [
+                    {
+                        path: 'vulns',
+                        key: 'id',
+                        tags: {
+                            gtitle: { path: 'groupTitle' },
+                            rid: { path: 'ruleId' },
+                            gid: { path: 'vulnNum' },
+                            stig_id: { path: 'ruleVer' },
+                            cci: {
+                                path: 'cciRef',
+                                transformer: cciRef
                             },
-                            refs: [],
-                            source_location: {},
-                            title: { path: 'ruleTitle' },
-                            id: { path: 'vulnNum' },
-                            desc: { path: 'vulnDiscuss' },
-                            descriptions: [
-                                {
-                                    data: { path: 'checkContent' },
-                                    label: 'check'
-                                },
-                                {
-                                    data: { path: 'fixText' },
-                                    label: 'fix'
-                                },
-                                {
-                                    arrayTransformer: parseComments,
-                                    data: { path: 'comments' },
-                                    label: 'comments'
-                                }
-                            ],
-                            impact: {
-                                transformer: transformImpact
+                            nist: {
+                                path: 'cciRef',
+                                transformer: nistTag
+                            },
+                            severity: {
+                                transformer: findSeverity
                             },
-                            code: {
-                                transformer: (vulnerability) => {
-                                    const data = (0, parseJson_1.parseJson)(vulnerability.thirdPartyTools);
-                                    if (data.ok) {
-                                        const code = lodash_1.default.get(data.value, 'hdfSpecificData.code');
-                                        if (code)
-                                            return code;
+                            weight: { path: 'weight' },
+                            // following transform takes the available attributes found in a checklist vuln and if available will add to the tags.
+                            // first element is the label name as it will appear in UI while the second is the ChecklistObject keyname
+                            transformer: (input) => {
+                                const tags = [
+                                    ['IA_Controls', 'iaControls'],
+                                    ['Legacy_ID', 'legacyId'],
+                                    ['False_Positives', 'falsePositives'],
+                                    ['False_Negatives', 'falseNegatives'],
+                                    ['Mitigations', 'mitigations'],
+                                    ['Mitigation_Controls', 'mitigationControl'],
+                                    ['Potential_Impact', 'potentialImpact'],
+                                    ['Responsibility', 'responsibility'],
+                                    ['STIGRef', 'stigRef'],
+                                    ['Security_Override_Guidance', 'securityOverrideGuidance'],
+                                    // does not follow above naming convention
+                                    // because it could be used in other converters
+                                    ['severityjustification', 'severityjustification']
+                                ];
+                                const fullTags = {};
+                                for (const [key, path] of tags) {
+                                    const tagValue = lodash_1.default.get(input, path);
+                                    if (tagValue && tagValue !== '; ') {
+                                        fullTags[key] = tagValue;
                                     }
-                                    return JSON.stringify(vulnerability, null, 2);
                                 }
+                                // another special case that does
+                                // not follow above naming conventions
+                                const severityOverride = findSeverityOverride(input);
+                                if (severityOverride) {
+                                    fullTags['severityoverride'] = severityOverride;
+                                }
+                                return fullTags;
+                            }
+                        },
+                        refs: [],
+                        source_location: {},
+                        title: { path: 'ruleTitle' },
+                        id: { path: 'vulnNum' },
+                        desc: { path: 'vulnDiscuss' },
+                        descriptions: [
+                            {
+                                data: { path: 'checkContent' },
+                                label: 'check'
                             },
-                            results: [
-                                {
-                                    arrayTransformer: parseFindingDetails,
-                                    status: {
-                                        path: 'status',
-                                        transformer: getStatus
-                                    },
-                                    code_desc: { path: 'findingdetails' },
-                                    start_time: ''
+                            {
+                                data: { path: 'fixText' },
+                                label: 'fix'
+                            },
+                            {
+                                arrayTransformer: parseComments,
+                                data: { path: 'comments' },
+                                label: 'comments'
+                            }
+                        ],
+                        impact: {
+                            transformer: transformImpact
+                        },
+                        code: {
+                            transformer: (vulnerability) => {
+                                const data = (0, parseJson_1.parseJson)(vulnerability.thirdPartyTools);
+                                if (data.ok) {
+                                    const code = lodash_1.default.get(data.value, 'hdfSpecificData.code');
+                                    if (code)
+                                        return code;
                                 }
-                            ]
-                        }
-                    ],
-                    sha256: ''
-                }
-            ],
-            passthrough: {
-                transformer: (data) => {
-                    return {
-                        ...{
-                            checklist: {
-                                asset: data.asset,
-                                stigs: data.stigs
+                                return JSON.stringify(vulnerability, null, 2);
                             }
                         },
-                        ...(this.withRaw && { raw: data.jsonixData })
-                    };
-                }
+                        results: [
+                            {
+                                arrayTransformer: parseFindingDetails,
+                                status: {
+                                    path: 'status',
+                                    transformer: getStatus
+                                },
+                                code_desc: { path: 'findingdetails' },
+                                start_time: ''
+                            }
+                        ]
+                    }
+                ],
+                sha256: ''
+            }
+        ],
+        passthrough: {
+            transformer: (data) => {
+                return {
+                    ...{
+                        checklist: {
+                            asset: data.asset,
+                            stigs: data.stigs
+                        }
+                    },
+                    ...(this.withRaw && { raw: data.jsonixData })
+                };
             }
-        };
+        }
+    };
+    constructor(checklistObject, withRaw = false) {
+        super(checklistObject);
         this.withRaw = withRaw;
     }
 }