This is the multi-page printable view of this section. Click here to print.

Return to the regular view of this page.

Getting Started

The following sections describe the installation of the OpenClarity backend and the CLI, and show you the most common tasks that you can perform with OpenClarity.

1 - Deploy on AWS

An AWS CloudFormation template is provided for quick deployment of the OpenClarity environment.

Note: To avoid extra costs (cross-region snapshots), you may want to deploy the OpenClarity AWS CloudFormation template in the same region where the majority of the VMs are that you want to scan with OpenClarity.

The following figure shows the basic AWS resources that the OpenClarity CloudFormation template creates:

  • a VPC with a public and private subnet, and

  • an AWS Internet Gateway (IGW) and NAT Gateway (NGW) into the VPC.

The public subnet (OpenClarityServerSubnet) hosts the OpenClarity Server (OpenClarityServer) EC2 instance. The OpenClarity server houses the scanning configuration, the UI, and other control components. The EC2 instance is assigned an external IPv4 address (EIP) for SSH and web UI access.

The private subnet (OpenClarityScannerSubnet) hosts the VM snapshot instances (EC2) that are scanned for security vulnerabilities.

Prerequisites

Deployment steps

To deploy the OpenClarity AWS CloudFormation Stack, you can:

  • click this quick-create link to navigate directly to the AWS CloudFormation console and jump to the wizard instructions, or
  • complete the following steps.
  1. Download the latest OpenClarity release.

    wget https://github.com/openclarity/openclarity/releases/download/v0.7.2/aws-cloudformation-v0.7.2.tar.gz
    

    Alternatively, copy the AWS CloudFormation template file from the project repository to deploy the latest development code and skip the next step.

  2. Create a new directory and extract the files.

    mkdir aws-cloudformation-v0.7.2
    tar -xvzf aws-cloudformation-v0.7.2.tar.gz -C aws-cloudformation-v0.7.2
    
  3. Log in to the AWS CloudFormation console and go to the AWS CloudFormation Stacks section, then select Create Stack > With New Resources (standard).

  4. Check Template is ready and Upload a template file, then click Upload a template file/Choose file and upload the previously downloaded CFN template file.

  5. In the OpenClarity CloudFormation Stack wizard, set the following:

    1. Enter a name for the stack.
    2. Select the InstanceType (defaults to t2.large for the OpenClarity Server, and the scanner VMs).
    3. Specify the SSH key for the EC2 instance in the KeyName field. You will need this key to connect to OpenClarity.
    4. Adjust SSHLocation according to your policies.
    5. Do not change AdvancedConfiguration, unless you are building from a custom registry.
    6. Click NEXT.
    7. (Optional) Add tags as needed for your environment. You can use the defaults unless you need to adjust for your own policies.
    8. Click NEXT, then scroll to the bottom of the screen, and check I acknowledge….
    9. Click SUBMIT.
  6. Once the stack is deployed successfully, copy the OpenClarity SSH address from the Outputs tab.

  7. Open an SSH tunnel to OpenClarity the server

    ssh -N -L 8080:localhost:80 -i  "<Path to the SSH key specified during install>" ubuntu@<OpenClarity SSH Address copied during install>
    
  8. Access the OpenClarity UI.

    1. Open the OpenClarity UI in your browser at http://localhost:8080/. The dashboard opens.

    2. (Optional) If needed, you can access the API at http://localhost:8080/api. For details on the API, see the API reference.

    OpenClarity UI

Next steps

Complete the First Tasks on the UI.

2 - Deploy on Azure

Prerequisites

