diff --git a/README.md b/README.md index 319f93aa2..320ef5533 100644 --- a/README.md +++ b/README.md @@ -19,7 +19,7 @@ Join [VMClarity's Slack channel](https://outshift.slack.com/messages/vmclarity) # Table of Contents - [Why VMClarity?](#why-vmclarity) -- [Quick Start](#quick-start) +- [Getting started](#getting-started) - [Overview](#overview) - [Roadmap](#roadmap) - [Contributing](#contributing) @@ -50,56 +50,9 @@ However, there are challenges with assembling and managing these tools yourself: The VMClarity project is focused on unifying detection and management of VM security threats in an agentless manner. -# Quick start +# Getting started -## Install VMClarity - -### AWS - -1. Start the CloudFormation [wizard](https://console.aws.amazon.com/cloudformation/home#/stacks/create/review?stackName=VMClarity&templateURL=https://vmclarity-cfn.s3.eu-central-1.amazonaws.com/0.6.0/VmClarity.cfn), or upload the [latest](https://github.com/openclarity/vmclarity/releases/latest) CloudFormation template -2. Specify the SSH key to be used to connect to VMClarity under 'KeyName' -3. Once deployed, copy VmClarity SSH Address from the "Outputs" tab - -For a detailed installation guide, please see [AWS](installation/aws/README.md). - -### Azure - -1. Click the [![Deploy To Azure](https://docs.microsoft.com/en-us/azure/templates/media/deploy-to-azure.svg)](https://portal.azure.com/#blade/Microsoft_Azure_CreateUIDef/CustomDeploymentBlade/uri/https%3A%2F%2Fraw.githubusercontent.com%2Fopenclarity%2Fvmclarity%2Fmain%2Finstallation%2Fazure%2Fvmclarity.json/uiFormDefinitionUri/https%3A%2F%2Fraw.githubusercontent.com%2Fopenclarity%2Fvmclarity%2Fmain%2Finstallation%2Fazure%2Fvmclarity-UI.json) button. -2. Fill out the required fields in the wizard -3. Once deployed, copy the VMClarity SSH address from the Outputs tab - -### GCP - -1. Change directory to `installation/gcp/dm` -2. Copy `vmclarity-config.example.yaml` to `vmclarity-config.yaml`, update with required values. -3. Deploy vmclarity using GCP deployment manager - ``` - gcloud deployment-manager deployments create --config vmclarity-config.yaml - ``` -4. Once deployed, copy the VMClarity SSH IP address from the CLI output. - -### Kubernetes - -1. helm install -n vmclarity --create-namespace vmclarity ./vmclarity - -## Access VMClarity UI - -1. Open connection to VMClarity API Gateway either: - - * On AWS, Azure or GCP, open an SSH tunnel to VMClarity VM server - ``` - ssh -N -L 8080:localhost:80 -i "" ubuntu@ - ``` - - * On Kubernetes port-forward vmclarity-gateway service: - ``` - kubectl port-forward -n vmclarity service/vmclarity-gateway 8080:80 - ``` - -2. Access VMClarity UI in the browser: http://localhost:8080/ -3. Access the [API](api/openapi.yaml) via http://localhost:8080/api - -For a detailed UI tour, please see [tour](TOUR.md). +For step-by-step guidance on how to deploy VMClarity across different environments, including AWS, Azure, GCP, and Docker, click on [this link](https://openclarity.io/docs/vmclarity/getting-started/) and choose your preferred provider for detailed deployment instructions. # Overview diff --git a/TOUR.md b/TOUR.md deleted file mode 100644 index fcdac8ecf..000000000 --- a/TOUR.md +++ /dev/null @@ -1,55 +0,0 @@ -# VMClarity UI Tour -Figure 1. VMClarity UI Dashboard -![VMClarity UI Dashboard](assets/vmclarity-ui-1.png) - -## Configure Your First Scan - -- Click on the "Scans" icon as shown in Figure 2. In the Scans window, you can create a new scan configuration. - -Figure 2. VMClarity UI Scan - -VMClarity UI Scan - -- Create a new scan configuration. As shown in Figure 3, click on "New scan configuration". - -Figure 3. VMClarity Scan Setup Step 1 - -VMClarity Scan Setup - Step 1 - -- In the "New scan config" wizard shown in Figure 4, follow the wizard steps to name the scan, and identify the AWS scope (region, VPC, security groups, etc.). In the example shown in Figure 4, the AWS us-east-2 region, and a specific VPC were identified as well as a specific EC2 instance with the name "vmclarity-demo-vm". - -Figure 4. VMClarity Scan Setup Step 2 - -VMClarity Scan Setup - Step 2 - -- Next, identify all the scan types you want enabled. As Figure 5 shows, all the available scan types have been enabled. - -Figure 5. VMClarity Scan Setup Step 3 - -VMClarity Scan Setup - Step 3 - -- Finally, select the scan time and/or frequency of the scans. Figure 6 shows the scan option of "now", but other options include "specific time" and "recurring" (Based on a cron job). - -Figure 6. VMClarity Scan Setup Step 4 - -VMClarity Scan Setup - Step 4 - -- Once all the scan setup steps have been entered, click on "Save". - -In the Scan Configurations tab, you will see the scan config listed as shown in Figure 7. - -Figure 7. VMClarity Scan Configuration List - -VMClarity Scan Config Summary - -Once a scan runs and generates findings, you can browse around the various VMClarity UI features and investigate the security scan reports. - -Here are a few of the many scan findings that are available in the VMClarity UI. - -Figure 8. VMClarity Scan List - -VMClarity Scan List - -Figure 9. VMClarity Dashboard - -VMClarity Dashboard with Findings diff --git a/assets/vmclarity-arch-20230406.svg b/assets/vmclarity-arch-20230406.svg deleted file mode 100644 index f8b4714b8..000000000 --- a/assets/vmclarity-arch-20230406.svg +++ /dev/null @@ -1 +0,0 @@ -Scan OrchestratorAPIUI WebserverBackendDatabasetrivy-servergrype-serverfreshclam-mirror•Operating System•Packages•Configuration•ApplicationsVolumeScanner JobSnapshot volumeSnapshotCLI (curl)UIThird Party API e.g.AWSexploitDB-server UI BackendDB DriverProvider DriverVMClarity CLIVMClarity CLICI/CDVM ImageTarget Asset \ No newline at end of file diff --git a/assets/vmclarity-cf-basic.svg b/assets/vmclarity-cf-basic.svg deleted file mode 100644 index b397a9e41..000000000 --- a/assets/vmclarity-cf-basic.svg +++ /dev/null @@ -1 +0,0 @@ -Private subnet (VmClarityScannerSubnet)Virtual private cloud (VPC)10.0.0.0/16Public subnet (VmClarityServerSubnet)10.0.0.0/24Availability ZoneAWS CloudVmClarityServerInternet gatewayRegion10.0.1.0/24NAT gateway \ No newline at end of file diff --git a/assets/vmclarity-dashboard-data.png b/assets/vmclarity-dashboard-data.png deleted file mode 100644 index 41e56dc68..000000000 Binary files a/assets/vmclarity-dashboard-data.png and /dev/null differ diff --git a/assets/vmclarity-scan-config-summary.png b/assets/vmclarity-scan-config-summary.png deleted file mode 100644 index 713fd0f99..000000000 Binary files a/assets/vmclarity-scan-config-summary.png and /dev/null differ diff --git a/assets/vmclarity-scan-list.png b/assets/vmclarity-scan-list.png deleted file mode 100644 index 427662e2e..000000000 Binary files a/assets/vmclarity-scan-list.png and /dev/null differ diff --git a/assets/vmclarity-scan-setup-1.png b/assets/vmclarity-scan-setup-1.png deleted file mode 100644 index 04f0ceb93..000000000 Binary files a/assets/vmclarity-scan-setup-1.png and /dev/null differ diff --git a/assets/vmclarity-scan-setup-2.png b/assets/vmclarity-scan-setup-2.png deleted file mode 100644 index ef8e9993d..000000000 Binary files a/assets/vmclarity-scan-setup-2.png and /dev/null differ diff --git a/assets/vmclarity-scan-setup-3.png b/assets/vmclarity-scan-setup-3.png deleted file mode 100644 index fab305710..000000000 Binary files a/assets/vmclarity-scan-setup-3.png and /dev/null differ diff --git a/assets/vmclarity-scan-setup-4.png b/assets/vmclarity-scan-setup-4.png deleted file mode 100644 index 1e405b7a1..000000000 Binary files a/assets/vmclarity-scan-setup-4.png and /dev/null differ diff --git a/assets/vmclarity-ui-1.png b/assets/vmclarity-ui-1.png deleted file mode 100644 index 7b34e4519..000000000 Binary files a/assets/vmclarity-ui-1.png and /dev/null differ diff --git a/assets/vmclarity-ui-2.png b/assets/vmclarity-ui-2.png deleted file mode 100644 index a1488c0ab..000000000 Binary files a/assets/vmclarity-ui-2.png and /dev/null differ diff --git a/installation/aws/README.md b/installation/aws/README.md deleted file mode 100644 index 786ce3376..000000000 --- a/installation/aws/README.md +++ /dev/null @@ -1,61 +0,0 @@ -# Installing on AWS -## Table of Contents - -- [Overview](#overview) -- [Deploy the VMClarity AWS CloudFormation Stack](#deploy-the-vmclarity-aws-cloudformation-stack) - -## Overview -An AWS CloudFormation template is provided for quick deployment of the -VMClarity environment. **Note**: To avoid extra costs (cross-region snapshots), -you may want to deploy the VMClarity AWS CloudFormation template in the same -region where the majority of VMs are that you want VMClarity to scan. - -Figure 2 illustrates the basic AWS resources that the VMClarity CloudFormation -template creates. The AWS CloudFormation template creates a single VPC with a -public and private subnet. An AWS Internet Gateway (IGW) and NAT Gateway (NGW) -are deployed in the VPC. - -The public subnet (VmClarityServerSubnet) hosts the VMClarity Server -(VmClarityServer) EC2 instance. The VMClarity server is what houses the -scanning configuration, UI and other control components. The EC2 instance is -assigned an external IPv4 address (EIP) for SSH and web UI access. - -The private subnet (VmClarityScannerSubnet) hosts the VM snapshot instances -(EC2) that are scanned for security vulnerabilities. - -Figure 2. VMClarity Cloud Formation Resources -![VMClarity CloudFormation Resources](../../assets/vmclarity-cf-basic.svg) - -## Deploy the VMClarity AWS CloudFormation Stack - -Click [here](https://console.aws.amazon.com/cloudformation/home#/stacks/create/review?stackName=VMClarity&templateURL=https://s3.eu-west-2.amazonaws.com/vmclarity-v0.4.0/VmClarity.cfn) to start the VMClarity CloudFormation Stack wizard. - -Alternatively: -* Obtain the CloudFormation template using one of the following: - * Download the latest stable VMClarity.cfn from the chosen VMClarity release - [here](https://github.com/openclarity/vmclarity/releases) - * Clone or copy the [AWS CloudFormation template](./VmClarity.cfn) - file from main to deploy the latest development code. -* Go to the AWS CloudFormation service page: > Create Stack > With New Resources - (standard)> Check "Template is ready", and Check "Upload a template file" > - Upload a template file/Choose file. - -In the VMClarity CloudFormation Stack wizard: -- Name the stack -- Select the InstanceType (defaults to t2.large for the VMClarity Server, and the scanner VMs) -- KeyName - Choose your SSH key for the EC2 instance -- SSHLocation - Adjust per your policies -- AdvancedConfiguration - Leave as-is unless you are building from a custom registry - -Click "NEXT" - -- Tags: Add as you wish -- Leave defaults unless you need to adjust for your own policies - -Click "NEXT" -Scroll to the bottom of the screen, and check "I acknowledge..." - -Click "SUBMIT" - -After a few minutes the stack will be deployed, and you can get the VMClarity -server instance public IPv4 address from the AWS CloudFormation "Outputs" tab. diff --git a/installation/docker/README.md b/installation/docker/README.md deleted file mode 100644 index 5535cdb2c..000000000 --- a/installation/docker/README.md +++ /dev/null @@ -1,24 +0,0 @@ -# Docker Compose - -## Configuring VMClarity - -Each configurable service has a .env file, in this file set the -attributes required for that service and it will be loaded by the compose file -when started. - -## Overriding Parameters in the docker-compose.yml - -You can override parameters in the docker-compose.yml by passing a custom env -file into the `docker compose up` command via the `--env-file` flag. An example -overriding all the container images `image_override.env` can be modified or -copied for this. - -## Starting VMClarity -``` -docker compose --project-name vmclarity --file docker-compose.yml up -d --wait --remove-orphans -``` - -## Stopping VMClarity -``` -docker compose --project-name vmclarity --file docker-compose.yml down --remove-orphans -``` diff --git a/installation/gcp/dm/README.md b/installation/gcp/dm/README.md deleted file mode 100644 index 737c19284..000000000 --- a/installation/gcp/dm/README.md +++ /dev/null @@ -1,30 +0,0 @@ -# Installing VMClarity on GCP with Deployment Manager - -1. Copy example configuration file to a new config - - ``` - cp vmclarity-config.example.yaml vmclarity-config.yaml - ``` - -2. Edit configuration to add required fields. - Check vmclarity.py.schema for other optional parameters. - -3. Create a deployment using the gcloud CLI - - ``` - gcloud deployment-manager deployments create --config vmclarity-config.yaml - ``` - -4. Copy the VMClarity IP address from the output - -5. SSH into the VMClarity server and open a tunnel to the UI - - ``` - ssh -L 8888:localhost:8888 vmclarity@ - ``` - -6. To update the VMClarity configuration, modify the vmclarity-config.yaml, then update the deployment: - - ``` - gcloud deployment-manager deployments update --config vmclarity-config.yaml - ```