Class: Relyze::Symbols::StaticLibraryPackage

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

Defined Under Namespace

Modules: TSortPackageArray

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initializeStaticLibraryPackage

Returns a new instance of StaticLibraryPackage



91
92
93
94
95
96
97
98
99
100
101
102
# File 'C:/Program Files/Relyze/lib/relyze/core/symbols.rb', line 91

def initialize
    @name     = ''
    @version  = '0.0.0'
    @origin   = nil
    @type     = nil
    @platform = nil
    @mode     = nil
    @arch     = nil
    @children = []
    @enabled  = true
    @count    = 0
end

Instance Attribute Details

#archObject (readonly)

Symbol

This packages architecture, :x86, x64, :arm or :arm64.



80
81
82
# File 'C:/Program Files/Relyze/lib/relyze/core/symbols.rb', line 80

def arch
  @arch
end

#childrenObject (readonly)

Array<Relyze::Symbols::StaticLibraryPackage>

An array of child packages belonging to this package.



83
84
85
# File 'C:/Program Files/Relyze/lib/relyze/core/symbols.rb', line 83

def children
  @children
end

#countObject (readonly)

Integer

The total number of signatures in this package not including any signatures in the child packages, unless this package contains shared child packages, in which case those shared signatures will be included in this count value.



89
90
91
# File 'C:/Program Files/Relyze/lib/relyze/core/symbols.rb', line 89

def count
  @count
end

#enabledObject

true,false

Set to false in order to permanently disable this package, preventing it from being automatically used during static library analysis.



86
87
88
# File 'C:/Program Files/Relyze/lib/relyze/core/symbols.rb', line 86

def enabled
  @enabled
end

#modeObject (readonly)

Symbol

This packages mode, :user or :kernel.



77
78
79
# File 'C:/Program Files/Relyze/lib/relyze/core/symbols.rb', line 77

def mode
  @mode
end

#nameObject (readonly)

String

This packages name.



62
63
64
# File 'C:/Program Files/Relyze/lib/relyze/core/symbols.rb', line 62

def name
  @name
end

#originObject (readonly)

Symbol

The origin of this packages symbols data base, :application, :user or :memory. By default the :application origin is “%ALLUSERSPROFILE%Relyzesymbols.db” and the :user origin is “%USERPROFILE%DocumentsRelyzeSymbolssymbols.db”. The :memory origin is an in memory database that will not persist past an application restart.



68
69
70
# File 'C:/Program Files/Relyze/lib/relyze/core/symbols.rb', line 68

def origin
  @origin
end

#platformObject (readonly)

Symbol

This packages platform, :windows.



74
75
76
# File 'C:/Program Files/Relyze/lib/relyze/core/symbols.rb', line 74

def platform
  @platform
end

#typeObject (readonly)

Symbol

This packages type, either :shared, :general or :automatic. :shared packages are used to share signatures between several other packages. A package that has a shared child package will apply those signatures in an opaque manner as if the shared signatures belonged to the parent package. :general packages are typically child packages, often having multiple parents, which are applied if the parent package is successfully applied. All :automatic packages are grouped into a set of packages, queried and the most applicable package is then applied during static library analysis.



71
72
73
# File 'C:/Program Files/Relyze/lib/relyze/core/symbols.rb', line 71

def type
  @type
end

#versionObject (readonly)

String

The version of Relyze that generated this package.



65
66
67
# File 'C:/Program Files/Relyze/lib/relyze/core/symbols.rb', line 65

def version
  @version
end

Class Method Details

.create(package_options, origin = :user, parallel = true) ⇒ Relyze::Symbols::StaticLibraryPackage?

Static method to create a new package of static library signatures from a series of input files.

Examples:

Creating a package of static library signatures.

packages = [
    {
        :name       => "CompilerX Runtime",
        :type       => :automatic,
        :platform   => :windows,
        :mode       => :user,
        :arch       => :x86,
        :files      => [
            "C:\\CompilerX\\Lib\\x86\\crt.lib",
            "C:\\CompilerX\\Lib\\x86\\foo.obj"
        ]
    },
]

