shellex 1.0.0

data/.gitignore

@@ -0,0 +1,18 @@
+*.gem
+*.rbc
+.bundle
+.config
+.yardoc
+Gemfile.lock
+InstalledFiles
+_yardoc
+coverage
+doc/
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp
+.idea

data/Gemfile

@@ -0,0 +1,11 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in shellex.gemspec
+gemspec
+
+gem 'rake'
+gem 'popen4'
+
+group :test do
+  gem 'shoulda-context'
+end

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2013 Dima Sabanin
+
+MIT License
+
+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,102 @@
+# Shellex [![Build Status](https://secure.travis-ci.org/dsabanin/shellex.png)](http://travis-ci.org/dsabanin/shellex)
+
+Shellex allows you to run shell commands from your ruby scripts in a more robust and secure way than the built-in options.
+We had a security audit in http://beanstalkapp.com recently which showed many problems caused by shell injections. This code
+ is the result of our attempt to fix these issues once and for all.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+    gem 'shellex'
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install shellex
+
+## Usage
+
+Grabbing STDOUT output:
+
+```ruby
+stdout, stderr = shellex("echo hello, world!")
+# stdout => "hello, world!\n"
+# stderr => ""
+```
+
+Grabbing STDERR output:
+
+```ruby
+stdout, stderr = shellex("echo error here 1>&2")
+# stdout => ""
+# stderr => "error here\n"
+```
+
+Convenience methods:
+
+```ruby
+shellex("echo hello, world").to_s # => "hello, world\n"
+shellex("echo hello, world").stdout # => "hello, world\n"
+shellex("echo error here 1>&2").stderr # => "error here\n"
+```
+
+Providing STDIN input:
+
+```ruby
+shellex("cat -", :input => "hello").stdout # => "hello"
+```
+
+By default if you don't provide input we close the STDIN stream, but if you want you can leave it open:
+
+```ruby
+shellex("cat /dev/stdin", :close_stdin => false)
+```
+
+Timeouts (default timeout is set to 5 minutes):
+
+```ruby
+shellex("sleep 10", :timeout => 1) # raises ShellExecutionTimeout exception
+```
+
+Interpolation of arguments:
+
+```ruby
+# to_s gets called on all arguments
+shellex("echo ? ? ?", 1, "blah", :symbol)
+# executes: echo '1' 'blah' 'symbol'
+
+# ?& interpolates each array element separately
+shellex("? ?& ?", "echo", [1,2,3,4], "abc")
+# executes: 'echo' '1' '2' '3' '4' 'abc'
+
+# ?& requires array to be present in the respective position
+shellex("? ?& ?", "echo", 1) # raises ShellArgumentMissing
+
+# ?~ escapes question mark
+shellex("? ?~", "echo", "ello")
+# executes: 'echo' ?
+
+# ? by default will turn nil into empty string
+shellex("echo ?", nil)
+# executes: echo ''
+
+# ?? will skip the argument if it's nil
+shellex("echo ??", nil)
+# executes: echo
+
+# Shell injection protection
+shellex("echo ?", "'; rm -Rf /; '")
+# executes harmless: echo ''\''; rm -Rf /; '\'''
+```
+
+## Contributing
+
+1. Fork it
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create new Pull Request

data/Rakefile

@@ -0,0 +1,9 @@
+require "bundler/gem_tasks"
+require 'rake/testtask'
+
+Rake::TestTask.new(:test) do |test|
+  test.libs << 'test'
+  test.pattern = 'test/*_test.rb'
+end
+
+task :default => [:test]

data/lib/lib.iml

@@ -0,0 +1,12 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<module type="RUBY_MODULE" version="4">
+  <component name="NewModuleRootManager" inherit-compiler-output="true">
+    <exclude-output />
+    <content url="file://$MODULE_DIR$">
+      <sourceFolder url="file://$MODULE_DIR$" isTestSource="false" />
+    </content>
+    <orderEntry type="inheritedJdk" />
+    <orderEntry type="sourceFolder" forTests="false" />
+  </component>
+</module>
+

data/lib/shellex.rb

@@ -0,0 +1,144 @@
+require "shellex/version"
+require 'popen4'
+
+class ShellExecutionError < StandardError; end
+class ShellExecutionFailed < ShellExecutionError
+  attr_accessor :output_without_command
+end
+class ShellExecutionTimeout < ShellExecutionError; end
+class ShellArgumentMissing < ShellExecutionError; end
+
+module Kernel
+  SHELLEX_IO_BUFFER = 32*1024
+  DEFAULT_TIMEOUT = 5*60
+
+  def _shellex_retvalue(ret)
+    def ret.stdout; self[0] end
+    def ret.stderr; self[1] end
+    def ret.to_s; stdout end
+    def ret.to_str; stdout end
+    ret.freeze
+  end
+
+  def _shellex_extend_status(status)
+    def status.command=(cmd)
+      @command = cmd
+    end
+    def status.command
+      @command
+    end
+  end
+
+  def shellex(cmd, *args)
+    stdout, stderr, status = silent_shellex(cmd, *args)
+    if status.success?
+      ret = [stdout, stderr]
+      return _shellex_retvalue(ret)
+    else
+      exc = ShellExecutionFailed.new("#{status.command} (exit code: #{status.exitstatus})\nOutput: #{stderr}")
+      exc.output_without_command = stderr
+      raise exc
+    end
+  end
+
+  def silent_shellex(cmd, *args)
+    opts = {:timeout => DEFAULT_TIMEOUT, :close_stdin => true}
+    if args.last.is_a?(Hash)
+      opts = opts.merge(args.pop)
+    end
+
+    cmd = cmd.with_args(*args)
+    out, err, pid, status = '', '', nil, nil
+
+    begin
+      Timeout.timeout(opts[:timeout].to_i) do
+        status = Open4.open4(cmd) do |pid, stdin, stdout, stderr|
+          stdin.write(opts[:input]) if opts[:input]
+          stdin.close if opts[:close_stdin]
+
+          while tmp = stdout.read(SHELLEX_IO_BUFFER)
+            out << tmp
+          end
+
+          while tmp = stderr.read(SHELLEX_IO_BUFFER)
+            err << tmp
+          end
+        end
+      end
+    rescue Exception => e
+      if pid
+        Process.kill 9, pid
+        Process.wait pid
+      end
+
+      # Exceptions coming from popen4 are deserialized from forked process, so they are not caught by listing
+      # class name in rescue clause
+      case e.class.to_s
+        when /Timeout::Error/
+          raise ShellExecutionTimeout, "Timeout after #{opts[:timeout]} secs while running '#{cmd}'"
+        else
+          raise ShellExecutionError, e.message
+      end
+    end
+
+    _shellex_debug(cmd, err, opts, out)
+
+    _shellex_extend_status(status)
+    status.command = cmd
+
+    return out, err, status
+  end
+
+  def _shellex_debug(cmd, err, opts, out)
+    if defined?(Rails) and Rails.env.development?
+      Rails.logger.info { "Executed: #{cmd}\n STDIN: #{opts[:input].inspect} STDOUT: #{out.inspect}\nSTDERR: #{err.inspect}" }
+    end
+  end
+end
+
+class String
+  def with_args(*args)
+    escape = proc { |val| val.to_s._shellex_escape }
+    ignore_nil = proc { |val| escape.call(val) unless val.nil? }
+
+    gsub(/(\?\&|\?\?|\?\!|\?~|\?)/) do |match|
+      val = args.shift
+
+      case match
+        when "?~" # Escape question mark
+          "?"
+        when "?!" # Argument can't be nil
+          if val.nil?
+            raise ShellArgumentMissing, "Argument marked as required with ?! is nil"
+          else
+            escape.call(val)
+          end
+        when "??" # Argument will be omitted if nil
+          ignore_nil.call(val)
+        when "?" # Argument will be escaped even if nil
+          escape.call(val)
+        when "?&" # Argument has to be array and each element will be escaped or ommitted if nil
+          if val.is_a?(Array)
+            val.map(&ignore_nil).compact.join(" ")
+          else
+            raise ShellArgumentMissing, "If ?& is present in this position, #{val.inspect} should be an Array"
+          end
+      end
+    end.strip
+  end
+
+  def _shellex_escape
+    if self.empty? or self.strip == ""
+      return "''"
+    end
+    self.split(/'/, -1).map{|e| "'#{e}'"}.join("\\'")
+  end
+
+  def shellex(*args)
+    shellex(self, *args)
+  end
+
+  def silent_shellex(*args)
+    silent_shellex(self, *args)
+  end
+end

data/lib/shellex/version.rb

@@ -0,0 +1,3 @@
+module Shellex
+  VERSION = "1.0.0"
+end

data/shellex.gemspec

@@ -0,0 +1,23 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'shellex/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = "shellex"
+  spec.version       = Shellex::VERSION
+  spec.authors       = ["Dima Sabanin"]
+  spec.email         = ["sdmitry@gmail.com"]
+  spec.description   = %q{Shell execution made easy and secure}
+  spec.summary       = %q{Allows you to securely execute shell code with exceptions on errors and timeouts}
+  spec.homepage      = "https://github.com/dsabanin/shellex"
+  spec.license       = "MIT"
+
+  spec.files         = `git ls-files`.split($/)
+  spec.executables   = spec.files.grep(%r{^bin/}) { |f| File.basename(f) }
+  spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})
+  spec.require_paths = ["lib"]
+
+  spec.add_development_dependency "bundler", "~> 1.3"
+  spec.add_development_dependency "rake"
+end

data/test/shellex_test.rb

@@ -0,0 +1,142 @@
+require 'shellex'
+require 'test/unit'
+require 'shoulda/context'
+
+class ShellexTest < Test::Unit::TestCase
+
+  context "ShellEx" do
+
+    context "capturing" do
+      should "stdout capturing" do
+        stdout, stderr = shellex("echo stdout")
+        assert_equal "stdout\n", stdout
+        assert_equal "", stderr
+      end
+
+      should "stderr capturing" do
+        stdout, stderr = shellex("echo stderr 1>&2")
+        assert_equal "", stdout
+        assert_equal "stderr\n", stderr
+      end
+
+      should "stdout and stderr capturing" do
+        stdout, stderr = shellex("echo stdout; echo stderr 1>&2")
+        assert_equal "stdout\n", stdout
+        assert_equal "stderr\n", stderr
+      end
+    end
+
+    should "eat stdin input" do
+      stdout, stderr = shellex("cat -", :input => "hello")
+      assert_equal "hello", stdout
+    end
+
+    should "timeout" do
+      assert_raises(ShellExecutionTimeout) do
+        shellex("sleep 10", :timeout => 1)
+      end
+    end
+
+    should "timeout on blocking io" do
+      assert_raises(ShellExecutionTimeout) do
+        shellex("cat /dev/stdin", :timeout => 1, :close_stdin => false)
+      end
+    end
+
+    context "interpolation" do
+      should "interpolate and escape the args" do
+        real = "echo ? ? ?".with_args(1, "blah", :symbol)
+        assert_equal "echo '1' 'blah' 'symbol'", real
+      end
+
+      should "interpolate ?& as series of args" do
+        real = "? ?&".with_args("echo", [1,2,3,4])
+        assert_equal "'echo' '1' '2' '3' '4'", real
+      end
+
+      should "interpolate ?& as series of args in the middle" do
+        real = "? ?& ?".with_args("echo", [1,2,3,4], "abc")
+        assert_equal "'echo' '1' '2' '3' '4' 'abc'", real
+      end
+
+      should "raise error if array for ?& is not given" do
+        assert_raises(ShellArgumentMissing) do
+          "? ?& ?".with_args("echo", 1)
+        end
+      end
+
+      should "interpolate empty array to empty space" do
+        real = "? ?& ?".with_args("echo", [], "abc")
+        assert_equal "'echo'  'abc'", real
+      end
+
+      should "interpolate nil in array to empty space" do
+        real = "? ?& ?".with_args("echo", [1, nil, 3], "abc")
+        assert_equal "'echo' '1' '3' 'abc'", real
+      end
+
+      should "interpolate on shellex call" do
+        stdout, stderr = shellex("? ?", "echo", "stdout")
+        assert_equal "stdout\n", stdout
+      end
+
+      should "interpolate nil value as empty string with ?" do
+        real = "? ?".with_args("echo", nil)
+        assert_equal "'echo' ''", real
+
+        real = "? ?".with_args("echo", "blah")
+        assert_equal "'echo' 'blah'", real
+      end
+
+      should "ignore nil values with ??" do
+        real = "? ??".with_args("echo", nil)
+        assert_equal "'echo'", real
+
+        real = "? ??".with_args("echo", "blah")
+        assert_equal "'echo' 'blah'", real
+      end
+
+      should "raise on required arguments" do
+        assert_raises(ShellArgumentMissing) do
+          real = "? ?!".with_args("echo", nil)
+        end
+
+        real = "? ??".with_args("echo", "blah")
+        assert_equal "'echo' 'blah'", real
+      end
+
+      should "be able to escape the question mark" do
+        real = "? ?~".with_args("echo", "ello")
+        assert_equal "'echo' ?", real
+      end
+    end
+
+    context "error handling" do
+      should "raise error if exit value is not zero" do
+        assert_raises(ShellExecutionFailed) do
+          shellex("test a = b")
+        end
+      end
+
+      should "have silent version that eats errors" do
+        cmd = "echo ? 1>&2; test a = ?"
+        stdout, stderr, status = silent_shellex(cmd, "stderr", "b")
+        assert_equal "", stdout
+        assert stderr.include?("stderr"), "Got: #{stderr}"
+        assert_equal false, status.success?
+        assert_equal "echo 'stderr' 1>&2; test a = 'b'", status.command
+      end
+    end
+
+    context "should have singleton-array api" do
+      should "provide stdout/stderr methods" do
+        api = shellex("echo test")
+        assert_equal "test\n", api.stdout
+        assert_equal "test\n", api.to_s
+        assert_equal "test\n", api.to_str
+        assert_equal "", api.stderr
+        assert api.frozen?
+      end
+    end
+  end
+end

