Hackernoon logoAn Open-Source Tool For Security Scans Of Container Images — Vilicus by@edersonbrilhante

An Open-Source Tool For Security Scans Of Container Images — Vilicus

Ederson Brilhante Hacker Noon profile picture

@edersonbrilhanteEderson Brilhante

Senior Software Engineer with 11 years of professional experience working in large internet companies.

What is Vilicus?

Vilicus is an open-source tool that orchestrates security scans of container images (Docker/OCI) and centralizes all results into a database for further analysis and metrics.

Vilicus provides many alternatives to use it:

Why do scan for vulnerabilities?

A recent analysis of around 4 million Docker Hub images by cyber security firm Prevasio found that 51% of the images had exploitable vulnerabilities. A large number of these were cryptocurrency miners, both open and hidden, and 6,432 of the images had malware.


Docker image security scanning is a process for finding security vulnerabilities within your Docker image files.
Typically, image scanning works by parsing through the packages or other dependencies that are defined in a container image file, then checking to see whether there are any known vulnerabilities in those packages or dependencies.

How does it work?

There are many tools to scan container images for vulnerabilities such as AnchoreClair, and Trivy. But sometimes the results from the same image can be different. And this project comes to help the developers to improve the quality of their container images by finding vulnerabilities and thus addressing them with agnostic sight from vendors.

Some articles comparing the scanning tools:


Cached Database

Vilicus updates daily the vendor databases with the latest changes in the vulns DBs.

Using a strategy to storage the database data in layers of docker images, the whole platform is ready to use in minutes instead of hours. Starting the sync feed with vulns from scratch can take at least 6 hours.

Do you want to know more about this strategy? Read my article

Local Registry

Vilicus provides a local registry, so you can build a local image and scanning it without pushing it to a remote repository.

docker build -t localhost:5000/local-image:my-tag .

curl -o docker-compose.yml https://raw.githubusercontent.com/edersonbrilhante/vilicus/main/deployments/docker-compose.yml

docker-compose up -d


docker run -v ${PWD}/artifacts:/artifacts \
  --network container:vilicus \
  vilicus/vilicus:latest \
  sh -c "dockerize -wait http://vilicus:8080/healthz -wait-retry-interval 60s -timeout 2000s vilicus-client -p /opt/vilicus/configs/conf.yaml -i ${IMAGE}  -t /opt/vilicus/contrib/sarif.tpl -o /artifacts/results.sarif"

GitHub Action

GitHub Actions makes it easy to automate all your software workflows, now with world-class CI/CD. Build, test, and deploy your code right from GitHub. Make code reviews, branch management, and issue triaging work the way you want - Source

Vilicus provides a GitHub action to help you scanning container images in your CI/CD.

Container scanning

A scan can be done using a remote image and a local image. Using a remote repository such as docker.io the image will be docker.io/your-organization/image:tag:

- name: Scan image
    uses: edersonbrilhante/vilicus-github-action@main
      image: "docker.io/myorganization/myimage:tag"

And to use a local image its need to tag as localhost:5000/image:tag:

  - name: Scan image
    uses: edersonbrilhante/vilicus-github-action@main
      image: "localhost:5000/myimage:tag"

Full example

Complete example with steps for cleaning space, building local image, Vilicus scanning, and uploading results to GitHub Security

name: Container Image CI
on: [push]
    runs-on: ubuntu-latest
      - name: Maximize Build Space
        uses: easimon/maximize-build-space@master
          root-reserve-mb: 512
          swap-size-mb: 1024
          remove-dotnet: 'true'
          remove-android: 'true'
          remove-haskell: 'true'
      - name: Checkout branch
        uses: actions/checkout@v2
      - name: Build the Container image
        run: docker build -t localhost:5000/local-image:${GITHUB_SHA} .
      - name: Vilicus Scan
        uses: edersonbrilhante/vilicus-github-action@main
          image: localhost:5000/local-image:${{ github.sha }}
      - name: Upload results to github security
        uses: github/codeql-action/upload-sarif@v1
          sarif_file: artifacts/results.sarif

Results in GitHub Security:

Check an example using Vilicus GitHub Action

Pipeline example:

List with all vulns found:

Vuln details:

GitLab CI Template

Vilicus provides a Template CI  to help you scanning container images in your CI/CD and import the results to Gitlab Security Tab

Vilicus needs a VM with ~30GB of free space disk, because that, it will not work with the GitLab shared-runners.

Linux shared runners

All your CI/CD jobs run on n1-standard-1 instances with 3.75GB of RAM, CoreOS and the latest Docker Engine installed. Instances provide 1 vCPU and 25GB of HDD disk space. - Source

You can use your own runner or use a strategy I created to have runner hosted by GitHub runner combine with the GitHub Action maximize-build-space

GitHub Action maximize-build-space

When removing software, consider that the removal of large amounts of files (which this is) can take minutes to complete. On the upside, you'll get more than 60 GB of disk space available if you actually need it. - Source

Do you want to know more about running GitLab Runners in GitHub? Read my article

How to use in .gitlab-ci.yml:

  - remote: https://raw.githubusercontent.com/edersonbrilhante/vilicus-gitlab/main/Vilicus.gitlab-ci.yml  

  extends: .vilicus
    IMAGE: <image>
    - <your runner>

Vulnerabilities imported in GitLab Security Tab:

Free Online Service

Vilicus also provides a free online service.

This service is a serverless full-stack application with backend workers and database only using git and ci/cd runners.

The Frontend is hosted in GitHub Pages. This frontend is a landing page with a free service to scan or display the vulnerabilities in container images.

The results of container image scans are stored in a GitLab Repository.

When the user asks to show the results from an image, the frontend consumes the GitLab API to retrieve the file with vulns from this image. In case this image is not scanned yet, the user has the option to schedule a scan using a google form.

When this form is filled, the data is sent to a Google Spreadsheet.

A GitHub Workflow runs every 5 minutes to check if there are new answers in this Spreadsheet. For each new image in the Spreadsheet, this workflow triggers another Workflow to scan the image and save the result in the GitLab Repository.

Displaying an image already scanned by the service

Scheduling a new scan:

Source Code

That’s it!

In case you have any questions, please leave a comment here or ping me on 🔗 LinkedIn.

Also published at https://dev.to/edersonbrilhante/vilicus-a-overseer-for-security-scanning-of-container-images-eji


Join Hacker Noon

Create your free account to unlock your custom reading experience.