@mitre/inspec-objects 0.0.1

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "@mitre/inspec-objects",
+  "version": "0.0.1",
+  "description": "Typescript objects for normalizing between InSpec profiles and XCCDF benchmarks",
+  "main": "index.ts",
+  "publishConfig": {
+    "main": "lib/index.js"
+  },
+  "scripts": {
+    "build": "tsc -p ./tsconfig.build.json",
+    "dev": "npx -y ts-node test.ts",
+    "test": "jest"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mitre/ts-inspec-objects.git"
+  },
+  "author": "The MITRE Security Automation Framework",
+  "license": "Apache-2.0",
+  "bugs": {
+    "url": "https://github.com/mitre/ts-inspec-objects/issues"
+  },
+  "homepage": "https://github.com/mitre/ts-inspec-objects#readme",
+  "dependencies": {
+    "@mitre/hdf-converters": "^2.6.9",
+    "@types/flat": "^5.0.2",
+    "@types/json-diff": "^0.7.0",
+    "@types/lodash": "^4.14.178",
+    "fast-xml-parser": "^3.1.19",
+    "flat": "^5.0.2",
+    "htmlparser2": "^7.2.0",
+    "inspecjs": "^2.6.6",
+    "jest": "^28.1.1",
+    "json-diff": "^0.9.0",
+    "lodash": "^4.17.21",
+    "ts-jest": "^28.0.4",
+    "typescript": "^4.5.5",
+    "yaml": "^1.10.2"
+  },
+  "devDependencies": {
+    "@types/jest": "^28.1.1",
+    "@types/node": "^17.0.18",
+    "@typescript-eslint/eslint-plugin": "^5.12.0",
+    "eslint": "^8.9.0"
+  },
+  "jest": {
+    "rootDir": ".",
+    "testTimeout": 10000000,
+    "transform": {
+      "^.+\\.ts$": "ts-jest"
+    }
+  }
+}

package/src/index.ts

@@ -0,0 +1,5 @@
+export * from './objects/control'
+export * from './objects/profile'
+export * from './parsers/json'
+export * from './parsers/xccdf'
+export * from './utilities/diff'

package/src/objects/control.ts

