@mitre/inspec-objects 2.0.1 → 2.0.2

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

@@ -4,17 +4,14 @@ on:
     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
+    runs-on: ubuntu-24.04
     steps:
-    - uses: hmarr/auto-approve-action@v3
-      with:
-        github-token: "${{ secrets.GITHUB_TOKEN }}"
+    - uses: hmarr/auto-approve-action@v4
     - name: Enable auto-merge for Dependabot PRs
       run: gh pr merge --auto --merge "$PR_URL"
       env:

package/.github/workflows/draft-release.yml

@@ -8,9 +8,9 @@ on:
 
 jobs:
   update_draft_release:
-    runs-on: ubuntu-latest
+    runs-on: ubuntu-24.04
     steps:
       # Drafts your next Release notes as Pull Requests are merged into "master"
-      - uses: toolmantim/release-drafter@v5.2.0
+      - uses: release-drafter/release-drafter@v6
         env:
-          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

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

@@ -7,15 +7,15 @@ on:
 jobs:
   build:
     name: Run TS-InSpec-Objects E2E Tests
-    runs-on: ubuntu-20.04
+    runs-on: ubuntu-24.04
 
     steps:
-     - uses: actions/checkout@v3
+     - uses: actions/checkout@v4
 
      - name: Setup Node.js
-       uses: actions/setup-node@v3
+       uses: actions/setup-node@v4
        with:
-        node-version: 18
+        node-version: 22
         cache: 'npm'
 
      - name: Install dependencies

package/.github/workflows/linter.yml

@@ -7,16 +7,16 @@ on:
 jobs:
   build:
     name: Lint TS-InSpec-Objects
-    runs-on: ubuntu-20.04
+    runs-on: ubuntu-24.04
 
     steps:
      - name: Checkout code
-       uses: actions/checkout@v3
+       uses: actions/checkout@v4
 
      - name: Setup Node.js
-       uses: actions/setup-node@v3
+       uses: actions/setup-node@v4
        with:
-        node-version: 18
+        node-version: 22
         cache: 'npm'
 
      - name: Install project dependencies

package/.github/workflows/push-to-gpr.yml

@@ -6,31 +6,28 @@ on:
 
 jobs:
   build-deploy:
-    runs-on: ubuntu-20.04
+    runs-on: ubuntu-24.04
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
 
       - name: Setup node
-        uses: actions/setup-node@v3
+        uses: actions/setup-node@v4
         with:
-          node-version: 18
-          registry-url: https://npm.pkg.github.com/
+          node-version: 22
+          registry-url: 'https://npm.pkg.github.com'
           scope: '@mitre'
 
       - name: Build the NPM Package
         run: |
           npm install
+          rm -rf test
           npm run build
+
       - name: Pack all items that are published
         run: npm pack
-      # Setup .npmrc file to publish to GitHub Package Registry
-      - uses: actions/setup-node@v1
-        with:
-          registry-url: 'https://npm.pkg.github.com'
-          scope: '@mitre'
 
       # Publish inspec-objects to GitHub Package Registry
       - name: Publish inspec-objects to GPR
         run: npm publish mitre-inspec-objects-*.tgz
         env:
-          NODE_AUTH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          NODE_AUTH_TOKEN: ${{ secrets.GITHUB_TOKEN }}

package/.github/workflows/push-to-npm.yml

@@ -6,14 +6,14 @@ on:
 
 jobs:
   build-deploy:
-    runs-on: ubuntu-20.04
+    runs-on: ubuntu-24.04
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
 
       - name: setup node
-        uses: actions/setup-node@v3
+        uses: actions/setup-node@v4
         with:
-          node-version: 18
+          node-version: 22
           registry-url: 'https://registry.npmjs.org'
 
       - name: Install project dependencies

package/README.md

@@ -1,12 +1,14 @@
 # ts-inspec-objects
-Typescript objects for InSpec profiles
+Typescript objects for InSpec Profiles
 
