jQAssistant Docker Plugin

Table of Contents

• Overview
• Scan Docker Registry
  • Maven
  • Scanner Properties
  • Self-Signed Certificates
• Example Queries
• Known Limitations
• Changelog
  • 2.0.0
  • 1.11.0
  • 1.10.0
  • 1.9.0
  • 1.8.2
  • 1.8.1
  • 1.8.0

Overview

The jQAssistant Docker plugin provides a scanner for Docker registries gathering information about:

• Repositories

• Tags

• Manifests and their configurations

• Layers (Blobs)

The scanner uses the Docker Registry HTTP API V2 as described here.

Incremental scans are supported, i.e. new or updated tags will be detected.

Scan Docker Registry

Maven

The plugin can be enabled in the configuration file .jqassistant.yml:

.jqassistant.yml

jqassistant:
  plugins:
    - group-id: org.jqassistant.plugins
      artifact-id: jqassistant-docker-plugin
      version: 2.0.0
  scan:
    include:
      urls:
        - docker:registry::http://my-docker-registry:5000
    properties:
      docker.repository.include: "*"
      # docker.repository.exclude: "foo/*"
      # docker.repository.updateExistingTags: true

Afterwards a scan can be triggered and the embedded server started:

Maven

mvn jqassistant:scan
mvn jqassistant:server

Command Line

bin/jqassistant.sh scan
bin/jqassistant.sh server

Scanner Properties

Table 1. Properties for the Docker Registry Scanner

Property	Description	Default
docker.repository.include	Pattern of repositories and tags to include, e.g. foo/*	*
docker.repository.exclude	Pattern of repositories and tags to exclude, e.g. bar/*
docker.repository.updateExistingTags	If true then already scanned tags will be checked for updated manifests (slows down incremental scan)	false

Self-Signed Certificates

If the Docker registry uses HTTPS with a self-signed certificate the latter must be imported into the keystore of the Java Runtime Environment:

$JAVA_HOME/bin/keytool -import -alias DOCKER -file docker.crt -keystore $JAVA_HOME/lib/security/cacerts

Tip	The certificate can be exported directly from a web browser (e.g. as DER encoded-binary X509), the default passwort of the JRE keystore is changeit.

Example Queries

After starting the embedded server the Neo4j browser is available under the URL http://localhost:7474 and allows executing queries:

All registry urls and contained repositories.

MATCH
  (registry:Docker:Registry)-[:CONTAINS_REPOSITORY]->(repository:Docker:Repository)
RETURN
  registry.url, collect(repository.name) AS repositories

All tags for repository centos.

MATCH
  (repository:Docker:Repository{name:'centos'})-[:CONTAINS_TAG]->(tag:Docker:Tag)
RETURN
  tag.name

Manifest, config, labels and image for repository centos with the tag latest.

MATCH
  (repository:Docker:Repository{name:'centos'})-[:CONTAINS_TAG]->(tag:Docker:Tag{name:'latest'}),
  (tag)-[:HAS_MANIFEST]->(manifest:Docker:Manifest)-[:HAS_CONFIG]->(config:Docker:Config)
OPTIONAL MATCH
  (config)-[:HAS_LABEL]->(label:Docker:Label)
OPTIONAL MATCH
  (config)-[:FOR_IMAGE]->(image:Docker:Image)
RETURN
  manifest, config, label, image

Layers for repository centos with tag latest.

MATCH
  (repository:Docker:Repository{name:'centos'})-[:CONTAINS_TAG]->(tag:Docker:Tag{name:'latest'}),
  (tag)-[:HAS_MANIFEST]->(manifest:Docker:Manifest),
  (manifest:Docker:Manifest)-[:DECLARES_LAYER]->(layer:Docker:Layer)-[:WITH_BLOB]->(blob:Docker:Blob)
RETURN
  layer.index, blob.digest, blob.size
ORDER BY
  layer.index

Aggregated blob size per repository

MATCH
  (repository:Docker:Repository)-[:CONTAINS_TAG]->(tag:Docker:Tag),
  (tag)-[:HAS_MANIFEST]->(:Docker:Manifest)-[:DECLARES_LAYER]->(layer:Docker:Layer)-[:WITH_BLOB]->(blob:Docker:Blob)
RETURN
  repository.name AS repository, sum(blob.size)/(1024*1024) AS repositorySizeMB
ORDER BY
  repositorySizeMB DESC

Known Limitations

• Authentication is not (yet) supported

Changelog

2.0.0

• upgraded to jQAssistant 2.0.0

• changed Maven coordinates to org.jqassistant.plugin:jqassistant-docker-plugin

1.11.0

• upgraded to jQAssistant 1.11.0

• added scanner property docker.repository.updateExistingTags to enable updates of existing tags

• added chain of manifests for updated tags (:Tag)-[:HAS_MANIFEST]→(:Manifest)-[:HAS_PREVIOUS_MANIFEST*]→(:Manifest)

• fixed NPEs when scanning a tag without valid manifest or layer references

1.10.0

• upgraded to jQAssistant 1.10.0

1.9.0

• upgraded to jQAssistant 1.9.0

1.8.2

• introduced Layer nodes, i.e. (:Manifest)-[:DECLARES_LAYER]→(:Layer)-[:WITH_BLOB]→(:Blob) replaces (:Manifest)-[:DECLARES_LAYER]→(:Blob)

1.8.1

• manage blobs per registry instead of repository, i.e. (:Registry)-[:CONTAINS_BLOB]→(:Blob) replaces (:Repository)-[:CONTAINS_BLOB]→(:Blob)

1.8.0

• Initial release