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

Return to the regular view of this page.

VMClarity development

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: make push-docker

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


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 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

  1. Build the containers and publish them to your docker registry

    DOCKER_REGISTRY=<your docker registry> make push-docker
  2. 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
  3. 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

  1. Copy the example scanConfig.json into the ubuntu user’s home directory

    scp scanConfig.json ubuntu@<ip address>:~/scanConfig.json
  2. Edit the scanConfig.json

    1. Give the scan config a unique name

    2. Enable the different scan families you want:

      "scanFamiliesConfig": {
        "sbom": {
          "enabled": true
        "vulnerabilities": {
          "enabled": true
        "exploits": {
          "enabled": true
    3. 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:

      "scope": ""
    1. 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.
  3. While ssh’d into the VMClarity server run

    curl -X POST http://localhost:8080/api/scanConfigs -H 'Content-Type: application/json' -d @scanConfig.json
  4. Check VMClarity logs to ensure that everything is performing as expected

    sudo journalctl -u vmclarity
  5. 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