moby-derp 0.1.0

data/README.md

@@ -0,0 +1,231 @@
+This tool is designed to securely manage a group of related containers, known
+colloquially as a ["pod"](https://kubernetes.io/docs/concepts/workloads/pods/pod/),
+under the Moby container management system.
+
+It has no aspirations to be a fully-fledged multi-host container orchestation system;
+instead, it is simply a means to create and maintain a pod of containers.
+
+The most common use-case for `moby-derp` is to allow unprivileged users to
+define a pod, and then allow those users to execute `moby-derp` as a privileged
+user via `sudo`.  Since this removes the need for random users to have direct
+control over the moby daemon, a lot of potential [privilege escalation
+attacks](https://fosterelli.co/privilege-escalation-via-docker.html)
+facilitated by moby's security model are thwarted.
+
+
+# Installation
+
+It's a gem:
+
+    gem install moby-derp
+
+If you're the sturdy type that likes to run from git:
+
+    rake install
+
+Or, if you've eschewed the convenience of Rubygems entirely, then you
+presumably know what to do already.
+
+
+# Usage
+
+The main interface for `moby-derp` is the command-line tool of the same name.
+It takes as its sole argument a YAML file containing a whole pile of information
+about the pod and how you want the containers within it to be run.  A very simple
+example file might look like this:
+
+    publish:
+      - 80:80
+    containers:
+      nginx:
+        image: 'nginx:latest'
+        mounts:
+          - source: nginx
+            target: /etc/nginx
+          - source: content
+            target: /var/www
+      content_puller:
+        image: 'example/content_puller'
+        mounts:
+          - source: content
+            target: /puller
+
+For full details on exactly what can be done using the pod configuration file,
+please see [`example.yml`](example.yml), which is a heavily-commented example
+of every possible configuration option that can be set.
+
+Once you have a pod config, saved in, say, `my-pod.yml`, you can tell `moby-derp`
+to run it:
+
+    moby-derp ./my-pod.yml
+
+Often, however, you won't have the ability to contact the moby daemon directly,
+so you'll run `moby-derp` via `sudo`:
+
+    sudo moby-derp ./my-pod.yml
+
+Where this comes in handy is that `sudo` can be configured to restrict the
+set of commands that a given user is allowed to run.  So, for instance, if the
+user who wants to run this pod is named `bob` on the system, I can put this
+in my `/etc/sudoers`:
+
+    bob ALL=(root) NOPASSWD: /usr/local/bin/moby-derp */my-pod.yml
+
+Then `bob` (and *only* `bob`) can run
+
+    sudo moby-derp ./my-pod.yml
+
+The name of the pod is taken from the name of the file, with any extension
+removed.  This is used as the prefix for the name of all containers in the pod.
+
+
+## System Configuration
+
+Some aspects of `moby-derp`'s operation are security-sensitive, and thus shouldn't
+be able to be modified by the ordinary user.  There is a
+system-wide configuration file for this purpose, by default located at
+`/etc/moby-derp.yml`.
+
+Its structure is quite simple.  A full example looks like this:
+
+    mount_root: '/srv/docker'
+    port_whitelist:
+      80: web-server
+      443: web-server
+      25: mail-server
+      1337: bobblehead
+
+The keys are:
+
+* **`mount_root`**: the directory on disk where all mounts for all pods will
+  be stored.  For security, the filesystem on which this location resides
+  should really be mounted `nosuid` and, if you can swing it, even `noexec`.
+  The directory specified by this option must already exist.
+
+* **`port_whitelist`**: a map of port numbers and the pod which should be
+  allowed to map them.  Any port which is not listed here cannot be explicitly
+  mapped by a pod, and only the pod named in the mapping can publish on the
+  specified port.
+
+If you wish to modify the location of the `moby-derp` system-wide configuration
+file, you can do so by setting the `MOBY_DERP_SYSTEM_CONFIG_FILE` environment
+variable.  Note, however, that it is a terrible idea to let ordinary users control
+that environment variable, so if you want to set it, please write a small
+wrapper script, like this:
+
+    #!/bin/sh
+
+    set -e
+
+    MOBY_DERP_SYSTEM_CONFIG_FILE=/opt/srv/etc/moby-derp/moby-derp.yaml
+
+    exec /usr/local/bin/moby-derp "$@"
+
+You can also set other relevant environment variables, such as `DOCKER_HOST`,
+in a like manner, if required.
+
+
+## Running `moby-derp` as a non-root user
+
+If you are properly cautious, it is a fine idea to not allow `moby-derp` itself
+root access to the system.  This is possible, although it comes with a few
+caveats:
+
+* The `sudoers` config needs to be adjusted appropriately, to specify the
+  user that you want to run `moby-derp` as;
+
+* The system-wide configuration file needs to be readable by whatever user
+  you run `moby-derp` as;
+
+* When running `moby-derp`, the user to run it as needs to be specified on
+  the command line, like so:
+
+        sudo -u moby-derper moby-derp ./my-pod.yml
+
+* The user that runs `moby-derp` must have access to the Docker control socket;
+  by default that means making that user a member of the `docker` group;
+
+* The user that runs `moby-derp` must have write access to the `mount_root`
+  directory, so it can create pod mount roots.
+
+
+# Security
+
+This section discusses the security model and guarantees of `moby-derp`.  It
+isn't necessary to simply use `moby-derp` in most circumstances.
+
+The fundamental principle of `moby-derp` is that users are given control over
+a certain portion of the container and filesystem namespace, by virtue of their
+ability to run `moby-derp` with a specific filename -- and nothing more.  The
+containers that a user can modify, and the portions of the filesystem that they
+can write files to, is strictly limited by the tool.
+
+
+## Container namespace
+
+All containers associated with a pod are named for the filename that is passed
+to `moby-derp`.  This means that, yes, different users need to use different
+filenames.  The benefit of this is that the `sudo` configuration becomes a lot
+easier to audit -- the pod name is right there.
+
+This means that no matter a user does, they cannot have any effect on any
+container which is not named for the pod they're manipulating.  There are also
+safety valves around `moby-derp`-managed containers being labelled as such, so
+that in the event that someone does inadvertently name a container in such a
+way that it can be manipulated by another user via `moby-derp`, it should still
+be safe from tampering.
+
+
+## Filesystem
+
+All references to the host side of mounts within the pod are made relative to
+the pod mount root, which is a subdirectory under the directory specified
+under the `mount_root` system configuration named for the pod.  As one would
+expect, attempts to use absolute paths, or parent directory references (via
+`..`) will not be looked upon kindly.
+
+To prevent attacks around modifying file permissions in the container and then
+using that on the host to escalate privileges, it is *STRONGLY* recommended
+that the filesystem which holds the `mount_root` be mounted `nosuid`, and even
+`noexec` if that isn't going to get in the way of your use-case.  You
+can also use the `userns-remap` feature if that is compatible with your use
+of Moby.
+
+
+## Network ports
+
+By default, `moby-derp` will not allow containers to publish to specific ports
+on the host.  The expectation is that network traffic will, for the most part,
+rely on direct connection to containers, using either host-based proxies,
+overlay networks, or new-fangled technologies like IPv6.  This prevents
+misbehaving pods from capturing ports intended for use by other pods.  Pods can
+still publish to ephemeral ports (using the `:containerPort` syntax, or
+`publish_all: true`) if they wish.
+
+If a pod *does* need to bind to a specific host port, then that pod/port pair
+should be whitelisted in the system configuration file.
+
+
+# Contributing
+
+See [`CONTRIBUTING.md`](CONTRIBUTING.md).
+
+
+# Licence
+
+Unless otherwise stated, everything in this repo is covered by the following
+copyright notice:
+
+    Copyright (C) 2019  Matt Palmer <matt@hezmatt.org>
+
+    This program is free software: you can redistribute it and/or modify it
+    under the terms of the GNU General Public License version 3, as
+    published by the Free Software Foundation.
+
+    This program is distributed in the hope that it will be useful,
+    but WITHOUT ANY WARRANTY; without even the implied warranty of
+    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+    GNU General Public License for more details.
+
+    You should have received a copy of the GNU General Public License
+    along with this program.  If not, see <http://www.gnu.org/licenses/>.

data/bin/moby-derp

@@ -0,0 +1,56 @@
+#!/usr/bin/env ruby
+
+require "moby_derp/system_config"
+require "moby_derp/pod_config"
+require "moby_derp/pod"
+
+require "docker-api"
+
+if ARGV.length != 1
+	$stderr.puts "No config file specified"
+	exit 1
+end
+
+logger = Logger.new($stdout)
+logger.formatter = ->(s, t, p, m) { "#{m}\n" }
+
+case ENV["MOBY_DERP_LOG_LEVEL"]
+when /\Adebug|info|warn|error\z/i
+  logger.level = Logger.const_get(ENV["MOBY_DERP_LOG_LEVEL"].upcase.to_sym)
+when /\Atrace\z/i
+  logger.level = Logger::DEBUG
+  require "tracer"
+  Tracer.add_filter { |_e, _f, _l, _id, _b, klass, *_| klass.to_s =~ /MobyDerp/ }
+  Tracer.on
+else
+  logger.level = Logger::INFO
+end
+
+begin
+  system_config_file = ENV["MOBY_DERP_SYSTEM_CONFIG_FILE"] || "/etc/moby-derp.conf"
+  system_config = MobyDerp::SystemConfig.new(system_config_file, Docker.info, logger)
+rescue MobyDerp::ConfigurationError => ex
+  $stderr.puts "There was an error reading the system config file #{system_config_file}: #{ex.message}"
+  exit 1
+rescue Excon::Error::Socket
+  $stderr.puts "Could not connect to the Moby server.  Is it running?"
+  exit 1
+end
+
+begin
+  pod_config = MobyDerp::PodConfig.new(ARGV.first, system_config)
+rescue MobyDerp::ConfigurationError => ex
+  $stderr.puts "There was an error reading the pod config file #{ARGV.first}: #{ex.message}"
+  exit 1
+end
+
+pod = MobyDerp::Pod.new(pod_config)
+
+begin
+  pod.run
+rescue MobyDerp::Error => ex
+  $stderr.puts "There was an error derping #{pod.name}: #{ex.message}"
+  exit 1
+end
+
+exit 0

data/example.yml

@@ -0,0 +1,297 @@
+# This is an example pod specification file for moby-derp.  It contains all
+# the possible configuration options, with comments describing their use.
+#
+# The name of a pod spec file is important, because the file name is used as
+# the name of the pod to manage, with any extension removed.  Because of the
+# limitations on container names imposed by Moby, this file name must, thus,
+# start with a alphanumeric character, and consist entirely of alphanumeric
+# characters, underscores, and hyphens.
+#
+
+# SECTION 1: CONTAINERS
+#
+# This is really what we're all here for, so let's get straight into it.
+#
+containers:
+  # The containers section contains a map of container names to the
+  # configuration parameters of that container.  Each container's name
+  # must consist entirely of alphanumeric characters, underscores, and
+  # hyphens.
+  #
+  flingle:
+    # The most important parameter for a container -- and, in fact,
+    # the *only* mandatory one -- is the container **image**.  The
+    # value given here must either be a symbolic image reference
+    # (name[:tag][@digest]) or a full image ID, including the digest
+    # identifier (`sha256:xyzzy123`).
+    #
+    image: 'moby-derp/flingle:latest'
+
+    # By default, if a symbolic image spec is provided in the `image` option,
+    # `moby-derp` will pull that image and recreate the container if the image
+    # ID has changed from what is currently running.  If, for some reason, you
+    # do *not* want this behaviour for a specific container, set this option to
+    # `false`.
+    #
+    # Note that, in all cases, if the image ID underlying a symbolic
+    # image spec changes in the local daemon's image store, the container will
+    # be restarted.
+    #
+    update_image: false
+
+    # Many moby images require a command, or at least command-line
+    # options, in order to run correctly.  To do this, set this
+    # key to whatever you need to pass.
+    #
+    # You can specify the command as a string, or as an array of strings if you
+    # want to avoid a layer or two of shell quoting.
+    #
+    command: '--foo=bar --wombat'
+
+    # The 12-factor app concept says that all configuration should be passed
+    # via the environment.  If that is your bag, then this section will make
+    # you very happy.
+    #
+    environment:
+      # The environment is specified as a map of variable name to variable
+      # values.  For passing big strings, you may want to get familiar with
+      # YAML's many string quoting and escaping modes.
+      #
+      APP_ENV: production
+      # Embedding your private key like this isn't necessarily a particularly
+      # good idea, but as an example of where you might need multiline strings,
+      # it works very well.
+      #
+      PRIVATE_KEY: |
+        -----BEGIN PRIVATE KEY-----
+        AAAAsd...
+        -----END PRIVATE KEY-----
+
+    # Persisting data past the lifetime of a particular container is the job
+    # of mounts.  Here you can specify filesystem locations on the host
+    # (relative to the pod's mount root) and where they should be
+    # mounted in the container.
+    #
+    # The list of mounts is an array of hashes, each of which specifies
+    # one mount.
+    #
+    mounts:
+        # The `source` parameter is a *relative* path (relative to the pod's
+        # mount root) on the host's filesystem.  Typically it will be a
+        # single descriptive word, but you can delve into subdirectories if
+        # you so choose.
+        #
+      - source: app
+        # The `target` is an absolute path within the container, where the
+        # associated host directory should be mounted.
+        #
+        target: /app
+
+      - source: static-assets
+        target: /app/public
+
+        # By default, mounts are read-write -- that is, if a process in the
+        # container has the relevant permissions, files in the mount can
+        # be modified, created, and deleted.  If you absolutely, positively
+        # want to make sure that can't happen, set `readonly: true`, and we'll
+        # tell Moby to make it so.
+        #
+        readonly: true
+
+    # Sometimes you need to add a label to a specific container.
+    # This is how you do that.
+    #
+    labels:
+      # It's very simple: `labelname: labelvalue`.
+      #
+      somelabel: 'Some mighty value'
+
+    # Mark the container's *root* filesystem as read-only.  Not *typically*
+    # a good idea.
+    #
+    readonly: true
+
+    # Specify the signal that should be sent to the container in order to
+    # cause it to stop gracefully.  Can be specified as a number, or a
+    # string with or without the leading `SIG`.
+    #
+    stop_signal: SIGQUIT
+
+    # How long, in seconds, to wait for the container to gracefully stop
+    # before whacking it with a `SIGKILL`.
+    #
+    stop_timeout: 42
+
+    # Adjust the container's restart policy.
+    #
+    restart: on-failure:42
+
+    # Here you can place limits on your containers, to prevent them
+    # accidentally blowing up the world.  Note that, in keeping with
+    # moby-derp's philosophy of limited privilege, you can only reduce
+    # the limits on a container, not raise them above what you would
+    # get by default (a bit like ulimits for non-root users).
+    #
+    limits:
+      # How many CPUs' worth of CPU time to allow this container to
+      # use.
+      #
+      cpus: 1.75
+
+      # A relative "share" of CPU time, calculated as a ratio of the
+      # total CPU shares granted to all cgroups.  The default of 1024
+      # is the maximum you can set.
+      #
+      cpu-shares: 72
+
+      # Set memory and swap limits.
+      #
+      # These two settings have complicated inter-relationships.  You
+      # definitely want to refer to
+      # https://docs.docker.com/config/containers/resource_constraints/#--memory-swap-details
+      # before using these.  You may also want to look at
+      # https://docs.docker.com/install/linux/linux-postinstall/#your-kernel-does-not-support-cgroup-swap-limit-capabilities
+      #
+      memory: 1G
+      memory-swap: 42M
+
+      # The "soft limit" for memory usage -- if your container's memory
+      # usage is above this limit, and the overall system is running low on
+      # memory, this container will be pressured to reduce its memory
+      # usage.
+      #
+      memory-reservation: 100M
+
+      # Increase a container's propensity to have its processes whacked by
+      # the OOM killer, if such a thing becomes necessary.  The value must
+      # be in the range 0 to 1000.
+      #
+      oom-score-adj: 42
+
+      # Limit the number of processes this container is allowed to create.
+      #
+      pids: 65535
+
+      # The amount of shared memory the container is allowed to use.
+      #
+      shm-size: 42G
+
+      # Set ulimits.
+      #
+      # All of the below settings are related to ulimits, which are the
+      # old-school, but still surprisingly effective, version of resource
+      # limits, from before we had cgroups.  All of the values take the
+      # form `<soft limit>[:<hard limit>]`, and if `<hard limit>` is not
+      # provided, it is set equal to the specified `<soft limit>`.  The
+      # soft limit must be less than or equal to the hard limit.
+      #
+      # See `getrlimit`(2) for what each limit means, as well as
+      # https://docs.docker.com/engine/reference/commandline/#set-ulimits-in-container---ulimit
+      # for Moby-specific restrictions and caveats.  As an additional
+      # undocumented caveat, if you want to set no limit for a resource,
+      # specify the string "unlimited".
+      #
+      # No value, for hard *or* soft limits, can be set higher than the
+      # hard limits for the `dockerd` process, although you won't know
+      # that you've broken the limits until `moby-derp` tries to start the
+      # container and the wheels fall off.
+      #
+      ulimit-core: 1:2
+      ulimit-cpu: 3:4
+      ulimit-data: 5:6
+      ulimit-fsize: 7:8
+      ulimit-memlock: 9:10
+      ulimit-msgqueue: 11:12
+      ulimit-nofile: 13:14
+      ulimit-rttime: 15:16
+      ulimit-stack: 17:18
+
+# SECTION 2: POD-LEVEL CONFIGURATION
+#
+# The remainder of the configuration items in this file correspond to settings
+# which apply to the pod -- either defaults for all containers in the pod, or
+# else settings which only apply to the "root" container in the pod (the container
+# which holds the networking, IPC, and PID namespaces).
+
+# Set a custom hostname for the container.
+#
+# The default is `<podname>-<host hostname>`, which works surprisingly well
+# in a majority of cases.  It's certainly less wild than the Moby default
+# of the short container ID.
+#
+hostname: bobtown
+
+# Common environment which will apply to all containers.
+#
+# These environment variables will be set for all containers, including the
+# pod "root" container.  Individual containers can override the value for an
+# environment variable, by setting their own value, but they *cannot* cause
+# an environment variable to be unset.
+#
+common_environment:
+  # As is the case for container-level environment variables, each key/value
+  # pair in the map is one environment variable name to value mapping.
+  #
+  AWESOME: yes
+
+# Common labels which will apply to all containers.
+#
+# These labels will be applied to every container in the pod, including the
+# pod "root" container.  Like common environment variables, an individual
+# container can override the value of a common label, but cannot cause the
+# label to be unset entirely.
+#
+common_labels:
+  mah_pod: is on fire
+
+# Labels that *only* apply to the "root" container of the pod.
+#
+# Some labels, often those associated with a container's network config
+# (like service discovery), should only be applied to the pod's "root"
+# container.  Those labels should be defined here.
+#
+root_labels:
+  service: over here
+
+# Common mount definitions that should apply to all containers.
+#
+# If you have a mount that every container in the pod should have access
+# to, you really don't want to have to specify it every time.  Instead,
+# you can put them here.  The format is the same as the per-container
+# `mounts` option.
+#
+common_mounts:
+  - source: app
+    target: /app
+  - source: static-assets
+    target: /app/public
+    readonly: true
+
+# A list of ports in the pod to expose.
+#
+# Marking a port as "exposed" interacts with Moby's "publish all" option,
+# as well as with service advertisement systems.
+#
+expose:
+  - 80
+  - 443
+  - 1337
+
+# A list of port publishing specifications.
+#
+# If you wish to use Moby's port forward/proxying mechanisms, you do that by
+# "publishing" the port(s) you want to use.  Note that, to prevent errant pods
+# from capturing ports they're not supposed to, by default pods can only publish
+# to ephemeral ports (no `hostPort` specification).  If a particular pod
+# *should* be able to publish a specific host port, it needs to be whitelisted
+# in the system-wide configuration (see the `port_whitelist` documentation
+# in the `moby-derp` README).
+#
+publish:
+  - :80
+  - :1234-1237
+
+# If you have a burning desire to have all exposed ports automatically published
+# to (not-so-)randomly chosen ephemeral ports, you can set this option to `true`.
+#
+publish_all: true

data/lib/freedom_patches/docker/image.rb

@@ -0,0 +1,23 @@
+module Docker
+	class Image
+		# https://github.com/docker/distribution/blob/master/reference/reference.go
+		# as at 2019-04-23
+		DIGEST_HEX                 = /[0-9a-fA-F]{32,}/
+		DIGEST_ALGORITHM_COMPONENT = /[A-Za-z][A-Za-z0-9]*/
+		DIGEST_ALGORITHM_SEPARATOR = /[+._-]/
+		DIGEST_ALGORITHM           = /#{DIGEST_ALGORITHM_COMPONENT}(#{DIGEST_ALGORITHM_SEPARATOR}#{DIGEST_ALGORITHM_COMPONENT})*/
+		DIGEST                     = /#{DIGEST_ALGORITHM}:#{DIGEST_HEX}/
+
+		TAG = /[\w][\w.-]{0,127}/
+
+		SEPARATOR        = /[_.]|__|[-]*/
+		ALPHANUMERIC     = /[a-z0-9]+/
+		PATH_COMPONENT   = /#{ALPHANUMERIC}(#{SEPARATOR}#{ALPHANUMERIC})*/
+		PORT_NUMBER      = /\d+/
+		DOMAIN_COMPONENT = /([a-zA-Z0-9]|[a-zA-Z0-9][a-zA-Z0-9-]*[a-zA-Z0-9])/
+		DOMAIN           = /#{DOMAIN_COMPONENT}(\.#{DOMAIN_COMPONENT})*(:#{PORT_NUMBER})?/
+		NAME             = /(#{DOMAIN}\/)?#{PATH_COMPONENT}(\/#{PATH_COMPONENT})*/
+		IMAGE_REFERENCE  = /\A#{NAME}(:#{TAG})?(@#{DIGEST})?\z/
+	end
+end
+

data/lib/moby_derp/config_file.rb

@@ -0,0 +1,33 @@
+require_relative "./error"
+require_relative "./logging_helpers"
+
+require "safe_yaml"
+
+module MobyDerp
+	class ConfigFile
+		include LoggingHelpers
+
+		attr_reader :logger
+
+		def initialize(filename)
+			begin
+				@logger.debug(logloc) { "Reading configuration file #{filename}" }
+				@config = SafeYAML.load(File.read(filename))
+			rescue Errno::ENOENT
+				raise ConfigurationError,
+				      "file does not exist"
+			rescue Errno::EPERM
+				raise ConfigurationError,
+				      "cannot read file"
+			rescue Psych::SyntaxError => ex
+				raise ConfigurationError,
+				      "invalid YAML syntax: #{ex.message}"
+			end
+
+			unless @config.is_a?(Hash)
+				raise ConfigurationError,
+				      "invalid file contents -- must be a map"
+			end
+		end
+	end
+end