Deployment steps

  1. Click here to deploy OpenClarity’s custom template.

  2. Fill out the required Project details and Instance details in the Basics tab.

    You can set the following parameters:

    ParameterRequiredDescription
    SubscriptionTrueAzure subscription where resources will be billed.
    RegionFalseAzure region where resources will be deployed.
    OpenClarity Deploy PostfixTruePostfix for Azure resource group name (e.g. openclarity-<postfix>).
    OpenClarity Server SSH UsernameTrueSSH Username for the OpenClarity Server Virtual Machine.
    OpenClarity Server SSH Public KeyTrueSSH Public Key for the OpenClarity Server Virtual Machine. Paste the contents of ~/.ssh/id_rsa2.pub here.
    OpenClarity Server VM SizeTrueThe size of the OpenClarity Server Virtual Machine.
    OpenClarity Scanner VMs SizeTrueThe size of the OpenClarity Scanner Virtual Machines.
    Security TypeFalseSecurity Type of the OpenClarity Server Virtual Machine, e.g. TrustedLaunch (default) or Standard.
  3. (Optional) In the Advanced tab, modify the Container Image for each service if a specific OpenClarity version is required. Then, select the delete policy and the database.

    ParameterRequiredDescription
    Service Container ImageTrueDocker Container Image to use for each service.
    Asset Scan Delete PolicyTrueDelete Policy for resources created when performing an asset scan, e.g. Always, OnSuccess or Never.
    Database To UseTrueDatabase type to use, e.g. SQLite, PostgreSQL or External PostgreSQL.
  4. Click Review + create to create the deployment.

  5. Once the deployment is completed successfully, copy the OpenClarity SSH address from the Outputs tab.

  6. Open an SSH tunnel to OpenClarity the server

    ssh -N -L 8080:localhost:80 -i  "<Path to the SSH key specified during install>" ubuntu@<OpenClarity SSH Address copied during install>
    
  7. Access the OpenClarity UI.

    1. Open the OpenClarity UI in your browser at http://localhost:8080/. The dashboard opens.

    2. (Optional) If needed, you can access the API at http://localhost:8080/api. For details on the API, see the API reference.

    OpenClarity UI

Next steps

Complete the First Tasks on the UI.

3 - Deploy on Docker

Prerequisites

Deployment steps

To run OpenClarity in Docker on a local machine, complete the following steps.

  1. Download the latest OpenClarity release.

    wget https://github.com/openclarity/openclarity/releases/download/v0.7.2/docker-compose-v0.7.2.tar.gz
    
  2. Create a new directory, extract the files and navigate to the directory.

    mkdir docker-compose-v0.7.2
    tar -xvzf docker-compose-v0.7.2.tar.gz -C docker-compose-v0.7.2
    cd docker-compose-v0.7.2
    
  3. Start every control plane element with the docker compose file.

    docker compose --project-name openclarity --file docker-compose.yml up -d --wait --remove-orphans
    

    The output should be similar to:

    [+] Running 14/14
    ⠿ Network openclarity                        Created                                                       0.2s
    ⠿ Volume "openclarity_grype-server-db"       Created                                                       0.0s
    ⠿ Volume "openclarity_apiserver-db-data"     Created                                                       0.0s
    ⠿ Container openclarity-orchestrator-1       Healthy                                                      69.7s
    ⠿ Container openclarity-yara-rule-server-1   Healthy                                                      17.6s
    ⠿ Container openclarity-exploit-db-server-1  Healthy                                                      17.7s
    ⠿ Container openclarity-swagger-ui-1         Healthy                                                       7.8s
    ⠿ Container openclarity-trivy-server-1       Healthy                                                      26.7s
    ⠿ Container openclarity-uibackend-1          Healthy                                                      17.6s
    ⠿ Container openclarity-ui-1                 Healthy                                                       7.7s
    ⠿ Container openclarity-freshclam-mirror-1   Healthy                                                       7.8s
    ⠿ Container openclarity-grype-server-1       Healthy                                                      37.3s
    ⠿ Container openclarity-gateway-1            Healthy                                                       7.7s
    ⠿ Container openclarity-apiserver-1          Healthy                                                      17.7s
    

    Please note that the image_override.env file enables you to use the images you build yourself. You can override parameters in the docker-compose.yml by passing a custom env file to the docker compose up command via the --env-file flag. The /installation/docker/image_override.env file contains an example overriding all the container images.

  4. Check the running containers in the Docker desktop.

  5. Access the OpenClarity UI. Navigate to http://localhost:8080/ in your browser.

