Skip to content

Commit

Permalink
Fix README Pull Request Review Comments (jfrog#79)
Browse files Browse the repository at this point in the history 
* Update README

* Fix PR comments

Co-authored-by: eyalbe4 <eyalbenmoshe@jfrog.com>
  • Loading branch information
@talarian1 @eyalbe4
talarian1 and eyalbe4 authored May 25, 2022
1 parent 32e5d1f commit d58b018
Show file tree
Hide file tree
Showing 2 changed files with 146 additions and 115 deletions.
180 changes: 146 additions & 34 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -10,22 +10,23 @@
</div>

## Table of contents

- [What is Frogbot?](#what-is-frogbot)
- [How does it work?](#how-does-it-work)
- [General](#general)
- [GitHub](#github)
- [GitLab](#gitlab)
- [Pull Request Comments](#pull-request-comments)
- [Installing and Using Frogbot](#installing-and-using-frogbot)
- [Pull requests scanning](#pull-requests-scanning)
- [Pull requests opening](#pull-requests-opening)
- [Installing and using Frogbot](#installing-and-using-frogbot)
- [Contributions](#contributions)

<div id="what-is-frogbot"></div>

## 🤖 What is Frogbot?

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.
Frogbot is a Git bot that does the following:
1. Scans pull requests for security vulnerabilities.
2. Opens pull requests with fixes for security vulnerabilities.

## Pull requests scanning
### General
Frogbot uses [JFrog Xray](https://jfrog.com/xray/) to scan your pull requests. It 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.
For pull requests scanning, please note that **GitHub**, **GitLab** and **Bitbucket Server** are supported.
Projects that use one of the following tools to download their dependencies are currently supported.

- Npm
Expand All @@ -37,17 +38,11 @@ Projects that use one of the following tools to download their dependencies are
- Nuget
- Dotnet

<div id="how-does-it-work"></div>

## 🕵️‍♀️ How does it work?

### General

### 🕵️‍♀️ How does pull requests scanning work?
#### GitHub
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.

### GitHub

1. A developer opens a pull request.
2. The Frogbot workflow automatically gets triggered and a [GitHub environment](https://docs.github.com/en/actions/deployment/targeting-different-environments/using-environments-for-deployment#creating-an-environment) named _frogbot_ is pending for the maintainer's approval:

Expand All @@ -56,24 +51,30 @@ After you create a new pull request, the maintainer of the git repository can tr
3. A Maintainer reviews the pull request and approves the scan: [![](./images/github-deployment.gif)](#running-frogbot-on-github)
4. Frogbot can be triggered again following new commits, by repeating steps 2 and 3.

### GitLab
#### GitLab
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.

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)]

### Pull Request Comments
#### Bitbucket Server
After you create a new pull request, Frogbot will automatically scan it. 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.

#### 👍 No issues
1. A developer opens a pull request.
2. Frogbot is triggered and scans the pull request, and adds a comment with the scan results.
3. Frogbot can be triggered again following new commits, by adding a comment with the `rescan` text.

#### Pull request comments
##### 👍 No issues
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

##### 👎 Issues were found
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)
Expand All @@ -84,18 +85,24 @@ If new vulnerabilities are found, Frogbot adds them as a comment on the pull req
| ![](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 |

<div id="installing-and-using-frogbot"></div>
## Pull requests opening
Frogbot scans your Git repository and automatically opens pull requests for upgrading vulnerable dependencies to a version with a fix.
Frogbot uses [JFrog Xray](https://jfrog.com/xray/) for the scanning. The scanning is triggered following commits that are pushed to the repository. For pull requests opening, 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.

## 🖥️ Installing and Using Frogbot
- npm
- Maven
- Go

### General
<div id="installing-and-using-frogbot"></div>

## 🖥️ Installing and using Frogbot
### General
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
2. [Setting up Frogbot on GitHub repositories](#setting-up-frogbot-on-github-repositories)
3. [Setting up Frogbot on GitLab repositories](#setting-up-frogbot-on-gitlab-repositories)
4. [Setting up Frogbot on Bitbucket Server repositories](#setting-up-frogbot-on-bitbucket-server-repositories)

### Set up a FREE JFrog Environment in the cloud
Need a FREE JFrog environment in the cloud, so Frogbot can scan your pull requests?

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:
Expand All @@ -117,23 +124,27 @@ 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
### Setting up Frogbot on GitHUb repositories
Frogbot is installed on GitHub repositories using GitHub Actions.
Here's how you install it:

1. Make sure you have the connection details of your JFrog environment.
2. Create a new "frogbot" [GitHub environment](https://docs.github.com/en/actions/deployment/targeting-different-environments/using-environments-for-deployment#creating-an-environment)

1. Add people or public teams as reviewers. The chosen reviewers are authorized to trigger Frogbot scan on pull requests.
2. Save the JFrog connection details as secrets in the environment 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 the environment with the following names - **JF_URL**, **JF_USER**, and **JF_PASSWORD** (You can also use **JF_XRAY_URL** and **JF_ARTIFACTORY_URL** instead of **JF_URL** and **JF_ACCESS_TOKEN** instead of **JF_USER** and **JF_PASSWORD**)

![](images/github-environment.png)

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 in the root of your GitHub repository.

### Install Frogbot Using GitLab CI
### Setting up Frogbot on GitLab repositories
Frogbot is installed on GitLab repositories using GitLab CI.
Here's how you install it:

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_).
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_XRAY_URL** and **JF_ARTIFACTORY_URL** instead of **JF_URL** and **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.

**Important Guidelines**
Expand Down Expand Up @@ -208,6 +219,107 @@ frogbot-scan:
# .\frogbot.exe ${FROGBOT_CMD}
```

### Setting up Frogbot on Bitbucket Server repositories
Frogbot is installed on Bitbucket Server repositories using Jenkins.
Here's how you install it:

1. Make sure you have the connection details of your JFrog environment.
2. Save the JFrog connection details as Credentials in Jenkins with the following Credential IDs: **JF_URL**, **JF_USER** and **JF_PASSWORD** (You can also use **JF_XRAY_URL** and **JF_ARTIFACTORY_URL** instead of **JF_URL** and **JF_ACCESS_TOKEN** instead of **JF_USER** and **JF_PASSWORD**).
3. Save your Bitbucket access token as a Credential in Jenkins with the BITBUCKET_TOKEN Credential ID.
4. Create a Pipeline job in Jenkins with the below Jenkinsfile content.
5. In the Jenkinsfile, set the values of all the mandatory variables.
6. In the Jenkinsfile, modify the code inside the `Download Frogbot` and `Scan Pull Requests` according to the Jenkins agent operating system.

**Important Guidelines**

- For npm, pip, pipenv, nuget or dotnet: Make sure to set inside the Jenkinsfile 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 in the Jenkinsfile, but not both.
- Make sure that all necessary build tool that are used to build the scanned project are installed on the Jenkins agent.

```groovy
// Run the job every 5 minutes
CRON_SETTINGS = '''*/5 * * * *'''
pipeline {
agent any
triggers {
cron(CRON_SETTINGS)
}
environment {
// [Mandatory only for projects which use npm, pip, pipenv, nuget and dotnet to download their dependencies]
// 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= credentials("JF_URL")
// [Mandatory if JF_ACCESS_TOKEN is not provided]
// JFrog user and password with 'read' permissions for Xray
JF_USER= credentials("JF_USER")
JF_PASSWORD= credentials("JF_PASSWORD")
// [Mandatory]
// Bitbucket accesses token with the following permissions
JF_GIT_TOKEN= credentials("BITBUCKET_TOKEN")
JF_GIT_PROVIDER= "bitbucket"
// [Mandatory]
// Bitbucket project namespace
JF_GIT_OWNER= ""
// [Mandatory]
// Bitbucket repository name
JF_GIT_REPO= ""
// [Mandatory]
// API endpoint to Bitbucket server
JF_GIT_API_ENDPOINT= ""
// Uncomment the below options if you'd like to use them.
// [Mandatory if JF_USER and JF_PASSWORD are not provided]
// JFrog access token with 'read' permissions for Xray
// JF_ACCESS_TOKEN= credentials("JF_ACCESS_TOKEN")
// [Optional, default: "."]
// Relative path to the project in the git repository
// JF_WORKING_DIR= path/to/project/dir
// [Optional]
// Xray Watches. Learn more about them here: https://www.jfrog.com/confluence/display/JFROG/Configuring+Xray+Watches
// JF_WATCHES= <watch-1>,<watch-2>...<watch-n>
// [Optional]
// JFrog project. Learn more about it here: https://www.jfrog.com/confluence/display/JFROG/Projects
// JF_PROJECT= <project-key>
}
stages {
stage ('Download Frogbot') {
steps {
// For Linux / MacOS runner:
sh """ curl -fLg "https://releases.jfrog.io/artifactory/frogbot/v2/[RELEASE]/getFrogbot.sh" | sh"""
// For Windows runner:
// powershell """iwr https://releases.jfrog.io/artifactory/frogbot/v2/[RELEASE]/frogbot-windows-amd64/frogbot.exe -OutFile .\frogbot.exe"""
}
}
stage ('Scan Pull Requests') {
steps {
sh "./frogbot scan-pull-requests"
// For Windows runner:
// powershell """.\frogbot.exe scan-pull-requests"""
}
}
}
}
```

<div id="contributions"></div>

## 💻 Contributions
Expand Down
81 changes: 0 additions & 81 deletions templates/Jenkins/Jenkinsfile
View file

This file was deleted.

0 comments on commit d58b018

Please sign in to comment.