Snyk CLI

Snyk’s CLI helps you find and fix known vulnerabilities in your dependencies, both ad hoc and as part of your CI (Build) system.

The Snyk CLI requires you to authenticate with your account before using it. It supports Node.js and Ruby.

Installation

Snyk is installed via npm. Run these commands to install it for local use:

npm install -g snyk

Once installed, you need to authenticate with your Snyk account:

snyk auth

Now you can perform a quick test on a public npm package, for instance:

snyk test ionic

As you can see, Snyk found and reported several vulnerabilities in the package. For each issue found, Snyk provides the severity of the issue, a link to a detailed description, the path through which the vulnerable module got into your system, and guidance on how to fix the problem.

Example output

$ snyk test
✗ High severity vulnerability found on minimatch@0.3.0
- desc: Regular Expression Denial of Service
- info: https://snyk.io/vuln/npm:minimatch:20160620
- from: ionic@2.1.17 > gulp@3.8.8 > liftoff@0.12.1 > findup-sync@0.1.3 > glob@3.2.11 > minimatch@0.3.0
Upgrade direct dependency gulp@3.8.8 to gulp@3.8.11 (triggers upgrades to liftoff@2.2.0 > findup-sync@0.3.0 > glob@5.0.15 > minimatch@3.0.2)

✗ Medium severity vulnerability found on moment@2.11.1
- desc: Regular Expression Denial of Service
- info: https://snyk.io/vuln/npm:moment:20161019
- from: ionic@2.1.17 > moment@2.11.1
Upgrade direct dependency moment@2.11.1 to moment@2.15.2

✗ Medium severity vulnerability found on send@0.10.1
- desc: Root Path Disclosure
- info: https://snyk.io/vuln/npm:send:20151103
- from: ionic@2.1.17 > serve-static@1.7.1 > send@0.10.1
Upgrade direct dependency serve-static@1.7.1 to serve-static@1.8.1 (triggers upgrades to send@0.11.1)

Authentication

Some Snyk commands require authentication. We use GitHub for authentication, but do not require access to your repositories, only your email address. You can authenticate by running snyk auth in your terminal, and it’ll guide you through this process.

Alternatively, you can visit your account, copy your token and paste it into your terminal as follows:

snyk auth <your token>

Wizard

Snyk’s wizard walks you through finding and fixing the known vulnerabilities in your project. Note that the wizard is currently only available for Node.js projects.

It leverages the separate test, protect and monitor actions, supported by an interactive workflow. To run the wizard, navigate to your project folder and run snyk wizard like so:

cd ~/projects/myproj/
snyk wizard

The wizard goes through multiple phases. First, it takes stock of which dependencies are locally installed, queries the snyk service for related known vulnerabilities, and asks you how you want to address each vulnerability that was found. As you answer the questions, the wizard will create a Snyk policy file, stored in a file named .snyk, which will guide future Snyk commands.

Here are the possible remediation steps for each vulnerability:

  • Upgrade - if upgrading a direct dependency can fix the current vulnerability, the wizard can automatically modify your package.json file to use the newer version and run npm update to apply the changes.
  • Patch - Sometimes there is no direct upgrade that can address the vulnerability, or there is one but you can’t upgrade due to functional reasons (e.g. it’s a major breaking change). For such cases, the wizard lets you patch the issue (using patches the Snyk team created and maintain). This option will make the minimal modifications to your locally installed module files to fix the vulnerability. It will also update the policy to patch this issue when running snyk protect, as shown below.
  • Ignore - If you believe this vulnerability is not exploitable, you can set the Snyk policy to ignore this vulnerability. By default, we will ignore the vulnerability for 30 days, to avoid easily hiding a true issue. If you want to ignore it permanently, you can manually edit the generated .snyk file. If neither a patch nor an upgrade are available, you can choose to ignore the issue for now, and we’ll notify you when a new patch or upgrade is available.

If more than one vulnerability is introduced via the same module, then the wizard groups them. You can upgrade, patch or ignore all of them; or if you want to see more details, you can review each vulnerability separately.

Example output

$ snyk wizard

Snyk's wizard will:

  * Enumerate your local dependencies and query Snyk's servers for vulnerabilities
  * Guide you through fixing found vulnerabilities
  * Create a .snyk policy file to guide snyk commands such as test and protect
  * Remember your dependencies to alert you when new vulnerabilities are disclosed

 Note: Node.js only.

Loading dependencies...
Querying vulnerabilities database...
Tested 446 dependencies for known vulnerabilities, found 8 vulnerabilities, 20 vulnerable paths.