packages.each do | package_options |
    package = Relyze::Symbols::StaticLibraryPackage.create( package_options )
    print_message( "Created package '%s' with %d signatures." % [ package.name, package.count ] ) if not package.nil?
end

Parameters:

  • package_options (Hash)

    The package options describing the package to create.

  • origin (Symbol) (defaults to: :user)

    The origin for this package is the symbols database where it is stored, :user or :memory. By default the :user DB origin is “%USERPROFILE%DocumentsRelyzeSymbolssymbols.db”. The :memory origin is an in memory database that will not persist past an application restart.

  • parallel (true, false) (defaults to: true)

    Use parallel processing while generating the package.

Options Hash (package_options):

  • :name (String)

    The name of this package.

  • :type (Symbol)

    The type of this package, :shared, :general or :automatic.

  • :platform (Symbol)

    The platform for this package, :windows.

  • :mode (Symbol)

    The mode for this package, :user or :kernel.

  • :arch (Symbol)

    The architecture for this package, :x86, x64, :arm or :arm64.

  • :pch_file (String, nil)

    The PCH file name to use when attempting to load types for this symbol.

  • :files (Array<String>)

    An array of files to process and generate signatures for this package (e.g. .lib and .obj files)

  • :children (Array<Relyze::Symbols::StaticLibraryPackage,String>)

    The children of this new package as an array of either package objects or package name strings. All child packages must reside in the same origin as the parent package.

Returns:



138
139
140
# File 'C:/Program Files/Relyze/lib/relyze/core/symbols.rb', line 138

def self.create( package_options, origin=:user, parallel=true )
    return nil
end

.create_packages(packages, origin = :user, parallel = true, plugin = nil) ⇒ true, false

Static helper method to create a series of packages.

Examples:

Create two packages, let create_packages() handle the package dependency order and gather files from a path.


packages = [
    {
        :name       => "CompilerX Runtime",
        :type       => :automatic,
        :platform   => :windows,
        :mode       => :user,
        :arch       => :x86,
        :files      => [
            "C:\\CompilerX\\Lib\\x86\\crt.lib",
            "C:\\CompilerX\\Lib\\x86\\foo.obj"
        ],
        :children   => [ "CompilerX Common" ]
    },
    {
        :name       => "CompilerX Common",
        :type       => :general,
        :platform   => :windows,
        :mode       => :user,
        :arch       => :x86,
        :paths      => [
            "C:\\CompilerX\\Lib\\x86\\shared\\",
        ],
        :extensions => [ "lib", "obj" ],
        :subdirs    => true
    }
] 

::Relyze::Symbols::StaticLibraryPackage.create_packages( packages, :user )

Parameters:

  • packages (Array<Hash>)

    An array of package_options Hash objects describing each package to create.

  • origin (Symbol) (defaults to: :user)

    The origin for this package is the symbols database where it is stored, :user or :memory. By default the :user DB origin is “%USERPROFILE%DocumentsRelyzeSymbolssymbols.db”. The :memory origin is an in memory database that will not persist past an application restart.

  • parallel (true, false) (defaults to: true)

    Use parallel processing while generating the package.

  • plugin (Relyze::Plugin::Base, nil) (defaults to: nil)

    An optional plugin instance to use for printing package creation status or errors.

Returns:

  • (true, false)


180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
# File 'C:/Program Files/Relyze/lib/relyze/core/symbols.rb', line 180

