Merge pull request #421 from NodeSecure/enhance-commands-docs

fraxken · web-flow · commit 29d1c9c8884e · 2024-08-18T15:22:44.000+02:00
docs: enhance CLI commands &amp; usage examples
diff --git a/README.md b/README.md
@@ -58,12 +58,9 @@ or
 $ git clone https://github.com/NodeSecure/cli.git
 $ cd cli
 
-# install NPM dependencies
 $ npm install
-
-# run esbuild to bundle/compile front-end assets
+# bundle/compile front-end assets
 $ npm run build
-
 $ npm link
 ```
 
@@ -77,32 +74,29 @@ $ nsecure auto express
 
 ## 👀 Usage example
 
-To show the complete list of commands
-```bash
-$ nsecure --help
-```
-
----
-
 ```bash
-# Run an analysis on the current working dir (must have a package.json file).
+# Run a scan on the current working dir
+# Note: must have a package.json or node_modules directory
 $ nsecure cwd
 
-# Run an analysis for a given 'npm' package (must be in the npm registry).
+# Run a scan on a remote 'npm' package
 $ nsecure from mocha
 ```
 
 Then a `nsecure-result.json` will be writted at the current CLI location. To open it on a web page just run
 
 ```bash
 $ nsecure open
-
-# If you want to define a specific port use the --port option.
-$ nsecure open --port 8080
 ```
 
 ### Command Documentation
 
+The CLI includes built-in documentation accessible with the --help option:
+```bash
+$ nsecure --help
+$ nsecure <command> --help
+```
+
 For complete details on each command, refer to the following documents:
 
 - [`cwd`](./docs/cli/cwd.md)
@@ -117,8 +111,7 @@ For complete details on each command, refer to the following documents:
 - [`config create`](./docs/cli/config.md)
 - [`config`](./docs/cli/config.md)
 
-
-Each link redirects you to the complete documentation of the command, with additional details, options, and usage examples.
+Each link provides access to the full documentation for the command, including additional details, options, and usage examples.
 
 ## Private registry / Verdaccio
 
diff --git a/bin/index.js b/bin/index.js
@@ -46,22 +46,25 @@ defaultScannerCommand("cwd", { strategy: vulnera.strategies.GITHUB_ADVISORY })
   .describe(i18n.getTokenSync("cli.commands.cwd.desc"))
   .option("-n, --nolock", i18n.getTokenSync("cli.commands.cwd.option_nolock"), false)
   .option("-f, --full", i18n.getTokenSync("cli.commands.cwd.option_full"), false)
-  .action(async(...options) => {
+  .action(async(options) => {
     checkNodeSecureToken();
-    await commands.scanner.cwd(...options);
+    await commands.scanner.cwd(options);
   });
 
-defaultScannerCommand("from <package>")
+defaultScannerCommand("from <spec>")
   .describe(i18n.getTokenSync("cli.commands.from.desc"))
-  .action(async(...options) => {
+  .action(async(spec, options) => {
     checkNodeSecureToken();
-    await commands.scanner.from(...options);
+    await commands.scanner.from(spec, options);
   });
 
-defaultScannerCommand("auto [package]", { includeOutput: false, strategy: vulnera.strategies.GITHUB_ADVISORY })
+defaultScannerCommand("auto [spec]", { includeOutput: false, strategy: vulnera.strategies.GITHUB_ADVISORY })
   .describe(i18n.getTokenSync("cli.commands.auto.desc"))
   .option("-k, --keep", i18n.getTokenSync("cli.commands.auto.option_keep"), false)
-  .action(commands.scanner.auto);
+  .action(async(spec, options) => {
+    checkNodeSecureToken();
+    await commands.scanner.auto(spec, options);
+  });
 
 prog
   .command("open [json]")
@@ -70,12 +73,12 @@ prog
   .action(commands.http.start);
 
 prog
-  .command("verify [package]")
+  .command("verify [spec]")
   .describe(i18n.getTokenSync("cli.commands.verify.desc"))
   .option("-j, --json", i18n.getTokenSync("cli.commands.verify.option_json"), false)
-  .action(async(...options) => {
+  .action(async(spec, options) => {
     checkNodeSecureToken();
-    await commands.verify.main(...options);
+    await commands.verify.main(spec, options);
   });
 
 prog
@@ -120,7 +123,7 @@ function defaultScannerCommand(name, options = {}) {
   const { includeOutput = true, strategy = null } = options;
 
   const cmd = prog.command(name)
-    .option("-d, --depth", i18n.getTokenSync("cli.commands.option_depth"), 4)
+    .option("-d, --depth", i18n.getTokenSync("cli.commands.option_depth"), Infinity)
     .option("--silent", i18n.getTokenSync("cli.commands.option_silent"), false);
 
   if (includeOutput) {
diff --git a/docs/cli/auto.md b/docs/cli/auto.md
@@ -5,14 +5,25 @@ The `auto` command combines the `cwd` and `from` commands to analyze and explore
 ## 📜 Syntax
 
 ```bash
