police-dataflow 0.0.1

data/.document

@@ -0,0 +1,5 @@
+lib/**/*.rb
+bin/*
+- 
+features/**/*.feature
+LICENSE.txt

data/Gemfile

@@ -0,0 +1,10 @@
+source :rubygems
+
+group :development do
+  gem 'bundler', '>= 1.1.0'
+  gem 'jeweler', '>= 1.8.3'
+  gem 'minitest', '>= 2.11.2'
+  gem 'rdoc', '>= 3.12'
+  gem 'simplecov', '>= 0.6.1'
+  gem 'yard', '>= 0.7'
+end

data/Gemfile.lock

@@ -0,0 +1,31 @@
+GEM
+  remote: http://rubygems.org/
+  specs:
+    git (1.2.5)
+    jeweler (1.8.3)
+      bundler (~> 1.0)
+      git (>= 1.2.5)
+      rake
+      rdoc
+    json (1.6.6)
+    minitest (2.11.4)
+    multi_json (1.2.0)
+    rake (0.9.2.2)
+    rdoc (3.12)
+      json (~> 1.4)
+    simplecov (0.6.1)
+      multi_json (~> 1.0)
+      simplecov-html (~> 0.5.3)
+    simplecov-html (0.5.3)
+    yard (0.7.5)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  bundler (>= 1.1.0)
+  jeweler (>= 1.8.3)
+  minitest (>= 2.11.2)
+  rdoc (>= 3.12)
+  simplecov (>= 0.6.1)
+  yard (>= 0.7)

data/LICENSE.txt

@@ -0,0 +1,20 @@
+Copyright (c) 2012 Massachusetts Institute of Technology
+
+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.markdown

@@ -0,0 +1,9 @@
+# police-dataflow
+
+Pure Ruby implementation of data flow label propagation. 
+
+
+## Copyright
+
+Copyright (c) 2012 Massachusetts Institute of Technology. See LICENSE.txt for
+further details.

data/Rakefile

@@ -0,0 +1,38 @@
+# encoding: utf-8
+
+require 'rubygems'
+require 'bundler'
+begin
+  Bundler.setup(:default, :development)
+rescue Bundler::BundlerError => e
+  $stderr.puts e.message
+  $stderr.puts "Run `bundle install` to install missing gems"
+  exit e.status_code
+end
+require 'rake'
+
+require 'jeweler'
+Jeweler::Tasks.new do |gem|
+  # gem is a Gem::Specification... see http://docs.rubygems.org/read/chapter/20 for more options
+  gem.name = "police-dataflow"
+  gem.homepage = "http://github.com/csail/police"
+  gem.license = "MIT"
+  gem.summary = %Q{Data flow label propagation}
+  gem.description = %Q{Pure Ruby implementtion of data flow label propagation.}
+  gem.email = "victor@costan.us"
+  gem.authors = ["Victor Costan"]
+  # dependencies defined in Gemfile
+end
+Jeweler::RubygemsDotOrgTasks.new
+
+require 'rake/testtask'
+Rake::TestTask.new(:test) do |test|
+  test.libs << 'lib' << 'test'
+  test.pattern = 'test/**/*_test.rb'
+  test.verbose = true
+end
+
+task :default => :test
+
+require 'yard'
+YARD::Rake::YardocTask.new

data/VERSION

@@ -0,0 +1 @@
+0.0.1

data/lib/police-dataflow.rb

@@ -0,0 +1,2 @@
+# Allow require 'police-dataflow' instead of 'police/dataflow'
+require 'police/dataflow'

data/lib/police/dataflow.rb

@@ -0,0 +1,16 @@
+module Police
+
+# Data flow labels "track" data as it is processed in a complex system.
+module DataFlow
+end  # namespace Police::DataFlow
+
+end  # namespace Police
+
+
+require 'police/dataflow/core_extensions.rb'
+require 'police/dataflow/guarding.rb'
+require 'police/dataflow/label.rb'
+require 'police/dataflow/labeling.rb'
+require 'police/dataflow/proxies.rb'
+require 'police/dataflow/proxy_base.rb'
+require 'police/dataflow/proxying.rb'

data/lib/police/dataflow/core_extensions.rb

