# Getting started

Docker is required to run Salus. The dependencies for the project are stored on a docker, which helps reduce the number of steps necessary to run Salus.

Docker is available on different operating systems. You can install the appropriate version for your operating system on the Docker website

brew install docker

All Set! you are now ready to run Salus ✨

Navigate to the root directory of the project you want to run Salus on

cd /path/to/repo

Run the following line in the root directory (No edits necessary). This will run the latest Version of Salus.

docker run --rm -t -v $(pwd):/home/repo coinbase/Salus

Running specific versions of Salus is also possible. All you need to do is provide the version tag

docker run --rm -t -v $(pwd):/home/repo coinbase/Salus:2.17.6

To view all versions of Salus, visit the releases page

Salus can be configured by providing a salus configuration file

docker run --rm -t -v $(pwd):/home/repo coinbase/Salus --config main.yaml

reports:
  - uri: file://tests/salus-report.txt
    format: txt
  - uri: https://salus-config.internal.net/salus-report
    format: json
    verbose: true
enforced_scanners:
  - PatternSearch
  - Brakeman

active_scanners:
  - PatternSearch
  - Brakeman
  - BundleAudit
  - NPMAudit

Salus provides global configurations for its scanners as well as scanner specific configurations.

Configurations for scanners are added to the salus config file with the config option scanner_config

The configuration below is an example of you could configure this option.

reports:
  - uri: file://tests/salus-report.txt
    format: txt

scanner_config:
  Gosec:
    pass_on_raise: false
  BundleAudit:
    exceptions:
      - advisory_id: CVE-2020-2020
        changed_by: security-team
        notes: Currently no patch exists 
        expiration: "2021-04-27"

Salus can be used in different CI pipelines to run security checks. You would have to configure your CI pipelines to run Salus to achieve this. For example, update the config file to run salus. In circle, it will look like this:

docker run --rm -t -v $(pwd):/home/repo coinbase/salus

You can also provide configurations as well and utilize environment variables in your salus configuration files

reports:
  - uri: 
    format: sarif
  - uri: https://salus-config.internal2.net/salus-report
    format: json

We currenlty have documentation on how to achieve this in:

• Circle CI
• Github Actions
• Bugsnag

First, you will need to get your development environment setup to customize salus. After getting your dependencies installed, you are ready to configure salus ✨

Custom Scanners can be created for salus. There is a checklist available to help guide this process.

With your new scanner, you can create your own scanner-specific configurations.

It is possible to build custom configurations for your scanner or even build additional configurations for existing scanners.

A good start would be to look at the Base scanner file, which is the parent file for all Salus scanners. The build_options method is what takes in the configurations

The next step would be to look at the source code for the scanner you want to customize.

In order to run your customized version of salus, you will need to create a docker image.

docker build -t salus-custom .

After this, you can run your version of salus in any location of your choice.

cd /path/to/run/salus/
docker run --rm -t -v $(pwd):/home/repo salus-custom