? High severity vuln found in tough-cookie@2.2.2, introduced via azure-mgmt-storage@0.9.16
- desc: ReDoS via long string of semicolons
- info: https://snyk.io/vuln/npm:tough-cookie:20160722
- from: azure-mgmt-storage@0.9.16 > azure-common@0.9.11 > request@2.45.0 > tough-cookie@2.2.2 Upgrade

? 6 vulnerabilities introduced via falcor-router-demo@1.0.5
  - info: https://snyk.io/package/npm/falcor-router-demo/1.0.5
  Remediation options (Use arrow keys)
❯ Re-install falcor-router-demo@1.0.5 (triggers upgrade to minimatch@3.0.2, tough-cookie@2.3.0) 
  Review vulnerabilities separately
  Set to ignore for 30 days (updates policy)
  Skip

Once all the issues are addressed, snyk wizard will optionally integrate some tests and protection steps into your package.json file:

  • It can add snyk test to the test script, which will query your local dependencies for vulnerabilities and err if found (except those you chose to ignore).
  • If you chose to patch an issue, the wizard will optionally add snyk protect to your project as a post-install step. This is helpful if you publish this module, as it will repeatedly patch the issues specified in .snyk every time a module is installed.</p>

Lastly, the wizard will create the .snyk file, modify package.json and run npm update to apply the changes. To monitor your project for new vulnerabilities, the wizard takes a snapshot of your current dependencies (similar to running snyk monitor). You can see all the snapshots for a project on the snyk website. We'll notify you via email if you're affected by newly disclosed vulnerabilities in them, or when a previously unavailable patch or upgrade path are available.

A few things to note:

  • The wizard doesn’t perform any git (or source control) actions, so be sure to add the .snyk file to your repository.
  • Subsequent runs of the wizard will not show items previously ignored. To start a-fresh, run snyk wizard --ignore-policy.
  • By default, both wizard and test ignore devDependencies. To test those, add the --dev flag.

Test

Test a local project

To only test your project for known vulnerabilities, browse to your project’s folder and run snyk test:

cd ~/projects/myproj/
snyk test

snyk test takes stock of all the local dependencies and queries the snyk service for related known vulnerabilities. It displays the found issues along with additional information. For Node.js projects, it also suggests remediation steps.

When testing locally, you can specify the file that Snyk should inspect for package information.

$ snyk test --file=package.json

When ommitted Snyk will try to detect the appropriate file for your project by looking for a package.json or Gemfile file. If both files exist it will use the package.json file. In this case you can force a Ruby test by pointing to your Gemfile.

 $ snyk test --file=Gemfile

snyk test can also get a folder name as an argument, which is especially handy if you want to test multiple projects. For instance, the following command tests all the projects under a certain folder for known vulnerabilities:

cd ~/projects/
snyk test *

Note for Node.js:
Since snyk test looks at the locally installed modules, it needs to run after npm install, and will seamlessly work with shrinkwrap, npm enterprise or any other custom installation logic you have.

Test a public GitHub repository

To test a public Github repository, run snyk test and include the Github URL to the repo.

snyk test https://github.com/snyk/snyk

The following git URL formats are supported:

  • git://github.com/user/project.git#commit-ish
  • https://github.com/user/project#commit-ish
  • user/project#commit-ish

This also works for Bitbucket and GitLab.

You can also test a public npm package or Github project via the Test page on snyk.io.

Test a public npm package

You can also use snyk test to scrutinize a public package before installing it, to see if it has known vulnerabilities or not. Using the package name will test the latest version of that package, and you can also provide a specific version or range using snyk test module[@semver-range].

snyk test lodash
snyk test ionic@1.6.5

Protect

The protect command applies the patches specified in your .snyk file to the local file system. This is currently supported for Node.js projects only.

Run snyk protect after you’ve created a .snyk file and installed your local dependencies (e.g. by running npm install).snyk wizard will do this as a last step.

Since running protect is the way to repeatedly apply patches, you should run it every time you reinstall your modules. Common integration points would be your CI/build system, your deployment system, and adding it as a post installation step in your package.json file (necessary if you consume this module via npm).

Monitor

With test and protect, you’re well set up to address currently known vulnerabilities. However, new vulnerabilities are constantly disclosed - which is where monitor comes in.

cd ~/projects/myproject/ snyk monitor