-nsecure auto [spec]
+$ nsecure auto [spec]
+```
+
+Omitting the `[spec]` option is equivalent to running the `cwd` and `open` commands together. If `[spec]` is provided, the `from` command will be used instead.
+
+## 👀 Example
+
+By default, when using the `auto` command, the JSON payload is deleted once the HTTP server is closed. If you want to keep the JSON file to share or re-open it later, simply add the `--keep` or `-k` option.
+
+```bash
+$ nsecure auto --keep
 ```
 
 ## ⚙️ Available Options
 
 | Name | Shortcut | Default Value | Description |
 |---|---|---|--|
-| `--depth` | `-d` | `4` | Specify the depth of dependency analysis. |
-| `--silent` |   |   | Suppress console output, making execution silent. |
+| `--depth` | `-d` | `Infinity` | Maximum tree depth to scan. |
+| `--silent` |   | `false` | Suppress console output, making execution silent. |
 | `--output` | `-o` | `nsecure-result` | Specify the output file for the results. |
-| `--keep` | `-k` | `false` | Preserve temporary files after execution. |
+| `--vulnerabilityStrategy` | `-s` | github-advisory | Strategy used to fetch package vulnerabilities (see Vulnera [available strategy](https://github.com/NodeSecure/vulnera?tab=readme-ov-file#available-strategy)). |
+| `--keep` | `-k` | `false` | Preserve JSON payload after execution. |
diff --git a/docs/cli/config.md b/docs/cli/config.md
@@ -5,7 +5,9 @@ The `config` command allows you to manage the `.nodesecurerc` configuration file
 ## 📜 Syntax
 
 ```bash
-nsecure config [sub-command] [options]
+$ nsecure config create [options]
+# OR
+$ nsecure config edit
 ```
 
 ## ⚙️ Available Options
@@ -19,4 +21,3 @@ nsecure config [sub-command] [options]
 ### `edit` Sub-command
 
 This sub-command does not have any specific options.
-
diff --git a/docs/cli/cwd.md b/docs/cli/cwd.md
@@ -5,7 +5,7 @@ The `cwd` command scans the project in the current working directory using the `
 ## 📜 Syntax
 
 ```bash
-nsecure cwd [options]
+$ nsecure cwd [options]
 ```
 
 ## ⚙️ Available Options
@@ -14,6 +14,7 @@ nsecure cwd [options]
 |---|---|---|---|
 | `--nolock` | `-n` | `false` | Do not use a lock file (package-lock.json or yarn.lock) for the analysis. |
 | `--full` | `-f` | `false` | Perform a full analysis of the project, including all dependencies. |
-| `--depth` | `-d` | `4` | Specify the depth of dependency analysis. |
-| `--silent` |   |   | Suppress console output, making execution silent. |
+| `--depth` | `-d` | `Infinity` | Maximum tree depth to scan. |
+| `--silent` |   | `false` | Suppress console output, making execution silent. |
 | `--output` | `-o` | `nsecure-result` | Specify the output file for the results. |
