jfrog · sverdlov93 · Aug 15, 2023 · Aug 3, 2023 · Aug 3, 2023 · Aug 3, 2023
diff --git a/commands/utils/params.go b/commands/utils/params.go
@@ -42,7 +42,7 @@ type FrogbotDetails struct {
 type RepoAggregator []Repository
 
 // NewRepoAggregator returns an initialized RepoAggregator with an empty repository
-func NewRepoAggregator() RepoAggregator {
+func newRepoAggregator() RepoAggregator {
 	return RepoAggregator{{Params: Params{Scan: Scan{Projects: []Project{{}}}}}}
 }
 
@@ -341,7 +341,7 @@ func BuildRepoAggregator(configFileContent []byte, gitParamsFromEnv *Git, server
 // If there is no config file, the function returns a RepoAggregator with an empty repository.
 func unmarshalFrogbotConfigYaml(yamlContent []byte) (result RepoAggregator, err error) {
 	if len(yamlContent) == 0 {
-		result = NewRepoAggregator()
+		result = newRepoAggregator()
 		return
 	}
 	err = yaml.Unmarshal(yamlContent, &result)

diff --git a/commands/utils/params_test.go b/commands/utils/params_test.go
@@ -32,7 +32,7 @@ func TestExtractParamsFromEnvError(t *testing.T) {
 }
 
 // Test extraction of env params in ScanPullRequest command
-// Pull request ID is not default, which mean we don't have branches related variables defined.
+// Pull request ID is not the default, which means we don't have branches related variables defined.
 func TestExtractParamsFromEnvPlatformScanPullRequest(t *testing.T) {
 	SetEnvAndAssert(t, map[string]string{
 		JFrogUrlEnv:         "http://127.0.0.1:8081",
@@ -48,7 +48,7 @@ func TestExtractParamsFromEnvPlatformScanPullRequest(t *testing.T) {
 }
 
 // Test extraction in ScanRepository command
-// Pull request ID is default 0, which mean we will have branches related variables.
+// Pull request ID's default is 0, which means we will have branches related variables.
 func TestExtractParamsFromEnvPlatformScanRepository(t *testing.T) {
 	SetEnvAndAssert(t, map[string]string{
 		JFrogUrlEnv:              "http://127.0.0.1:8081",

diff --git a/docs/install-github.md b/docs/install-github.md
@@ -1,27 +1,286 @@
 [Go back to the main documentation page](https://github.com/jfrog/frogbot)
 
-# Installing Frogbot on GitHub repositories
+# Setting Frogbot on GitHub repositories
 
-  <summary>Install Frogbot Using GitHub Actions</summary>
+## Github Prerequisites
 
-   - Make sure you have the connection details of your JFrog environment.
+   - Go to your **Frogbot Management Repository** settings page and save the JFrog connection details as repository secrets with the following names - **JF_URL**, **JF_ACCESS_TOKEN**
 
-   - Go to your **Frogbot Management 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_USER** + **JF_PASSWORD** instead of **JF_ACCESS_TOKEN**
 
-   > **_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**
-
-   ![](../images/github-repository-secrets.png)
+   <img src="../images/github-repository-secrets.png" width="600">
 
    - Check the Allow GitHub Actions to create and approve pull requests check box.
 
-   ![](../images/github-pr-permissions.png)
+   <img src="../images/github-pr-permissions.png" width="600">
 
-   - Create a new [GitHub environment](https://docs.github.com/en/actions/deployment/targeting-different-environments/using-environments-for-deployment#creating-an-environment)
+   - For open-source projects: Create a new [GitHub environment](https://docs.github.com/en/actions/deployment/targeting-different-environments/using-environments-for-deployment#creating-an-environment)
    called **frogbot** and add people or public teams as reviewers. The chosen reviewers can trigger Frogbot scans on pull requests.
 
-   ![](../images/github-environment.png)
+   <img src="../images/github-environment.png" width="600">
+
+## Frogbot GitHub Action Templates
+
+Use these templates to install [Frogbot](https://github.com/jfrog/frogbot/blob/master/README.md#frogbot) on your GitHub repository.
+Push the workflow files to the `.github/workflows` directory at the root of your GitHub repository.
+
+> **IMPORTANT**: The workflow files must be pushed to the target branch before Frogbot is triggered. This means that if, for example, a pull request includes the workflow files and the target branch doesn't, Frogbot will fail to run.
+
+### 🔎Scan pull requests
+
+Create a file named `frogbot-scan-pull-request.yml` with the content of the following template.
+This will allow Frogbot to scan pull requests for security issues when the pull requests are open, and before they are merged.
+
+<details>
+  <summary>Show Template</summary>
+
+```yaml
+name: "Frogbot Scan Pull Request"
+on:
+  pull_request_target:
+    types: [opened, synchronize]
+permissions:
+  pull-requests: write
+  contents: read
+jobs:
+  scan-pull-request:
+    runs-on: ubuntu-latest
+    # A pull request needs to be approved before Frogbot scans it. Any GitHub user who is associated with the
+    # "frogbot" GitHub environment can approve the pull request to be scanned.
+    environment: frogbot
+    steps:
+      - uses: jfrog/frogbot@v2
+        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 username with 'read' permissions for Xray. Must be provided with JF_PASSWORD
+          # JF_USER: ${{ secrets.JF_USER }}
+
+          # [Mandatory if JF_ACCESS_TOKEN is not provided]
+          # JFrog password. Must be provided with JF_USER
+          # JF_PASSWORD: ${{ secrets.JF_PASSWORD }}
+
+          # [Mandatory]
+          # The GitHub token is automatically generated for the job
+          JF_GIT_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+          # [Optional, default: https://api.github.com]
+          # API endpoint to GitHub
+          # JF_GIT_API_ENDPOINT: https://github.example.com
+
+          # [Optional]
+          # By default, the Frogbot workflows download the Frogbot executable as well as other tools
+          # needed from https://releases.jfrog.io
+          # If the machine that runs Frogbot has no access to the internet, follow these steps to allow the
+          # executable to be downloaded from an Artifactory instance, which the machine has access to:
+          #
+          # 1. Login to the Artifactory UI, with a user who has admin credentials.
+          # 2. Create a Remote Repository with the following properties set.
+          #    Under the 'Basic' tab:
+          #       Package Type: Generic
+          #       URL: https://releases.jfrog.io
+          #    Under the 'Advanced' tab:
+          #       Uncheck the 'Store Artifacts Locally' option
+          # 3. Set the value of the 'JF_RELEASES_REPO' variable with the Repository Key you created.
+          # JF_RELEASES_REPO: ""
+
+          ##########################################################################
+          ##   If your project uses a 'frogbot-config.yml' file, you can define   ##
+          ##   the following variables inside the file, instead of here.          ##
+          ##########################################################################
+
+          # [Mandatory if the two conditions below are met]
+          # 1. The project uses yarn 2, NuGet or .NET Core to download its dependencies
+          # 2. The `installCommand` variable isn't set in your frogbot-config.yml file.
+          #
+          # The command that installs the project dependencies (e.g "nuget restore")
+          # JF_INSTALL_DEPS_CMD: ""
+
+          # [Optional, default: "."]
+          # Relative path to the root of 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"
+
+          # [Optional]
+          # Frogbot will download the project dependencies if they're not cached locally. To download the
+          # dependencies from a virtual repository in Artifactory, set the name of the repository. There's no
+          # need to set this value, if it is set in the frogbot-config.yml file.
+          # JF_DEPS_REPO: ""
+
+          # [Optional, Default: "FALSE"]
+          # If TRUE, Frogbot creates a single pull request with all the fixes.
+          # If false, Frogbot creates a separate pull request for each fix.
+          # JF_GIT_AGGREGATE_FIXES: "FALSE"
+
+          # [Optional, Default: "FALSE"]
+          # Handle vulnerabilities with fix versions only
+          # JF_FIXABLE_ONLY: "TRUE"
+
+          # [Optional]
+          # Set the minimum severity for vulnerabilities that should be fixed and commented on in pull requests
+          # The following values are accepted: Low, Medium, High or Critical
+          # JF_MIN_SEVERITY: ""
+```
+
+</details>
+
+### 🛠️Scanning repository branches and fixing issues
+
+Create a file named `frogbot-scan-and-fix.yml` with the content of the following template.
+Make sure to follow the guidelines in the 'Using the Templates' section above.
+This will make Frogbot open pull requests with fixes for security vulnerabilities found in the GitHub repository.
+
+<details>
+  <summary>Show Template</summary>
+
+```yaml
+name: "Frogbot Scan Repository"
+on:
+  workflow_dispatch:
+  schedule:
+    # The repository will be scanned once a day at 00:00 GMT.
+    - cron: "0 0 * * *"
+permissions:
+  contents: write
+  pull-requests: write
+  security-events: write
+jobs:
+  scan-repository:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        # The repository scanning will be triggered periodically on the following branches.
+        branch: [ "dev" ]
+    steps:
+      - uses: actions/checkout@v3
+        with:
+          ref: ${{ matrix.branch }}
+
+      - uses: jfrog/frogbot@v2
+        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 username with 'read' permissions for Xray. Must be provided with JF_PASSWORD
+          # JF_USER: ${{ secrets.JF_USER }}
+
+          # [Mandatory if JF_ACCESS_TOKEN is not provided]
+          # JFrog password. Must be provided with JF_USER
+          # JF_PASSWORD: ${{ secrets.JF_PASSWORD }}
+
+          # [Mandatory]
+          # The GitHub token automatically generated for the job
+          JF_GIT_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+          # [Optional, default: https://api.github.com]
+          # API endpoint to GitHub
+          # JF_GIT_API_ENDPOINT: https://github.example.com
+
+          # [Optional]
+          # By default, the Frogbot workflows download the Frogbot executable as well as other tools
+          # needed from https://releases.jfrog.io
+          # If the machine that runs Frogbot has no access to the internet, follow these steps to allow the
+          # executable to be downloaded from an Artifactory instance, which the machine has access to:
+          #
+          # 1. Login to the Artifactory UI, with a user which has admin credentials.
+          # 2. Create a Remote Repository with the following properties set.
+          #    Under the 'Basic' tab:
+          #       Package Type: Generic
+          #       URL: https://releases.jfrog.io
+          #    Under the 'Advanced' tab:
+          #       Uncheck the 'Store Artifacts Locally' option
+          # 3. Set the value of the 'JF_RELEASES_REPO' variable with the Repository Key you created.
+          # JF_RELEASES_REPO: ""
+
+          ##########################################################################
+          ##   If your project uses a 'frogbot-config.yml' file, you can define   ##
+          ##   the following variables inside the file, instead of here.          ##
+          ##########################################################################
+
+          # [Optional, default: "."]
+          # Relative path to the root of 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: "TRUE"]
+          # Fails the Frogbot task if any security issue is found.
+          # JF_FAIL: "FALSE"
+
+          # [Optional]
+          # Frogbot will download the project dependencies, if they're not cached locally. To download the
+          # dependencies from a virtual repository in Artifactory, set the name of the repository. There's no
+          # need to set this value, if it is set in the frogbot-config.yml file.
+          # JF_DEPS_REPO: ""
+
+          # [Optional]
+          # Template for the branch name generated by Frogbot when creating pull requests with fixes.
+          # The template must include ${BRANCH_NAME_HASH}, to ensure that the generated branch name is unique.
+          # The template can optionally include the ${IMPACTED_PACKAGE} and ${FIX_VERSION} variables.
+          # JF_BRANCH_NAME_TEMPLATE: "frogbot-${IMPACTED_PACKAGE}-${BRANCH_NAME_HASH}"
+
+          # [Optional]
+          # Template for the commit message generated by Frogbot when creating pull requests with fixes
+          # The template can optionally include the ${IMPACTED_PACKAGE} and ${FIX_VERSION} variables.
+          # JF_COMMIT_MESSAGE_TEMPLATE: "Upgrade ${IMPACTED_PACKAGE} to ${FIX_VERSION}"
+
+          # [Optional]
+          # Template for the pull request title generated by Frogbot when creating pull requests with fixes.
+          # The template can optionally include the ${IMPACTED_PACKAGE} and ${FIX_VERSION} variables.
+          # JF_PULL_REQUEST_TITLE_TEMPLATE: "[🐸 Frogbot] Upgrade ${IMPACTED_PACKAGE} to ${FIX_VERSION}"
+
+          # [Optional, Default: "FALSE"]
+          # If TRUE, Frogbot creates a single pull request with all the fixes.
+          # If FALSE, Frogbot creates a separate pull request for each fix.
+          # JF_GIT_AGGREGATE_FIXES: "FALSE"
+
+          # [Optional, Default: "FALSE"]
+          # Handle vulnerabilities with fix versions only
+          # JF_FIXABLE_ONLY: "TRUE"
+
+          # [Optional]
+          # Set the minimum severity for vulnerabilities that should be fixed and commented on in pull requests
+          # The following values are accepted: Low, Medium, High or Critical
+          # JF_MIN_SEVERITY: ""
 
-   - Use our [GitHub Actions templates](templates/github-actions/README.md#frogbot-gitHub-actions-templates) to add Frogbot workflows to your project.
+          # [Optional, Default: eco-system+frogbot@jfrog.com]
+          # Set the email of the commit author
+          # JF_GIT_EMAIL_AUTHOR: ""
 
-   - Push the workflow files to the **.github/workflows** directory in the root of your **Frogbot Management Repository**.
+```
+</details>
diff --git a/docs/templates/github-actions/README.md b/docs/templates/github-actions/README.md
diff --git a/...scan-and-fix/frogbot-scan-and-fix-npm.yml → ...hub-actions/frogbot-scan-pull-request.yml b/...scan-and-fix/frogbot-scan-and-fix-npm.yml → ...hub-actions/frogbot-scan-pull-request.yml