Class: Relyze::Plugin::Base

Inherits:
Object
  • Object
show all
Defined in:
C:/Program Files/Relyze/lib/relyze/core/plugin.rb

Direct Known Subclasses

Analysis, Decoder, Loader

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(_information) ⇒ Base

Create a new Analysis plugin instance.

Parameters:

  • _information (Hash) —

    A hash describing this plugin.

Options Hash (_information):

  • :guid (String) —

    A unique GUID for this plugin. Required.

  • :name (String) —

    A name for this plugin. Required.

  • :description (String) —

    A description of this plugin. Required.

  • :authors (Array) —

    An array of authors for this plugin. Required.

  • :license (String) —

    A license description for this plugin. Required.

  • :options (Hash) —

    A hash of options for this plugin. The user may modify the values of this hash by providing a plugin command line, either in the GUI or on the system command line before running any plugins. Optional.

  • :version (String) —

    This plugins version as a string in the format major.minor. Optional, will default to '1.0'.

  • :min_app_ver (String) —

    The minimum version of Relyze this plugin may be run on.

  • :max_app_ver (String) —

    The maximum version of Relyze this plugin may be run on.

  • :require (Hash) —

    A hash describing this plugins requirements before it can be run. Define :type to restrict running the plugin against specific model types (e.g [:pe]). Define :arch to restrict running the plugin against specific architectures (e.g. [:x86]). Define :files to perform a Ruby require on a list of files before running the plugin.



37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
 
# File 'C:/Program Files/Relyze/lib/relyze/core/plugin.rb', line 37

def initialize( _information )
    @information   = _information
    @autorun_model = nil
    @relyze        = nil

    raise 'You must spedcify a plugin :guid.' if not @information[:guid] or @information[:guid].empty?
    
    raise 'You must spedcify a plugin :name.' if not @information[:name] or @information[:name].empty?
    
    raise 'You must specify a plugin :description.' if not @information[:description] or @information[:description].empty?
    
    raise 'You must specify a plugin :authors.' if not @information[:authors] or @information[:authors].empty?
    
    raise 'You must specify a plugin :license.' if not @information[:license] or @information[:license].empty?
    
    if( not @information[:options] or @information[:options].class != ::Hash )
        @information[:options] = ::Hash.new
    end
    
    if( @information[:guid] !~ /{[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}}/i )
        raise 'You must spedcify a valid plugin :guid.'
    end
    
    if( @information[:version] and /(\d{1,}).(\d{1,})/.match( self.version ) == nil )
        raise 'You must specify a valid :version, e.g. \'1.0\'.'
    end
    
    if( @information.has_key?( :min_application_version ) and not @information.has_key?( :min_app_ver ) )
        @information[:min_app_ver] = @information[:min_application_version]
    end
                    
    if( @information.has_key?( :max_application_version ) and not @information.has_key?( :max_app_ver ) )
        @information[:max_app_ver] = @information[:max_application_version]
    end
    
    if( @information[:min_app_ver] and /(\d{1,})(?:\.(\d{1,}))?(?:\.(\d{1,}))?/.match( @information[:min_app_ver] ) == nil )
        raise 'You must specify a valid :min_app_ver, e.g. \'1.0.0\'.'
    end    
    
    if( @information[:max_app_ver] and /(\d{1,})(?:\.(\d{1,}))?(?:\.(\d{1,}))?/.match( @information[:max_app_ver] ) == nil )
        raise 'You must specify a valid :max_app_ver, e.g. \'2.0.0\'.'
    end
    
    if( @information[:require] )
    
        if( @information[:require].class != ::Hash )
            raise 'You must specify a Hash for the require options'
        end
        
        if( @information[:require][:type] and @information[:require][:type].class != ::Array )
            raise 'You must specify an Array for the require :type options'
        end
        
        if( @information[:require][:arch] and @information[:require][:arch].class != ::Array )
            raise 'You must specify an Array for the require :arch options'
        end

        if( @information[:require][:files] and @information[:require][:files].class != ::Array )
            raise 'You must specify an Array for the require :files options'
        end
    end
