Skip to main content
Redhat Developers  Logo
  • Products

    Featured

    • Red Hat Enterprise Linux
      Red Hat Enterprise Linux Icon
    • Red Hat OpenShift AI
      Red Hat OpenShift AI
    • Red Hat Enterprise Linux AI
      Linux icon inside of a brain
    • Image mode for Red Hat Enterprise Linux
      RHEL image mode
    • Red Hat OpenShift
      Openshift icon
    • Red Hat Ansible Automation Platform
      Ansible icon
    • Red Hat Developer Hub
      Developer Hub
    • View All Red Hat Products
    • Linux

      • Red Hat Enterprise Linux
      • Image mode for Red Hat Enterprise Linux
      • Red Hat Universal Base Images (UBI)
    • Java runtimes & frameworks

      • JBoss Enterprise Application Platform
      • Red Hat build of OpenJDK
    • Kubernetes

      • Red Hat OpenShift
      • Microsoft Azure Red Hat OpenShift
      • Red Hat OpenShift Virtualization
      • Red Hat OpenShift Lightspeed
    • Integration & App Connectivity

      • Red Hat Build of Apache Camel
      • Red Hat Service Interconnect
      • Red Hat Connectivity Link
    • AI/ML

      • Red Hat OpenShift AI
      • Red Hat Enterprise Linux AI
    • Automation

      • Red Hat Ansible Automation Platform
      • Red Hat Ansible Lightspeed
    • Developer tools

      • Red Hat Trusted Software Supply Chain
      • Podman Desktop
      • Red Hat OpenShift Dev Spaces
    • Developer Sandbox

      Developer Sandbox
      Try Red Hat products and technologies without setup or configuration fees for 30 days with this shared Openshift and Kubernetes cluster.
    • Try at no cost
  • Technologies

    Featured

    • AI/ML
      AI/ML Icon
    • Linux
      Linux Icon
    • Kubernetes
      Cloud icon
    • Automation
      Automation Icon showing arrows moving in a circle around a gear
    • View All Technologies
    • Programming Languages & Frameworks

      • Java
      • Python
      • JavaScript
    • System Design & Architecture

      • Red Hat architecture and design patterns
      • Microservices
      • Event-Driven Architecture
      • Databases
    • Developer Productivity

      • Developer productivity
      • Developer Tools
      • GitOps
    • Secure Development & Architectures

      • Security
      • Secure coding
    • Platform Engineering

      • DevOps
      • DevSecOps
      • Ansible automation for applications and services
    • Automated Data Processing

      • AI/ML
      • Data Science
      • Apache Kafka on Kubernetes
      • View All Technologies
    • Start exploring in the Developer Sandbox for free

      sandbox graphic
      Try Red Hat's products and technologies without setup or configuration.
    • Try at no cost
  • Learn

    Featured

    • Kubernetes & Cloud Native
      Openshift icon
    • Linux
      Rhel icon
    • Automation
      Ansible cloud icon
    • Java
      Java icon
    • AI/ML
      AI/ML Icon
    • View All Learning Resources

    E-Books

    • GitOps Cookbook
    • Podman in Action
    • Kubernetes Operators
    • The Path to GitOps
    • View All E-books

    Cheat Sheets

    • Linux Commands
    • Bash Commands
    • Git
    • systemd Commands
    • View All Cheat Sheets

    Documentation

    • API Catalog
    • Product Documentation
    • Legacy Documentation
    • Red Hat Learning

      Learning image
      Boost your technical skills to expert-level with the help of interactive lessons offered by various Red Hat Learning programs.
    • Explore Red Hat Learning
  • Developer Sandbox

    Developer Sandbox

    • Access Red Hat’s products and technologies without setup or configuration, and start developing quicker than ever before with our new, no-cost sandbox environments.
    • Explore Developer Sandbox

    Featured Developer Sandbox activities

    • Get started with your Developer Sandbox
    • OpenShift virtualization and application modernization using the Developer Sandbox
    • Explore all Developer Sandbox activities

    Ready to start developing apps?

    • Try at no cost
  • Blog
  • Events
  • Videos

Creating a custom atomic scan plug-in

May 20, 2016
Brent Baude
Related topics:
Developer Tools
Related products:
Developer Tools

Share:

    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: June 13, 2024

    Recent Posts

    • Ollama or vLLM? How to choose the right LLM serving tool for your use case

    • How to build a Model-as-a-Service platform

    • How Quarkus works with OpenTelemetry on OpenShift

    • Our top 10 articles of 2025 (so far)

    • The benefits of auto-merging GitHub and GitLab repositories

    Red Hat Developers logo LinkedIn YouTube Twitter Facebook

    Products

    • Red Hat Enterprise Linux
    • Red Hat OpenShift
    • Red Hat Ansible Automation Platform

    Build

    • Developer Sandbox
    • Developer Tools
    • Interactive Tutorials
    • API Catalog

    Quicklinks

    • Learning Resources
    • E-books
    • Cheat Sheets
    • Blog
    • Events
    • Newsletter

    Communicate

    • About us
    • Contact sales
    • Find a partner
    • Report a website issue
    • Site Status Dashboard
    • Report a security problem

    RED HAT DEVELOPER

    Build here. Go anywhere.

    We serve the builders. The problem solvers who create careers with code.

    Join us if you’re a developer, software engineer, web designer, front-end designer, UX designer, computer scientist, architect, tester, product manager, project manager or team lead.

    Sign me up

    Red Hat legal and privacy links

    • About Red Hat
    • Jobs
    • Events
    • Locations
    • Contact Red Hat
    • Red Hat Blog
    • Inclusion at Red Hat
    • Cool Stuff Store
    • Red Hat Summit
    © 2025 Red Hat

    Red Hat legal and privacy links

    • Privacy statement
    • Terms of use
    • All policies and guidelines
    • Digital accessibility

    Report a website issue