@mitre/inspec-objects 1.0.1 → 2.0.0

package/.github/dependabot.yml

@@ -0,0 +1,11 @@
+version: 2
+updates:
+
+  # Maintain dependencies for npm
+  - package-ecosystem: "npm"
+    directory: "/"
+    schedule:
+      interval: daily
+      time: "20:00"
+      timezone: America/New_York
+    open-pull-requests-limit: 99

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

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

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

@@ -1,5 +1,4 @@
 name: Run TS-InSpec-Objects E2E Tests
-
 on:
   push:
     branches: [ main ]
@@ -7,6 +6,7 @@ on:
 
 jobs:
   build:
+    name: Run TS-InSpec-Objects E2E Tests
     runs-on: ubuntu-20.04
 
     steps:

package/.github/workflows/linter.yml

@@ -1,6 +1,4 @@
-
 name: Lint TS-InSpec-Objects
-
 on:
   push:
     branches: [ main ]
@@ -8,6 +6,7 @@ on:
 
 jobs:
   build:
+    name: Lint TS-InSpec-Objects
     runs-on: ubuntu-20.04
 
     steps:

package/README.md

@@ -49,17 +49,58 @@ Here are some formatting choices that are being made.
   <img src="images/Delta_Process.jpg" alt="Delta and Stub Generation Process" title="Delta and Stub Generation Process">
 </div>
 
-### NOTICE
+## Development Environment Configuration
+### Installation
+To install the project, clone the repository and install the dependencies:
+```bash
+# SSH
+git clone git@github.com:mitre/ts-inspec-objects.git 
+# HTTPS
+git clone https://github.com/mitre/ts-inspec-objects.git
+
+cd project
+npm install
+```
+
+### Compile the project
+Use the `build` script command to generate the executable libraries:
+```bash
+npm run build
+```
+
+### Linting the code
+Use either the `lint` or `lint:ci` command to invoke the linter:
+```bash
+# Auto fix
+npm run lint
+
+# Display linting findings
+npm run lint:ci
+```
+
+### Run the Test Suite
+Use the `test` script command to run all tests contained in the tests directory:
+
+```bash
+npm run test
+```
+
+### Run a Specific Test
+To run a specific test use the `npx jest --findRelatedTests` command:
+```bash
+npx jest --findRelatedTests <test\testName.ts>
+```
+## NOTICE
 
-© 2018-2022 The MITRE Corporation.
+© 2018-2025 The MITRE Corporation.
 
 Approved for Public Release; Distribution Unlimited. Case Number 18-3678.
 
-### NOTICE
+## NOTICE
 
 MITRE hereby grants express written permission to use, reproduce, distribute, modify, and otherwise leverage this software to the extent permitted by the licensed terms provided in the LICENSE.md file included with this project.
 
-### NOTICE
+## NOTICE
 
 This software was produced for the U. S. Government under Contract Number HHSM-500-2012-00008I, and is subject to Federal Acquisition Regulation Clause 52.227-14, Rights in Data-General.
 

package/lib/index.d.ts

@@ -1,7 +1,9 @@
-export * from './objects/control';
-export * from './objects/profile';
 export * from './parsers/json';
 export * from './parsers/oval';
 export * from './parsers/xccdf';
 export * from './utilities/diff';
 export * from './utilities/update';
+import Control from './objects/control';
+import Profile from './objects/profile';
+export { Control };
+export { Profile };

package/lib/index.js

@@ -1,10 +1,13 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.Profile = exports.Control = void 0;
 const tslib_1 = require("tslib");
-tslib_1.__exportStar(require("./objects/control"), exports);
-tslib_1.__exportStar(require("./objects/profile"), exports);
 tslib_1.__exportStar(require("./parsers/json"), exports);
 tslib_1.__exportStar(require("./parsers/oval"), exports);
 tslib_1.__exportStar(require("./parsers/xccdf"), exports);
 tslib_1.__exportStar(require("./utilities/diff"), exports);
 tslib_1.__exportStar(require("./utilities/update"), exports);
+const control_1 = tslib_1.__importDefault(require("./objects/control"));
+exports.Control = control_1.default;
+const profile_1 = tslib_1.__importDefault(require("./objects/profile"));
+exports.Profile = profile_1.default;

package/lib/objects/control.d.ts

@@ -1,9 +1,40 @@
 import { ExecJSON } from 'inspecjs';
