JFrog Frogbot Documentation

To begin using JFrog Frogbot, refer to the official documentation for setup and configuration instructions.

Note on Versions:

• V3 (main branch): The active development version.
• V2 (v2_main branch): In sunset mode/maintenance only. It is not accepting new features or general contributions, only critical bug and security fixes.

https://docs.jfrog.com/security/docs/frogbot-v3

Frogbot is a command-line interface tool. It is initialized via the main function which sets up the default logger and executes the application logic. The CLI is built using the urfave/cli/v2 framework and exposes various commands through GetCommands(). To run the application, it expects standard command-line arguments provided via os.Args.

# Example of running the compiled binary
./frogbot --help

The Frogbot GitHub Action entrypoint automatically determines the appropriate scan or fix action based on the GitHub event that triggered the workflow.

When the action runs, it performs the following lifecycle steps:

1. Retrieves the JFrog Platform URL.
2. Sets up OIDC tokens if required.
3. Configures the environment and updates the system PATH.
4. Executes logic based on the eventName:
   • pull_request or pull_request_target: Runs a scan on the pull request (execScanPullRequest).
   • push, schedule, or workflow_dispatch: Attempts to create fix pull requests (execCreateFixPullRequests).
   • Other events: The action fails with an unsupported event error.

If an unsupported event is received or an error occurs during execution, the action calls core.setFailed to mark the workflow step as failed.

Frogbot can be executed as a GitHub Action. When triggered, the action automatically determines the JFrog Platform URL, sets up OIDC tokens if required, and configures the environment. The action's behavior changes based on the GitHub event type:

• pull_request or pull_request_target: Executes a scan on the pull request.
• push, schedule, or workflow_dispatch: Executes the creation of fix pull requests.
• Other events: The action will fail with an error indicating the event is not supported.

This entrypoint is designed to be used within a GitHub Actions workflow file.

# Example usage in a GitHub Actions workflow
jobs:
  frogbot:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Run Frogbot
        uses: jfrog/frogbot-action@v3 # Replace with actual action name/version

You can display a badge in your repository's README to indicate that it is being scanned by Frogbot. Copy and paste the following Markdown snippet into your README.md file:

[![Scanned by Frogbot](https://raw.github.com/jfrog/frogbot/main/images/frogbot-badge.svg)](https://jfrog.com/help/r/jfrog-security-user-guide/shift-left-on-security/frogbot)

Frogbot maintains a comprehensive list of allowed licenses. If you are configuring license policies or troubleshooting why a specific dependency is being flagged, you can refer to this list of supported license identifiers.

0BSD
AAL
Abstyles
AdaCore-doc
Adobe-2006
...
ZPL-2.1

To implement a new command within the Frogbot framework, you must satisfy the FrogbotCommand interface. This interface is used by the Exec function to orchestrate the command lifecycle, including configuration loading and environment setup.

// The interface definition
type FrogbotCommand interface {
	// Run the command
	Run(config utils.Repository, client vcsclient.VcsClient) error
}

When implementing Run, you receive:

• config: A utils.Repository object containing repository and JFrog project details.
• client: A vcsclient.VcsClient used to interact with the Version Control System (e.g., Git).

Frogbot provides two primary commands for security scanning and remediation via the CLI:

1. Scan Pull Request (scan-pull-request or spr): Scans a specific pull request with JFrog Xray to identify security vulnerabilities.
2. Scan Repository (scan-repository, cfpr, or create-fix-pull-requests): Scans the current branch and automatically creates pull requests with suggested fixes if vulnerabilities are found.

These commands are typically invoked through the Frogbot CLI entrypoint.