@@ -0,0 +1,137 @@
+import { ExecJSON } from "inspecjs";
+import _ from "lodash";
+import {flatten, unflatten} from "flat"
+import { escapeQuotes, unformatText, wrapAndEscapeQuotes } from "../utilities/global";
+
+export default class Control {
+  id?: string | null;
+  title?: string | null;
+  code?: string | null;
+  desc?: string | null;
+  descs?: ExecJSON.ControlDescription[] | { [key: string]: string } | null;
+  impact?: number;
+  ref?: string;
+  refs?: string[];
+  tags: {
+    check?: string;
+    fix?: string;
+    severity?: string;
+    gtitle?: string;
+    gid?: string;
+    satisfies?: string[];
+    rid?: string;
+    stig_id?: string;
+    fix_id?: string;
+    cci?: string[];
+    cis_controls?: Record<string, string[]>[];
+    nist?: string[];
+    legacy?: string[];
+    false_negatives?: string;
+    false_positives?: string;
+    documentable?: boolean;
+    mitigations?: string;
+    severity_override_guidance?: string;
+    potential_impacts?: string;
+    third_party_tools?: string;
+    mitigation_controls?: string;
+    responsibility?: string;
+    ia_controls?: string;
+    [key: string]:
+      | string
+      | string[]
+      | Record<string, string[]>[]
+      | boolean
+      | undefined
+      | null;
+  } = {};
+
+  constructor(data?: Partial<Control>) {
+    if (data) {
+      Object.entries(data).forEach(([key, value]) => {
+        _.set(this, key, value);
+      });
+    }
+  }
+
+  toUnformattedObject(): Control {
+    const flattened: Record<string, string | number> = flatten(this)
+    
+    Object.entries(flattened).forEach(([key, value]) => {
+      if(typeof value === 'string') {
+        _.set(flattened, key, unformatText(value));
+      }
+    });
+
+    return new Control(unflatten(flattened));
+  }
+
+  toRuby(lineLength: number = 80) {
+    let result = "# encoding: UTF-8\n\n";
+
+    result += `control "${this.id}" do\n`;
+    if (this.title) {
+      result += `  title "${wrapAndEscapeQuotes(this.title, lineLength)}"\n`;
+    } else {
+      console.error(`${this.id} does not have a title`);
+    }
+
+    if (this.desc) {
+      result += `  desc "${wrapAndEscapeQuotes(this.desc, lineLength)}"\n`;
+    } else {
+      console.error(`${this.id} does not have a desc`);
+    }
+
+    if (this.descs) {
+      Object.entries(this.descs).forEach(([key, desc]) => {
+        if (desc) {
+          result += `  desc "${key}", "${wrapAndEscapeQuotes(
+            desc,
+            lineLength
+          )}"\n`;
+        } else {
+          console.error(`${this.id} does not have a desc for the value ${key}`);
+        }
+      });
+    }
+
+    if (this.impact) {
+      result += `  impact ${this.impact}\n`;
+    } else {
+      console.error(`${this.id} does not have an impact`);
+    }
+
+    if (this.refs) {
+      this.refs.forEach((ref) => {
+        result += `  ref '${escapeQuotes(ref)}'\n`;
+      });
+    }
+
+    Object.entries(this.tags).forEach(([tag, value]) => {
+      if (value) {
+        if (typeof value === "object") {
+          if (Array.isArray(value) && typeof value[0] === "string") {
+            result += `  tag ${tag}: ${JSON.stringify(value)}\n`;
+          } else {
+            // Convert JSON Object to Ruby Hash
+            const stringifiedObject = JSON.stringify(value, null, 2)
+              .replace(/\n/g, "\n  ")
+              .replace(/\{\n {6}/g, "{")
+              .replace(/\[\n {8}/g, "[")
+              .replace(/\n {6}\]/g, "]")
+              .replace(/\n {4}\}/g, "}")
+              .replace(/": \[/g, '" => [');
+            result += `  tag ${tag}: ${stringifiedObject}\n`;
+          }
+        } else if (typeof value === "string") {
+          result += `  tag ${tag}: "${wrapAndEscapeQuotes(
+            value,
+            lineLength
+          )}"\n`;
+        }
+      }
+    });
+    result += "end";
+
+    return result;
+  }
+}

package/src/objects/profile.ts

@@ -0,0 +1,93 @@
+import Control from "./control";
+import YAML from "yaml";
+import _ from "lodash";
+import { unformatText } from "../utilities/global";
+
+export default class Profile {
+  name?: string | null;
+  title?: string | null;
+  maintainer?: string | null;
+  copyright?: string | null;
+  copyright_email?: string | null;
+  license?: string | null;
+  summary?: string | null;
+  description?: string | null;
+  version?: string | null;
+  inspec_version?: string | null;
+  supports: {
+    "platform-family"?: string;
+    "platform-name"?: string;
+    "os-name"?: string;
+    "os-family"?: string;
+    release?: string;
+    platform?: string;
+  }[] = [];
+  depends: {
+    // Required for all
+    name: string; // Required for all
+
+    // Local file
+    path?: string; // Local path on disk
+
+    // Remote HTTP(s)
+    url?: string; // Remote URL tarball
+    username?: string; // HTTP Basic Authentication Username
+    password?: string; // HTTP Basic Authentication Password
+
+    // Git Repository
+    git?: string;
+    branch?: string;
+    tag?: string;
+    commit?: string;
+    version?: string;
+    relative_path?: string;
+
+    // Chef Supermarket
+    supermarket?: string;
+
+    // Base Compliance
+    compliance?: string;
+  }[] = [];
+  inputs: { [key: string]: string }[] = [];
+  gem_dependencies?: {name: string, version: string}[];
+  libraries: string[] = [];
+  readme?: string | null;
+  files: string[] = [];
+  controls: Control[] = [];
+
+  constructor(data?: Omit<Partial<Profile>, "controls">) {
+    if (data) {
+      Object.entries(data).forEach(([key, value]) => {
+        _.set(this, key, value);
+      });
+    }
+  }
+
+  createInspecYaml(): string {
+    return YAML.stringify({
+      name: this.name,
+      title: this.title,
+      maintainer: this.maintainer,
+      copyright: this.copyright,
+      copyright_email: this.copyright_email,
+      license: this.license,
+      summary: this.summary,
+      description: this.description,
+      version: this.version,
+      supports: this.supports,
+      depends: this.depends,
+      inspec_version: this.inspec_version,
+    });
+  }
+
+  toUnformattedObject(): Profile {
+    const unformattedProfile: Profile = new Profile(this);
+    Object.entries(this).forEach(([key, value]) => {
+      if (typeof value === "string") {
+        _.set(unformattedProfile, key, unformatText(value));
+      }
+    });
+    unformattedProfile.controls = this.controls.map((control) => control.toUnformattedObject())
+    return unformattedProfile;
+  }
+}

package/src/parsers/json.ts

@@ -0,0 +1,92 @@
+import {
+  ContextualizedEvaluation,
+  ContextualizedProfile,
+  contextualizeEvaluation,
+  contextualizeProfile,
+  ConversionResult,
+  convertFile,
+  ExecJSON
+} from "inspecjs";
+import _ from "lodash";
+import Control from "../objects/control";
+import Profile from "../objects/profile";
+
+export function processEvaluation(evaluationInput: ContextualizedEvaluation) {
+  const topLevelProfile = evaluationInput.contains[0];
+  const profile = new Profile({
+    name: topLevelProfile.data.name,
+    title: topLevelProfile.data.title,
+    maintainer: topLevelProfile.data.maintainer,
+    copyright: topLevelProfile.data.copyright,
+    copyright_email: topLevelProfile.data.copyright_email,
+    license: _.get(topLevelProfile.data, "license"),
+    summary: _.get(topLevelProfile.data, "summary"),
+    description: _.get(topLevelProfile.data, "description"),
+    version: topLevelProfile.data.version,
+  });
+  topLevelProfile.contains.forEach((control) => {
+    profile.controls.push(
+      new Control({
+        id: control.data.id,
+        title: control.data.title,
+        impact: control.data.impact,
+        desc: control.data.desc,
+        descs: control.hdf.wraps.descriptions,
+        tags: control.hdf.wraps.tags,
+      })
+    );
+  });
+  return profile;
+}
+
+export function processProfileJSON(
+  profileInput: ContextualizedProfile
+): Profile {
+  const profile = new Profile({
+    name: profileInput.data.name,
+    title: profileInput.data.title,
+    maintainer: profileInput.data.maintainer,
+    copyright: profileInput.data.copyright,
+    copyright_email: profileInput.data.copyright_email,
+    license: _.get(profileInput.data, "license"),
+    summary: _.get(profileInput.data, "summary"),
+    description: _.get(profileInput.data, "description"),
+    version: profileInput.data.version,
+  });
+  profileInput.data.controls.forEach((control) => {
+    profile.controls.push(
+      new Control({
+        id: control.id,
+        title: control.title,
+        desc: control.desc,
+        impact: control.impact,
+        code: control.code,
+        tags: control.tags,
+        descs: control.descriptions,
+      })
+    );
+  });
+  return profile;
+}
+
+export function processExecJSON(execJSON: ExecJSON.Execution) {
+  return processEvaluation(contextualizeEvaluation(execJSON));
+}
+
+export function processJSON(json: string): Profile {
+  const convertedFile: ConversionResult = convertFile(json, true);
+  let profile = new Profile();
+  if (convertedFile["1_0_ExecJson"]) {
+    profile = processEvaluation(
+      contextualizeEvaluation(convertedFile["1_0_ExecJson"])
+    ).toUnformattedObject();
+  } else if (convertedFile["1_0_ProfileJson"]) {
+    profile = processProfileJSON(contextualizeProfile(JSON.parse(json))).toUnformattedObject();
+  } else {
+    throw new Error("Unknown file type passed");
+  }
+
+  profile.controls = _.sortBy(profile.controls, "id");
+
+  return profile;
+}

package/src/parsers/xccdf.ts

@@ -0,0 +1,74 @@
+import {data as CCINistMappings} from '@mitre/hdf-converters/lib/src/mappings/CciNistMappingData'
+import Profile from '../objects/profile';
+import { convertEncodedHTMLIntoJson, convertEncodedXmlIntoJson, impactNumberToSeverityString, severityStringToImpact } from '../utilities/xccdf';
+import { DecodedDescription, DisaStig } from '../types/xccdf';
+import Control from '../objects/control';
+import _ from 'lodash';
+
+export function processXCCDF(xml: string): Profile {
+    const parsedXML: DisaStig = convertEncodedXmlIntoJson(xml)
+    const groups = parsedXML.Benchmark.Group;
+
+    const profile = new Profile({
+        name: parsedXML.Benchmark['@_id'],
+        title: parsedXML.Benchmark.title,
+        summary: parsedXML.Benchmark.description
+    });
+
+    groups.forEach(group => {
+        const extractedDescription: DecodedDescription = convertEncodedHTMLIntoJson(group.Rule?.description)
+        const control = new Control({
+            id: group['@_id'],
+            title: group.Rule['@_severity'] ? group.Rule.title : `[[[MISSING SEVERITY FROM STIG]]] ${group.Rule.title}`,
+            desc: extractedDescription.VulnDiscussion?.split('Satisfies: ')[0],
+            impact: severityStringToImpact(group.Rule['@_severity'] || 'critical'),
+            descs: {
+                check: group.Rule.check['check-content'],
+                fix: group.Rule.fixtext['#text']
+            },
+            tags: _.omitBy({
+                severity: impactNumberToSeverityString(severityStringToImpact(group.Rule['@_severity'] || 'critical')),
+                gtitle: group.title,
+                satisfies: extractedDescription.VulnDiscussion?.includes('Satisfies: ') && extractedDescription.VulnDiscussion.split('Satisfies: ').length >= 1 ? extractedDescription.VulnDiscussion.split('Satisfies: ')[1].split(',').map(satisfaction => satisfaction.trim()) : undefined,
+                gid: group['@_id'],
+                rid: group.Rule['@_id'],
+                stig_id: group.Rule.version,
+                fix_id: group.Rule.fix['@_id'],
+                false_negatives: extractedDescription.FalseNegatives,
+                false_positives: extractedDescription.FalsePositives,
+                documentable: extractedDescription.Documentable,
+                mitigations: extractedDescription.Mitigations,
+                severity_override_guidance: extractedDescription.SeverityOverrideGuidance,
+                potential_impacts: extractedDescription.PotentialImpacts,
+                third_party_tools: extractedDescription.ThirdPartyTools,
+                mitigation_control: extractedDescription.MitigationControl, // This exists as mitigation_controls in inspec_tools, but is called mitigation_control in the xccdf, this shouldn't ever be defined but is still here for backwards compatibility
+                mitigation_controls: extractedDescription.MitigationControls,
+                responsibility: extractedDescription.Responsibility,
+                ia_controls: extractedDescription.IAControls
+            }, i => !Boolean(i))
+        })
+
+        if ('ident' in group.Rule) {
+            const identifiers = Array.isArray(group.Rule.ident) ? group.Rule.ident : [group.Rule.ident]
+            // Grab CCI/NIST/Legacy identifiers
+            identifiers.forEach(identifier => {
+              const identifierText = identifier['#text']
+              if (identifier['@_system'].toLowerCase().endsWith('cci')) {
+                control.tags.cci?.push(identifierText)
+                if (identifierText in CCINistMappings) {
+                  control.tags.nist?.push(_.get(CCINistMappings, identifierText))
+                }
+              }
+              if (identifier['@_system'].toLowerCase().endsWith('legacy')) {
+                control.tags.legacy?.push(identifierText)
+              } 
+            })
+          }
+
+        profile.controls.push(control)
+    })
+
+    profile.controls = _.sortBy(profile.controls, 'id')
+
+    return profile.toUnformattedObject()
+}

package/src/types/diff.d.ts

@@ -0,0 +1,9 @@
+import Control from "../objects/control"
+
+export type ProfileDiff = {
+    removedControlIDs: string[];
+    addedControlIDs: string[];
+    changedControls: {
+        [key: string]: Partial<Control>;
+    }
+}

package/src/types/xccdf.d.ts

@@ -0,0 +1,126 @@
+export interface DisaStig {
+    Benchmark: Benchmark;
+}
+
+export interface Benchmark {
+    '@_xmlns:dc':           string;
+    '@_xmlns:xsi':          string;
+    '@_xmlns:cpe':          string;
+    '@_xmlns:xhtml':        string;
+    '@_xmlns:dsig':         string;
+    '@_xsi:schemaLocation': string;
+    '@_id':                 string;
+    '@_xml:lang':           string;
+    '@_xmlns':              string;
+    status:                 Status;
+    title:                  string;
+    description:            string;
+    notice:                 Notice;
+    'front-matter':         Matter;
+    'rear-matter':          Matter;
+    reference:              BenchmarkReference;
+    'plain-text':           PlainText[];
+    version:                number;
+    Profile:                Group[];
+    Group:                  Group[];
+}
+
+export interface Group {
+    '@_id':      string;
+    title:       string;
+    description: string;
+    Rule:       Rule;
+    select?:     Select[];
+}
+
+export interface Rule {
+    '@_id':       string;
+    '@_weight':   string;
+    '@_severity': string;
+    version:      string;
+    title:        string;
+    description:  string;
+    reference:    RuleReference;
+    ident:        Ident[];
+    fixtext:      Fixtext;
+    fix:          Fix;
+    check:        Check;
+}
+
+export interface Check {
+    '@_system':          string;
+    'check-content-ref': CheckContentRef;
+    'check-content':     string;
+}
+
+export interface CheckContentRef {
+    '@_href': string;
+    '@_name': string;
+}
+
+export interface Fix {
+    '@_id': string;
+}
+
+export interface Fixtext {
+    '#text':    string;
+    '@_fixref': string;
+}
+
+export interface Ident {
+    '#text':    string;
+    '@_system': string;
+}
+
+export interface RuleReference {
+    'dc:title':      string;
+    'dc:publisher':  string;
+    'dc:type':       string;
+    'dc:subject':    string;
+    'dc:identifier': number;
+}
+
+export interface Select {
+    '@_idref':    string;
+    '@_selected': string;
+}
+
+export interface Matter {
+    '@_xml:lang': string;
+}
+
+export interface Notice {
+    '@_id':       string;
+    '@_xml:lang': string;
+}
+
+export interface PlainText {
+    '#text': string;
+    '@_id':  string;
+}
+
+export interface BenchmarkReference {
+    '@_href':       string;
+    'dc:publisher': string;
+    'dc:source':    string;
+}
+
+export interface Status {
+    '#text':  string;
+    '@_date': Date;
+}
+
+export interface DecodedDescription {
+    VulnDiscussion?: string;
+    FalsePositives?: string;
+    FalseNegatives?: string;
+    Documentable?: boolean;
+    Mitigations?: string;
+    SeverityOverrideGuidance?: string;
+    PotentialImpacts?: string;
+    ThirdPartyTools?: string;
+    MitigationControl?: string;
+    MitigationControls?: string;
+    Responsibility?: string;
+    IAControls?: string;
+}

package/src/utilities/diff.ts

@@ -0,0 +1,54 @@
+import { diff } from 'json-diff';
+import Profile from '../objects/profile';
+import { ProfileDiff } from '../types/diff';
+import _ from 'lodash'
+
+export function diffProfile(fromProfile: Profile, toProfile: Profile): ProfileDiff {
+    const profileDiff: ProfileDiff = {
+        addedControlIDs: [],
+        removedControlIDs: [],
+        changedControls: {}
+    };
+
+    const fromControlIDs = fromProfile.controls.map((control) => control.id).sort();
+    const toControlIDs = toProfile.controls.map((control) => control.id).sort();
+
+    // Find new controls
+    const controlIDDiff: string[][] = diff(fromControlIDs, toControlIDs)
+    controlIDDiff.forEach((diffValue) => {
+        if (diffValue[0] === '-') {
+            profileDiff.removedControlIDs.push(diffValue[1])
+        } else if (diffValue[0] === '+') {
+            profileDiff.addedControlIDs.push(diffValue[1])
+        }
+    })
+
+    // Add new controls to changedControls
+    profileDiff.addedControlIDs.forEach((addedControl) => {
+        const newControl = toProfile.controls.find((control) => addedControl === control.id)
+        if (newControl) {
+            profileDiff.changedControls[addedControl] = newControl
+        }
+    })
+
+    // Find changed controls
+    for (const fromControl of fromProfile.controls) {
+        const toControl = toProfile.controls.find((control) => control.id === fromControl.id)
+        if (toControl) {
+            const controlDiff: Record<string, any> | undefined = diff(fromControl, toControl);
+            if (controlDiff) {
+                Object.entries(controlDiff).forEach(([key, value]) => {
+                    if (_.has(value, '__new')) {
+                        _.set(profileDiff, 'changedControls.'+fromControl.id +'.'+key.replace('.', '\\.'), _.get(controlDiff, key+'.__new'))
+                    } else if (typeof value === 'object') {
+                        Object.entries(value).forEach(([subKey, subValue]) => {
+                            _.set(profileDiff, 'changedControls.'+fromControl.id +'.'+key.replace('.', '\\.')+'.'+subKey.replace('.', '\\.'), _.get(controlDiff, key+'.'+subKey+'.__new'))
+                        })
+                    }
+                })
+            }
+        }
+    }
+
+    return profileDiff
+}

package/src/utilities/global.ts

@@ -0,0 +1,23 @@
+import _ from "lodash";
+
+// Breaks lines down to lineLength number of characters
+export function wrap(s: string, lineLength = 80): string {
+  return s.replace(
+    new RegExp(`(?![^\n]{1,${lineLength}}$)([^\n]{1,${lineLength}})`, "g"),
+    "$1\n"
+  );
+}
+
+export function unformatText(s: string): string {
+  return s.replace(/\n/g, ' ').replace(/\\n/g, ' ').replace(/( +|\t)/g, ' ')
+}
+
+const escapeQuotes = (s: string) =>
+  s.replace(/\\/g, "\\\\").replace(/'/g, "\\'"); // Escape backslashes and quotes
+const escapeDoubleQuotes = (s: string) =>
+  s.replace(/\\/g, "\\\\").replace(/"/g, '\\"'); // Escape backslashes and double quotes
+
+const wrapAndEscapeQuotes = (s: string, lineLength?: number) =>
+  escapeDoubleQuotes(wrap(s, lineLength)); // Escape backslashes and quotes, and wrap long lines
+
+export { escapeQuotes, escapeDoubleQuotes, wrapAndEscapeQuotes };