CI/CD

Integrating tools into CI/CD pipelines can be a difficult and time-consuming job. If you are focused on a singular goal of getting your app to build, test and deploy, it is typically not so hard.

However when you find yourself in a position of needing to integrate security tools, the idea of making even a one-line change to your config can be daunting.

We are addressing this by providing a Kubernetes-based CI system purposed-built for running Security tools. Zodiac enables security tools to be run entirely in parallel with no friction with the development team.

Zodiac

Zodiac is the component that enables the autiomation assessments. You read more about it in the Getting Started Guide.

Manual Integration

This section describes how to integrate Soluble with your CI/CD platform by making changes to the job configuration.

Before you go forward with this approach, please make sure that you have read through the Zodiac section first.

For most CI environments, the easiest way to install the soluble CLI is to add it to the build job itself.

The following command will download and install the CLI on demand.

curl -sL https://raw.githubusercontent.com/soluble-ai/soluble-cli/master/linux-install.sh | sh

The CLI will be installed in the current directory with the execute bit set. You are welcome to move it somewhere else, but leaving it in the current directory, which should be the checked-out source tree for most CI systems.

There are two important environment variables that you should have set: SOLUBLE_API_TOKEN and SOLUBLE_ORG_ID prior to installatin.

If they are set at the time the installation script is run, then the file $HOME/.soluble/cli-config.json will be written automatically. You can find these values in from your own ${HOME}/.soluble/cli-config.json that is created when you run soluble login.

Note: If you would rather store and distribute ${HOME}/.soluble/cli-config.json yourself, via Secrets Manager or S3 or another mechanism you are free to do so.

Failing Builds

You can add --fail SEVERITY=THRESHOLD_COUNT for each assessment that you run.

If you add --fail high=1 then the build fill fail if more than one High finding is detected. Note that a critical finding will also trigger this failure.

The order of finding severity is critical > high > medium > low > info.

Note that the --fail flag only works with --upload because the finding severity is provided by Soluble Fusion, not the assessment tool.

Failing At End

If you are running multiple assessments in a single build job, you might not want to fail at the first assessment. This will prevent subsequent assessments from even running, since the CI platform will terminate execution with a command with a non-zero exit code.

So if you would rather fail at the end, add the following:

soluble build report --fail high=1

at the end of the build job. This will allow all the previous assessments to be run and reported before triggering a failure.

GitHub PR Status

Soluble can update GitHUb PR Status Checks if you call soluble update-pr.

For this to work, you need to have installed the Soluble GitHub App which enables the CLI to receive github API credentials to post status checks.

To do this, while logged in to Soluble, run the following visit the following in your web browser. https://github.com/apps/soluble-fusion.

CI Providers

Circle CI

The following is an example for Circle CI with inline comments.

version: 2.1

workflows:
  workflow:
    jobs:
      - build:
            # my-env-context is a CircleCI Build Context containing SOLUBLE_API_TOKEN and SOLUBLE_ORG_ID
            # Circle CI contexts are documented here: https://circleci.com/docs/2.0/contexts/
            context: my-env-context

jobs:
  build:
    machine:
      # Need to use machine image builders if you intend to use checkov and other assessment tools via docker.
      # Circle CI builders, by default, do not have docker available to build steps.  If you don't have docker available
      # then you have to manually install assessment tools, which is cumbersome.  So using machine image builder 
      # is reccommended.  Circle CI documenation is here: https://circleci.com/docs/2.0/executor-intro/
      image: ubuntu-1604:202010-01
    steps:
      - checkout
      #
      #
      # Install the CLI, using the values of SOLUBLE_API_TOKEN and SOLUBLE_ORG_ID.  Those values are written to
      # ~/.soluble/cli-config.json
      - run: "curl -sL https://raw.githubusercontent.com/soluble-ai/soluble-cli/master/linux-install.sh | sh"
      #
      #
      # Run tfsec on the files in path/to/terraform/files and upload the results to Soluble Fusion.  Will continue 
      # on error, which is probably what you want with multiple assessments.  If you want to fail fast on error, add
      # --fail high=1, which would return a non-zero exit code if there are 1 or more HIGH or CRITICAL errors found.
      - run: "soluble tf-scan tfsec -d path/to/terraform/files --upload"
      #
      # Run checkov on path/to/terraform/files and uplaod the results to Soluble Fusion.
      - run: "soluble tf-scan checkov  -d path/to/terraform/files --upload"
      #
      # Run a secrets scan on the source tree
      - run: "soluble secrets-scan --upload"
      # Produce a consolidated assessment summary and fail if there are one or more findings in any of the above
      # assessments.
      - run: "soluble build report --fail high=1

An important point with Circle CI is that by default the builders do not have Docker available in build steps. The Soluble CLI prefers to use container image distributions of tools which have complicated depenencies such as checkov. So you should use the machine image option.

If you prefer not to do this and are happy to install and maintain checkov and other tools yourself, you can pass --tool-path as an argument to each soluble command.

For example, --tool-path checkov would use the checkov available on your PATH.

Kubernetes-based CI/CD

Kubernetes-based CI/CD platforms such as Tekton, Drone, etc. will typically not have Docker available. In this case you will need to have the tools pre-installed in the container image that you are using for the build execution and use the --tool-path option described above.