Skip to content

Commit

Permalink
docs: Readme edit pass
Browse files Browse the repository at this point in the history 
Fixes: #135
PR-URL: #136
  • Loading branch information
@Fishrock123
Fishrock123 committed Apr 15, 2019
1 parent c8db290 commit 2cd778a
Showing 1 changed file with 60 additions and 120 deletions.
180 changes: 60 additions & 120 deletions README.md
View file
Expand Up @@ -2,54 +2,38 @@

[![Build Status](https://travis-ci.org/nodesource/ncm-cli.svg?branch=master)](https://travis-ci.org/nodesource/ncm-cli)

`ncm-cli` is a command-line tool for NodeSource Certified Modules 2.0, designed to make code quality, security, and compliance a breeze. Generate a custom project report, fetch compliance and security information, manage organizational whitelists, and inspect specific packages in greater detail -- all from the command-line.
The command-line tool for NodeSource Certified Modules 2.0 — designed to make code quality, security, and compliance a breeze. Generate a custom project report, fetch compliance and security information, manage organizational whitelists, and inspect specific packages in greater detail — all from the command-line.

## Installation

```
npm install -g ncm-cli
$ npm install -g ncm-cli
```

## Usage

```
Usage:
┌─────────────────────────┐
│ ncm <command> [options] │
└─────────────────────────┘
-h, --help Display help for any command OR this message
-v, --version Print ncm CLI version
ncm details <module>
ncm details <module@version>
ncm report
ncm report <directory>
-l, --long
-c --compliance
-s --security
--filter=<value>
ncm signin (interactive)
-g, --github Sign in via GitHub account
-G, --google Sign in via Google account
$ ncm <command> [options]
```

ncm signout
```
$ ncm help <command>
```

## Authentication

`ncm-cli` supports three forms of authentication.
`ncm-cli` supports three forms of authentication (required).

### 1. NodeSource Account:

Sign-in interactively using your [NodeSource account](https://accounts.nodesource.com) email and password.

```
$ ncm signin
```

### 2. Single Sign-on

* Using a Google account: `ncm signin -G, --google`
* Using a GitHub account: `ncm signin -g, --github`

Expand All @@ -59,14 +43,18 @@ $ ncm signin
$ NCM_TOKEN=<token> ncm <command> [options]
```

Learn more about obtaining service tokens and configuring permissions [here](https://docs.nodesource.com/ncm_v2/docs#ci-setup).
Learn more about obtaining NodeSource service tokens and configuring permissions [here](https://docs.nodesource.com/ncm_v2/docs#ci-setup).

## `ncm report`

Generate and return a project report (defaults to the current directory) outlining package certification. To specify a directory on which to generate a report, simply pass the directory following the command. The top five riskiest modules will be displayed alongside your concise project report.
Generates a project-wide report of directory risk and quality of installed or specified packages.
The top five riskiest modules detected will be displayed alongside a concise project report.

The directory to generate a report from may be specified via `ncm report <dir>`.
Defaults to using the current working directory.

```
$ ncm report /path/to/foo
$ ncm report
╔════════════╗
║ foo Report ║
Expand Down Expand Up @@ -101,7 +89,9 @@ $ ncm report /path/to/foo
└──────────────────────────────────────────┴────────────┴───────────────────────┴───────────────┘
```

By passing `--long, -l`, the returned report will be formatted to give greater detail into individual package certification. This will include the module name, version, risk score, license compliance, and respective security vulnerabilities.
### Full Reports

A report with a list of all modules can be generated by passing `--long, -l`.

```
$ ncm report --long
Expand Down Expand Up @@ -141,78 +131,32 @@ $ ncm report --long
│ formidable @ 1.0.16 │ |||| High │ X UNKNOWN │ ✓ 0 │
│ mime @ 1.2.11 │ |||| High │ X UNKNOWN │ X 1L │
│ qs @ 2.3.3 │ |||| High │ ✓ BSD-2-Clause │ X 1H │
│ cookiejar @ 2.0.6 │ |||| Med │ ✓ MIT │ ✓ 0 │
│ ms @ 2.0.0 │ |||| Med │ ✓ MIT │ ✓ 0 │
│ readable-stream @ 1.0.27-1 │ |||| Med │ ✓ MIT │ ✓ 0 │
│ string_decoder @ 0.10.31 │ |||| Med │ ✓ MIT │ ✓ 0 │
│ async @ 1.5.2 │ |||| Low │ ✓ MIT │ ✓ 0 │
│ combined-stream @ 1.0.7 │ |||| Low │ ✓ MIT │ ✓ 0 │
│ component-emitter @ 1.2.1 │ |||| Low │ ✓ MIT │ ✓ 0 │
│ core-util-is @ 1.0.2 │ |||| Low │ ✓ MIT │ ✓ 0 │
│ delayed-stream @ 1.0.0 │ |||| Low │ ✓ MIT │ ✓ 0 │
│ extend @ 3.0.0 │ |||| Low │ ✓ MIT │ X 1L │
│ inherits @ 2.0.3 │ |||| Low │ ✓ ISC │ ✓ 0 │
│ isarray @ 0.0.1 │ |||| Low │ ✓ MIT │ ✓ 0 │
│ mime-db @ 1.38.0 │ |||| Low │ ✓ MIT │ ✓ 0 │
│ reduce-component @ 1.0.1 │ |||| Low │ ✓ Apache-2.0 │ ✓ 0 │
│ debug @ 2.6.9 │ |||| None │ ✓ MIT │ ✓ 0 │
│ methods @ 1.1.2 │ |||| None │ ✓ MIT │ ✓ 0 │
│ mime-types @ 2.1.22 │ |||| None │ ✓ MIT │ ✓ 0 │
└──────────────────────────────────────────┴────────────┴───────────────────────┴───────────────┘
```

The report feature also includes the ability to filter depending on specified criteria.

### Filter: Compliance
To display only non-compliant packages, pass the `--compliance, -c` flag.
### Filter: Security
To display packages which contain at least one security vulnerability, pass the `--security, -s` flag.

### Filter: Vulnerability Severity
You may also filter the report based on one or more severity levels. `ncm-cli` supports the following levels of severity: critical, high, medium, low. Passing the `--filter=` flag along with one or more of these filter parameters will result in a report that displays only packages that contain at least one such vulnerability.
... etc ...
│ mime-types @ 2.1.22 │ |||| None │ ✓ MIT │ ✓ 0 │
└──────────────────────────────────────────┴────────────┴───────────────────────┴───────────────┘
```
$ ncm report --filter=high,medium
╔════════════╗
║ foo Report ║
╚════════════╝

24 packages checked
### Filters

! 3 critical risk
4 high risk
4 medium risk
10 low risk
Reports may be filtered based on any of the following flags:

! 7 security vulnerabilities found across 6 modules
|➔ Run `ncm report --filter=security` for a list
- `--compliance, -c` - only display non-compliant packages.
- `--security, -s` - only display packages with vulnerabilities.

! 2 noncompliant modules found
|➔ Run `ncm report --filter=compliance` for a list
─────────────────────────────────────────────────────────────────────────────────────────────────
null
-------------------------------------------------------------------------------------------------
Module Name Risk License Security
┌──────────────────────────────────────────┬────────────┬───────────────────────┬───────────────┐
│ qs @ 6.3.1 │ |||| Crit │ ✓ BSD-3-Clause │ X 1H │
│ superagent @ 1.8.5 │ |||| Crit │ ✓ MIT │ X 1M 1L │
│ qs @ 2.3.3 │ |||| High │ ✓ BSD-2-Clause │ X 1H │
└──────────────────────────────────────────┴────────────┴───────────────────────┴───────────────┘
```

## `ncm details <module{@version}>`

Returns a detailed report about a specific module with version. `ncm-cli` will default to using the `latest` version.
Returns a detailed report about a specific module version.
Defaults to using the `latest` version as published to npm if no `version` is provided.

```
$ ncm details client-request
$ ncm details client-request@2.3.0
╔═════════════════════════╗
║ client-request @ latest ║
╚═════════════════════════╝
╔═════════════════════════════════════════╗
║ client-request @ 2.3.0 (within ncm-cli) ║
╚═════════════════════════════════════════╝
┌──────┬───────────┐
│ |||| │ None Risk │
Expand Down Expand Up @@ -243,15 +187,29 @@ Code Quality (does not affect risk score):
┌───┬────────────────────────────────────────────────────────────────────────────────────────────┐
│ ! │ This package version's size on disk is 40.0 kB. │
└───┴────────────────────────────────────────────────────────────────────────────────────────────┘
Required By (leftmost is directly in your package):
┌────────────────────────────────────────────────────────────────────────────────────────────┐
│ (Directly in your package) │
└────────────────────────────────────────────────────────────────────────────────────────────┘
```

## `ncm install <module{@version}>`

Runs and displays `ncm details <module{@version}>` with an interactive confirmation prompt.
If confirmed, attempts to run `npm install <module{@version}>` with any additional options provided.

_The config keys `installBin` and `installCmd` can adjust this to work with other package installers if necessary._
_For more information, see `ncm config --help`._

## `ncm whitelist`

Display and modify your organization’s module whitelist.
Display or modify your NodeSource organization’s module whitelist.

### `ncm whitelist --list`

Returns a list containing each module in your organization’s whitelist. Public modules are listed alongside their risk score, license compliance, and security summary.
Returns a list containing each module in your NodeSource organization’s whitelist.
Public modules are listed alongside their risk score, license compliance, and security summary.

```
$ ncm whitelist --list
Expand All @@ -273,46 +231,28 @@ $ ncm whitelist --list

### `ncm whitelist --add <module@version>`

Add a module to your organization’s whitelist.
Add one or more modules to your NodeSource organization’s whitelist.

### `ncm whitelist --remove <module@version>`

Remove a module to your organization’s whitelist.

```
$ ncm whitelist --remove qs@6.3.1
╔══════════════════════════════╗
║ personal Whitelisted Modules ║
╚══════════════════════════════╝
✓ Package(s) removed successfully.
```
Remove one or more modules from your NodeSource organization’s whitelist.

## `ncm config`

`ncm-cli` allows access to various configuration settings. For more information, use the help command: `ncm config --help`
## `ncm orgs`

## `ncm help`
Change your active NodeSource organization, which impacts the whitelist.
Defaults to an interactive prompt.

Display the NodeSource Certified Modules help menu. For more information on a specific command, run `ncm <command> --help`.
By passing an `<orgname>`, the interactive part may be skipped.

## `ncm orgs <orgname>`
Input is _case sensitive_.

Change your active organization interactively by entering the `orgs` command without passing an `<orgname>`. By passing an organization name, `ncm-cli` will switch the active organization without prompting for input.

```
$ ncm orgs personal
╔═════════════════════════════════════╗
║ Select your NodeSource organization ║
╚═════════════════════════════════════╝
## `ncm config`

✓ You're using ncm with the personal settings.
```
Access to various configuration settings.
For more information, use the help command: `ncm config --help`

## License & Copyright

Copyright 2019 NodeSource
Copyright 2019 NodeSource — _[Contributions via DCO 1.1](contributing.md#developers-certificate-of-origin)_

Licensed under the Apache License, Version 2.0, see the LICENSE file for details.
Licensed under the Apache License, Version 2.0 — see the [LICENSE](LICENSE) file for details.

0 comments on commit 2cd778a

Please sign in to comment.