Configuration

At GuardRails, we focus on security that doesn't get in your way. That means supporting a quick and easy installation, without any additional configuration.

Nonetheless, we understand that one size doesn't fit all. A great developer experience requires flexibility to configure GuardRails to your needs.

Configuration file

Location: .guardrails/config.yml

You can override the default configuration for your account/organization in the Settings tab of the dashboard. By default, the config is:

bundles: "auto"
report:
  pullRequest:
    findings: "onChangedLinesOnly"
    comment: true
notifications:
  slack:
    enabled: false
useGitClone: false

Bundles

Bundles are set of tools we use to detect security issues in repositories, typically grouped by programming language. Currently, we support the following bundles: javascript, ruby, solidity, go, php, python, java, c, elixir, terraform, rust, apex, dotnet and general.

By default, we run the general bundle, along with the bundle(s) matching the language(s) we detect in your repository. It may happen that we don't detect (all) the language(s) of your repository. In that case you can override the bundles attribute to serve your needs:

bundles:
  - javascript
  - solidity
  - general

You can even go further by overriding the tools that run within a bundle:

bundles:
  - javascript
  - solidity:
      - mythx
  - general

This will run the full JavaScript and General bundle, along with just the Mythx tool from the Solidity bundle (which by default runs both Mythx and Solhint).

You can also exclude engines from being run. The below configuration would allow you to run all detected engines, but not run the Java engines dependency-check and spotbugs (it would still run semgrep), and completely avoid any PHP engines (including future engines that may be added).

bundles: "auto"
excludeBundles:
  - java:
    - dependency-check
    - spotbugs
  - php

To know more about the tools of a bundle, please refer to the Tools section.

Reports

Pull Request

report.pullRequest.findings

Possible values:

• onAllFiles: Show all vulnerabilities that exist in all files of the repo.
• onChangedFilesOnly: Show all vulnerabilities that exist in all changed files of the PR/MR.
• onChangedLinesOnly: Show all vulnerabilities in the changed lines of the PR/MR (default).

This attribute enables you to control the behavior of GuardRails in your pull/merge requests. Per default, we only notify you of security issues detected in the lines that changed in your pull/merge requests (onChangedLinesOnly).

report.pullRequest.comment

Possible values:

• 0 (Disabled For All Repositories)
• 1 (Enabled For All Repositories) (default)
• 2 (Disabled For Public Repositories Only)

By default, we post a comment in your pull/merge requests if we find any security issues. If you prefer to review the reports via our dashboard and want to disable the comments, set this attribute to 0 (Disabled For All Repositories). If you need to show the comments in private repositories only but not in public repositories, set it to 2 (Disabled For Public Repositories Only).

report.pullRequest.showPublicReposChecks

Possible values:

• 0 (Disabled For All Repositories)
• 1 (Enabled For All Repositories) (default)
• 2 (Disabled For Public Repositories Only)

By default, we show GuardRails checks running in your pull/merge requests in all enabled repositories. If you prefer to show them only in private repositories or hide them completely for all repositories, set this attribute to 2 (Disabled For Public Repositories Only), or 0 (Disabled For All Repositories) respectively.

Monorepo Configuration

GuardRails supports Monorepos and can be granularly configured to represent virtually any monorepo structure. If you have requirements that are not supported by our current configuration, please send us an email to [email protected].

Let's assume the following monorepo structure:

├── app1/
│   ├── src/
│   └── index.js
├── java/
│   ├── java-app1/
│   ├── java-app2/
│   ├── java-app3/
│   ├── java-app4/
│   └── java-app5/
├── php
│   ├── php-app1/
│   ├── php-app2/
│   ├── php-app3/
│   ├── php-app4/
│   └── README.md
├── docs
│   └── README.md
└── README.md

The app1 folder contains a Node.js application, the java folder contains 5 apps in sub-folders, and the php folder contains 4 apps in sub-folders. There is a doc folder as well containing a README.md. An example configuration for that structure can be found below:

monorepo:    
  - /app1
  - /java/*:
      bundles:
         - java:
             - semgrep 
  - /php/*:
      bundles:
         - php
      report:                                                 
        pullRequest:
            findings: "onChangedFilesOnly"

This configuration treats the app1/ folder as a dedicated repo and will apply the default configuration. The java/ folder will be considered as root container and all sub-folders will be considered as standalone repositories. A specific configuration will be applied to all sub-folders, in this case only the java engine semgrep will be run against any changes. Do note that a change in for example the java/java-app1 repo, will only trigger a scan for that sub-folder, not any other folders. Similarly the php/ folder will be treat all sub-folders as standalone repositories and will apply a special config that runs all php engines as well as report vulnerabilities in all files that have changes, not just in the lines that changed.

All files and folders that are not specifically mentioned in the monrepo config directive will be considered as "one repo". This special root sub-repository is shown as having the same name of the parent monorepo, with the red information icon next to it.

For example, the /docs/ folder and the /README.md file would be scanned if there are changes in either. Especially, if you don't configure a folder containing sub-repositories (e.g. the /java folder), any other changes such as to a README file would result in all sub-folders being scanned.

Ignoring Config Files

GuardRails supports configuration via the .guardrails/config.yml for each repository. In addition, it is possible to configure most settings on an org-wide level, via the Settings tab on the dashboard. It is also possible to configure GuardRails on a per-repo level via the Repository Settings tab in the dashboard. The enforcement of config options is happening according to this hierarchy. Global settings will be applied, unless there are settings defined on the repository setting level in the dashboard. Repository settings will be applied, unless there are settings defined in the .guardrails/config.yml on the repository code.

The ignoring config files toggle can be set on both the org-wide as well as the repo specific level. Once it's active, the .guardrails/config.yml file will always be ignored and the config from the either global or repo level setting will be applied.

Notifications

Slack

In order to enable Slack notifications for GuardRails, you first have to set up incoming Webhooks for Slack. There are 5 steps to follow:

1. Create a Slack app (if you don't already have one).
2. Enable Incoming Webhooks from the settings page.
3. After the settings page refreshes, click Add New Webhook to Workspace.
4. Pick a channel that the app will post to, then click Authorize.
5. Copy the value of the Incoming Webhook URL

You can either configure Slack notifications in GuardRails on account level or on repostiory level. If you configure on account level the slack configuration will be the default values for all of the repositories under that account. If you configure on repository level the slack configuration will only be set for that specific repository and will override any configurations made on account level.

Configure Slack on account level

1. Navigate to the GuardRails dashboard.
2. Go to the account settings page.
3. Fill in the configuration that should be the default for all repositories under the account (you can override these values in each repository, see below for more info).

Configure Slack on repository level

For repository level configurations you can either configure it in the GuardRails dashboard or by creating a config file in you Git repository (.guardrails/config.yml). All values entered on the repository level will override any configuration made on the account level, and any configuration made in the Git repository will override all configurations made in the dashboard (even those made in the repository settings).

To configure Slack using the GuardRails dashboard follow these steps:

1. Navigate to the GuardRails dashboard.
2. Go to the repostiory that you want to configure Slack notifications for and click on settings.
3. Fill in your Slack configuration.

To configure Slack in the Git repository follow these steps:

1. Create the file .guardrails/config.yml in your Git repository (if it doesn't already exist).
2. Open the file and add your configuration (see below for example of a valid configuration).

notifications:
  slack:
    notify: whenScanHasFindingsOnly
    enabled: true
    webhookUrl: >-
      https://hooks.slack.com/services/XXXXXXXXX/YYYYYYYYY/xyxyxyxyxyxyxyxyxyxyxyxy

The Slack webhook url contains the secret that is needed to authenticate and send Slack notifications. This means that if your Git repository is public, malicious people might find your webhook url and send Slack notifications to you. We therefore do not recommend that you enter the Slack webhook url in your Git repository, instead you should configure the url in the GuardRails dashboard.

Configuration Values

notifications.slack.enabled

Possible values: true or false (default).

notifications.slack.notify

Possible values: onAllScans (default), whenScanHasFindingsOnly, or whenPRHasFindingsOnly.

notifications.slack.webhookURL

A valid URL corresponding to a Slack Incoming Webhook.

Scanning with .git directory

By default scans are done on contents of a git repository without including .git directory itself. You can override this behavior with useGitClone.

Possible values: true or false (default).

Ignoring code

Ignoring files and folders

Location: .guardrails/ignore

The ignore file can come handy if you notice GuardRails is alerting you on some code you deliberately know is vulnerable, or causes false positives. The ignore file follows the gitignore file pattern. Refer to the gitignore docs for more details. One example file is:

tests/**/*

Ignore lines

If you want to disable one line in particular, you need to add guardrails-disable-line on the concerned line, usually as a comment.

const highEntropyStringThatIsNotASecret = "e32kdjksw'(&dej+"; // guardrails-disable-line