Merge pull request #469 from marcandre/safety_first

Add `Psych.safe_load_file`. Tweak doc to provide `safe_` examples.

4 files changed, 47 insertions, 5 deletions

diff --git a/README.md b/README.md
index 0fc68d9..405e955 100644
--- a/README.md
+++ b/README.md
@@ -12,8 +12,8 @@ serialize and de-serialize most Ruby objects to and from the YAML format.
 ## Examples
 
 ```ruby
-# Load YAML in to a Ruby object
-Psych.load('--- foo') # => 'foo'
+# Safely load YAML in to a Ruby object
+Psych.safe_load('--- foo') # => 'foo'
 
 # Emit YAML from a Ruby object
 Psych.dump("foo")     # => "--- foo\n...\n"
diff --git a/lib/psych.rb b/lib/psych.rb
index b09866a..a5de756 100644
--- a/lib/psych.rb
+++ b/lib/psych.rb
@@ -74,12 +74,15 @@ require 'psych/class_loader'
 #
 # ==== Reading from a string
 #
-#   Psych.load("--- a")             # => 'a'
-#   Psych.load("---\n - a\n - b")   # => ['a', 'b']
+#   Psych.safe_load("--- a")             # => 'a'
+#   Psych.safe_load("---\n - a\n - b")   # => ['a', 'b']
+#   # From a trusted string:
+#   Psych.load("--- !ruby/range\nbegin: 0\nend: 42\nexcl: false\n") # => 0..42
 #
 # ==== Reading from a file
 #
-#   Psych.load_file("database.yml")
+#   Psych.safe_load_file("data.yml", permitted_classes: [Date])
+#   Psych.load_file("trusted_database.yml")
 #
 # ==== Exception handling
 #
@@ -571,12 +574,27 @@ module Psych
   # Load the document contained in +filename+.  Returns the yaml contained in
   # +filename+ as a Ruby object, or if the file is empty, it returns
   # the specified +fallback+ return value, which defaults to +false+.
+  #
+  # NOTE: This method *should not* be used to parse untrusted documents, such as
+  # YAML documents that are supplied via user input.  Instead, please use the
+  # safe_load_file method.
   def self.load_file filename, **kwargs
     File.open(filename, 'r:bom|utf-8') { |f|
       self.load f, filename: filename, **kwargs
     }
   end
 
+  ###
+  # Safely loads the document contained in +filename+.  Returns the yaml contained in
+  # +filename+ as a Ruby object, or if the file is empty, it returns
+  # the specified +fallback+ return value, which defaults to +false+.
+  # See safe_load for options.
+  def self.safe_load_file filename, **kwargs
+    File.open(filename, 'r:bom|utf-8') { |f|
+      self.safe_load f, filename: filename, **kwargs
+    }
+  end
+
   # :stopdoc:
   @domain_types = {}
   def self.add_domain_type domain, type_tag, &block
diff --git a/test/psych/test_exception.rb b/test/psych/test_exception.rb
index e355c26..78601d0 100644
--- a/test/psych/test_exception.rb
+++ b/test/psych/test_exception.rb
@@ -118,6 +118,18 @@ module Psych
       }
     end
 
+    def test_safe_load_file_exception
+      Tempfile.create(['loadfile', 'yml']) {|t|
+        t.binmode
+        t.write '--- `'
+        t.close
+        ex = assert_raises(Psych::SyntaxError) do
+          Psych.safe_load_file t.path
+        end
+        assert_equal t.path, ex.file
+      }
+    end
+
     def test_psych_parse_takes_file
       ex = assert_raises(Psych::SyntaxError) do
         Psych.parse '--- `'
diff --git a/test/psych/test_psych.rb b/test/psych/test_psych.rb
index 7219e83..30612de 100644
--- a/test/psych/test_psych.rb
+++ b/test/psych/test_psych.rb
@@ -319,6 +319,18 @@ class TestPsych < Psych::TestCase
     }
   end
 
+  def test_safe_load_file_with_permitted_classe
+    Tempfile.create(['false', 'yml']) {|t|
+      t.binmode
+      t.write("--- !ruby/range\nbegin: 0\nend: 42\nexcl: false\n")
+      t.close
+      assert_equal 0..42, Psych.safe_load_file(t.path, permitted_classes: [Range])
+      assert_raises(Psych::DisallowedClass) {
+        Psych.safe_load_file(t.path)
+      }
+    }
+  end
+
   def test_parse_file
     Tempfile.create(['yikes', 'yml']) {|t|
       t.binmode