zeronorth/integration-orchestrator repository overview

                                __
                               (__)
    ____________ _____   ____  _   _  ____  _____ _______ _    _
   |___  /  ____|  __ \ / __ \| \ | |/ __ \|  __ \__   __| |  | |
      / /| |__  | |__) | |  | |  \| | |  | | |__) | | |  | |__| |
     / / |  __| |  _  /| |  | | . \ | |  | |  _  /  | |  |  __  |
    / /__| |____| | \ \| |__| | |\  | |__| | | \ \  | |  | |  | |
   /_____|______|_|  \_\\____/|_| \_|\____/|_|  \_\ |_|  |_|  |_|

                    Integration Orchestrator

⁠Introduction

The integration-orchestrator is your starting point to running ZeroNorth's OnPremise solution. This client consists of the tools needed to boot our scanners in your envrionment. Follow the guide below to get started. You will need to have a few dependencies installed to get started.

⁠Dependencies

Your environment should consist of at least 1 Linux host(s) containing a docker engine installed and ready to run containers. Below is a short list of basic minimum versioned tools needed:

• Docker 17.12

Once you have a host running the above and you have authenticated to our DockerHUB integration account, you are ready to begin scanning. You can gain access to our account by speaking to your rep at ZeroNorth.

⁠Fabric setup

Now that you have all dependencies installed and are ready to move forward. You will need to go through the basic flow of setting up your Integration, Scenario, Target and Policy. Be sure that when creating your Integration object, you set Scan Execution to local - otherwise the policy will not run correctly.

If you would like to validate that you have setup everything correctly. You can go ahead and POST to policies/{policyId}/run this will return you a valid jobId, but the job will not actually run until you run the integration-orchestrator it will then pick up this job you started (which are all in a PENDING status) and run it in your local, onprem environment. If you GET /onprem/jobs, you should now see the jobId of the job listed as the first result. You are now ready to proceed.

⁠Application Setup

Once you have pulled down the codebase, the only thing left to do is run this application. Next you will need your token - Where do I get my token? Good question, it can be found under User Tokens section of your Profile in the Fabric portal.

⁠Setup

1. Inside of the env.local file, find the key of CYBRIC_JWT and replace the portion after the equals sign of {YOUR_JWT} with the token you got from the paragraph above via the Fabric portal. Also set DOCKER_HUB_USERNAME and DOCKER_HUB_PASSWORD in env.local to your DockerHub credentials. These credentials must be whitelisted to be able to pull ZeroNorth Docker images. Please contact ZeroNorth support [email protected]⁠ if you need your DockerHub account whitelisted.

⁠Docker

To run in this method, follow the commands below. If you have a different location of your Docker sock, be sure to change that in the -v option below. This process will launch another docker container, so it needs to know where your sock file is.

$> docker run -it -v /shared:/shared -v /var/run/docker.sock:/var/run/docker.sock --env-file ./env.local zeronorth/integration-orchestrator:latest '/app/run.sh'

⁠Warnings

If you would like to disable SSL verification, set CYBRIC_VERIFY_SSL=0 - it defaults to verifying SSL.

⁠Proxy support

If the customer is running the Integration Orchestrator behind a proxy. Set the appropriate property for the customer environment and remove (completely) any rows that are not required.

HTTP_PROXY=
HTTPS_PROXY=
FTP_PROXY=
NO_PROXY=

⁠Log Level and Format

LOGGER_SERIALIZER=
LOGGER_LEVEL=

The format is set by LOGGER_SERIALIZER, the accepted inputs are TEXT, SIMPLE, BUNYAN (default)

The level is set by LOGGER_LEVEL, the accepted inputs are DEBUG, INFO (default), WARNING, ERROR, CRITICAL

⁠Mounting a CUSTOMER_ARTIFACTS_PATH

The CUSTOMER_ARTIFACTS_PATH should reference a customer_artifacts_folder which contains artifacts that will be presented to the runner. The folder structure described bellow is important for the runner to see those artifact(s).

Adding a customer provided certificate (PEM format). The certificate needs to be named certificate.

customer_artifacts_folder/certificates/certificate

Adding a license which is required for a specific tool scan. License name specified during license creation on the ZeroNorth platform.

customer_artifacts_folder/license/<License Name>

Adding ZAP context files (auth script, context, url file, etc). The artifact name specified during artifact creation on the ZeroNorth platform.

customer_artifacts_folder/authScript/<Artifact Name>
customer_artifacts_folder/context/<Artifact Name>
customer_artifacts_folder/urlFile/<Artifact Name>

Adding a ZAP hosts file. The hosts file name is specified during creation of the host file on the ZeroNorth platform.

customer_artifacts_folder/hosts/<Hosts file name>