Just before you deploy, run snyk monitor in your project directory. This will take a snapshot of your current dependencies, so we can notify you about newly disclosed vulnerabilities in them, or when a previously unavailable patch or upgrade path are created. If you take multiple snapshots of the same project, we will only alert you to new information about the latest one.

Log in and go to snyk.io/monitor to see the lastest snapshot and history of your project.

Example output

$ snyk monitor
Captured a snapshot of this project's dependencies. Explore this snapshot at https://snyk.io/monitor/1a53f19a-f64f-44ab-b122-74ce82c1c34b
Notifications about newly disclosed vulnerabilities related to these dependencies will be emailed to you.

Integrating Snyk into your dev workflow

To continuously avoid known vulnerabilities in your dependencies, integrate Snyk into your continuous integration (a.k.a. build) system.

For Node.js

  1. Install the Snyk utility using npm install -g snyk.
  2. Run snyk wizard in the directory of your project following the prompts which will also generate a .snyk policy file.
  3. Ensure the .snyk file you generated was added to your source control (git add .snyk).
  4. If you selected to, Snyk will include snyk test as part of your npm test command, so if there are new vulnerabilities in the future, your CI will fail, protecting you from introducing vulnerabilities to production. Alternatively, you can add snyk test to any other CI test platform you use.

For Ruby CI

  1. Install the Snyk utility using npm install -g snyk.
  2. Add snyk test to your CI test platform

Setting up automatic monitoring

If you monitor a project with Snyk, you’ll get notified if your project’s dependencies are affected by newly disclosed vulnerabilities. To make sure this list of dependencies is up to date, refresh it continuously by running snyk monitor in your deployment process. You’ll also need to authenticate to Snyk, so we can know where to update the dependencies.

To do both, add the following to your deployment scripts:

snyk auth $SNYK_TOKEN
snyk monitor

Configure your environment to include the SNYK_TOKEN environment variable. You can find your API token on the dashboard after logging in.

API token configuration

Make sure you don’t check your API token into source control, to avoid exposing it to others. Instead, use your CI environment variables to configure it.

See guidance for how to do this on:

You can find others through an easy Google search.

Badge

Once you’re vulnerability free, you can put a badge on your README showing your package has no known security holes. This will show your users you care about security, and tell them that they should care too.

Read more about configuring badges in the badges section.

CLI commands overview

snyk [options] [command] [package]

The package argument is optional. If no package is given, Snyk will run the command against the current working directory allowing you test you non-public applications.

Commands

auth [api-token].....Sign into Snyk.
test ............... Test for any known vulnerabilities.
wizard ............. Configure your policy file to update, auto patch and
                     ignore vulnerabilities. Note: Node.js only.
protect ............ Protect your code from vulnerabilities and
                     optionally suppress specific vulnerabilities.
                     Note: Node.js only.
monitor ............ Record the state of dependencies and any vulnerabilities on snyk.io.
policy ............. Display the Snyk policy for a package.

Options

--dev .............. Include devDependencies (defaults to production only).
--file=<string> .... Sets package file. For more help run `snyk help file`.
--org=<org-name> ... Associate a snapshot (or wizard snapshot) with a specific
                     organisation. For more help run `snyk help orgs`.
--ignore-policy .... Ignores and resets the state of your policy file.
--trust-policies ... Applies and uses ignore rules from your dependencies's Snyk policies,
                     otherwise ignore policies are only shown as a suggestion.
--dry-run .......... Don't apply updates or patches during protect.
-q, --quiet ........ Silence all output.
-h, --help ......... This help information.
-v, --version ...... The CLI version.

Examples

  $ snyk test
  $ snyk test ionic@1.6.5
  $ snyk monitor --org=my-team

Use snyk test in your test scripts. If a vulnerability is found, the process will exit with a non-zero exit code.

Troubleshooting

If your instance of the Snyk CLI has started failing, follow these steps to resolve:

  1. Ensure you are on the most up to date version of the CLI by running

    npm update -g snyk
    
  2. Make sure you are authenticating prior to running the Snyk CLI command

You can either authenticate by running snyk auth in your terminal, and it’ll guide you through this process, or visit your account and copy your API token and paste it into your terminal as follows:

bash snyk auth <your token>

  1. If you are still having problems after upgrading and authenticating send an email to support@snyk.io and we will try to help you out.

Note:

Authentication is required for snyk test and snyk monitor from Tuesday the 24th of January 2017 for details on why we require authentication take a look at our blog post Requiring authentication in Snyk CLI.

Registration with Snyk is free. If you do not already have an account all you need to do is run snyk auth in your terminal (or sign up) to get an account setup.