diff --git a/.github/workflows/synchronize-readme.yml b/.github/workflows/synchronize-readme.yml new file mode 100644 index 0000000000..13b3e0a526 --- /dev/null +++ b/.github/workflows/synchronize-readme.yml @@ -0,0 +1,63 @@ +name: Synchronize Readme + +on: + workflow_dispatch: + schedule: + - cron: '0 12 * * 1-5' # Mon-Fri at 12 + +jobs: + build: + name: synchronize-readme + runs-on: ubuntu-latest + steps: + - run: | + # Setup + gh auth setup-git + git config --global user.email "noreply@snyk.io" + git config --global user.name "$GITHUB_ACTOR" + + # Clone the CLI repository + gh repo clone snyk/cli cli -- --depth=1 --quiet + git -C ./cli checkout -B $DESTINATION_BRANCH + + # Retrieve the GitBook content + wget https://raw.githubusercontent.com/snyk/user-docs/main/docs/snyk-cli/getting-started-with-the-snyk-cli.md -O current_gitbook.md + + # Find relative paths to GitBooks assets (such as images) and replace with absolute paths + sed -i \ + -e "s|../.gitbook/assets/|https://github.com/snyk/user-docs/raw/HEAD/docs/.gitbook/assets/|g" \ + current_gitbook.md + + # Replace the README.md content with the GitBook content + cp current_gitbook.md ./cli/README.md + + # If changes, commit and create PR + if [[ $(git -C ./cli status --porcelain) ]]; then + echo "Documentation changes detected" + cd ./cli + npm clean-install + npx prettier --write ./cli/README.md + git push -f -u origin $DESTINATION_BRANCH + + export SHA=$( git rev-parse $DESTINATION_BRANCH:README.md ) + export CONTENT=$( base64 -i README.md ) + gh api --method PUT /repos/:owner/:repo/contents/README.md \ + --field message="$MESSAGE" \ + --field content="$CONTENT" \ + --field encoding="base64" \ + --field branch="$DESTINATION_BRANCH" \ + --field sha="$SHA" + + if [[ ! $(gh pr list --search "$MESSAGE" 2>&1 | grep -e "$MESSAGE";) ]]; then + echo "Creating PR" + gh pr create --title="$MESSAGE" --body="Automatic PR controlled by GitHub Action." --head $DESTINATION_BRANCH + else + echo "PR exists, pushed changes to it." + fi + else + echo "No documentation changes detected, exiting." + fi + env: + DESTINATION_BRANCH: docs/automatic-gitbook-update + MESSAGE: 'docs: synchronizing README from GitBook' + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} diff --git a/README.md b/README.md index 8fed1f37a3..af76e23e83 100644 --- a/README.md +++ b/README.md @@ -1,323 +1,120 @@ -

- -

+# Getting started with the Snyk CLI -# Snyk CLI +## Introduction to Snyk and the Snyk CLI -[Snyk](https://snyk.io) scans and monitors your projects for security vulnerabilities. +[Snyk](https://snyk.io/) is a developer-first, cloud-native security tool to scan and monitor your software development projects for security vulnerabilities. Snyk scans multiple content types for security issues: -![Snyk CLI screenshot](help/snyk-cli-screenshot.png) +- [**Snyk Open Source**](https://docs.snyk.io/scan-using-snyk/snyk-open-source): Find and automatically fix open-source vulnerabilities +- [**Snyk Code**](https://docs.snyk.io/scan-using-snyk/snyk-code): Find and fix vulnerabilities in your application code in real time +- [**Snyk Container**](https://docs.snyk.io/scan-using-snyk/snyk-container): Find and fix vulnerabilities in container images and Kubernetes applications +- [**Snyk Infrastructure as Code**](https://docs.snyk.io/scan-using-snyk/scan-infrastructure): Find and fix insecure configurations in Terraform and Kubernetes code -# What is [Snyk](https://snyk.io)? +[Learn more about what Snyk can do and sign up for a free account](https://snyk.io/). -[Snyk](https://snyk.io) is a developer-first cloud-native security tool. -It covers multiple areas of application security: +The **Snyk CLI brings the functionality of Snyk into your development workflow**. You can run the CLI locally from the command line or in an IDE. You can also run the CLI in your CI/CD pipeline. The following shows an example of Snyk CLI test command output. -1. [**Snyk Open Source**](https://snyk.io/product/open-source-security-management/): Find and automatically fix open source vulnerabilities -2. [**Snyk Code**](https://snyk.io/product/snyk-code/): Find and fix vulnerabilities in your application code in real time -3. [**Snyk Container**](https://snyk.io/product/container-vulnerability-management/): Find and fix vulnerabilities in container images and Kubernetes applications -4. [**Snyk Infrastructure as Code**](https://snyk.io/product/infrastructure-as-code-security/): Find and fix insecure configurations in Terraform and Kubernetes code +
Snyk CLI test command output example

