ZeroNorth™ Integration-Orchestrator (an on-prem option)

ZeroNorth Experts
, ,
1

The ZeroNorth Integration Orchestrator is a way to run the ZeroNorth Platform as a pseudo-on-prem solution. This client is a docker image and consists of the tools needed to run various scanners in your own environment, with the scan results being posted to the ZeroNorth cloud platform for viewing in ZeroNorth’s znHUB dashboards.

Prerequisites

  • ZeroNorth platform license and credentials
  • A Unix or Linux host with Docker 17.12 or later installed. Docker on MacOS and Windows also works (see the related article Docker on Windows - Integration Orchestrator ). The host will serve as your local ZeroNorth node and should have equivalent of 2 CPUs, 16 GB of RAM, and 100+ GB of storage.
  • Docker Hub credentials and privileges to access ZeroNorth’s zeronorth/integration-orchestrator image (contact support@zeronorth.io for access)

Overview

The key advantage to using the integration-orchestrator on-prem solution is that it does not require in-bound connectivity from the ZeroNorth platform to your environment. The on-prem image, running as a Docker container, reaches out to the ZeroNorth platform to obtain the Policy details and to post the results.

The following diagram illustrates the network layout of the Integration-Orchestrator in use:

image
image891×296 27.1 KB

The actual scans are executed in one of three ways:

  1. Local - Scanners are invoked locally by the on-prem image and can run within your environment (e.g. SonarQube, Nessus, NMAP, Nikto, OpenVas, etc.).
  2. Hosted Service - The on-prem image will submit the code to scanning services hosted either by ZeroNorth or within the customer’s environment. The results are then posted to the ZeroNorth cloud platform.
  3. SaaS Platform - Scanners such as tenable.io, WhiteSource and Veracode are available only as a SaaS offering. If you wish to use this type of scanner service, connectivity to the respective platform is required.

Setting up the Integration-Orchestrator

On the host where you installed docker, do the following:

  • [sudo] docker login , providing the docker credentials that were given access to the zeronorth/integration-orchestrator image.
  • [sudo] docker pull zeronorth/integration-orchestrator:latest
  • Optionally, if you plan to utilize the ZeroNorth Defect Density feature, also pull the image zeronorth/marmalade-runner:latest .
  • Ensure that the host has a /shared folder that is writable by the Docker process.
  • Create a env.local file in a secure location with the following contents:

CYBRIC_JWT=
DOCKER_HUB_USERNAME=
DOCKER_HUB_PASSWORD=
CYBRIC_VERIFY_SSL=1 (optional)

See this article for instructions on obtaining your ZeroNorth API Token. To bypass SSL verification, set CYBRIC_VERIFY_SSL=0 .

  • Run the docker image:

[sudo] docker run -v /shared:/shared -v /var/run/docker.sock:/var/run/docker.sock --env-file <full path the env.local file> zeronorth/integration-orchestrator:latest '/app/run.sh'

You will need to ensure that the Docker host has a /shared folder for the “-v /shared:/shared” bind-mount to work correctly. The need to use sudo to run your docker command will depend on your environment and your account privileges. Your integration-orchestrator on-prem node is now ready and will poll for work:

image
image1264×229 66.4 KB

Using the Integration-Orchestrator

Running a scan Policy with the integration-orchestrator is done with the following steps:

  1. Using the ZeroNorth UI , create a new Custom Integration. Be sure to set Initiate Scans From to “Customer’s Environment” when creating the Integration:
    image
    image746×358 14.5 KB
  2. In the ZeroNorth UI , Go to znOPS > Targets.
  3. Create a New Target under the Integration created in Step 1.
  4. In the ZeroNorth UI , Go to znOPS > Policies.
  5. Create a New Policy , associating the newly created Target with a relevant Scenario.
  6. Locate the Policy you just created, and then select the “Run Now” option from the Policy menu (the 3-dots menu to the far right):
    image
    image889×348 11.8 KB

    The Policy will start a Job which will remain in the “PENDING” state.
  7. Assuming that the docker integration-orchestrator image is running, it will pick up the pending Job for the Policy and will start the scan:
    image
    image1264×178 46.2 KB
  8. When the scan is completed, the ZeroNorth UI will show the results.

Useful bash Scripts

  • zn_orchestrator.bash - a convenience script for launching the Integration Orchestrator Docker container. It performs basic environment checks, pulls the Integration Orchestrator Docker image (assumes you’ve done docker login already), and then launches the Integration Orchestrator in the background.

  • zn_onprem_jobs_clean.bash - use this script to clean out the “onprem jobs queue”. Sometimes, you might end up with a job (or many jobs) that is stuck in the onprem jobs queue. When that happens, the next time the Integration Orchestrator is launched, it will either have trouble with the next job in the queue, or try to job all of the jobs in the queue. Either way, use this script to purge the onprem jobs queue. Purging the onprem jobs queue may have the following effects:

    • Pending onprem jobs will not get to run. This does NOT include onprem application scans that are handled by the “Integration Container.”
    • Pending Repo Discoveries (e.g. GitHub Enterpise onprem, Bitbucket Enterprise onprem, etc.)

  • zn_orchestrator.bash

10 KB Download

7 KB Download