From 745776137dbdc5adf7b6867530c7f3028032d73b Mon Sep 17 00:00:00 2001 From: eyalbe4 Date: Fri, 1 Apr 2022 11:04:45 +0300 Subject: [PATCH 1/7] Docs update --- README.md | 190 +++++++------------- templates/github-actions/README.md | 15 +- templates/github-actions/frogbot-dotnet.yml | 12 +- templates/github-actions/frogbot-go.yml | 8 + templates/github-actions/frogbot-gradle.yml | 8 + templates/github-actions/frogbot-maven.yml | 8 + templates/github-actions/frogbot-npm.yml | 12 +- templates/github-actions/frogbot-nuget.yml | 13 +- templates/github-actions/frogbot-pip.yml | 12 +- templates/github-actions/frogbot-pipenv.yml | 12 +- 10 files changed, 149 insertions(+), 141 deletions(-) diff --git a/README.md b/README.md index 7e742b779..dd9f6b418 100644 --- a/README.md +++ b/README.md @@ -6,24 +6,33 @@ [![Coverage Status](https://coveralls.io/repos/github/jfrog/frogbot/badge.svg?branch=dev)](https://coveralls.io/github/jfrog/frogbot?branch=dev) ## 🤖 What is Frogbot? - -Frogbot is a Git bot that scans your pull requests with JFrog Xray for security vulnerabilities. Frogbot can be easily triggered following the creation of a new pull request. Frogbot adds the scan results as a comment on the pull request. If no vulnerabilities are found, Frogbot will also add a comment, confirming this. Currently GitHub and GitLab are supported. Bitbucket will be supported soon. +Frogbot is a Git bot that scans your pull requests with [JFrog Xray](https://jfrog.com/xray/) for security vulnerabilities. Frogbot adds the scan results as a comment on the pull request. If no vulnerabilities are found, Frogbot will also add a comment, confirming this. Currently GitHub and GitLab are supported. Bitbucket will be supported soon. ## 🕵 How does it work? - -After a new pull request is created, one of the maintainers can add the "Frogbot scan" label to the pull request. Frogbot will then be triggered and the pull request will be scanned. The scan output will include only new vulnerabilities added by the pull request. Vulnerabilities that existed in the code prior to the pull request created will not be added to the report. - +### General +After a new pull request is created, a maintainer of the git repository can trigger Frogbot to scan the pull request. The scan is triggered from the git UI. The scan output will include only new vulnerabilities added by the pull request. Vulnerabilities that aren't new and existed in the code prior to the pull request creation will not be added to the report. + +### On GitHub +1. A developer opens a pull request +2. If missing, Frogbot creates the `🐸 frogbot scan` laben in the repository +3. A maintainer of the repository assigns the `🐸 frogbot scan` label on this pull request +4. Frogbot gets triggered by the label, scans the pull request, adds a comment with the scan results and removes the label from the pull request +5. Frogbot can be triggered again following new commits, by adding the label to the pull request again + +### On GitLab +1. A developer opens a merge request +2. A maintainer of the repository triggers the manual frogbot-scan job +3. Frogbot gets triggered by the job, scans the merge request and adds a comment with the scan results +4. Frogbot can be triggered again following new commits, by trigerring the frogbot-scan job again +[![GitLab CI Run Button](./images/gitlab-run-button.png)](#-Using-Frogbot-with-GitLab-CI) + ## Pull Request Comments - ### 👍 No issues - If no vulnerabilities were found, Frogbot will automatically add the following comment to the pull request: [![](https://raw.githubusercontent.com/jfrog/frogbot/master/resources/noVulnerabilityBanner.png)](#-no-issues) ### 👎 Issues were found - -If vulnerabilities were found, Frogbot will mention them in a comment to the pull request. For example: - +If vulnerabilities were found, Frogbot will add them in a comment on the pull request. For example: [![](https://raw.githubusercontent.com/jfrog/frogbot/master/resources/vulnerabilitiesBanner.png)](#-issues-were-found) | SEVERITY | IMPACTED PACKAGE | VERSION | FIXED VERSIONS | COMPONENT | COMPONENT VERSION | CVE | @@ -32,77 +41,41 @@ If vulnerabilities were found, Frogbot will mention them in a comment to the pul | ![](https://raw.githubusercontent.com/jfrog/frogbot/master/resources/highSeverity.png) High | github.com/mholt/archiver/v3 | v3.5.1 | | github.com/mholt/archiver/v3 | v3.5.1 | | ![](https://raw.githubusercontent.com/jfrog/frogbot/master/resources/mediumSeverity.png) Medium | github.com/nats-io/nats-streaming-server | v0.21.0 | [0.24.3] | github.com/nats-io/nats-streaming-server | v0.21.0 | CVE-2022-26652 | -## 🖥️ Usage - -- [Using Frogbot with GitHub Actions](#using-frogbot-with-github-actions) -- [Using Frogbot with GitLab CI](#using-frogbot-with-gitlab-ci) - -### Using Frogbot with GitHub Actions - -For a quick start, please refer to our [GitHub Actions templates](templates/github-actions/README.md#github-actions-templates). - -#### How does it work? - -1. User opens a Pull Request -1. If missing, Frogbot creates a label `🐸 frogbot scan` in the repository -1. A maintainer reviews the Pull Request and assigns `🐸 frogbot scan` -1. Frogbot gets triggered by the label, unlabels it, and executes the pull request scanning - -Here's a recommended structure of a `frogbot.yml` workflow file: - -```yml -name: "Frogbot" -on: - # After a pull request opened, Frogbot automatically creates the "🐸 frogbot scan" label if needed. - # After "🐸 frogbot scan" label was added to a pull request, Frogbot scans the pull request. - pull_request_target: - types: [opened, labeled] -jobs: - scan-pull-request: - runs-on: ubuntu-latest - steps: - - uses: actions/checkout@v2 - with: - ref: ${{ github.event.pull_request.head.sha }} - - # Install prerequisites - "setup-go", "setup-node", "setup-python", etc. - # ... - - - uses: jfrog/frogbot@v1 - env: - # [Mandatory] JFrog platform URL - JF_URL: ${{ secrets.JF_URL }} - - # [Mandatory if JF_USER and JF_PASSWORD are not provided] JFrog access token with 'read' permissions on Xray service - JF_ACCESS_TOKEN: ${{ secrets.JF_ACCESS_TOKEN }} - - # [Mandatory if JF_ACCESS_TOKEN is not provided] JFrog platform username - JF_USER: ${{ secrets.JF_USER }} - - # [Mandatory if JF_ACCESS_TOKEN is not provided] JFrog platform password - JF_PASSWORD: ${{ secrets.JF_PASSWORD }} - - # [Mandatory] The GitHub token is automatically generated for the job - JF_GIT_TOKEN: ${{ secrets.GITHUB_TOKEN }} - - # [Optional] Xray Watches. Learn more about them here: https://www.jfrog.com/confluence/display/JFROG/Configuring+Xray+Watches - JF_WATCHES: ,... - - # [Optional] JFrog project. Learn more about it here: https://www.jfrog.com/confluence/display/JFROG/Projects - JF_PROJECT: - - # [Optional] The command that installs the dependencies. For example - "npm i", "nuget restore", "dotnet restore", "pip install", etc. - JF_INSTALL_DEPS_CMD: +## 🖥️ Installing and Using Frogbot +### General +1. Frogbot requires a JFrog environment to scan pull requests with. Don't have a JFrog environment? No problem - [Set Up a FREE JFrog Environment in the Cloud](set-up-a-free-jfrog-environment-in-the-cloud). You'll later save its connection details (URLm username and password) as secrets in git. +2. Setting up Frogbot on a GitHub repository? [Install Frogbot using GitHub Actions](#install-frogbot-using-github-actions) +3. Setting up Frogbot on a GitLab repository? [Install Frogbot using GitLab CI](#install-frogbot-using-gitlab-ci) + +### Set Up a FREE JFrog Environment in the Cloud +Need a FREE JFrog environment in the cloud, which Frogbot can scan pull requests with? Just run one of the following commands in your terminal, to set up an environment in less than a minute. The commands will do the following: +* Install JFrog CLI on your machine. +* Create a FREE JFrog environment in the cloud for you. +After the set up is complete, you'll receive an email with your JFrog environment connection details, which you can then store as secrets in git. +**On MacOS and Linux using cUrl** +``` +curl -fL https://getcli.jfrog.io?setup | sh +``` +**On Windows using PowerShell** +``` +powershell "Start-Process -Wait -Verb RunAs powershell '-NoProfile iwr https://releases.jfrog.io/artifactory/jfrog-cli/v2-jf/[RELEASE]/jfrog-cli-windows-amd64/jf.exe -OutFile $env:SYSTEMROOT\system32\jf.exe'" ; jf setup ``` -### Using Frogbot with GitLab CI +### Install Frogbot using GitHub Actions +1. Make sure you have the connection details of your JFrog environment. +2. Save the JFrog connection details as secrets in GitHub with the following names - *JF_URL*, *JF_USER* and *JF_PASSWORD*. You can also use *JF_ACCESS_TOKEN* instead of *JF_USER* and *JF_PASSWORD*. +3. Use one of these [GitHub Actions templates](templates/github-actions/README.md#github-actions-templates) to create a file named `frogbot.yml`. +4. Push the `frogbot.yml` file to the `.github/workflow` directory at the root of your GitHub repository. -#### How does it work? +### Install Frogbot using GitLab CI +1. Make sure you have the connection details of your JFrog environment. +2. Save the JFrog connection details as secrets in GitLab with the following names - *JF_URL*, *JF_USER* and *JF_PASSWORD*. You can also use *JF_ACCESS_TOKEN* instead of *JF_USER* and *JF_PASSWORD*. +4. Add a job named `frogbot-scan` to your `.gitlab-ci.yml` file in your GitLab repositorym using the below structure. -1. User opens a Merge Request -1. A maintainer reviews the Merge Request and runs the manual frogbot-scan job +**Important** -Here's a recommended structure of frogbot-scan job in a `.gitlab-ci.yml`: +* If the project uses npm, pip, pipenv, nuget or dotnet to download its depedencies, make sure to set the command that downloads your project depedencies as the value of the *JF_INSTALL_DEPS_CMD* variable. For example, `npm i` or `nuget restore` +* Make sure that either *JF_USER* and *JF_PASSWORD* or *JF_ACCESS_TOKEN* are set, but not both. ```yml frogbot-scan: @@ -110,20 +83,28 @@ frogbot-scan: - if: $CI_PIPELINE_SOURCE == 'merge_request_event' when: manual variables: - # [Mandatory] JFrog platform URL + # [Mandatory only for project which npm, pip, pipenv, nuget and dotnet] + # The command that installs the project dependencies (e.g "npm i", "nuget restore" or "dotnet restore") + JF_INSTALL_DEPS_CMD: "" + + # [Mandatory] + # JFrog platform URL JF_URL: $JF_URL - # [Mandatory if JF_ACCESS_TOKEN is not provided] JFrog user and password with 'read' permissions on Xray service + # [Mandatory if JF_ACCESS_TOKEN is not provided] + # JFrog user and password with 'read' permissions for Xray JF_USER: $JF_USER JF_PASSWORD: $JF_PASSWORD - # [Optional] The command that installs the project dependencies (e.g "npm i", "nuget restore" or "dotnet restore") - JF_INSTALL_DEPS_CMD: "" + # [Mandatory if JF_USER and JF_PASSWORD are not provided] + # JFrog access token with 'read' permissions for Xray + JF_ACCESS_TOKEN: $JF_ACCESS_TOKEN - # [Mandatory] GitLab accesses token with the following permissions scopes: api, read_api, read_user, read_repository + # [Mandatory] + # GitLab accesses token with the following permissions scopes: api, read_api, read_user, read_repository JF_GIT_TOKEN: $USER_TOKEN - # Predefined gitlab variables + # Predefined gitlab variables. There's no need to set them JF_GIT_PROVIDER: gitlab JF_GIT_OWNER: $CI_PROJECT_NAMESPACE JF_GIT_REPO: $CI_PROJECT_NAME @@ -134,48 +115,5 @@ frogbot-scan: - ./frogbot scan-pull-request ``` -[![GitLab CI Run Button](./images/gitlab-run-button.png)](#-Using-Frogbot-with-GitLab-CI) - -### Download Frogbot Manually - -Download Frogbot using the following command: - -```bash -curl -fLg "https://releases.jfrog.io/artifactory/frogbot/v1/[RELEASE]/getFrogbot.sh" | sh -``` - -
-Download Frogbot through Artifactory - -If your agent has no internet access, you can configure the pipeline to download Frogbot and from a JFrog Artifactory instance, which is configured to proxy the download repositories. - -1. Create a remote repository in Artifactory for downloading Frogbot. Name the repository frogbot and set its URL to https://releases.jfrog.io/artifactory/frogbot/v1/ -2. Depends on your agent's architecture and operating system, download Frogbot using curl: - -```bash -curl -fLg "https://acme.jfrog.io/artifactory/frogbot/[RELEASE]//frogbot" -H "Authorization: Bearer $JF_ACCESS_TOKEN" -o frogbot -``` - -##### Available architechtures: - -- frogbot-linux-386 -- frogbot-linux-amd64 -- frogbot-linux-arm -- frogbot-linux-arm64 -- frogbot-linux-ppc64 -- frogbot-linux-ppc64le -- frogbot-linux-s390x -- frogbot-mac-386 -- frogbot-windows-amd64 - -For example: - -```bash -curl -fLg "https://acme.jfrog.io/artifactory/frogbot/[RELEASE]/frogbot-linux-386/frogbot" -H "Authorization: Bearer $JF_ACCESS_TOKEN" -o frogbot -``` - -
- ## 💻 Contributions - -We welcome pull requests from the community. To help us improving this project, please read our [contribution](./CONTRIBUTING.md#-guidelines) guide. +We welcome pull requests from the community. To help us improve this project, please read our [contribution](./CONTRIBUTING.md#-guidelines) guide. diff --git a/templates/github-actions/README.md b/templates/github-actions/README.md index 550d8390d..ec1b52d3c 100644 --- a/templates/github-actions/README.md +++ b/templates/github-actions/README.md @@ -1,10 +1,15 @@ -# GitHub Actions Templates +# Frogbot GitHub Actions Templates +## General +Use these templates to install [Frogbot](https://github.com/jfrog/frogbot/blob/master/README.md#frogbot) on your GitHub repository. -Use these templates to immediately start scanning your pull requests in your GitHub repository. -To use the templates in this directory, put the relevant `.yml` file under `.github/workflow` directory in the root of your repository. - -The following templates are available: +## Using the Templates +1. Make sure you have the connection details of your JFrog environment. +2. Save the JFrog connection details as secrets in GitHub with the following names - *JF_URL*, *JF_USER* and *JF_PASSWORD*. You can also use *JF_ACCESS_TOKEN* instead of *JF_USER* and *JF_PASSWORD*. +3. Use one of the templates below, depending on the tool used to download dependencies for you project, to create a file named `frogbot.yml`. +4. Only if the template you're using includes the `JF_INSTALL_DEPS_CMD` variable, make sure it includes the correct command to download your project depedencies. For example, `npm i` or `nuget restore`. +5. Push the `frogbot.yml` file to the `.github/workflow` directory at the root of your GitHub repository. +## The Available Templates - [Maven](frogbot-maven.yml) - [Gradle](frogbot-gradle.yml) - [npm](frogbot-npm.yml) diff --git a/templates/github-actions/frogbot-dotnet.yml b/templates/github-actions/frogbot-dotnet.yml index 2c5ca19c8..e1e2d9a88 100644 --- a/templates/github-actions/frogbot-dotnet.yml +++ b/templates/github-actions/frogbot-dotnet.yml @@ -19,6 +19,9 @@ jobs: - uses: jfrog/frogbot@v1 env: + # [Mandatory] The command that installs the dependencies + JF_INSTALL_DEPS_CMD: "dotnet restore" + # [Mandatory] JFrog platform URL JF_URL: ${{ secrets.JF_URL }} @@ -28,5 +31,10 @@ jobs: # [Manadatory] The GitHub token automatically generated for the job JF_GIT_TOKEN: ${{ secrets.GITHUB_TOKEN }} - # [Optional] The command that installs the dependencies - JF_INSTALL_DEPS_CMD: "dotnet restore" + # Uncomment the below options if you'd like to use them. + + # [Optional] Xray Watches. Learn more about them here: https://www.jfrog.com/confluence/display/JFROG/Configuring+Xray+Watches + # JF_WATCHES: ,... + + # [Optional] JFrog project. Learn more about it here: https://www.jfrog.com/confluence/display/JFROG/Projects + # JF_PROJECT: diff --git a/templates/github-actions/frogbot-go.yml b/templates/github-actions/frogbot-go.yml index bebbee46a..27c4c4f16 100644 --- a/templates/github-actions/frogbot-go.yml +++ b/templates/github-actions/frogbot-go.yml @@ -28,3 +28,11 @@ jobs: # [Manadatory] The GitHub token automatically generated for the job JF_GIT_TOKEN: ${{ secrets.GITHUB_TOKEN }} + + # Uncomment the below options if you'd like to use them. + + # [Optional] Xray Watches. Learn more about them here: https://www.jfrog.com/confluence/display/JFROG/Configuring+Xray+Watches + # JF_WATCHES: ,... + + # [Optional] JFrog project. Learn more about it here: https://www.jfrog.com/confluence/display/JFROG/Projects + # JF_PROJECT: diff --git a/templates/github-actions/frogbot-gradle.yml b/templates/github-actions/frogbot-gradle.yml index 0faf9f1b0..30bfa95ae 100644 --- a/templates/github-actions/frogbot-gradle.yml +++ b/templates/github-actions/frogbot-gradle.yml @@ -31,3 +31,11 @@ jobs: # [Manadatory] The GitHub token automatically generated for the job JF_GIT_TOKEN: ${{ secrets.GITHUB_TOKEN }} + + # Uncomment the below options if you'd like to use them. + + # [Optional] Xray Watches. Learn more about them here: https://www.jfrog.com/confluence/display/JFROG/Configuring+Xray+Watches + # JF_WATCHES: ,... + + # [Optional] JFrog project. Learn more about it here: https://www.jfrog.com/confluence/display/JFROG/Projects + # JF_PROJECT: diff --git a/templates/github-actions/frogbot-maven.yml b/templates/github-actions/frogbot-maven.yml index bec5b3a14..6069f6a89 100644 --- a/templates/github-actions/frogbot-maven.yml +++ b/templates/github-actions/frogbot-maven.yml @@ -29,3 +29,11 @@ jobs: # [Manadatory] The GitHub token automatically generated for the job JF_GIT_TOKEN: ${{ secrets.GITHUB_TOKEN }} + + # Uncomment the below options if you'd like to use them. + + # [Optional] Xray Watches. Learn more about them here: https://www.jfrog.com/confluence/display/JFROG/Configuring+Xray+Watches + # JF_WATCHES: ,... + + # [Optional] JFrog project. Learn more about it here: https://www.jfrog.com/confluence/display/JFROG/Projects + # JF_PROJECT: diff --git a/templates/github-actions/frogbot-npm.yml b/templates/github-actions/frogbot-npm.yml index 69797245e..e6032902b 100644 --- a/templates/github-actions/frogbot-npm.yml +++ b/templates/github-actions/frogbot-npm.yml @@ -20,6 +20,9 @@ jobs: - uses: jfrog/frogbot@v1 env: + # [Mandatory] The command that installs the dependencies + JF_INSTALL_DEPS_CMD: "npm i" + # [Mandatory] JFrog platform URL JF_URL: ${{ secrets.JF_URL }} @@ -29,5 +32,10 @@ jobs: # [Manadatory] The GitHub token automatically generated for the job JF_GIT_TOKEN: ${{ secrets.GITHUB_TOKEN }} - # [Optional] The command that installs the dependencies - JF_INSTALL_DEPS_CMD: "npm i" + # Uncomment the below options if you'd like to use them. + + # [Optional] Xray Watches. Learn more about them here: https://www.jfrog.com/confluence/display/JFROG/Configuring+Xray+Watches + # JF_WATCHES: ,... + + # [Optional] JFrog project. Learn more about it here: https://www.jfrog.com/confluence/display/JFROG/Projects + # JF_PROJECT: diff --git a/templates/github-actions/frogbot-nuget.yml b/templates/github-actions/frogbot-nuget.yml index 5edff5591..488730636 100644 --- a/templates/github-actions/frogbot-nuget.yml +++ b/templates/github-actions/frogbot-nuget.yml @@ -19,6 +19,10 @@ jobs: - uses: jfrog/frogbot@v1 env: + + # [Optional] The command that installs the dependencies + JF_INSTALL_DEPS_CMD: "nuget restore" + # [Mandatory] JFrog platform URL JF_URL: ${{ secrets.JF_URL }} @@ -28,5 +32,10 @@ jobs: # [Manadatory] The GitHub token automatically generated for the job JF_GIT_TOKEN: ${{ secrets.GITHUB_TOKEN }} - # [Optional] The command that installs the dependencies - JF_INSTALL_DEPS_CMD: "nuget restore" + # Uncomment the below options if you'd like to use them. + + # [Optional] Xray Watches. Learn more about them here: https://www.jfrog.com/confluence/display/JFROG/Configuring+Xray+Watches + # JF_WATCHES: ,... + + # [Optional] JFrog project. Learn more about it here: https://www.jfrog.com/confluence/display/JFROG/Projects + # JF_PROJECT: diff --git a/templates/github-actions/frogbot-pip.yml b/templates/github-actions/frogbot-pip.yml index 5342ec771..f01de4d89 100644 --- a/templates/github-actions/frogbot-pip.yml +++ b/templates/github-actions/frogbot-pip.yml @@ -19,6 +19,9 @@ jobs: - uses: jfrog/frogbot@v1 env: + # [Optional] The command that installs the dependencies + JF_INSTALL_DEPS_CMD: "pip install" + # [Mandatory] JFrog platform URL JF_URL: ${{ secrets.JF_URL }} @@ -28,5 +31,10 @@ jobs: # [Manadatory] The GitHub token automatically generated for the job JF_GIT_TOKEN: ${{ secrets.GITHUB_TOKEN }} - # [Optional] The command that installs the dependencies - JF_INSTALL_DEPS_CMD: "pip install" + # Uncomment the below options if you'd like to use them. + + # [Optional] Xray Watches. Learn more about them here: https://www.jfrog.com/confluence/display/JFROG/Configuring+Xray+Watches + # JF_WATCHES: ,... + + # [Optional] JFrog project. Learn more about it here: https://www.jfrog.com/confluence/display/JFROG/Projects + # JF_PROJECT: diff --git a/templates/github-actions/frogbot-pipenv.yml b/templates/github-actions/frogbot-pipenv.yml index 4b074580a..7839afdd7 100644 --- a/templates/github-actions/frogbot-pipenv.yml +++ b/templates/github-actions/frogbot-pipenv.yml @@ -21,6 +21,9 @@ jobs: - uses: jfrog/frogbot@v1 env: + # [Optional] The command that installs the dependencies + JF_INSTALL_DEPS_CMD: "pipenv install" + # [Mandatory] JFrog platform URL JF_URL: ${{ secrets.JF_URL }} @@ -30,5 +33,10 @@ jobs: # [Manadatory] The GitHub token automatically generated for the job JF_GIT_TOKEN: ${{ secrets.GITHUB_TOKEN }} - # [Optional] The command that installs the dependencies - JF_INSTALL_DEPS_CMD: "pipenv install" + # Uncomment the below options if you'd like to use them. + + # [Optional] Xray Watches. Learn more about them here: https://www.jfrog.com/confluence/display/JFROG/Configuring+Xray+Watches + # JF_WATCHES: ,... + + # [Optional] JFrog project. Learn more about it here: https://www.jfrog.com/confluence/display/JFROG/Projects + # JF_PROJECT: From 5e2ac693a12d9007b3be0c0f519eb1285d5c9bdd Mon Sep 17 00:00:00 2001 From: eyalbe4 Date: Fri, 1 Apr 2022 11:23:11 +0300 Subject: [PATCH 2/7] README fixes and improvements --- README.md | 8 +++----- 1 file changed, 3 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index dd9f6b418..6d855c1ef 100644 --- a/README.md +++ b/README.md @@ -1,12 +1,10 @@ # Frogbot - ## Project Status - [![Build status](https://github.com/jfrog/frogbot/actions/workflows/test.yml/badge.svg)](https://github.com/jfrog/frogbot/actions/workflows/test.yml) [![GitHub Action Test](https://github.com/jfrog/frogbot/actions/workflows/action-test.yml/badge.svg)](https://github.com/jfrog/frogbot/actions/workflows/action-test.yml) [![Coverage Status](https://coveralls.io/repos/github/jfrog/frogbot/badge.svg?branch=dev)](https://coveralls.io/github/jfrog/frogbot?branch=dev) ## 🤖 What is Frogbot? -Frogbot is a Git bot that scans your pull requests with [JFrog Xray](https://jfrog.com/xray/) for security vulnerabilities. Frogbot adds the scan results as a comment on the pull request. If no vulnerabilities are found, Frogbot will also add a comment, confirming this. Currently GitHub and GitLab are supported. Bitbucket will be supported soon. +Frogbot is a git bot that scans your pull requests with [JFrog Xray](https://jfrog.com/xray/) for security vulnerabilities. Frogbot adds the scan results as a comment on the pull request. If no vulnerabilities are found, Frogbot will also add a comment, confirming this. Currently GitHub and GitLab are supported. Bitbucket will be supported soon. ## 🕵 How does it work? ### General @@ -43,13 +41,13 @@ If vulnerabilities were found, Frogbot will add them in a comment on the pull re ## 🖥️ Installing and Using Frogbot ### General -1. Frogbot requires a JFrog environment to scan pull requests with. Don't have a JFrog environment? No problem - [Set Up a FREE JFrog Environment in the Cloud](set-up-a-free-jfrog-environment-in-the-cloud). You'll later save its connection details (URLm username and password) as secrets in git. +1. Frogbot requires a JFrog environment to scan pull requests with. Don't have a JFrog environment? No problem - [Set Up a FREE JFrog Environment in the Cloud](#set-up-a-free-jfrog-environment-in-the-cloud). You'll later save its connection details (URLm username and password) as secrets in git. 2. Setting up Frogbot on a GitHub repository? [Install Frogbot using GitHub Actions](#install-frogbot-using-github-actions) 3. Setting up Frogbot on a GitLab repository? [Install Frogbot using GitLab CI](#install-frogbot-using-gitlab-ci) ### Set Up a FREE JFrog Environment in the Cloud Need a FREE JFrog environment in the cloud, which Frogbot can scan pull requests with? Just run one of the following commands in your terminal, to set up an environment in less than a minute. The commands will do the following: -* Install JFrog CLI on your machine. +* Install [JFrog CLI](https://www.jfrog.com/confluence/display/CLI/JFrog+CLI) on your machine. * Create a FREE JFrog environment in the cloud for you. After the set up is complete, you'll receive an email with your JFrog environment connection details, which you can then store as secrets in git. **On MacOS and Linux using cUrl** From 5cf4f56fe9c9d14e8bec42cc2719788aa092af60 Mon Sep 17 00:00:00 2001 From: eyalbe4 Date: Fri, 1 Apr 2022 11:29:57 +0300 Subject: [PATCH 3/7] Improve link --- README.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 6d855c1ef..d8142a2e7 100644 --- a/README.md +++ b/README.md @@ -50,6 +50,7 @@ Need a FREE JFrog environment in the cloud, which Frogbot can scan pull requests * Install [JFrog CLI](https://www.jfrog.com/confluence/display/CLI/JFrog+CLI) on your machine. * Create a FREE JFrog environment in the cloud for you. After the set up is complete, you'll receive an email with your JFrog environment connection details, which you can then store as secrets in git. + **On MacOS and Linux using cUrl** ``` curl -fL https://getcli.jfrog.io?setup | sh @@ -62,7 +63,7 @@ powershell "Start-Process -Wait -Verb RunAs powershell '-NoProfile iwr https://r ### Install Frogbot using GitHub Actions 1. Make sure you have the connection details of your JFrog environment. 2. Save the JFrog connection details as secrets in GitHub with the following names - *JF_URL*, *JF_USER* and *JF_PASSWORD*. You can also use *JF_ACCESS_TOKEN* instead of *JF_USER* and *JF_PASSWORD*. -3. Use one of these [GitHub Actions templates](templates/github-actions/README.md#github-actions-templates) to create a file named `frogbot.yml`. +3. Use one of these [GitHub Actions templates](templates/github-actions/README.md#github-actions-templates#frogbot-gitHub-actions-templates) to create a file named `frogbot.yml`. 4. Push the `frogbot.yml` file to the `.github/workflow` directory at the root of your GitHub repository. ### Install Frogbot using GitLab CI From b3cb98ec7c4f14a6601108db28377e8347a4ba56 Mon Sep 17 00:00:00 2001 From: eyalbe4 Date: Fri, 1 Apr 2022 11:31:59 +0300 Subject: [PATCH 4/7] Fix link --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index d8142a2e7..dae1da390 100644 --- a/README.md +++ b/README.md @@ -63,7 +63,7 @@ powershell "Start-Process -Wait -Verb RunAs powershell '-NoProfile iwr https://r ### Install Frogbot using GitHub Actions 1. Make sure you have the connection details of your JFrog environment. 2. Save the JFrog connection details as secrets in GitHub with the following names - *JF_URL*, *JF_USER* and *JF_PASSWORD*. You can also use *JF_ACCESS_TOKEN* instead of *JF_USER* and *JF_PASSWORD*. -3. Use one of these [GitHub Actions templates](templates/github-actions/README.md#github-actions-templates#frogbot-gitHub-actions-templates) to create a file named `frogbot.yml`. +3. Use one of these [GitHub Actions templates](templates/github-actions/README.md#frogbot-gitHub-actions-templates) to create a file named `frogbot.yml`. 4. Push the `frogbot.yml` file to the `.github/workflow` directory at the root of your GitHub repository. ### Install Frogbot using GitLab CI From 4680bef4619ebc1a1365444b9f655232514cf9ef Mon Sep 17 00:00:00 2001 From: eyalbe4 Date: Fri, 1 Apr 2022 11:38:59 +0300 Subject: [PATCH 5/7] Add supported tools --- README.md | 12 +++++++++++- 1 file changed, 11 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index dae1da390..25969c5ca 100644 --- a/README.md +++ b/README.md @@ -4,7 +4,17 @@ [![Coverage Status](https://coveralls.io/repos/github/jfrog/frogbot/badge.svg?branch=dev)](https://coveralls.io/github/jfrog/frogbot?branch=dev) ## 🤖 What is Frogbot? -Frogbot is a git bot that scans your pull requests with [JFrog Xray](https://jfrog.com/xray/) for security vulnerabilities. Frogbot adds the scan results as a comment on the pull request. If no vulnerabilities are found, Frogbot will also add a comment, confirming this. Currently GitHub and GitLab are supported. Bitbucket will be supported soon. +Frogbot is a git bot that scans your pull requests with [JFrog Xray](https://jfrog.com/xray/) for security vulnerabilities. Frogbot adds the scan results as a comment on the pull request. If no vulnerabilities are found, Frogbot will also add a comment, confirming this. +Currently GitHub and GitLab are supported. Bitbucket will be supported soon. +Projects that use one of the following tools to download their dependencies are currently supported. +* Npm +* Maven +* Gradle +* Go +* Pip +* Pipenv +* Nuget +* Dotnet ## 🕵 How does it work? ### General From 1d2de5c55d48083c6f0a8f2e4c72ccd5cd322e1b Mon Sep 17 00:00:00 2001 From: eyalbe4 Date: Mon, 18 Apr 2022 13:05:05 +0300 Subject: [PATCH 6/7] Docs corrections --- README.md | 72 ++++++++++++++++++++++++++++--------------------------- 1 file changed, 37 insertions(+), 35 deletions(-) diff --git a/README.md b/README.md index 0ee8be0ae..ea3534a0d 100644 --- a/README.md +++ b/README.md @@ -13,8 +13,8 @@ ## 🤖 What is Frogbot? -Frogbot is a git bot that scans your pull requests with [JFrog Xray](https://jfrog.com/xray/) for security vulnerabilities. Frogbot adds the scan results as a comment on the pull request. If no new vulnerabilities are found, Frogbot will also add a comment, confirming this. -Currently GitHub and GitLab are supported. Bitbucket will be supported soon. +Frogbot is a Git bot that scans your pull requests for security vulnerabilities using [JFrog Xray](https://jfrog.com/xray/) . Frogbot adds the scan results as a comment on the pull request. If no new vulnerabilities are found, Frogbot will also add a comment, confirming this. +Please note that GitHub and GitLab are currently supported and Bitbucket will be supported soon. Projects that use one of the following tools to download their dependencies are currently supported. - Npm @@ -29,36 +29,36 @@ Projects that use one of the following tools to download their dependencies are ## 🕵️‍♀️ How does it work? ### General +For security reasons, Frogbot is not triggered automatically. +After you create a new pull request, the maintainer of the git repository can trigger Frogbot to scan the pull request from the pull request UI. The scan output will include only new vulnerabilities added by the pull request. Vulnerabilities that aren't new, and existed in the code prior to the pull request creation, will not be included in the report. -After a new pull request is created, a maintainer of the git repository can trigger Frogbot to scan the pull request from the pull request UI. For security reasons, Frogbot is not triggered automatically. The scan output will include only new vulnerabilities added by the pull request. Vulnerabilities that aren't new, and existed in the code prior to the pull request creation will not be added to the report. +### Running Frogbot on GitHub -### On GitHub +1. A developer opens a pull request. +2. If missing, Frogbot creates the `🐸 frogbot scan` label in the repository. +3. A maintainer of the repository assigns the `🐸 frogbot scan` label on the pull request. +4. Frogbot is triggered by the label, scans the pull request, adds a comment with the scan results, and removes the label from the pull request. +5. Frogbot can be triggered again following new commits, by adding the label to the pull request again. -1. A developer opens a pull request -2. If missing, Frogbot creates the `🐸 frogbot scan` label in the repository -3. A maintainer of the repository assigns the `🐸 frogbot scan` label on this pull request -4. Frogbot gets triggered by the label, scans the pull request, adds a comment with the scan results and removes the label from the pull request -5. Frogbot can be triggered again following new commits, by adding the label to the pull request again +### Running Frogbot on GitLab -### On GitLab - -1. A developer opens a merge request -2. A maintainer of the repository triggers the manual frogbot-scan job -3. Frogbot gets triggered by the job, scans the merge request and adds a comment with the scan results -4. Frogbot can be triggered again following new commits, by trigerring the frogbot-scan job again - [![GitLab CI Run Button](./images/gitlab-run-button.png)](#-Using-Frogbot-with-GitLab-CI) +1. A developer opens a merge request. +2. A maintainer of the repository triggers the manual **frogbot-scan** job. +3. Frogbot is triggered by the job, scans the merge request, and adds a comment with the scan results. +4. Frogbot can be triggered again following new commits, by triggering the **frogbot-scan** job again + [![GitLab CI Run Button](./images/gitlab-run-button.png)](#-Using-Frogbot-with-GitLab-CI). ## Pull Request Comments ### 👍 No issues -If no new vulnerabilities were found, Frogbot will automatically add the following comment to the pull request: +If no new vulnerabilities are found, Frogbot automatically adds the following comment to the pull request: [![](https://raw.githubusercontent.com/jfrog/frogbot/master/resources/noVulnerabilityBanner.png)](#-no-issues) ### 👎 Issues were found -If new vulnerabilities were found, Frogbot will add them in a comment on the pull request. For example: +If new vulnerabilities are found, Frogbot adds them as a comment on the pull request. For example: [![](https://raw.githubusercontent.com/jfrog/frogbot/master/resources/vulnerabilitiesBanner.png)](#-issues-were-found) @@ -72,17 +72,20 @@ If new vulnerabilities were found, Frogbot will add them in a comment on the pul ### General -1. Frogbot requires a JFrog environment to scan pull requests with. Don't have a JFrog environment? No problem - [Set Up a FREE JFrog Environment in the Cloud](#set-up-a-free-jfrog-environment-in-the-cloud). You'll later save its connection details (URL, username and password) as secrets in git. +1. Frogbot requires a JFrog environment to scan pull requests. Don't have a JFrog environment? No problem - [Set Up a FREE JFrog Environment in the Cloud](#set-up-a-free-jfrog-environment-in-the-cloud). You'll later save the connection details (URL, username, and password) as secrets in Git. 2. Setting up Frogbot on a GitHub repository? [Install Frogbot using GitHub Actions](#install-frogbot-using-github-actions) 3. Setting up Frogbot on a GitLab repository? [Install Frogbot using GitLab CI](#install-frogbot-using-gitlab-ci) -### Set Up a FREE JFrog Environment in the Cloud +### Set up a FREE JFrog Environment in the Cloud + +Need a FREE JFrog environment in the cloud, so Frogbot can scan your pull requests? -Need a FREE JFrog environment in the cloud, which Frogbot can scan pull requests with? Just run one of the following commands in your terminal, to set up an environment in less than a minute. The commands will do the following: +Just run one of the following commands in your terminal, to set up an environment in less than a minute. The commands will do the following: -- Install [JFrog CLI](https://www.jfrog.com/confluence/display/CLI/JFrog+CLI) on your machine. -- Create a FREE JFrog environment in the cloud for you. - After the set up is complete, you'll receive an email with your JFrog environment connection details, which you can then store as secrets in git. +1. Install [JFrog CLI](https://www.jfrog.com/confluence/display/CLI/JFrog+CLI) on your machine. +2. Create a FREE JFrog environment in the cloud for you. + +After the set up is complete, you'll receive an email with your JFrog environment connection details, which you can then store as secrets in Git. **On MacOS and Linux using cUrl** @@ -96,23 +99,23 @@ curl -fL https://getcli.jfrog.io?setup | sh powershell "Start-Process -Wait -Verb RunAs powershell '-NoProfile iwr https://releases.jfrog.io/artifactory/jfrog-cli/v2-jf/[RELEASE]/jfrog-cli-windows-amd64/jf.exe -OutFile $env:SYSTEMROOT\system32\jf.exe'" ; jf setup ``` -### Install Frogbot using GitHub Actions +### Install Frogbot Using GitHub Actions 1. Make sure you have the connection details of your JFrog environment. -2. Save the JFrog connection details as secrets in GitHub with the following names - _JF_URL_, _JF_USER_ and _JF_PASSWORD_. You can also use _JF_ACCESS_TOKEN_ instead of _JF_USER_ and _JF_PASSWORD_. +2. Save the JFrog connection details as secrets in GitHub with the following names - _JF_URL_, _JF_USER_ and _JF_PASSWORD_ (You can also use _JF_ACCESS_TOKEN_ instead of _JF_USER_ and _JF_PASSWORD_). 3. Use one of these [GitHub Actions templates](templates/github-actions/README.md#frogbot-gitHub-actions-templates) to create a file named `frogbot.yml`. -4. Push the `frogbot.yml` file to the `.github/workflows` directory at the root of your GitHub repository. +4. Push the `frogbot.yml` file to the `.github/workflows` directory in the root of your GitHub repository. -### Install Frogbot using GitLab CI +### Install Frogbot Using GitLab CI 1. Make sure you have the connection details of your JFrog environment. -2. Save the JFrog connection details as secrets in GitLab with the following names - _JF_URL_, _JF_USER_ and _JF_PASSWORD_. You can also use _JF_ACCESS_TOKEN_ instead of _JF_USER_ and _JF_PASSWORD_. -3. Add a job named `frogbot-scan` to your `.gitlab-ci.yml` file in your GitLab repository using the below structure. +2. Save the JFrog connection details as secrets in GitLab with the following names: _JF_URL_, _JF_USER_ and _JF_PASSWORD_ (You can also use _JF_ACCESS_TOKEN_ instead of _JF_USER_ and _JF_PASSWORD_). +3. Add a job named `frogbot-scan` to your `.gitlab-ci.yml` file to your GitLab repository using the below structure. -**Important** +**Important Guidelines** -- If the project uses npm, pip, pipenv, nuget or dotnet to download its depedencies, make sure to set the command that downloads your project depedencies as the value of the _JF_INSTALL_DEPS_CMD_ variable. For example, `npm i` or `nuget restore` -- Make sure that either _JF_USER_ and _JF_PASSWORD_ or _JF_ACCESS_TOKEN_ are set, but not both. +- For npm, pip, pipenv, nuget or dotnet: To download the depedencies, make sure to set the command in a way that it downloads your project dependencies as the value of the **_JF_INSTALL_DEPS_CMD** variable. For example, `npm i` or `nuget restore` +- Make sure that **_JF_USER** and **JF_PASSWORD** or **JF_ACCESS_TOKEN** are set, but not both. ```yml frogbot-scan: @@ -172,5 +175,4 @@ frogbot-scan: ``` ## 💻 Contributions - -We welcome pull requests from the community. To help us improve this project, please read our [contribution](./CONTRIBUTING.md#-guidelines) guide. +We welcome pull requests from the community. To help us improve this project, please read our [Contribution](./CONTRIBUTING.md#-guidelines) guide. From 5b35f9973c6d190895b5ec7c2ca292946048bdee Mon Sep 17 00:00:00 2001 From: eyalbe4 Date: Mon, 18 Apr 2022 16:57:32 +0300 Subject: [PATCH 7/7] CR comments --- README.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index ea3534a0d..b283e347b 100644 --- a/README.md +++ b/README.md @@ -110,12 +110,12 @@ powershell "Start-Process -Wait -Verb RunAs powershell '-NoProfile iwr https://r 1. Make sure you have the connection details of your JFrog environment. 2. Save the JFrog connection details as secrets in GitLab with the following names: _JF_URL_, _JF_USER_ and _JF_PASSWORD_ (You can also use _JF_ACCESS_TOKEN_ instead of _JF_USER_ and _JF_PASSWORD_). -3. Add a job named `frogbot-scan` to your `.gitlab-ci.yml` file to your GitLab repository using the below structure. +3. Add a job named `frogbot-scan` to your `.gitlab-ci.yml` file in your GitLab repository using the below structure. **Important Guidelines** -- For npm, pip, pipenv, nuget or dotnet: To download the depedencies, make sure to set the command in a way that it downloads your project dependencies as the value of the **_JF_INSTALL_DEPS_CMD** variable. For example, `npm i` or `nuget restore` -- Make sure that **_JF_USER** and **JF_PASSWORD** or **JF_ACCESS_TOKEN** are set, but not both. +- For npm, pip, pipenv, nuget or dotnet: Make sure to set the command in a way that it downloads your project dependencies as the value of the **JF_INSTALL_DEPS_CMD** variable. For example, `npm i` or `nuget restore` +- Make sure that either **_JF_USER** and **JF_PASSWORD** or **JF_ACCESS_TOKEN** are set, but not both. ```yml frogbot-scan: