hoosegow 1.2.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 08457775221dac7f850e7f3ba83e41661a45ae62
+  data.tar.gz: 64919e4a0404a832ff1cd700bb8b665af96fd63e
+SHA512:
+  metadata.gz: fe8880787a543fca141ec9c2f59df2ae778dc7d791709c7a9f39e304f2ea0f16800d79d3236c0e28f4feff3fb7afc3077c124c4a645be2206a46f4dc85d8e6d6
+  data.tar.gz: edda7d73693b4944a81dc1cbdbf699feb2ffba8507412fb12d0207188fcf74cead9732fd37cad938516eccdb007c2d24e513cfcb350bb915d23ed35eff63669b

data/Dockerfile

@@ -0,0 +1,46 @@
+# Ubuntu base image
+FROM ubuntu
+
+# Install rbenv deps
+RUN apt-get update
+RUN apt-get install -y build-essential zlib1g-dev libssl-dev openssl libreadline-dev sqlite3 libsqlite3-dev libxslt-dev libxml2-dev curl wget git-core
+
+# Install rbenv
+RUN git clone https://github.com/sstephenson/rbenv.git /.rbenv
+RUN echo 'export PATH="/.rbenv/bin:$PATH"' >> /etc/profile
+RUN echo 'export RBENV_ROOT="/.rbenv"'     >> /etc/profile
+RUN echo 'eval "$(rbenv init -)"'          >> /etc/profile
+RUN echo 'gem: --no-rdoc --no-ri'          >> /etc/gemrc
+
+# Install rbenv build plugin
+RUN mkdir -p /.rbenv/plugins
+RUN git clone https://github.com/sstephenson/ruby-build.git /.rbenv/plugins/ruby-build
+
+# Install specified ruby version
+RUN /bin/bash -l -c 'RUBY_CONFIGURE_OPTS="--disable-install-doc" rbenv install {{ruby_version}}'
+RUN /bin/bash -l -c 'rbenv global {{ruby_version}}'
+RUN /bin/bash -l -c 'gem install bundler'
+RUN /bin/bash -l -c 'rbenv rehash'
+
+# Create a user to run as.
+RUN adduser --no-create-home --disabled-password --gecos "" --shell /bin/false hoosegow
+
+###########################################################################################
+# Anything added after the ADD command will not be cached. Try to add changes above here. #
+###########################################################################################
+
+# Add this directory to /
+ADD . /hoosegow
+RUN chown -R hoosegow:hoosegow /hoosegow
+
+# Switch to limited user now.
+USER hoosegow
+
+# Run all commands in /hoosegow
+WORKDIR /hoosegow
+
+# Bundle hoosegow
+RUN /bin/bash -l -c 'BUNDLE_JOBS=4 bundle install --path .bundle --without development test'
+
+# Command to run when `docker run hoosegow`
+ENTRYPOINT /bin/bash -l -c bin/hoosegow

data/Gemfile

@@ -0,0 +1,9 @@
+source 'https://rubygems.org'
+
+gemspec
+
+# Load dependency Gemfile if present.
+inmate_gemfile = File.join(File.dirname(__FILE__), 'inmate', 'Gemfile')
+if File.exist? inmate_gemfile
+  eval(IO.read(inmate_gemfile), binding)
+end

data/LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2014 GitHub, Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,82 @@
+# Hoosegow
+
+Ephemeral Docker jails for running untrusted Ruby code.
+
+Hoosegow runs both in your code and in a Docker container. When you call a method on a Hoosegow instance, it proxies the method call to another instance of Hoosegow running inside a Docker container.
+
+# Security
+
+Hoosegow is intended to add a layer of security to projects that need to run code that is not fully trusted/audited. Because the untrusted code is running inside a Docker container, an attacker who manages to exploit a vulnerability in the code must also break out of the Docker container before gaining any access to the host system.
+
+This means that Hoosegow is only as strong as Docker. Docker employs Kernel namespaces, capabilities, and cgroups to contain processes running inside a container. This is not true Virtualization though, and a process running as root inside the container *can* compromise the host system. Any priviledge escalation bugs in the host Kernel could also be used to become root and compromise the host machine. Further hardening of the base Ubuntu image, along with tools like AppArmor or SE-Linux can improve the security posture of an application relying on Hoosegow/Docker.
+
+The following are some useful resources regarding the security of Docker:
+
+- The [Docker Security](https://docs.docker.com/articles/security/) article from Docker.io.
+- The [LXC, Docker, Security](http://www.slideshare.net/jpetazzo/linux-containers-lxc-docker-and-security) slides from Jérôme Petazzoni.
+- The series of Docker security articles from Daniel J. Walsh ([one](http://opensource.com/business/14/7/docker-security-selinux), [two](http://opensource.com/business/14/9/security-for-docker)). 
+
+#### Installing
+
+Gems are available from the [releases page](https://github.com/github/hoosegow/releases). Download a gem to
+your app's `vendor/cache` directory, and add this to your Gemfile:
+
+    gem "hoosegow"
+
+#### Defining Methods to Proxy
+
+You need to define the methods you want to have run in the Docker container. To do this, you need to create a `inmate.rb` file that defines a `Hoosegow::Inmate` module. Any methods on this module will be available on `Hoosegow` instances and will be proxied to the Docker container. Here is an example `inmate.rb` file:
+
+```ruby
+class Hoosegow
+  module Inmate
+    def reverse(input)
+      input.reverse
+    end
+  end
+end
+```
+
+The `inmate.rb` file should be in its own folder, with an optional `Gemfile` to specify dependencies. This directory will be copied to the Docker container at build time so your methods are available to be proxied to. You specify the location of the directory containing the `inmate.rb` file when instantiating a `Hoosegow` object:
+
+```ruby
+hoosegow = Hoosegow.new :inmate_dir => File.join(RAILS_ROOT, "hoosegow_deps")
+hoosegow.reverse "foobar"
+#=> "raboof"
+```
+
+#### Building the Docker Image
+
+Before you can start using Hoosegow, you need to build the Docker image that Hoosegow will proxy method calls to. This can be done in a rake task or bootstrap script:
+
+```ruby
+hoosegow = Hoosegow.new :inmate_dir => File.join(RAILS_ROOT, "hoosegow_deps")
+hoosegow.build_image
+hoosegow.image_name
+#=> "hoosegow:2f8f155e72828ddab9bd8bd0e355c47fb01a5323"
+```
+
+The image will need to be rebuilt with any changes to Hoosegow or the `inmate.rb` file. If the image is built ahead of time (by a rake task or bootstrap script), you can pass the name of the image to use when instantiating a Hoosegow instance:
+
+```ruby
+ENV['HOOSEGOW_IMAGE']
+#=> "hoosegow:2f8f155e72828ddab9bd8bd0e355c47fb01a5323"
+hoosegow = Hoosegow.new :inmate_dir => File.join(RAILS_ROOT, "hoosegow_deps")
+                        :image_name => ENV['HOOSEGOW_IMAGE']
+```
+
+#### Configuring the Connection to Docker
+
+By default Docker's API listens locally on a Unix socket. If you are running Docker with it's default configuration, you don't need to worry about configuring Hoosegow.
+
+**Configure Hoosegow to connect to a non-standard Unix socket.**
+
+```ruby
+Hoosegow.new :socket => '/path/to/socket'
+```
+
+**Configure Hoosegow to connect to a Docker daemon running on another computer.**
+
+```ruby
+Hoosegow.new :host => '192.168.1.192', :port => 4243
+```

data/Rakefile

@@ -0,0 +1,37 @@
+require_relative 'lib/hoosegow'
+
+require 'rspec/core/rake_task'
+
+begin
+  require_relative 'config'
+rescue LoadError
+  CONFIG = {}
+end
+
+inmate_dir = File.join(File.dirname(__FILE__), 'spec', 'test_inmate')
+CONFIG[:inmate_dir] = inmate_dir
+CONFIG[:image_name] = Hoosegow.new(CONFIG).image_name
+
+RSpec::Core::RakeTask.new(:spec)
+Rake::Task[:spec].prerequisites << :bootstrap_docker
+task :default => :spec
+
+def hoosegow
+  @hoosgow ||= Hoosegow.new CONFIG
+end
+
+desc "Benchmark render_reverse run in docker"
+task :benchmark => :bootstrap_docker do
+  10.times do |i|
+    sleep 0.5
+    start = Time.now
+    hoosegow.render_reverse "foobar"
+    puts "render_reverse run ##{i} took #{Time.now - start} seconds"
+  end
+  hoosegow.cleanup
+end
+
+desc "Building docker image."
+task :bootstrap_docker do
+  hoosegow.build_image unless hoosegow.image_exists?
+end

data/bin/hoosegow

@@ -0,0 +1,14 @@
+#!/usr/bin/env ruby
+# See docs/dispatch.md for more information.
+
+require_relative '../lib/hoosegow'
+
+real_stdout = $stdout.dup
+real_stdout.sync = true
+intercepted_stdout, intercepting_stdout = IO.pipe # returns reader,writer
+$stdout.reopen(intercepting_stdout)
+
+Hoosegow::Protocol::Inmate.run({
+  :stdout => real_stdout,
+  :intercepted => intercepted_stdout,
+})

data/docs/dispatch-seq.txt

@@ -0,0 +1,13 @@
+title Hoosegow method dispatch
+
+App->Hoosegow: do_work(args)
+Hoosegow->Docker: start and attach to instance
+Hoosegow->bin/hoosegow: stdin: msgpack(:do_work, args)
+bin/hoosegow->Inmate: send(:do_work, args)
+Inmate->bin/hoosegow: yield("message")
+bin/hoosegow->Hoosegow: stdout: msgpack(:yield, "message")
+Hoosegow->App: yield("message")
+Inmate->bin/hoosegow: return :ok
+bin/hoosegow->Hoosegow: stdout: msgpack(:return, "ok")
+Hoosegow->Docker: stop container
+Hoosegow->App: return "ok"

data/docs/dispatch.md

@@ -0,0 +1,53 @@
+# Hoosegow dispatch
+
+Calling a method on an inmate involves passing information through several layers. The participants in the flow are:
+
+* **App** - your app's code, outside of the container.
+* **Hoosegow** - an instance of the `Hoosegow` class, created outside the container.
+* **Docker** - the docker daemon.
+* **`bin/hoosegow`** - the entry point in the docker container.
+* **Inmate** - an instance of the `Hoosegow` class, inside the container, that has included `Hoosegow::Inmate` (your sandboxed code).
+
+![](dispatch.png)
+
+## Interfaces
+
+### Hoosegow (outside the container)
+
+The outer instance of `Hoosegow` receives a normal call from the application.
+
+It encodes the method name and arguments and provides that to an attach call to Docker.
+
+It reads the Docker response as it comes in. It demultiplexes the docker output into `STDERR` and `STDOUT`. `STDOUT` is further decoded into the actual `STDOUT` from the Inmate, `yield` calls, and the method result.
+
+### Docker
+
+Docker receives an HTTP POST with a body, and returns an HTTP response with a body. The HTTP request body is treated as `STDIN`, and the response body contains `STDOUT` and `STDERR`.
+
+See [documentation for attach](http://docs.docker.io/en/latest/reference/api/docker_remote_api_v1.7/#attach-to-a-container).
+
+### bin/hoosegow
+
+`bin/hoosegow` is started by Docker when the container starts. It is the entry point of the container.
+
+It decodes `STDIN` and calls the requested method on the Inmate.
+
+`STDOUT` is reopened so that we can encode a few things on it:
+
+* normal stdout from the inmate or child processes spawned by the inmate
+* data that is `yield`ed
+* the return value from the inmate.
+
+`STDERR` is left as-is.
+
+### Inmate
+
+The Inmate is an object that includes the `Hoosegow::Inmate` module.
+
+Input to the Inmate is a method name and arguments.
+
+Output from the Inmate can be spread across several things:
+
+* `STDOUT` and `STDERR` - e.g. puts calls 
+* `yield` to a block
+* the result of the method

data/hoosegow.gemspec

@@ -0,0 +1,32 @@
+require 'rake'
+
+Gem::Specification.new do |s|
+  s.name        = 'hoosegow'
+  s.version     = '1.2.0'
+  s.summary     = "A Docker jail for ruby code"
+  s.description = "Hoosegow provides an RPC layer on top of Docker containers so that you can isolate unsafe parts of your application."
+  s.authors     = ["Ben Toews", "Matt Burke"]
+  s.email       = 'mastahyeti@github.com'
+  s.licenses    = ["MIT"]
+  globs = %w[
+    README.md
+    LICENSE
+    Gemfile
+    Rakefile
+    Dockerfile
+    hoosegow.gemspec
+    docs/**/*
+    lib/**/*
+    script/**/*
+    spec/**/*
+  ]
+  s.files       = Dir[*globs]
+  s.executables = ['hoosegow']
+  s.homepage    = 'https://github.com/github/hoosegow'
+  s.required_ruby_version = ">= 1.9.3"
+  s.add_development_dependency 'rake',       '>= 10.3.2', '~> 10.3'
+  s.add_development_dependency 'rspec',      '>= 2.14.1', '~> 2.14'
+  s.add_runtime_dependency     'msgpack',    '>= 0.5.6',  '~> 0.5'
+  s.add_runtime_dependency     'yajl-ruby',  '>= 1.1.0',  '~> 1.1'
+  s.add_runtime_dependency     'docker-api', '~> 1.13.6'
+end

data/lib/hoosegow.rb

@@ -0,0 +1,160 @@
+require_relative 'hoosegow/docker'
+require_relative 'hoosegow/exceptions'
+require_relative 'hoosegow/image_bundle'
+require_relative 'hoosegow/protocol'
+
+class Hoosegow
+  # Public: Initialize a Hoosegow instance.
+  #
+  # options -
+  #           :no_proxy     - Development mode. Use this if you don't want to
+  #                           setup Docker on your development instance, but
+  #                           still need to test rendering files. This is how
+  #                           Hoosegow runs inside the Docker container.
+  #           :inmate_dir   - Dependency directory to be coppied to the hoosegow
+  #                           image. This should include a file called
+  #                          `inmate.rb` that defines a Hoosegow::Inmate module.
+  #           :image_name   - The name of the Docker image to use. If this isn't
+  #                           specified, we will infer the image name from the
+  #                           hash the files present.
+  #           :ruby_version - The Ruby version to install in the Docker
+  #                           container (Default RUBY_VERSION).
+  #           :socket       - Path to Unix socket where Docker daemon is
+  #                           running. (optional. defaults to
+  #                           "/var/run/docker.sock")
+  #           :host         - IP or hostname where Docker daemon is running.
+  #                           Don't set this if Docker is listening locally on a
+  #                           Unix socket.
+  #           :port         - TCP port where Docker daemon is running. Don't set
+  #                           this if Docker is listening locally on a Unix
+  #                           socket.
+  def initialize(options = {})
+    options         = options.dup
+    @no_proxy       = options.delete(:no_proxy)
+    @inmate_dir     = options.delete(:inmate_dir) || '/hoosegow/inmate'
+    @image_name     = options.delete(:image_name)
+    @ruby_version   = options.delete(:ruby_version) || RUBY_VERSION
+    @docker_options = options
+    load_inmate_methods
+
+    # Don't want to have to require these in the container.
+    unless no_proxy?
+      require 'tmpdir'
+      require 'fileutils'
+      require 'open3'
+      require 'digest'
+    end
+  end
+
+  # Public: The thing that defines which files go into the docker image tarball.
+  def image_bundle
+    @image_bundle ||=
+      Hoosegow::ImageBundle.new.tap do |image|
+        image.add(File.expand_path('../../*', __FILE__), :ignore_hidden => true)
+        image.add(File.join(@inmate_dir, "*"), :prefix => 'inmate')
+        image.ruby_version = @ruby_version
+      end
+  end
+
+  # Public: Proxies method call to instance running in a Docker container.
+  #
+  # name  - The method to call in the Docker instance.
+  # args  - Arguments that should be passed to the Docker instance method.
+  # block - A block that can be yielded to.
+  #
+  # See docs/dispatch.md for more information.
+  #
+  # Returns the return value from the Docker instance method.
+  def proxy_send(name, args, &block)
+    proxy = Hoosegow::Protocol::Proxy.new(
+      :stdout => $stdout,
+      :stderr => $stderr,
+      :yield  => block
+    )
+    encoded_send = proxy.encode_send(name, args)
+    docker.run_container(image_name, encoded_send) do |type, msg|
+      proxy.receive(type, msg)
+    end
+
+    proxy.return_value
+  end
+
+  # Public: Load inmate methods from #{inmate_dir}/inmate.rb and hook them up
+  # to proxied to the Docker container. If we are in the container, the methods
+  # are loaded and setup to be called directly.
+  #
+  # Returns nothing. Raises InmateImportError if there is a problem.
+  def load_inmate_methods
+    inmate_file = File.join @inmate_dir, 'inmate.rb'
+
+    unless File.exist?(inmate_file)
+      raise Hoosegow::InmateImportError, "inmate file doesn't exist"
+    end
+
+    require inmate_file
+
+    unless Hoosegow.const_defined?(:Inmate) && Hoosegow::Inmate.is_a?(Module)
+      raise Hoosegow::InmateImportError,
+        "inmate file doesn't define Hoosegow::Inmate"
+    end
+
+    if no_proxy?
+      self.extend Hoosegow::Inmate
+    else
+      inmate_methods = Hoosegow::Inmate.instance_methods
+      inmate_methods.each do |name|
+        define_singleton_method name do |*args, &block|
+          proxy_send name, args, &block
+        end
+      end
+    end
+  end
+
+  # Public: We create/start a container after every run to reduce latency. This
+  # needs to be called before the process ends to cleanup that remaining
+  # container.
+  #
+  # Returns nothing.
+  def cleanup
+    docker.stop_container
+    docker.delete_container
+  end
+
+  # Check if the Docker image exists.
+  #
+  # Returns true/false.
+  def image_exists?
+    docker.image_exist? image_name
+  end
+
+  # Public: Build a Docker image from the Dockerfile in the root directory of
+  # the gem.
+  #
+  # Returns build output text. Raises ImageBuildError if there is a problem.
+  def build_image(&block)
+    docker.build_image image_name, image_bundle.tarball, &block
+  end
+
+  # Private: The name of the docker image to use. If not specified manually,
+  # this will be infered from the hash of the tarball.
+  #
+  # Returns string image name.
+  def image_name
+    @image_name || image_bundle.image_name
+  end
+
+  private
+  # Private: Get or create a Docker instance.
+  #
+  # Returns an Docker instance.
+  def docker
+    @docker ||= Docker.new @docker_options
+  end
+
+  # Returns true if we are in the Docker instance or are in develpment mode.
+  #
+  # Returns true/false.
+  def no_proxy?
+    !!@no_proxy
+  end
+end