VMClarity development

1: End-to-End Testing Guide

Building VMClarity Binaries

Makefile targets are provided to compile and build the VMClarity binaries. make build can be used to build all of the components, but also specific targets are provided, for example make build-cli and make build-backend to build the specific components in isolation.

Building VMClarity Containers

make docker can be used to build the VMClarity containers for all of the components. Specific targets for example make docker-cli and make docker-backend are also provided.

make push-docker is also provided as a shortcut for building and then publishing the VMClarity containers to a registry. You can override the destination registry like:

DOCKER_REGISTRY=docker.io/tehsmash make push-docker

You must be logged into the docker registry locally before using this target.

Linting

make lint can be used to run the required linting rules over the code. golangci-lint rules and config can be viewed in the .golangcilint file in the root of the repo.

make fix is also provided which will resolve lint issues which are automatically fixable for example format issues.

make license can be used to validate that all the files in the repo have the correctly formatted license header.

To lint the cloudformation template, cfn-lint can be used, see https://github.com/aws-cloudformation/cfn-lint#install for instructions on how to install it for your system.

Unit tests

make test can be used run all the unit tests in the repo. Alternatively you can use the standard go test CLI to run a specific package or test like:

go test ./cli/cmd/... -run Test_isSupportedFS

Generating API code

After making changes to the API schema in api/openapi.yaml, you can run make api to regenerate the model, client and server code.

Testing End to End

For details on how to test VMClarity end to end please see End-to-End Testing Guide.

1 - End-to-End Testing Guide

Installing a specific VMClarity build on AWS

Build the containers and publish them to your docker registry
```
DOCKER_REGISTRY=<your docker registry> make push-docker
```
Install VMClarity cloudformation
1. Ensure you have an SSH key pair uploaded to AWS Ec2
2. Go to CloudFormation -> Create Stack -> Upload template.
3. Upload the VMClarity.cfn file.
4. Follow the wizard through to the end
  1. Set the VMClarity Backend Container Image and VMClarity Scanner Container Image parameters in the wizard to use custom images (from step 1.) for deployment.
  2. Change the Asset Scan Delete Policy to OnSuccess or Never if debugging scanner VMs is required.
5. Wait for install to complete
Ensure that VMClarity backend is working correctly
1. Get the IP address from the CloudFormation stack’s Output Tab
2. ssh ubuntu@<ip address>
3. Check the VMClarity Logs
```
sudo journalctl -u vmclarity
```

Performing an end to end test

Copy the example scanConfig.json into the ubuntu user’s home directory
```
scp scanConfig.json ubuntu@<ip address>:~/scanConfig.json
```

Edit the scanConfig.json

Give the scan config a unique name

Enable the different scan families you want:

"scanFamiliesConfig": {
  "sbom": {
    "enabled": true
  },
  "vulnerabilities": {
    "enabled": true
  },
  "exploits": {
    "enabled": true
  }
},

Configure the scope of the test

By Region, VPC or Security group:

"scope": "contains(assetInfo.location, '<name of region>/<name of vpc>') and contains(assetInfo.securityGroups, '{\"id\":\"<name of sec group>\"}')"

By tag:

"scope": "contains(assetInfo.tags, '{\"key\":\"<key>\",\"value\":\"<value>\"}')"

All:
```
```yaml
"scope": ""
```
```

Set operationTime to the time you want the scan to run. As long as the time is in the future it can be within seconds.

While ssh’d into the VMClarity server run

curl -X POST http://localhost:8080/api/scanConfigs -H 'Content-Type: application/json' -d @scanConfig.json

Check VMClarity logs to ensure that everything is performing as expected
```
sudo journalctl -u vmclarity
```
Monitor the asset scans
- Get scans:
```
curl -X GET http://localhost:8080/api/scans
```
  After the operationTime in the scan config created above there should be a new scan object created in Pending.
  Once discovery has been performed, the scan’s assetIDs list should be populated will all the assets to be scanned by this scan.
  The scan will then create all the “assetScans” for tracking the scan process for each asset. When that is completed the scan will move to “InProgress”.
- Get asset scans:
```
curl -X GET http://localhost:8080/api/assetScans
```