def self.create_packages( packages, origin=:user, parallel=true, plugin=nil )

    # Reorder the packages based on their dependencies, as we must create child packages before the parent packages.
    begin
        packages.extend( Relyze::Symbols::StaticLibraryPackage::TSortPackageArray.init )
        packages = packages.tsort()
    rescue
        plugin.print_error( "[-] Failed to sort the package dependencies. #{$!}" ) if plugin
        return false
    end

    # If :path and :extensions keys are set, gather the files located at this path.
    packages.each do | package_options |
    
        package_options[:files] = [] if package_options[:files].nil?
        
        package_options[:children] = [] if package_options[:children].nil?
        
        if( not package_options[:paths].nil? and not package_options[:extensions].nil? )
            package_options[:subdirs] = false if package_options[:subdirs].nil?
            package_options[:paths].each do | path |
                package_options[:extensions].each do | extension |
                    ::Dir.glob( "#{path}#{package_options[:subdirs] ? '**/' : ''}*.#{extension}" ).each do | file |
                        package_options[:files] << file
                    end
                end
            end
        end

        package_options[:files].each do | file |
            if( not ::File.exists?( file ) )
                plugin.print_error( "[-] File '#{file}' does not exist for package '#{package_options[:name]}'." ) if plugin
                return false
            end
        end
        
        # Only fail if package_options has no files *and* no children, we can have packages with no files but
        # which has shared children with another package_options.
        if( package_options[:files].empty? and package_options[:children].empty? )
            plugin.print_error( "[!] package '#{package_options[:name]}' has no files and no children." ) if plugin
            return false
        end
    end
    
    packages.each do | package_options |

        package_object = Relyze::Symbols::StaticLibraryPackage.create( package_options, origin, parallel )
        
        if( package_object.nil? )
            plugin.print_error( "[!] Failed to create package '#{package_options[:name]}'." ) if plugin
            return false
        end
        
        plugin.print_message( "[+] Created package '%s' with %d signatures." % [ package_object.name, package_object.count ] ) if plugin
    end

    return true
end

Instance Method Details

#applicable?(target) ⇒ true, false

Test if this package is applicable to a given model or package. An applicable package will have a matching platform, mode and architecture to the target.

Parameters:

Returns:

  • (true, false)


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

def applicable?( target )
    return false
end

#apply(model, functions = nil) ⇒ Number

Apply the static library signatures from this package and any child packages to a model.

Examples:

Apply the most similar package against the first 32 functions of the current model.

functions = cm.functions.sort_by do | func |
    func.rva
end
functions       = functions[0,[32,functions.length].min]
best_similarity = 0.0
best_package    = nil
@relyze.static_library_packages.each do | package |
    next if not package.applicable?( cm )
    next if package.type != :automatic
    similarity = package.query( cm, functions )
    print_message( "Package '%s' has a similarity of %2.2f%%." % [ package.name, similarity * 100 ] )
    if( similarity > best_similarity )
        best_package    = package
        best_similarity = similarity
    end
end
if( not best_package.nil? )
    print_message( "Applied %d signatures from package '%s' against %d functions." % [ best_package.apply( cm, functions ), best_package.name, functions.length ] )
end

Parameters:

Returns:

  • (Number)

    This number of signatures that were successfully applied.



304
305
306
# File 'C:/Program Files/Relyze/lib/relyze/core/symbols.rb', line 304

def apply( model, functions=nil )
    return 0
end

#delete!true, false

Permanently delete this package and all its corresponding signatures from the symbols database where it is stored. Packages whose @origin is :application may not be deleted.

Returns:

  • (true, false)


311
312
313
# File 'C:/Program Files/Relyze/lib/relyze/core/symbols.rb', line 311

def delete!
    return false
end

#enabled?Boolean

Test if this package is enabled or not. Disabled packages are not automatically used during static library analysis.

true,false

Returns:

  • (Boolean)


257
258
259
# File 'C:/Program Files/Relyze/lib/relyze/core/symbols.rb', line 257

def enabled?
    return @enabled
end

#query(model, functions = nil) ⇒ Number

Query the similarity of this package against a model.

Examples:

@relyze.static_library_packages.each do | package |
    if( package.applicable?( cm ) )
        similarity = package.query( cm )
        print_message( "Package '%s' has a similarity of %2.2f%%" % [ package.name, similarity * 100.0 ] )
    end
end

Parameters:

Returns:

  • (Number)

    The similarity amount in the range of 0.0 to 1.0.



274
275
276
# File 'C:/Program Files/Relyze/lib/relyze/core/symbols.rb', line 274

def query( model, functions=nil )
    return 0.0
end

#to_sString

Get a simple description of this package.

Returns:

  • (String)

    This packages description.



242
243
244
# File 'C:/Program Files/Relyze/lib/relyze/core/symbols.rb', line 242

def to_s
	return "Package '%s' (%s, %s, %s, %s)" % [ self.name, self.platform, self.mode, self.arch, self.type ]
end
p://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard 0.9.20 (ruby-2.6.5).