Snyk CLI test command output

-[Learn more about what Snyk can do and sign up for a free account ยป](https://snyk.io) +Snyk CLI scanning **supports many languages and tools.** For detailed information, see the [summary of supported environments](https://docs.snyk.io/getting-started/introducing-snyk#how-can-snyk-work-in-my-environment). -# What is Snyk CLI? +This page explains how to install, authenticate, and start scanning using the CLI. Snyk also has an onboarding wizard to guide you through these steps. For a demonstration, view [Starting with Snyk: an overview of the CLI onboarding flow](https://www.youtube.com/watch?v=adj3VF82-v8). -Snyk CLI brings the functionality of [Snyk](https://snyk.io) into your development workflow. It can be run locally or in your CI/CD pipeline to scan your projects for security issues. +## Install the Snyk CLI and authenticate your machine -## Supported languages and tools +To use the CLI, you must install it and authenticate your machine. See [Install or update the Snyk CLI](https://docs.snyk.io/snyk-cli/install-the-snyk-cli) and [Authenticate the CLI with your account](https://docs.snyk.io/snyk-cli/authenticate-the-cli-with-your-account). You can refer to the [release notes](https://github.com/snyk/cli/releases) for a summary of changes in each release. Before scanning your code, review the [Code execution warning for Snyk CLI](https://docs.snyk.io/snyk-cli/code-execution-warning-for-snyk-cli). -Snyk supports many languages and tools, including Java, .NET, JavaScript, Python, Golang, PHP, C/C++, Ruby, Scala and more. See our [Language Support documentation](https://support.snyk.io/hc/en-us/articles/360020352437-Language-support-summary). +**Note:** Before you can use the CLI for Open Source scanning, you must install your package manager. The needed third-party tools, such as Gradle or Maven, must be in the `PATH`. -CLI also supports [Docker scanning](https://support.snyk.io/hc/en-us/articles/360003946897-Snyk-Container-security-overview) and [Terraform, k8s and other Infrastructure as Code files scanning](https://support.snyk.io/hc/en-us/categories/360001342678-Infrastructure-as-code). +You can use the CLI in your IDE or CI/CD environment. For details, see [Install as part of a Snyk integration](https://docs.snyk.io/snyk-cli/install-the-snyk-cli#install-as-a-part-of-a-snyk-integration). ---- +## Test your installation -# Install Snyk CLI +After authenticating, you can **test your installation**. For a quick test, run `snyk --help`. -Snyk CLI can be installed through multiple channels. +Alternatively, you can perform a **quick test** on a public npm package, for example `snyk test ionic`. -## Install with npm or Yarn +Look at the `test` command **report** in your terminal. The report shows the vulnerabilities Snyk found in the package. For each issue found, Snyk reports the severity of the issue, provides a link to a detailed description, reports the path through which the vulnerable module got into your system, and provides guidance on how to fix the problem. -[Snyk CLI is available as an npm package](https://www.npmjs.com/package/snyk). If you have Node.js installed locally, you can install it by running: +## Scan your development Project -```bash -npm install snyk@latest -g -``` - -or if you are using Yarn: - -```bash -yarn global add snyk -``` - -## More installation methods - -
- Standalone executables (macOS, Linux, Windows) - -### Standalone executables - -Use [GitHub Releases](https://github.com/snyk/snyk/releases) to download a standalone executable of Snyk CLI for your platform. - -We also provide these standalone executables on our official CDN. See [the `release.json` file](https://static.snyk.io/cli/latest/release.json) for the download links: - -```text -https://static.snyk.io/cli/latest/release.json - -# Or for specific version or platform -https://static.snyk.io/cli/v1.666.0/release.json -https://static.snyk.io/cli/latest/snyk-macos -``` - -For example, to download and run the latest Snyk CLI on macOS, you could run: - -```bash -curl https://static.snyk.io/cli/latest/snyk-macos -o snyk -chmod +x ./snyk -mv ./snyk /usr/local/bin/ -``` - -You can also use these direct links to download the executables: - -- macOS: https://static.snyk.io/cli/latest/snyk-macos -- Windows: https://static.snyk.io/cli/latest/snyk-win.exe -- Linux: https://static.snyk.io/cli/latest/snyk-linux -- Linux (arm64): https://static.snyk.io/cli/latest/snyk-linux-arm64 -- Alpine: https://static.snyk.io/cli/latest/snyk-alpine - -Drawback of this method is, that you will have to manually keep the Snyk CLI up to date. - -#### Verifying standalone binaries - -You can verify both shasum of downloaded binaries and their GPG signatures. - -Download location on `static.snyk.io` contains a file called `sha256sums.txt.asc`. -You can download it directly `https://static.snyk.io/cli/latest/sha256sums.txt.asc` or for a specific version like `https://static.snyk.io/cli/v1.666.0/sha256sums.txt.asc`. - -To check that a downloaded file matches the checksum, use a `sha256sum` command like so: - -```bash -grep snyk-macos sha256sums.txt.asc | sha256sum -c - -``` - -If you want to verify Snyk CLI standalone binaries against [Snyk CLI GPG key](help/_about-this-project/snyk-code-signing-public.pgp), you will need to import it first: - -```bash -# A22665FB96CAB0E0973604C83676C4B8289C296E is the key belonging to code-signing@snyk.io -# Copy of this public key is also in this repository /help/_about-this-project/snyk-code-signing-public.pgp -gpg --keyserver hkps://keys.openpgp.org --recv-keys A22665FB96CAB0E0973604C83676C4B8289C296E -``` - -Then verify the file is signed with: - -```bash -gpg --verify sha256sums.txt.asc -``` - -Command output should look like: - -```plain -gpg: Signature made So 8 Jan 14:11:44 2023 CET -gpg: using EDDSA key A22665FB96CAB0E0973604C83676C4B8289C296E -gpg: Good signature from "Snyk Limited " [unknown] -gpg: WARNING: This key is not certified with a trusted signature! -gpg: There is no indication that the signature belongs to the owner. -Primary key fingerprint: A226 65FB 96CA B0E0 9736 04C8 3676 C4B8 289C 296E -``` - -
- -
- Install with Homebrew (macOS, Linux) - -### Homebrew - -Install Snyk CLI from [Snyk tap](https://github.com/snyk/homebrew-tap) with [Homebrew](https://brew.sh) by running: - -```bash -brew tap snyk/tap -brew install snyk -``` - -
- -
- Scoop (Windows) - -### Scoop +**Note:** Before using the Snyk CLI to test your Open Source Project for vulnerabilities, with limited exceptions, you must **build your Project**. For details, see [Which Projects must be built before testing with CLI?](https://support.snyk.io/hc/en-us/articles/360015552617-Which-projects-must-be-built-before-testing-with-CLI-) -Install Snyk CLI from our [Snyk bucket](https://github.com/snyk/scoop-snyk) with [Scoop](https://scoop.sh) on Windows: +In addition, depending on the language of your open-source Project, you may need to **set up your language environment** before using the Snyk CLI. For details, refer to [Supported languages, frameworks, and feature availability overview.](https://docs.snyk.io/scan-using-snyk/supported-languages-and-frameworks/supported-languages-frameworks-and-feature-availability-overview) -``` -scoop bucket add snyk https://github.com/snyk/scoop-snyk -scoop install snyk -``` - -
- -
- Snyk CLI in a Docker image - -### Snyk CLI in a Docker image - -Snyk CLI can also be run from a Docker image. Snyk offers multiple Docker tags under [`snyk/snyk`](https://hub.docker.com/r/snyk/snyk). These images wrap the Snyk CLI and depending on the Tag come with a relevant tooling for different projects. [See the snyk/images on GitHub for more details and examples](https://github.com/snyk/snyk-images). - -
- -## Install as a part of a Snyk CLI integration - -Snyk also offers many integrations into developer tooling. These integrations will install and manage the Snyk CLI for you. For example: - -- [Snyk Jenkins plugin](https://github.com/jenkinsci/snyk-security-scanner-plugin) -- [CircleCI Orb](https://github.com/snyk/snyk-orb) -- [Azure Pipelines Task](https://github.com/snyk/snyk-azure-pipelines-task) -- [GitHub Actions](https://github.com/snyk/actions) -- [IntelliJ IDE Plugin](https://github.com/snyk/snyk-intellij-plugin) -- [VS Code Extension](https://marketplace.visualstudio.com/items?itemName=snyk-security.snyk-vulnerability-scanner) -- [Eclipse IDE Extension](https://github.com/snyk/snyk-eclipse-plugin) -- [Maven plugin](https://github.com/snyk/snyk-maven-plugin) -- And many more. See [the Integrations documentation](https://support.snyk.io/hc/en-us/categories/360000598398-Integrations) - -

- - Snyk CLI IDE integration - -

- ---- - -# Getting started with Snyk CLI - -Once you installed the Snyk CLI, you can verify it's working by running: - -```bash -snyk --help -``` - -See the [full Snyk CLI help](./help/cli-commands). - -## Authenticating Snyk CLI - -Snyk CLI depends on [Snyk.io](https://snyk.io) APIs. Connect your Snyk CLI with [Snyk.io](https://snyk.io) by running: - -```bash -snyk auth -``` +After you have installed the CLI and authenticated your machine, to **scan an open-source Project**, use `cd /my/project/` to change the current directory to`a`folder containing a supported package manifest file, such as `package.json`, `pom.xml`, or `composer.lock`. Then run `snyk test`. All vulnerabilities identified are listed, including their path and fix guidance. -## Setting up language support +To scan your **source code** run `snyk code test`. -Depending on your project's language, you might need to setup your language environment before using Snyk. +You can **scan a Docker image** by its tag running, for example: `snyk container test ubuntu:18.04`. -See our [Language Support documentation](https://support.snyk.io/hc/en-us/articles/360020352437-Language-support-summary). +To scan a **Kubernetes (K8s) file** run the following:\ +`snyk iac test /path/to/kubernetes_file.yaml` -## Scanning your project +For details about using the Snyk CLI to scan each content type, see the following: -If you are already in a folder with a supported project, start by running: +- [Snyk CLI for Snyk Open Source](https://docs.snyk.io/snyk-cli/scan-and-maintain-projects-using-the-cli/snyk-cli-for-open-source) and the CLI help for the [`test`](https://docs.snyk.io/snyk-cli/commands/test) and [`monitor`](https://docs.snyk.io/snyk-cli/commands/monitor) commands +- [Snyk CLI for Snyk Code](https://docs.snyk.io/snyk-cli/commands/code) and the [Snyk Code CLI help](https://docs.snyk.io/snyk-cli/scan-and-maintain-projects-using-the-cli/snyk-cli-for-snyk-code) +- [Snyk CLI for Snyk Container](https://docs.snyk.io/snyk-cli/commands/container), including Docker scanning, and the [Snyk Container CLI help](https://docs.snyk.io/snyk-cli/scan-and-maintain-projects-using-the-cli/snyk-cli-for-snyk-container) +- [Snyk CLI for Snyk IaC](https://docs.snyk.io/snyk-cli/scan-and-maintain-projects-using-the-cli/snyk-cli-for-iac), including Terraform and Kubernetes (K8s) Projects, and the [Snyk IAC CLI help](https://docs.snyk.io/snyk-cli/commands/iac) -```bash -snyk test -``` - -Or scan a Docker image by its tag with [Snyk Container](https://snyk.io/product/container-vulnerability-management/): +## Monitor your Open Source or Container Project -```bash -snyk container test ubuntu:18.04 -``` +Snyk can monitor your Open Source or Container integrated SCM Project periodically and alert you to new vulnerabilities. To set up your Project to be monitored, run `snyk monitor` or `snyk container monitor`. -Or a k8s file: - -```bash -snyk iac test /path/to/kubernetes_file.yaml -``` - -## Monitoring your project - -Snyk can also monitor your project periodically and alert you for new vulnerabilities. The `snyk monitor` is similar to `snyk test` and can be used to create a project on the Snyk website that will be continuously monitored for new vulnerabilities. - -

- - Snyk CLI monitor projects - -

+This creates a snapshot of your current dependencies so Snyk can regularly scan your code. Snyk can then alert you about newly disclosed vulnerabilities as they are introduced or when a previously unavailable patch or upgrade path is created. The following code shows an example of the output of the `snyk monitor` command. ``` > snyk monitor Monitoring /project (project-name)... -Explore this snapshot at https://app.snyk.io/org/my-org/project/29361c2c-9005-4692-8df4-88f1c040fa7c/history/e1c994b3-de5d-482b-9281-eab4236c851e +Explore this snapshot at +https://app.snyk.io/org/my-org/project/29361c2c-9005-4692 +-8df4-88f1c040fa7c/history/e1c994b3-de5d-482b-9281-eab4236c851e -Notifications about newly disclosed issues related to these dependencies will be emailed to you. +Notifications about newly disclosed issues related to these +dependencies will be emailed to you. ``` -### Add Snyk to your CI/CD - -Snyk is really powerful when you are continuously scanning and monitoring your projects for vulnerabilities. +You can log in to your Snyk account and navigate to the [Projects page](https://app.snyk.io/projects) to find the latest snapshot and scan results: -Use one of [our integrations](#install-as-a-part-of-a-snyk-cli-integration) to stay secure. +
Snyk monitor snapshot and scan results

Snyk monitor snapshot and scan results

-You can authorize Snyk CLI in your CI/CD programatically: +For more information, see [Monitor your Projects at regular intervals](https://docs.snyk.io/snyk-cli/scan-and-maintain-projects-using-the-cli/monitor-your-projects-at-regular-intervals). -```bash -# Using a SNYK_TOKEN envvar (preferred) -SNYK_TOKEN= snyk test - -# Or using a Snyk auth command -snyk auth -snyk test -``` +## Running out of tests -## More flags and options to try - -Here are some flags that you might find useful: - -- `--severity-threshold=low|medium|high|critical` - - Only report vulnerabilities of provided level or higher. - -- `--json` - - Prints results in JSON format. - -- `--all-projects` - - Auto-detect all projects in working directory - -[See all the available commands and options](./help/cli-commands) by running `--help`: - -```bash -snyk --help -# or get help for a specific command like -snyk iac --help -snyk code --help -``` +Snyk allows unlimited tests for public repositories. If you are on the Free plan, you have a limited number of tests per month. Paid plans have unlimited tests on private and public repositories. If you are on the Free plan and notice that your test count is quickly being used, even with public repositories, you can remedy this by telling Snyk the public url of the repository that is being scanned by the Snyk CLI. This ensures that Snyk does not count a public repository towards the test limits. -# Getting support +If you run out of tests on an open-source Project, follow these steps: -If you need support using Snyk CLI, please [contact support](https://support.snyk.io). +- Run `snyk monitor`. +- Open the Snyk UI and navigate to the **settings** of the Project. +- Enter the URL of your open-source repository in **Git remote URL**. -# Contributing +## Additional information about the Snyk CLI -If you are an external contributor, before working on any contributions, please first [contact support](https://support.snyk.io) to discuss the issue or feature request with us. +Run `snyk help` or see the [CLI commands and options summary](https://docs.snyk.io/snyk-cli/cli-commands-and-options-summary). -If you are contributing to Snyk CLI, see [our contributing guidelines](CONTRIBUTING.md) +See the course [Introduction to the Snyk CLI](https://learn.snyk.io/lesson/snyk-cli/https://learn.snyk.io/lesson/snyk-cli/) for a quick video training session. -For information on how Snyk CLI is implemented, see [our design decisions](help/_about-this-project/README.md). +Snyk also provides a [cheat sheet](https://res.cloudinary.com/snyk/image/upload/v1664236143/cheat-sheets/cheat-sheet-snyk-cli-v3.pdf) ([blog post](https://snyk.io/blog/snyk-cli-cheat-sheet/)) and a [video tutorial](https://www.youtube.com/watch?v=xp_LtchEkT8). -This repository is a monorepo, also covering other projects and tools: +In particular, see the information about the following options that you may find useful: -- [`@snyk/fix`](packages/snyk-fix): npm package for `snyk fix` libraries. -- [`@snyk/protect`](packages/snyk-protect): npm package for [`snyk-protect`](https://www.npmjs.com/package/@snyk/protect) command. +- `--severity-threshold=low|medium|high|critical`: Report only vulnerabilities of the specified level or higher. +- `--json`: Print results in JSON format. +- `--all-projects`: Auto-detect all Projects in the working directory. -# Security +For detailed information about the CLI, see the [CLI docs](https://docs.snyk.io/snyk-cli). -For any security issues or concerns, please see [SECURITY.md](SECURITY.md) file in this repository. +## Getting support for the Snyk CLI -# Notices +[Submit a ticket](https://support.snyk.io/hc/en-us/requests/new) to Snyk support whenever you need help with the Snyk CLI or Snyk in general. Note that Snyk support does not actively monitor GitHub Issues on any [Snyk development project](https://github.com/snyk). -## Snyk API usage policy +## Contributing to the Snyk CLI -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). +The Snyk CLI project is open-source, but Snyk does not encourage outside contributors. ---- +## Security -Made with ๐Ÿ’œ by Snyk +For any security issues or concerns, see the [SECURITY.md](https://github.com/snyk/snyk/blob/master/SECURITY.md) file in the GitHub repository.