Class: Contrast::Agent::Reporting::FindingEvent

Inherits:
ReportableHash show all
Defined in:
lib/contrast/agent/reporting/reporting_events/finding_event.rb

Overview

This is the new FindingEvent class which will include all the needed information for the new reporting system to relay this information in the Finding/Trace messages. These FindingEvents are used by TeamServer to construct the vulnerability information for the assess feature. They represent the operation the application underwent that transformed data during the dataflow.

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Methods inherited from ReportableHash

#event_json, #valid?

Methods included from Components::Logger::InstanceMethods

#cef_logger, #logger

Constructor Details

#initialize(event_data = nil, source_type = nil, source_name = nil) ⇒ Contrast::Agent::Reporting::FindingEvent

Creates new FindingEvent.

Parameters:

  • event_data (Contrast::Agent::Assess::Events::EventData) (defaults to: nil)
  • source_type (String, nil) (defaults to: nil) —

    the type of this source, from the source_node, or a KEY_TYPE if invoked for a map,

  • source_name (String, nil) (defaults to: nil) —

    the name of this source, i.e. the key used to accessed if from a map or nil if a type like,



99
100
101
102
103
104
105
106
107
 
# File 'lib/contrast/agent/reporting/reporting_events/finding_event.rb', line 99

def initialize event_data = nil, source_type = nil, source_name = nil
  @event_sources = []
  @stack = []
  @time = Contrast::Utils::Timer.now_ms
  @thread = Thread.current.object_id.to_s
  @event_id = Contrast::Agent::Reporting::FindingEvent.next_atomic_id
  initialize_routine(event_data, source_type, source_name)
  super()
end

Instance Attribute Details

#action ⇒ Symbol (readonly)

Returns what the event did; CREATION, A2O, A2P, A2A, A2R, O2A, O2O, O2P, O2R, P2A, P2O, P2P, P2R, TAG, TRIGGER.

Returns:

  • (Symbol) —

    what the event did; CREATION, A2O, A2P, A2A, A2R, O2A, O2O, O2P, O2R, P2A, P2O, P2P, P2R, TAG, TRIGGER.



31
32
33
 
# File 'lib/contrast/agent/reporting/reporting_events/finding_event.rb', line 31

def action
  @action
end

#args ⇒ Array<Contrast::Agent::Assess::ContrastObject, nil> (readonly)

Returns the safe representation of the Arguments with which the method was invoked.

Returns:



36
37
38
 
# File 'lib/contrast/agent/reporting/reporting_events/finding_event.rb', line 36

def args
  @args
end

#code ⇒ nil (readonly)

Returns unused.

Returns:

  • (nil) —

    unused.



38
39
40
 
# File 'lib/contrast/agent/reporting/reporting_events/finding_event.rb', line 38

def code
  @code
end

#event_id ⇒ Integer (readonly)

Returns the id of this event.

Returns:

  • (Integer) —

    the id of this event.



40
41
42
 
# File 'lib/contrast/agent/reporting/reporting_events/finding_event.rb', line 40

def event_id
  @event_id
end

#event_sources ⇒ Array<Contrast::Agent::Reporting::EventSource> (readonly)

Returns the source of taint.

Returns:

  • (Array<Contrast::Agent::Reporting::EventSource>) —

    the source of taint



42
43
44
 
# File 'lib/contrast/agent/reporting/reporting_events/finding_event.rb', line 42

def event_sources
  @event_sources
end

#field_name ⇒ nil (readonly)

Returns unused.

Returns:

  • (nil) —

    unused.



48
49
50
 
# File 'lib/contrast/agent/reporting/reporting_events/finding_event.rb', line 48

def field_name
  @field_name
end

#object ⇒ Contrast::Agent::Assess::ContrastObject (readonly)

Returns the safe representation of the Object on which the method was invoked.

Returns:



55
56
57
 
# File 'lib/contrast/agent/reporting/reporting_events/finding_event.rb', line 55

def object
  @object
end

#parent_object_ids ⇒ Array<Contrast::Agent::Reporting::FindingEventParentObject> (readonly)

Returns the ids of all the events directly preceding this.

Returns:



58
59
60
 
# File 'lib/contrast/agent/reporting/reporting_events/finding_event.rb', line 58

def parent_object_ids
  @parent_object_ids
end

#policy_node ⇒ Contrast::Agent::Assess::Policy::PolicyNode (readonly)

Returns the node that governs this event.

Returns:



60
61
62
 
# File 'lib/contrast/agent/reporting/reporting_events/finding_event.rb', line 60

def policy_node
  @policy_node
end

#properties ⇒ Array<Contrast::Agent::Reporting::FindingEventProperty> (readonly)

Returns:



62
63
64
 
# File 'lib/contrast/agent/reporting/reporting_events/finding_event.rb', line 62

def properties
  @properties
end

#reportable_args ⇒ Array<Contrast::Agent::Reporting::FindingEventObject> (readonly)

Returns the arguments passed to the method.

Returns:



33
34
35
 
# File 'lib/contrast/agent/reporting/reporting_events/finding_event.rb', line 33

def reportable_args
  @reportable_args
end

#reportable_object ⇒ Contrast::Agent::Reporting::FindingEventObject (readonly)

Returns the object this method was invoked on.

Returns:



50
51
52
 
# File 'lib/contrast/agent/reporting/reporting_events/finding_event.rb', line 50

def reportable_object
  @reportable_object
end

#reportable_ret ⇒ Contrast::Agent::Reporting::FindingEventObject (readonly)

Returns the return of the method.

Returns:



64
65
66
 
# File 'lib/contrast/agent/reporting/reporting_events/finding_event.rb', line 64

def reportable_ret
  @reportable_ret
end

#reportable_tags ⇒ String (readonly)

Returns comma separated list of descriptions of what’s happened to the data.

Returns:

  • (String) —

    comma separated list of descriptions of what’s happened to the data



74
75
76
 
# File 'lib/contrast/agent/reporting/reporting_events/finding_event.rb', line 74

def reportable_tags
  @reportable_tags
end

#request ⇒ Contrast::Agent::Request? (readonly)

Returns our wrapper around the Rack::Request for this context.

Returns:



52
53
54
 
# File 'lib/contrast/agent/reporting/reporting_events/finding_event.rb', line 52

def request
  @request
end

#ret ⇒ Contrast::Agent::Assess::ContrastObject (readonly)

Returns the safe representation of the Return of the invoked method.

Returns:



66
67
68
 
# File 'lib/contrast/agent/reporting/reporting_events/finding_event.rb', line 66

def ret
  @ret
end

#signature ⇒ Contrast::Agent::Reporting::FindingEventSignature (readonly)

Returns the signature of the method.

Returns:



68
69
70
 
# File 'lib/contrast/agent/reporting/reporting_events/finding_event.rb', line 68

def signature
  @signature
end

#source ⇒ String (readonly)

Returns the source of the taint from the method; ^(O|R|Pd+)$.

Returns:

  • (String) —

    the source of the taint from the method; ^(O|R|Pd+)$



70
71
72
 
# File 'lib/contrast/agent/reporting/reporting_events/finding_event.rb', line 70

def source
  @source
end

#source_name ⇒ String? (readonly)

Returns:



46
47
48
 
# File 'lib/contrast/agent/reporting/reporting_events/finding_event.rb', line 46

def source_name
  @source_name
end

#source_type ⇒ String? (readonly)

Returns:



44
45
46
 
# File 'lib/contrast/agent/reporting/reporting_events/finding_event.rb', line 44

def source_type
  @source_type
end

#stack ⇒ Array<Contrast::Agent::Reporting::FindingEventStack> (readonly)

Returns:



72
73
74
 
# File 'lib/contrast/agent/reporting/reporting_events/finding_event.rb', line 72

def stack
  @stack
end

#stack_trace ⇒ Array<String> (readonly)

Returns the execution stack at the time the method for this event was invoked.

Returns:

  • (Array<String>) —

    the execution stack at the time the method for this event was invoked



89
90
91
 
# File 'lib/contrast/agent/reporting/reporting_events/finding_event.rb', line 89

def stack_trace
  @stack_trace
end

#tags ⇒ Hash<Contrast::Agent::Assess::Tag> (readonly)

Returns:



76
77
78
 
# File 'lib/contrast/agent/reporting/reporting_events/finding_event.rb', line 76

def tags
  @tags
end

#taint_ranges ⇒ Array<Contrast::Agent::Reporting::FindingEventTaintRange> (readonly)

Returns the tags and spans of the source that are tracked.

Returns:



79
80
81
 
# File 'lib/contrast/agent/reporting/reporting_events/finding_event.rb', line 79

def taint_ranges
  @taint_ranges
end

#target ⇒ String (readonly)

Returns the target of the taint from the method; ^(O|R|Pd+)$.

Returns:

  • (String) —

    the target of the taint from the method; ^(O|R|Pd+)$



81
82
83
 
# File 'lib/contrast/agent/reporting/reporting_events/finding_event.rb', line 81

def target
  @target
end

#thread ⇒ String (readonly)

Returns the id of the thread on which the method was invoked.

Returns:

  • (String) —

    the id of the thread on which the method was invoked



83
84
85
 
# File 'lib/contrast/agent/reporting/reporting_events/finding_event.rb', line 83