end

Instance Attribute Details

#autorun_model ⇒ Object (readonly)

The model object this plugin is automatically being run against, if any.



19
20
21
 
# File 'C:/Program Files/Relyze/lib/relyze/core/plugin.rb', line 19

def autorun_model
  @autorun_model
end

#information ⇒ Object (readonly)

Get the plugins information hash.



16
17
18
 
# File 'C:/Program Files/Relyze/lib/relyze/core/plugin.rb', line 16

def information
  @information
end

#relyze ⇒ Object (readonly)

Gets the Application instance.



22
23
24
 
# File 'C:/Program Files/Relyze/lib/relyze/core/plugin.rb', line 22

def relyze
  @relyze
end

Instance Method Details

#abort_analysis ⇒ Object

Helper method to abort the analysis. See FileModel#abort.



265
266
267
 
# File 'C:/Program Files/Relyze/lib/relyze/core/plugin.rb', line 265

def abort_analysis
    @autorun_model.abort if not @autorun_model.nil?
end

#authors ⇒ Array<String>

Get the plugins authors.

Returns:

  • (Array<String>) —

    An array of strings, one for each author.



142
143
144
 
# File 'C:/Program Files/Relyze/lib/relyze/core/plugin.rb', line 142

def authors
    return @information[:authors]
end

#can_run?(action = nil) ⇒ Boolean

Helper method automatically called before a plugin is run. If this method return true then the plugin may run otherwise the plugin will not run.

Returns:

  • (Boolean) 


308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
 
# File 'C:/Program Files/Relyze/lib/relyze/core/plugin.rb', line 308

def can_run?( action=nil )
    return false if @relyze.nil?
    
    if( @information[:min_app_ver] )
        minv = /(\d{1,})(?:\.(\d{1,}))?(?:\.(\d{1,}))?/.match( @information[:min_app_ver] )
        
        if( minv[1] and @relyze.version_major < minv[1].to_i )
            return false
        end
        
        if( minv[1] and minv[2] and @relyze.version_major == minv[1].to_i and @relyze.version_minor < minv[2].to_i )
            return false
        end    
        
        if( minv[1] and minv[2] and minv[3] and @relyze.version_major == minv[1].to_i and @relyze.version_minor == minv[2].to_i and @relyze.version_patch < minv[3].to_i )
            return false
        end
    end
    
    if( @information[:max_app_ver] )
        maxv = /(\d{1,})(?:\.(\d{1,}))?(?:\.(\d{1,}))?/.match( @information[:max_app_ver] )
        
        if( maxv[1] and @relyze.version_major > maxv[1].to_i )
            return false
        end
        
        if( maxv[1] and maxv[2] and @relyze.version_major == maxv[1].to_i and @relyze.version_minor > maxv[2].to_i )
            return false
        end    
        
        if( maxv[1] and maxv[2] and maxv[3] and @relyze.version_major == maxv[1].to_i and @relyze.version_minor == maxv[2].to_i and @relyze.version_patch > maxv[3].to_i )
            return false
        end
    end
    
    if( @information[:require] )
    
        if( @information[:require][:type] )
            if( not current_model )
                return false
            end
            return false if not @information[:require][:type].each do | type |
                if( current_model.type == type )
                    break true
                end
            end
        end
        
        if( @information[:require][:arch] )
            if( not current_model )
                return false
            end
            return false if not @information[:require][:arch].each do | arch |
                if( current_model.arch == arch )
                    break true
                end
            end
        end
    
        if( @information[:require][:files] )
            if( not require_files( @information[:require][:files] ) )
                return false
            end                        
        end
        
    end
    
    return true
end

#current_model ⇒ Relyze::FileModel, NilClass Also known as: cm

Helper method to retrieve the current model, which is either the model object this plugin is automatically being run against or the model corresponding to the currently active tab in the application GUI.

Returns:



260
261
262
 
# File 'C:/Program Files/Relyze/lib/relyze/core/plugin.rb', line 260

def current_model
    return @autorun_model || @relyze.tab_current_model( @relyze.active_tab )
end

