Frogbot

🤖 What is Frogbot?

Frogbot is a Git bot that scans your pull requests and repositories for security vulnerabilities. You can scan pull requests when they are opened, and Git repositories following new commits.

Scan pull requests when they are opened

General

Frogbot uses JFrog Xray (version 3.29.0 and above is required) 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.

Supported platforms:

Bitbucket Server
GitHub
GitLab

Supported package management tools:

Go
Gradle
Maven
.NET
npm
NuGet
Pip
Pipenv
Poetry
Yarn 2

🕵️‍♀️ How does Pull Request scanning work?

GitHub

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.

NOTE: The scan output will include only new vulnerabilities added by the pull request. Vulnerabilities that aren't new, and existed in the code before the pull request was created, will not be included in the report. In order to include all of the vulnerabilities in the report, including older ones that weren't added by this PR, use the JF_INCLUDE_ALL_VULNERABILITIES environment variable.

The Frogbot GitHub scan workflow is:

The developer opens a pull request.
The Frogbot workflow automatically gets triggered and a GitHub environment named frogbot becomes pending for the maintainer's approval.

The maintainer of the repository reviews the pull request and approves the scan:
Frogbot can be triggered again following new commits, by repeating steps 2 and 3.

GitLab

After you create a new merge request, the maintainer of the Git repository can trigger Frogbot to scan the merge request from the merge request UI.

NOTE: The scan output will include only new vulnerabilities added by the merge request. Vulnerabilities that aren't new, and existed in the code before the merge request was created, will not be included in the report. In order to include all of the vulnerabilities in the report, including older ones that weren't added by this merge request, use the JF_INCLUDE_ALL_VULNERABILITIES environment variable.

The Frogbot GitLab flow is as follows:

The developer opens a merge request.
The maintainer of the repository reviews the merge request and approves the scan by trigerring the manual frogbot-scan job.
Frogbot is then triggered by the job, it scans the merge request, and adds a comment with the scan results.
Frogbot can be triggered again following new commits, by triggering the frogbot-scan job again. GitLab CI Run Button

Bitbucket Server

After you create a new pull request, Frogbot will automatically scan it.

NOTE: The scan output will include only new vulnerabilities added by the pull request. Vulnerabilities that aren't new, and existed in the code before the pull request was created, will not be included in the report. In order to include all of the vulnerabilities in the report, including older ones that weren't added by this PR, use the JF_INCLUDE_ALL_VULNERABILITIES environment variable.

The Frogbot scan on Bitbucket Server workflow:

The developer opens a pull request.
Frogbot scans the pull request and adds a comment with the scan results.
Frogbot can be triggered again following new commits, by adding a comment with the rescan text.

Scan results

Frogbot adds the scan results to the pull request in the following format:

👍 No issues

If no new vulnerabilities are found, Frogbot automatically adds the following comment to the pull request:

👎 Issues were found

If new vulnerabilities are found, Frogbot adds them as a comment on the pull request. For example:

SEVERITY	IMPACTED PACKAGE	VERSION	FIXED VERSIONS	COMPONENT	COMPONENT VERSION	CVE
High	github.com/nats-io/nats-streaming-server	v0.21.0	[0.24.1]	github.com/nats-io/nats-streaming-server	v0.21.0	CVE-2022-24450
High	github.com/mholt/archiver/v3	v3.5.1		github.com/mholt/archiver/v3	v3.5.1
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

Scanning repositories following new commits

Frogbot scans your Git repository and automatically opens pull requests for upgrading vulnerable dependencies to a version with a fix.

NOTE: This feature is currently supported for GitHub and GitLab only.

For GitHub repositories, Frogbot also adds Security Alerts which you can view in the GitHub UI:

Frogbot uses JFrog Xray for the scanning. The scanning is triggered following commits that are pushed to the repository.

Supported package management tools:

Go
Maven
npm
Pip
Pipenv
Poetry
Yarn 2

🖥️ Installing and using Frogbot

Setting up a FREE JFrog Environment in the Cloud

Frogbot requires a JFrog environment to scan your projects. If you don't have an environment, we can set up a free environment in the cloud for you. 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.

For macOS and Linux, use curl

curl -fL https://getcli.jfrog.io?setup | sh

For Windows, use 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

After the setup is complete, you'll receive an email with your JFrog environment connection details, which can be stored as secrets in Git.

Setting up Frogbot on GitHub repositories

To install Frogbot on GitHub repositories using GitHub Actions:

Make sure you have the connection details of your JFrog environment.
Go to your GitHub repository settings page and save the JFrog connection details as repository secrets with the following names - JF_URL, JF_USER, and JF_PASSWORD

