Merge pull request #25 from garethr/improve-readme

Add more details to the README

README.md

@@ -1,37 +1,77 @@
-# helm-snyk
+# Check your Helm chart for vulnerabilities
 
-This Helm plugin allows you to test the images found within a given Helm chart for security vulnerabilities using Snyk.
+The Helm plugin for Snyk provides a subcommand for testing the images in a given Helm chart for vulnerabilities.
+
+## Installation
+
+Install the plugin using the built-in `helm plugin` command:
 
-## Usage as Helm plugin
-First install the plugin (requires Helm)
 ```
 helm plugin install https://github.com/snyk-labs/helm-snyk
 ```
 
-Set your `SNYK_TOKEN` environment variable:
+The plugin connects to the Snyk service to lookup vulnerability information. If you don't have a Snyk account, go to [https://snyk.io/login](https://snyk.io/login) to sign up for free. You can then obtain an access token from [https://app.snyk.io/account](https://app.snyk.io/account) or for information on using service accounts, see [https://snyk.io/docs/service-accounts/](https://snyk.io/docs/service-accounts/).
+
+Once you have an account, you should set the `SNYK_TOKEN` environment variable:
+
 ```
 export SNYK_TOKEN=<your-snyk-token>
 ```
-If you don't have a Snyk token, go to [https://snyk.io/login](https://snyk.io/login) to sign up. You can them obtain your token from [https://app.snyk.io/account](https://app.snyk.io/account) or for information on using service accounts, see [https://snyk.io/docs/service-accounts/](https://snyk.io/docs/service-accounts/).
 
-Then `cd` to a directory containing a Helm chart you want to test and run:
-```
-helm snyk .
-```
+The plugin also requires a local Docker installation and uses this to download and test each of the images discovered in the chart.
 
-Alternatively, you can specify a full path:
-```
-helm snyk /path/to/helm/chart
-```
 
-To save the output to a file either use piping or use the `--output` option. For example:
-```
-helm snyk . --output=<filename.json>
-```
+## Usage
 
-## Usage as CLI tool
+With the plugin installed, simply run the new `helm snyk test` command and point it to the directory of the chart. For instance:
+
+```console
+$ helm snyk test stable/redis
+Image: docker.io/bitnami/redis:5.0.5-debian-9-r181
+Testing docker.io/bitnami/redis:5.0.5-debian-9-r181...
+✗ Low severity vulnerability found in tar
+  Description: CVE-2005-2541
+  Info: https://snyk.io/vuln/SNYK-LINUX-TAR-105079
+  Introduced through: meta-common-packages@meta
+  From: meta-common-packages@meta > tar@1.29b-1.1
+✗ Low severity vulnerability found in systemd/libsystemd0
+  Description: CVE-2019-9619
+  Info: https://snyk.io/vuln/SNYK-LINUX-SYSTEMD-442642
+  Introduced through: systemd/libsystemd0@232-25+deb9u12, util-linux/bsdutils@1:2.29.2-1+deb9u1, procps@2:3.3.12-3+deb9u1, sysvinit/sysvinit-utils@2.88dsf-59.9, systemd/libudev1@232-25+deb9u12, util-linux/mount@2.29.2-1+deb9u1
+  From: systemd/libsystemd0@232-25+deb9u12
+  From: util-linux/bsdutils@1:2.29.2-1+deb9u1 > systemd/libsystemd0@232-25+deb9u12
+  From: procps@2:3.3.12-3+deb9u1 > procps/libprocps6@2:3.3.12-3+deb9u1 > systemd/libsystemd0@232-25+deb9u12
+  and 4 more...
+...
 ```
-git clone git@github.com:snyk-labs/helm-snyk.git
-npm install
-npm start -- <helm-chart-directory> [--output=<output-file.json>]
+
+As well as the user-friendly output above the plugin also supports outputting the results as a JSON document. This can be useful for further analysis or integration with other tooling.
+
+```console
+$ helm snyki test stable/mysql --json
+{
+  "helmChart": "mysql@1.3.0",
+  "images": [
+    {
+      "imageName": "dduportal/bats:0.4.0",
+      "results": {
+        "vulnerabilities": [
+          {
+            "CVSSv3": null,
+            "creationTime": "2019-02-06T14:40:43.295348Z",
+            "credit": [
+              ""
+            ],
+            "cvssScore": null,
+            "description": "## Overview\nCVE-2011-3374",
+            "disclosureTime": null,
+            "id": "SNYK-LINUX-APT-116518",
+            "identifiers": {
+              "ALTERNATIVE": [
+                "SNYK-DEBIAN8-APT-407500",
+...
 ```
+
+For further options and features see the help instructions with the `--help` flag.
+
+