Next steps

Complete the First Tasks on the UI.

Clean up steps

  1. After you’ve finished your tasks, stop the running containers.

    docker compose --project-name openclarity --file docker-compose.yml down --remove-orphans
    

4 - Deploy on GCP

Prerequisites

  • You can install OpenClarity using the CLI, so you have to have gcloud on your computer available beforehand. For details on installing and configuring gcloud, see the official installation guide.
  • If you have already installed OpenClarity before and want to reinstall it, you have to manually restore deleted roles that were created during the previous installation.

Deployment steps

To install OpenClarity on Google Cloud Platform (GCP), complete the following steps.

  1. Download the newest GCP deployment release from GitHub and extract it to any location.

    wget https://github.com/openclarity/openclarity/releases/download/v0.7.2/gcp-deployment-v0.7.2.tar.gz
    
  2. Create a new directory, extract the files and navigate to the directory.

    mkdir gcp-deployment-v0.7.2
    tar -xvzf gcp-deployment-v0.7.2.tar.gz -C gcp-deployment-v0.7.2
    cd gcp-deployment-v0.7.2
    
  3. Copy the example configuration file and rename it.

    cp openclarity-config.example.yaml openclarity-config.yaml
    
  4. The following table contains all the fields that can be set in the openclarity-config.yaml file. You have to set at least the required ones.

    FieldRequiredDefaultDescription
    zoneyesThe Zone to locate the OpenClarity server.
    machineTypeyesThe machine type for the OpenClarity server.
    regionyesThe region to locate OpenClarity.
    scannerMachineTypee2-standard-2Machine type to use for the Scanner instances.
    scannerSourceImageprojects/ubuntu-os-cloud/global/images/ubuntu-2204-jammy-v20230630Source image to use for the Scanner instances.
    databaseToUseSQLiteThe database that OpenClarity should use.
    apiserverContainerImageghcr.io/openclarity/openclarity-apiserver:0.7.2The container image to use for the apiserver.
    orchestratorContainerImageghcr.io/openclarity/openclarity-orchestrator:0.7.2The container image to use for the orchestrator.
    uiContainerImageghcr.io/openclarity/openclarity-ui:0.7.2The container image to use for the ui.
    uibackendContainerImageghcr.io/openclarity/openclarity-ui-backend:0.7.2The container image to use for the uibackend.
    scannerContainerImageghcr.io/openclarity/openclarity-cli:0.7.2The container image to use for the scanner.
    exploitDBServerContainerImageghcr.io/openclarity/exploit-db-server:v0.2.4The container image to use for the exploit db server.
    trivyServerContainerImagedocker.io/aquasec/trivy:0.41.0The container image to use for the trivy server.
    grypeServerContainerImageghcr.io/openclarity/grype-server:v0.7.0The container image to use for the grype server.
    freshclamMirrorContainerImageghcr.io/openclarity/freshclam-mirror:v0.2.0The container image to use for the fresh clam mirror server.
    postgresqlContainerImagedocker.io/bitnami/postgresql:12.14.0-debian-11-r28The container image to use for the postgresql server.
    assetScanDeletePolicyAlwaysWhen asset scans should be cleaned up after scanning.
    postgresDBPasswordPostgres DB password. Only required if DatabaseToUse is Postgresql.
    externalDBNameDB to use in the external DB. Only required if DatabaseToUse is External.
    externalDBUsernameUsername for the external DB. Only required if the DatabaseToUse is External.
    externalDBPasswordPassword for the external DB. Only required if the DatabaseToUse is External.
    externalDBHostHostname or IP for the external DB. Only required if the DatabaseToUse is External.
    externalDBPortPort for the external DB. Only required if the DatabaseToUse is External.
  5. Deploy OpenClarity using gcloud deployment-manager.

    gcloud deployment-manager deployments create <openclarity deployment name> --config openclarity-config.yaml
    
  6. Open an SSH tunnel to the OpenClarity server with gcloud. For further information on how to create an SSH connection with gcloud to one of your instances check the official page.

    gcloud compute ssh --project=<project id> --zone=<zone name> <name of your VM> -- -NL 8080:localhost:80
    
  7. Access the OpenClarity UI.

    1. Open the OpenClarity UI in your browser at http://localhost:8080/. The dashboard opens.

    2. (Optional) If needed, you can access the API at http://localhost:8080/api. For details on the API, see the API reference.

    OpenClarity UI

