ZeroNorth™ Integration-Container

ZeroNorth Experts
,
1

Use ZeroNorth’s Integration Docker Image to easily Orchestrate and Automate security testing for your CI/CD pipeline . Create a seamless integration between your DevOps process and leading security tools. Achieve continuous security built into your CI/CD pipeline.

image
image1482×684 182 KB

The above flow can apply equally to many popular CI/CD workflow tools, including:

  • Jenkins
  • Bamboo
  • GitLab
  • TeamCity
  • Azure DevOps / TFS
  • …and more

Features and Benefits:

  • ZeroNorth Integration Docker image is public and free to use.
  • Utilize your existing licenses/servers for scanning tools.
  • View scan results, history, etc. in ZeroNorth’s Fabric UI as usual.
  • Embed security into DevOps, paving the path to DevSecOps.

Prerequisites

The steps described in this article assume that you have:

  • ZeroNorth License and Credentials
  • Access to ZeroNorth and the Scanning tools
  • Docker daemon installed and configured
  • CI/CD pipeline that can work with Docker

Integration

Security scans/tests can be done at one or more, or all of the following 5 integration points:

  1. Source code scanning immediately after being checked out from source control.
  2. Build artifact scanning immediately after your build process.
  3. Scanning of built Docker images either in a private repository or on Docker Hub.
  4. Shallow application scan after deployment. This is used to get a quick assessment of the integrity of newly deployed code by using non-destructive application scans.
  5. Deep vulnerability scans on a clone of newly deployed app. This is used when a more comprehensive test is required, which may result in destroyed data or compromised applications.

Example flow with ZeroNorth Docker Image integrated into a CI/CD workflow:

image
image1136×531 51.3 KB

Setup

The publicly available ZeroNorth Integration Docker images is available on Docker Hub ( Docker Hub ). The README file has a complete list of environment variable that you can set to utilize the docker image.

Using the Docker Image

Below are a couple of examples of Docker commands to interact with the ZeroNorth Integration Container to invoke ZeroNorth scans.

1) Scanning Source Code

In this example, the project whose source you want to scan must be available to the Docker container:

docker run -v <path to checked out source code>:/code -v <folder location for temporary results>:/results -e CYBRIC_API_KEY=<your ZeroNorth API token> -e POLICY_ID=<Policy ID> zeronorth/integration:latest python cybric.py

where:

  • refers to the folder where the source to be scanned is accessible. Mounts to /code within the Docker container.
  • refers to the folder where ZeroNorth will write the results of the scan. Mounts to /results within the Docker container.
  • refers to the ID of the Policy created in advance via the ZeroNorth UI. The Policy must be set to expect an “artifact” type Target and a suitable Scenario such as SAST or SCA tools.

HINTS:

  • Depending on the security setup of your docker daemon, it may be necessary to run docker using sudo:
    sudo docker run ...
  • We always recommend the use of “CYBRIC_API_KEY=” instead of CYBRIC_USER and CYBRIC_PASSWORD. See the article Obtaining your ZeroNorth API Token for details.
  • Some operating systems (e.g. MacOS) may display an error message like:
    Mounts denied: The path /shared/customer_artifacts is not shared from the host and is not known to Docker...
    If you encounter this message, you can specify an alternate host path for the above mount by adding a Docker environment variable like this:
    -e CUSTOMER_ARTIFACTS_PATH=/home/user/zn/dummy (or something similar) where “dummy” is a folder, not a file.

2) A Build Artifact Scan using a ZeroNorth API Token

The following example submits a build artifact for a scan using a pre-defined Scan Policy:

docker run -v <path to the build artifact>:/code -v <folder location for temporary results>:/results -e CYBRIC_API_KEY=<your ZeroNorth API token> -e POLICY_ID=<Policy ID> zeronorth/integration:latest python cybric.py

where:

  • refers to the folder where the source to be scanned is accessible. Mounts to /code within the Docker container.
  • refers to the folder where ZeroNorth will write the results of the scan. Mounts to /results within the Docker container.
  • refers to the ID of the Policy created in advance via the ZeroNorth UI. The Policy must be set to expect an “artifact” type Target and a suitable Scenario such as SAST or SCA tools.

Other Ways to Use the Docker Image

The zeronorth/integration Docker image can also be used to create the necessary Target and the Scan Policy on-demand. This technique is useful when your CI/CD environment is very dynamic, where new projects are created often. The following example illustrates the on-demand technique for using the Docker image:

docker run -v /my/build/artifact/folder:/code -v /tmp:/results -e CYBRIC_API_KEY=..... -e INTEGRATION_NAME="<IntName>" -e TARGET_NAME="<TgtName>" -e SCENARIO="<ScenarioName>" -e POLICY_NAME="<PolName>" -e GET_ISSUE_DETAILS=1 -e FAIL_ON_HIGH_SEVERITY=HIGH zeronorth/integration:latest python cybric.py

where,

  • refer to the existing, uniquely identifiable ZeroNorth Integration to associate the new Target with. In most cases, this Integration should be of the type “Artifact”.
  • is the name of the Target you want to create. If the name already exists, ZeroNorth will use the existing Target.
  • refer to the existing, uniquely identifiable ZeroNorth Scenario to use in creating the Scan Policy.
  • is the name of the Scan Policy you want to create. If the name already exists, ZeroNorth will use the existing Policy.

For a complete list of the available options, refer to the technical specification of the ZeroNorth Integration Docker image .

Performing “onprem” Scans

The same Docker image, zeronorth/integration, can be used to perform SAST/SCA scans of a build artifact onprem. This approach is useful when:

  • The scanner server/service is accessible only from within your own network.
  • The application code/build cannot leave the premises for security and/or compliance reasons.

To perform an onprem “artifact” scan using the Integration Container (I-C), use the following modified form of the Integration Container docker run command:

[sudo] docker run -v /var/run/docker.sock:/var/run/docker.sock -e WORKSPACE=/path/to/the/build -v /tmp:/results -e CYBRIC_API_KEY=<API key> -e POLICY_ID=<Policy ID> [-e DEBUG=1] zeronorth/integration:latest python cybric.py

The items in [] brackets are optional:

  • sudo is needed if you are logged in as a user who does not belong to the “docker” (“Docker-Users” in Windows) user group.
  • -e DEBUG=1 will cause the I-C to wait for the runner to finish before exiting. Without this option, the I-C will return immediately after spawning the runner.

Prerequisites

  • The Target must be based on an Integration of Type “Artifact” and be set to “Customer’s Environment” (a.k.a. “onprem”).
  • Ensure that the appropriate runner image is already pulled (e.g. zeronorth/sonarqube-agent-job-runner:latest , etc.)
  • The bind mount for /var/run/docker.sock is required.
  • The WORKSPACE variable must be set to the full path of the build artifact to scan.
  • The bind mount for /code is not needed.

Viewing Results

  • Use ZeroNorth’s UI to view your scan results.
  • Output content is also available in /results/scan.out file of the zeronorth/integration Docker container.

More Information

For more information, refer to the technical specification of the ZeroNorth Integration Docker image . For information related to Docker for Windows, search this KB for “docker on windows”.

BASH Script for Convenience

The zn_integration.bash script is a convenience script for running the ZeroNorth Integration Container. It has the following beneficial features:

  • Performs basic environment/connectivity check.
  • Automatically constructs all of the necessary parameters.
  • Automatically detects if the requested scan is “onprem”, making the necessary adjustments to the parameters.

Use the following download link (TinyGoat-Build.zip is a sample vulnerable application for your testing convenience):

10 KB Download

4 MB Download