-This repository contains the source code that facilitates the writing of InSpec profiles (for use in things like stub generation and delta comparisons) more consistent with `Chef Cookstyle` formatting for ease of use when comparing with new changes from delta and when generating InSpec stubs that match a standard format. 
+This repository contains the source code that facilitates the writing of InSpec Profiles (for use in things like stub generation and delta comparisons) more consistent with `Chef Cookstyle` formatting for ease of use when comparing with new changes from delta and when generating InSpec stubs that match a standard format. 
 
 For more information about Chef Cookstyle see: 
  - [chef/cookstyle on GitHub](https://github.com/chef/cookstyle)
  - [Chef Cookstyle on Chef documents page](https://docs.chef.io/workstation/cookstyle/)
 
+The `ts-inspec-objects` provides the capability of updating InSpect Profiles and creating stub Profiles based on XCCDF Benchmarks. This is accomplished by providing `Profile` and `Control` classes and supporting methods (functions).
+
 ## How to Use
 The process code maintained in this repository generates a `npm` executable that is published to the `npm registry` as [mitre-inspec-objects](https://www.npmjs.com/package/@mitre/inspec-objects).
 
@@ -18,7 +20,7 @@ The package is a CommonJS-based npm written in TypeScript
 
 ## Parsing Process
 
-When using this library to parse `InSpec profiles` or `xccdf files` for the purposes of generating InSpec profiles, the general workflow is as follows:
+When using this library to parse `InSpec Profiles` or `xccdf files` for the purposes of generating InSpec profiles, the general workflow is as follows:
 ```
   - The input is processed, read into a typescript object
   - Operated on with any required action / logic
@@ -39,16 +41,46 @@ Here are some formatting choices that are being made.
 2. Tag keywords are not quoted (ex: tag severity: 'medium')
 3. Each control file ends with a newline
 
-### Workflow graphical representation
+---
+### XCCDF Workflow Process
+Processes an XCCDF (Extensible Configuration Checklist Description Format) XML string based on the `Rule Identifier` provided and converts it into a Profile object.
+If and OVAL definition is provided it retrives the oval objects and associated states and the Controls description check text is update with the content.
+<div align="center">
+  <img src="images/ts-inspec-objects-xccdf-workflow-process.png" alt="Typescript Objects XCCDF Conversion Workflow Process" title="Typescript Objects XCCDF Conversion Workflow Process">
+</div>
+
+### OVAL Workflow Process
+Processes an OVAL (Open Vulnerability and Assessment Language) XML string and converts it into a JSON object.
+The process extracts definitions and their associated criteria references and resolved values.
+The process executes 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.
+<div align="center">
+  <img src="images/ts-inspec-objects-oval-workflow-process.png" alt="Typescript Objects Oval Conversion Workflow Process" title="Typescript Objects Oval Conversion Workflow Process">
+</div>
+
+### InSpec Profile Workflow Process
+Process 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.
+<div align="center">
+  <img src="images/ts-inspec-objects-inspec-profile-workflow-process.png" alt="Typescript Objects InSpec Profile Workflow Process" title="Typescript Objects InSpec Profile Workflow Process">
+</div>
+
+### Update Profile Using XCCDF Workflow Process
+Updates a Profile with new metadata from and XCCDF, based on the `Rule Indetefier` and logs the process.
 <div align="center">
-  <img src="images/ts-inspec-objects.jpg" alt="Typescript Objects Generation Process" title="Typescript Objects Generation Process">
+  <img src="images/ts-inspec-objects-updateProfileUsingXccdf-workflow.png" alt="Typescript Objects Update Profile Using XCCDF Workflow Process" title="Typescript Objects Update Profile Using XCCDF Workflow Process">
 </div>
 
-### Delta and Stub Process
+### Update Control Workflow Process
+Updates a given control object with the provided partial control and logs the process.
 <div align="center">
-  <img src="images/Delta_Process.jpg" alt="Delta and Stub Generation Process" title="Delta and Stub Generation Process">
+  <img src="images/ts-inspec-objects-process-updateControl-workflow.png" alt="Typescript Objects Update Control Workflow Process" title="Typescript Objects Update Control Workflow Process">
 </div>
 
+---
 ## Development Environment Configuration
 ### Installation
 To install the project, clone the repository and install the dependencies:

package/lib/parsers/xccdf.d.ts

@@ -27,7 +27,8 @@ export type InputTextLang = {
     '@_lang': string;
 };
 /**
- * Processes an XCCDF XML string and converts it into a Profile object.
+ * Processes an XCCDF (Extensible Configuration Checklist Description Format) 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

package/lib/parsers/xccdf.js

@@ -75,7 +75,8 @@ function ensureDecodedXMLStringValue(input, defaultValue) {
             : lodash_1.default.get(input, '#text', defaultValue);
 }
 /**
- * Processes an XCCDF XML string and converts it into a Profile object.
+ * Processes an XCCDF (Extensible Configuration Checklist Description Format) 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

package/lib/utilities/update.d.ts

@@ -74,4 +74,14 @@ export declare function updateControlDescribeBlock(from: Control, update: Partia
  * @throws Will throw an error if a new control is added but the control data is not available.
  */
 export declare function updateProfile(from: Profile, using: Profile, logger: winston.Logger): Omit<UpdatedProfileReturn, 'markdown'>;
+/**
+ * Update a Profile with with new metadata from a XCCDF benchmark
+ *
+ * @param from - A Profile object
+ * @param using - An XCCDF in string format (XML)
+ * @param id - Specifies the rule ID format to use ('group', 'rule', 'version', or 'cis').
+ * @param logger - A winston logger instance for logging debug information.
+ * @param ovalDefinitions - Optional OVAL definitions to use for resolving values.
+ * @returns The Updated Profile (profile, the diff between from and using, and the markdown)
+ */
 export declare function updateProfileUsingXCCDF(from: Profile, using: string, id: 'group' | 'rule' | 'version' | 'cis', logger: winston.Logger, ovalDefinitions?: Record<string, OvalDefinitionValue>): UpdatedProfileReturn;

package/lib/utilities/update.js

@@ -377,9 +377,19 @@ function updateProfile(from, using, logger) {
         diff,
     };
 }
+/**
+ * Update a Profile with with new metadata from a XCCDF benchmark
+ *
+ * @param from - A Profile object
+ * @param using - An XCCDF in string format (XML)
+ * @param id - Specifies the rule ID format to use ('group', 'rule', 'version', or 'cis').
+ * @param logger - A winston logger instance for logging debug information.
+ * @param ovalDefinitions - Optional OVAL definitions to use for resolving values.
+ * @returns The Updated Profile (profile, the diff between from and using, and the markdown)
+ */
 function updateProfileUsingXCCDF(from, using, id, logger, ovalDefinitions) {
     logger.info(`Updating profile ${from.name} with control IDs type: ${id}`);
-    // Parse the XCCDF benchmark and convert it into a Profile
+    // Parse the XCCDF benchmark and convert it into a Profile object
     logger.debug('Loading XCCDF File');
     const xccdfProfile = (0, xccdf_1.processXCCDF)(using, false, id, ovalDefinitions);
     logger.debug('Loaded XCCDF File');

package/lib/utilities/xccdf.d.ts

@@ -68,10 +68,17 @@ export declare function convertJsonIntoXML(data: any): string;
  */
 export declare function removeXMLSpecialCharacters(str: string): string;
 /**
- * Removes HTML tags from the given input string.
- *
+ * Removes all of the HTML tags and leaves only the text content.
+  *
  * @param input - The string from which HTML tags should be removed.
  * @returns A new string with all HTML tags removed.
+ *
+ * @example
+ * ```typescript
+ * const str = '<div>Hello <b>World</b>!</div>';
+ * const stripped = removeHtmlTags(str);
+ * console.log(stripped); // Output: "Hello World!"
+ * ```
  */
 export declare function removeHtmlTags(input: string): string;
 /**

package/lib/utilities/xccdf.js

@@ -118,12 +118,29 @@ function removeXMLSpecialCharacters(str) {
     return result;
 }
 /**
- * Removes HTML tags from the given input string.
- *
+ * Removes all of the HTML tags and leaves only the text content.
+  *
  * @param input - The string from which HTML tags should be removed.
  * @returns A new string with all HTML tags removed.
+ *
+ * @example
+ * ```typescript
+ * const str = '<div>Hello <b>World</b>!</div>';
+ * const stripped = removeHtmlTags(str);
+ * console.log(stripped); // Output: "Hello World!"
+ * ```
  */
 function removeHtmlTags(input) {
+    // Regex explained
+    //    <: Matches the opening angle bracket of an HTML tag
+    //   /?: Matches zero or one forward slash /, to include closing tags
+    // [^>]: Matches any character except the > symbol
+    //    +: Ensures preceding pattern ([^>]) matches one or more characters
+    // (>|$):
+    //   > matches the closing angle bracket of an HTML tag.
+    //   $ matches the end of the string. This ensures the regex can handle
+    //     cases where the tag is incomplete or unclosed (e.g., <div)
+    // g: Global flag to find all matches in the input string
     return input.replace(/<\/?[^>]+(>|$)/g, '');
 }
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mitre/inspec-objects",
-  "version": "2.0.1",
+  "version": "2.0.2",
   "description": "Typescript objects for normalizing between InSpec profiles and XCCDF benchmarks",
   "main": "lib/index.js",
   "publishConfig": {
@@ -31,13 +31,13 @@
     "@types/lodash": "^4.14.178",
     "@types/mustache": "^4.2.0",
     "@types/pretty": "^2.0.1",
-    "fast-xml-parser": "^4.5.1",
+    "fast-xml-parser": "^5.0.7",
     "flat": "5.0.2",
     "he": "^1.2.0",
     "htmlparser2": "^10.0.0",
     "inspecjs": "^2.6.6",
     "json-diff": "^1.0.6",
-    "jstoxml": "^5.0.2",
+    "jstoxml": "^6.0.1",
     "lodash": "^4.17.21",
     "mustache": "^4.2.0",
     "pretty": "^2.0.0",
@@ -45,12 +45,12 @@
     "yaml": "^2.3.1"
   },
   "devDependencies": {
-    "@types/jest": "^29.5.12",
-    "@types/node": "^22.5.2",
+    "@types/jest": "^30.0.0",
+    "@types/node": "^24.0.0",
     "@typescript-eslint/eslint-plugin": "^6.4.1",
     "@typescript-eslint/parser": "^6.0.0",
     "eslint": "^8.30.0",
-    "jest": "^29.7.0",
+    "jest": "^30.0.0",
     "ts-jest": "^29.1.1",
     "tslib": "^2.4.0",
     "typescript": "^5.2.2"