Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

refactor: new CLI commands documentation #413

Merged
merged 16 commits into from
Aug 17, 2024
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 4 additions & 0 deletions .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -65,3 +65,7 @@ vuln.json
tmp/
dist/
reports

# macOS system files
.DS_Store

40 changes: 14 additions & 26 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -100,37 +100,25 @@ $ nsecure open
# If you want to define a specific port use the --port option.
$ nsecure open --port 8080
```
---

##### Available options

| name | shortcut | default value | description |
| --- | --- | --- | --- |
| --port | -p | 0 | Define the running port, can also be define through the environment variable `PORT` |

The `auto` command can be used to chain `cwd/from` and `open` commands automatically.
### Command Documentation

```bash
$ nsecure auto jest
For complete details on each command, refer to the following documents:

# if no package is given to the auto command then it will run the cwd command instead of from.
$ nsecure auto
```
- [`cwd`](./docs/cli/cwd.md)
- [`from`](./docs/cli/from.md)
- [`auto`](./docs/cli/auto.md)
- [`open`](./docs/cli/open.md)
- [`verify`](./docs/cli/verify.md)
- [`summary`](./docs/cli/summary.md)
- [`scorecard`](./docs/cli/scorecard.md)
- [`report`](./docs/cli/report.md)
- [`lang`](./docs/cli/lang.md)
- [`config create`](./docs/cli/config.md)
- [`config`](./docs/cli/config.md)

> [!IMPORTANT]
> By default with the auto command the .json file is deleted when the http server is closed. It's possible to disable this behavior by using the CLI option `--keep`, `-k`.

---
Some options are available on both `cwd`, `from` and `auto` commands. The output option is not available for the `auto` command.

| name | shortcut | default value | description |
| --- | --- | --- | --- |
| --depth | -d | **4** | the maximum depth we must walk (when we fetch the whole tree). |
| --output | -o | **nsecure-result** | the name that the outputted .json file will have |

```bash
$ nsecure from express -d 10 -o express-security-report
```
Each link redirects you to the complete documentation of the command, with additional details, options, and usage examples.

## Private registry / Verdaccio

Expand Down
18 changes: 18 additions & 0 deletions docs/cli/auto.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,18 @@
# 🚀 Command `auto`

The `auto` command combines the `cwd` and `from` commands to analyze and explore a local project or remote NPM packages in the WebUI.

## 📜 Syntax

```bash
nsecure auto [spec]
```

## ⚙️ Available Options

| Name | Shortcut | Default Value | Description |
|---|---|---|--|
| `--depth` | `-d` | `4` | Specify the depth of dependency analysis. |
| `--silent` | | | 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. |
22 changes: 22 additions & 0 deletions docs/cli/config.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,22 @@
# ⚙️ Command `config`

The `config` command allows you to manage the `.nodesecurerc` configuration file, which is used by NodeSecure components to customize their behavior. You can use this command to create a new configuration file or edit the existing one.

## 📜 Syntax

```bash
nsecure config [sub-command] [options]
```

## ⚙️ Available Options

### `create` Sub-command

| Name | Shortcut | Default Value | Description |
|---|---|---|---|
| `--cwd` | `-c` | `false` | Create the configuration file in the current working directory instead of the default location. |

### `edit` Sub-command

This sub-command does not have any specific options.

19 changes: 19 additions & 0 deletions docs/cli/cwd.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,19 @@
# 📂 Command `cwd`

The `cwd` command scans the project in the current working directory using the `package.json` and `package-lock.json` files, and stores the analysis results in a JSON file. You can then share this JSON or explore it in the WebUI using the `open` command.

## 📜 Syntax

```bash
nsecure cwd [options]
```

## ⚙️ Available Options

| Name | Shortcut | Default Value | Description |
|---|---|---|---|
| `--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. |
| `--output` | `-o` | `nsecure-result` | Specify the output file for the results. |
18 changes: 18 additions & 0 deletions docs/cli/from.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,18 @@
# 📦 Command `from`

The `from` command allows you to run a security analysis on a specific npm package, which must be available in the npm registry. This command is useful for evaluating the security of a package before including it in your project.

## 📜 Syntax

```bash
nsecure from <package> [options]
```

## ⚙️ Available Options

| Name | Shortcut | Default Value | Description |
|---|---|---|---|
| `--depth` | `-d` | `4` | Specify the depth of dependency analysis. |
| `--output` | `-o` | `nsecure-result` | Specify the output file for the results. |
| `--silent` | | | Suppress console output, making execution silent. |

9 changes: 9 additions & 0 deletions docs/cli/lang.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,9 @@
## 📝 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

## 📜 Syntax

```bash
nsecure lang
```
22 changes: 22 additions & 0 deletions docs/cli/open.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,22 @@
## 📝 Command `open`

The `open` command reads a specified JSON payload and starts a local HTTP server. This allows you to explore dependencies, their metrics, and potential threats directly in your web browser.

## 📜 Syntax

```bash
nsecure open [json]
```

fraxken marked this conversation as resolved.
Show resolved Hide resolved
> [!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 |
|---|---|---|---|
| `--port` | `-p` | `process.env.PORT` | Specify the port on which the HTTP server should run. |

19 changes: 19 additions & 0 deletions docs/cli/report.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,19 @@
## 📝 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.

## 📜 Syntax

```bash
nsecure report [repository]
```

## ⚙️ Available Options

| Name | Shortcut | Default Value | Description |
|---|---|---|---|
| `--theme` | `-t` | `white` | Specify the theme for the report. |
| `--includesAllDeps` | `-i` | `true` | Include all dependencies in the report. |
| `--title` | `-l` | `NodeSecure Report` | Specify the title of the report. |
| `--reporters` | `-r` | `["html"]` | Specify the format of the report (e.g., HTML, JSON). |

16 changes: 16 additions & 0 deletions docs/cli/scorecard.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,16 @@
## 📝 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.

## 📜 Syntax

```bash
nsecure scorecard [repository]
```

## ⚙️ Available Options

| Name | Shortcut | Default Value | Description |
|---|---|---|---|
| `--vcs` | | `github` | Specify the version control system (VCS) used by the repository. |

9 changes: 9 additions & 0 deletions docs/cli/summary.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,9 @@
## 📝 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.

## 📜 Syntax

```bash
nsecure summary [json]
```
15 changes: 15 additions & 0 deletions docs/cli/verify.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,15 @@
## 📝 Command `verify`

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.

## 📜 Syntax

```bash
nsecure verify [package]
```

## ⚙️ Available Options

| Name | Shortcut | Default Value | Description |
|---|---|---|---|
| `--json` | `-j` | `false` | Output the results in JSON format. |