A framework for Static Analysis of Docker container images
Go Other
Permalink
Failed to load latest commit information.
cmd/collector Removed docker mflag dependency Oct 17, 2016
config Removed docker mflag dependency Oct 17, 2016
data Output a record with blank package info if packages cannot be determi… Jul 2, 2015
docker bugfixes. Sep 18, 2015
docs New flags for setting registry request rate limits. Aug 10, 2016
except extended errorwarn test cases. Oct 7, 2015
fsutil Improved image removal, and error logging. Sep 30, 2015
resources Added ListUsers May 13, 2015
.gitattributes Added .gitattributes to make linguist ignore python modules. May 21, 2015
LICENSE adding license May 8, 2015
README.md Update README.md Jul 21, 2015
distro.go Recognize ubuntu yakkety Aug 9, 2016
distro_test.go Support for registry v2 token auth required for Docker Hub, GCR, etc. Feb 4, 2016
dockerRemote.go Updated logging pkg. Common name prefix for scan containers. Aug 4, 2016
dockerRemote_test.go Single http.Client for all docker daemon accesses Jul 28, 2016
filewriter.go Bugfix for v2 schema 1 images Jul 21, 2016
imagedata.go New flags for setting registry request rate limits. Aug 10, 2016
imagedata_test.go Single http.Client for all docker daemon accesses Jul 28, 2016
metadata.go Record registry in image metadata Aug 9, 2016
metadata_test.go Single http.Client for all docker daemon accesses Jul 28, 2016
registry.go New flags for setting registry request rate limits. Aug 10, 2016
registry_test.go New flags for setting registry request rate limits. Aug 10, 2016
registryauth.go Removed docker mflag dependency Oct 17, 2016
registryauth_test.go Single http.Client for all docker daemon accesses Jul 28, 2016
runscripts.go Removed docker mflag dependency Oct 17, 2016
runscripts_test.go Single http.Client for all docker daemon accesses Jul 28, 2016
script.go Improved image removal, and error logging. Sep 30, 2015
writer.go New --registryproto option. Jun 11, 2015
writer_test.go Record registry in image metadata Aug 9, 2016

README.md

Banyan Collector: A framework to peek inside containers

Have you wondered what your container images really contain? If they have the very packages that are susceptible to all kinds of attacks? Or, if they have the configuration you expect when they are run? Banyan Collector provides a powerful, extensible framework to answer all these questions and more.

Banyan Collector is a light-weight, easy to use, and modular system that allows you to launch containers from a registry, run arbitrary scripts inside them, and gather useful information. This framework can be used to statically analyze images for several purposes including:

  • Collect specific information from all images (e.g., packages installed)
  • Enforce policies (e.g., no unauthorized user accounts, etc.)
  • Validate invariants (e.g., nginx.conf is present in the right directory, etc.)
  • and so on...

Getting started

The collector can be run in one of two modes: (a) as a standalone executable (b) in a container. The main requirement is to run the collector on a Docker Host (machine that has the Docker Daemon running). If you want to collect data from a private registry make sure you are logged into it (sudo docker login REGISTRY)

(a) To run it as a standalone executable, you need go in your environment (https://golang.org/doc/install). Once go is installed, just run the following on a Docker Host:

$ go get -u github.com/banyanops/collector/...
$ cd <COLLECTOR_SOURCE_DIR>; sudo COLLECTOR_DIR=$PWD $GOPATH/bin/collector <REGISTRY> <REPO>

where REGISTRY is either a private registry (e.g., http://reg.myorg.com) or Docker Hub (index.docker.io), and REPO is a repository for which you'd like to collect data. For a private registry (with search enabled), if no REPO is specified, data is collected from all the repositories. Collector also supports the Google Container Registry (*.gcr.io), quay.io, and collecting from local images instead of pulling from a registry (by specifying "local.host" as the REGISTRY).

(b) To run the collector in a container, please follow instructions on Docker Hub.

More generally, collector can be configured using several options (e.g., registry poll interval, remove images threshold, secure registry settings, etc.):

$ sudo collector [options] REGISTRY [REPO1 REPO2 ...]

For a list of all the options run:

$ collector -h

Why not just use shell scripts?

Shell scripts are great for quickly getting specific information from images. However, as we add more complexity, it becomes hard to write scripts that are easy to maintain, quickly extensible and portable to different environments.

For example, the complexity in managing registry connections, keeping track of repo/tag changes, cleaning up stale images, supporting arbitrary policies, etc. is too much to handle using simple scripts. Furthermore, packaging the collector in a container provides a portable framework that is not dependent on any particular host configuration, and can seamlessly run anywhere.

Tests

The go tests rely on write access to the Docker UNIX socket /var/run/docker.sock. One approach is to add the user to the "docker" group to enable write access to the socket. Alternatively, the tests can be run as "root", for example using "sudo", but this requires the root user to share the Go development environment ($GOPATH, etc.).

Another requirement to run the tests is to set environment variables $DOCKER_USER and $DOCKER_PASSWORD to the user's Docker Hub login credentials. Additionally, the tests emit a warning if $COLLECTOR_DIR is not set (but the warning can be safely ignored).

Once the environment has been correctly setup, go tests can be run using the standard command:

$ go test

More information

More details about Collector operation/architecture, etc. are available under docs.

For further details about how one might use this in an enterprise, please check out Banyan. This SAAS service offers deeper analysis of your data and provides a dashboard showing which of your images are compliant to your policies (e.g., which of your images have security vulnerabilities, etc.) along with real-time updates and email notifications.

Get involved

Collector is under active development. Fork the project and submit pull requests, or file issues or tweet us @banyanops.

License

Banyan Collector is distributed under Apache 2.0 License. More details in LICENSE.