def thread
  @thread
end

#time ⇒ Integer (readonly)

Returns the time, in ms, when the event was generated.

Returns:

  • (Integer) —

    the time, in ms, when the event was generated



85
86
87
 
# File 'lib/contrast/agent/reporting/reporting_events/finding_event.rb', line 85

def time
  @time
end

#type ⇒ String (readonly)

Returns the type of event; METHOD, PROPAGATION, TAG.

Returns:

  • (String) —

    the type of event; METHOD, PROPAGATION, TAG



87
88
89
 
# File 'lib/contrast/agent/reporting/reporting_events/finding_event.rb', line 87

def type
  @type
end

Class Method Details

.from_source(source) ⇒ Array<Contrast::Agent::Reporting::FindingEvent>

Find all the events leading up to the given source and return an array of FindingEvents

Parameters:

  • source (Object) —

    something that may have been tracked

Returns:



159
160
161
162
163
 
# File 'lib/contrast/agent/reporting/reporting_events/finding_event.rb', line 159

def from_source source
  return unless source && (props = Contrast::Agent::Assess::Tracker.properties(source))

  build_events([], props.event) if props.event
end

.next_atomic_id ⇒ Object 



140
141
142
143
144
145
146
147
 
# File 'lib/contrast/agent/reporting/reporting_events/finding_event.rb', line 140

def self.next_atomic_id
  @atomic_mutex.synchronize do
    @atomic_id += 1
    # Rollover things
  rescue StandardError
    @atomic_id = 1
  end
end

Instance Method Details

#initialize_routine(event_data, source_type = nil, source_name = nil) ⇒ Object

Init routine to find parents events, capture stack trace and retrieve object, args, ret and properties.

Parameters:

  • event_data (Contrast::Agent::Assess::Events::EventData)
  • source_type (String, nil) (defaults to: nil) —

    the type of this source, from the source_node, or a KEY_TYPE if invoked for a map,

  • source_name (String, nil) (defaults to: nil) —

    the name of this source, i.e. the key used to accessed if from a map or nil if a type like,



116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
 
# File 'lib/contrast/agent/reporting/reporting_events/finding_event.rb', line 116

def initialize_routine event_data, source_type = nil, source_name = nil
  return unless event_data&.cs__is_a?(Contrast::Agent::Assess::Events::EventData)

  # Initialize source event:
  if event_data.policy_node.cs__class == Contrast::Agent::Assess::Policy::SourceNode
    build_source_event(source_type, source_name)
  end

  @policy_node = event_data.policy_node
  @tags = Contrast::Agent::Assess::Tracker.properties(event_data.tagged)&.get_tags
  find_parent_events!(event_data.policy_node, event_data.object, event_data.ret, event_data.args)
  snapshot!(event_data.object, event_data.ret, event_data.args)
  display_params!
  capture_stacktrace!
  stack!
  properties!
  # following methods must be called after snapshot!
  dataflow!
  @signature = Contrast::Agent::Reporting::FindingEventSignature.new(policy_node, args, ret)
end

#parent_events ⇒ Array<Contrast::Agent::Reporting::FindingEvent>

Returns:



150
151
152
 
# File 'lib/contrast/agent/reporting/reporting_events/finding_event.rb', line 150

def parent_events
  @_parent_events ||= []
end

#to_controlled_hash ⇒ Hash

Convert the instance variables on the class, and other information, into the identifiers required for TeamServer to process the JSON form of this message.

Returns:

Raises:

  • (ArgumentError) 


189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
 
# File 'lib/contrast/agent/reporting/reporting_events/finding_event.rb', line 189

def to_controlled_hash # rubocop:disable Metrics/AbcSize
  validate
  {
      action: action,
      args: reportable_args.map(&:to_controlled_hash),
      # code: code, # Unused by our agent
      objectId: event_id,
      eventSources: event_sources.map(&:to_controlled_hash),
      # fieldName: field_name, # Unused by our agent
      object: reportable_object.to_controlled_hash,
      parentObjectIds: parent_object_ids.map(&:to_controlled_hash),
      properties: properties.map(&:to_controlled_hash),
      ret: reportable_ret&.to_controlled_hash,
      signature: signature.to_controlled_hash,
      source: source || '',
      stack: stack.map(&:to_controlled_hash),
      tags: reportable_tags.join(','),
      taintRanges: taint_ranges.map(&:to_controlled_hash),
      target: target || '',
      thread: thread,
      time: time,
      type: type
  }
end

#validate ⇒ Object

Raises:

  • (ArgumentError) 


215
216
217
218
 
# File 'lib/contrast/agent/reporting/reporting_events/finding_event.rb', line 215

def validate
  validate_base
  validate_dataflow
end