#description(flatten = false) ⇒ Object

Get this plugins description.



121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
 
# File 'C:/Program Files/Relyze/lib/relyze/core/plugin.rb', line 121

def description( flatten=false )
    if( not flatten )
        return @information[:description]
    end
    
    lines = @information[:description].gsub( "\r\n", "\n" ).split( "\n" )

    lines.map! do | line |
        if( not line.empty? )
            tab_count = line[/\A\t*/].size if tab_count.nil? 

            line.reverse.chomp( "\t" * (tab_count.nil? ? 0 : tab_count ) ).reverse.strip
        end
    end

    return lines.join( ' ' ).strip
end

#get_persistent_value(name, default = nil) ⇒ String, ...

Get a persistent value for this plugin, identified by a name in the application library.

Examples:

Get a persistent value

key = self.get_persistent_value( :apikey )
if( key.nil? )
    key = @relyze.input_dialog( self.name, 'Please enter your API key:' )
    self.set_persistent_value( :apikey, key )
end

Parameters:

  • name (Symbol) —

    The name of the value to set.

  • default (String, Integer, Float, TrueClass, FalseClass, NilClass) (defaults to: nil) —

    A default value to return if the persistent value identified by name is not previously set.

Returns:



240
241
242
243
 
# File 'C:/Program Files/Relyze/lib/relyze/core/plugin.rb', line 240

def get_persistent_value( name, default=nil )
    value = @relyze.get_persistent_value( self, name )
    return ( value.nil? ? default : value )
end

#guid ⇒ Object

Get this plugins unique GUID value.



111
112
113
 
# File 'C:/Program Files/Relyze/lib/relyze/core/plugin.rb', line 111

def guid
    return @information[:guid]
end

#license ⇒ Object

Get this plugins license description.



147
148
149
 
# File 'C:/Program Files/Relyze/lib/relyze/core/plugin.rb', line 147

def license
    return @information[:license]
end

#name ⇒ Object

Get this plugins name.



116
117
118
 
# File 'C:/Program Files/Relyze/lib/relyze/core/plugin.rb', line 116

def name
    return @information[:name]
end

#options ⇒ Hash

Get this plugins options hash. The options may be specified by a plugin and modified by the plugin command line passed by the user. For example passing “/foo=bar” on the plugin command line will set options = “bar”

Returns:

  • (Hash) —

    The plugin options.



180
181
182
 
# File 'C:/Program Files/Relyze/lib/relyze/core/plugin.rb', line 180

def options    
    return @information[:options] || {}
end

#origin ⇒ Symbol

Returns this plugins origin.

Returns:

  • (Symbol) —

    Returns this plugins origin.



101
102
103
 
# File 'C:/Program Files/Relyze/lib/relyze/core/plugin.rb', line 101

def origin
    return :ruby
end

#print_error(message) ⇒ Object

Print an error message to the GUI console.



207
208
209
 
# File 'C:/Program Files/Relyze/lib/relyze/core/plugin.rb', line 207

def print_error( message )
    @relyze.console_print( self, :error, message )
end

#print_exception(e) ⇒ Object

Print an exception to the GUI console.



217
218
219
220
221
222
223
224
 
# File 'C:/Program Files/Relyze/lib/relyze/core/plugin.rb', line 217

def print_exception( e )
    self.print_error( "[!] #{self.name}: #{e.to_s} (#{e.class})" )
    if( e.backtrace )
        e.backtrace.each do | line |
            self.print_error( "[!]\t" + line )
        end
    end
end

#print_message(message) ⇒ Object

Print a normal message to the GUI console.



202
203
204
 
# File 'C:/Program Files/Relyze/lib/relyze/core/plugin.rb', line 202

def print_message( message )
    @relyze.console_print( self, :normal, message )
end

#print_warning(message) ⇒ Object

Print a warning message to the GUI console.



212
213
214
 
# File 'C:/Program Files/Relyze/lib/relyze/core/plugin.rb', line 212

def print_warning( message )
    @relyze.console_print( self, :warning, message )
end

#references ⇒ Array<String>

Get this plugins external references, typically website URLs.