+/**
+ * Converts an array of ExecJSON.ControlDescription objects or a dictionary of descriptions
+ * into a standardized dictionary format.
+ *
+ * @param descs - An array of ExecJSON.ControlDescription objects, a dictionary of descriptions,
+ *                or null/undefined.
+ * @returns A dictionary where the keys are description labels and the values are description data.
+ *          If the input is null or undefined, an empty dictionary is returned.
+ */
 export declare function objectifyDescriptions(descs: ExecJSON.ControlDescription[] | {
     [key: string]: string | undefined;
 } | null | undefined): {
     [key: string]: string | undefined;
 };
+/**
+ * Represents a Control object with various properties and methods to manipulate and convert it.
+ *
+ * @class Control
+ * @property {string} id - The unique identifier for the control.
+ * @property {string | null} [title] - The title of the control.
+ * @property {string | null} [code] - The code associated with the control.
+ * @property {string | null} [describe] - Additional description content for the control.
+ * @property {string | null} [desc] - The default description of the control.
+ * @property {Object.<string, string | undefined>} descs - Additional descriptions for the control.
+ * @property {number} [impact] - The impact value of the control.
+ * @property {string} [ref] - A reference string for the control.
+ * @property {(string | { ref?: string; url?: string; uri?: string; })[]} [refs] - An array of references for the control.
+ * @property {Object.<string, string | string[] | Record<string, string[]>[] | boolean | undefined | null>} tags - Tags associated with the control.
+ *
+ * @constructor
+ * @param {Partial<Control>} [data] - An optional partial object of type Control to initialize the instance with.
+ *
+ * @method toUnformattedObject
+ * @method toString
+ * @method toRuby
+ */
 export default class Control {
     id: string;
     title?: string | null;
@@ -47,8 +78,55 @@ export default class Control {
         ia_controls?: string;
         [key: string]: string | string[] | Record<string, string[]>[] | boolean | undefined | null;
     };
+    /**
+     * Constructs a new instance of the Control class.
+     *
+     * @param data - An optional partial object of type Control to initialize the instance with.
+     *               If provided, the properties of the data object will be assigned to the instance.
+     */
     constructor(data?: Partial<Control>);
+    /**
+     * Converts the current Control object into an unformatted object.
+     * The method flattens the object, processes its string properties,
+     * and then unflattens it back into a Control object.
+     *
+     * @returns {Control} A new Control object created from the unformatted data.
+     */
     toUnformattedObject(): Control;
+    /**
+     * Converts the control object to a string representation in a specific format.
+     * Provides the ability to get the control in its raw form
+     *
+     * The resulting string includes:
+     * - The control ID.
+     * - The title, if present.
+     * - The default description, if present.
+     * - Additional descriptions, if present.
+     * - The impact value, if present.
+     * - References, if present.
+     * - Tags, if present.
+     * - Additional describe content, if present.
+     *
+     * @returns {string} The string representation of the control object.
+     */
     toString(): string;
+    /**
+     * Converts the control object to a Ruby string representation.
+     *
+     * @param {boolean} [verbose=false] - If true, logs detailed error and warning messages.
+     * @returns {string} The Ruby string representation of the control object.
+     *
+     * The generated Ruby string includes:
+     * - `control` block with the control ID.
+     * - `title` if available, otherwise logs an error if verbose is true.
+     * - `desc` if available, otherwise logs an error if verbose is true.
+     * - Additional descriptions (`descs`) if available, with special handling for the 'default' keyword.
+     * - `impact` if defined, otherwise logs an error if verbose is true.
+     * - `refs` if available, with support for both string and object references.
+     * - `tags` if available, with special formatting for arrays and objects, and handling for nil values for specific tags.
+     * - `describe` if available, appended at the end of the control block.
+     *
+     * The function ensures proper formatting and escaping of quotes for Ruby syntax.
+     */
     toRuby(verbose?: boolean): string;
 }

package/lib/objects/control.js

@@ -1,11 +1,21 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.objectifyDescriptions = void 0;
+exports.objectifyDescriptions = objectifyDescriptions;
 const tslib_1 = require("tslib");
 const lodash_1 = tslib_1.__importDefault(require("lodash"));
 const flat_1 = require("flat");
+const flat_2 = require("flat");
 const global_1 = require("../utilities/global");
 const logging_1 = require("../utilities/logging");