@@ -0,0 +1,12 @@
+# @private
+# The methods below are used by the Police::Dataflow implementation, and
+# should not be called directly.
+class Object
+  # Counterpart to the Police::DataFlow::ProxyBase#__police_labels__ attribute.
+  #
+  # @return [NilClass] nil, to help the Police::DataFlow implementation
+  #     distinguish between "real" objects and label-carrying proxies
+  def __police_labels__
+    nil
+  end
+end

data/lib/police/dataflow/guarding.rb

@@ -0,0 +1,16 @@
+module Police
+
+module DataFlow
+  # TODO(pwnall): spec
+  def self.guard
+    
+  end
+
+# Guarding logic.
+module Guarding
+  
+end  # namespace Police::DataFlow::Guarding
+  
+end  # namespace Police::DataFlow
+
+end  # namespace Police

data/lib/police/dataflow/label.rb

@@ -0,0 +1,86 @@
+module Police
+
+module DataFlow
+
+# Superclass for objects used as data flow labels.
+class Label
+  # True for labels that automatically propagate across operations.
+  #
+  # Labels that indicate privacy auto-flow. For example, an auto-generated
+  # message that contains a user's phone number is just as sensitive as the
+  # phone number.
+  # 
+  # Labels that indicate sanitization do not auto-flow. For example, a substring
+  # of an HTML-sanitized string is not necessarily HTML-sanitized.
+  #
+  # @return [Boolean] if true, the label will be automatically added to objects
+  #     whose value is likely to be derived from other labeled objects
+  def self.autoflow?
+    true
+  end
+  
+  # Label method changing the return value of a method in a labeled object.
+  #
+  # @param [Symbol] method_name the name of the method that will be decorated
+  #     by the label
+  # @return [Symbol, NilClass] the name of a label instance method that will
+  #     be given a chance to label the decorated method's return value
+  #
+  # @see Police::DataFlow::Label.sample_return_hook
+  def self.return_hook(method_name)
+    :sample_return_hook
+  end
+  
+  # Label method changing the values yielded by a method in a labeled object.
+  #
+  # @param [Symbol] method_name the name of the method that will be decorated
+  #     by the label
+  # @return [Symbol, NilClass] the name of a label instance method that will
+  #     be given a chance to label the values yielded by the decorated method
+  #     to its block
+  #
+  # @see Police::DataFlow::Label.sample_yield_args_hook
+  def self.yield_args_hook(method_name)
+    :sample_yield_args_hook
+  end
+  
+  # Hook that can label a decorated method's return value.
+  #
+  # @param [Object] value the decorated method's return value; if a method is
+  #     decorated by multiple labels, the value might be already labeled by
+  #     another label's return hook
+  # @param [Object] receiver the object that the decorated method was called on
+  # @param [Array] args the arguments passed to the decorated method
+  # @return [Object] either the un-modified value argument, or the return value
+  #     of calling Police::Dataflow.label on the value argument
+  def sample_return_hook(value, receiver, *args)
+    Police::DataFlow.label value, self
+  end
+
+  # Hook that can label the values that a decorated method yields to its block.
+  #
+  # @param [Object] receiver the object that the decorated method was called on
+  # @param [Array] yield_args the arguments yielded by the decorated method to
+  #     its block; the array's elements can be replaced with the return values
+  #     of calling Police::DataFlow.label on them; if a method is
+  #     decorated by multiple labels, the values might be already labeled by
+  #     another label's yield values hook
+  # @param [Array] args the arguments passed to the decorated method
+  def sample_yield_args_hook(receiver, yield_args, *args)
+    yield_args.map! { |arg| Police::DataFlow.label arg, self }
+  end
+
+  # An opportunity for a label to reject being attached to a piece of data.
+  #
+  # @param [Object] data the data that this label will be attached to
+  # @return [Boolean] true if this label can be used with the given piece of
+  #     data; if this method returns false, the labeling code will raise an
+  #     exception
+  def accepts?(data)
+    true
+  end
+end  # module Police::DataFlow::Label
+
+end  # namespace Police::DataFlow
+
+end  # namespace Police

data/lib/police/dataflow/labeling.rb

