Adding Markdown Table Reporting to Summary, and more .... (#2186)

* Adding Markdown Table Reporting to Summary, and more .... - Refactored and simplified the summary code - Documented everything - Added a more logicical set of flags so that you could both output to stdout and a file at the same time or either - Added Logging to Summary - Added Unit Tests - Still need to add a Markdown Table Test - The JSON and YAML tests are passing Signed-off-by: Aaron Lippold <[email protected]> Signed-off-by: Emily Rodriguez <[email protected]> Co-authored-by: Emily Rodriguez <[email protected]> Co-authored-by: Emily Rodriguez <[email protected]>
mitre · Jan 19, 2024 · 01dffae · 01dffae
1 parent 7cc4e34
commit 01dffae
Show file tree

Hide file tree

Showing 34 changed files with 5,697 additions and 3,786 deletions.
diff --git a/.eslintrc b/.eslintrc
@@ -21,6 +21,7 @@
     "unicorn/prefer-json-parse-buffer": "off",
     "camelcase": "off",
     "no-console": "off",
+    "no-unused-expressions": "off",
     "node/no-missing-import": "off",
     "complexity": "off",
     "no-constant-condition": "off",

diff --git a/.gitignore b/.gitignore
@@ -1,3 +1,4 @@
+generatedMD.md
 *-debug.log
 *-error.log
 /.nyc_output
@@ -11,3 +12,6 @@ node_modules
 out
 .env
 *.tgz
+**/saf-cli.log
+*.html
+saf-cli.log
diff --git a/.nvmrc b/.nvmrc
@@ -0,0 +1 @@
+v18.18
diff --git a/.vscode/launch.json b/.vscode/launch.json
@@ -0,0 +1,27 @@
+{
+  "version": "0.2.0",
+  "configurations": [
+    {
+      "type": "node",
+      "request": "launch",
+      "name": "Debug MarkdownTable",
+      "runtimeExecutable": "node --inspect", // replace with your actual path
+      "program": "${workspaceFolder}/bin/run",
+      "args": [
+        "view",
+        "summary",
+        "-i",
+        "test/sample_data/HDF/input/rhel-8_hardened.json",
+        "--format",
+        "markdown",
+        "--logLevel",
+        "verbose"
+      ],
+      "console": "integratedTerminal",
+      "internalConsoleOptions": "neverOpen",
+      "outFiles": ["${workspaceFolder}/dist/**/*.js"],
+      "preLaunchTask": "tsc: build - tsconfig.json",
+      "sourceMaps": true
+    }
+  ]
+}
diff --git a/Dockerfile b/Dockerfile
@@ -1,4 +1,4 @@
-ARG BASE_CONTAINER=node:18-alpine
+ARG BASE_CONTAINER=node:18.18-alpine
 
 FROM $BASE_CONTAINER AS builder
 

diff --git a/README.md b/README.md
@@ -4,12 +4,16 @@ The MITRE Security Automation Framework (SAF) Command Line Interface (CLI) bring
 
 The SAF CLI is the successor to [Heimdall Tools](https://github.com/mitre/heimdall_tools) and [InSpec Tools](https://github.com/mitre/inspec_tools).
 
-## Terminology:
+## Terminology
 
-- "[Heimdall](https://github.com/mitre/heimdall2)" - Our visualizer for all security result data
-- "[Heimdall Data Format (HDF)](https://saf.mitre.org/#/normalize)" - Our common data format to preserve and transform security data
+- [Heimdall](https://github.com/mitre/heimdall2) - Our visualizer for all security result data
+- [Heimdall Data Format (HDF)](https://saf.mitre.org/#/normalize) - Our common data format to preserve and transform security data
 
-## Installation:
+## Development Testing & Contribution
+
+- [Development, Testing & Contribution Guide](#development-testing--contribution)
+
+## Installation
 
   * [Via NPM](#installation-via-npm)
       * [Update via NPM](#update-via-npm)
@@ -117,6 +121,10 @@ The SAF CLI is the successor to [Heimdall Tools](https://github.com/mitre/heimda
 
 ---
 
+## Development, Testing and Contributing
+
+See the [Contributor's Guide](./docs/contributors-guide.md) for more information
+
 ## Installation
 
 ___
@@ -418,7 +426,7 @@ convert hdf2csv               Translate a Heimdall Data Format JSON file into a
     -h, --help                              Show CLI help.
     -i, --input=<hdf-scan-results-json>     (required) Input HDF file
     -o, --output=<output-csv>               (required) Output CSV file
-    -t, --noTruncate                        Don't truncate fields longer than 32,767 characters (the cell limit in Excel)
+    -t, --noTruncate                        Do not truncate fields longer than 32,767 characters (the cell limit in Excel)
 
   EXAMPLES
     $ saf convert hdf2csv -i rhel7-results.json -o rhel7.csv --fields "Results Set,Status,ID,Title,Severity"
@@ -1038,7 +1046,7 @@ ___
 
 You can start a local Heimdall Lite instance to visualize your findings with the SAF CLI. To start an instance use the `saf view heimdall` command:
 
-```
+```shell
 view heimdall                 Run an instance of Heimdall Lite to
                               visualize your data
   USAGE
@@ -1047,7 +1055,7 @@ view heimdall                 Run an instance of Heimdall Lite to
   FLAGS
     -f, --files=<file>...   File(s) to display in Heimdall
     -h, --help              Show CLI help.
-    -n, --noOpenBrowser     Don't open the default browser automatically
+    -n, --noOpenBrowser     Do not open the default browser automatically
     -p, --port=<port>       [default: 3000] Port To Expose Heimdall On (Default 3000)
 
   ALIASES
@@ -1060,26 +1068,49 @@ view heimdall                 Run an instance of Heimdall Lite to
 
 #### Summary
 
-To get a quick compliance summary from an HDF file (grouped by profile name) use the `saf view summary` command:
+Generate a comprehensive summary of compliance data, including totals and counts, from your OHDF files.
 
-```
-view summary                  Get a quick compliance overview of an HDF file
+The output can be displayed in the console, or exported as YAML, JSON, or a GitHub-flavored Markdown table.
 
-  USAGE
-    $ saf view summary -i <hdf-file> [-h] [-j] [-o <output>]
+```powershell
+USAGE
+  $ saf view summary -i <value> [-o <value>] [-f json|yaml|markdown] [-s]
+    [-r] [-t] [-l <value>] [-h]
 
-  FLAGS
-    -h, --help                  Show CLI help.
-    -i, --input=<hdf-file>...   (required) Input HDF files
-    -j, --json                  Output results as JSON
-    -o, --output=<output>
+FLAGS
+  -h, --help  Show help information
 
-  ALIASES
-    $ saf summary
+FORMATTING FLAGS
+  -f, --format=<option>    [default: yaml] Specify output format
+                           <options: json|yaml|markdown>
+  -r, --[no-]print-pretty  Enable human-readable data output
+  -t, --[no-]title-table   Add titles to the markdown table(s)
 
-  EXAMPLES
-    $ saf view summary -i rhel7-results.json
-    $ saf view summary -i rhel7-host1-results.json nginx-host1-results.json mysql-host1-results.json
+I/O FLAGS
+  -i, --input=<value>...  (required) Specify input HDF file(s)
+  -o, --output=<value>    Specify output file(s)
+  -s, --[no-]stdout       Enable printing to console
+
+DEBUGGING FLAGS
+  -l, --logLevel=<value>  [default: info] Set log level
+
+DESCRIPTION
+  Generate a comprehensive summary of compliance data, including totals and
+  counts, from your HDF files. The output can be displayed in the console, or
+  exported as YAML, JSON, or a GitHub-flavored Markdown table.
+
+ALIASES
+  $ saf summary
+
+EXAMPLES
+  $ saf summary -i input.hdf                                              # Summarize 'input.hdf' single HDF file
+  $ saf summary -i input.json --format=json                               # Specify Formats
+  $ saf summary -i input.json --format=markdown --no-stdout -o output.md  # Output GitHub Flavored Markdown Table, skip the console, and save to 'output.md'
+  $ saf summary --input input1.hdf --input input2.hdf                     # Summarize multiple HDF files
+  $ saf summary --input input1.hdf input2.hdf
+  $ saf summary -i input.hdf --output output.json                         # Save summary to 'output.json' and print to the console
+  $ saf summary --input input.hdf --pretty-print                          # Enable human-readable output
+  $ saf summary -i input.hdf --no-pretty-print                            # Useful for scripts or data-processing (RAW yaml/json/etc.)
 ```
 [top](#view-hdf-summaries-and-data)
 

diff --git a/docs/contributors-guide.md b/docs/contributors-guide.md
@@ -0,0 +1,96 @@
+# MITRE `saf-cli` Develpment, Testing and Contribution Guide
+
+The MITRE saf-cli is an OCLIF application developed with TypeScript.
+
+## Prerequisites
+
+- Node.js (check the package.json file for the current version)
+- npm (version 6 or newer)
+
+## Installation
+
+To install the project, clone the repository and install the dependencies:
+
+```bash
+git clone https://github.com/mitre/saf.git
+cd project
+npm install
+```
+
+## Development
+
+To start the development server, run:
+
+```bash
+npm run dev -- ${command you destire to run & its flags}
+```
+
+This script will clean the `lib` directory, compile the TypeScript files, and start the application. You can pass arguments to the `dev` script using the `--` syntax. For example:
+
+```bash
+npm run dev -- --help
+npm run dev -- view summary
+```
+
+## Testing
+
+We use both ts-mocha/chai and ts-jest for testing.
+
+### Command Tests
+
+The 'command' tests are located in the `./tests/commands` directory and organized by the OCLIF commands such as attest, view, generate etc. These tests are written in ts-mocha. You can run all the tests or a single test. For example:
+
+```bash
+npm run test:mocha
+npm run test:mocha:one ./tests/command/view/summary.ts
+```
+
+### Utility Tests
+
+The 'utility' tests are located in the `./tests/utility` directory and organized by each of the utility classes of the saf-cli. These tests are a mix of chai and jest tests. The chai tests are all the files named `{utility}.test.ts` and the jest tests are located in the `__tests__` directory. You can run all the tests or a single test. For example:
+
+```bash
+npm run test:jest
+npm run test:jest:one ./tests/utility/calculations.test.ts
+```
+
+## Linting
+
+We use ESLint with the TypeScript ESLint plugin for linting. To run the linter, use:
+
+```bash
+npm run lint
+npm run lint --fix
+```
+
+## Building
+
+To build the project, use:
+
+```bash
+npm run prepack
+```
+
+This script will clean the `lib` directory and compile the TypeScript files.
+
+## Usage
+
+Here's how you can use the CLI:
+
+```bash
+./bin/run command-name
+```
+
+You can get help on the available commands with:
+
+```bash
+./bin/run --help
+```
+
+## Contributing
+
+Contributions are welcome! We use the standard GitFlow model for PRs. Please ensure that your PRs pass all tests and close all related issues. We also use a semver-based release process.
+
+## License
+
+See the LICENSE and NOTICE files at the root of the project.
diff --git a/pack-heimdall-lite.sh b/pack-heimdall-lite.sh
@@ -2,7 +2,7 @@
 
 set -o errexit   # abort on nonzero exitstatus
 set -o nounset   # abort on unbound variable
-set -o pipefail  # don't hide errors within pipes
+set -o pipefail  # do not hide errors within pipes
 
 ORIGINAL=$PWD
 echo $ORIGINAL