klar analyzer
GitLab Analyzer for Docker Containers.
This analyzer is a wrapper around clair, a vulnerability static analysis for docker containers, utilizing klar to analyze images stored in a private or public Docker registry for security vulnerabilities.
Technical Documentation
See the Process Flow documentation for a technical overview of the Container Scanning components and walkthrough of the Container Scanning process.
Environment Variables
See the Available variables section in the GitLab Container Scanning docs.
Due to this analyzer's deprecation, explicit user opt-in is required by setting the IGNORE_DEPRECATION_ERROR
environment variable to any value. When absent, the analyzer aborts on start up.
Development
Build image
$ ./script/build image
Running the analyzer locally
See the Running the standalone Container Scanning Tool section in the GitLab Container Scanning docs.
Tests
The integration tests depend on some background services in order to complete successfully.
To start the background services:
$ ./script/server start
To stop the background services:
$ ./script/server stop
To run the unit tests:
$ ./script/test unit
To run the integration tests:
$ ./script/test integration
To run a specific integration test:
$ ./script/test integration spec/integration/rhel_spec.rb
To run the docker image analysis tests:
$ IMAGE_NAME=registry.gitlab.com/gitlab-org/security-products/analyzers/klar:latest ./script/test image
To run the project linters:
$ ./script/test lint
To run all the tests:
$ ./script/test
How to update the upstream Scanner
- Check for the latest versions of
clair
andklar
at https://github.com/coreos/clair/tags and https://github.com/optiopay/klar/tags - Compare with the values of
SCANNER_VERSION
andKLAR_EXECUTABLE_VERSION
in the Dockerfile - If an update is available, create a branch and bump the version in CHANGELOG.md
- Edit the Dockerfile and change the default values for the following Docker build arguments:
- If updating the
CLAIR_VERSION
variable, also make sure to update the container-scanner/clair/config.yaml.template file to match the latest version of the config.yaml.sample from the clair repository, since the format of this file may change between versions. You'll also need to ensure that thePOSTGRES-VULNERABILITIES-DB-URL
placeholder variable is inserted into thehost
field of thedatabase
block in the newconfig.yaml.template
file, for example:clair: database: type: pgsql options: source: POSTGRES-VULNERABILITIES-DB-CONNECTION-STRING
- Create a merge request which will automatically build and tag a new analyzer image using the following form:
registry.gitlab.com/gitlab-org/security-products/analyzers/klar/tmp:af864bd61230d3d694eb01d6205b268b4ad63ac0
where the tag is theSHA
of the most recent commit - Create a new branch in the container-scanning test project and do the following:
- Modify the container_scanning section of .gitlab-ci.yml to reference the new analyzer image:
container_scanning: allow_failure: false # the following is the only line you should need to add here image: registry.gitlab.com/gitlab-org/security-products/analyzers/klar/tmp:af864bd61230d3d694eb01d6205b268b4ad63ac0 variables: GIT_STRATEGY: fetch CLAIR_DB_IMAGE_TAG: "2019-09-04" artifacts: paths: [gl-container-scanning-report.json]
- Trigger the pipeline for the above branch in the
container-scanning test project
and make sure it passes
- Modify the container_scanning section of .gitlab-ci.yml to reference the new analyzer image:
- Merge the request created in step
5.
and follow the release process to publish this update.
Versioning and release process
With the initial release of the Klar analyzer in 12.3
, the associated vendored template was using a 12-3-stable
docker image tag. This has been removed and starting with GitLab 12.4
, it follows the usual release process as any other analyzer and doesn't need to be released as an x-y-stable
docker image tag.
Please check the common Versioning and release process documentation.
Contributing
Contributions are welcome, see CONTRIBUTING.md
for more details.
License
This code is distributed under the GitLab Enterprise Edition (EE) license, see the LICENSE file.