Salus : Security Scanner Coordinator

Salus (Security Automation as a Lightweight Universal Scanner), named after the Roman goddess of protection, is a tool for coordinating the execution of security scanners. You can run Salus on a repository via the Docker daemon and it will determine which scanners are relevant, run them and provide the output. Most scanners are other mature open source projects which we include directly in the container.

Salus is particularly useful for CI/CD pipelines because it becomes a centralized place to coordinate scanning across a large fleet of repositories. Typically, scanners are configured at the repository level for each project. This means that when making org wide changes to how the scanners are run, each repository must be updated. Instead, you can update Salus and all builds will instantly inherit the change.

Salus supports powerful configuration that allows for global defaults and local tweaks. Finally, Salus can report metrics on each repository, such as what packages are included or what concerns exist. These reports can be centrally evaluated in your infrastructure to allow for scalable security tracking.

Using Salus

#Navigate to the root directory of the project you want to run Salus on
cd /path/to/repo
#Run the following line while in the root directory (No edits necessary)
docker run –rm -t -v $(pwd):/home/repo coinbase/salus

Supported Scanners

• Bandit – Execution of Bandit 1.6.2, looks for common security issues in Python code.
• Brakeman – Execution of Brakeman 4.10.0, looks for vulnerable code in Rails projects.
• semgrep – Execution of semgrep 0.36.0 which looks for semantic and syntactical patterns in code at the AST level.
• BundleAudit – Execution of bundle-audit 0.8.0, looks for CVEs in ruby gem dependencies.
• Gosec – Execution of gosec 2.7.0, looks for security problems in go code.
• npm audit – Execution of npm audit 6.14.8 which looks for CVEs in node module dependencies.
• yarn audit – Execution of yarn audit 1.22.0 which looks for CVEs in node module dependencies.
• PatternSearch – Execution of sift 0.9.0, looks for certain strings in a project that might be dangerous or could require that certain strings be present.
• Cargo Audit – Execution of Cargo Audit 0.14.0 Audit Cargo.lock files for crates with security vulnerabilities reported to the RustSec Advisory Database

Dependency Tracking

Salus also parses dependency files and reports which libraries and versions are being used. This can be useful for tracking dependencies across your fleet.

Currently supported languages are:

• Ruby
• Node.js
• Python
• Go
• Rust

Configuration

Salus is designed to be highly configurable so that it can work in many different types of environments and with many different scanners. It supports environment variable interpolation and cascading configurations, and can read configuration and post reports over HTTP.

Sometimes it’s necessary to ignore certain CVEs, rules, tests, groups, directories, or otherwise modify the default configuration for a scanner. The docs/scanners directory explains how to do so for each scanner that Salus supports.

If you would like to build custom scanners or support more languages that are not currently supported, you can use this method of building custom Salus images.

CircleCI Integration

Salus can be integrated with CircleCI by using a public Orb. All Salus configuration options are supported, and defaults are the same as for Salus itself.

Example CircleCI config.yml:

version: 2.1
orbs:
salus: federacy/salus@3.0.0
workflows:
main:
jobs:
– salus/scan

Orb Documentation

CircleCI Orb For Salus

Parameters

attribute	description	default	options
salus_executor	CircleCI executor to use that specifies Salus environment	coinbase/salus:latest	See executor reference
active_scanners	Scanners to run	all	Brakeman, PatternSearch, BundleAudit, NPMAudit
enforced_scanners	Scanners that block builds	all	Brakeman, PatternSearch, BundleAudit, NPMAudit
report_uri	Where to send Salus reports	file://../salus-report.json	Any URI
report_format	What format to use for report	json	json, yaml, txt
report_verbosity	Whether to enable a verbose report	true	true, false
configuration_file	Location of config file in repo (overrides all other parameters except salus_executor)	“”	Any filename

Note: active_scanners and enforced_scanners must be yaml formatted for Salus configuration file.

CircleCI Environment Variables

Stored in custom_info of a Salus scan.

Key	CircleCI Variable	Description
sha1	CIRCLE_SHA1	Hash of last commit in build
ci_project_username	CIRCLE_PROJECT_USERNAME	SCM username of project
reponame	CIRCLE_PROJECT_REPONAME	Name of repository
branch	CIRCLE_BRANCH	Name of git branch being built
tag	CIRCLE_TAG	Name of tag
repository_url	CIRCLE_REPOSITORY_URL	URL of the Github or Bitbucket repository
compare_url	CIRCLE_COMPARE_URL	URL to compare commits in build
build_url	CIRCLE_BUILD_URL	URL for the build
external_build_id	CIRCLE_BUILD_NUM	CircleCI or other build identifier
pull_requests	CIRCLE_PULL_REQUESTS	Comma-separated list of pull requests
ci_username	CIRCLE_USERNAME	SCM username of user who triggered build
pr_username	CIRCLE_PR_USERNAME	SCM username of user who created pull/merge request
pr_reponame	CIRCLE_PR_REPONAME	Name of repository where pull/merge request was created
pr_number	CIRCLE_PR_NUMBER	Number of the pull/merge request

Examples

.circleci/config.yml

blocking scan with all scanners

version: 2.1
orbs:
salus: federacy/salus@3.0.0
workflows:
main:
jobs:
– salus/scan

non-blocking scan with all scanners

