Merge pull request #1527 from snyk/feat/command-docs

New --help command docs

.circleci/config.yml

@@ -78,7 +78,7 @@ commands:
   install_sbt_unix:
     description: Install SBT
     steps:
-      - run: 
+      - run:
           name: Installing sbt
           command: sdk install sbt 1.3.12
   install_node_npm:
@@ -109,6 +109,12 @@ commands:
       - run:
           name: NPM version
           command: npm --version
+  generate_help:
+    description: Generate CLI help files
+    steps:
+      - run:
+          name: Run CLI help text builder
+          command: npm run generate-help
 
 jobs:
   regression-test:
@@ -117,9 +123,13 @@ jobs:
       - image: circleci/node:<< parameters.node_version >>
     steps:
       - checkout
+      - setup_remote_docker:
+          version: 19.03.13
+          # docker_layer_caching: true
       - install_shellspec
       - install_deps
       - build_ts
+      - generate_help
       - run:
           name: Run auth
           command: npm run snyk-auth
@@ -213,7 +223,11 @@ jobs:
     resource_class: small
     steps:
       - checkout
+      - setup_remote_docker:
+          version: 19.03.13
+          # docker_layer_caching: true
       - install_deps
+      - generate_help
       - run: sudo npm i -g semantic-release @semantic-release/exec pkg
       - run: sudo apt-get install -y osslsigncode
       - run:

.github/CODEOWNERS

@@ -1,9 +1,8 @@
 # Snyk Boost will be required for a review on every PR
 README.md  @snyk/content @snyk/boost
 src/cli/commands/test/formatters/format-reachability.ts  @snyk/flow
-help/  @snyk/content @snyk/boost
+help/  @snyk/hammer
 *  @snyk/hammer @snyk/boost
-help/iac.txt @snyk/cloudconfig
 src/cli/commands/test/iac-output.ts @snyk/cloudconfig
 src/lib/cloud-config-projects.ts @snyk/cloudconfig
 src/lib/iac/ @snyk/cloudconfig
@@ -15,3 +14,5 @@ test/fixtures/iac/ @snyk/cloudconfig
 test/smoke/spec/iac/ @snyk/cloudconfig
 src/lib/errors/invalid-iac-file.ts @snyk/cloudconfig
 src/lib/errors/unsupported-options-iac-error.ts @snyk/cloudconfig
+help/commands-docs/iac-examples.md @snyk/cloudconfig
+help/commands-docs/iac.md @snyk/cloudconfig

.gitignore

@@ -17,6 +17,9 @@ snyk_report.html
 !/docker/snyk_report.css
 cert.pem
 key.pem
+help/commands-md
+help/commands-txt
+help/commands-man
 
 # Diagnostic reports (https://nodejs.org/api/report.html)
 report.[0-9]*.[0-9]*.[0-9]*.[0-9]*.json

help/README.md

