GitHub Actions

Integrate Frogbot with the JFrog GitHub App

This procedure guides you through integrating JFrog Frogbot with your GitHub repositories using the JFrog GitHub App. By completing this integration, Frogbot will be configured to continuously monitor your selected repositories—commenting on security issues directly in pull requests, and even creating fix pull requests for vulnerable dependencies.

Before You Begin

• Make sure the JFrog GitHub App is installed
• Supported for Xray version 3.128.3 and above

📘

This integration is supported only for repositories under a GitHub Organization. Personal repositories under individual user accounts are not supported

Integration

1. Navigate to Administration > Xray Settings > Indexed Resources, and open the Git Repositories tab.
2. Select Add Git Repositories and choose how to integrate Frogbot with your repositories:
   • Automatic Integration Use the JFrog GitHub App to automatically configure Frogbot with GitHub Actions.
   • Manual Integration Prefer to set things up yourself? Follow the Frogbot documentation for detailed instructions.
3. Under the Select GitHub Repositories tab, choose the repositories you want Frogbot to integrate with and scan. JFrog will handle the setup automatically, including:
   • Opening a pull request in each selected repository with the Frogbot workflow YAML file.
   • Adding the required secrets needed for Frogbot execution.
4. (Optional): Choose whether to Automatically merge the Frogbot YAML file into your repositories:
   • If enabled, the workflow file will be merged automatically once the pull request is created.
   • If disabled, you will need to manually review and approve each pull request before Frogbot becomes active in the repository.
5. To begin the integration process, select Integrate Frogbot.
6. The View Pull Requests tab opens. Here, you can:
   • See whether each pull request was successfully merged or failed.
   • Select any item in the table to open the corresponding commit page on GitHub.

What the Frogbot Workflow Does

The Frogbot YAML file is automatically added to each selected repository and sets up a workflow that protects the main branch by scanning every commit pushed to it and every pull request opened against it. The workflow also requests the necessary permissions to open fix pull requests and add comments to PRs with any security issues it detects.

Frogbot Workflow Template

name: "Frogbot Security Scan"

on:
  pull_request_target: 
    types: [opened, synchronize]
  push:
    branches:
      - main
  workflow_dispatch:

permissions:
  pull-requests: write
  contents: write
  security-events: write

jobs:
  frogbot-scan:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        branch: ["main"]
    steps:
      - uses: jfrog/frogbot@v2
        env:
          JF_URL: ${{ secrets.JF_URL }}
          JF_ACCESS_TOKEN: ${{ secrets.JF_ACCESS_TOKEN }}
          JF_GIT_TOKEN: ${{ secrets.JF_GIT_TOKEN }}
          JF_GIT_BASE_BRANCH: ${{ matrix.branch }}

Next Steps

1. Configure and manage your repositories' scan settings.
2. View scan results.

Installation

Step 1: Set Up Repository Secrets

1. Go to Settings > Secrets and variables > Actions.
2. Add the following secrets:

Step 2: Allow Frogbot to open Pull Requests

1. In GitHub, navigate to the Settings tab.
2. From the main menu, select Actions > General and check the Allow GitHub Actions to create and approve pull requests check box.

Step 3: Create an Execution Environment (Recommended for Open Source Projects Only)

1. In GitHub, navigate to the Settings tab.
2. From the main menu, select Environments and click on New environment. The Environments window opens.
3. Create a new GitHub environment named frogbot.
4. Add people or public teams as reviewers. The chosen reviewers can trigger Frogbot scans on pull requests.
5. If the environment is required for execution, specify it in the relevant job within the CI workflow.

Step 4: Create a GitHub Actions Workflow

1. Create a new YAML workflow file: .github/workflows/frogbot.yml
2. Add the following workflow configuration:

name: "Frogbot Security Scan"

on:
  pull_request_target: 
    types: [opened, synchronize] # Triggers scan-pr flow for every opened/updated pull request
  push: # Triggers scan-repo flow for every push to the specified branches
    branches:
      - main
  schedule:
    - cron: "0 0 * * *"   # The repository will be scanned once a day at 00:00 GMT.
  workflow_dispatch: # The repository will be scanned on demand

