@mitre/inspec-objects 2.0.1 → 2.0.4

package/.github/dependabot.yml

@@ -6,6 +6,8 @@ updates:
     directory: "/"
     schedule:
       interval: daily
-      time: "20:00"
-      timezone: America/New_York
-    open-pull-requests-limit: 99
+    groups:
+      typescript-eslint:
+        applies-to: version-updates
+        patterns:
+          - "@typescript-eslint/*"

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

@@ -10,11 +10,9 @@ 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/build.yml

@@ -0,0 +1,30 @@
+name: Build and Pack TS-InSpec-Objects
+on:
+  push:
+    branches: [ main ]
+  pull_request:
+
+jobs:
+  build:
+    name: Build and Pack TS-InSpec-Objects
+    runs-on: ubuntu-24.04
+
+    steps:
+     - uses: actions/checkout@v4
+
+     - name: Setup Node.js
+       uses: actions/setup-node@v4
+       with:
+        node-version: 22
+        cache: 'npm'
+
+     - name: Prep
+       run: |
+         npm ci
+         rm -rf test
+
+     - name: Build
+       run: npm run build
+
+     - name: Pack
+       run: npm pack

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,30 @@ 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
-          npm run build
-      - name: Pack all items that are published
+      - name: Install project dependencies
+        run: npm ci
+
+      - name: Remove testing resources
+        run: rm -rf test
+
+      - name: Build
+        run: npm run build
+
+      - name: Pack all items that are published as packages
         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/oval.js

@@ -109,7 +109,6 @@ function processOVAL(oval) {
                 extractedDefinitions[definition['@_id']].resolvedValues = (_a = extractedDefinitions[definition['@_id']].criteriaRefs) === null || _a === void 0 ? void 0 : _a.map((criteriaRef) => {
                     // Extract the original criteria from the oval file
                     const foundCriteriaRefererence = searchTree(parsed.oval_definitions[0].tests, (oNode) => oNode['@_id'] === criteriaRef, false)[0];
-                    // eslint-disable-next-line @typescript-eslint/ban-types
                     const foundObjects = [];
                     const foundStates = [];
                     if (foundCriteriaRefererence) {

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
@@ -173,9 +174,7 @@ function processXCCDF(xml, removeNewlines, useRuleId, ovalDefinitions) {
                 break;
             case 'version':
                 if (rule.version !== undefined) {
-                    (lodash_1.default.isArray(rule.version))
-                        ? control.id = rule.version[0]
-                        : control.id = rule.version;
+                    control.id = (lodash_1.default.isArray(rule.version)) ? rule.version[0] : rule.version;
                 }
                 else {
                     throw new Error('The rule type "version" did not provide an identification (Id) value');
@@ -343,8 +342,8 @@ function processXCCDF(xml, removeNewlines, useRuleId, ovalDefinitions) {
         }
         // Update the control tags base on corresponding rule tags.
         control.tags.severity = (0, xccdf_1.impactNumberToSeverityString)((0, xccdf_1.severityStringToImpact)(rule['@_severity'] || 'medium'));
-        control.tags.gid = rule.group['@_id'],
-            control.tags.rid = rule['@_id'];
+        control.tags.gid = rule.group['@_id'];
+        control.tags.rid = rule['@_id'];
         control.tags.stig_id = rule['version'];
         if (typeof rule.group.title === 'string') {
             control.tags.gtitle = (0, xccdf_1.removeXMLSpecialCharacters)(rule.group.title);

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.4",
   "description": "Typescript objects for normalizing between InSpec profiles and XCCDF benchmarks",
   "main": "lib/index.js",
   "publishConfig": {
@@ -9,7 +9,7 @@
   "scripts": {
     "build": "tsc -p ./tsconfig.build.json",
     "dev": "npx -y ts-node test.ts",
-    "test": "jest",
+    "test": "vitest",
     "lint": "eslint \"**/*.ts\" --fix",
     "lint:ci": "eslint \"**/*.ts\" --max-warnings 0"
   },
@@ -24,42 +24,33 @@
   },
   "homepage": "https://github.com/mitre/ts-inspec-objects#readme",
   "dependencies": {
-    "@types/flat": "5.0.2",
+    "@types/flat": "5.0.5",
     "@types/he": "^1.1.2",
     "@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": "^4.5.1",
-    "flat": "5.0.2",
+    "fast-xml-parser": "^5.0.7",
+    "flat": "6.0.1",
     "he": "^1.2.0",
     "htmlparser2": "^10.0.0",
     "inspecjs": "^2.6.6",
     "json-diff": "^1.0.6",
-    "jstoxml": "^5.0.2",
+    "jstoxml": "^7.0.1",
     "lodash": "^4.17.21",
     "mustache": "^4.2.0",
     "pretty": "^2.0.0",
+    "tslib": "^2.8.1",
     "winston": "^3.8.1",
     "yaml": "^2.3.1"
   },
   "devDependencies": {
-    "@types/jest": "^29.5.12",
-    "@types/node": "^22.5.2",
-    "@typescript-eslint/eslint-plugin": "^6.4.1",
-    "@typescript-eslint/parser": "^6.0.0",
+    "@types/node": "^24.0.0",
+    "@typescript-eslint/eslint-plugin": "^8.35.1",
+    "@typescript-eslint/parser": "^8.35.1",
     "eslint": "^8.30.0",
-    "jest": "^29.7.0",
-    "ts-jest": "^29.1.1",
-    "tslib": "^2.4.0",
-    "typescript": "^5.2.2"
-  },
-  "jest": {
-    "rootDir": ".",
-    "testTimeout": 10000000,
-    "transform": {
-      "^.+\\.ts$": "ts-jest"
-    }
+    "typescript": "^5.2.2",
+    "vitest": "^3.2.4"
   }
 }

package/tsconfig.json

@@ -11,11 +11,11 @@
     "rootDir": "src",
     "strict": true,
     "target": "es2019",
-    "types": ["node", "jest"]
+    "types": ["node"]
   },
   "include": [
     "index.ts",
     "src/**/*",
     "types/*"
   ],
-}
+}

package/vitest.config.ts

@@ -0,0 +1,7 @@
+import {defineConfig} from 'vitest/config';
+
+export default defineConfig({
+  test: {
+    testTimeout: 60000
+  }
+});