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
semgrep0.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 audit6.14.8 which looks for CVEs in node module dependencies. - yarn audit – Execution of
yarn audit1.22.0 which looks for CVEs in node module dependencies. - PatternSearch – Execution of
sift0.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