permissions:
  pull-requests: write
  contents: write
  security-events: write
  # [Mandatory If using OIDC authentication protocol instead of JF_ACCESS_TOKEN]
  # id-token: write

jobs:
  frogbot-scan:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        # The repository scanning will be triggered periodically on the following branches.
        branch: ["main"]
    steps:
      - uses: jfrog/frogbot@v2
        # [Mandatory if using OIDC authentication protocol instead of JF_ACCESS_TOKEN]
        # Insert to oidc-provider-name the 'Provider Name' defined in the OIDC integration configured in the JPD
        # with:
        #   oidc-provider-name: ""
        env:
          JF_URL: ${{ secrets.JF_URL }}
          JF_ACCESS_TOKEN: ${{ secrets.JF_ACCESS_TOKEN }}
          JF_GIT_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          JF_GIT_BASE_BRANCH: ${{ matrix.branch }}    # For repository scan action

3. Before setting up Frogbot, ensure all required tools and technologies are installed on your system and are available in your system's $PATH.

OpenID Connect Authentication

The sensitive connection details, such as the access token used by JFrog Frogbot, can be automatically generated by the action instead of storing it as a secret in GitHub. This is made possible by leveraging the OpenID-Connect (OIDC) protocol. This protocol can authenticate the workflow issuer and supply a valid access token. Learn more about this integration in this blog post. To utilize the OIDC protocol, follow these steps:

JFrog Platform configuration

Step 1: Configure an OIDC Integration

This phase is integration between GitHub Actions and the JFrog platform.

1. In the JFrog Platform, navigate to Administration > General Management > Manage Integrations.
2. From the New Integration drop-down, select OpenID Connect and enter the following information:
   1. Provider Name The 'Provider Name' value should be used as the oidc-provider-name input in Workflow Configuration step 2 below.
   2. Provider Type
   3. Description (optional)
   4. Provider URL
   5. Audience (optional) Does NOT represent the 'aud' claim that can be added to identity-mapping configured in the 'Claims JSON' (shown below). Only claims that are included in the 'Claims Json' created during step 2 will be validated.
   6. Token Issuer

Step 2: Configure an Identity Mapping

This phase is integration between a particular GitHub repository and the JFrog platform.

An identity mapping is a configuration object utilized by the JFrog Platform to associate incoming OIDC claims with particular selected fields. These fields include repository, actor, workflow, and others.

1. Select Identity Mappings > Add Identity Mapping and enter the following information:
   1. Name
   2. Priority (enter '1')
   3. Description (optional)
   4. Claims JSON You have the flexibility to define any valid list of claims required for request authentication. You can check a list of the possible claims here. Example:

      {
          "repository": "repository-owner/my-repository"
      }

Workflow configuration

Step 1: Set the Required Permissions During the protocol's execution, you must obtain a JSON Web Token (JWT) from GitHub's OIDC provider. To request this token, ensure that the workflow is configured with the required permission.

1. Configure the specified permission in the workflow file:

   permissions:
       id-token: write

Step 2: Pass the oidc-provider-name Input

The oidc-provider-name parameter specifies the OIDC configuration whose identity mapping should match the generated JWT claims.

1. Set the oidc-provider-name parameter to be the same as the Provider Name set in the OIDC configuration within the JFrog Platform.

Step 3: (Optional) Specify the oidc-audience Input

The oidc-audience input defines the intended recipients of the ID token (JWT), restricting access to authorized recipients within the JFrog Platform. By default, it is set to the GitHub repository owner's URL. This ensures that only workflows within the specified repository or organization can request an access token. Read more about it.

Usage Example

- uses: jfrog/frogbot@v2
  env:
      JF_URL: ${{ vars.JF_URL }}
      JF_GIT_TOKEN: ${{ secrets.GITHUB_TOKEN }}
  with:
  oidc-provider-name: frogbot-integration

Troubleshooting

Scan Failures Due to Token Expiration

When using OIDC integration, Xray or JFrog Advanced Security scans may fail if the token expires before the scans are complete. To prevent this, consider increasing the Token Expiration Time in the Identity Mapping Configuration to ensure the token remains valid for the entire scanning process. The required duration may vary based on the project's size.