@@ -0,0 +1,71 @@
+module Police
+
+module DataFlow
+  # Attaches a label to a piece of data.
+  #
+  # @param [Object] data the data that will be labeled
+  # @param [Police::DataFlow::Label] label the label to be applied to the object
+  # @return [BasicObject] either the given piece of data, or a proxy that should
+  #     be used instead of it
+  def self.label(data, label)
+    label_set = data.__police_labels__
+    if label_set.nil?
+      proxied = data
+      label_set = {}
+      autoflow_set = {}
+    else
+      proxied = data.__police_proxied__
+      autoflow_set = data.__police_autoflows__
+    end
+    
+    if Police::DataFlow::Labeling.add_label_to_set label, label_set,
+                                                   autoflow_set
+      data = Police::DataFlow::Proxying.proxy proxied, label_set, autoflow_set
+      data
+    end
+    data
+  end
+  
+  # All the labels attached to a piece of data.
+  #
+  # @param [Object] data the data whose labels are queried
+  # @return [Array<Police::DataFlow::Label>] all the labels attached to the data
+  def self.labels(data)
+    return [] unless label_set = data.__police_labels__
+    return label_set.first.last.keys if label_set.length == 1
+    
+    labels = []
+    label_set.each { |label_key, label_hash| labels.concat label_hash.keys }
+    labels
+  end
+
+# Label algebra.
+module Labeling
+  # Adds a label to the set of labels held by an object's proxy.
+  #
+  # @param [Hash<Integer,Hash<Police::DataFlow::Label,Boolean>>] label_set the
+  #     set of all labels that will be held by the object's proxy
+  # @param [Hash<Integer,Hash<Police::DataFlow::Label,Boolean>>] autoflow_set
+  #     the set of labels whose autoflow? method returned true
+  # @return [Boolean] false if the set already had a label of the same type, so
+  #     the proxy holding the set can still be used; true if the set had to be
+  #     expanded, so a new proxy is needed
+  def self.add_label_to_set(label, label_set, autoflow_set)
+    label_class = label.class
+    label_key = label_class.__id__
+    if label_set.has_key? label_key
+      label_set[label_key][label] = true
+      # NOTE: autoflow_set uses use the same hash, so no work is necessary
+      return false
+    end
+    
+    label_entry = { label => true }
+    label_set[label_key] = label_entry
+    autoflow_set[label_key] = label_entry if label_class.autoflow?
+    true
+  end
+end  # namespace Police::DataFlow::Labeling
+  
+end  # namespace Police::DataFlow
+
+end  # namespace Police

data/lib/police/dataflow/proxies.rb

@@ -0,0 +1,51 @@
+module Police
+
+module DataFlow
+
+# Namespace for the auto-generated proxy classes.
+module Proxies
+  # A class whose instances proxy instances of a Ruby class.
+  #
+  # @param [Class] proxied_class the class whose instances will be proxied by
+  #     instances of the returned class
+  # @param [Hash<Integer,Hash<Police::DataFlow::Label,Boolean>>] label_set the
+  #     set of all labels that will be carried by the proxied object
+  # @return [Class] a Police::DataFlow::ProxyBase subclass that can proxy
+  #     instances of the given class
+  def self.for(proxied_class, label_set)
+    unless class_cache = @classes[proxied_class]
+      class_cache = {}
+      @classes[proxied_class] = class_cache
+    end
+     
+    cache_key = label_set.keys.sort!.freeze
+    return class_cache[cache_key] if class_cache.has_key? cache_key
+    
+    label_classes = label_set.map { |label_key, label_hash|
+      label_hash.first.first.class
+    }.sort_by!(&:__id__).freeze
+
+    proxy_class = Class.new Police::DataFlow::ProxyBase
+    proxy_class.__police_classes__ = label_classes
+    class_cache[cache_key] = proxy_class
+    proxy_class
+  end
+
+  # Clears the cache of proxy classes associated with Ruby classes.
+  #
+  # This method has a terrible impact on VM performance, and is only intended
+  # for testing the Police::DataFlow implementation.
+  #
+  # @return [Boolean] true
+  def self.clear_cache
+    @classes.clear
+    true
+  end
+
+  # Maps Ruby classes to auto-generated proxy classes.
+  @classes = {}
+end  # namespace Police::DataFlow::Proxies
+
+end  # namespace Police::DataFlow
+
+end  # namespace Police

data/lib/police/dataflow/proxy_base.rb

