diff --git a/README.md b/README.md index 207bc0b7..a49e6228 100644 --- a/README.md +++ b/README.md @@ -54,6 +54,25 @@ Sometimes it's necessary to whitelist certain CVEs that Salus detects. The [docs If you would like to build customer scanners or support more languages that are not currenclty supported, you can use [this method of building custom Salus images](docs/custom_salus.md). + +## 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@2.4.2 + +workflows: + main: + jobs: + - salus/scan +``` + ## Using Salus in your Repo For your given CI, update the config file to run salus. In circle, it will look like this: @@ -64,6 +83,7 @@ docker run --rm -t -v $(pwd):/home/repo coinbase/salus coinbase/salus pulls the docker image + ## [Detailed Documentation](docs) ## 👷‍♂️ Development diff --git a/integrations/circleci/README.md b/integrations/circleci/README.md new file mode 100644 index 00000000..d501e14a --- /dev/null +++ b/integrations/circleci/README.md @@ -0,0 +1,82 @@ +# CircleCI Orb for Salus + +## Parameters + +| attribute | description | default | options | +| --------- | ----------- | ------- | ------- | +| salus_executor | CircleCI executor to use that specifies Salus environment | `coinbase/salus:2.4.2` | See [executor reference](https://circleci.com/docs/2.0/configuration-reference/#executors-requires-version-21)| +| 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. + +## Examples + +.circleci/config.yml + +### blocking scan with all scanners + +``` +version: 2.1 + +orbs: + salus: federacy/salus@2.4.2 + +workflows: + main: + jobs: + - salus/scan +``` + +### non-blocking scan with all scanners + +``` +version: 2.1 + +orbs: + salus: federacy/salus@2.4.2 + +workflows: + main: + jobs: + - salus/scan: + enforced_scanners: "none" +``` + +### blocking scan with only Brakeman + +``` +version: 2.1 + +orbs: + salus: federacy/salus@2.4.2 + +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@2.4.2 +executors: + salus_latest: + docker: + - image: coinbase/salus:latest +workflows: + salus_scan: + jobs: + - salus/scan: + salus_executor: + name: salus_latest +``` diff --git a/integrations/circleci/orb.yml b/integrations/circleci/orb.yml new file mode 100644 index 00000000..70f965ee --- /dev/null +++ b/integrations/circleci/orb.yml @@ -0,0 +1,127 @@ +# Use the latest 2.1 version of CircleCI pipeline processing engine, see https://circleci.com/docs/2.0/configuration-reference/ +version: 2.1 +description: "Salus security scanner coordinator (SAST)" + +executors: + salus: + docker: + - image: coinbase/salus:2.4.2 +jobs: + scan: + executor: << parameters.salus_executor >> + working_directory: /home/repo + parameters: + salus_executor: + description: Executor for Salus + type: executor + default: salus + active_scanners: + description: Scanners to run + type: string + default: "all" + enforced_scanners: + description: lists all scanners that should cause Salus to exit with a non-zero status if they find a security vulnerability. + type: string + default: "all" + report_uri: + description: Defines where to send Salus reports + type: string + default: "file://../salus-report.json" + report_format: + description: Defines the format of the report (json, yaml, txt) + type: string + default: "json" + report_verbosity: + description: Defines whether the report should be verbose + type: boolean + default: true + configuration_file: + description: Location of the Salus configuration file + type: string + default: "" + steps: + - checkout + - run: + name: Create configuration + command: | + echo " + config_version: 1 + + active_scanners: << parameters.active_scanners >> + + enforced_scanners: << parameters.enforced_scanners >> + + reports: + - uri: << parameters.report_uri >> + format: << parameters.report_format >> + verbose: << parameters.report_verbosity >>" | tee salus-configuration.yaml + working_directory: /home + - run: + name: Run scan + command: | + configuration_file="<>" + if [[ -n "${configuration_file}" ]]; then + if [[ ! -f "repo/${configuration_file}" ]]; then + echo "repo/${configuration_file} does not exist, aborting." + exit 1 + else + bundle exec /home/bin/salus scan --repo_path $CIRCLE_WORKING_DIRECTORY --config "file://${configuration_file}" + fi + else + bundle exec /home/bin/salus scan --repo_path $CIRCLE_WORKING_DIRECTORY --config "file://../salus-configuration.yaml" + fi + environment: + BUNDLE_GEMFILE: /home/Gemfile + working_directory: /home + - store_artifacts: + path: /home/salus-report.json + +examples: + blocking_scan: + description: A Salus scan that blocks on any potential vulnerabilities + usage: + version: 2.1 + orbs: + salus: federacy/salus@2.4.2 + workflows: + salus_scan: + jobs: + - salus/scan + non_blocking_scan: + description: A Salus scan that does not block on potential vulnerabilities + usage: + version: 2.1 + orbs: + salus: federacy/salus@2.4.2 + workflows: + salus_scan: + jobs: + - salus/scan: + enforced_scanners: "none" + specify_scanners: + description: A Salus scan using specific scanners + usage: + version: 2.1 + orbs: + salus: federacy/salus@2.4.2 + workflows: + salus_scan: + jobs: + - salus/scan: + active_scanners: "\n - Brakeman" + specify_executor_scan: + description: A Salus scan that blocks on any potential vulnerabilities + usage: + version: 2.1 + orbs: + salus: federacy/salus@2.4.2 + executors: + salus_latest: + docker: + - image: coinbase/salus:latest + workflows: + salus_scan: + jobs: + - salus/scan: + salus_executor: + name: salus_latest