+/**
+ * Converts an array of ExecJSON.ControlDescription objects or a dictionary of descriptions
+ * into a standardized dictionary format.
+ *
+ * @param descs - An array of ExecJSON.ControlDescription objects, a dictionary of descriptions,
+ *                or null/undefined.
+ * @returns A dictionary where the keys are description labels and the values are description data.
+ *          If the input is null or undefined, an empty dictionary is returned.
+ */
 function objectifyDescriptions(descs) {
     if (Array.isArray(descs)) {
         const descriptions = {};
@@ -16,8 +26,35 @@ function objectifyDescriptions(descs) {
     }
     return descs || {};
 }
-exports.objectifyDescriptions = objectifyDescriptions;
+/**
+ * Represents a Control object with various properties and methods to manipulate and convert it.
+ *
+ * @class Control
+ * @property {string} id - The unique identifier for the control.
+ * @property {string | null} [title] - The title of the control.
+ * @property {string | null} [code] - The code associated with the control.
+ * @property {string | null} [describe] - Additional description content for the control.
+ * @property {string | null} [desc] - The default description of the control.
+ * @property {Object.<string, string | undefined>} descs - Additional descriptions for the control.
+ * @property {number} [impact] - The impact value of the control.
+ * @property {string} [ref] - A reference string for the control.
+ * @property {(string | { ref?: string; url?: string; uri?: string; })[]} [refs] - An array of references for the control.
+ * @property {Object.<string, string | string[] | Record<string, string[]>[] | boolean | undefined | null>} tags - Tags associated with the control.
+ *
+ * @constructor
+ * @param {Partial<Control>} [data] - An optional partial object of type Control to initialize the instance with.
+ *
+ * @method toUnformattedObject
+ * @method toString
+ * @method toRuby
+ */
 class Control {
+    /**
+     * Constructs a new instance of the Control class.
+     *
+     * @param data - An optional partial object of type Control to initialize the instance with.
+     *               If provided, the properties of the data object will be assigned to the instance.
+     */
     constructor(data) {
         this.tags = {};
         this.refs = [];
@@ -28,6 +65,13 @@ class Control {
             });
         }
     }
+    /**
+     * Converts the current Control object into an unformatted object.
+     * The method flattens the object, processes its string properties,
+     * and then unflattens it back into a Control object.
+     *
+     * @returns {Control} A new Control object created from the unformatted data.
+     */
     toUnformattedObject() {
         const flattened = (0, flat_1.flatten)(this);
         Object.entries(flattened).forEach(([key, value]) => {
@@ -35,9 +79,24 @@ class Control {
                 lodash_1.default.set(flattened, key, value);
             }
         });
-        return new Control((0, flat_1.unflatten)(flattened));
+        return new Control((0, flat_2.unflatten)(flattened));
     }
