Class: Police::DataFlow::Label

Inherits:
Object
  • Object
show all
Defined in:
lib/police/dataflow/label.rb

Overview

Superclass for objects used as data flow labels.

Class Method Summary collapse

Instance Method Summary collapse

Class Method Details

.return_hook(method_name) ⇒ Symbol, NilClass

Label method changing the return value of a method in a labeled object.

Parameters:

  • method_name (Symbol) —

    the name of the method that will be decorated by the label

Returns:

  • (Symbol, NilClass) —

    the name of a label instance method that will be given a chance to label the decorated method’s return value; the return value for a given method name should always be the same

See Also:

  • sample_return_hook


35
36
37
 
# File 'lib/police/dataflow/label.rb', line 35

def self.return_hook(method_name)
  :sample_return_hook
end

.sticky? ⇒ Boolean

True for labels that automatically propagate across operations.

This method’s return value is used for methods where the label does not provide a hook. When present, hooks are responsible for label propagation.

Labels that indicate privacy should be sticky. 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 should not be sticky. For example, a substring of an HTML-sanitized string is not necessarily HTML-sanitized.

Returns:

  • (Boolean) —

    if true, the label will be automatically added to objects whose value is likely to be derived from other labeled objects; the return value for a given method name should always be the same



22
23
24
 
# File 'lib/police/dataflow/label.rb', line 22

def self.sticky?
  true
end

.yield_args_hook(method_name) ⇒ Symbol, NilClass

Label method changing the values yielded by a method in a labeled object.

Parameters:

  • method_name (Symbol) —

    the name of the method that will be decorated by the label

Returns:

  • (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 Also:

  • sample_yield_args_hook


48
49
50
 
# File 'lib/police/dataflow/label.rb', line 48

def self.yield_args_hook(method_name)
  :sample_yield_args_hook
end

Instance Method Details

#accepts?(data) ⇒ Boolean

An opportunity for a label to reject being attached to a piece of data.

Parameters:

  • data (Object) —

    the data that this label will be attached to

Returns:

  • (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



84
85
86
 
# File 'lib/police/dataflow/label.rb', line 84

def accepts?(data)
  true
end

#sample_return_hook(value, receiver, *args) ⇒ Object

Hook that can label a decorated method’s return value.

Parameters:

  • value (Object) —

    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

  • receiver (Object) —

    the object that the decorated method was called on

  • args (Array) —

    the arguments passed to the decorated method

Returns:

  • (Object) —

    either the un-modified value argument, or the return value of calling Police::DataFlow.label on the value argument



61
62
63
 
# File 'lib/police/dataflow/label.rb', line 61

def sample_return_hook(value, receiver, *args)
  Police::DataFlow.label value, self
end

#sample_yield_args_hook(receiver, yield_args, *args) ⇒ Object

Hook that can label the values that a decorated method yields to its block.

Parameters:

  • receiver (Object) —

    the object that the decorated method was called on

  • yield_args (Array) —

    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

  • args (Array) —

    the arguments passed to the decorated method



74
75
76
 
# File 'lib/police/dataflow/label.rb', line 74

def sample_yield_args_hook(receiver, yield_args, *args)
  yield_args.map! { |arg| Police::DataFlow.label arg, self }
end