+| `--vulnerabilityStrategy` | `-s` | github-advisory | Strategy used to fetch package vulnerabilities (see Vulnera [available strategy](https://github.com/NodeSecure/vulnera?tab=readme-ov-file#available-strategy)). |
diff --git a/docs/cli/from.md b/docs/cli/from.md
@@ -5,14 +5,22 @@ The `from` command allows you to run a security analysis on a specific npm packa
 ## 📜 Syntax
 
 ```bash
-nsecure from <package> [options]
+$ nsecure from <spec> [options]
+```
+
+## 👀 Example
+
+Scanning version 3.0.0 of express and saving the result into `./express-report.json`
+
+```bash
+$ nsecure from express@3.0.0 -o express-report
 ```
 
 ## ⚙️ Available Options
 
 | Name | Shortcut | Default Value | Description |
 |---|---|---|---|
-| `--depth` | `-d` | `4` | Specify the depth of dependency analysis. |
+| `--depth` | `-d` | `Infinity` | Maximum tree depth to scan. |
+| `--silent` |   | `false` | Suppress console output, making execution silent. |
 | `--output` | `-o` | `nsecure-result` | Specify the output file for the results. |
-| `--silent` |   |   | Suppress console output, making execution silent. |
-
+| `--vulnerabilityStrategy` | `-s` | github-advisory | Strategy used to fetch package vulnerabilities (see Vulnera [available strategy](https://github.com/NodeSecure/vulnera?tab=readme-ov-file#available-strategy)). |
diff --git a/docs/cli/images/lang.PNG b/docs/cli/images/lang.PNG
diff --git a/docs/cli/images/scorecard.PNG b/docs/cli/images/scorecard.PNG
diff --git a/docs/cli/images/summary.PNG b/docs/cli/images/summary.PNG
diff --git a/docs/cli/images/verify.PNG b/docs/cli/images/verify.PNG
diff --git a/docs/cli/lang.md b/docs/cli/lang.md
@@ -1,9 +1,16 @@
 ## 📝 Command `lang`
 
-The `lang` command allows you to set your preferred language. Use this command to customize the language used in the CLI or Web interfaces
+The `lang` command allows you to set your preferred language. Use this command to customize the language used in the CLI or Web interfaces.
+
+<p align="center">
+<img src="./images/lang.PNG">
+</p>
+
+> [!NOTES]
+> Feel free to help us translate this tool into other languages. Translations can be found in the root `./i18n` folder.
 
 ## 📜 Syntax
 
 ```bash
-nsecure lang
+$ nsecure lang
 ```
diff --git a/docs/cli/open.md b/docs/cli/open.md
@@ -5,15 +5,12 @@ The `open` command reads a specified JSON payload and starts a local HTTP server
 ## 📜 Syntax
 
 ```bash
-nsecure open [json]
+$ nsecure open [json]
 ```
 
 > [!NOTE]
 > If the `[json]` property is omitted, the command will default to searching for a `nsecure-result.json` file in the current working directory.
 
->[!NOTE]
-> If the `[json]` property is omitted, the command will default to searching for a `nsecure-result.json` file in the current working directory.
-> 
 ## ⚙️ Available Options
 
 | Name | Shortcut | Default Value | Description |
diff --git a/docs/cli/report.md b/docs/cli/report.md
@@ -1,11 +1,16 @@
 ## 📝 Command `report`
 
-The `report` command generates a detailed security report for a repository in PDF format. The report can include all dependencies and can be customized with various options.
+The `report` command generates a detailed security report for a repository in PDF format (using [@nodesecure/report](https://github.com/NodeSecure/report)). The report can include all dependencies and can be customized with various options.
+
+<p align="center">
+<img src="https://camo.githubusercontent.com/a0611e28412fccf7ebc63b0f2ffca18055c04c3d144f4da98d149d064f59674b/68747470733a2f2f692e696d6775722e636f6d2f4a6872373645662e6a7067">
+</p>
+
 
 ## 📜 Syntax
 
 ```bash
-nsecure report [repository]
+$ nsecure report [repository]
 ```
 
 ## ⚙️ Available Options
diff --git a/docs/cli/scorecard.md b/docs/cli/scorecard.md
@@ -1,16 +1,23 @@
 ## 📝 Command `scorecard`
 
-The `scorecard` command is used to generate an OpenSSF scorecard for a specific GIT repository or NPM package. This command evaluates the repository and provides a security score based on various criteria.
+The `scorecard` command is used to generate an [OpenSSF scorecard](https://openssf.org/projects/scorecard/) for a specific GIT repository or NPM package.
+
+This command evaluates the repository and provides a security score based on various criteria.
+
+<p align="center">
+<img src="./images/scorecard.PNG">
+</p>
+
+Under the hood it use our [OpenSSF scorecard SDK for Node.js](https://github.com/NodeSecure/ossf-scorecard-sdk)
 
 ## 📜 Syntax
 
 ```bash
-nsecure scorecard [repository]
+$ nsecure scorecard [repository]
 ```
 
 ## ⚙️ Available Options
 
 | Name | Shortcut | Default Value | Description |
 |---|---|---|---|
 | `--vcs` |   | `github` | Specify the version control system (VCS) used by the repository. |
-
diff --git a/docs/cli/summary.md b/docs/cli/summary.md
@@ -1,9 +1,16 @@
 ## 📝 Command `summary`
 
-The `summary` command is used to generate a summarized report from a JSON security report. This command provides a concise overview of the security findings.
+The `summary` command generates a summarized report from a specified JSON payload.
+
+<p align="center">
+<img src="./images/summary.PNG">
+</p>
 
 ## 📜 Syntax
 
 ```bash
-nsecure summary [json]
+$ nsecure summary [json]
 ```
+
+> [!NOTE]
+> If the `[json]` property is omitted, the command will default to searching for a `nsecure-result.json` file in the current working directory.
diff --git a/docs/cli/verify.md b/docs/cli/verify.md
@@ -2,12 +2,19 @@
 
 The `verify` command performs a deep analysis of a specified NPM package. It provides advanced information about the files in the tarball, including details on potential threats, file integrity, and more.
 
+<p align="center">
+<img src="./images/verify.PNG">
+</p>
+
 ## 📜 Syntax
 
 ```bash
-nsecure verify [package]
+$ nsecure verify [spec]
 ```
 
+> [!NOTE]
+> If the `[spec]` property is omitted, the command will default to searching the local project manifest to extract it's name + version.
+
 ## ⚙️ Available Options
 
 | Name | Shortcut | Default Value | Description |
diff --git a/src/commands/scanner.js b/src/commands/scanner.js