-    // WIP - provides the ability to get the control in its raw form
+    /**
+     * Converts the control object to a string representation in a specific format.
+     * Provides the ability to get the control in its raw form
+     *
+     * The resulting string includes:
+     * - The control ID.
+     * - The title, if present.
+     * - The default description, if present.
+     * - Additional descriptions, if present.
+     * - The impact value, if present.
+     * - References, if present.
+     * - Tags, if present.
+     * - Additional describe content, if present.
+     *
+     * @returns {string} The string representation of the control object.
+     */
     toString() {
         let result = '';
         result += `control '${this.id}' do\n`;
@@ -58,6 +117,9 @@ class Control {
         if (this.impact) {
             result += `  impact ${this.impact}\n`;
         }
+        else if (this.impact === 0) {
+            result += `  impact ${this.impact.toFixed(1)}\n`;
+        }
         if (this.refs) {
             this.refs.forEach((ref) => {
                 var _a;
@@ -97,8 +159,26 @@ class Control {
         result += 'end\n';
         return result;
     }
-    toRuby(verbose = true) {
-        const logger = (0, logging_1.createWinstonLogger)();
+    /**
+     * Converts the control object to a Ruby string representation.
+     *
+     * @param {boolean} [verbose=false] - If true, logs detailed error and warning messages.
+     * @returns {string} The Ruby string representation of the control object.
+     *
+     * The generated Ruby string includes:
+     * - `control` block with the control ID.
+     * - `title` if available, otherwise logs an error if verbose is true.
+     * - `desc` if available, otherwise logs an error if verbose is true.
+     * - Additional descriptions (`descs`) if available, with special handling for the 'default' keyword.
+     * - `impact` if defined, otherwise logs an error if verbose is true.
+     * - `refs` if available, with support for both string and object references.
+     * - `tags` if available, with special formatting for arrays and objects, and handling for nil values for specific tags.
+     * - `describe` if available, appended at the end of the control block.
+     *
+     * The function ensures proper formatting and escaping of quotes for Ruby syntax.
+     */
+    toRuby(verbose = false) {
+        const logger = (0, logging_1.createWinstonLogger)('ts-inspec-objects');
         let result = '';
         result += `control '${this.id}' do\n`;
         if (this.title) {
@@ -137,7 +217,7 @@ class Control {
                 }
                 else {
                     if (verbose) {
-                        logger.error(`${this.id} does not have a desc for the value ${key}`);
+                        logger.warn(`${this.id} does not have a desc for the value ${key}`);
                     }
                 }
             });
@@ -150,17 +230,20 @@ class Control {
                 logger.error(`${this.id} does not have an impact`);
             }
         }
-        if (this.refs) {
-            this.refs.forEach((ref) => {
-                var _a;
-                if (typeof ref === 'string') {
-                    result += `  ref ${(0, global_1.escapeQuotes)(ref)}\n`;
-                }
-                else {
-                    result += `  ref ${(0, global_1.escapeQuotes)(((_a = ref.ref) === null || _a === void 0 ? void 0 : _a.toString()) || '')}, url: ${(0, global_1.escapeQuotes)(ref.url || '')}`;
-                }
-            });
-        }
+        //-------------------------------------------------------------------------
+        // This may not be necessary, leaving commented code for posterity. Once we
+        // have implemented the process and determined that there isn't any side
+        // effects we can remove the commented code
+        //-------------------------------------------------------------------------
+        // if (this.refs) {
+        //   this.refs.forEach((ref) => {
+        //     if (typeof ref === 'string') {
+        //       result += `  ref ${escapeQuotes(ref)}\n`;
+        //     } else {
+        //       result += `  ref ${escapeQuotes(ref.ref?.toString() || '')}, url: ${escapeQuotes(ref.url || '')}`
+        //     }
+        //   });
+        // }
         Object.entries(this.tags).forEach(([tag, value]) => {
             if (value) {
                 if (typeof value === 'object') {

package/lib/objects/profile.d.ts

@@ -1,4 +1,38 @@
 import Control from './control';
+/**
+ * Represents an InSpec profile with various metadata and dependencies.
+ *
+ * @remarks
+ * This class is used to model an InSpec profile, which includes metadata such as
+ * name, title, maintainer, copyright, license, and version. It also includes
+ * dependencies, supported platforms, inputs, gem dependencies, libraries, readme,
+ * files, and controls.
+ *
+ * It provides methods to generate a YAML representation of the profile and to convert
+ * the profile to an unformatted version.
+ *
+ * @example
+ * ```typescript
+ * const profileData = {
+ *   name: "example-profile",
+ *   title: "Example Profile",
+ *   maintainer: "John Doe",
+ *   version: "1.0.0",
+ *   supports: [{ 'platform-name': 'ubuntu' }],
+ *   depends: [{ name: "dependency-profile", url: "http://example.com/dependency.tar.gz" }],
+ *   inputs: [{ key: "value" }],
+ *   libraries: ["lib/example.rb"],
+ *   files: ["controls/example.rb"],
+ *   readme: "This is an example profile.",
+ * };
+ *
+ * const profile = new Profile(profileData);
+ * const yamlString = profile.createInspecYaml();
+ * console.log(yamlString);
+ * ```
+ *
+ * @public
+ */
 export default class Profile {
     name?: string | null;
     title?: string | null;
@@ -44,7 +78,31 @@ export default class Profile {
     readme?: string | null;
     files: string[];
     controls: Control[];
+    /**
+     * Constructs a new instance of the Profile class.
+     *
+     * @param data - An optional object containing partial profile data, excluding the 'controls' property.
+     *               The provided data will be used to set the corresponding properties on the instance.
+     */
     constructor(data?: Omit<Partial<Profile>, 'controls'>);
+    /**
+     * Generates an InSpec YAML string representation of the profile object.
+     * Note: Per Chef documentation the inspec_version should be a string
+     *       in the format of "x.y.z" or "x.y.z-alpha" or "x.y.z-beta",
+     *       it must be double quoted, most often the format is "~>#.#"
+     *
+     * @returns {string} The YAML string representation of the profile.
+     */
     createInspecYaml(): string;
+    /**
+     * Converts the current Profile object to an unformatted version.
+     *
+     * This method creates a new Profile instance and iterates over the properties
+     * of the current Profile object. If a property value is a string, it applies
+     * the `unformatText` function to the value and sets it on the new Profile instance.
+     * It also recursively converts the controls of the Profile to their unformatted versions.
+     *
+     * @returns {Profile} The unformatted Profile object.
+     */
     toUnformattedObject(): Profile;
 }

package/lib/objects/profile.js

@@ -4,7 +4,47 @@ const tslib_1 = require("tslib");
 const yaml_1 = tslib_1.__importDefault(require("yaml"));
 const lodash_1 = tslib_1.__importDefault(require("lodash"));
 const global_1 = require("../utilities/global");
+/**
+ * Represents an InSpec profile with various metadata and dependencies.
+ *
+ * @remarks
+ * This class is used to model an InSpec profile, which includes metadata such as
+ * name, title, maintainer, copyright, license, and version. It also includes
+ * dependencies, supported platforms, inputs, gem dependencies, libraries, readme,
+ * files, and controls.
+ *
+ * It provides methods to generate a YAML representation of the profile and to convert
+ * the profile to an unformatted version.
+ *
+ * @example
+ * ```typescript
+ * const profileData = {
+ *   name: "example-profile",
+ *   title: "Example Profile",
+ *   maintainer: "John Doe",
+ *   version: "1.0.0",
+ *   supports: [{ 'platform-name': 'ubuntu' }],
+ *   depends: [{ name: "dependency-profile", url: "http://example.com/dependency.tar.gz" }],
+ *   inputs: [{ key: "value" }],
+ *   libraries: ["lib/example.rb"],
+ *   files: ["controls/example.rb"],
+ *   readme: "This is an example profile.",
+ * };
+ *
+ * const profile = new Profile(profileData);
+ * const yamlString = profile.createInspecYaml();
+ * console.log(yamlString);
+ * ```
+ *
+ * @public
+ */
 class Profile {
+    /**
+     * Constructs a new instance of the Profile class.
+     *
+     * @param data - An optional object containing partial profile data, excluding the 'controls' property.
+     *               The provided data will be used to set the corresponding properties on the instance.
+     */
     constructor(data) {
         this.supports = [];
         this.depends = [];
@@ -18,6 +58,14 @@ class Profile {
             });
         }
     }
+    /**
+     * Generates an InSpec YAML string representation of the profile object.
+     * Note: Per Chef documentation the inspec_version should be a string
+     *       in the format of "x.y.z" or "x.y.z-alpha" or "x.y.z-beta",
+     *       it must be double quoted, most often the format is "~>#.#"
+     *
+     * @returns {string} The YAML string representation of the profile.
+     */
     createInspecYaml() {
         return yaml_1.default.stringify({
             name: this.name,
@@ -31,9 +79,20 @@ class Profile {
             version: this.version,
             supports: this.supports,
             depends: this.depends,
-            inspec_version: this.inspec_version,
+            //inspec_version: this.inspec_version,
+            inspec_version: yaml_1.default.stringify(`${this.inspec_version}`, { defaultStringType: 'QUOTE_DOUBLE' }),
         });
     }
+    /**
+     * Converts the current Profile object to an unformatted version.
+     *
+     * This method creates a new Profile instance and iterates over the properties
+     * of the current Profile object. If a property value is a string, it applies
+     * the `unformatText` function to the value and sets it on the new Profile instance.
+     * It also recursively converts the controls of the Profile to their unformatted versions.
+     *
+     * @returns {Profile} The unformatted Profile object.
+     */
     toUnformattedObject() {
         const unformattedProfile = new Profile(this);
         Object.entries(this).forEach(([key, value]) => {

package/lib/parsers/json.d.ts

@@ -1,6 +1,38 @@
 import { ContextualizedEvaluation, ContextualizedProfile, ExecJSON } from 'inspecjs';
 import Profile from '../objects/profile';
+/**
+ * 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.
+ */
 export declare function processEvaluation(evaluationInput: ContextualizedEvaluation): Profile;
+/**
+ * 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.
+ */
 export declare function processProfileJSON(profileInput: ContextualizedProfile): Profile;
+/**
+ * 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.
+ */
 export declare function processExecJSON(execJSON: ExecJSON.Execution): Profile;
+/**
+ * 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.
+ */
 export declare function processInSpecProfile(json: string): Profile;