Skip to main content

Handling blocking findings and errors

This article documents how Semgrep handles blocking findings and errors and how you can change Semgrep's default behavior.

Blocking findings​

Blocking findings are those identified by Semgrep Code using rules defined in Semgrep AppSec Platform's Policies page and are set to Block mode. You can avoid blocking findings by removing rules or by switching the rule mode to Monitor, Comment, or Disabled.

If you do not use Semgrep AppSec Platform with Semgrep in CI or Semgrep Managed Scans (that is, you are using a stand-alone setup), all Semgrep findings are blocking findings. The existence of any findings means that Semgrep returns an exit code of 1, which you can use to block your PRs or MRs.

Semgrep's default behavior regarding blocking findings and errors​

When Semgrep identifies one or more blocking findings, it returns exit code 1. You can use this result to set up additional checks to enforce a block in your CI/CD pipeline, such as not allowing the merge of the PR/MR. This action applies to both full scans and diff-aware scans.

The process to enforce a block on a PR or MR after Semgrep exits with error code 1 is dependent on your CI provider. Review your CI provider's documentation for further information.

If Semgrep encounters an internal error, it sends an anonymous crash report to a crash-reporting server and returns exit code 0. If you want to catch internal errors, review the CLI reference for more information about Semgrep's exit codes and the options explained in this article to determine how you want to handle each exit code.

Configuration options for blocking findings and errors in CI​

You can configure, change, or revert to the default setup of blocking findings and errors in your CI pipeline by passing one of the following options in the semgrep.yml file used to configure and run Semgrep in your CI pipeline:

CI optionDescription
semgrep ci or semgrep ci --suppress-errorsDefault. CI fails on blocking findings, but passes on internal errors.
semgrep ci --no-suppress-errorsCI fails on blocking findings and internal errors.
semgrep ci || trueCI passes on blocking findings and internal errors.

To change Semgrep's behavior, modify your pipeline or job file, specifically the semgrep ci command, to the CI option that best fits your needs. For example, GitHub users should edit the semgrep.yml workflow file and include the following under the run key:

run:
    semgrep ci --suppress-errors

GitLab users would include the following under the script key:

script:
    semgrep ci --suppress-errors

If you use any other CI provider, refer to its documentation for information on where to provide this information. See the Examples of blocking findings and errors configuration below.

Sample configurations for blocking findings and errors​

The following is a sample .semgrep.yml file you can use with GitHub Actions. Semgrep's default behavior regarding blocking findings and errors applies here:

  • Semgrep returns exit code 1 if there are blocking findings
  • Semgrep returns exit code 0 if there are no blocking findings, even if there are internal errors. Semgrep does, however, send an anonymous report to the crash-reporting server.

This means that, by default, Semgrep doesn't report statuses other than 0 or 1.

# Name of this GitHub Actions workflow.
name: Semgrep

on:
  # Scan changed files in PRs (diff-aware scanning):
  pull_request: {}
  # Scan on-demand through GitHub Actions interface:
  workflow_dispatch: {}
  # Scan mainline branches if there are changes to .github/workflows/semgrep.yml:
  push:
    branches:
      - main
      - master
    paths:
      - .github/workflows/semgrep.yml
  # Schedule the CI job (this method uses cron syntax):
  schedule:
    - cron: '20 17 * * *' # Sets Semgrep to scan every day at 17:20 UTC.
    # It is recommended to change the schedule to a random time.

jobs:
  semgrep:
    # User definable name of this GitHub Actions job.
    name: semgrep/ci
    # If you are self-hosting, change the following `runs-on` value:
    runs-on: ubuntu-latest

    container:
      # A Docker image with Semgrep installed. Do not change this.
      image: semgrep/semgrep

    # Skip any PR created by dependabot to avoid permission issues:
    if: (github.actor != 'dependabot[bot]')

    steps:
      # Fetch project source with GitHub Actions Checkout. Use either v3 or v4.
      - uses: actions/checkout@v4
      # Run the "semgrep ci" command on the command line of the docker image.
      - run: semgrep ci
        env:
          # Connect to Semgrep AppSec Platform through your SEMGREP_APP_TOKEN.
          # Generate a token from Semgrep AppSec Platform > Settings
          # and add it to your GitHub secrets.
          SEMGREP_APP_TOKEN: ${{ secrets.SEMGREP_APP_TOKEN }}

Optionally, you can explicitly indicate that Semgrep is using the default settings by including the --suppress-errors flag. The modified portion of the configuration file is as follows:

steps:
  - uses: actions/checkout@v4
  - name: Scan and suppress internal errors
    run: semgrep ci --suppress-errors

The following code snippets display the position of the default flag in the configuration files of various CI providers:

steps:
- uses: actions/checkout@v4
- name: Scan and suppress internal errors
   run: semgrep ci --suppress-errors

See Configuration options for blocking findings and errors for information about the modifications to semgrep ci you can make to change Semgrep's default behavior.

Not finding what you need in this doc? Ask questions in our Community Slack group, or see Support for other ways to get help.