version: 2.1
orbs:
salus: federacy/salus@3.0.0
workflows:
main:
jobs:
– salus/scan:
enforced_scanners: “none”

blocking scan with only Brakeman

version: 2.1
orbs:
salus: federacy/salus@3.0.0
workflows:
main:
jobs:
– salus/scan:
active_scanners: “\n – Brakeman”
enforced_scanners: “\n – Brakeman”

scan with custom Salus executor

version: 2.1
orbs:
salus: federacy/salus@3.0.0
executors:
salus_2_4_2:
docker:
– image: coinbase/salus:2.4.2
workflows:
salus_scan:
jobs:
– salus/scan:
salus_executor:
name: salus_2_4_2

Unused CircleCI Environment Variables

CI, CI_PULL_REQUEST, CI_PULL_REQUESTS, CIRCLE_INTERNAL_TASK_DATA, CIRCLE_JOB, CIRCLE_NODE_INDEX, CIRCLE_NODE_TOTAL, CIRCLE_PREVIOUS_BUILD_NUM, CIRCLE_PULL_REQUEST, CIRCLE_WORKFLOW_ID, CIRCLE_WORKING_DIRECTORY, CIRCLECI, HOME.

Github Actions Integration

Salus can also be used with Github Actions.

Example .github/workflows/main.yml:

on: [push]
jobs:
salus_scan_job:
runs-on: ubuntu-latest
name: Salus Security Scan Example
steps:
– uses: actions/checkout@v1
– name: Salus Scan
id: salus_scan
uses: federacy/scan-action@0.1.1

Github Action Documentation

Salus Security Scan Action

This action utilizes Salus from Coinbase to run SAST and dependency scans.

Bundle Audit, Brakeman, NPM Audit, and Yarn Audit reports can optionally be sent to Secure Development by Federacy for analysis.

Scanners Supported

Name	Language
Bundle Audit	Ruby
Brakeman	Ruby
npm audit	JavaScript
yarn audit	JavaScript
Gosec	Go
Bandit	Python
Cargo Audit	Rust
semgrep	Many
PatternSearch	n/a (uses Sift)

Example Usage

Defaults

on: [push]
jobs:
salus_scan_job:
runs-on: ubuntu-latest
name: Salus Security Scan Example
steps:
– uses: actions/checkout@v1
– name: Salus Scan
id: salus_scan
uses: federacy/scan-action@0.1.1

Single scanner

on: [push]
jobs:
salus_scan_job:
runs-on: ubuntu-latest
name: Salus Security Scan Example
steps:
– uses: actions/checkout@v1
– name: Salus Scan
id: salus_scan
uses: federacy/scan-action@0.1.1
with:
active_scanners: “\n – Brakeman”
enforced_scanners: “\n – Brakeman”

No enforced scanners

on: [push]
jobs:
salus_scan_job:
runs-on: ubuntu-latest
name: Salus Security Scan Example
steps:
– uses: actions/checkout@v1
– name: Salus Scan
id: salus_scan
uses: federacy/scan-action@0.1.1
with:
enforced_scanners: “none”

Custom configuration

on: [push]
jobs:
salus_scan_job:
runs-on: ubuntu-latest
name: Salus Security Scan Example
steps:
– uses: actions/checkout@v1
– name: Salus Scan
id: salus_scan
uses: federacy/scan-action@0.1.1
env:
SALUS_CONFIGURATION: “file://../salus-configuration.yaml file://config/pattern_search.yaml”

Inputs

attribute	description	default	options
active_scanners	Scanners to run	all	Brakeman, PatternSearch, BundleAudit, NPMAudit, GoSec
enforced_scanners	Scanners that block builds	all	Brakeman, PatternSearch, BundleAudit, NPMAudit, GoSec
report_uri	Where to send Salus reports	file://../salus-report.json	Any URI
report_format	What format to use for report	json	json, yaml, txt
report_verbosity	Whether to enable a verbose report	true	true, false
salus_configuration	Where to find Salus configuration	file://../salus-configuration.yaml	Any URI

Note: active_scanners and enforced_scanners must be yaml formatted for Salus configuration file.

Outputs

None.

Github Environment Variables

Stored in custom_info of a Salus scan.

Key	Github Variable	Description
sha1	GITHUB_SHA	Hash of last commit in build
reponame	GITHUB_REPOSITORY	Name of repository
ref	GITHUB_REF	Ref that triggered flow (branch or tag)
ci_username	GITHUB_ACTOR	Github username of user who triggered build
github_action	GITHUB_ACTION	Name of the action
github_workflow	GITHUB_WORKFLOW	Name of the workflow
github_event_name	GITHUB_EVENT_NAME	Name of the event that triggered workflow
github_event_path	GITHUB_EVENT_PATH	Path of event payload
github_workspace	GITHUB_WORKSPACE	Workspace directory path
github_head_ref	GITHUB_HEAD_REF	Ref of the head repository, if forked
github_base_ref	GITHUB_BASE_REF	Ref of the base repository, if forked
github_home	HOME	Path to home directory used by Github

Sending Reports To Dashboard

Steps:

• Create free account on Secure Development by Federacy
• Click ‘Applications’ in navbar
• Click ‘Create Application’
• Copy example job to your workflow in .github/workflows

Using Salus In Your Repo

For your given CI, update the config file to run salus. In circle, it will look like this:

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

coinbase/salus pulls the docker image