semgrep CI update

content/docs/static-analysis/semgrep/20-ci.md

@@ -35,6 +35,60 @@ The following are key points to note:
   by separating them with a space.
 - By default, the CI process fails if findings are detected but passes if internal errors occur. For more information, see
 [Passing or failing the CI job](https://semgrep.dev/docs/semgrep-ci/running-semgrep-ci-without-semgrep-app/#passing-or-failing-the-ci-job).
+- See the example job that uploads findings to [GitHub Advanced Security Dashboard](https://semgrep.dev/docs/semgrep-ci/sample-ci-configs#:~:text=Alternate%20job%20that%20uploads%20findings%20to%20GitHub%20Advanced%20Security%20Dashboard).
+
+#### Adding custom Semgrep rules to CI/CD
+
+When you want to use your own custom rules in addition to the standard rulesets (such as `p/default` or `p/javascript`)
+passed to the `SEMGREP_RULES`, follow the steps below:
+
+1. If your custom Semgrep rules directory **is in the same** repository as the scanned code,
+       just pass the directory path in the `SEMGREP_RULES` variable:
+      (e.g., `SEMGREP RULES: p/default custom-semgrep-rules-dir/`)
+
+2. If your custom Semgrep rules **are in another private repository**, do the following:
+
+    a. [Generate an access token for the repository with Semgrep rules](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens).
+    Remember to select the least scopes necessary.
+
+    b. [Add the generated access token](https://docs.github.com/en/actions/security-guides/using-secrets-in-github-actions)
+    to the repository where the workflow is run
+
+    c. Add the `actions/checkout` step in a job after the main source code checkout with:
+      - The `repository` name
+      - Personal access `token` (PAT) used to fetch the repository
+      - Relative `path` to place the repository
+
+    d. Pass the path to the directory with custom Semgrep rules in the `SEMGREP_RULES` environment variable
+
+    {{< hint info >}}
+If your repository with custom rules is publicly available, just omit the steps where you create the PAT and do not pass
+the `token` in the checkout step.
+    {{< /hint >}}
+
+    For example:
+
+    ```yaml
+    # Set up an environment variable with the name of the private repository with custom Semgrep rules
+    env:
+      SEMGREP_PRIVATE_RULES_REPO: semgrep-private-rules
+    steps:
+        # Main checkout of the repository source code
+      - name: Checkout main repository
+        uses: actions/checkout@v4
+        # Checkout of the repository with custom Semgrep rules
+      - name: Checkout private custom Semgrep rules
+        uses: actions/checkout@v4
+        with:
+          repository: ${{ github.repository_owner }}/${{ env.SEMGREP_PRIVATE_RULES_REPO }} # organization-name/Semgrep-rules-repo
+          token: ${{ secrets.SEMGREP_RULES_TOKEN }} # Configured PAT
+          path: ${{ env.SEMGREP_PRIVATE_RULES_REPO }} # Relative path to place the repository
+        # ...
+      - run: semgrep ci
+      env:
+        # Pass the directory with the checked-out Semgrep rules repository
+        SEMGREP_RULES: ${{ env.SEMGREP_PRIVATE_RULES_REPO }}
+    ```
 
 ### GitHub integration steps
 
@@ -78,14 +132,31 @@ jobs:
     container:
       # Use a Docker image with Semgrep pre-installed.
       image: returntocorp/semgrep
+    # Set up an env variable - the name of the (private) repository with custom Semgrep rules
+    # env:
+      # SEMGREP_PRIVATE_RULES_REPO: semgrep-private-rules
     steps:
       # Use the GitHub Actions Checkout step to fetch the project source code.
-      - uses: actions/checkout@v3
+      - name: Checkout main repository
+        uses: actions/checkout@v4
+      # In case you have a (private) repository with custom Semgrep rules:
+      # - name: Checkout custom Semgrep rules
+      #   uses: actions/checkout@v4
+      #   with:
+      #     repository: ${{ github.repository_owner }}/${{ env.SEMGREP_PRIVATE_RULES_REPO }}
+      #     token: ${{ secrets.SEMGREP_RULES_TOKEN }} # If the repository is private
+      #     path: ${{ env.SEMGREP_PRIVATE_RULES_REPO }}
        # Execute the "semgrep ci" command within the Semgrep Docker container.
       - run: semgrep ci
         env:
-          # Set the SEMGREP_RULES environment variable to define which rules Semgrep should use.
-          SEMGREP_RULES: p/default # Browse more rulesets - semgrep.dev/explore
+          # Set the SEMGREP_RULES environment variable to specify which rules Semgrep should use.
+          # Use common security-related rulesets for this job (starting with `p/`)
+          # or use a directory with your custom rules from the current repository (such as `semgrep-rules/`).
+          SEMGREP_RULES: >
+            p/default
+            semgrep-rules/
+        # Pass the directory with the checked-out Semgrep rules repository
+        #    ${{ env.SEMGREP_PRIVATE_RULES_REPO }}
   # Define the second job for scanning pull requests.
   semgrep-pr:
     # Define the conditions for running this job. Run only within Pull Requests, excluding Dependabot PRs.
@@ -99,13 +170,20 @@ jobs:
       image: returntocorp/semgrep
     steps:
       # Fetch project source with GitHub Actions Checkout.
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
       # Execute the "semgrep ci" command within the Semgrep Docker container.
       - run: semgrep ci
         env:
-          # Set the SEMGREP_RULES environment variable to define which rules Semgrep should use.
-          # Use common security-related rulesets for this job.
-          SEMGREP_RULES: p/cwe-top-25 p/owasp-top-ten p/r2c-security-audit p/javascript p/trailofbits # more at semgrep.dev/explore
+          # Set the SEMGREP_RULES environment variable to specify which rules Semgrep should use.
+          # Use common security-related rulesets for this job (starting with `p/`)
+          # or use a directory with your custom rules from the current repository (such as `semgrep-rules/`).
+          SEMGREP_RULES: > 
+            p/cwe-top-25
+            p/owasp-top-ten
+            p/r2c-security-audit
+            p/javascript
+            p/trailofbits
+            semgrep-rules/
 ```
 
 This configuration ensures that your codebase is scanned regularly for potential issues