Documentation

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, Ruby, Python, Scala and Java.

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 set the environment variable SNYK_TOKEN to your token. This approach is recommended for CI environments.

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

Please note that if a yarn.lock file is detected in your folder, the wizard will ask you whether to treat the project as a Yarn project (the default answer), or as an npm project.

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 uses npm or yarn 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 use the snyk ignore command, or 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.

Lastly, the wizard will create the .snyk file, modify package.json and use npm or yarn 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 snyk test runs, it tries to detect the appropriate file for your project by looking for the following files, in this order:

  1. yarn.lock
  2. package.json
  3. Gemfile
  4. Gemfile.lock
  5. pom.xml
  6. requirements.txt
  7. build.gradle
  8. build.sbt

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

$ snyk test --file=package.json

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 or yarn install, and will seamlessly work with shrinkwrap, npm enterprise or any other custom installation logic you have.

Note for Java:
Since snyk test looks at the locally installed modules, it needs to run after mvn install.

Note for Scala: In order to use the CLI to test against your build.sbt manifest file, you’ll need to first install the sbt-dependency-graph plugin.

Running snyk test on your Scala projects without this plugin will throw the following error:

Error: Missing plugin `sbt-dependency-graph` (https://github.com/jrudolph/sbt-dependency-graph).
Please install it globally or on the current project and try again.

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

Test a Maven or Gradle project with variables

You can pass variables to snyk test running on Maven or Gradle projects. This is useful when you want to test a specific profile (in Maven) or configuration (in Gradle), or pass system properties. This is done by sending flags after a double-dash option when running snyk test. Note that all flags after the double-dash option will be used as Maven or Gradle flags.

For example, suppose you want to test a specific Maven profile: prod. Running the following will test this profile:

snyk test -- -Pprod

In another example, if you use a system property in your pom.xml file, e.g: <version>${pkg_version}</version>, you can define the system property in snyk test as follows:

snyk test -- -Dpkg_version=1.4

For testing a Gradle project with test dependencies, you would be able to pass the appropriate configuration to snyk test:

snyk test -- --configuration testCompile

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 or yarn 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 or yarn).

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 is 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.

Specifiying which organisation for monitoring

If you have several organisations set up in Snyk, running snyk monitor will associate the generated snapshot to your "default" (personal) organization. To specify a different organisation, you can use the --org option.

snyk monitor --org=my-org-name

Monitor a Maven or Gradle project with variables

You can pass variables to snyk monitor running on Maven or Gradle projects. This is useful when you want to monitor a specific profile (in Maven) or configuration (in Gradle), or pass system properties. This is done by sending flags after a double-dash option when running snyk monitor. Note that all flags after the double-dash option will be used as Maven flags.

For example, suppose you want to monitor a specific Maven profile: prod. Running the following will monitor this profile:

snyk monitor -- -Pprod

In another example, if you use a system property in your pom.xml file, e.g: <version>${pkg_version}</version>, you can define the system property in snyk monitor as follows:

snyk monitor -- -Dpkg_version=1.4

For monitoring a Gradle project with test dependencies, you would be able to pass the appropriate configuration to snyk monitor:

snyk monitor -- --configuration testCompile

Ignore

Sometimes, Snyk may alert you to a vulnerability that you either has no patches or updates available, or that you do not believe to be currently exploitable in your application. In this case, you may want to tell Snyk to ignore the vulnerability for a certain period of time.

If you're using snyk wizard (only available on Node.js projects), the wizard will give you the option of ignoring the vulnerability for a period of 30 days. If you're using Ruby or Java, or if you want to specify a different duration, you can use the snyk ignore command.

snyk ignore --id=IssueID [--expiry=expiry] [--reason='reason for ignoring']

Options

snyk ignore accepts three options:

Option Description Default Required
--id

The Snyk ID for the issue to ignore. Found by running snyk test and grabbing the last segment of the URL for a given vulnerability.

Example: For the vulnerability found at https://snyk.io/vuln/npm:tough-cookie:20160722, you would use:
--id=npm:tough-cookie:20160722

None Yes
--expiry

The expiry date string, according to RFC2822.

Example: --expiry=2017-04-30

30 days No
--reason

The reason for ignoring the issue.

Example: --reason='Not currently exploitable.'

"None Given" No

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, Python and Java CI

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

For Scala

  1. Install the Snyk utility using npm install -g snyk.
  2. Install the sbt-dependency-graph plugin.
  3. 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 the list of dependencies we have for your project is up to date, refresh it continuously by running snyk monitor in your deployment process.

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.

Open source projects

Tests against open source projects are free. If your source code is available publicly on the internet, you can set your project as open source by following these steps.

  1. If you haven’t done so already, run snyk monitor in your terminal to create a project on Snyk
  2. On the Snyk website, view your projects and select the CLI project you just created
  3. Click on “settings” from the right hand side of this page to change the project settings
  4. Enter a git URI to the source code for your project where it says “Git remote URI”. If your code is hosted on GitHub, you can find this by clicking the “Clone or download” button and copying the URI.
  5. If we are able to verify that the URI points to a git repository then your project will be marked as open source and will no longer be tracked against your private project test usage.

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 your 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.
ignore ............. Ignore an issue. For more help run `snyk help ignore`.

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' Snyk policies,
                     otherwise ignore policies are only shown as a suggestion.
--show-vulnerable-paths=<boolean>
                     Display the dependency paths from the top level
                     dependencies, down to the vulnerable packages (defaults
                     to true). Applicable to `snyk test`.
--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
  $ snyk test --show-vulnerable-paths=false

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 install -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, copy your API token and set the environment variable SNYK_TOKEN to your token.

  3. If you are still having problems after upgrading and authenticating send an email to support@snyk.io and we will 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.