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.
Here are all the possibilities:
bundles:
- apex:
- pmd
- c:
- flawfinder
- dotnet:
- security-scan
- devaudit
- elixir:
- sobelow
- general:
- detect-secrets
- detect-gr-secrets
- oss-index
- go:
- gosec
- nancy
- java:
- spotbugs
- dependency-check
- javascript:
- eslint
- npm-audit
- retirejs
- NodeJsScan
- kubernetes:
- kubesec
- mobile:
- mobsf
- php:
- phpcs-security-audit
- security-checker
- python:
- bandit
- safety
- ruby:
- brakeman
- bundler-audit
- rubocop
- rust:
- cargo-audit
- solidity:
- mythx
- solhint
- terraform:
- tfsec
- typescript:
- tslint-config-security
Reports
Pull Request
report.pullRequest.findings
Possible values: onAllFiles
, onChangedFilesOnly
, or onChangedLinesOnly
(default).
This attribute enables you to control the behavior of GuardRails in your pull requests. Per default, we only notify you of security issues detected in the lines that changed in your pull requests (onChangedLinesOnly
).
report.pullRequest.comment
Possible values: true
(default) or false
.
By default, we post a comment in your pull 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 false
.
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].
Note: This configuration can also be done via the repository settings page, without requiring to add the config file to the repository.
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". 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 6 steps to follow:
- Create a (Slack app)[https://api.slack.com/apps/new] (if you don't already have one).
- Enable
Incoming Webhooks
from the settings page. - After the settings page refreshes, click
Add New Webhook to Workspace
. - Pick a channel that the app will post to, then click
Authorize
. - Copy the value of the Incoming Webhook URL
- Configure GuardRails:
notifications:
slack:
notify: whenScanHasFindingsOnly
enabled: true
webhookUrl: >-
https://hooks.slack.com/services/XXXXXXXXX/YYYYYYYYY/xyxyxyxyxyxyxyxyxyxyxyxy
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