Command line tools for container quality assurance
Singularity Container Tools
These are tools for Singularity containers, optimized for using with continuous integration for security and quality checks. For an example of the package being used in a continuous integration context, see the stools-clair repository.
Note that after the first two releases, version numbers correspond with releases on pypi, and not Singularity versions.
- v0.0.13 (master) adds support for reports saving
- v3.2.1 Uses Singularity v3.2.1 and above
- v2.4.5 Uses Singularity v2.4.5
Clair is intended to run as a server to continuous scan Docker layers for vulnerabilities. This doesn't map well to the research domain because of the following:
- Docker containers come in layers (.tar.gz files) while Singularity images are single binary files that don't "plug in" nicely to Clair.
- Most researchers can't support continuous running of such a service.
On the other hand, a typical researcher does use services like TravisCI and CircleCI to run their code bases against tests. Since these services now offer running containers and other service-type things, we in fact could do the following:
- Spin up a Clair server during testing
- Build a Singularity image, and scan the filesystem contents (before finalized in the image).
While this isn't a continually running service, we can minimally ensure that a container is scanned each time it is built (and then likely merged to be used in production). If the user takes advantage of Singularity Hub or Singularity Registry Server the image will be pushed or built for production after passing these various tests.
This experiment is based on early discussion in this thread.
You'll need to first clone the repository:
git clone https://github.com/singularityhub/stools cd stools
If you want, build the container (or use a tagged release from Docker Hub).
$ docker build -t vanessa/stools-clair .
Start the application with docker compose.
Note that you should have the images you want to scan in the $PWD, which will be mapped to the container in
(see the docker-compose.yml file). You can change this around, just be sure that the containers you want to add are here.
$ docker-compose up -d
Make sure that your containers are up and running! There is one for the clair server that we will interact with, and one for the database.
$ docker-compose ps Name Command State Ports ----------------------------------------------------------------------------------------------------------------- clair-db docker-entrypoint.sh postgres Up 0.0.0.0:5432->5432/tcp clair-scanner /clair -config=/config/con ... Up 0.0.0.0:6060->6060/tcp, 6061/tcp, 0.0.0.0:8080->8080/tcp
Also note that the folder reports by way of being in the mounted present working
directory, will appear at
/code/reports in the container. We will need to know this later.
Scan an Image
Let's scan a local image in $PWD mapped to /code in the container. First pull one from your registry of choice:
$ singularity pull shub://vsoch/singularity-images
And now let's scan! We do this by executing a command to the
The most basic usage will just print a report to stdout, like this:
$ docker exec -it clair-scanner sclair singularity-images_latest.sif ... CVE-2016-9843 (Low) http://people.ubuntu.com/~ubuntu-security/cve/CVE-2016-9843 The crc32_big function in crc32.c in zlib 1.2.8 might allow context-dependent attackers to have unspecified impact via vectors involving big-endian CRC calculation.
Save a Report
However, if you want to save a report to file (json), you can add the
pointing to an existing output directory of choice. For example, since reports
is provided in our present working directory and already bound to the container at
we can specify that as an argument:
$ docker exec -it clair-scanner sclair --report /code/reports singularity-images_latest.sif
--report will not disable the print to stdout. However, if you want to disable it,
you can add the
--no-print option. An example JSON report can be found in the reports folder.
$ docker exec -it clair-scanner sclair --report /code/reports --no-print singularity-images_latest.sif
For a full example of what is printed to stdout (using a container with a known vulnerability) see the example test folder.
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.