NOTE: 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

Check the Allow GitHub Actions to create and approve pull requests check box.
Create a new GitHub environment called frogbot and add people or public teams as reviewers. The chosen reviewers can trigger Frogbot scans on pull requests.
Use our GitHub Actions templates to add Frogbot workflows to your project.
Push the workflow files to the .github/workflows directory in the root of your GitHub repository.

Setting up Frogbot on GitLab repositories

To install Frogbot on GitLab repositories using GitLab CI:

Make sure you have the connection details of your JFrog environment.
Go to your GitLab repository settings page and save the JFrog connection details as repository secrets with the following names - JF_URL, JF_USER, and JF_PASSWORD

NOTE: 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

Add a job named frogbot-scan to your .gitlab-ci.yml file in your GitLab repository using the code block below.

Important

For npm, yarn 2, NuGet or .NET: 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.

frogbot-scan:
  rules:
    - if: $CI_PIPELINE_SOURCE == 'merge_request_event'
      when: manual
      variables:
        FROGBOT_CMD: "scan-pull-request"
        JF_GIT_BASE_BRANCH: $CI_MERGE_REQUEST_TARGET_BRANCH_NAME
      # Creating fix pull requests will be triggered by any push to the default branch.
      # You can change it to any other branch you want, for example:
      # if: $CI_COMMIT_BRANCH == "dev"
    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
      variables:
        FROGBOT_CMD: "create-fix-pull-requests"
        JF_GIT_BASE_BRANCH: $CI_COMMIT_BRANCH
  variables:
    # [Mandatory only for projects which use npm, yarn 2, NuGet and .NET 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 (This functionality requires version 3.29.0 or above of Xray)
    JF_URL: $JF_URL

    # [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

    # [Mandatory]
    # GitLab accesses token with the following permissions scopes: api, read_api, read_user, read_repository
    JF_GIT_TOKEN: $USER_TOKEN

    # 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
    JF_GIT_PULL_REQUEST_ID: $CI_MERGE_REQUEST_IID

    # Uncomment the below options if you'd like to use them.

    # [Optional, default: https://gitlab.com]
    # API endpoint to GitLab
    # JF_GIT_API_ENDPOINT: https://gitlab.example.com

    # [Mandatory if JF_USER and JF_PASSWORD are not provided]
    # JFrog access token with 'read' permissions for Xray
    # JF_ACCESS_TOKEN: $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>

    # [Optional, default: "FALSE"]
    # Displays all existing vulnerabilities, including the ones that were added by the pull request.
    # JF_INCLUDE_ALL_VULNERABILITIES: "TRUE"

    # [Optional, default: "TRUE"]
    # Fails the Frogbot task if any security issue is found.
    # JF_FAIL: "FALSE"
  script:
    # For Linux / MacOS runner:
    - curl -fLg "https://releases.jfrog.io/artifactory/frogbot/v2/[RELEASE]/getFrogbot.sh" | sh
    - ./frogbot ${FROGBOT_CMD}

    # For Windows runner:
    # iwr https://releases.jfrog.io/artifactory/frogbot/v2/[RELEASE]/frogbot-windows-amd64/frogbot.exe -OutFile .\frogbot.exe
    # .\frogbot.exe ${FROGBOT_CMD}

Setting up Frogbot on Bitbucket Server repositories

Frogbot is installed on Bitbucket Server repositories using JFrog Pipelines or Jenkins.

Using JFrog Pipelines

To install Frogbot using JFrog Pipelines:

Make sure you have the connection details of your JFrog environment.
Save the JFrog connection details as a JFrog Platform Access Token Integration named jfrogPlatform.
Save your Bitbucket access token as a Generic Integration named bitbucket with the token as the key and the Bitbucket access token as the value.
Create a Pipelines job with the below pipelines.yml content.
In the pipelines.yml, make sure to set values for all the mandatory variables.
In the pipelines.yml, if you're using a Windows agent, modify the code inside the onExecute sections as described on the yaml comments.

Important

For npm, yarn 2, NuGet or .NET: Make sure to set inside the pipelines.yml 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 all necessary build tool that are used to build the scanned project are installed on the Pipelines agent.

resources:
  - name: cron_trigger
    type: CronTrigger
    configuration:
      interval: '*/5 * * * *'     # Every 5 minutes