Next steps

Complete the First Tasks on the UI.

Uninstall OpenClarity

  1. You can uninstall OpenClarity using the gcloud manager.

    gcloud deployment-manager deployments delete <openclarity deployment name>
    

Restore deleted roles

  1. On the IAM & Admin page on GCP, open the Roles tab, then search for OpenClarity in the filter input.

  2. Now manually undelete the Discoverer Snapshotter and Scanner roles to set their statuses from Deleted to Enabled.

    Undelete roles

5 - Deploy on Kubernetes

Prerequisites

  • Install a tool to run local Kubernetes clusters. Here, Kind is used as the default option for creating a local cluster.
  • Helm to install OpenClarity.

Deployment steps

To deploy OpenClarity to your Kubernetes cluster, complete the following steps.

  1. Create a Kubernetes cluster.

    kind create cluster --name openclarity-k8s
    
  2. Ensure the Kubernetes cluster is up and running. If you’re using kind, you can check the status of your clusters with the following command:

    kind get clusters
    
  3. Use Helm to install OpenClarity. Run the following command:

    helm install openclarity oci://ghcr.io/openclarity/charts/openclarity --version 0.7.2 \
        --namespace openclarity --create-namespace \
        --set orchestrator.provider=kubernetes \
        --set orchestrator.serviceAccount.automountServiceAccountToken=true
    
  4. Verify that all the OpenClarity pods have been successfully deployed by executing the following command:

    kubectl get pods -n openclarity
    
  5. Wait until all pods are in the Running state or have completed their initialization.

  6. Once the pods are ready, start port forwarding to access the OpenClarity gateway service. Use the following command to forward traffic from your local machine to the cluster:

    kubectl port-forward -n openclarity service/openclarity-gateway 8080:80
    
  7. Access the OpenClarity UI by navigating to http://localhost:8080/ in your web browser.

Next steps

Complete the First Tasks on the UI.

Clean up steps

  1. Uninstall OpenClarity with Helm. Run the following command:

    helm uninstall openclarity --namespace openclarity
    
  2. Delete the Kubernetes cluster.

    kind delete clusters openclarity-k8s
    

6 - First Tasks on the UI

Configure your first scan

  1. Open the UI.

    1. Open the OpenClarity UI in your browser at http://localhost:8080/. The dashboard opens.

    2. (Optional) If needed, you can access the API at http://localhost:8080/api. For details on the API, see the API reference.

    OpenClarity UI
  2. Click on the Scans icon. In the Scans window, you can create a new scan configuration.

    OpenClarity UI Scan
  3. Click New scan configuration.

    OpenClarity Scan Setup - Step 1
  4. Follow the steps of the New scan config wizard to name the scan, and optionally narrow the scope down with an OData query.

    OpenClarity Scan Setup - Step 2
  5. Enable the scan types you want to perform.

    OpenClarity Scan Setup - Step 3
  6. Select the time and/or frequency of the scans. To run the scan immediately, select Now.

    OpenClarity Scan Setup - Step 4
  7. Optionally, adjust the number of scanners to run in parallel and whether to use spot instances on cloud providers, or not.

    OpenClarity Scan Setup - Step 5
  8. Click Save. The new scan appears on the Scan Configurations tab.

    OpenClarity Scan Config Summary
  9. Once a scan is finished, you can browse around the various OpenClarity UI features and investigate the security scan reports.

    OpenClarity Dashboard with Findings