metadata

@@ -0,0 +1,103 @@
+--- !ruby/object:Gem::Specification 
+name: shellex
+version: !ruby/object:Gem::Version 
+  hash: 23
+  prerelease: 
+  segments: 
+  - 1
+  - 0
+  - 0
+  version: 1.0.0
+platform: ruby
+authors: 
+- Dima Sabanin
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2013-03-15 00:00:00 Z
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: bundler
+  prerelease: false
+  requirement: &id001 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ~>
+      - !ruby/object:Gem::Version 
+        hash: 9
+        segments: 
+        - 1
+        - 3
+        version: "1.3"
+  type: :development
+  version_requirements: *id001
+- !ruby/object:Gem::Dependency 
+  name: rake
+  prerelease: false
+  requirement: &id002 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        hash: 3
+        segments: 
+        - 0
+        version: "0"
+  type: :development
+  version_requirements: *id002
+description: Shell execution made easy and secure
+email: 
+- sdmitry@gmail.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: []
+
+files: 
+- .gitignore
+- Gemfile
+- LICENSE.txt
+- README.md
+- Rakefile
+- lib/lib.iml
+- lib/shellex.rb
+- lib/shellex/version.rb
+- shellex.gemspec
+- test/shellex_test.rb
+homepage: https://github.com/dsabanin/shellex
+licenses: 
+- MIT
+post_install_message: 
+rdoc_options: []
+
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
+      version: "0"
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
+      version: "0"
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.8.24
+signing_key: 
+specification_version: 3
+summary: Allows you to securely execute shell code with exceptions on errors and timeouts
+test_files: 
+- test/shellex_test.rb