pipelines:
  - name: Frogbot
    steps:
      - name: Frogbot_Scan
        type: Bash # For Windows runner: PowerShell
        configuration:
          integrations:
            - name: jfrogPlatform
            - name: bitbucket
          inputResources:
            - name: cron_trigger
          environmentVariables:
            # [Mandatory only for projects which use npm, yarn 2, NuGet and .NET 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: $int_jfrogPlatform_url

            # [Mandatory if JF_USER and JF_PASSWORD are not provided]
            # JFrog access token with 'read' permissions for Xray
            JF_ACCESS_TOKEN: $int_jfrogPlatform_accessToken

            # [Mandatory]
            # Bitbucket accesses token with the following permissions 
            JF_GIT_TOKEN: $int_bitbucket_token
            JF_GIT_PROVIDER: "bitbucketServer"

            # [Mandatory]
            # API endpoint to Bitbucket server
            JF_GIT_API_ENDPOINT: $int_bitbucket_url

            # [Mandatory]
            # Bitbucket project namespace
            JF_GIT_OWNER: ""

            # [Mandatory]
            # Bitbucket repository name
            JF_GIT_REPO: ""

            # Uncomment the below options if you'd like to use them.

            # [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>

             # [Optional, default: "FALSE"]
             # Displays all existing vulnerabilities, including the ones that were added by the pull request.
             # JF_INCLUDE_ALL_VULNERABILITIES: "TRUE"

             # [Optional, default: "TRUE"]
             # Fails the Frogbot task if any security issue is found.
             # JF_FAIL: "FALSE"
        execution:
           onExecute:
              - curl -fLg "https://releases.jfrog.io/artifactory/frogbot/v2/[RELEASE]/getFrogbot.sh" | sh
              - ./frogbot scan-pull-requests
              # For Windows runner:
              # - iwr https://releases.jfrog.io/artifactory/frogbot/v2/[RELEASE]/frogbot-windows-amd64/frogbot.exe -OutFile .\frogbot.exe
              # - .\frogbot.exe scan-pull-requests

Using Jenkins

To install Frogbot using Jenkins:

Make sure you have the connection details of your JFrog environment.
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).
Save your Bitbucket access token as a Credential in Jenkins with the BITBUCKET_TOKEN Credential ID.
Create a Pipeline job in Jenkins with the below Jenkinsfile content.
In the Jenkinsfile, set the values of all the mandatory variables.
In the Jenkinsfile, modify the code inside the Download Frogbot and Scan Pull Requests according to the Jenkins agent operating system.

Important

For npm, yarn 2, NuGet or .NET: 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.

// Run the job every 5 minutes 
CRON_SETTINGS = '''*/5 * * * *'''

pipeline {
    agent any

    triggers {
        cron(CRON_SETTINGS)
    }

    environment {
        // [Mandatory only for projects which use npm, yarn 2, NuGet and .NET 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 (This functionality requires version 3.29.0 or above of Xray)
        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= "bitbucketServer"

        // [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>

        // [Optional, default: "FALSE"]
        // Displays all existing vulnerabilities, including the ones that were added by the pull request.
        // JF_INCLUDE_ALL_VULNERABILITIES= "TRUE"

        // [Optional, default: "TRUE"]
        // Fails the Frogbot task if any security issue is found.
        // JF_FAIL= "FALSE"
    }

   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"""
            }
        }
    }
}

💻 Contributions

We welcome pull requests from the community. To help us improve this project, please read our Contribution guide.

Name		Name	Last commit message	Last commit date
Latest commit History 219 Commits
.github		.github
action		action
buildscripts		buildscripts
commands		commands
images		images
release		release
resources		resources
starter-workflows		starter-workflows
templates/github-actions		templates/github-actions
.gitignore		.gitignore
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
README.md		README.md
action.yml		action.yml
go.mod		go.mod
go.sum		go.sum
main.go		main.go
main_test.go		main_test.go

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

Frogbot

Table of contents

🤖 What is Frogbot?

Scan pull requests when they are opened

General

🕵️‍♀️ How does Pull Request scanning work?

Scan results

👍 No issues

👎 Issues were found

Scanning repositories following new commits

🖥️ Installing and using Frogbot

Using JFrog Pipelines

Using Jenkins

💻 Contributions

About

Releases

Packages

Contributors 14

Languages

License

actions-marketplace-validations/jfrog_frogbot

Folders and files

Latest commit

History

Repository files navigation

Frogbot

Table of contents

🤖 What is Frogbot?

Scan pull requests when they are opened

General

🕵️‍♀️ How does Pull Request scanning work?

Scan results

👍 No issues

👎 Issues were found

Scanning repositories following new commits

🖥️ Installing and using Frogbot

Using JFrog Pipelines

Using Jenkins

💻 Contributions

About

Resources

License

Stars

Watchers

Forks

Releases

Packages 0

Contributors 14

Languages

Packages