Returns:

  • (Array<String>) —

    An array of strings, one for each reference.



187
188
189
 
# File 'C:/Program Files/Relyze/lib/relyze/core/plugin.rb', line 187

def references
    return @information[:references] || []
end

#remove_task ⇒ Object (protected) 



380
381
382
 
# File 'C:/Program Files/Relyze/lib/relyze/core/plugin.rb', line 380

def remove_task
    return false
end

#require_files(files) ⇒ Object

Helper method to do a Ruby require for an Array of files. Not to be called directly, instead pass the required files in the plugins information during initialization.

Examples:

def initialize               
    super( {
        :guid        => '{8660CF7B-3AB3-41A4-B10A-89C6F64BFB1C}',
        :name        => 'Your Plugin Name',
        :description => 'Your Plugin Description',
        :authors     => [ 'Your Name' ],
        :license     => 'Your License',
        :references  => [ 'www.your.website' ]
        :require     => {
            :files   => [ 'date', 'digest/sha1', 'rubygems', 'json', 'rest-client' ]
        }
    } )
end


294
295
296
297
298
299
300
301
302
303
304
 
# File 'C:/Program Files/Relyze/lib/relyze/core/plugin.rb', line 294

def require_files( files )
    files.each do | file |    
        begin
            require( file )
        rescue ::LoadError
            print_error( $! )
            return false
        end
    end
    return true
end

#restart_analysis ⇒ Object

Helper method to restart the analysis. See FileModel#restart.



270
271
272
 
# File 'C:/Program Files/Relyze/lib/relyze/core/plugin.rb', line 270

def restart_analysis
    @autorun_model.restart if not @autorun_model.nil?
end

#set_persistent_value(name, value) ⇒ TrueClass, FalseClass

Set a persistent value identified by a name for this plugin in the application library. This value survives application restarts.

Parameters:

Returns:

  • (TrueClass, FalseClass) —

    Returns true if the value was set or false if the value was not set.



251
252
253
 
# File 'C:/Program Files/Relyze/lib/relyze/core/plugin.rb', line 251

def set_persistent_value( name, value )
    return @relyze.set_persistent_value( self, name, value )
end

#task_status(status, amount = nil) ⇒ Object

Update this plugins status with the task manager. Every plugin instance will appear in the GUI Task Manager. To update the tasks progress bar you can call task_status( :progress, amount )

Parameters:

  • status (Symbol) —

    Either :progress or :finished

  • amount (Integer, nil) (defaults to: nil) —

    If status is :progress, then amount can be between 0 and 100.



197
198
199
 
# File 'C:/Program Files/Relyze/lib/relyze/core/plugin.rb', line 197

def task_status( status, amount=nil )
    return false
end

#type ⇒ Object

Get the plugin type, either :analysis or :decoder



106
107
108
 
# File 'C:/Program Files/Relyze/lib/relyze/core/plugin.rb', line 106

def type
    return nil
end

#version ⇒ String

Get this plugins version as a string in the format major.minor.

Returns:

  • (String) —

    The version string, e.g. “1.0”



154
155
156
157
158
159
 
# File 'C:/Program Files/Relyze/lib/relyze/core/plugin.rb', line 154

def version
    if @information[:version]
        return @information[:version].to_s
    end
    return '1.0'
end

#version_major ⇒ Integer

Get this plugins major version number.

Returns:

  • (Integer) —

    The major version number.



164
165
166
 
# File 'C:/Program Files/Relyze/lib/relyze/core/plugin.rb', line 164

def version_major
    return /(\d{1,}).(\d{1,})/.match( self.version )[1].to_i
end

#version_minor ⇒ Integer

Get this plugins minor version number.

Returns:

  • (Integer) —

    The minor version number.



171
172
173
 
# File 'C:/Program Files/Relyze/lib/relyze/core/plugin.rb', line 171

def version_minor
    return /(\d{1,}).(\d{1,})/.match( self.version )[2].to_i
end
id="footer"> Generated on Tue Aug 9 11:51:57 2022 by yard 0.9.20 (ruby-2.6.5).