From bb7307e31451dea2259aa677830ec3f780666293 Mon Sep 17 00:00:00 2001 From: awileysnyk <95229836+awileysnyk@users.noreply.github.com> Date: Tue, 14 Dec 2021 14:29:58 -0500 Subject: [PATCH] docs: update test command help --- help/cli-commands/test.md | 254 +++++++++++++++----------------------- 1 file changed, 98 insertions(+), 156 deletions(-) diff --git a/help/cli-commands/test.md b/help/cli-commands/test.md index 4ab76b3516a..e6661986856 100644 --- a/help/cli-commands/test.md +++ b/help/cli-commands/test.md @@ -1,4 +1,4 @@ -# snyk test -- test local project for vulnerabilities +# snyk test -- test a project for open source vulnerabilities and license issues ## Usage @@ -6,33 +6,52 @@ ## Description -Test command checks locally installed projects for vulnerabilities. It tries to autodetect supported manifest files with dependencies and test those. +The `snyk test` command checks projects for open source vulnerabilities and license issues. The test command tries to auto-detect supported manifest files with dependencies and test those. + +## Exit codes + +Possible exit codes and their meaning: + +**0**: success, no vulnerabilities found
+**1**: action_needed, vulnerabilities found
+**2**: failure, try to re-run command
+**3**: failure, no supported projects detected
+ +## Configure the Snyk CLI + +You can use environment variables to configure the Snyk CLI and also set variables to configure the Snyk CLI to connect with the Snyk API. See [Configure the Snyk CLI](https://docs.snyk.io/features/snyk-cli/configure-the-snyk-cli). + +## Debug + +Use the `-d` option to output the debug logs. ## Options -To see command-specific flags and usage, see `help` command, e.g. `snyk container --help`. -For advanced usage, we offer language and context specific flags, listed further down this document. +See also subsequent sections for options for specific build environments, package managers, languages, and `[]` which you specify last. ### `--all-projects` -Auto-detect all projects in working directory +Auto-detect all projects in the working directory. ### `--detection-depth=` -Use with --all-projects or --yarn-workspaces to indicate how many sub-directories to search. `DEPTH` must be a number. +Use with options as documented to indicate how many sub-directories to search. `DEPTH` must be a number. + +Default: 4 (the current working directory and 3 sub-directories). -Default: 4 (the current working directory and 3 sub-directories) +Example: `--detection-depth=3` limits search to the specified directory (or the current directory if no `` is specified) plus three levels of subdirectories. ### `--exclude=[,]...>` -Can be used with --all-projects and --yarn-workspaces to indicate sub-directories and files to exclude. Must be comma separated. +Can be used with `--all-projects` and `--yarn-workspaces` to indicate sub-directories and files to exclude. Must be comma separated. -If using with `--detection-depth` exclude ignores directories at any level deep. +Use the exclude option with `--detection-depth` to ignore directories at any depth. ### `--prune-repeated-subdependencies`, `-p` Prune dependency trees, removing duplicate sub-dependencies. -Will still find all vulnerabilities, but potentially not all of the vulnerable paths. + +Continues to find all vulnerabilities, but may not find all of the vulnerable paths. ### `--print-deps` @@ -44,42 +63,42 @@ Set or override the remote URL for the repository that you would like to monitor ### `--dev` -Include development-only dependencies. Applicable only for some package managers. E.g. _devDependencies_ in npm or _:development_ dependencies in Gemfile. +Include development-only dependencies. Applicable only for some package managers, for example `devDependencies` in npm or `:development` dependencies in Gemfile. -Default: scan only production dependencies +Default: scan only production dependencies. ### `--org=` -Specify the to run Snyk commands tied to a specific organization. This will influence where will new projects be created after running `monitor` command, some features availability and private tests limits. +Specify the to run Snyk commands tied to a specific organization. The influences some features availability and private test limits. + If you have multiple organizations, you can set a default from the CLI using: `$ snyk config set org=` -Setting a default will ensure all newly monitored projects will be created -under your default organization. If you need to override the default, you can use the `--org=`argument. +Set a default to ensure all newly tested projects are tested under your default organization. If you need to override the default, use the `--org=` option. -Default: uses `` that sets as default in your [Account settings](https://app.snyk.io/account) +Default: `` that is the current preferred organization in your [Account settings](https://app.snyk.io/account). ### `--file=` -Sets a package file. +Specify a package file. -When testing locally or monitoring a project, you can specify the file that Snyk should inspect for package information. When ommitted Snyk will try to detect the appropriate file for your project. +When testing locally or monitoring a project, you can specify the file that Snyk should inspect for package information. When the file is not specified, Snyk tries to detect the appropriate file for your project. ### `--ignore-policy` -Ignores all set policies. The current policy in `.snyk` file, Org level ignores and the project policy on snyk.io. +Ignore all set policies, the current policy in the `.snyk` file, Org level ignores, and the project policy on snyk.io. -### `--trust-policies` +### `--org=` -Applies and uses ignore rules from your dependencies' Snyk policies, otherwise ignore policies are only shown as a suggestion. +Apply and use ignore rules from the Snyk policies your dependencies; otherwise ignore rules in the dependencies are only shown as a suggestion. -### `--show-vulnerable-paths`=none|some|all +### `--show-vulnerable-paths=none|some|all` -Display the dependency paths from the top level dependencies, down to the vulnerable packages. Doesn't affect output when using JSON `--json` output. +Display the dependency paths from the top level dependencies down to the vulnerable packages. Does not affect output when using JSON `--json` output. -Default: (a few example paths shown) - is an alias for . +Default: `some` (a few example paths shown). +`false` is an alias for `none`. ### `--project-name=` @@ -87,24 +106,21 @@ Specify a custom Snyk project name. ### `--target-reference=` -A reference which differentiates this project. For example, a branch name or version. Projects using the same reference can be used for grouping. Only supported for Snyk Open Source. [More information](https://snyk.info/3B0vTPs). - -### `--tags=[,]...>` - -This is an alias for `--project-tags`. +Specify a reference which differentiates this project, for example, a branch name or version. Projects having the same reference can be grouped based on that reference. Only supported for Snyk Open Source. For more information see [Separating projects by branch or version](https://snyk.info/3B0vTPs). ### `--policy-path=` -Manually pass a path to a snyk policy file. +Manually pass a path to a `.snyk` policy file. ### `--json` -Prints results in JSON format. +Print results in JSON format. ### `--json-file-output=` Save test output in JSON format directly to the specified file, regardless of whether or not you use the `--json` option. -This is especially useful if you want to display the human-readable test output via stdout and at the same time save the JSON format output to a file. + +This is especially useful if you want to display the human-readable test output using stdout and at the same time save the JSON format output to a file. ### `--sarif` @@ -113,204 +129,130 @@ Return results in SARIF format. ### `--sarif-file-output=` Save test output in SARIF format directly to the 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. + +This is especially useful if you want to display the human-readable test output using stdout and at the same time save the SARIF format output to a file. ### `--severity-threshold=low|medium|high|critical` -Only report vulnerabilities of provided level or higher. +Report only vulnerabilities at the specified level or higher. ### `--fail-on=all|upgradable|patchable` -Only fail when there are vulnerabilities that can be fixed. +Fail only when there are vulnerabilities that can be fixed. -- `all`: fails when there is at least one vulnerability that can be either upgraded or patched. -- `upgradable`: fails when there is at least one vulnerability that can be upgraded. -- `patchable`: fails when there is at least one vulnerability that can be patched. +- `all`: fail when there is at least one vulnerability that can be either upgraded or patched. +- `upgradable`: fail when there is at least one vulnerability that can be upgraded. +- `patchable`: fail when there is at least one vulnerability that can be patched. -If vulnerabilities do not have a fix and this option is being used, tests will pass. +If vulnerabilities do not have a fix and this option is being used, tests pass. -### `-- []` +## Options for Maven projects -Pass extra arguments directly to Gradle or Maven. -E.g. `snyk test -- --build-cache` +For more information about Maven CLI options see [Snyk for Java (Gradle, Maven)](https://docs.snyk.io/products/snyk-open-source/language-and-package-manager-support/snyk-for-java-gradle-maven). -Below are flags that are influencing CLI behavior for specific projects, languages and contexts: +### `--scan-all-unmanaged` -### Maven options +Auto-detect maven jars, aars, and wars in given directory. To test individually use `--file=`. -#### `--scan-all-unmanaged` +### `--reachable` -Auto detects maven jars, aars, and wars in given directory. Individual testing can be done with `--file=` +Analyze your source code to find which vulnerable functions and packages are called. -#### `--reachable` +### `--reachable-timeout=` -Analyze your source code to find which vulnerable -functions and packages are called. - -#### `--reachable-timeout=` - -The amount of time (in seconds) to wait for Snyk to gather reachability data. If it takes longer than , Reachable Vulnerabilities are not reported. This does not affect regular test or monitor output. +Specify the amount of time (in seconds) to wait for Snyk to gather reachability data. If it takes longer than ``, reachable vulnerabilities are not reported. This does not affect regular test or monitor output. Default: 300 (5 minutes). -### Gradle options +## Options for Gradle projects -[More information about Gradle CLI options](https://snyk.co/ucT6P) +For more information about Gradle CLI options see [Snyk for Java (Gradle, Maven)](https://docs.snyk.io/products/snyk-open-source/language-and-package-manager-support/snyk-for-java-gradle-maven). -#### `--sub-project=`, `--gradle-sub-project=` +### `--sub-project=`, `--gradle-sub-project=` For Gradle "multi project" configurations, test a specific sub-project. -#### `--all-sub-projects` +### `--all-sub-projects` For "multi project" configurations, test all sub-projects. -#### `--configuration-matching=` +### `--configuration-matching=` -Resolve dependencies using only configuration(s) that match the provided Java regular expression, e.g. `^releaseRuntimeClasspath$`. +Resolve dependencies using only configuration(s) that match the specified Java regular expression, for example, `^releaseRuntimeClasspath$`. -#### `--configuration-attributes=[,]...` +### `--configuration-attributes=[,]...` -Select certain values of configuration attributes to resolve the dependencies. E.g. `buildtype:release,usage:java-runtime` +Select certain values of configuration attributes to install dependencies and perform dependency resolution, for example, `buildtype:release,usage:java-runtime`. -#### `--reachable` +### `--reachable` -Analyze your source code to find which vulnerable -functions and packages are called. +Analyze your source code to find which vulnerable functions and packages are called. -#### `--reachable-timeout=` +### `--reachable-timeout=` -The amount of time (in seconds) to wait for Snyk to gather reachability data. If it takes longer than , Reachable Vulnerabilities are not reported. This does not affect regular test or monitor output. +Specify the amount of time (in seconds) to wait for Snyk to gather reachability data. If it takes longer than ``, reachable vulnerabilities are not reported. This does not affect regular test or monitor output. Default: 300 (5 minutes). -#### `--init-script=` +### `--project-name-prefix=` -When monitoring a .NET project, use this flag to add a custom prefix to the name of files inside a project along with any desired separators, e.g. `snyk monitor --file=my-project.sln --project-name-prefix=my-group/`. This is useful when you have multiple projects with the same name in other sln files. +When monitoring a .NET project, use this option to add a custom prefix to the name of files inside a project along with any desired separators, for example, `snyk monitor --file=my-project.sln --project-name-prefix=my-group/`. This is useful when you have multiple projects with the same name in other `.sln` files. -### npm options +## Options for npm projects -#### `--strict-out-of-sync=true|false` +### `--strict-out-of-sync=true|false` Control testing out of sync lockfiles. Default: true -### Yarn options +## Options for Yarn projects -#### `--strict-out-of-sync=true|false` +### `--strict-out-of-sync=true|false` Control testing out of sync lockfiles. Default: true -#### `--yarn-workspaces` +### `--yarn-workspaces` Detect and scan yarn workspaces. You can specify how many sub-directories to search using `--detection-depth` and exclude directories and files using `--exclude`. -### CocoaPods options +## Options for CocoaPods projects -#### `--strict-out-of-sync=true|false` +### `--strict-out-of-sync=true|false` Control testing out of sync lockfiles. Default: false -### Python options +## Options for Python projects -#### `--command=` +### `--command=` -Indicate which specific Python commands to use based on Python version. The default is `python` which executes your systems default python version. Run 'python -V' to find out what version is it. If you are using multiple Python versions, use this parameter to specify the correct Python command for execution. +Indicate which specific Python commands to use based on Python version. The default is `python` which executes your default python version. Run 'python -V' to find out what version it is. If you are using multiple Python versions, use this parameter to specify the correct Python command for execution. Default: `python` Example: `--command=python3` -#### `--skip-unresolved`=true|false +### `--skip-unresolved=true|false` Allow skipping packages that are not found in the environment. -### Flags available accross all commands - -#### `--insecure` - -Ignore unknown certificate authorities. - -#### `-d` - -Output debug logs. - -#### `--quiet`, `-q` - -Silence all output. - -#### `--version`, `-v` - -Prints versions. +## `-- []` -#### `--help []`, `[] --help`, `-h` - -Prints a help text. You may specify a `` to get more details. - -## Environment - -You can set these environment variables to change CLI settings. - -### `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)
-[How to use Service Accounts](https://snyk.co/ucT6L)
- -### `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". - -### `SNYK_REGISTRY_USERNAME` - -Specify a username to use when connecting to a container registry. Note that using the `--username` flag will override this value. This will be ignored in favour of local Docker binary credentials when Docker is present. - -### `SNYK_REGISTRY_PASSWORD` - -Specify a password to use when connecting to a container registry. Note that using the `--password` flag will override this value. This will be ignored in favour of local Docker binary credentials when Docker is present. - -### Connecting to Snyk API - -By default Snyk CLI will connect to `https://snyk.io/api/v1`. - -#### `SNYK_API` - -Sets API host to use for Snyk requests. Useful for on-premise instances and configuring proxies. If set with `http` protocol CLI will upgrade the requests to `https`. Unless `SNYK_HTTP_PROTOCOL_UPGRADE` is set to `0`. - -#### `SNYK_HTTP_PROTOCOL_UPGRADE=0` - -If set to the value of `0`, API requests aimed at `http` URLs will not be upgraded to `https`. If not set, the default behavior will be to upgrade these requests from `http` to `https`. Useful e.g., for reverse proxies. - -#### `HTTPS_PROXY` and `HTTP_PROXY` - -Allows you to specify a proxy to use for `https` and `http` calls. The `https` in the `HTTPS_PROXY` means that _requests using `https` protocol_ will use this proxy. The proxy itself doesn't need to use `https`. - -## Exit codes - -Possible exit codes and their meaning: - -**0**: success, no vulns found
-**1**: action_needed, vulns found
-**2**: failure, try to re-run command
-**3**: failure, no supported projects detected
+Use context-specific options to pass extra arguments directly to Gradle, Maven, or other build tools. These options are specified last. Example: `snyk test -- --build-cache`