Merge pull request #59 from jsulinski/circleci-orb

CircleCI orb and documentation

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/[email protected]
+
+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

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/[email protected]
+
+workflows:
+  main:
+    jobs:
+      - salus/scan
+```
+
+### non-blocking scan with all scanners
+
+```
+version: 2.1
+
+orbs:
+  salus: federacy/[email protected]
+
+workflows:
+  main:
+    jobs:
+      - salus/scan:
+          enforced_scanners: "none"
+```
+
+### blocking scan with only Brakeman
+
+```
+version: 2.1
+
+orbs:
+  salus: federacy/[email protected]
+
+workflows:
+  main:
+    jobs:
+      - salus/scan:
+          active_scanners: "\n    - Brakeman"
+          enforced_scanners: "\n    - Brakeman"
+```
+
+### scan with custom Salus executor
+
+```
+version: 2.1
+orbs:
+  salus: federacy/[email protected]
+executors:
+  salus_latest:
+    docker:
+      - image: coinbase/salus:latest
+workflows:
+  salus_scan:
+    jobs: 
+      - salus/scan:
+          salus_executor:
+            name: salus_latest
+```

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="<<parameters.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/[email protected]
+      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/[email protected]
+      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/[email protected]
+      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/[email protected]
+      executors:
+        salus_latest:
+          docker:
+            - image: coinbase/salus:latest
+      workflows:
+        salus_scan:
+          jobs: 
+            - salus/scan:
+                salus_executor:
+                  name: salus_latest