@@ -0,0 +1,57 @@
+# CLI Help files
+
+Snyk CLI help files are generated from markdown sources in `help/commands-docs` folder.
+
+There is a simple templating system that pieces markdown sources together. Those are later transformed into a [roff (man-pages) format](<https://en.wikipedia.org/wiki/Roff_(software)>). Those are then saved as plaintext to be used by `--help` argument.
+
+1. Markdown fragments
+2. Markdown documents for each command
+3. roff man pages
+4. plain text version of man page
+
+Since [package.json supports specifying man files](https://docs.npmjs.com/cli/v6/configuring-npm/package-json#man), they will get exposed under `man snyk`.
+
+This system improves authoring, as markdown is easier to format. It's keeping the docs consistent and exposes them through `man` command.
+
+## Updating or adding help documents
+
+Contact **Team Hammer** or open an issue in this repository when in doubt.
+
+Keep all changes in `help/commands-docs` folder, as other folders are ignored by `.gitignore` file and are auto-generated in CI pipeline.
+
+See other documents and help files for hints on how to format arguments. Keep formatting simple, as the transformation to `roff` might have issues with complex structures.
+
+### CLI options
+
+```md
+- `--severity-threshold`=low|medium|high:
+  Only report vulnerabilities of provided level or higher.
+```
+
+CLI flag should be in backticks. Options (filenames, org names…) should use Keyword extension (see below) and literal options (true|false, low|medium|high…) should be typed as above.
+
+### Keyword extension
+
+There is one non-standard markdown extension:
+
+```md
+<KEYWORD>
+```
+
+Visually, it'll get rendered as underlined text. It's used to mark a "variable". For example this command flag:
+
+```md
+- `--sarif-file-output`=<OUTPUT_FILE_PATH>:
+  (only in `test` command)
+  Save test output in SARIF format directly to the <OUTPUT_FILE_PATH> file, regardless of whether or not you use the `--sarif` option.
+  This is especially useful if you want to display the human-readable test output via stdout and at the same time save the SARIF format output to a file.
+```
+
+## Running locally
+
+- have docker running
+- have `npm`/`npx` available
+
+```
+$ npm run generate-help
+```

help/commands-docs/_ENVIRONMENT.md

@@ -0,0 +1,17 @@
+## ENVIRONMENT
+
+You can set these environment variables to change CLI run settings. These keys will override settings in your `snyk config`:
+
+- `SNYK_TOKEN`:
+  Snyk authorization token. Setting this envvar will override the token that may be available in your `snyk config` settings.
+
+  [How to get your account token](https://snyk.co/ucT6J)<br />
+  [How to use Service Accounts](https://snyk.co/ucT6L)<br />
+
+- `SNYK_API`:
+  Sets API host to use for Snyk requests. Useful for on-premise instances and configuring proxies.
+
+- `SNYK_CFG_`<KEY>:
+  Allows you to override any key that's also available as `snyk config` option.
+
+  E.g. `SNYK_CFG_ORG`=myorg will override default org option in `config` with "myorg".

help/commands-docs/_EXAMPLES.md

@@ -0,0 +1,28 @@
+## EXAMPLES
+
+- `Authenticate in your CI without user interaction`:
+  \$ snyk auth MY_API_TOKEN
+- `Test a project in current folder for known vulnerabilities`:
+  \$ snyk test
+- `Test a specific dependency for vulnerabilities`:
+  \$ snyk test ionic@1.6.5
+
+More examples:
+
+    $ snyk test --show-vulnerable-paths=false
+    $ snyk monitor --org=my-team
+    $ snyk monitor --project-name=my-project
+
+### Container scanning
+
+See `snyk container --help` for more details and examples:
+
+    $ snyk container test ubuntu:18.04 --org=my-team
+    $ snyk container test app:latest --file=Dockerfile --policy-path=path/to/.snyk
+
+### Infrastructure as Code (IAC) scanning
+
+See `snyk iac --help` for more details and examples:
+
+    $ snyk iac test /path/to/Kubernetes.yaml
+    $ snyk iac test /path/to/terraform_file.tf

help/commands-docs/_EXIT_CODES.md

@@ -0,0 +1,8 @@
+## EXIT CODES
+
+Possible exit codes and their meaning:
+
+**0**: success, no vulns found<br />
+**1**: action_needed, vulns found<br />
+**2**: failure, try to re-run command<br />
+**3**: failure, no supported projects detected<br />

help/commands-docs/_NOTICES.md

@@ -0,0 +1,5 @@
+## NOTICES
+
+### Snyk API usage policy
+
+The use of Snyk's API, whether through the use of the 'snyk' npm package or otherwise, is subject to the [terms & conditions](https://snyk.co/ucT6N)

help/commands-docs/_SNYK_COMMAND_HEADER.md

@@ -0,0 +1,51 @@
+# snyk(1) -- CLI and build-time tool to find & fix known vulnerabilities in open-source dependencies
+
+## SYNOPSIS
+
+`snyk` \[<COMMAND>] \[<SUBCOMMAND>] \[<OPTIONS>] \[<PACKAGE>] \[-- <COMPILER_OPTIONS>]
+
+## DESCRIPTION
+
+Snyk helps you find, fix and monitor known vulnerabilities in open source dependencies.<br />
+For more information see https://snyk.io
+
+### Not sure where to start?
+
+1. authenticate with `$ snyk auth`
+2. test your local project with `$ snyk test`
+3. get alerted for new vulnerabilities with `$ snyk monitor`
+
+## COMMANDS
+
+To see command-specific flags and usage, see `help` command, e.g. `snyk container --help`.
+Available top-level CLI commands:
+
+- `auth` \[<API_TOKEN>\]:
+  Authenticate Snyk CLI with a Snyk account.
+
+- `test`:
+  Test local project for vulnerabilities.
+
+- `monitor`:
+  Snapshot and continuously monitor your project.
+
+- `container`:
+  Test container images for vulnerabilities. See `snyk container --help` for full instructions.
+
+- `iac`:
+  Find security issues in your Infrastructure as Code files. See `snyk iac --help` for full instructions.
+
+- `config`:
+  Manage Snyk CLI configuration.
+
+- `protect`:
+  Applies the patches specified in your .snyk file to the local file system.
+
+- `policy`:
+  Display the .snyk policy for a package.
+
+- `ignore`:
+  Modifies the .snyk policy to ignore stated issues.
+
+- `wizard`:
+  Configure your policy file to update, auto patch and ignore vulnerabilities. Snyk wizard updates your .snyk file.