@@ -0,0 +1,132 @@
+module Police
+
+module DataFlow
+
+# Base class for labeled objects replacements.
+class ProxyBase < BasicObject
+  # The object being proxied by this object.
+  #
+  # @private
+  # Use the Police::DataFlow API instead of reading this attribute directly.
+  attr_reader :__police_proxied__
+  
+  # The Label instances attached to the proxied object.
+  #
+  # @private
+  # Use the Police::DataFlow API instead of reading this attribute directly.
+  attr_reader :__police_labels__
+  
+  # The subset of this object's labels whose autoflow? method returns true.
+  #
+  # @private
+  # This is an optimization used by the Police::DataFlow implementation. Do not
+  # read it directly.
+  attr_reader :__police_autoflows__
+  
+  # Creates a proxied object.
+  #
+  # @param [Object] proxied the object that will receive messages sent to the
+  #     newly created proxy
+  # @param [Class<Police::DataFlow::ProxyBase>] proxy_class the
+  #     Police::DataFlow::ProxyBase subclass being instantiated; Object
+  #     instances can call Object#class to get to their class, but BasicObject
+  #     instances don't have this luxury
+  # @param [Hash<Integer,Hash<Police::DataFlow::Label,Boolean>>] label_set the
+  #     set of all labels that will be held by the object's proxy
+  # @param [Hash<Integer,Hash<Police::DataFlow::Label,Boolean>>] autoflow_set
+  #     the set of labels whose autoflow? method returned true
+  def initialize(proxied, proxy_class, label_set, autoflow_set)
+    @__police_proxied__ = proxied
+    @__police_labels__ = label_set
+
+    # Holds the object's class, because Object#class is not available.
+    @__police_class__ = proxy_class
+
+    # Labels that flow automatically across method calls.
+    @__police_autoflows__ = autoflow_set
+  end
+
+  # Handles method calls to the proxied object.
+  #
+  # Whenever possible, proxy methods are created on-the-fly, so that future
+  # calls to the same method will be faster.
+  def method_missing(name, *args, &block)
+    # Build a fast path for future method calls, if possible.
+    respond_to_missing? name, true
+
+    if block
+      return_value = @__police_proxied__.__send__ name, *args do |*yield_args|
+        # Yielded values filtering.
+        @__police_labels__.each do |_, label_hash|
+          next unless hook = label_hash.first.first.class.yield_args_hook(name)
+          label_hash.each do |label, _|
+            block_args = label.__send__ hook, self, yield_args, *args
+          end
+        end
+        
+        yield_return = yield(*yield_args)
+        # TODO(pwnall): consider adding a yield value filter
+        next yield_return
+      end
+    else
+      return_value = @__police_proxied__.__send__ name, *args, &block
+    end
+    
+    # Return value filtering.
+    @__police_labels__.each do |_, label_hash|
+      next unless hook = label_hash.first.first.class.return_hook(name)
+      label_hash.each do |label, _|
+        return_value = label.__send__ hook, return_value, self, *args
+      end
+    end
+    return return_value
+  end
+  
+  # Called when Object#respond_to? returns false.
+  def respond_to_missing?(name, include_private)
+    return false unless @__police_proxied__.respond_to? name, include_private
+    
+    # A method on the proxied object doesn't have a corresponding proxy.
+    # Fix this by creating all possible proxies.
+    
+    # NOTE: this approach is cheaper than creating proxies one by one, because
+    #       it plays nice with method caches
+    
+    ::Police::DataFlow::Proxying.add_class_methods @__police_class__,
+                                                   @__police_proxied__.class
+    
+    # NOTE: we don't want to create unnecessary singleton classes
+    # target_methods = @__police_proxied__.singleton_methods true
+    # unless target_methods.empty?
+    #  ::Police::DataFlow::Proxying.add_singleton_methods self,
+    #      @__police_proxied__, target_methods
+    # end
+    
+    true
+  end
+  
+  # Ruby 1.9 throws scary warnings if proxies define object_id.
+  # In either case, it's probably best to have it match __id__.
+  alias object_id __id__
+  
+  # Remove the == and != implementations from BasicObject, so that we can proxy
+  # them. This is particularly important for String.
+  #
+  # NOTE: We don't remove equal?, because Object's documentation says that
+  #       BasicObject subclasses should really not override it. We also don't
+  #       remove instance_eval and instance_exec, so the code that gets executed
+  #       using them will still have its method calls proxied correctly.
+  undef ==, !=
+
+  class <<self
+    # The classes of the labels supported by the proxy class.
+    #
+    # @private
+    # This is a Police::DataFlow implementation detail. Do not read it directly.
+    attr_accessor :__police_classes__
+  end  
+end  # class Police::DataFlow::ProxyBase
+
+end  # namespace Police::DataFlow
+
+end  # namespace Police