Salus : Security Scanner Coordinator

0
102
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

attributedescriptiondefaultoptions
salus_executorCircleCI executor to use that specifies Salus environmentcoinbase/salus:latestSee executor reference
active_scannersScanners to runallBrakeman, PatternSearch, BundleAudit, NPMAudit
enforced_scannersScanners that block buildsallBrakeman, PatternSearch, BundleAudit, NPMAudit
report_uriWhere to send Salus reportsfile://../salus-report.jsonAny URI
report_formatWhat format to use for reportjsonjson, yaml, txt
report_verbosityWhether to enable a verbose reporttruetrue, false
configuration_fileLocation 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.

KeyCircleCI VariableDescription
sha1CIRCLE_SHA1Hash of last commit in build
ci_project_usernameCIRCLE_PROJECT_USERNAMESCM username of project
reponameCIRCLE_PROJECT_REPONAMEName of repository
branchCIRCLE_BRANCHName of git branch being built
tagCIRCLE_TAGName of tag
repository_urlCIRCLE_REPOSITORY_URLURL of the Github or Bitbucket repository
compare_urlCIRCLE_COMPARE_URLURL to compare commits in build
build_urlCIRCLE_BUILD_URLURL for the build
external_build_idCIRCLE_BUILD_NUMCircleCI or other build identifier
pull_requestsCIRCLE_PULL_REQUESTSComma-separated list of pull requests
ci_usernameCIRCLE_USERNAMESCM username of user who triggered build
pr_usernameCIRCLE_PR_USERNAMESCM username of user who created pull/merge request
pr_reponameCIRCLE_PR_REPONAMEName of repository where pull/merge request was created
pr_numberCIRCLE_PR_NUMBERNumber 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

NameLanguage
Bundle AuditRuby
BrakemanRuby
npm auditJavaScript
yarn auditJavaScript
GosecGo
BanditPython
Cargo AuditRust
semgrepMany
PatternSearchn/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

attributedescriptiondefaultoptions
active_scannersScanners to runallBrakeman, PatternSearch, BundleAudit, NPMAudit, GoSec
enforced_scannersScanners that block buildsallBrakeman, PatternSearch, BundleAudit, NPMAudit, GoSec
report_uriWhere to send Salus reportsfile://../salus-report.jsonAny URI
report_formatWhat format to use for reportjsonjson, yaml, txt
report_verbosityWhether to enable a verbose reporttruetrue, false
salus_configurationWhere to find Salus configurationfile://../salus-configuration.yamlAny 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.

KeyGithub VariableDescription
sha1GITHUB_SHAHash of last commit in build
reponameGITHUB_REPOSITORYName of repository
refGITHUB_REFRef that triggered flow (branch or tag)
ci_usernameGITHUB_ACTORGithub username of user who triggered build
github_actionGITHUB_ACTIONName of the action
github_workflowGITHUB_WORKFLOWName of the workflow
github_event_nameGITHUB_EVENT_NAMEName of the event that triggered workflow
github_event_pathGITHUB_EVENT_PATHPath of event payload
github_workspaceGITHUB_WORKSPACEWorkspace directory path
github_head_refGITHUB_HEAD_REFRef of the head repository, if forked
github_base_refGITHUB_BASE_REFRef of the base repository, if forked
github_homeHOMEPath 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