In my previous article where I introduced atomic scan, I largely talked about using atomic to scan your containers and images for CVE Vulnerabilities. I also discussed how atomic scan had been architected to a plug-in approached so that you can implement your own scanners. The plug-ins do not have to focus on vulnerabilities, it could be as simple a scanner that collects information about containers and images.
In this blog, I will walk through how you can create your own custom scanner within the atomic plug-in framework.
The components of a scan plug-in
Creating a scanner plug-in for atomic mostly revolves around:
- making atomic aware of your plug-in
- ensuring the right input
- dealing with the output
Make atomic aware of your plug-in
To make atomic aware of your plug-in, you must deliver a configuration file that describes your atomic into one of atomic's configuration directory. One a proper file is in place, atomic can then use your plug-in. This also entails the use of some 'installation' technique. Both are described below.
Configuration File
The configuration file for plug-ins resides in /etc/atomic.d. Atomic ships a single plug-in
configuration for scanning with the openscap project. The plugin format is as follows:
type: scanner
scanner_name:
image_name: fully-qualified image name
default_scan:
custom_args: [optional]
scans: [
{ name: scan1,
args: [... ],
description: "Performs scan1"},
{ name: scan2,
args: [...],
description: "Performs scan2"
}
]
The scanner arguments must be in list format. You must also define one of your of your scans as the default scan for your scanner plug-in. You can also add an optional key and value for custom_args which allows you to add custom arguments to the docker command. This is typically used for bind mounting additional directories on the host file system for your scanning application. And finally, the image name must be fully-qualified because this is used to pull the image if it is not already local.
Installing your configuration file
The preferred way to install your plugin’s configuration file is through the use of the atomic’s install command. This command will execute the INSTALL label on the image. Typically, the INSTALL label is a combination of a temporary docker container command and a script to be executed by the container. An example INSTALL label might look like this:
LABEL INSTALL ‘docker run -it --rm -v /etc/atomic.d:/host/etc/atomic.d ${IMAGE} install.sh’
And the corresponding install.sh could be as simple as:
#/bin/sh echo “Installing configuration file for PLUGIN_NAME” cp -v /PLUGIN_NAME /host/etc/atomic.d
The destination of the configuration file in the install script is preceeded by /host because that is where the host's /etc/atomic.d/ is bind mounted into the container as described by the INSTALL label above.
Input from atomic
As of now, atomic scan can take four different inputs for which containers or images to scan. They are:
- --images (scan all images)
- --containers (scan all containers)
- --all (scan all containers and images)
- a list of images or containers (provide a list of image or container names or IDs.
Atomic will then mount the filesystem of each container or image to a time stamped directory under /run/atomic/time-stamp. Each container or image will be mounted to a directory with its ID. So for example, if you were scanning two images that had IDs of cef54 and b36fg respectively, the directory structure would look like:
/run/atomic/time-stamp/
cef54.../
b36fg.../
When atomic runs your scanning image, it will always mount /run/atomic/time-stamp to your container's /scanin directory. Your scanning container simply needs to walk the first level of directories under /scanin for processing. And because the directories are named with the ID of the object, you have a nice key to organize your output data.
Output from atomic
Just like how atomic will bind mount the chroots to /scanin, it also bind mounts a /scanout directory to the container. On the host, the /scanout directory is actually mapped to
/var/lib/atomic/scanner-name/time-stamp. Atomic expects you to put your output in the /scanout directory, again organizing your output data by directory names that correlate to the IDs of the object. You can output whatever data files you want but you must output a json file in each directory that follows the required template so that atomic can display some information to stdout for the user.
An example of what this directory structure looks like on the host can be as follows:
/var/lib/atomic/scanner-name/time-stamp/
cef54../
json
b36fb../
json
JSON template
The required JSON template must be formed as follows:
{
"Time": "timestamp",
"Finished Time": "timestamp",
"Successful": "true",
"Scan Type": "Description of scan",
"UUID": "/scanin/ID_of_object",
"CVE Feed Last Updated": "timestamp",
"Scanner": "scanner_name",
"Vulnerabilities": [
{
"Custom": {
"custom_key1": "custom_val1",
"custom_key2": [
{
"custom_key3": "custom_val3",
"custom_key_4": "custom_val4"
...
If the type of scanning you are performing is not related to CVEs or identifying vulnerabilities, you
can change the Vulnerabilities key results Results. Notice that you can use the custom tag to
add custom outputs. Atomic will recursively follow the custom tag and will output the key and values
verbatim as they are.
A sample custom scanner
If you want to create a custom scanner plugin for Atomic, you need to have prepared the following elements:
- A configuration file that describes your scanner plug-in
- An install script that prepares the host to run your scanning application
- Your scanning application
- An image that contains all of the above.
In my example below, I have created a custom scan plug-in that allows you to list all the RPMs in an image, which is the default scan type for my image. I also provide an alternative scan type that allows you to list the OS version of each image.
Configuration file
This configuration file is what enables your scanner plug-in with Atomic. Note that you can provide one or more types of scans in your configuration file but you must set a default. In the case of my custom configuration file, there are two scan types defined: rpm-list and get-os. Notice how they each call the python executable with a different argument which allows me to differentiate between the two.
type: scanner
scanner_name: example_plugin
image_name: example_plugin
default_scan: rpm-list
custom_args: ['-v', '/tmp/foobar:/foobar']
scans: [
{ name: rpm-list,
args: ['python', 'list_rpms.py', 'list-rpms'],
description: "List all RPMS",
},
{ name: get-os,
args: ['python', 'list_rpms.py', 'get-os'],
description: "Get the OS of the object",
}
]
Install script
The install script is used by the atomic install command to put your scanner's configuration file in the correct directory on the host file system. The atomic install command uses the INSTALL label in your image to call the install script you have provided. The following is a simple install script that copies my example_plugin configuration file to /etc/atomic.d on the host file system using the bind mount defined in the INSTALL label (shown in the Dockerfile below).
#/bin/bash echo "Copying example_plugin configuration file to host filesystem..." cp -v /example_plugin /host/etc/atomic.d/
Executable
Obviously a scanner can be very complex. My example scanner here is a relatively simple python executable that can list the RPMs in an image or show its OS version. Note how in the python executable, the results are written to json files in the required template.
import os
import subprocess
from datetime import datetime
import json
from sys import argv
class ScanForInfo(object):
INDIR = '/scanin'
OUTDIR = '/scanout'
def __init__(self):
self._dirs = [ _dir for _dir in os.listdir(self.INDIR) if os.path.isdir(os.path.join(self.INDIR, _dir))]
def list_rpms(self):
for _dir in self._dirs:
full_indir = os.path.join(self.INDIR, _dir)
# If the chroot has the rpm command
if os.path.exists(os.path.join(full_indir, 'usr/bin/rpm')):
full_outdir = os.path.join(self.OUTDIR, _dir)
# Get the RPMs
cmd = ['rpm', '--root', full_indir, '-qa']
rpms = subprocess.check_output(cmd).split()
# Construct the JSON
rpms_out = {'Custom': {}}
rpms_out['Custom']['rpms'] = rpms
# Make the outdir
os.makedirs(full_outdir)
# Writing JSON data
self.write_json_to_file(full_outdir, rpms_out, _dir)
def get_os(self):
for _dir in self._dirs:
full_indir = os.path.join(self.INDIR, _dir)
os_release = None
for location in ['etc/release', 'etc/redhat-release','etc/debian_version']:
try:
os_release = open(os.path.join(full_indir, location), 'r').read()
except IOError:
pass
if os_release is not None:
break
full_outdir = os.path.join(self.OUTDIR, _dir)
# Construct the JSON
out = {'Custom': {}}
out['Custom']['os_release'] = os_release
# Make the outdir
os.makedirs(full_outdir)
# Writing JSON data
self.write_json_to_file(full_outdir, out, _dir)
@staticmethod
def write_json_to_file(outdir, json_data, uuid):
current_time = datetime.now().strftime('%Y-%m-%d-%H-%M-%S-%f')
json_out = {
"Time": current_time,
"Finished Time": current_time,
"Successful": "true",
"Scan Type": "List RPMs",
"UUID": "/scanin/{}".format(uuid),
"CVE Feed Last Updated": "NA",
"Scanner": "example_plugin",
"Results": [json_data],
}
with open(os.path.join(outdir, 'json'), 'w') as f:
json.dump(json_out, f)
scan = ScanForInfo()
if argv[1] == 'list-rpms':
scan.list_rpms()
elif argv[1] == 'get-os':
scan.get_os()
Dockerfile
The Dockerfile for my example plug-in is very simple. It contains an INSTALL label so that atomic install will function properly. And besides the RHEL base image, it simply adds the example plugin configuration file, the scanner executable, and the install.sh script itself.
from registry.access.redhat.com/rhel7:latest LABEL INSTALL='docker run -it --rm --privileged -v /etc/atomic.d/:/host/etc/atomic.d/ $IMAGE sh /install.sh' ADD example_plugin / ADD list_rpms.py / ADD install.sh /
The user experience
As is the mission of the atomic application, the user experience for using the new scanner image is very crisp and easy. The first step in using the image is to use atomic install to prepare the host operating system. In the case of this example, we simply need to 'expose' the example_plugin configuration file from the image to /etc/atomic.d/ on the host.
# sudo atomic install example_plugin docker run -it --rm -v /etc/atomic.d/:/host/etc/atomic.d/ example_plugin sh /install.sh Copying example_plugin configuration file to host filesystem... '/example_plugin' -> '/host/etc/atomic.d/example_plugin' #
With atomic install, if the image is not local, atomic will pull the image from the correct repository onto your host. In the example case, the image was already local. Now the host is aware of the new plugin and we can verify what scanning options are available to us with the atomic scan command.
# sudo atomic scan --list Scanner: openscap * Image Name: openscap Scan type: cve_scan * Description: Performs a CVE scan based on known CVE data Scan type: standards_scan Description: Performs a standard scan Scanner: example_plugin Image Name: example_plugin Scan type: rpm-list * Description: List all RPMS Scan type: get-os Description: Get the OS of the object * denotes default
When viewing the list of available scan options, notice how asterisks (*) are use to denote defaults. In this case, you can see that 'openscap' is the default scanner and its 'cve_scan' is the default scan type. For our example plugin, 'rpm-list' is the default scan type and 'get-os' is an additional scan type. You can set the default scanner in the /etc/atomic configuration file.
You can use the '--scanner' option in atomic scan to switch scanners and if no '--scan_type' is provided, it will use the default scan type declared for that scanner.
# sudo atomic scan --scanner example_plugin registry.access.redhat.com/rhel7:latest docker run -it --rm -v /etc/localtime:/etc/localtime -v /run/atomic/2016-05-18-13-44-57-660748:/scanin -v /var/lib/atomic/example_plugin/2016-05-18-13-44-57-660748:/scanout:rw,Z -v /tmp/foobar:/foobar example_plugin python list_rpms.py list-rpms registry.access.redhat.com/rhel7:latest (c453594215e4370) The following results were found: rpms: tzdata-2016d-1.el7.noarch setup-2.8.71-6.el7.noarch basesystem-10.0-7.el7.noarch nss-softokn-freebl-3.16.2.3-14.2.el7_2.x86_64 glibc-2.17-106.el7_2.6.x86_64 ... (content remove for space) yum-plugin-ovl-1.1.31-34.el7.noarch vim-minimal-7.4.160-1.el7.x86_64 rootfiles-8.1-11.el7.noarch Files associated with this scan are in /var/lib/atomic/example_plugin/2016-05-18-13-44-57-660748.
Notice how atomic scan will also cite where the output files from the scan are located.
If you wanted to use the example_plugin scanner and the scan_type of 'get-os', you simply need to pass both the '--scanner' and '--scan_type' command switches.
# sudo atomic scan --scanner example_plugin --scan_type get-os registry.access.redhat.com/rhel7:latest ubuntu docker run -it --rm -v /etc/localtime:/etc/localtime -v /run/atomic/2016-05-18-13-47-25-627346:/scanin -v /var/lib/atomic/example_plugin/2016-05-18-13-47-25-627346:/scanout:rw,Z -v /tmp/foobar:/foobar example_plugin python list_rpms.py get-os ubuntu (17b6a9e179d7cb9) The following results were found: os_release: stretch/sid registry.access.redhat.com/rhel7:latest (c453594215e4370) The following results were found: os_release: Red Hat Enterprise Linux Server release 7.2 (Maipo) Files associated with this scan are in /var/lib/atomic/example_plugin/2016-05-18-13-47-25-627346.Last updated: January 19, 2023